pmx-canvas 0.7.2 → 0.8.0

package/dist/types/cli/commands/record.d.ts

@@ -1,5 +1,5 @@
 export declare function parseRecordOptions(flags: Record<string, string | boolean>): {
-    theme: "dark" | "light" | "high-contrast" | "midnight" | "sepia" | "arctic" | "ember" | "forest" | "volt" | undefined;
+    theme: "harbor" | "daylight" | "high-contrast" | "midnight" | "sepia" | "arctic" | "ember" | "forest" | "volt" | undefined;
     present: boolean;
     tourFile: string | undefined;
     chromePath: string | undefined;

package/dist/types/client/canvas/ChoiceMenu.d.ts

@@ -0,0 +1,13 @@
+/** Themed single-choice menu shared by the feedback form and steering composer. */
+export declare function ChoiceMenu({ label, value, options, onChange, className, above, }: {
+    label: string;
+    value: string;
+    options: Array<{
+        value: string;
+        label: string;
+        disabled?: boolean;
+    }>;
+    onChange: (value: string) => void;
+    className?: string;
+    above?: boolean;
+}): import("preact/src").JSX.Element;

package/dist/types/client/canvas/NodeContextMark.d.ts

@@ -0,0 +1,24 @@
+import type { CanvasNodeState } from '../types';
+export declare const GLYPHS: {
+    readonly eye: "M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6S2 12 2 12zM12 9.5a2.5 2.5 0 1 0 0 5a2.5 2.5 0 1 0 0-5";
+    readonly eyeOff: "M3 3l18 18M10.6 6.1A10 10 0 0 1 12 6c6.5 0 10 6 10 6a17 17 0 0 1-3 3.6M6.6 6.6C3.8 8.3 2 12 2 12s3.5 6 10 6a9.6 9.6 0 0 0 4.4-1";
+    readonly spark: "M12 3l1.8 5.2L19 10l-5.2 1.8L12 17l-1.8-5.2L5 10l5.2-1.8z";
+    readonly pen: "M4 20l4.2-1L19 8.2 15.8 5 5 15.8z";
+    readonly warn: "M12 4l9 16H3zM12 10v4M12 17v.5";
+};
+/** The header chip saying what agents did with this node (one per node; glyph + word). */
+export declare function NodeContextMark({ node, pinned }: {
+    node: CanvasNodeState;
+    pinned: boolean;
+}): import("preact/src").JSX.Element | null;
+/** Pinned by an agent: the violet dot on the pin badge. */
+export declare function isAgentPin(nodeId: string): boolean;
+/**
+ * Near a pin (docs/design/NearPin.dc.html): a dotted pin-blue chip on an
+ * unpinned node the brief carries as title + short summary. Weaker than "in
+ * context" on purpose: the agent never gets this node's full content.
+ */
+export declare function NearPinMark({ node, pinned }: {
+    node: CanvasNodeState;
+    pinned: boolean;
+}): import("preact/src").JSX.Element | null;

package/dist/types/client/canvas/SessionReceipt.d.ts

@@ -3,7 +3,9 @@
  * at the canvas region's top-right after a session ends — what the session did
  * (items / done / vetoed), the pre-session snapshot (taken at attach, so View
  * diff shows the session's changes and a restore undoes them), and History
- * (the snapshots panel). Client-side state, cleared on dismiss.
+ * (the snapshots panel). Client-side state, cleared on dismiss (see
+ * applySessionReceipt for which endings show at all and how a burst merges
+ * into one card).
  */
 export interface DiffSummary {
     added: number;

package/dist/types/client/icons.d.ts

@@ -13,7 +13,6 @@ export declare function IconExpand(p: IconProps): JSX.Element;
 export declare function IconArrowLeft(p: IconProps): JSX.Element;
 export declare function IconRefresh(p: IconProps): JSX.Element;
 export declare function IconUndo(p: IconProps): JSX.Element;
-export declare function IconSparkle(p: IconProps): JSX.Element;
 /** Upload into a tray — attach a document. */
 export declare function IconUpload(p: IconProps): JSX.Element;
 /** Dropdown disclosure, sized like the other toolbar icons. */
@@ -50,7 +49,7 @@ export declare function IconSearch(p: IconProps): JSX.Element;
 export declare function IconShortcuts(p: IconProps): JSX.Element;
 /** Speech bubble — steer the agent (command bar composer). */
 export declare function IconSteer(p: IconProps): JSX.Element;
-/** Framed pin — context pinning. */
+/** Push pin — context pinning (docs/design/Chrome.dc.html). */
 export declare function IconPin(p: IconProps): JSX.Element;
 /** Focus Field — PMX Canvas brand mark (concentric rounded squares → lit core). */
 export declare function IconLogo({ size, class: className }: IconProps): JSX.Element;

package/dist/types/client/mcp-app/index.d.ts

@@ -0,0 +1 @@
+import '../uuid-polyfill';

package/dist/types/client/nodes/McpAppNode.d.ts

@@ -12,10 +12,11 @@ type ViewerFrameSource = {
  * white navigation paint. Two animation frames after load gives the new document
  * a composited paint before the old one is removed.
  */
-export declare function RefreshingViewerFrame({ source, iframeRef, onLoad, title, className, sandbox, allow, tabIndex, }: {
+export declare function RefreshingViewerFrame({ source, iframeRef, onLoad, onDocumentLoad, title, className, sandbox, allow, tabIndex, }: {
     source: ViewerFrameSource;
     iframeRef: RefObject<HTMLIFrameElement>;
     onLoad: () => void;
+    onDocumentLoad?: (frame: HTMLIFrameElement) => void;
     title: string;
     className?: string;
     sandbox?: string;

package/dist/types/client/nodes/ax-node-actions.d.ts

@@ -9,8 +9,8 @@ export declare function runNodeAxInteraction(node: CanvasNodeState, type: string
 export declare const axNodeActionButtonStyle: {
     readonly padding: "3px 8px";
     readonly fontSize: "10px";
-    readonly background: "var(--c-accent-12)";
-    readonly border: "1px solid var(--c-accent-25)";
+    readonly background: "color-mix(in srgb, var(--c-accent) 12%, transparent)";
+    readonly border: "1px solid color-mix(in srgb, var(--c-accent) 25%, transparent)";
     readonly borderRadius: "4px";
     readonly color: "var(--c-text-soft)";
     readonly cursor: "pointer";

package/dist/types/client/nodes/markdown-sanitize.d.ts

@@ -0,0 +1,2 @@
+/** Sanitize rendered Markdown before it enters the privileged workbench DOM. */
+export declare function sanitizeMarkdownHtml(html: string): string;

package/dist/types/client/nodes/use-workbench-asset.d.ts

@@ -0,0 +1,2 @@
+/** Asset bytes travel through the host, not a localhost URL in the user's browser. */
+export declare function useWorkbenchAsset(path: string): string | undefined;

package/dist/types/client/nodes/viewer-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare function restoreViewerRuntimeState(nodeId: string, token: string, source: Window): void;

package/dist/types/client/state/attention-store.d.ts

@@ -1,4 +1,3 @@
-import type { SemanticAttentionRegion } from '../../shared/semantic-attention.js';
 export type AttentionTone = 'context' | 'relationship' | 'group' | 'cluster' | 'neighborhood' | 'remove';
 export interface AttentionEntry {
     id: string;
@@ -10,16 +9,12 @@ export interface AttentionEntry {
 }
 export declare const attentionToast: import("@preact/signals-core").Signal<AttentionEntry | null>;
 export declare const attentionHistory: import("@preact/signals-core").Signal<AttentionEntry[]>;
-export declare const attentionPrimaryNodeIds: import("@preact/signals-core").Signal<Set<string>>;
-export declare const attentionSecondaryNodeIds: import("@preact/signals-core").Signal<Set<string>>;
-export declare const attentionRegions: import("@preact/signals-core").Signal<SemanticAttentionRegion[]>;
 export declare const attentionPulseNodeIds: import("@preact/signals-core").Signal<Set<string>>;
 export declare const attentionHistoryOpen: import("@preact/signals-core").Signal<boolean>;
 export declare const attentionHistoryUnread: import("@preact/signals-core").Signal<number>;
 export declare function resetAttentionState(): void;
 export declare function openAttentionHistory(): void;
 export declare function closeAttentionHistory(): void;
-export declare function setAttentionFocus(primaryNodeIds: string[], secondaryNodeIds: string[], regions: SemanticAttentionRegion[]): void;
 export declare function setAttentionToast(entry: AttentionEntry | null): void;
 export declare function pushAttentionHistory(entry: AttentionEntry, limit?: number): void;
 export declare function setAttentionPulse(nodeIds: string[]): void;

package/dist/types/client/state/canvas-store.d.ts

@@ -25,6 +25,8 @@ export declare const pendingExpandedNodeCloseId: import("@preact/signals-core").
 export declare const pendingConnection: import("@preact/signals-core").Signal<{
     from: string;
 } | null>;
+/** Invalidates in-flight interaction replies when board navigation resets the canvas. */
+export declare const canvasInteractionEpoch: import("@preact/signals-core").Signal<number>;
 export declare const draggingEdge: import("@preact/signals-core").Signal<{
     fromId: string;
     fromX: number;

package/dist/types/client/state/context-status-store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What agents did with the board's context (docs/design/AgentContext.dc.html):
+ * per node, the latest agent read of its content and the revision it read;
+ * per pin, who pinned it, when and why. Server truth from
+ * `GET /api/canvas/ax/context-status`, refetched when a read lands
+ * (`context-status-changed`), when pins change, and on (re)connect.
+ */
+export interface NodeReadStatus {
+    nodeId: string;
+    lastReadAt: string;
+    lastReadBy: string;
+    readRevision: number;
+    readCount: number;
+}
+export interface ContextPinMeta {
+    pinnedBy: {
+        actor: 'human' | 'agent' | 'system' | 'unknown';
+        source: string;
+        agentId?: string;
+    };
+    pinnedAt: string;
+    reason?: string;
+}
+interface ContextStatusResponse {
+    ok?: boolean;
+    boardId?: string | null;
+    nodes?: NodeReadStatus[];
+    pins?: Record<string, ContextPinMeta>;
+}
+export declare const nodeReadStatus: import("@preact/signals-core").Signal<Map<string, NodeReadStatus>>;
+export declare const contextPinMeta: import("@preact/signals-core").Signal<Record<string, ContextPinMeta>>;
+export declare function applyContextStatus(response: ContextStatusResponse): void;
+export declare function refreshContextStatus(): Promise<void>;
+/** How an agent's context relates to one pinned node — the mark its header shows. */
+export type PinnedReadState = {
+    kind: 'not-read';
+} | {
+    kind: 'read';
+    by: string;
+    at: string;
+    count: number;
+} | {
+    kind: 'changed';
+    by: string;
+    at: string;
+};
+export declare function pinnedReadState(nodeId: string, currentRevision: number): PinnedReadState;
+/** Display name for an attributed writer: its agent id, else its transport label. */
+export declare function writerName(actor: {
+    source: string;
+    agentId?: string;
+}): string;
+export {};

package/dist/types/client/state/intent-bridge.d.ts

@@ -84,7 +84,7 @@ export declare function pushCanvasUpdate(updates: Array<{
 }>, options?: {
     recordHistory?: boolean;
 }): Promise<void>;
-/** Create a canvas edge via the server. */
+/** Render the server-confirmed edge immediately, without waiting for SSE/polling. */
 export declare function createEdgeFromClient(from: string, to: string, type: string, label?: string): Promise<{
     ok: boolean;
     id?: string;
@@ -120,9 +120,12 @@ export declare function updateNodeFromClient(id: string, patch: {
     data?: Record<string, unknown>;
     /** Groups: replace the membership list (positions preserved). */
     children?: string[];
+    expectedContentRevision?: number;
+    expectedBoardId?: string | null;
 }): Promise<{
     ok: boolean;
     id?: string;
+    contentRevision?: number;
 }>;
 /** Refresh a webpage node from its persisted URL on the server. */
 export declare function refreshWebpageNodeFromClient(id: string, url?: string): Promise<{

package/dist/types/client/state/near-pin-store.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Near a pin (docs/design/NearPin.dc.html): each pinned node pulls up to five
+ * unpinned nodes within 600 px into the agent's brief as title + short
+ * summary. Same rule as the server's brief (`findNeighborhoods`), so the mark
+ * claims exactly what the agent receives.
+ */
+export interface NearPin {
+    pinNodeId: string;
+    pinTitle: string;
+}
+/**
+ * Unpinned node id → the pins it is near, nearest first. Every drag frame
+ * moves a node, so the result keeps its identity while no node's set of pins
+ * changes: the chips subscribed to it re-render only when a neighbourhood does.
+ */
+export declare const nearPins: import("@preact/signals-core").ReadonlySignal<Map<string, NearPin[]>>;

package/dist/types/client/state/presence-store.d.ts

@@ -17,6 +17,11 @@ export declare const activityFeedOpen: import("@preact/signals-core").Signal<boo
 export declare const writersSheetOpen: import("@preact/signals-core").Signal<boolean>;
 /** Feed filter: a writer's sessionId, or null for all. */
 export declare const activityFilter: import("@preact/signals-core").Signal<string | null>;
+/**
+ * A writer's colour says what it is, not who: agents take the agent violet,
+ * subagents (fleet workers) the subagent fuchsia. Writers are told apart by
+ * name and initial (docs/design.md, "Kinds carry no colour").
+ */
 export declare function writerColor(sessionId: string): string;
 /** Avatar initial: first letter of the label, upper-cased. */
 export declare function writerInitial(label: string): string;

package/dist/types/client/state/session-store.d.ts

@@ -155,12 +155,13 @@ export declare function endSession(session: {
     agentId: string | null;
 }): Promise<boolean>;
 export interface SessionReceipt {
-    label: string;
+    /** Distinct labels of the sessions on this card (one unless merged). */
+    labels: string[];
+    /** Endings folded into this card (see applySessionReceipt). */
+    sessions: number;
     endedAt: string;
     /** Why it ended — the receipt should answer this, not leave the human asking. */
     endedBy?: 'human' | 'agent' | 'idle-timeout';
-    /** The session changed nothing on the board (its pre-session snapshot was dropped). */
-    unchanged?: boolean;
     /** Cancelled (withdrawn items), rejected (human's explicit no on a gate), and
      * held (TTL expired unanswered) are three different outcomes — never one
      * "vetoed" pile. */
@@ -171,13 +172,42 @@ export interface SessionReceipt {
         rejected: number;
         held: number;
     };
+    /** The pre-session snapshot; null when the board was empty at attach, or on a
+     * merged receipt (each session's snapshot is in History). */
     snapshot: {
         id: string;
         name: string;
     } | null;
+    /** What the session did with context (docs/design/AgentContext.dc.html receipt). */
+    context: SessionContextActivity;
+}
+export interface ReceiptNode {
+    id: string;
+    title: string;
+    reason?: string;
+}
+export interface SessionContextActivity {
+    read: ReceiptNode[];
+    pinned: ReceiptNode[];
+    created: ReceiptNode[];
+    edited: ReceiptNode[];
+    changedSinceRead: ReceiptNode[];
 }
+/**
+ * The agent-activity lens: while on, nodes the last session did not touch
+ * (read, pin, create, edit) are dimmed. Null when off.
+ */
+export declare const activityLensNodeIds: import("@preact/signals-core").Signal<Set<string> | null>;
+export declare function setActivityLens(on: boolean): void;
 /** The last ended session's receipt (design item 2); client-side, cleared on dismiss. */
 export declare const sessionReceipt: import("@preact/signals-core").Signal<SessionReceipt | null>;
+/**
+ * The receipt rule: a pop-up only for a top-level session that changed the
+ * board or read/pinned context. `unchanged` endings and worker endings
+ * (`parentAgentId` set — their orchestrator's receipt covers the board since
+ * it attached) stay in the timeline and History only, and never replace or
+ * extend an open receipt. Qualifying endings while one is up merge into it.
+ */
 export declare function applySessionReceipt(data: Record<string, unknown>): void;
 export declare function dismissSessionReceipt(): void;
 export declare function resetSessionStore(): void;

package/dist/types/client/state/workbench-transport.d.ts

@@ -0,0 +1,16 @@
+/** The normal workbench uses HTTP; an MCP App installs its host transport before mounting. */
+type WorkbenchFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export declare function installWorkbenchTransport(transport: WorkbenchFetch | undefined): void;
+export declare function isHostedWorkbench(): boolean;
+export declare const workbenchFetch: WorkbenchFetch;
+type WorkbenchDownload = (file: {
+    name: string;
+    mimeType: string;
+    text: string;
+}) => Promise<{
+    isError?: boolean;
+}>;
+export declare function installWorkbenchDownload(download: WorkbenchDownload | undefined): void;
+/** Export files live on PMX, not on the embedded frame's sandbox origin. */
+export declare function downloadWorkbenchExport(path: string): Promise<void>;
+export {};

package/dist/types/client/theme/tokens.d.ts

@@ -11,10 +11,8 @@ export interface CanvasTokens {
     accent: string;
     ok: string;
     warn: string;
-    warnAlt: string;
     danger: string;
-    purple: string;
-    thinking: string;
+    agent: string;
     subagent: string;
     font: string;
     mono: string;

package/dist/types/client/types.d.ts

@@ -18,8 +18,17 @@ export interface CanvasNodeState {
     zIndex: number;
     collapsed: boolean;
     pinned: boolean;
+    contentRevision?: number;
+    /** Who created / last edited the node's content (server attribution). */
+    createdBy?: NodeActor;
+    lastEditedBy?: NodeActor;
     data: Record<string, unknown>;
 }
+export interface NodeActor {
+    actor: 'human' | 'agent' | 'system' | 'unknown';
+    source: string;
+    agentId?: string;
+}
 export interface CanvasEdge {
     id: string;
     from: string;

package/dist/types/json-render/renderer/index.d.ts

@@ -5,7 +5,7 @@
  * Runs inside a pmx-canvas iframe and reads the normalized json-render spec
  * from an inline global injected by the server-side viewer route.
  */
-import type { Spec } from '@json-render/core';
+import { type Spec } from '@json-render/core';
 declare global {
     interface Window {
         __PMX_CANVAS_JSON_RENDER_SPEC__?: Spec & {
@@ -17,5 +17,6 @@ declare global {
         __PMX_CANVAS_JSON_RENDER_NODE_ID__?: string;
         __PMX_CANVAS_AX_TOKEN__?: string;
         __PMX_CANVAS_AX_STATE__?: unknown;
+        __PMX_CANVAS_UI_STATE_TOKEN__?: string;
     }
 }

package/dist/types/json-render/server.d.ts

@@ -66,7 +66,7 @@ export type GraphChartType = 'LineChart' | 'BarChart' | 'PieChart' | 'AreaChart'
 export declare function escapeInlineScriptSource(source: string): string;
 export declare function inferJsonRenderNodeTitle(spec: JsonRenderSpec, fallback?: string): string;
 export declare function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpec;
-/** shadcn 0.21 ignores these props unless the renderer supplies a two-way binding. */
+/** Binding-only form props that normalization could not bind (see bindLiteralFormValues). */
 export declare function jsonRenderFormWarnings(spec: JsonRenderSpec): string[];
 export declare function normalizeGraphType(value: string): GraphChartType;
 export declare function buildGraphSpec(input: GraphNodeInput): JsonRenderSpec;
@@ -101,6 +101,8 @@ export declare function buildJsonRenderViewerHtml(options: {
     nodeId?: string;
     axToken?: string;
     axState?: unknown;
+    /** Independent nonce for tab-local runtime state across focus transitions. */
+    stateToken?: string;
     /** Nonce for the content-height reporter so the node can grow to fit the chart. */
     frameToken?: string;
     /** When true, charts render at their natural (intrinsic) height instead of

package/dist/types/mcp/app-server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** Private, single-workspace profile. No public HTTP listener or tenant routing. */
+export declare function createCanvasAppServer(): McpServer;

package/dist/types/mcp/canvas-access.d.ts

@@ -88,5 +88,5 @@ export declare function shouldAttachToExistingDaemon(occupant: {
  * FS-safe (defaults to false on any error).
  */
 export declare function looksLikeIncidentalCwd(cwd: string): boolean;
-export declare function createCanvasAccess(): Promise<CanvasAccess>;
+export declare function createCanvasAccess(allowExternalMcp?: boolean): Promise<CanvasAccess>;
 export {};

package/dist/types/mcp/canvas-app.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CanvasAccess } from './canvas-access.js';
+/** Focused app profile; deliberately does not register the general-purpose composites. */
+export declare function registerCanvasApp(server: McpServer, ensureCanvas: () => Promise<CanvasAccess>): void;

package/dist/types/mcp/workbench-app.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CanvasAccess } from './canvas-access.js';
+/** HTTP-shaped replies let the real workbench retain its existing API contracts. */
+export declare function registerWorkbenchApp(server: McpServer, ensureCanvas: () => Promise<CanvasAccess>): void;

package/dist/types/server/agent-presence.d.ts

@@ -99,7 +99,7 @@ export declare function estimateContextBudget(): ContextBudget;
 /** Returns the id of the pre-session snapshot the server took, if any. */
 type SessionStartListener = (presence: AgentPresence) => string | null;
 export type SessionEndReason = 'human' | 'agent' | 'idle-timeout';
-type SessionEndListener = (presence: AgentPresence, startSnapshotId: string | null, endedBy: SessionEndReason) => void;
+type SessionEndListener = (presence: AgentPresence, startSnapshotId: string | null, endedBy: SessionEndReason, startedAt: string | null) => void;
 export declare class AgentPresenceRegistry {
     private readonly presences;
     /** Newest first; bounded. Survives a writer fading — the feed is history, the writer list is presence. */

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

@@ -1,6 +1,6 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import type { AxApprovalStatus, AxEventKind, AxWorkItemStatus } from '../shared/ax-kinds.js';
-import type { AgentContextNode } from './agent-context.js';
+import type { AgentContextNode } from '../shared/agent-context.js';
 import type { ActorAttribution } from './attribution.js';
 export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
 export interface PmxAxFocusState {

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

@@ -5,6 +5,7 @@
  * WAL-mode persistence. Replaces the previous JSON file-based approach.
  */
 import { Database } from 'bun:sqlite';
+import type { ActorAttribution } from './attribution.js';
 import { type Tour } from '../shared/tour.js';
 import { type CanvasThemeName } from '../shared/themes.js';
 import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, CanvasSnapshot, CanvasSnapshotListOptions, ViewportState } from './canvas-state.js';
@@ -20,9 +21,16 @@ export interface PersistedCanvasState {
     edges: CanvasEdge[];
     annotations?: CanvasAnnotation[];
     contextPins: string[];
+    /** Who pinned each context pin, when and why; pins without an entry have an unknown pinner. */
+    contextPinMeta?: Record<string, ContextPinMeta>;
     ax?: PmxAxState;
     revisionState?: PersistedRevisionState;
 }
+export interface ContextPinMeta {
+    pinnedBy: ActorAttribution;
+    pinnedAt: string;
+    reason?: string;
+}
 export interface PersistedRevisionState {
     revision: number;
     floor: number;

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

@@ -0,0 +1,25 @@
+import type { CanvasNodeState, CanvasNodeUpdate } from './canvas-state.js';
+/** Flat fields take precedence over nested aliases; absent axes remain absent. */
+export declare function resolveCreateGeometry(body: Record<string, unknown>): {
+    x: number | undefined;
+    y: number | undefined;
+    width: number | undefined;
+    height: number | undefined;
+};
+/** Guards and PATCH execution must resolve aliases and single-axis moves identically. */
+export declare function resolvePatchGeometry(body: Record<string, unknown>, existing: CanvasNodeState): {
+    size?: {
+        width: number;
+        height: number;
+    } | undefined;
+    position?: {
+        x: number;
+        y: number;
+    } | undefined;
+};
+export declare function validateCanvasNodePatch(patch: {
+    position?: unknown;
+    size?: unknown;
+}): string | null;
+/** Invalid patches cannot count as explicit child-position overrides. */
+export declare function validCanvasNodeUpdates(input: unknown): CanvasNodeUpdate[];

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

@@ -130,16 +130,6 @@ export declare function syncCanvasRuntimeBackends(options?: {
     rehydrated: number;
     failed: number;
 }>;
-export declare function validateCanvasNodePatch(patch: {
-    position?: {
-        x: number;
-        y: number;
-    };
-    size?: {
-        width: number;
-        height: number;
-    };
-}): string | null;
 export declare function mergeTraceNodeDataFields(base: Record<string, unknown>, input: Record<string, unknown>): Record<string, unknown>;
 export declare function hasTraceNodeDataFields(input: Record<string, unknown>): boolean;
 export declare function scheduleCodeGraphRecompute(onComplete?: () => void): void;
@@ -189,7 +179,7 @@ export declare function applyCanvasNodeUpdates(updates: CanvasNodeUpdate[]): {
     applied: number;
     skipped: number;
 };
-export declare function setCanvasContextPins(nodeIds: string[], mode?: CanvasPinMode): {
+export declare function setCanvasContextPins(nodeIds: string[], mode?: CanvasPinMode, reason?: string): {
     count: number;
     nodeIds: string[];
 };

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

@@ -12,11 +12,11 @@
  * the one-shot boot migration into SQLite was retired.
  */
 import { type Tour } from '../shared/tour.js';
-import { type CanvasBoard, type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
+import { type CanvasBoard, type ContextPinMeta, type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
 import { type DocumentImport, type DocumentImportStatus, type ImportSection, type Attachment } from './document-import.js';
 import { type PmxAxActivityKind, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
 import { type ActorAttribution } from './attribution.js';
-import { type ContextRead, type ContextReadConsumerSummary, type ContextReadInput } from './context-reads.js';
+import { type ContextRead, type ContextReadConsumerSummary, type ContextReadInput, type NodeReadStatus } from './context-reads.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
 export interface PersistedBlobRef {
     __pmxCanvasBlob: 'v1';
@@ -171,6 +171,8 @@ declare class CanvasStateManager {
     private _tour;
     private _theme;
     private _contextPinnedNodeIds;
+    /** Who pinned each pin, when and why; kept only for ids in `_contextPinnedNodeIds`. */
+    private _contextPinMeta;
     private _workspaceRoot;
     private _contentRevision;
     private _revisionFloor;
@@ -185,12 +187,15 @@ declare class CanvasStateManager {
      */
     onChange(cb: (type: CanvasChangeType) => void): () => void;
     private _workItemsChangedListener;
+    /** Single slot (architecture rule 8): server.ts tells the workbench a read landed. Never MCP. */
+    private _contextReadListener;
     /**
      * Register THE work-item change listener (single slot, last-write-wins).
      * Fired after addWorkItem/updateWorkItem completes (including the node
      * status mirror), so live views like the workboard can rebuild from the
      * fresh work-item list.
      */
+    setContextReadListener(listener: ((boardId: string | null) => void) | null): void;
     setWorkItemsChangedListener(listener: (() => void) | null): void;
     private notifyWorkItemsChanged;
     private notifyChange;
@@ -609,6 +614,12 @@ declare class CanvasStateManager {
     getAxTimelineSummary(): PmxAxTimelineSummary;
     /** Records one agent context read (diagnostics; never notifies, so a read cannot trigger reads). */
     recordContextRead(input: ContextReadInput, boardId?: string | null): ContextRead | null;
+    /** The delivered ids that are nodes on the read board, each with its content revision now. */
+    private readRevisions;
+    /** Per node on a board, the latest agent read that delivered its content. */
+    getNodeReadStatus(boardId?: string | null): NodeReadStatus[];
+    /** Nodes on a board whose content an agent read at or after `since` (ISO). */
+    getReadNodeIdsSince(boardId: string | null, since: string): string[];
     getContextReads(limit?: number): {
         reads: ContextRead[];
         summary: ContextReadConsumerSummary[];
@@ -619,7 +630,18 @@ declare class CanvasStateManager {
         steering: PmxAxSteeringMessage[];
         summary: PmxAxTimelineSummary;
     };
-    setContextPins(nodeIds: string[]): void;
+    /**
+     * Replace the pin set. Newly pinned nodes are attributed to the current
+     * actor (with `reason` when given); pins that stay keep their attribution.
+     * `restore` re-applies saved attribution, so undo does not re-attribute.
+     */
+    setContextPins(nodeIds: string[], options?: {
+        reason?: string;
+        restore?: Map<string, ContextPinMeta>;
+    }): void;
+    /** Who pinned each current pin, when and why (pins with an unknown pinner are absent). */
+    getContextPinMeta(): Record<string, ContextPinMeta>;
+    private pinMetaRecord;
     clearContextPins(): void;
     /** Move child nodes into a group. Sets data.parentGroup on children and data.children on the group. */
     groupNodes(groupId: string, childIds: string[], options?: GroupNodesOptions): boolean;

package/dist/types/server/context-brief.d.ts

@@ -1,5 +1,7 @@
 import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
-export type ContextBriefReason = 'pinned' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+export type ContextBriefReason = 'pinned' | 'near' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+/** A near entry carries a short summary, never full content: pin the node to send that. */
+export declare const NEAR_SUMMARY_LENGTH = 280;
 export interface ContextBriefSourceEntry {
     sourceBoardId: string;
     nodeId: string;
@@ -57,6 +59,11 @@ export interface CompiledContextEntry {
     text: string;
     /** A linked board's pin title is discovery metadata, not delivery of that pinned card. */
     titleOnly?: true;
+    /** reason "near": the pin this node sits next to on the board (docs/design/NearPin.dc.html). */
+    near?: {
+        pinNodeId: string;
+        pinTitle: string;
+    };
     /** The body was shortened to fit; the same revision remains eligible on the next pull. */
     truncated?: true;
     provenance?: {