pmx-canvas 0.1.30 → 0.1.31

package/dist/types/server/canvas-state.d.ts

@@ -199,6 +199,13 @@ declare class CanvasStateManager {
     private emptyPersistedState;
     /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
+    /**
+     * Whether this workspace's canvas DB already holds saved state. Used to gate
+     * brand-new-workspace seeding (e.g. the default docked status/context widgets)
+     * so we never add nodes to a canvas that already has content. Reflects the
+     * pre-run persisted flag until the next save.
+     */
+    hasPersistedState(): boolean;
     /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;

package/dist/types/server/html-surface.d.ts

@@ -22,6 +22,12 @@ export declare const HTML_SURFACE_SANDBOX = "allow-scripts";
 export declare function normalizeSurfaceTheme(value: string | null | undefined): SurfaceTheme;
 export interface HtmlSurfaceOptions {
     theme: SurfaceTheme;
+    /**
+     * Tab/document title. Injected as `<title>` only when the author HTML does not
+     * already declare one, so a standalone "Open as site" tab shows the node title
+     * instead of falling back to the raw URL.
+     */
+    title?: string;
     /** Client nonce that authorizes parent → iframe theme-update messages. */
     themeToken?: string;
     presentation?: boolean;

package/dist/types/server/index.d.ts

@@ -7,12 +7,22 @@ import type { AxTimelineQuery } from './canvas-db.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
 import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
+import { type SerializedCanvasNode } from './canvas-serialization.js';
 import type { HtmlPrimitiveKind } from './html-primitives.js';
 import { type WebArtifactBuildInput, type WebArtifactCanvasBuildResult } from './web-artifacts.js';
 import { type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 import { type DiagramPresetOpenInput } from './diagram-presets.js';
 import { type GraphNodeInput, type JsonRenderNodeInput, type JsonRenderSpec } from '../json-render/server.js';
 import type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus } from './server.js';
+/**
+ * Node object returned by the SDK's create/get methods. It is the fully
+ * serialized node (adds `surfaceUrl`, `kind`, `title`, `content`, …) plus a
+ * `nodeId` alias for `id`, so the SDK return shape matches the HTTP/CLI
+ * `node`-create responses field-for-field.
+ */
+export type SdkCanvasNode = SerializedCanvasNode & {
+    nodeId: string;
+};
 export declare class PmxCanvas extends EventEmitter {
     private _port;
     private _server;
@@ -54,7 +64,7 @@ export declare class PmxCanvas extends EventEmitter {
         width?: number;
         height?: number;
         strictSize?: boolean;
-    }): CanvasNodeState;
+    }): SdkCanvasNode;
     addWebpageNode(input: {
         title?: string;
         url: string;
@@ -262,7 +272,7 @@ export declare class PmxCanvas extends EventEmitter {
         nodeIds?: string[];
     }): ReturnType<typeof fitCanvasView>;
     getLayout(): CanvasLayout;
-    getNode(id: string): CanvasNodeState | undefined;
+    getNode(id: string): SdkCanvasNode | undefined;
     search(query: string): ReturnType<typeof searchNodes>;
     getSpatialContext(): import("./spatial-analysis.js").SpatialContext;
     undo(): Promise<{
@@ -435,7 +445,7 @@ export declare class PmxCanvas extends EventEmitter {
         width?: number;
         height?: number;
         strictSize?: boolean;
-    }): string;
+    }): SdkCanvasNode;
     addHtmlPrimitive(input: {
         kind: HtmlPrimitiveKind;
         title?: string;

package/dist/types/server/server.d.ts

@@ -83,6 +83,18 @@ export declare function hasWorkbenchSubscribers(): boolean;
 export declare function setPrimaryWorkbenchCanvasPromptHandler(handler: PrimaryWorkbenchCanvasPromptHandler | null): void;
 export declare function buildMacBrowserOpenScript(appName: string, url: string): string;
 export declare function openUrlInExternalBrowser(url: string): boolean;
+/**
+ * Seed the docked status (left) + context (right) widgets so a freshly opened
+ * canvas shows them by default — the same nodes the agent-event path creates on
+ * demand (`status-main`, `context-main`), just present from the start.
+ *
+ * First-run only: we bail if the workspace canvas already has persisted state,
+ * so we never add them to a board with content, and — because first-run state is
+ * persisted on save — deleting or undocking them later is respected (they are
+ * not re-seeded). Create-if-missing keeps it idempotent if the agent path
+ * already made one. Returns true if anything was seeded.
+ */
+export declare function ensureDefaultDockedNodes(): boolean;
 export declare function emitPrimaryWorkbenchEvent(event: string, payload?: PrimaryWorkbenchEventPayload): void;
 export declare function consumePrimaryWorkbenchIntents(limit?: number): PrimaryWorkbenchIntent[];
 export declare function getPrimaryWorkbenchUrl(workspaceRoot?: string): string | null;

package/docs/sdk.md

@@ -15,7 +15,9 @@ import { createCanvas } from 'pmx-canvas';
 const canvas = createCanvas({ port: 4313 });
 await canvas.start({ open: true });
 
-// Add nodes — addNode returns the created node (with `.id`, geometry, and data)
+// Add nodes — addNode/getNode/addHtmlNode return the created node: `.id`
+// (plus a `.nodeId` alias), geometry, `.data`, and `.surfaceUrl` for
+// surface-eligible types (html, json-render, graph, …).
 const n1 = canvas.addNode({ type: 'markdown', title: 'Plan', content: '# Step 1\nDo the thing.' });
 const n2 = canvas.addNode({ type: 'status', title: 'Build', content: 'passing' });
 const n3 = canvas.addNode({ type: 'file', content: 'src/index.ts' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/src/cli/index.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { runAgentCli } from './agent.js';
 import { createCanvas } from '../server/index.js';
 import { seedDemoCanvas } from '../server/demo.js';
+import { ensureDefaultDockedNodes } from '../server/server.js';
 
 const args = process.argv.slice(2);
 
@@ -599,7 +600,13 @@ Examples:
     process.exit(1);
   }
 
-  if (demo && canvas.getLayout().nodes.length === 0) seedDemoCanvas();
+  if (demo && canvas.getLayout().nodes.length === 0) {
+    seedDemoCanvas();
+  } else if (!demo) {
+    // First-run only: dock a status (left) + context (right) widget by default so
+    // a fresh canvas isn't empty. No-op once the workspace has saved state.
+    ensureDefaultDockedNodes();
+  }
 
   console.log(`\n  PMX Canvas running at http://localhost:${canvas.port}`);
   console.log(`  Health: http://localhost:${canvas.port}/health\n`);

package/src/client/canvas/DockedNode.tsx

@@ -2,7 +2,7 @@ import { ContextNode } from '../nodes/ContextNode';
 import { LedgerNode } from '../nodes/LedgerNode';
 import { StatusNode } from '../nodes/StatusNode';
 import { StatusSummary } from '../nodes/StatusSummary';
-import { attentionHistoryOpen, closeAttentionHistory } from '../state/attention-store';
+import { closeAttentionHistory } from '../state/attention-store';
 import { getContextPinnedNodes, toggleCollapsed, undockNode } from '../state/canvas-store';
 import { TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
@@ -40,44 +40,44 @@ function ContextDockedNode({ node }: { node: CanvasNodeState }) {
     toggleCollapsed(node.id);
   };
 
-  // Hide the collapsed Context pill while the Updates side panel is open.
-  // Mutual exclusion guarantees both panels can't be expanded simultaneously,
-  // but the pill itself would otherwise sit beneath/beside the Updates panel
-  // at the same right edge — better to hide until Updates is closed.
-  if (collapsed && attentionHistoryOpen.value) return null;
-
   if (collapsed) {
+    // Collapsed = a menu-height pill in the right of the top HUD row, mirroring
+    // the docked status widget on the left so the bar reads as one continuous menu.
     return (
-      <button
-        type="button"
-        class="context-dock-tab"
-        data-docked-node="true"
-        onClick={expand}
-        aria-label={hasItems ? `Context — ${count} item${count === 1 ? '' : 's'}` : 'Context'}
-        title={hasItems ? `${count} item${count === 1 ? '' : 's'} in agent context` : 'Agent context'}
-      >
-        <svg
-          width="14"
-          height="14"
-          viewBox="0 0 16 16"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="1.5"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-          aria-hidden="true"
-        >
-          <rect x="1.5" y="2.5" width="13" height="11" rx="1.5" />
-          <line x1="1.5" y1="6" x2="14.5" y2="6" />
-          <circle cx="4" cy="4.25" r="0.6" fill="currentColor" stroke="none" />
-        </svg>
-        <span class="context-dock-tab-label">Context</span>
-        {hasItems && (
-          <span class="context-dock-tab-badge" aria-hidden="true">
-            {count > 99 ? '99+' : count}
-          </span>
-        )}
-      </button>
+      <div class="docked-node docked-node--collapsed" data-docked-node="true">
+        <div class="docked-node-header">
+          <span class="node-type-badge">Context</span>
+          {hasItems && (
+            <span class="docked-node-count" aria-hidden="true">
+              {count > 99 ? '99+' : count}
+            </span>
+          )}
+          <div class="docked-node-controls">
+            <button
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation();
+                expand();
+              }}
+              title={hasItems ? `${count} item${count === 1 ? '' : 's'} in agent context — expand` : 'Expand agent context'}
+              aria-label={hasItems ? `Context — ${count} item${count === 1 ? '' : 's'}` : 'Expand agent context'}
+            >
+              {'▸'}
+            </button>
+            <button
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation();
+                undockNode(node.id);
+              }}
+              title="Undock to canvas"
+              aria-label="Undock to canvas"
+            >
+              {'⊙'}
+            </button>
+          </div>
+        </div>
+      </div>
     );
   }
 
@@ -130,7 +130,7 @@ export function DockedNode({ node }: { node: CanvasNodeState }) {
   }
 
   return (
-    <div class="docked-node" data-docked-node="true">
+    <div class={`docked-node${node.collapsed ? ' docked-node--collapsed' : ''}`} data-docked-node="true">
       <div class="docked-node-header">
         <span class="node-type-badge">{TYPE_LABELS[node.type] ?? node.type}</span>
         {node.type === 'status' && node.collapsed && <StatusSummary node={node} />}

package/src/client/theme/global.css

@@ -56,6 +56,10 @@
   --mono: "IBM Plex Mono", "SF Mono", "Fira Code", monospace;
   --radius: 10px;
   --radius-sm: 6px;
+  /* Shared height for the top HUD row so the toolbar and the collapsed docked
+     status/context widgets that flank it line up to the same height. Matches the
+     toolbar's natural content height (icon buttons at 6px padding). */
+  --hud-bar-height: 44px;
 }
 
 :root[data-theme="light"] {
@@ -481,6 +485,8 @@ body,
   align-items: center;
   gap: 6px;
   padding: 6px 10px;
+  min-height: var(--hud-bar-height);
+  box-sizing: border-box;
   background: var(--c-panel-glass);
   backdrop-filter: blur(12px);
   border: 1px solid var(--c-line);
@@ -1409,6 +1415,38 @@ html.is-node-resizing .ext-app-preview-catcher {
   max-width: 320px;
 }
 
+/* Collapsed docked widget = a single menu-height pill that flanks the toolbar.
+   Pinned to the same height as .canvas-toolbar so the top HUD row reads as one
+   continuous bar (status on the left, context on the right). */
+.docked-node--collapsed {
+  height: var(--hud-bar-height);
+  box-sizing: border-box;
+  justify-content: center;
+  width: auto;
+  /* Reset the base .docked-node min-width so the collapsed pill hugs its content
+     (badge + count + controls) instead of stretching to a 200px bar. */
+  min-width: 0;
+}
+.docked-node--collapsed .docked-node-header {
+  height: 100%;
+  padding: 0 10px;
+  border-bottom: none;
+}
+.docked-node-count {
+  min-width: 18px;
+  height: 18px;
+  padding: 0 5px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 9px;
+  background: var(--c-accent);
+  color: var(--c-contrast-fg);
+  font-size: 10px;
+  font-weight: 700;
+  flex-shrink: 0;
+}
+
 .docked-node-header {
   display: flex;
   align-items: center;
@@ -1948,62 +1986,6 @@ html.is-node-resizing .ext-app-preview-catcher {
   max-width: 200px;
 }
 
-/* Context dock — collapsed pill mirrors Updates pill, sits above it */
-.context-dock-tab {
-  position: fixed;
-  top: 92px;
-  right: 0;
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 12px 8px 14px;
-  background: color-mix(in srgb, var(--c-panel-glass) 96%, transparent);
-  backdrop-filter: blur(16px);
-  border: 1px solid color-mix(in srgb, var(--c-line) 82%, var(--c-accent) 18%);
-  border-right: 0;
-  border-radius: 14px 0 0 14px;
-  box-shadow: 0 12px 36px var(--c-shadow);
-  color: var(--c-text);
-  cursor: pointer;
-  font: inherit;
-  font-size: 11px;
-  font-weight: 600;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-  z-index: 60;
-}
-
-.context-dock-tab:hover {
-  border-color: color-mix(in srgb, var(--c-accent) 40%, var(--c-line) 60%);
-  color: var(--c-accent);
-}
-
-.context-dock-tab svg {
-  display: block;
-  color: var(--c-accent);
-  flex-shrink: 0;
-}
-
-.context-dock-tab-label {
-  white-space: nowrap;
-}
-
-.context-dock-tab-badge {
-  min-width: 18px;
-  height: 18px;
-  padding: 0 5px;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  border-radius: 9px;
-  background: var(--c-accent);
-  color: var(--c-contrast-fg);
-  font-size: 10px;
-  font-weight: 700;
-  letter-spacing: 0;
-  text-transform: none;
-}
-
 /* Context dock — expanded panel anchored top-right edge.
    Mutually exclusive with the Updates panel (see DockedNode.tsx and
    AttentionHistory.tsx) — opening one collapses the other, so they can both

package/src/mcp/canvas-access.ts

@@ -271,7 +271,9 @@ class LocalCanvasAccess implements CanvasAccess {
   }
 
   async addHtmlNode(input: AddHtmlNodeInput): Promise<string> {
-    return this.canvas.addHtmlNode(input);
+    // PmxCanvas.addHtmlNode returns the created node; the CanvasAccess contract
+    // is a bare id string, so extract it (mirrors addNode above).
+    return this.canvas.addHtmlNode(input).id;
   }
 
   async addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult> {

package/src/server/canvas-state.ts

@@ -442,18 +442,14 @@ class CanvasStateManager {
   }
 
   private normalizeNode(node: CanvasNodeState): CanvasNodeState {
-    const normalized: CanvasNodeState = {
+    // Context nodes default to a right-docked, collapsed pill (see DockedNode.tsx),
+    // but that default is applied at CREATE time only — it must not be re-forced on
+    // every write, or the node could never be undocked. Undocking (dockPosition →
+    // null) is a deliberate user action and is respected here.
+    return {
       ...node,
       data: normalizeCanvasNodeData(node.type, node.data),
     };
-    // Context nodes are always docked to the right side as a pill/panel widget
-    // (see DockedNode.tsx). They start collapsed so the user sees the slim
-    // pill first; expanding reveals the full context overview panel.
-    if (normalized.type === 'context' && normalized.dockPosition !== 'right') {
-      normalized.dockPosition = 'right';
-      normalized.collapsed = true;
-    }
-    return normalized;
   }
 
   private nodeForRead(node: CanvasNodeState): CanvasNodeState {
@@ -930,6 +926,16 @@ class CanvasStateManager {
     return false;
   }
 
+  /**
+   * Whether this workspace's canvas DB already holds saved state. Used to gate
+   * brand-new-workspace seeding (e.g. the default docked status/context widgets)
+   * so we never add nodes to a canvas that already has content. Reflects the
+   * pre-run persisted flag until the next save.
+   */
+  hasPersistedState(): boolean {
+    return this._db ? isDbPopulated(this._db) : false;
+  }
+
   /** Debounced save — coalesces rapid mutations into a single write. */
   private scheduleSave(): void {
     if (!this._db) return;
@@ -1343,7 +1349,15 @@ class CanvasStateManager {
   }
 
   addNode(node: CanvasNodeState): void {
-    const cloned = structuredClone(this.normalizeNode(node));
+    // Context nodes default to a right-docked, collapsed pill when created without
+    // an explicit dock position. CREATE-time default only — once placed, updates
+    // (including undock → dockPosition null) are respected (see normalizeNode).
+    // Skip during suppressed replay (undo/redo re-add) so a deliberately-undocked
+    // context node is restored verbatim instead of being snapped back to the dock.
+    const seeded = node.type === 'context' && node.dockPosition == null && this._suppressRecordingDepth === 0
+      ? { ...node, dockPosition: 'right' as const, collapsed: true }
+      : node;
+    const cloned = structuredClone(this.normalizeNode(seeded));
     this.nodes.set(node.id, cloned);
     this.scheduleSave();
     this.notifyChange('nodes');

package/src/server/html-surface.ts

@@ -126,8 +126,19 @@ window.PMX_AX = {
 </script>`;
 }
 
+/** Escape a string for safe interpolation into element text (e.g. `<title>`). */
+function escapeSurfaceHtml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
 export interface HtmlSurfaceOptions {
   theme: SurfaceTheme;
+  /**
+   * Tab/document title. Injected as `<title>` only when the author HTML does not
+   * already declare one, so a standalone "Open as site" tab shows the node title
+   * instead of falling back to the raw URL.
+   */
+  title?: string;
   /** Client nonce that authorizes parent → iframe theme-update messages. */
   themeToken?: string;
   presentation?: boolean;
@@ -158,13 +169,22 @@ export function buildHtmlSurfaceDocument(userHtml: string, options: HtmlSurfaceO
   const presentationAttr = options.presentation ? ' data-pmx-presentation-mode="present"' : '';
   const trimmed = userHtml.trim();
   const isFullDoc = /<html[\s>]/i.test(trimmed);
+  // Only supply a fallback <title> when the author HTML does not already set a
+  // DOCUMENT title. Strip inline <svg>/<math> first so a nested accessibility
+  // <title> (e.g. <svg><title>…</title></svg>) doesn't suppress the fallback.
+  const withoutNestedTitles = trimmed
+    .replace(/<svg[\s\S]*?<\/svg>/gi, '')
+    .replace(/<math[\s\S]*?<\/math>/gi, '');
+  const titleTag = options.title && !/<title[\s>]/i.test(withoutNestedTitles)
+    ? `<title>${escapeSurfaceHtml(options.title)}</title>`
+    : '';
   if (isFullDoc) {
     const withTheme = trimmed.replace(
       /<html([^>]*)>/i,
       `<html$1 data-pmx-canvas-theme="${options.theme}" data-theme="${options.theme}"${presentationAttr}>`,
     );
-    return injectIntoHead(withTheme, injectedHeadContent);
+    return injectIntoHead(withTheme, `${titleTag}${injectedHeadContent}`);
   }
   // Fragment — wrap in a full document.
-  return `<!doctype html><html data-pmx-canvas-theme="${options.theme}" data-theme="${options.theme}"${presentationAttr}><head><meta charset="utf-8">${injectedHeadContent}</head><body>${userHtml}</body></html>`;
+  return `<!doctype html><html data-pmx-canvas-theme="${options.theme}" data-theme="${options.theme}"${presentationAttr}><head><meta charset="utf-8">${titleTag}${injectedHeadContent}</head><body>${userHtml}</body></html>`;
 }

package/src/server/index.ts

@@ -74,6 +74,7 @@ import {
 } from './canvas-operations.js';
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
+import { serializeCanvasNode, type SerializedCanvasNode } from './canvas-serialization.js';
 import { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors } from './html-primitives.js';
 import type { HtmlPrimitiveKind } from './html-primitives.js';
 import {
@@ -124,6 +125,19 @@ import type {
   PrimaryWorkbenchIntent,
 } from './server.js';
 
+/**
+ * Node object returned by the SDK's create/get methods. It is the fully
+ * serialized node (adds `surfaceUrl`, `kind`, `title`, `content`, …) plus a
+ * `nodeId` alias for `id`, so the SDK return shape matches the HTTP/CLI
+ * `node`-create responses field-for-field.
+ */
+export type SdkCanvasNode = SerializedCanvasNode & { nodeId: string };
+
+/** Enrich a raw canvas node into the SDK return shape (surfaceUrl + nodeId). */
+function toSdkNode(node: CanvasNodeState): SdkCanvasNode {
+  return { ...serializeCanvasNode(node), nodeId: node.id };
+}
+
 export class PmxCanvas extends EventEmitter {
   private _port: number;
   private _server: string | null = null;
@@ -224,7 +238,7 @@ export class PmxCanvas extends EventEmitter {
     width?: number;
     height?: number;
     strictSize?: boolean;
-  }): CanvasNodeState {
+  }): SdkCanvasNode {
     if (input.type === 'webpage') {
       throw new Error('Use addWebpageNode for webpage nodes so page content is fetched and cached on the server.');
     }
@@ -241,7 +255,7 @@ export class PmxCanvas extends EventEmitter {
       });
       const groupNode = canvasState.getNode(groupId);
       if (!groupNode) throw new Error(`Group node "${groupId}" was not created.`);
-      return groupNode;
+      return toSdkNode(groupNode);
     }
     const { id, needsCodeGraphRecompute } = addCanvasNode({
       ...input,
@@ -277,7 +291,7 @@ export class PmxCanvas extends EventEmitter {
 
     const node = canvasState.getNode(id);
     if (!node) throw new Error(`Node "${id}" was not created.`);
-    return node;
+    return toSdkNode(node);
   }
 
   async addWebpageNode(input: {
@@ -735,8 +749,9 @@ export class PmxCanvas extends EventEmitter {
     return canvasState.getLayout();
   }
 
-  getNode(id: string): CanvasNodeState | undefined {
-    return canvasState.getNode(id);
+  getNode(id: string): SdkCanvasNode | undefined {
+    const node = canvasState.getNode(id);
+    return node ? toSdkNode(node) : undefined;
   }
 
   search(query: string): ReturnType<typeof searchNodes> {
@@ -1027,7 +1042,7 @@ export class PmxCanvas extends EventEmitter {
     width?: number;
     height?: number;
     strictSize?: boolean;
-  }): string {
+  }): SdkCanvasNode {
     const { id } = addCanvasNode({
       type: 'html',
       ...(typeof input.title === 'string' ? { title: input.title } : {}),
@@ -1050,7 +1065,9 @@ export class PmxCanvas extends EventEmitter {
       defaultHeight: 640,
     });
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-    return id;
+    const node = canvasState.getNode(id);
+    if (!node) throw new Error(`HTML node "${id}" was not created.`);
+    return toSdkNode(node);
   }
 
   addHtmlPrimitive(input: {

package/src/server/server.ts

@@ -1432,8 +1432,12 @@ function handleNodeSurface(pathname: string, url: URL): Response {
     if (!html) return responseText('HTML node has no content', 404);
     const present = url.searchParams.get('present') === '1';
     const axCaps = resolveNodeAxCapabilities(node);
+    const surfaceTitle = typeof node.data.title === 'string' && node.data.title.trim()
+      ? node.data.title
+      : node.id;
     const doc = buildHtmlSurfaceDocument(html, {
       theme,
+      title: surfaceTitle,
       themeToken: url.searchParams.get('themeToken') ?? undefined,
       presentation: present,
       presentationExitToken: url.searchParams.get('presentToken') ?? undefined,
@@ -4482,6 +4486,57 @@ function syncContextNodeToCanvasState(
   canvasState.updateNode(id, { data: mergedData });
 }
 
+/**
+ * Seed the docked status (left) + context (right) widgets so a freshly opened
+ * canvas shows them by default — the same nodes the agent-event path creates on
+ * demand (`status-main`, `context-main`), just present from the start.
+ *
+ * First-run only: we bail if the workspace canvas already has persisted state,
+ * so we never add them to a board with content, and — because first-run state is
+ * persisted on save — deleting or undocking them later is respected (they are
+ * not re-seeded). Create-if-missing keeps it idempotent if the agent path
+ * already made one. Returns true if anything was seeded.
+ */
+export function ensureDefaultDockedNodes(): boolean {
+  if (canvasState.hasPersistedState()) return false;
+  let seeded = false;
+  // NOTE: these node specs mirror the agent-event create paths below
+  // (`canvas-status` for status-main, `syncContextNodeToCanvasState` for
+  // context-main) — keep geometry/dock defaults in sync if you change them.
+  if (!canvasState.getNode('status-main')) {
+    canvasState.addNode({
+      id: 'status-main',
+      type: 'status',
+      position: { x: 40, y: 80 },
+      size: { width: 300, height: 120 },
+      zIndex: 0,
+      collapsed: true,
+      pinned: false,
+      dockPosition: 'left',
+      data: { phase: 'idle', message: '', elapsed: 0 },
+    });
+    seeded = true;
+  }
+  if (!canvasState.getNode('context-main')) {
+    canvasState.addNode({
+      id: 'context-main',
+      type: 'context',
+      position: { x: 1130, y: 80 },
+      size: { width: 320, height: 400 },
+      zIndex: 1,
+      collapsed: true,
+      pinned: false,
+      dockPosition: 'right',
+      data: { cards: [], auxTabs: [] },
+    });
+    seeded = true;
+  }
+  if (seeded) {
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  }
+  return seeded;
+}
+
 // Maps responseNodeId -> thread prompt node ID for O(1) routing of response events
 const serverResponseToThreadMap = new Map<string, string>();