pmx-canvas 0.10.0 → 0.12.0

package/src/server/tour-control.ts

@@ -8,26 +8,88 @@
  *
  * This module must never import server.ts or index.ts.
  */
-import { derivedTour, resolveStop, tourStopSchema, type Camera, type Tour, type TourStop } from '../shared/tour.js';
-import { canvasState } from './canvas-state.js';
+import {
+  derivedTour,
+  resolveStop,
+  tourPresenterSchema,
+  tourStopSchema,
+  type Camera,
+  type Tour,
+  type TourPresenter,
+  type TourStop,
+} from '../shared/tour.js';
+import { boardCatalogEpoch, canvasState } from './canvas-state.js';
 import { getClientViewportSize } from './canvas-operations.js';
 import { OperationError } from './operations/types.js';
+import { createBoardLocal } from './board-local.js';
 
 export type TourStep = number | 'next' | 'previous';
 
-export interface TourStepResult {
+export interface TourDelivery {
+  catalogEpoch: string;
+  boardGeneration: number;
+  sequence: number;
+}
+
+export interface TourStepResult extends TourDelivery {
   index: number;
   total: number;
   stop: TourStop;
 }
 
+export interface TourSuperseded {
+  superseded: true;
+}
+
 export interface TourState {
   tour: Tour;
   derived: boolean;
   position: number | null;
 }
 
-let cursor: { boardGeneration: number; tour: string; index: number } | null = null;
+const boardTour = createBoardLocal(() => ({
+  cursor: null as { boardGeneration: number; viewGeneration: number; tour: string; index: number } | null,
+  presenterGeneration: -1,
+  presenterIntents: new Map<string, number>(),
+}));
+// One order for both HTTP acknowledgements and event delivery in this server run.
+let sequence = 0;
+
+function claimPresenter(presenter: TourPresenter | undefined): boolean {
+  if (presenter === undefined) return true;
+  const state = boardTour.current;
+  const { presenterIntents } = state;
+  const { clientId, intent, catalogEpoch, boardGeneration } = tourPresenterSchema.parse(presenter);
+  if (
+    canvasState.isBackgroundBoard ||
+    catalogEpoch !== boardCatalogEpoch ||
+    boardGeneration !== canvasState.visibleBoardGeneration
+  )
+    return false;
+  if (state.presenterGeneration !== boardGeneration) {
+    presenterIntents.clear();
+    state.presenterGeneration = boardGeneration;
+  }
+  const previous = presenterIntents.get(clientId);
+  if (previous !== undefined && intent <= previous) return false;
+  // Never evict an identity: that would make its delayed requests valid again.
+  if (previous === undefined && presenterIntents.size >= 4096)
+    throw new OperationError(
+      'Too many presentation documents on this board activation. Reopen the board to continue.',
+      409,
+    );
+  // Even a later invalid stop supersedes older commands. Claim before resolving it.
+  presenterIntents.set(clientId, intent);
+  return true;
+}
+
+function nextDelivery(): TourDelivery {
+  return {
+    catalogEpoch: boardCatalogEpoch,
+    boardGeneration: canvasState.isBackgroundBoard ? canvasState.boardGeneration : canvasState.visibleBoardGeneration,
+    sequence: ++sequence,
+  };
+}
 
 export function currentTour(): TourState {
   const saved = canvasState.getTour();
@@ -37,14 +99,23 @@ export function currentTour(): TourState {
 
 /** The stop the tour is on for the active board, or null when not touring. */
 function tourPosition(tour: Tour): number | null {
-  if (cursor && (cursor.boardGeneration !== canvasState.boardGeneration || cursor.tour !== JSON.stringify(tour))) {
-    cursor = null;
+  const { cursor } = boardTour.current;
+  if (
+    cursor &&
+    (cursor.boardGeneration !== canvasState.boardLifetimeGeneration ||
+      (!canvasState.isBackgroundBoard && cursor.viewGeneration !== canvasState.visibleBoardGeneration) ||
+      cursor.tour !== JSON.stringify(tour))
+  ) {
+    boardTour.current.cursor = null;
   }
-  return cursor?.index ?? null;
+  return boardTour.current.cursor?.index ?? null;
 }
 
 /** Move the shared cursor. `next`/`previous` clamp at the ends; an explicit index must exist. */
-export function goToTourStop(step: TourStep): TourStepResult {
+export function goToTourStop(step: TourStep): TourStepResult;
+export function goToTourStop(step: TourStep, presenter: TourPresenter | undefined): TourStepResult | TourSuperseded;
+export function goToTourStop(step: TourStep, presenter?: TourPresenter): TourStepResult | TourSuperseded {
+  if (!claimPresenter(presenter)) return { superseded: true };
   const { tour, position: at } = currentTour();
   const { stops } = tour;
   if (stops.length === 0) {
@@ -55,12 +126,26 @@ export function goToTourStop(step: TourStep): TourStepResult {
   else if (step === 'previous') index = at === null ? 0 : Math.max(0, Math.min(stops.length - 1, at - 1));
   else if (Number.isInteger(step) && step >= 0 && step < stops.length) index = step;
   else throw new OperationError(`Tour stop ${step} does not exist (stops 0–${stops.length - 1}).`, 400);
-  cursor = { boardGeneration: canvasState.boardGeneration, tour: JSON.stringify(tour), index };
-  return { index, total: stops.length, stop: stops[index] as TourStop };
+  boardTour.current.cursor = {
+    boardGeneration: canvasState.boardLifetimeGeneration,
+    viewGeneration: canvasState.visibleBoardGeneration,
+    tour: JSON.stringify(tour),
+    index,
+  };
+  return {
+    ...nextDelivery(),
+    index,
+    total: stops.length,
+    stop: stops[index] as TourStop,
+  };
 }
 
-export function exitTour(): void {
-  cursor = null;
+export function exitTour(): TourDelivery;
+export function exitTour(presenter: TourPresenter | undefined): TourDelivery | TourSuperseded;
+export function exitTour(presenter?: TourPresenter): TourDelivery | TourSuperseded {
+  if (!claimPresenter(presenter)) return { superseded: true };
+  boardTour.current.cursor = null;
+  return nextDelivery();
 }
 
 /**

package/src/server/trace-manager.ts

@@ -72,6 +72,10 @@ class TraceManager {
     return this._enabled;
   }
 
+  get ownedNodeIds(): readonly string[] {
+    return this.traceNodeIds;
+  }
+
   setEnabled(value: boolean): void {
     this._enabled = value;
     if (value) {

package/src/server/web-artifacts/scripts/init-artifact.sh

@@ -146,8 +146,8 @@ fi
 
 echo "🚀 Creating new React + Vite project: $PROJECT_NAME"
 
-# Create new Vite project (always use latest create-vite, pin vite version later)
-run_pnpm_quiet create vite "$PROJECT_NAME" --template react-ts --no-interactive
+# 9.3.2 shipped without templates; keep scaffolding on the verified complete package.
+run_pnpm_quiet create vite@9.3.1 "$PROJECT_NAME" --template react-ts --no-interactive
 
 # Navigate into project directory
 cd "$PROJECT_NAME"

package/src/shared/agent-context.ts

@@ -374,8 +374,14 @@ export function summarizeNodeForAgentContext(node: CanvasNodeState, options: Age
       return truncateContextText(`${prefix}${fileContent}`, defaultTextLength);
     }
     case 'status':
+      if (typeof node.data.workItemId === 'string') {
+        return truncateContextText(
+          `Read-only live task: ${node.data.workItemId}\n${node.data.liveWorkAvailable === false ? 'Task unavailable' : textFields(node.data, ['title', 'workState', 'detail', 'liveWorkSource'])}`,
+          defaultTextLength,
+        );
+      }
       return truncateContextText(
-        `Status: ${textFields(node.data, ['phase']) || textFields(node.data, ['content']) || textFields(node.data, ['status']) || 'unknown'}\n${textFields(node.data, ['detail', 'message', 'activeTool'])}`,
+        `Status: ${textFields(node.data, ['workState']) || textFields(node.data, ['phase']) || textFields(node.data, ['content']) || textFields(node.data, ['status']) || 'unknown'}\n${textFields(node.data, ['detail', 'message', 'activeTool'])}${typeof node.data.progress === 'number' ? `\nProgress: ${node.data.progress}%` : ''}`,
         defaultTextLength,
       );
     case 'context':

package/src/shared/auto-arrange.ts

@@ -463,10 +463,11 @@ export function computeAutoArrange(
   const { outgoing, undirected, indegree, outdegree } = buildUnitGraphs(units, nodeToUnit, allEdges);
   const clusters = collectSpatialClusters(units, undirected);
   const absoluteUnitPositions = new Map<string, ArrangePosition>();
-  // Already-packed cluster rects: a cluster that grew past its old bounds is
-  // shifted below earlier clusters instead of overlapping them. Clusters are
-  // processed top-left first, so the cascade is deterministic.
-  const packedRects: Array<ArrangePosition & ArrangeSize> = [];
+  // Reserve fixed cards as well as already-packed clusters. A growing cluster
+  // shifts below blockers without moving pinned cards or splitting its groups.
+  const packedRects: Array<ArrangePosition & ArrangeSize> = allNodes
+    .filter((node) => node.pinned)
+    .map((node) => ({ ...node.position, ...node.size }));
 
   for (const clusterUnits of clusters) {
     const components = collectComponents(clusterUnits, undirected).map((component) =>

package/src/shared/ax-kinds.ts

@@ -5,6 +5,19 @@
  */
 export type AxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
 
+/** Authored work cards use the task vocabulary without creating an AX task. */
+export const WORK_CARD_STATES: Record<AxWorkItemStatus, { label: string; glyph: string }> = {
+  todo: { label: 'To do', glyph: '○' },
+  'in-progress': { label: 'In progress', glyph: '◐' },
+  blocked: { label: 'Blocked', glyph: '⧗' },
+  done: { label: 'Done', glyph: '✓' },
+  cancelled: { label: 'Cancelled', glyph: '×' },
+};
+
+export function isWorkCardState(value: unknown): value is AxWorkItemStatus {
+  return typeof value === 'string' && Object.hasOwn(WORK_CARD_STATES, value);
+}
+
 /** `held` = auto-held by the unattended-approval policy: the action did NOT proceed. */
 export type AxApprovalStatus = 'pending' | 'approved' | 'rejected' | 'held';
 

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

@@ -21,13 +21,24 @@ 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';
+/** MCP apps share their window channel with an SDK JSON-RPC transport. */
+export const MCP_SURFACE_METHOD = 'notifications/pmx/surface';
 
-/**
- * Parent→ext-app paint probe (Finding N): the parent asks the app document to
- * answer with a double-rAF `paint-tick` beacon. A frame whose rendering
- * pipeline is live answers within a frame or two; silence past the timeout is
- * the paint-fail signal that drives the recovery ladder.
- */
-export const EXT_APP_PAINT_PROBE_SOURCE = 'pmx-canvas-ext-app-paint-probe';
+export function surfaceNotification(params: Record<string, unknown>) {
+  return { jsonrpc: '2.0' as const, method: MCP_SURFACE_METHOD, params };
+}
+
+export function readSurfaceNotification(message: unknown): unknown {
+  if (
+    message &&
+    typeof message === 'object' &&
+    'jsonrpc' in message &&
+    message.jsonrpc === '2.0' &&
+    'method' in message &&
+    message.method === MCP_SURFACE_METHOD &&
+    !('id' in message) &&
+    'params' in message
+  )
+    return message.params;
+  return null;
+}

package/src/shared/content-height-reporter.ts

@@ -22,11 +22,12 @@ export function sanitizeFrameToken(token: string): string {
 export function contentHeightReporterSource(frameToken: string): string {
   const token = JSON.stringify(sanitizeFrameToken(frameToken));
   return (
-    `(function(){var T=${token};var last=0,timer=null;` +
+    `(function(){var T=${token};var last=0,lastViewport=0,timer=null;` +
     `function m(){var d=document.documentElement;return Math.max(d?d.scrollHeight:0,document.body?document.body.scrollHeight:0);}` +
-    `function r(){var h=m();if(Math.abs(h-last)<=4)return;last=h;window.parent.postMessage({source:'pmx-canvas-frame',type:'content-height',token:T,height:h},'*');}` +
+    `function r(force){var h=m(),v=window.innerHeight;if(!force&&Math.abs(h-last)<=4&&v===lastViewport)return;last=h;lastViewport=v;window.parent.postMessage({source:'pmx-canvas-frame',type:'content-height',token:T,height:h},'*');}` +
     `function s(){if(timer)return;timer=setTimeout(function(){timer=null;r();},100);}` +
-    `if(document.readyState!=='loading')s();window.addEventListener('load',s,true);` +
+    `window.addEventListener('message',function(e){var d=e.data;if(e.source===window.parent&&d&&d.source==='pmx-canvas-frame'&&d.type==='measure-content'&&d.token===T)r(true);});` +
+    `if(document.readyState!=='loading')s();window.addEventListener('load',s,true);window.addEventListener('resize',s);` +
     `try{new ResizeObserver(s).observe(document.documentElement);}catch(e){}` +
     `new MutationObserver(s).observe(document.documentElement,{subtree:true,childList:true,characterData:true,attributes:true});` +
     `if(document.fonts)document.fonts.ready.then(s);setTimeout(s,60);})();`

package/src/shared/human-presence.ts

@@ -21,6 +21,7 @@ export interface HumanPresenceSnapshot {
   humans: HumanPresence[];
 }
 
+export const HUMAN_NAME_MAX_LENGTH = 40;
 /** A tab that stops reporting is gone after this. */
 export const HUMAN_PRESENCE_TTL_MS = 30_000;
 /** A grab the tab stops renewing (crash, tab closed mid-drag) releases after this. */

package/src/shared/lifecycle-status.ts

@@ -21,6 +21,8 @@ export interface LifecycleQualification {
   contentChangedAt: string | null;
   /** The revisions a validating reviewer must have inspected, qualified by source relation. */
   observations: Record<string, number | null>;
+  /** Warnings keyed by the same qualified source identity as observations. */
+  sourceWarnings?: Record<string, string[]>;
   sources: SourceQualification[];
   relevance: 'card-pinned' | 'board-pinned' | 'not-selected';
 }

package/src/shared/tour.ts

@@ -21,6 +21,14 @@ export const tourStopSchema = z.object({
   pullback: z.number().min(0).max(4).optional(),
 });
 export const tourSchema = z.object({ stops: z.array(tourStopSchema).max(1000) });
+/** Latest intent from one document, scoped to the server's board activation. */
+export const tourPresenterSchema = z.object({
+  clientId: z.string().min(1).max(128),
+  intent: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  catalogEpoch: z.string().min(1).max(128),
+  boardGeneration: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+});
+export type TourPresenter = z.infer<typeof tourPresenterSchema>;
 export type Tour = z.infer<typeof tourSchema>;
 export type TourStop = z.infer<typeof tourStopSchema>;
 export type Camera = z.infer<typeof cameraSchema>;