PowerScroll

Append a markdown block to the bottom of a page. This is the main way to write content. The markdown is rendered live in the app: use "- " for bullets, "1. " for numbered lists, "- [ ] " for checkboxes (which the user can then click to tick), "#"/"##" for headings, **bold**, `code`, tables, and $math$. Prefer one block per logical chunk (one list, one paragraph) rather than one block per line.

Who else is working in this notebook. Several agents may be connected at once but only one may operate at a time, so call this when a tool comes back LOCKED, or before starting a long piece of work. Reports the connected notebook, every connected agent, which one holds the notebook, how long until it frees up, and whether that is you. This tool is never blocked. Note that a free result can go stale immediately -- another agent may take the lock before your next call -- so treat the LOCKED error as the real signal and this as a way to understand it.

Check whether a newer PowerScroll release exists on GitHub. Reports the running version and the latest one. Note "checked": when false the API was unreachable or rate limited and the status is unknown — that is not the same as up to date.

DEPRECATED - use create_diagram_plantuml, create_diagram_mermaid, create_diagram_svg or create_diagram_drawio instead, which name the language they take and each document their own subset. This name still works and sniffs the format from the source, but it will be removed. Behaviour is otherwise identical.

Draw a draw.io / mxGraph diagram onto the page. BY DEFAULT (v0.64+) the source is rendered by the embedded draw.io viewer into an exact vector snapshot — colours, gradients, curved edges, double-headed arrows, HTML labels, shadows and every built-in shape render exactly as diagrams.net shows them. The response then carries renderMode 'snapshot' and elementCount 0: a snapshot diagram has NO member nodes BY DESIGN — the stored XML remains the editable source, read_diagram returns it, and "Export as .drawio" emits it verbatim. Library stencil ICONS (mxgraph.aws4/mscae/cisco) are the one gap: they render as their styled box + label, since stencil packs are not bundled. If the viewer extension is unavailable (e.g. offline before it was installed), the tool FALLS BACK to transpiling the source into native PowerScroll shapes and says so in warnings. Pass render:'nodes' to force that transpile path deliberately, when you WANT individually-selectable member nodes instead of exact paint. Everything below documents the transpiled subset — it applies to render:'nodes' and to the fallback, NOT to snapshots. THIS TOOL IS A SIBLING OF create_diagram_svg: YOU have already done the layout and the coordinates are the payload. Use create_diagram_plantuml or create_diagram_mermaid when you want a diagram laid out well without doing the geometry yourself. Supported vertices: default and rounded rectangles, ellipses, rhombi (as a 45° rect fitted to the cell), triangles, labels, standalone text cells, and flattened groups / containers / swimlanes. Paint via fillColor, strokeColor, strokeWidth, dashed=1 and dashPattern. rotation on a rectangle is honoured. Supported vertices also include UML module/component (rectangle with two left tabs), ports (small rectangles, including relative geometry + mxPoint offset so they sit on the parent edge), and box-like mxgraph.uml / mxgraph.basic library shapes (drawn as rectangles; an ignored diagnostic names the original stencil). Supported edges: a st…

Draw a diagram on the page from MERMAID source. (For PlantUML source, use create_diagram_plantuml instead.) A DOCUMENTED SUBSET is read, and anything outside it comes back as a diagnostic instead of being drawn wrong. (1) FLOWCHART: "flowchart TD" / "flowchart LR" / "graph LR" as the first line, then nodes A[Label], A(Label) and A{Label}, and edges A --> B, A -->|guard| B and A --- B. Chains such as A --> B --> C work. (2) SEQUENCE: "sequenceDiagram" as the first line, then participant X (optionally "participant X as Label") and messages A->>B: text and A-->>B: reply. TWO THINGS TO EXPECT. Node SHAPE is carried as a stereotype above the name, not as geometry: a {decision} renders as a box labelled "decision" rather than as a diamond, because the shared layout has one box shape. LAYOUT is left to right whatever direction the header names, and a sequence renders as participants side by side with numbered messages between them, not as lifelines running down the page. NOT SUPPORTED, and refused with a diagnostic: subgraphs, dotted (-.->), thick (==>) and circle/cross (--o, --x) links, compound node shapes such as A[[Sub]] or A((Circle)), loop/alt/opt/par/note blocks, and the class, state, ER and Gantt families. What lands on the canvas is ordinary PowerScroll shapes and text inside a diagram frame, so the user can drag any part of it afterwards - this is NOT an image. Supply semantics only; every coordinate is computed here from real text metrics. The response carries the diagnostics, so one call is enough to know whether it came out right.

Draw a UML diagram on the page from PLANTUML source. (For Mermaid source, use create_diagram_mermaid instead - this tool refuses it rather than half-drawing it.) Two PlantUML dialects are supported, and the right one is detected automatically. (1) COMPONENT / COMPOSITE STRUCTURE: components, nested components, ports (port / portin / portout), provided and required interfaces, and assembly and delegation connectors. A composite-structure part puts its role in the label, as component "role : Type [multiplicity]" as alias. Nesting uses braces. (2) ACTIVITY / SWIMLANE FLOWCHARTS: |Lane| switches the swimlane, start and stop are the pseudostates, :action; is a step, and if (cond) then (label) / else (label) / endif adds a decision with guards on the arrows. Steps run top to bottom in source order and the lane fixes the column. What lands on the canvas is ordinary PowerScroll shapes and text inside a diagram frame, so the user can drag any part of it afterwards - this is NOT an image. Supply semantics only: name the steps or entities and what connects to what. Every coordinate is computed here from real text metrics, and there is no way to position anything yourself. Do NOT include skinparam, !include, !theme or any styling - PowerScroll supplies the style and those lines come back as skipped diagnostics. fork, split, while and repeat are refused rather than drawn wrong, and activity branches currently render in source order rather than as parallel paths that rejoin. The response carries the diagnostics, so one call is enough to know whether it came out right.

Draw an SVG onto the page as native PowerScroll shapes. Every element becomes an ordinary rectangle, circle, line or text run that the user can select and drag afterwards -- it is transpiled, NOT embedded as an image. THIS TOOL IS THE OPPOSITE OF THE OTHER TWO: create_diagram_plantuml and create_diagram_mermaid want semantics and compute every coordinate for you, whereas here YOU have already done the layout and the coordinates are the payload. Use this when you want exact placement, and one of the others when you want a diagram laid out well without doing the geometry yourself. Supported: svg (viewBox and width/height set a uniform scale), g with translate and uniform scale, rect (incl. rx), circle, ellipse, line, polyline, polygon, and text with tspan and text-anchor. Paint via fill, stroke, stroke-width, stroke-dasharray and font-*, read from attributes or a style attribute and inherited down the tree. REFUSED, each with a diagnostic naming it: path (a bezier has no native node, and flattening it to line segments is a lie that survives every later edit), gradients, patterns, filters, masks, clipPath, use, symbol, image, foreignObject, textPath, style, script, animation and nested svg. rotate() transforms are refused too, because the native rotation turns about an element's own corner rather than the user-space origin, so honouring it would move your drawing. Keep to the supported subset and nothing is silently lost. The response carries the diagnostics, so one call tells you what was dropped.

Create a new page and open it. By default also writes the title onto the canvas as an H1 block so the page reads as a titled note.

Create a new named scroll on a page — a fresh vertical column to the right of the existing ones, with its title shown at the top on the canvas. Use this to keep a separate workstream (say "Open questions" beside "Research log") from interleaving with what is already there. Returns a scrollId to pass to append_block.

Create a new section (a tab in the notebook sidebar). Sections contain pages. A first empty page is created along with it.

Delete a single markdown block by id. Use read_page first to get block ids and check you are removing the right one. Passed a diagram FRAME id, this cascades to the frame's members and grouped strokes — same primitive as delete_diagram, which names the act and reports the counts. Passed a diagram MEMBER id (a node whose groupId is owned by a diagram frame), the call is refused (UNSUPPORTED) naming the owning diagram and pointing at delete_diagram or the redraw path.

Delete a diagram frame and everything that belongs to it: every node whose groupId is the frame id, and every stroke grouped with it. Use this when you placed a diagram you no longer want — delete_block on the frame id does the same cascade, but this tool names the act and reports how many members and strokes went. Occupants below the frame in the same scroll close the gap. An unknown id is NOT_FOUND. Passing a non-diagram node id is refused (the message names the type and points at delete_block). The bridge has no undo, so pass confirm:true once the user has agreed. Returns deletedMembers and deletedStrokes.

Delete a page and everything on it. Cannot be undone from here — the app has no agent-facing undo — so ask the user before calling, then pass confirm:true. Refuses when the page is the last one in its section.

Delete a named scroll (a column band). When the band holds ANY content — nodes, group members, or ink — content is REQUIRED: "delete" removes them with the band, "keep" closes the gap and leaves them where they are. There is deliberately no default. The old default was keep (confirm:true used to be a safe trim); a default flip would silently destroy callers that never passed the flag. An empty band needs no content param. Membership is group-aware: a diagram belongs to the band of its frame origin, and its members and grouped ink follow that verdict. A page must keep at least one scroll: a plain page is one untitled scroll — untitle it instead of deleting the last one.

Delete a section AND every page inside it. This is the widest-reaching delete available — confirm the page list with the user first (list_pages shows what would go). Refuses when it is the notebook's only section.

Refit an existing diagram to the scroll band its frame sits in. Unlike placement-time fit (shrink-only), this scales BOTH directions: up to fill band-width minus padding when the diagram is under-width, down with the same 0.45 floor when over. Works on member diagrams (members rescale) and on renderMode 'snapshot' diagrams (the frame rescales; the image follows). Out-of-band frames are refused (PRECONDITION, naming the diagram). Discover ids from read_page diagrams[]. One undo in the app.

Read the canvas look a page is actually drawn with: which guide style is active and which background colour. A page may override the notebook default, so the reply also carries "source" (whether each value came from the page or the notebook) and "notebookDefault". Call before set_background when you intend to restore the previous look afterwards.

Re-fetch a single markdown block by id (BlockSummary plus page location). Use this after read_page hits the size cap. A block larger than the 20000-character budget is returned in slices: the response carries markdownTruncated {fullLength, notice} and nextOffset — pass nextOffset back as offset to continue. Any block, any size, is fully readable in bounded calls. Unknown or non-block ids are NOT_FOUND.

Insert a markdown block into a scroll at a chosen position, shifting every occupant below it (text, diagram frames, images, shapes, ungrouped ink) down by the new block's height + 12px. Frame members ride the frame. Prefer after (a block or diagram-frame id): ids survive reordering, indices do not. Exactly one of after or index. index 0 is the top of the column (ceiling-clamped when a titled scroll arms the page ceiling). index counts packed occupants of the scroll, not read_page blocks[] — prefer after. Returns the new block plus displacedCount.

Insert an image into a scroll at a chosen position, shifting every occupant below it (text, diagram frames, images, shapes, ungrouped ink) down by the image's display height + 12px. Frame members ride the frame. Source is exactly one of data (a data:image/...;base64, URI) or path (a local png/jpg/jpeg/gif/webp file this server reads and encodes — the app never sees paths). Both or neither is an error. Placement matches insert_block: prefer after (an occupant id); exactly one of after or index. index 0 is the column top (ceiling-clamped when a titled scroll arms the page ceiling). Optional alt (defaults to "image") and mini (land as a 160px-wide thumbnail). Oversized images are downscaled to a 2048px long edge like UI imports. Returns id + display and natural dims + displacedCount — never the base64 payload. One undo.

List every section and page in the connected notebook, with the number of text blocks on each and which page is currently open. Call this first to discover page ids.

List the scrolls (named vertical columns) on a page, with how many blocks each holds. Call this before writing when a page may have more than one workstream on it: passing the returned scrollId to append_block keeps your blocks in their own column instead of stacking under someone else's. A block belongs to whichever scroll it physically sits in, so a block the user drags to another scroll moves with it.

Move a markdown block or diagram frame inside a scroll or across scrolls on the same page. Occupants below the source close up; occupants at the target open a gap. Diagram members ride the frame. ONE undo. Prefer after (a block or diagram-frame id) over index: ids survive reordering. scrollId is optional and defaults to the block's current scroll; when given it must be on the same page. Exactly one of after or index. Diagram members, shapes and images as the move target are refused by name. Returns the block plus displacedCount.

Move a page into a different section. Section ids come from list_pages. A section must keep at least one page, so moving the only page out of a section is refused — create another page there first.

Move a scroll (named column band) left or right, or to an absolute column. Members, grouped ink and the band's own width travel with it; neighbouring scrolls shift to make room and cumulative offsets are recomputed. A diagram belongs to the band of its frame origin — the whole group moves, it is never split. Refuses with NOT_FOUND on an unknown id and PRECONDITION when the scroll is already at the named edge.

Read one diagram: id, title, format, source, bounds, memberCount, and a page of members [{id, type, x, y, w, h, label?}]. member_limit + member_cursor page members (cursor = last member id; same style as read_page). Default member_limit is derived from the 20000-character budget so a typical page sits well under it. If the serialized response still exceeds the budget, members trim at an entry boundary (truncated {at, notice}). Source counts toward the budget; if source alone blows it, source is cut (sourceTruncated {fullLength, notice}) and the notice names the full length and suggests exporting as .drawio. Discover ids from read_page diagrams[]. An unknown id is NOT_FOUND. A non-diagram id is UNSUPPORTED naming the type. A draw.io diagram rendered as an exact snapshot (renderMode 'snapshot', v0.64+) returns members: [] and memberCount 0 BY DESIGN — its structure lives entirely in the source XML, which is what you read and edit.

Export one image by node id so you can look at it. Discovers ids from read_page images[].id. The notebook returns the embedded bytes over the bridge; this server decodes them and writes a local file. Optional out_path (absolute) names the destination — parent dirs are created; an existing file is overwritten. When omitted, the file lands in os.tmpdir()/powerscroll-images/<id>.<ext>. The response is {path, format, bytes, naturalWidth, naturalHeight, alt} — NEVER the base64 payload. Unknown id is NOT_FOUND. A non-image id is UNSUPPORTED naming the type. Then open the file with your vision tools.

Read a page. DEFAULT CHANGED in v0.54: blocks[] is free-standing markdown only — diagram labels (text nodes with a groupId) no longer leak in as fake content, and diagrams are collapsed to diagrams[] {id, title, format, memberCount, bounds} with NO members and NO source. Images are a compact images[] index {id, alt, x, y, w, h, naturalWidth, naturalHeight, bytes, mini, scrollId} — never the base64 payload. Discovery flow: read_page → diagrams[].id → read_diagram / delete_diagram / fit_diagram; read_page → images[].id → read_image (writes a local file you open with vision). include defaults to ["blocks","diagrams","images"]; pass ["images"] for an images-only fetch or ["diagrams"] for diagrams-only. Optional scrollId filters all three lists. limit + cursor page blocks in column-major reading order (cursor = last block id from the previous page; stable across appends). Serialized reads are hard-capped at 20000 characters and never fail for size: blocks drop first (truncated {at, notice}), then per-diagram source is replaced with sourceOmitted {length, notice: "use read_diagram"}, then diagrams[] trims at an entry boundary, then images[] trims (imagesTruncated {at, notice}). A single oversized block has its markdown cut (markdownTruncated {fullLength, notice}). include_diagram_source:true adds source on each diagrams[] entry. Use get_block(blockId) to re-fetch one block after a cap.

Rename the notebook itself (the title shown in the app and used for future Save As filenames). This does NOT rename the .html file already on disk — that keeps its current name until the user saves to a new location. The result reports the bound filename so you can tell them.

Retitle a page in the sidebar. If the page still opens with the "# Old title" heading block that create_page wrote, that block is retitled too so the two do not drift apart; a hand-edited heading is left alone.

Rename a scroll. The new title appears immediately at the top of that column on the canvas. Naming a previously untitled scroll is how its header first appears. Pass an empty title to untitle it: the header disappears and the page ceiling disarms — a plain page is one untitled scroll, not zero scrolls.

Resize a scroll band by stable id. The width is clamped to PowerScroll's shared limits, persists on that page, and every node or stroke in bands to the right moves by the same delta. The resized band's own content stays fixed. One undo restores width and positions. list_scrolls reports the effective width.

Install the latest PowerScroll release into the current notebook file. This rewrites the .html on disk and reloads the app, which drops this bridge connection until the notebook reconnects. Ask the user before calling it, then pass confirm:true. A safety backup is downloaded first where the browser allows it. Run check_update first.

Write the notebook back to the file it was opened from. Only works when the notebook is already bound to a file: the Save As picker needs a click from the user, which an agent cannot supply. Call this after a batch of edits so the work is on disk.

Change the notebook's canvas look. "scroll" renders each column as one continuous vertical sheet with light page separators — best for long reading and for notes an agent is filling in. "pages" shows detached A4 cards, "grid" a dot grid, "none" a blank canvas. The setting is stored in the notebook itself, so it survives closing and reopening. Pass at least one of guideStyle or color. Scope defaults to "notebook" (every page that has not overridden it). Pass scope:"page" to change one page only — useful when a notebook wants a scrolling page of notes next to a grid page of diagrams.

Replace the markdown of an existing block, found via read_page. Use this to revise content or tick a checkbox ("- [ ]" to "- [x]") rather than appending a duplicate block. If the block grows or shrinks, every occupant below it in the scroll (text, diagram frames, images, shapes, ungrouped ink) shifts by the height delta; frame members ride the frame. One undo. Returns displacedCount. A diagram-member id is refused (UNSUPPORTED) naming the owning diagram — redraw the source instead.