pmx-canvas 0.7.1 → 0.7.3

package/src/server/board-export.ts

@@ -11,8 +11,9 @@
  */
 import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { Marked, type RendererThis, type Tokens } from 'marked';
+import { Marked, Renderer, type RendererThis, type Tokens } from 'marked';
 import { canvasThemeScheme } from '../shared/themes.js';
+import { delimiterForPath, parseDelimitedText } from '../shared/delimited-text.js';
 import { buildJsonRenderViewerHtml, escapeInlineScriptSource, readJsonRenderBundle } from '../json-render/server.js';
 import type { JsonRenderSpec } from '../json-render/server.js';
 import { getCanvasNodeTitle } from './canvas-serialization.js';
@@ -89,6 +90,9 @@ function createMarkdown(remoteImages: Set<string>, links: Set<string>): Marked {
       html({ text: raw }: Tokens.HTML | Tokens.Tag) {
         return escapeHtml(raw);
       },
+      table(this: RendererThis, token: Tokens.Table) {
+        return tableScroll(Renderer.prototype.table.call(this, token));
+      },
       link(this: RendererThis, { href, tokens }: Tokens.Link) {
         const inner = this.parser.parseInline(tokens);
         if (/^https?:/i.test(href)) links.add(href);
@@ -136,6 +140,24 @@ function pre(value: string, className = ''): string {
   return `<pre class="${className}">${escapeHtml(value)}</pre>`;
 }
 
+function tableScroll(html: string): string {
+  return `<div class="table-scroll" role="region" aria-label="Table" tabindex="0">${html}</div>`;
+}
+
+function fileBody(value: string, name: string): string {
+  const delimiter = delimiterForPath(name);
+  if (delimiter) {
+    const table = parseDelimitedText(value, delimiter);
+    if (table.header.length > 1) {
+      // Match the workbench's bounded table preview without losing the remainder.
+      const preview = table.rows.slice(0, 500);
+      const html = `<table><thead><tr>${table.header.map((cell) => `<th scope="col">${escapeHtml(cell)}</th>`).join('')}</tr></thead><tbody>${preview.map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(cell)}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
+      return `${tableScroll(html)}${table.rows.length > preview.length ? `<details><summary>Showing 500 of ${table.rows.length} rows — full text</summary>${pre(value, 'code')}</details>` : ''}`;
+    }
+  }
+  return pre(value, 'code');
+}
+
 function rows(entries: Array<[string, unknown]>): string {
   const cells = entries
     .filter(([, value]) => value !== undefined && value !== null && value !== '')
@@ -258,20 +280,27 @@ async function collect(
         break;
       case 'status':
         card.html = rows([
-          ['Phase', data.phase],
+          ['Phase', text(data.phase).trim() || text(data.content).trim() || text(data.status).trim() || 'idle'],
           ['Message', data.message],
           ['Detail', data.detail],
+          ['Active tool', data.activeTool],
         ]);
         break;
       case 'context': {
         const items = Array.isArray(data.cards) ? (data.cards as Array<Record<string, unknown>>) : [];
-        card.html = `<ul class="list">${items
-          .map((item) => `<li><strong>${escapeHtml(text(item.title))}</strong> ${escapeHtml(text(item.summary))}</li>`)
-          .join('')}</ul>`;
+        card.html = `${rows([
+          ['Tokens', data.currentTokens],
+          ['Token limit', data.tokenLimit],
+          ['Messages', data.messagesLength],
+        ])}${
+          items.length
+            ? `<ul class="list">${items.map((item) => `<li><strong>${escapeHtml(text(item.title) || text(item.label))}</strong><p>${escapeHtml(text(item.summary))}</p></li>`).join('')}</ul>`
+            : `<p class="prose">${escapeHtml(text(data.content) || text(data.rendered).replace(/<[^>]+>/g, ' '))}</p>`
+        }`;
         break;
       }
       case 'ledger':
-        card.html = `${text(data.content) ? pre(text(data.content)) : ''}${rows(
+        card.html = `${text(data.content) ? pre(text(data.content).replaceAll('\\n', '\n')) : ''}${rows(
           Object.entries(data).filter(
             ([key]) => !['title', 'content', '__type', 'strictSize', 'arrangeLocked'].includes(key),
           ),
@@ -279,10 +308,11 @@ async function collect(
         break;
       case 'trace':
         card.html = rows([
-          ['Tool', data.toolName],
-          ['Status', data.status],
+          ['Tool', text(data.toolName) || title],
+          ['Status', text(data.status) || 'running'],
           ['Duration', data.duration],
-          ['Result', data.resultSummary],
+          ['Result', text(data.resultSummary) || text(data.content)],
+          ['Error', data.error],
         ]);
         break;
       case 'diff':
@@ -301,7 +331,7 @@ async function collect(
           .join('\n')}</pre>`;
         break;
       case 'prompt':
-        card.html = pre(text(data.text));
+        card.html = `<div class="prose">${escapeHtml(text(data.text))}</div>`;
         break;
       case 'response':
         card.html = `<div class="md">${await markdown.parse(text(data.content))}</div>`;
@@ -327,9 +357,9 @@ async function collect(
           if (img) manifest.embeddedImages += 1;
         }
         card.html = img
-          ? `<img class="image" src="${escapeHtml(img)}" alt="${escapeHtml(alt)}" referrerpolicy="no-referrer">${
-              text(data.caption) ? `<p class="dim">${escapeHtml(text(data.caption))}</p>` : ''
-            }`
+          ? `<figure class="image-figure"><img class="image" src="${escapeHtml(img)}" alt="${escapeHtml(alt)}" referrerpolicy="no-referrer">${
+              text(data.caption) ? `<figcaption class="dim">${escapeHtml(text(data.caption))}</figcaption>` : ''
+            }</figure>`
           : `<div class="placeholder">Image not available: ${escapeHtml(src)}</div>`;
         break;
       }
@@ -337,14 +367,14 @@ async function collect(
         const path = text(data.path);
         if (!path) {
           // Inline content the board itself holds, not a file on disk.
-          card.html = pre(text(data.fileContent) || text(data.content), 'code');
+          card.html = fileBody(text(data.fileContent) || text(data.content), title);
           break;
         }
         const body = includeFiles ? fileText(node, path) : null;
         manifest.files.push({ nodeId: node.id, path, included: body !== null });
         card.html = `<p class="dim">${escapeHtml(path)}</p>${
           body !== null
-            ? pre(body, 'code')
+            ? fileBody(body, path)
             : '<div class="placeholder">File contents not included in this export.</div>'
         }`;
         break;
@@ -527,7 +557,7 @@ function exportPage(input: {
   </div>
 </header>
 <main id="stage" aria-label="Board"><div id="world"><svg id="edges" aria-hidden="true"></svg></div></main>
-<div id="overlay" hidden><div class="sheet" role="dialog" aria-modal="true"><header><strong id="overlay-title"></strong><button type="button" id="overlay-close" aria-label="Close">×</button></header><div id="overlay-body"></div></div></div>
+<div id="overlay" hidden><div class="sheet" role="dialog" aria-modal="true" aria-labelledby="overlay-title"><header><strong id="overlay-title"></strong><button type="button" id="overlay-close" aria-label="Close">×</button></header><div id="overlay-body"></div></div></div>
 <script type="application/json" id="pmx-board">${scriptJson(input.board)}</script>
 <script type="application/json" id="pmx-assets">${scriptJson(input.assets)}</script>
 <script>${EXPORT_VIEWER_JS}</script>
@@ -540,7 +570,7 @@ const EXPORT_CSS = `
 :root{--bg:#0b1016;--panel:#121a23;--line:#263241;--text:#e8edf2;--soft:#9aa7b4;--accent:#4bbcff;--add:#2ea66f;--del:#e25d6e}
 [data-scheme=light]{--bg:#f4f6f8;--panel:#ffffff;--line:#d5dbe1;--text:#17202a;--soft:#5b6875;--accent:#0a6fc2;--add:#1c7a4f;--del:#b3263a}
 *{box-sizing:border-box}
-html,body{margin:0;height:100%;background:var(--bg);color:var(--text);font:14px/1.45 system-ui,-apple-system,Segoe UI,sans-serif}
+html,body{margin:0;height:100%;background:var(--bg);color:var(--text);font:15px/1.65 system-ui,-apple-system,Segoe UI,sans-serif}
 .bar{position:fixed;top:0;left:0;right:0;height:48px;display:flex;align-items:center;justify-content:space-between;gap:12px;padding:0 16px;background:var(--panel);border-bottom:1px solid var(--line);z-index:5}
 .bar .name{display:flex;flex-direction:column;min-width:0}
 .bar .name strong,.bar .name span{white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
@@ -548,6 +578,7 @@ html,body{margin:0;height:100%;background:var(--bg);color:var(--text);font:14px/
 .tools{display:flex;gap:6px;flex-shrink:0}
 button{font:inherit;color:var(--text);background:none;border:1px solid var(--line);border-radius:7px;padding:4px 10px;cursor:pointer}
 button:hover{border-color:var(--accent)}
+button:focus-visible,a:focus-visible,[tabindex]:focus-visible{outline:2px solid var(--accent);outline-offset:-3px}
 #stage{position:fixed;top:48px;left:0;right:0;bottom:0;overflow:hidden;cursor:grab;touch-action:none}
 #stage.panning{cursor:grabbing}
 #world{position:absolute;left:0;top:0;transform-origin:0 0}
@@ -556,25 +587,43 @@ button:hover{border-color:var(--accent)}
 #edges text{fill:var(--soft);font-size:12px;text-anchor:middle}
 .card{position:absolute;display:flex;flex-direction:column;background:var(--panel);border:1px solid var(--line);border-radius:10px;overflow:hidden;box-shadow:0 6px 24px rgba(0,0,0,.18)}
 .card.group{background:color-mix(in srgb,var(--accent) 5%,transparent);border-style:dashed;box-shadow:none}
-.card-title{flex-shrink:0;padding:7px 10px;font-weight:600;font-size:13px;border-bottom:1px solid var(--line);cursor:zoom-in;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.card-title{position:relative;flex-shrink:0;width:100%;text-align:left;padding:12px 42px 12px 18px;font-weight:600;font-size:13px;border:0;border-bottom:1px solid var(--line);border-radius:0;cursor:zoom-in;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;background:color-mix(in srgb,var(--soft) 5%,var(--panel))}
+button.card-title:after{content:'↗';position:absolute;right:16px;color:var(--soft);font-size:16px}
 .card.group .card-title{border-bottom:none;cursor:default;color:var(--soft)}
-.card-body{flex:1;min-height:0;overflow:auto;padding:8px 10px}
-.card iframe,#overlay-body iframe{flex:1;width:100%;height:100%;border:0;background:var(--bg)}
-.md h1,.md h2,.md h3{margin:.4em 0 .3em;line-height:1.2}.md p{margin:.4em 0}.md img{max-width:100%}
-.md code,pre{font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace}
-pre{margin:0;white-space:pre-wrap;word-break:break-word}
-pre.diff .add{color:var(--add)}pre.diff .del{color:var(--del)}pre.diff .hunk{color:var(--accent)}
-a{color:var(--accent)}
+.card-body{flex:1;min-height:0;min-width:0;overflow:auto;padding:20px;overflow-wrap:anywhere;overscroll-behavior:contain;cursor:auto}
+.card-body>:first-child,.md>:first-child{margin-top:0}.card-body>:last-child,.md>:last-child{margin-bottom:0}
+.card iframe,#overlay-body iframe{flex:1;min-height:0;width:100%;height:100%;border:0;background:var(--bg)}
+.md h1,.md h2,.md h3,.md h4,.md h5,.md h6{margin:1.4em 0 .6em;line-height:1.3;font-weight:650;letter-spacing:-.02em}
+.md h1{font-size:26px}.md h2{font-size:21px}.md h3{font-size:18px}.md h4,.md h5,.md h6{font-size:15px}
+.md p{margin:0 0 1em}.md img{max-width:100%;height:auto;border-radius:6px}
+.md ul,.md ol{padding-left:1.6em;margin:0 0 1em}.md li+li{margin-top:.35em}.md li>ul,.md li>ol{margin-top:.4em;margin-bottom:.4em}
+.md input[type=checkbox]{accent-color:var(--accent);margin-right:.5em}
+.md blockquote{margin:1em 0;padding:10px 16px;border-left:3px solid var(--accent);background:color-mix(in srgb,var(--accent) 7%,var(--panel));color:var(--soft)}
+.md blockquote>:last-child{margin-bottom:0}.md hr{border:0;border-top:1px solid var(--line);margin:24px 0}
+.md code,pre{font:13px/1.65 ui-monospace,SFMono-Regular,Menlo,monospace;tab-size:2}
+.md :not(pre)>code{padding:2px 5px;border:1px solid var(--line);border-radius:4px;background:color-mix(in srgb,var(--soft) 8%,var(--panel))}
+pre{margin:0 0 16px;padding:14px 16px;border:1px solid var(--line);border-radius:8px;background:color-mix(in srgb,var(--soft) 5%,var(--panel));white-space:pre;overflow:auto;overflow-wrap:normal;overscroll-behavior:contain}
+.prose{white-space:pre-wrap}.table-scroll{width:100%;max-width:100%;overflow:auto;margin:16px 0;border:1px solid var(--line);border-radius:8px;overscroll-behavior:contain}
+.table-scroll table{border-collapse:separate;border-spacing:0;width:100%;font-size:13px;line-height:1.55;font-variant-numeric:tabular-nums}
+.table-scroll th,.table-scroll td{padding:10px 14px;min-width:90px;max-width:36ch;border-bottom:1px solid var(--line);border-right:1px solid var(--line);vertical-align:top;overflow-wrap:normal;white-space:pre-wrap}
+.table-scroll th{font-weight:650;background:color-mix(in srgb,var(--soft) 10%,var(--panel))}.table-scroll th:not([align]){text-align:left}
+.table-scroll tr:nth-child(even) td{background:color-mix(in srgb,var(--soft) 4%,var(--panel))}
+.table-scroll tr:last-child td{border-bottom:0}.table-scroll tr>:last-child{border-right:0}
+pre.diff .add{color:var(--add);background:color-mix(in srgb,var(--add) 9%,transparent)}pre.diff .del{color:var(--del);background:color-mix(in srgb,var(--del) 9%,transparent)}pre.diff .hunk{color:var(--accent)}
+a{color:var(--accent);text-underline-offset:3px}
 .dim{color:var(--soft)}
-.kv{border-collapse:collapse;font-size:12px}.kv th{text-align:left;color:var(--soft);padding:2px 10px 2px 0;vertical-align:top}.kv td{padding:2px 0}
-.list{margin:0;padding-left:18px}
-.image{max-width:100%;max-height:100%;object-fit:contain;display:block;margin:auto}
-.placeholder{padding:12px;border:1px dashed var(--line);border-radius:8px;color:var(--soft);font-size:12px}
+.kv{border-collapse:collapse;width:100%;font-size:14px;table-layout:fixed}.kv th{text-align:left;color:var(--soft);width:30%;font-weight:500}.kv th,.kv td{padding:10px 12px;border-bottom:1px solid var(--line);vertical-align:top;white-space:pre-wrap}.kv tr:last-child>*{border-bottom:0}
+.list{list-style:none;margin:0;padding:0}.list li{padding:12px 0;border-bottom:1px solid var(--line)}.list li:last-child{border-bottom:0}.list p{margin:6px 0 0;color:var(--soft)}
+.image-figure{margin:0;height:100%;display:flex;flex-direction:column;gap:12px}.image{flex:1;min-height:0;max-width:100%;width:100%;object-fit:contain;display:block}.image-figure figcaption{flex-shrink:0;font-size:13px;text-align:center}
+.placeholder{padding:16px;border:1px dashed var(--line);border-radius:8px;color:var(--soft);font-size:14px;line-height:1.6}
+details{margin-top:16px}summary{cursor:pointer;color:var(--soft);margin-bottom:12px}
 #overlay{position:fixed;inset:0;background:rgba(0,0,0,.5);display:flex;align-items:center;justify-content:center;padding:24px;z-index:10}
 #overlay[hidden]{display:none}
 #overlay .sheet{width:min(1100px,100%);height:min(90vh,100%);display:flex;flex-direction:column;background:var(--panel);border:1px solid var(--line);border-radius:12px;overflow:hidden}
 #overlay .sheet>header{display:flex;justify-content:space-between;align-items:center;padding:10px 14px;border-bottom:1px solid var(--line)}
-#overlay-body{flex:1;min-height:0;overflow:auto;padding:14px;display:flex;flex-direction:column}
+#overlay-body{flex:1;min-height:0;overflow:hidden;display:flex;flex-direction:column}
+#overlay-body .card-body{padding:28px 32px}#overlay-body .md{max-width:960px;margin:0 auto}
+@media(max-width:600px){#overlay{padding:8px}#overlay .sheet{height:100%}#overlay-body .card-body{padding:18px}.bar{padding:0 10px}.bar .name span{display:none}}
 `;
 
 const EXPORT_VIEWER_JS = `(() => {
@@ -606,12 +655,15 @@ for (const card of ordered) {
   const el = document.createElement('section');
   el.className = 'card' + (card.group ? ' group' : '');
   el.dataset.nodeId = card.id;
+  el.dataset.nodeType = card.kind;
   Object.assign(el.style, { left: card.x + 'px', top: card.y + 'px', width: card.w + 'px', height: card.h + 'px' });
-  const title = document.createElement('div');
+  const title = document.createElement(card.group ? 'div' : 'button');
   title.className = 'card-title';
   title.textContent = card.title;
   el.appendChild(title);
   if (!card.group) {
+    title.type = 'button';
+    title.setAttribute('aria-label', 'Expand ' + card.title);
     el.appendChild(body(card));
     title.addEventListener('click', () => expand(card));
   }
@@ -653,6 +705,7 @@ const zoomAt = (factor, cx, cy) => {
   apply();
 };
 stage.addEventListener('wheel', (e) => {
+  if (e.target.closest('.card-body') && !e.ctrlKey && !e.metaKey) return;
   e.preventDefault();
   const r = stage.getBoundingClientRect();
   zoomAt(Math.exp(-e.deltaY * 0.0015), e.clientX - r.left, e.clientY - r.top);
@@ -673,11 +726,23 @@ stage.addEventListener('pointerup', () => { drag = null; stage.classList.remove(
 document.querySelector('[data-zoom=in]').addEventListener('click', () => zoomAt(1.25, stage.clientWidth / 2, stage.clientHeight / 2));
 document.querySelector('[data-zoom=out]').addEventListener('click', () => zoomAt(0.8, stage.clientWidth / 2, stage.clientHeight / 2));
 document.querySelector('[data-zoom=fit]').addEventListener('click', fit);
-const close = () => { overlay.hidden = true; document.getElementById('overlay-body').replaceChildren(); };
+let invoker = null;
+const close = () => {
+  if (overlay.hidden) return;
+  overlay.hidden = true;
+  document.getElementById('overlay-body').replaceChildren();
+  stage.inert = false;
+  document.querySelector('.bar').inert = false;
+  invoker?.focus({ preventScroll: true });
+};
 function expand(card) {
+  invoker = document.activeElement;
   document.getElementById('overlay-title').textContent = card.title;
   document.getElementById('overlay-body').replaceChildren(body(card));
   overlay.hidden = false;
+  stage.inert = true;
+  document.querySelector('.bar').inert = true;
+  document.getElementById('overlay-close').focus();
 }
 document.getElementById('overlay-close').addEventListener('click', close);
 overlay.addEventListener('click', (e) => { if (e.target === overlay) close(); });

package/src/server/index.ts

@@ -44,6 +44,7 @@ import type { BackupFile, BackupStatus } from './backup.js';
 import type { ExportManifest } from './board-export.js';
 import { onFileNodeChanged } from './file-watcher.js';
 import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
+import { overlapsAny } from '../shared/placement.js';
 import { searchNodes, buildSpatialContext } from './spatial-analysis.js';
 import { mutationHistory, diffLayouts, formatDiff } from './mutation-history.js';
 import { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
@@ -741,14 +742,19 @@ export class PmxCanvas extends EventEmitter {
   } {
     if (canvasState.activeBoardId !== input.boardId) throw new Error('The captured target board is not active.');
     assertInsideFence('node.add', createTarget(input));
+    const obstacles = canvasState.getLayout().nodes;
+    const requested = { x: input.x ?? 40, y: input.y ?? 80 };
+    const position = overlapsAny(requested, 440, 360, obstacles, 48)
+      ? findOpenCanvasPosition(obstacles, 440, 360, 48)
+      : requested;
+    assertInsideFence('node.add', createTarget(position));
     const attachment = canvasState.storeAttachment({ ...input, mime: input.mime ?? 'application/octet-stream' });
     if (!attachment) throw new Error('Board not found.');
     const { id: nodeId, node } = addCanvasNode({
       type: 'file',
       title: input.name,
       data: { attachmentId: attachment.id, mime: attachment.mime, size: attachment.size },
-      x: input.x,
-      y: input.y,
+      ...position,
       defaultWidth: 440,
       defaultHeight: 360,
       fileMode: 'auto',
@@ -840,11 +846,7 @@ export class PmxCanvas extends EventEmitter {
 
   /** Open a board, or Home with null. */
   async openBoard(id: string | null): Promise<void> {
-    await executeOperation(
-      'board.open',
-      { id },
-      { source: 'sdk', fromWorkbench: true, humanAuthor: true, suppressAutoGhost: true },
-    );
+    await executeOperation('board.open', { id }, { source: 'sdk', suppressAutoGhost: true });
   }
 
   async deleteBoard(id: string): Promise<void> {

package/src/server/operations/composites.ts

@@ -151,13 +151,14 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_board',
     description:
-      'Boards in this workspace — the library of the human\'s and your working memory, filed in categories on Home. Your writes always go to the board the human has open (activeBoardId); on Home (no board open) your first write opens their most recent board, or a new one when there are none. Action "list" returns every board (with its category), most recently opened first; "get" reads one (default: the open board); "create" makes a new empty board WITHOUT opening it (optional category); "update" renames a board, files it under a category (category "" removes it), or designates its README via readmeNodeId. As part of normal board authoring, read the board metadata; if readmeNodeId is null, choose or create a concise markdown introduction explaining its purpose and key context, then designate that node with "update". Preserve an existing README unless the human asks to change it; humans can override the designation manually. Only the human opens, switches or deletes boards — if you need another board, ask them in the chat to open it.',
-    actionSummary: 'list | get | create | create-from | update',
+      'Boards in this workspace — the library of the human\'s and your working memory, filed in categories on Home. Your writes always go to the open board (activeBoardId); on Home (no board open) your first write opens the most recent board, or a new one when there are none. Action "list" returns every board (with its category), most recently opened first; "get" reads one (default: the open board); "create" makes a new empty board WITHOUT opening it (optional category); "open" explicitly switches the shared workbench to id (null or omitted opens Home), changing the visible board and subsequent write target. After creating a board, open its returned id and verify activeBoardId before writing; another participant can switch the board later. "update" renames a board, files it under a category (category "" removes it), or designates its README via readmeNodeId. As part of normal board authoring, read the board metadata; if readmeNodeId is null, choose or create a concise markdown introduction explaining its purpose and key context, then designate that node with "update". Preserve an existing README unless the human asks to change it; humans can override the designation manually. Only the human deletes boards.',
+    actionSummary: 'list | get | create | create-from | open | update',
     actions: {
       list: 'board.list',
       get: 'board.get',
       create: 'board.create',
       'create-from': 'board.create-from',
+      open: 'board.open',
       update: 'board.update',
     },
   },

package/src/server/operations/ops/ax-presence.ts

@@ -27,13 +27,17 @@ const presenceGetOperation = defineOperation<z.infer<typeof emptySchema>, Record
 // One schema (agent-presence.ts) — only the descriptions are added here.
 const presenceSetShape = {
   source: PRESENCE_SET_SHAPE.source.describe('Host label (copilot, codex, mcp, …); defaults to the transport'),
-  agentId: PRESENCE_SET_SHAPE.agentId.describe('Per-agent identity within the host (sub-agents keep their own cursor)'),
-  label: PRESENCE_SET_SHAPE.label.describe('Display name for this writer'),
+  agentId: PRESENCE_SET_SHAPE.agentId.describe(
+    'Stable identity for a genuinely separate agent, not a task name. Omit for the main agent when a host adapter already owns its session.',
+  ),
+  label: PRESENCE_SET_SHAPE.label.describe('Display name for this writer; use detail for the current task'),
   phase: PRESENCE_SET_SHAPE.phase.describe('idle | thinking | tooling | waiting-approval'),
   detail: PRESENCE_SET_SHAPE.detail.describe('Tool / step name shown beside the phase'),
   focusNodeId: PRESENCE_SET_SHAPE.focusNodeId.describe('Node the agent is working on'),
   cursor: PRESENCE_SET_SHAPE.cursor.describe('Agent cursor in world coordinates'),
-  attached: PRESENCE_SET_SHAPE.attached.describe('true attaches a session (Focus Session chrome); false detaches it'),
+  attached: PRESENCE_SET_SHAPE.attached.describe(
+    'true attaches a session; false detaches it. Read presence first and reuse your host adapter session instead of attaching another. Only detach sessions you own.',
+  ),
   contextUsage: PRESENCE_SET_SHAPE.contextUsage.describe(
     "The agent's real token window as {used,total} — shown on the board's context meter instead of the pinned-context estimate (null clears it)",
   ),

package/src/server/operations/ops/boards.ts

@@ -2,9 +2,9 @@
  * Many boards (plan 012): board.list / board.get / board.create /
  * board.update / board.open / board.delete.
  *
- * Agents list, read and create boards. Opening, switching and deleting are the
- * human's (HUMAN_ONLY_OPS in registry.ts): an agent that wants another board
- * asks. Every change broadcasts `boards-changed` with the full list.
+ * Agents can explicitly open boards as well as list, read and create them.
+ * Deletion requires the human (HUMAN_ONLY_OPS in registry.ts).
+ * Every change broadcasts `boards-changed` with the full list.
  *
  * Route-order note: board.open (POST /api/canvas/boards/open) is registered
  * before any `/api/canvas/boards/:id` POST route so ':id' cannot swallow it.
@@ -171,7 +171,7 @@ const boardCreateOperation = defineOperation<z.infer<typeof createSchema>, Recor
   mcp: {
     toolName: 'canvas_create_board',
     description:
-      'Create a new empty board. It is NOT opened: only the human opens boards, so ask them to open it before writing to it.',
+      'Create a new empty board without opening it. Use canvas_board action "open" with the returned board id before writing to it.',
     extraShape: {
       name: z.string().describe('Board name'),
       category: z.string().optional().describe('Folder path on Home, e.g. Engineering/Canvas'),
@@ -186,7 +186,7 @@ const boardCreateOperation = defineOperation<z.infer<typeof createSchema>, Recor
   },
 });
 
-// ── board.open (human only) ───────────────────────────────────
+// ── board.open ────────────────────────────────────────────────
 
 const openShape = {
   id: z.unknown().optional().describe('Board id to open; null or omitted opens Home'),
@@ -199,6 +199,13 @@ const boardOpenOperation = defineOperation<z.infer<typeof openSchema>, Record<st
   input: openSchema,
   inputShape: openShape,
   http: { method: 'POST', path: '/api/canvas/boards/open' },
+  mcp: {
+    toolName: 'canvas_open_board',
+    description:
+      'Open a board in the shared workbench, or Home with null. Changes the visible board and the target of subsequent writes. Verify activeBoardId in the response before authoring.',
+    extraShape: { id: z.string().nullable().optional().describe('Board id to open; null or omitted opens Home') },
+    formatResult: jsonResult,
+  },
   handler: (input, ctx) => {
     const id = typeof input.id === 'string' && input.id.trim() ? input.id.trim() : null;
     if (!openCanvasBoard(id).ok) throw new OperationError(`Board "${id}" not found.`, 404);

package/src/server/operations/registry.ts

@@ -405,15 +405,9 @@ export async function executeOperation(
   );
 }
 
-/** Opening, switching and deleting boards is the human's; an agent asks for another board. */
-const HUMAN_ONLY_OPS = new Set(['board.open', 'board.delete', 'import.request', 'import.cancel', 'import.commit']);
-const TRUSTED_HUMAN_ONLY_OPS = new Set([
-  'board.open',
-  'board.delete',
-  'import.request',
-  'import.cancel',
-  'import.commit',
-]);
+/** Board deletion and import review actions require the human in the workbench. */
+const HUMAN_ONLY_OPS = new Set(['board.delete', 'import.request', 'import.cancel', 'import.commit']);
+const TRUSTED_HUMAN_ONLY_OPS = new Set(['board.delete', 'import.request', 'import.cancel', 'import.commit']);
 
 /**
  * Writes that need a board beyond the layout mutations: canvas-bound AX items,
@@ -443,10 +437,7 @@ function needsOpenBoard(op: Operation): boolean {
 async function executeOperationInner(name: string, rawInput: unknown, meta: ExecuteOperationMeta): Promise<unknown> {
   const op = getOperation(name);
   if (HUMAN_ONLY_OPS.has(name) && !meta.fromWorkbench) {
-    throw new OperationError(
-      'Only the human opens or deletes boards. Ask them in the chat to open the board you need.',
-      403,
-    );
+    throw new OperationError('This action requires the human in the workbench.', 403);
   }
   if (TRUSTED_HUMAN_ONLY_OPS.has(name) && !meta.humanAuthor) {
     throw new OperationError('This action requires trusted human authority.', 403);

package/src/server/server.ts

@@ -61,6 +61,7 @@ import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 import { getMcpAppHostSnapshot } from './mcp-app-host.js';
 import { closeMcpAppSession, closeAllMcpAppSessions } from './mcp-app-runtime.js';
 import { findOpenCanvasPosition } from './placement.js';
+import { overlapsAny } from '../shared/placement.js';
 import { mutationHistory } from './mutation-history.js';
 import { buildAgentContextPreamble } from './agent-context.js';
 import { buildCanvasAxSurfaceSnapshot } from './ax-context.js';
@@ -1736,10 +1737,12 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
   const html = await buildJsonRenderViewerHtml({
     title,
     spec,
+    nodeId,
+    stateToken: url.searchParams.get('stateToken') ?? undefined,
     ...(theme ? { theme } : {}),
     ...(display ? { display } : {}),
     ...(devtoolsEnabled ? { devtools: true } : {}),
-    ...(axToken ? { nodeId, axToken } : {}),
+    ...(axToken ? { axToken } : {}),
     // Seed the read-side AX state (only for AX-enabled nodes) so specs can bind /ax.
     ...(axToken && axEnabled ? { axState: buildCanvasAxSurfaceSnapshot() } : {}),
     // Content-fit: report natural height (charts render intrinsic) so the node grows.
@@ -3474,19 +3477,25 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
               canvasState.storeAttachment({ boardId, name, mime, bytes }),
             );
             if (!attachment) return responseJson({ ok: false, error: 'Board not found.' }, 404);
+            const obstacles = canvasState.getLayout().nodes;
+            const position = overlapsAny({ x, y }, 440, 360, obstacles, 48)
+              ? findOpenCanvasPosition(obstacles, 440, 360, 48)
+              : { x, y };
             const { node } = withCurrentActor({ actor: 'human', source: 'browser' }, () =>
               addCanvasNode({
                 type: 'file',
                 title: name,
                 data: { attachmentId: attachment.id, mime, size: attachment.size },
-                x,
-                y,
+                ...position,
                 defaultWidth: 440,
                 defaultHeight: 360,
                 fileMode: 'auto',
               }),
             );
-            const created = canvasState.createDocumentImport(attachment.id, { x, y: y + 400 });
+            const created = canvasState.createDocumentImport(attachment.id, {
+              x: node.position.x,
+              y: node.position.y + 400,
+            });
             const documentImport = created;
             emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
             return responseJson({ ok: true, attachment, nodeId: node.id, import: documentImport }, 201);

package/src/shared/ax-surface-protocol.ts

@@ -18,6 +18,9 @@ export const AX_SURFACE_ACK_SOURCE = 'pmx-canvas-ax-ack';
 /** Parent→surface pushes (theme updates, live AX state) into html/viewer iframes. */
 export const HTML_SURFACE_PUSH_SOURCE = 'pmx-canvas-html-node';
 
+/** Tab-local JSON viewer state handoff, independent of AX capabilities. */
+export const JSON_VIEWER_STATE_SOURCE = 'pmx-canvas-json-state';
+
 /** Ext-app boot beacon: the iframe's scripts executed (WebKit watchdog liveness). */
 export const EXT_APP_BOOT_BEACON_SOURCE = 'pmx-canvas-ext-app-alive';
 

package/src/shared/delimited-text.ts

@@ -0,0 +1,75 @@
+export interface DelimitedTable {
+  header: string[];
+  /** Rectangular: every row padded (short) or truncated (long) to the header width. */
+  rows: string[][];
+}
+
+/** Column delimiter for a delimited-data path, or null when the file is not one. */
+export function delimiterForPath(path: string): string | null {
+  const lower = path.toLowerCase();
+  if (lower.endsWith('.csv')) return ',';
+  if (lower.endsWith('.tsv')) return '\t';
+  return null;
+}
+
+/**
+ * RFC4180-ish delimited-text parser. Quoted fields may contain the delimiter,
+ * newlines, and `""` escapes; CRLF, LF and lone CR all end a record; a trailing
+ * newline produces no phantom empty row. Ragged records are squared off against
+ * the header width instead of throwing.
+ */
+export function parseDelimitedText(text: string, delimiter: string): DelimitedTable {
+  const records: string[][] = [];
+  let row: string[] = [];
+  let field = '';
+  let quoted = false;
+  // Tracks whether the current record consumed anything — distinguishes a real
+  // empty-quoted record from the dangling state after a terminating newline.
+  let started = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    started = true;
+    if (quoted) {
+      if (char === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          quoted = false;
+        }
+      } else if (char === '\r' && text[i + 1] === '\n') {
+        field += '\n';
+        i++;
+      } else {
+        field += char;
+      }
+      continue;
+    }
+    if (char === '"' && field === '') {
+      quoted = true;
+    } else if (char === delimiter) {
+      row.push(field);
+      field = '';
+    } else if (char === '\n' || char === '\r') {
+      if (char === '\r' && text[i + 1] === '\n') i++;
+      row.push(field);
+      field = '';
+      records.push(row);
+      row = [];
+      started = false;
+    } else {
+      field += char;
+    }
+  }
+  if (started) {
+    row.push(field);
+    records.push(row);
+  }
+
+  const header = records.shift() ?? [];
+  return {
+    header,
+    rows: records.map((record) => Array.from({ length: header.length }, (_, i) => record[i] ?? '')),
+  };
+}