@canvas-harness/core 0.1.1 → 0.1.2

package/dist/index.d.cts

@@ -817,7 +817,28 @@ type SnapshotEnv = {
 type NodeTypeDefOptions = {
     /** Unique type id, e.g. 'chart-card'. */
     type: string;
+    /**
+     * Canvas paint for the node body. Caller has already applied the
+     * camera + node transform, so paint at `(0, 0, node.w, node.h)`.
+     *
+     * Context state contract:
+     *   - The renderer wraps this call in `ctx.save()` / `ctx.restore()`
+     *     so any state you change (fillStyle, strokeStyle, lineWidth,
+     *     setLineDash, globalAlpha, font, …) is automatically rolled
+     *     back before the next node draws — set whatever you need
+     *     without worrying about cleanup.
+     *   - Conversely, **do NOT assume default state on entry.** Always
+     *     set the styles you depend on; the previous node's values
+     *     may still be in effect.
+     *   - The transform is NOT save/restore-protected at this level
+     *     (it's managed one frame up by the renderer). Don't leave
+     *     `translate` / `rotate` / `scale` calls un-paired.
+     */
     renderCanvas?: (ctx: CanvasRenderingContext2D, node: Node, env: RenderEnv) => void;
+    /**
+     * Low-zoom / motion fallback paint — see ARCHITECTURE.md §5.3 LOD.
+     * Same context-state contract as `renderCanvas`.
+     */
     drawPlaceholder?: (ctx: CanvasRenderingContext2D, node: Node, env: RenderEnv) => void;
     /**
      * The React view component reference. Stored as `unknown` here because the
@@ -2328,6 +2349,15 @@ declare const worldViewport: (surface: CanvasSurface, camera: CameraState) => Wo
  * Wraps a draw callback in the local-frame transform for one node:
  * translates to the node's center, rotates by node.angle, then translates
  * back to the node's top-left so the drawer can build paths in (0..w, 0..h).
+ *
+ * Fast path: when `node.angle === 0` (the common case) we skip the
+ * canvas2d save/restore pair entirely and manually un-translate after
+ * the callback. `save()`/`restore()` allocate + swap a full graphics
+ * state record; at 10k+ nodes/frame that's ~1ms of the paint budget.
+ * The callback is responsible for not leaking transform state — all
+ * built-in drawers (drawShape, drawCompositeRough, paintFrameNode,
+ * paintImageNode, paintIconNode) honor this contract by either
+ * leaving the transform untouched or restoring their own inner pushes.
  */
 declare const drawWithNodeTransform: (ctx: CanvasRenderingContext2D, node: Node, fn: () => void) => void;
 

package/dist/index.d.ts

@@ -817,7 +817,28 @@ type SnapshotEnv = {
 type NodeTypeDefOptions = {
     /** Unique type id, e.g. 'chart-card'. */
     type: string;
+    /**
+     * Canvas paint for the node body. Caller has already applied the
+     * camera + node transform, so paint at `(0, 0, node.w, node.h)`.
+     *
+     * Context state contract:
+     *   - The renderer wraps this call in `ctx.save()` / `ctx.restore()`
+     *     so any state you change (fillStyle, strokeStyle, lineWidth,
+     *     setLineDash, globalAlpha, font, …) is automatically rolled
+     *     back before the next node draws — set whatever you need
+     *     without worrying about cleanup.
+     *   - Conversely, **do NOT assume default state on entry.** Always
+     *     set the styles you depend on; the previous node's values
+     *     may still be in effect.
+     *   - The transform is NOT save/restore-protected at this level
+     *     (it's managed one frame up by the renderer). Don't leave
+     *     `translate` / `rotate` / `scale` calls un-paired.
+     */
     renderCanvas?: (ctx: CanvasRenderingContext2D, node: Node, env: RenderEnv) => void;
+    /**
+     * Low-zoom / motion fallback paint — see ARCHITECTURE.md §5.3 LOD.
+     * Same context-state contract as `renderCanvas`.
+     */
     drawPlaceholder?: (ctx: CanvasRenderingContext2D, node: Node, env: RenderEnv) => void;
     /**
      * The React view component reference. Stored as `unknown` here because the
@@ -2328,6 +2349,15 @@ declare const worldViewport: (surface: CanvasSurface, camera: CameraState) => Wo
  * Wraps a draw callback in the local-frame transform for one node:
  * translates to the node's center, rotates by node.angle, then translates
  * back to the node's top-left so the drawer can build paths in (0..w, 0..h).
+ *
+ * Fast path: when `node.angle === 0` (the common case) we skip the
+ * canvas2d save/restore pair entirely and manually un-translate after
+ * the callback. `save()`/`restore()` allocate + swap a full graphics
+ * state record; at 10k+ nodes/frame that's ~1ms of the paint budget.
+ * The callback is responsible for not leaking transform state — all
+ * built-in drawers (drawShape, drawCompositeRough, paintFrameNode,
+ * paintImageNode, paintIconNode) honor this contract by either
+ * leaving the transform untouched or restoring their own inner pushes.
  */
 declare const drawWithNodeTransform: (ctx: CanvasRenderingContext2D, node: Node, fn: () => void) => void;
 

package/dist/index.js

@@ -4869,16 +4869,18 @@ var applyCameraTransform = (surface, camera) => {
 };
 var worldViewport = (surface, camera) => viewportWorldRect(camera, surface.cssWidth, surface.cssHeight);
 var drawWithNodeTransform = (ctx, node, fn) => {
-  ctx.save();
   if (node.angle === 0) {
     ctx.translate(node.x, node.y);
-  } else {
-    const cx = node.x + node.w / 2;
-    const cy = node.y + node.h / 2;
-    ctx.translate(cx, cy);
-    ctx.rotate(node.angle);
-    ctx.translate(-node.w / 2, -node.h / 2);
+    fn();
+    ctx.translate(-node.x, -node.y);
+    return;
   }
+  ctx.save();
+  const cx = node.x + node.w / 2;
+  const cy = node.y + node.h / 2;
+  ctx.translate(cx, cy);
+  ctx.rotate(node.angle);
+  ctx.translate(-node.w / 2, -node.h / 2);
   fn();
   ctx.restore();
 };
@@ -4900,6 +4902,12 @@ var createRenderer = (opts) => {
   let interactiveDirty = false;
   let overlaySet = /* @__PURE__ */ new Set();
   let lastDrawn = 0;
+  let sortedNodeIdsCache = null;
+  let sortedEdgeIdsCache = null;
+  const invalidateSortedCaches = () => {
+    sortedNodeIdsCache = null;
+    sortedEdgeIdsCache = null;
+  };
   const requestRepaint = () => {
     staticDirty = true;
     loop.requestFrame();
@@ -5029,7 +5037,9 @@ var createRenderer = (opts) => {
       }
       if (def.renderCanvas) {
         drawWithNodeTransform(staticSurface.ctx, node, () => {
+          staticSurface.ctx.save();
           def.renderCanvas(staticSurface.ctx, node, renderEnv);
+          staticSurface.ctx.restore();
         });
         drawn++;
       }
@@ -5062,11 +5072,19 @@ var createRenderer = (opts) => {
       }
     }
     if (def.drawPlaceholder) {
-      drawWithNodeTransform(ctx, node, () => def.drawPlaceholder(ctx, node, env));
+      drawWithNodeTransform(ctx, node, () => {
+        ctx.save();
+        def.drawPlaceholder(ctx, node, env);
+        ctx.restore();
+      });
       return true;
     }
     if (def.renderCanvas) {
-      drawWithNodeTransform(ctx, node, () => def.renderCanvas(ctx, node, env));
+      drawWithNodeTransform(ctx, node, () => {
+        ctx.save();
+        def.renderCanvas(ctx, node, env);
+        ctx.restore();
+      });
       return true;
     }
     return false;
@@ -5133,14 +5151,23 @@ var createRenderer = (opts) => {
       isMoving: isMoving2
     });
   };
+  const getSortedEdgeIds = () => {
+    if (sortedEdgeIdsCache) return sortedEdgeIdsCache;
+    const all = store.getAllEdges();
+    sortedEdgeIdsCache = all.slice().sort((a, b) => a.z - b.z || (a.id < b.id ? -1 : 1)).map((e) => e.id);
+    return sortedEdgeIdsCache;
+  };
   const visibleEdges = (viewport) => {
     const ids = store.querySpatial({ rect: viewport }).edges;
+    if (ids.length === 0) return [];
+    const visibleSet = new Set(ids);
+    const sorted = getSortedEdgeIds();
     const result = [];
-    for (const id of ids) {
+    for (const id of sorted) {
+      if (!visibleSet.has(id)) continue;
       const e = store.getEdge(id);
       if (e) result.push(e);
     }
-    result.sort((a, b) => a.z - b.z || (a.id < b.id ? -1 : 1));
     return result;
   };
   const paintInteractive = () => {
@@ -5288,21 +5315,31 @@ var createRenderer = (opts) => {
     }
     return m;
   };
+  const getSortedNodeIds = () => {
+    if (sortedNodeIdsCache) return sortedNodeIdsCache;
+    const all = store.getAllNodes();
+    sortedNodeIdsCache = all.slice().sort((a, b) => a.z - b.z || (a.id < b.id ? -1 : 1)).map((n) => n.id);
+    return sortedNodeIdsCache;
+  };
   const visibleNodes = (camera, viewport) => {
     const ids = store.querySpatial({ rect: viewport }).nodes;
+    if (ids.length === 0) return [];
+    const visibleSet = new Set(ids);
+    const sorted = getSortedNodeIds();
     const result = [];
     const minWorldSize = MIN_ON_SCREEN_SIZE_PX / camera.z;
-    for (const id of ids) {
+    for (const id of sorted) {
+      if (!visibleSet.has(id)) continue;
       const n = store.getNode(id);
       if (!n) continue;
       if (n.w < minWorldSize && n.h < minWorldSize) continue;
       if (intersectsViewport(n, viewport)) result.push(n);
     }
-    result.sort((a, b) => a.z - b.z || (a.id < b.id ? -1 : 1));
     return result;
   };
   const loop = createFrameLoop({ draw: drawFrame });
   const onStoreChange = () => {
+    invalidateSortedCaches();
     staticDirty = true;
     interactiveDirty = true;
     loop.requestFrame();