@canvas-harness/core 0.0.2 → 0.0.3

package/dist/index.d.cts

@@ -227,6 +227,14 @@ type Scene = {
     groups: Record<GroupId, Group>;
     camera: CameraState;
     selection: (NodeId | EdgeId)[];
+    /**
+     * Presentation order for frame-typed nodes. Auto-maintained by the
+     * store on `node.add` / `node.remove`; explicitly mutated via
+     * `setFrameOrder` (which emits a `frame.reorder` op). Optional for
+     * backward compat — missing on older saved scenes is treated as [].
+     * See ARCHITECTURE.md §3.7 frames.
+     */
+    frameOrder?: NodeId[];
 };
 /**
  * On-the-wire serialized form. Arrays gzip smaller and have predictable iteration order.
@@ -239,6 +247,7 @@ type SerializedScene = {
     groups: Group[];
     camera: CameraState;
     selection: (NodeId | EdgeId)[];
+    frameOrder?: NodeId[];
 };
 
 /**
@@ -276,6 +285,10 @@ type Op = {
 } | {
     type: 'group.remove';
     group: Group;
+} | {
+    type: 'frame.reorder';
+    ids: NodeId[];
+    prev: NodeId[];
 };
 /**
  * A batch is the atomic unit of mutation (also the unit of undo/redo and sync).
@@ -1644,6 +1657,26 @@ interface CanvasStore {
     getEdgeCount(): number;
     /** O(1) count. */
     getGroupCount(): number;
+    /**
+     * Returns frame nodes (`type === 'frame'`) in presentation order.
+     * Order is auto-maintained on add/remove and can be explicitly
+     * mutated via {@link CanvasStore.setFrameOrder}. Used by present
+     * mode + export to drive slide sequencing.
+     */
+    getFrames(): Node[];
+    /**
+     * Replace the presentation order of frames. `ids` must be a
+     * permutation of the current frame ids (any unknown ids are
+     * dropped; missing frames are appended to preserve invariants).
+     * Emits a `frame.reorder` op; undoable, syncs over collab.
+     */
+    setFrameOrder(ids: NodeId[]): void;
+    /**
+     * Geometric containment query: returns all non-frame nodes whose
+     * AABB is fully inside the given frame's AABB. Used to compute
+     * "what's on this slide". Cheap — backed by the spatial index.
+     */
+    getNodesInFrame(id: NodeId): Node[];
     /**
      * Spatial query — ids of nodes + edges that intersect a rect or
      * contain a point. Backed by a uniform grid for sub-millisecond
@@ -2055,6 +2088,12 @@ type Renderer = {
     setBackground(bg: CanvasBackground | undefined): void;
     /** Update the selection chrome color. Triggers an interactive repaint. */
     setSelectionColor(color: string): void;
+    /**
+     * Toggle frame-node paint. Use during a presentation flow to drop
+     * the slide border + label so only the frame contents are visible.
+     * Triggers a static repaint.
+     */
+    setHideFrames(hidden: boolean): void;
     /** Per-frame timing (FPS, lastMs, avgMs, frames). */
     stats(): FrameStats;
     /** Number of items the most recent paint actually drew. */

package/dist/index.d.ts

@@ -227,6 +227,14 @@ type Scene = {
     groups: Record<GroupId, Group>;
     camera: CameraState;
     selection: (NodeId | EdgeId)[];
+    /**
+     * Presentation order for frame-typed nodes. Auto-maintained by the
+     * store on `node.add` / `node.remove`; explicitly mutated via
+     * `setFrameOrder` (which emits a `frame.reorder` op). Optional for
+     * backward compat — missing on older saved scenes is treated as [].
+     * See ARCHITECTURE.md §3.7 frames.
+     */
+    frameOrder?: NodeId[];
 };
 /**
  * On-the-wire serialized form. Arrays gzip smaller and have predictable iteration order.
@@ -239,6 +247,7 @@ type SerializedScene = {
     groups: Group[];
     camera: CameraState;
     selection: (NodeId | EdgeId)[];
+    frameOrder?: NodeId[];
 };
 
 /**
@@ -276,6 +285,10 @@ type Op = {
 } | {
     type: 'group.remove';
     group: Group;
+} | {
+    type: 'frame.reorder';
+    ids: NodeId[];
+    prev: NodeId[];
 };
 /**
  * A batch is the atomic unit of mutation (also the unit of undo/redo and sync).
@@ -1644,6 +1657,26 @@ interface CanvasStore {
     getEdgeCount(): number;
     /** O(1) count. */
     getGroupCount(): number;
+    /**
+     * Returns frame nodes (`type === 'frame'`) in presentation order.
+     * Order is auto-maintained on add/remove and can be explicitly
+     * mutated via {@link CanvasStore.setFrameOrder}. Used by present
+     * mode + export to drive slide sequencing.
+     */
+    getFrames(): Node[];
+    /**
+     * Replace the presentation order of frames. `ids` must be a
+     * permutation of the current frame ids (any unknown ids are
+     * dropped; missing frames are appended to preserve invariants).
+     * Emits a `frame.reorder` op; undoable, syncs over collab.
+     */
+    setFrameOrder(ids: NodeId[]): void;
+    /**
+     * Geometric containment query: returns all non-frame nodes whose
+     * AABB is fully inside the given frame's AABB. Used to compute
+     * "what's on this slide". Cheap — backed by the spatial index.
+     */
+    getNodesInFrame(id: NodeId): Node[];
     /**
      * Spatial query — ids of nodes + edges that intersect a rect or
      * contain a point. Backed by a uniform grid for sub-millisecond
@@ -2055,6 +2088,12 @@ type Renderer = {
     setBackground(bg: CanvasBackground | undefined): void;
     /** Update the selection chrome color. Triggers an interactive repaint. */
     setSelectionColor(color: string): void;
+    /**
+     * Toggle frame-node paint. Use during a presentation flow to drop
+     * the slide border + label so only the frame contents are visible.
+     * Triggers a static repaint.
+     */
+    setHideFrames(hidden: boolean): void;
     /** Per-frame timing (FPS, lastMs, avgMs, frames). */
     stats(): FrameStats;
     /** Number of items the most recent paint actually drew. */

package/dist/index.js

@@ -3131,6 +3131,8 @@ var inverseOp = (op) => {
       return { type: "group.remove", group: op.group };
     case "group.remove":
       return { type: "group.upsert", group: op.group };
+    case "frame.reorder":
+      return { type: "frame.reorder", ids: op.prev, prev: op.ids };
   }
 };
 var inverseBatch = (batch) => {
@@ -3198,6 +3200,7 @@ var createCanvasStore = (opts = {}) => {
   const groupIdsAtom = atom("groupIds", []);
   const cameraAtom = atom("camera", initial.camera);
   const selectionAtom = atom("selection", initial.selection);
+  const frameOrderAtom = atom("frameOrder", initial.frameOrder ?? []);
   const interactionAtom = atom("interaction", idleInteractionState());
   const localPresenceAtom = atom("presence", emptyPresenceState(clientId));
   const remotePresence = /* @__PURE__ */ new Map();
@@ -3304,6 +3307,9 @@ var createCanvasStore = (opts = {}) => {
         nodeAtoms.set(op.node.id, a);
         nodeIdsAtom.update((ids) => [...ids, op.node.id]);
         reindexNode(op.node);
+        if (op.node.type === "frame") {
+          frameOrderAtom.update((ids) => ids.includes(op.node.id) ? ids : [...ids, op.node.id]);
+        }
         break;
       }
       case "node.update": {
@@ -3328,6 +3334,9 @@ var createCanvasStore = (opts = {}) => {
         nodeIdsAtom.update((ids) => ids.filter((x) => x !== id));
         unindexNode(id);
         incidentEdges.delete(id);
+        if (op.node.type === "frame") {
+          frameOrderAtom.update((ids) => ids.filter((x) => x !== id));
+        }
         break;
       }
       case "edge.add": {
@@ -3377,6 +3386,10 @@ var createCanvasStore = (opts = {}) => {
         groupIdsAtom.update((ids) => ids.filter((x) => x !== id));
         break;
       }
+      case "frame.reorder": {
+        frameOrderAtom.set([...op.ids]);
+        break;
+      }
     }
   };
   const enqueueOp = (op) => {
@@ -3399,6 +3412,7 @@ var createCanvasStore = (opts = {}) => {
     return prev;
   };
   const populateInitial = (scene) => {
+    const seededFrameOrder = [];
     for (const id of Object.keys(scene.nodes)) {
       const node = scene.nodes[id];
       if (!node) continue;
@@ -3406,7 +3420,9 @@ var createCanvasStore = (opts = {}) => {
       nodeAtoms.set(node.id, a);
       nodeIdsAtom.update((ids) => [...ids, node.id]);
       reindexNode(node);
+      if (node.type === "frame") seededFrameOrder.push(node.id);
     }
+    if (!scene.frameOrder) frameOrderAtom.set(seededFrameOrder);
     for (const id of Object.keys(scene.edges)) {
       const edge = scene.edges[id];
       if (!edge) continue;
@@ -3708,6 +3724,53 @@ var createCanvasStore = (opts = {}) => {
     getNodeCount: () => nodeIdsAtom.value.length,
     getEdgeCount: () => edgeIdsAtom.value.length,
     getGroupCount: () => groupIdsAtom.value.length,
+    getFrames: () => {
+      const out = [];
+      for (const id of frameOrderAtom.value) {
+        const n = nodeAtoms.get(id)?.value;
+        if (n && n.type === "frame") out.push(n);
+      }
+      return out;
+    },
+    setFrameOrder(ids) {
+      const valid = /* @__PURE__ */ new Set();
+      for (const a of nodeAtoms.values()) {
+        if (a.value.type === "frame") valid.add(a.value.id);
+      }
+      const filtered = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const id of ids) {
+        if (valid.has(id) && !seen.has(id)) {
+          filtered.push(id);
+          seen.add(id);
+        }
+      }
+      for (const id of valid) {
+        if (!seen.has(id)) filtered.push(id);
+      }
+      const prev = [...frameOrderAtom.value];
+      if (filtered.length === prev.length && filtered.every((id, i) => id === prev[i])) {
+        return;
+      }
+      enqueueOp({ type: "frame.reorder", ids: filtered, prev });
+    },
+    getNodesInFrame(id) {
+      const frame = nodeAtoms.get(id)?.value;
+      if (!frame || frame.type !== "frame") return [];
+      const frameAabb = nodeAABB(frame);
+      const candidates = nodeIndex.queryRect(frameAabb);
+      const out = [];
+      for (const cid of candidates) {
+        if (cid === id) continue;
+        const node = nodeAtoms.get(cid)?.value;
+        if (!node || node.type === "frame") continue;
+        const a = nodeAABB(node);
+        if (a.x >= frameAabb.x && a.y >= frameAabb.y && a.x + a.w <= frameAabb.x + frameAabb.w && a.y + a.h <= frameAabb.y + frameAabb.h) {
+          out.push(node);
+        }
+      }
+      return out;
+    },
     getEdgeGeometry(id) {
       const edge = edgeAtoms.get(id)?.value;
       if (!edge) return void 0;
@@ -3869,7 +3932,8 @@ var toSerialized = (scene) => ({
   edges: Object.values(scene.edges),
   groups: Object.values(scene.groups),
   camera: scene.camera,
-  selection: scene.selection
+  selection: scene.selection,
+  ...scene.frameOrder && scene.frameOrder.length > 0 ? { frameOrder: scene.frameOrder } : {}
 });
 var fromSerialized = (raw) => {
   let working = raw;
@@ -3891,7 +3955,8 @@ var fromSerialized = (raw) => {
     edges: Object.fromEntries(ser.edges.map((e) => [asEdgeId(e.id), e])),
     groups: Object.fromEntries(ser.groups.map((g) => [asGroupId(g.id), g])),
     camera: ser.camera,
-    selection: ser.selection
+    selection: ser.selection,
+    ...ser.frameOrder ? { frameOrder: ser.frameOrder } : {}
   };
 };
 var storeToJSON = (store) => ({
@@ -4436,6 +4501,40 @@ var drawMarquee = (ctx, rect, scale, color) => {
   ctx.restore();
 };
 
+// src/render/paint-frame.ts
+var FRAME_BORDER_PX = 1.5;
+var FRAME_BORDER_COLOR_DEFAULT = "#94a3b8";
+var FRAME_FILL_DEFAULT = "rgba(148, 163, 184, 0.06)";
+var FRAME_LABEL_FONT_PX = 12;
+var FRAME_LABEL_GAP_PX = 6;
+var FRAME_LABEL_COLOR = "#64748b";
+var paintFrameNode = (ctx, node, scale, theme) => {
+  if (node.w <= 0 || node.h <= 0) return;
+  const opacity = resolveOpacity(node.style, theme);
+  const needsScope = opacity !== 1;
+  if (needsScope) {
+    ctx.save();
+    ctx.globalAlpha = opacity;
+  }
+  const fill = node.style?.backgroundColor ?? (theme ? theme("frame.background") : void 0) ?? FRAME_FILL_DEFAULT;
+  ctx.fillStyle = fill;
+  ctx.fillRect(0, 0, node.w, node.h);
+  const stroke = resolveColor(node.style, "strokeColor", FRAME_BORDER_COLOR_DEFAULT, theme);
+  ctx.strokeStyle = stroke;
+  ctx.lineWidth = FRAME_BORDER_PX / scale;
+  ctx.setLineDash([]);
+  ctx.strokeRect(0, 0, node.w, node.h);
+  const labelPx = FRAME_LABEL_FONT_PX / scale;
+  const gapPx = FRAME_LABEL_GAP_PX / scale;
+  const label = node.content?.trim() || "Frame";
+  ctx.fillStyle = FRAME_LABEL_COLOR;
+  ctx.textBaseline = "bottom";
+  ctx.textAlign = "left";
+  ctx.font = `500 ${labelPx}px system-ui, -apple-system, sans-serif`;
+  ctx.fillText(label, 0, -gapPx);
+  if (needsScope) ctx.restore();
+};
+
 // src/render/shapes/content-bounds.ts
 var SQRT2_INV = 1 / Math.SQRT2;
 var contentBounds = (node) => {
@@ -4509,6 +4608,7 @@ var createRenderer = (opts) => {
   const interactiveSurface = setupSurface(opts.interactiveCanvas);
   let background = opts.background;
   let selectionColor = opts.selectionColor ?? DEFAULT_SELECTION_COLOR;
+  let hideFrames = false;
   sizeSurface(staticSurface, opts.width, opts.height);
   sizeSurface(interactiveSurface, opts.width, opts.height);
   let staticDirty = true;
@@ -4558,7 +4658,18 @@ var createRenderer = (opts) => {
     const cameraIsMoving = interaction.mode === "panning" || interaction.mode === "zooming";
     const movingNodeCount = excludedNodes?.size ?? 0;
     const roughEnabled = !cameraIsMoving && movingNodeCount <= ROUGH_MAX_MOVING_NODES && camera.z >= ROUGH_MIN_ZOOM && visible.length <= ROUGH_MAX_NODES;
+    if (!hideFrames) {
+      for (const node of visible) {
+        if (node.type !== "frame") continue;
+        if (excludedNodes?.has(node.id)) continue;
+        drawWithNodeTransform(staticSurface.ctx, node, () => {
+          paintFrameNode(staticSurface.ctx, node, scale, theme);
+        });
+        drawn++;
+      }
+    }
     for (const node of visible) {
+      if (node.type === "frame") continue;
       if (excludedNodes?.has(node.id)) continue;
       const isEditingThis = editingNodeId === node.id;
       if (isDrawablePrimitive(node.type)) {
@@ -4761,9 +4872,13 @@ var createRenderer = (opts) => {
         isMoving: true};
       const dragRoughEnabled = inDragMap.size <= ROUGH_MAX_MOVING_NODES && camera.z >= ROUGH_MIN_ZOOM;
       for (const node of inDragMap.values()) {
-        if (!isDrawablePrimitive(node.type) && node.type !== "text" && node.type !== "image" && node.type !== "icon")
+        if (!isDrawablePrimitive(node.type) && node.type !== "text" && node.type !== "image" && node.type !== "icon" && node.type !== "frame")
           continue;
         drawWithNodeTransform(ctx, node, () => {
+          if (node.type === "frame") {
+            paintFrameNode(ctx, node, scale, theme);
+            return;
+          }
           if (node.type === "image") {
             paintImageNode(ctx, node, assetCache, theme);
             return;
@@ -4965,6 +5080,11 @@ var createRenderer = (opts) => {
       interactiveDirty = true;
       loop.requestFrame();
     },
+    setHideFrames(hidden) {
+      hideFrames = hidden;
+      staticDirty = true;
+      loop.requestFrame();
+    },
     stats: () => loop.stats(),
     lastDrawCount: () => lastDrawn,
     getOverlaySet: () => [...overlaySet],
@@ -4995,6 +5115,7 @@ var sceneBounds = (store) => {
   let maxY = Number.NEGATIVE_INFINITY;
   for (const n of nodes) {
     if (n.hidden) continue;
+    if (n.type === "frame") continue;
     const r = nodeAABB(n);
     if (r.x < minX) minX = r.x;
     if (r.y < minY) minY = r.y;
@@ -5025,6 +5146,7 @@ var renderMinimapContent = (ctx, store, mapWidth, mapHeight, opts = {}) => {
   const defaultColor = opts.defaultNodeColor ?? "#94a3b8";
   for (const node of store.getAllNodes()) {
     if (node.hidden) continue;
+    if (node.type === "frame") continue;
     const r = nodeAABB(node);
     const x = offX + (r.x - bx) * scale;
     const y = offY + (r.y - by) * scale;