@canvas-harness/core 0.0.1 → 0.0.3

package/dist/index.cjs

@@ -2908,6 +2908,155 @@ var createDefaultTextareaEditor = ({
   };
 };
 
+// src/assets/image.ts
+var MAX_IMAGE_BYTES = 2 * 1024 * 1024;
+var ACCEPTED_MIME = /* @__PURE__ */ new Set(["image/png", "image/jpeg"]);
+var validateImageInput = (input) => {
+  if (typeof input === "string") {
+    if (!input.startsWith("data:")) {
+      throw new Error(
+        "addImage: external URL strings are not supported. Pass a File, Blob, or `data:image/(png|jpeg)` URI."
+      );
+    }
+    const mimeMatch = /^data:([^;,]+)/.exec(input);
+    const mime = mimeMatch?.[1] ?? "";
+    if (!ACCEPTED_MIME.has(mime)) {
+      throw new Error(
+        `addImage: unsupported MIME "${mime || "(unknown)"}". Only image/png and image/jpeg are supported.`
+      );
+    }
+    const comma = input.indexOf(",");
+    if (comma < 0) throw new Error("addImage: malformed data URI (missing payload separator)");
+    const decodedBytes = Math.floor((input.length - comma - 1) * 3 / 4);
+    if (decodedBytes > MAX_IMAGE_BYTES) {
+      throw new Error(
+        `addImage: image exceeds the 2 MB limit (${Math.round(decodedBytes / 1024)} KB).`
+      );
+    }
+    return;
+  }
+  if (!ACCEPTED_MIME.has(input.type)) {
+    throw new Error(
+      `addImage: unsupported file type "${input.type || "(unknown)"}". Only image/png and image/jpeg are supported.`
+    );
+  }
+  if (input.size > MAX_IMAGE_BYTES) {
+    throw new Error(`addImage: file exceeds the 2 MB limit (${Math.round(input.size / 1024)} KB).`);
+  }
+};
+var toImageBlob = async (input) => {
+  if (typeof input === "string") {
+    const res = await fetch(input);
+    return res.blob();
+  }
+  return input;
+};
+var downscaleImageBlob = async (blob, maxDim) => {
+  const bitmap = await createImageBitmap(blob);
+  const naturalW = bitmap.width;
+  const naturalH = bitmap.height;
+  const maxSide = Math.max(naturalW, naturalH);
+  if (maxDim <= 0 || maxSide <= maxDim) {
+    bitmap.close?.();
+    return { blob, naturalW, naturalH };
+  }
+  const scale = maxDim / maxSide;
+  const w = Math.max(1, Math.round(naturalW * scale));
+  const h = Math.max(1, Math.round(naturalH * scale));
+  const canvas = new OffscreenCanvas(w, h);
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("addImage: failed to acquire OffscreenCanvas 2d context");
+  ctx.drawImage(bitmap, 0, 0, w, h);
+  bitmap.close?.();
+  const outType = blob.type === "image/png" ? "image/png" : "image/jpeg";
+  const outBlob = await canvas.convertToBlob({ type: outType, quality: 0.9 });
+  return { blob: outBlob, naturalW: w, naturalH: h };
+};
+var blobToDataUri = (blob) => {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      if (typeof reader.result === "string") resolve(reader.result);
+      else reject(new Error("FileReader returned non-string result"));
+    };
+    reader.onerror = () => reject(reader.error ?? new Error("FileReader failed"));
+    reader.readAsDataURL(blob);
+  });
+};
+
+// src/assets/svg.ts
+var MAX_SVG_BYTES = 2 * 1024 * 1024;
+var DEFAULT_SVG_SIZE = 24;
+var validateSvgMarkup = (markup) => {
+  if (typeof markup !== "string") {
+    throw new Error("addSvg: src must be a string of SVG markup");
+  }
+  const byteLen = new Blob([markup]).size;
+  if (byteLen > MAX_SVG_BYTES) {
+    throw new Error(`addSvg: SVG markup exceeds the 2 MB limit (${Math.round(byteLen / 1024)} KB).`);
+  }
+  if (!/<svg[\s>]/i.test(markup)) {
+    throw new Error("addSvg: src does not look like SVG markup (no <svg> tag found)");
+  }
+};
+var sanitizeSvg = (markup) => {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(markup, "image/svg+xml");
+  const root = doc.documentElement;
+  if (root.nodeName === "parsererror" || root.querySelector("parsererror")) {
+    throw new Error("addSvg: malformed SVG (parser error)");
+  }
+  const removable = [];
+  const walker = doc.createTreeWalker(doc, NodeFilter.SHOW_ELEMENT);
+  let n = walker.nextNode();
+  while (n) {
+    const el = n;
+    const tag = el.tagName.toLowerCase();
+    if (tag === "script" || tag === "foreignobject") {
+      removable.push(el);
+    } else {
+      for (const attr of [...el.attributes]) {
+        const name = attr.name.toLowerCase();
+        const value = attr.value.trim().toLowerCase();
+        if (name.startsWith("on")) {
+          el.removeAttribute(attr.name);
+        } else if ((name === "href" || name === "xlink:href" || name === "src") && value.startsWith("javascript:")) {
+          el.removeAttribute(attr.name);
+        }
+      }
+    }
+    n = walker.nextNode();
+  }
+  for (const el of removable) el.remove();
+  return new XMLSerializer().serializeToString(doc);
+};
+var extractSvgDimensions = (markup) => {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(markup, "image/svg+xml");
+  const svg = doc.documentElement;
+  if (svg.nodeName.toLowerCase() !== "svg") {
+    return { w: DEFAULT_SVG_SIZE, h: DEFAULT_SVG_SIZE };
+  }
+  const widthAttr = svg.getAttribute("width");
+  const heightAttr = svg.getAttribute("height");
+  if (widthAttr && heightAttr) {
+    const w = Number.parseFloat(widthAttr);
+    const h = Number.parseFloat(heightAttr);
+    if (Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0) return { w, h };
+  }
+  const viewBox = svg.getAttribute("viewBox");
+  if (viewBox) {
+    const parts = viewBox.split(/[\s,]+/).map(Number.parseFloat);
+    if (parts.length === 4 && parts.every(Number.isFinite) && parts[2] > 0 && parts[3] > 0) {
+      return { w: parts[2], h: parts[3] };
+    }
+  }
+  return { w: DEFAULT_SVG_SIZE, h: DEFAULT_SVG_SIZE };
+};
+var applySvgColor = (markup, color) => {
+  return markup.replace(/currentColor/gi, color);
+};
+
 // src/store/conflict.ts
 var detectConflicts = (batch, getNode, getEdge) => {
   const out = [];
@@ -2984,6 +3133,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) => {
@@ -3051,6 +3202,7 @@ var createCanvasStore = (opts = {}) => {
   const groupIdsAtom = signia.atom("groupIds", []);
   const cameraAtom = signia.atom("camera", initial.camera);
   const selectionAtom = signia.atom("selection", initial.selection);
+  const frameOrderAtom = signia.atom("frameOrder", initial.frameOrder ?? []);
   const interactionAtom = signia.atom("interaction", idleInteractionState());
   const localPresenceAtom = signia.atom("presence", emptyPresenceState(clientId));
   const remotePresence = /* @__PURE__ */ new Map();
@@ -3157,6 +3309,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": {
@@ -3181,6 +3336,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": {
@@ -3230,6 +3388,10 @@ var createCanvasStore = (opts = {}) => {
         groupIdsAtom.update((ids) => ids.filter((x) => x !== id));
         break;
       }
+      case "frame.reorder": {
+        frameOrderAtom.set([...op.ids]);
+        break;
+      }
     }
   };
   const enqueueOp = (op) => {
@@ -3252,6 +3414,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;
@@ -3259,7 +3422,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;
@@ -3328,6 +3493,55 @@ var createCanvasStore = (opts = {}) => {
         if (batch) emitChange(batch);
       });
     },
+    async addImage(opts2) {
+      validateImageInput(opts2.src);
+      const rawBlob = await toImageBlob(opts2.src);
+      const maxDim = opts2.maxDimension ?? 2048;
+      const { blob, naturalW, naturalH } = await downscaleImageBlob(rawBlob, maxDim);
+      const src = await blobToDataUri(blob);
+      const DEFAULT_MAX_NODE_SIDE = 400;
+      const aspectScale = Math.min(1, DEFAULT_MAX_NODE_SIDE / Math.max(naturalW, naturalH));
+      const w = opts2.w ?? Math.max(1, Math.round(naturalW * aspectScale));
+      const h = opts2.h ?? Math.max(1, Math.round(naturalH * aspectScale));
+      const id = asNodeId(idGenerator());
+      this.addNode({
+        id,
+        type: "image",
+        x: opts2.x,
+        y: opts2.y,
+        w,
+        h,
+        angle: 0,
+        z: 0,
+        groups: [],
+        style: opts2.style,
+        data: { src, naturalW, naturalH, alt: opts2.alt }
+      });
+      return id;
+    },
+    async addSvg(opts2) {
+      validateSvgMarkup(opts2.src);
+      const sanitized = sanitizeSvg(opts2.src);
+      const intrinsic = extractSvgDimensions(sanitized);
+      const w = opts2.w ?? intrinsic.w;
+      const h = opts2.h ?? intrinsic.h;
+      const mergedStyle = opts2.color || opts2.style ? { ...opts2.color ? { iconColor: opts2.color } : {}, ...opts2.style } : void 0;
+      const id = asNodeId(idGenerator());
+      this.addNode({
+        id,
+        type: "icon",
+        x: opts2.x,
+        y: opts2.y,
+        w,
+        h,
+        angle: 0,
+        z: 0,
+        groups: [],
+        ...mergedStyle ? { style: mergedStyle } : {},
+        data: { src: sanitized, alt: opts2.alt }
+      });
+      return id;
+    },
     addEdge(edge) {
       const withZ = edge.z === 0 ? { ...edge, z: ++topZ } : edge;
       if (withZ.z > topZ) topZ = withZ.z;
@@ -3512,6 +3726,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;
@@ -3673,7 +3934,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;
@@ -3695,7 +3957,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) => ({
@@ -3800,6 +4063,182 @@ var createFrameLoop = ({ draw, historySize = 60 }) => {
   };
 };
 
+// src/render/assets/cache.ts
+var MAX_ENTRIES2 = 256;
+var bucketSize = (px) => {
+  if (px <= 32) return 32;
+  if (px <= 64) return 64;
+  if (px <= 128) return 128;
+  if (px <= 256) return 256;
+  if (px <= 512) return 512;
+  return Math.ceil(px / 256) * 256;
+};
+var createAssetCache = (opts = {}) => {
+  const entries = /* @__PURE__ */ new Map();
+  let disposed = false;
+  const notify = () => {
+    if (disposed) return;
+    opts.onReady?.();
+  };
+  const touch = (key, entry) => {
+    entries.delete(key);
+    entries.set(key, entry);
+    if (entries.size > MAX_ENTRIES2) {
+      const oldestKey = entries.keys().next().value;
+      if (oldestKey !== void 0) {
+        const evicted = entries.get(oldestKey);
+        if (evicted?.kind === "icon" && evicted.bitmap) evicted.bitmap.close?.();
+        entries.delete(oldestKey);
+      }
+    }
+  };
+  const startImageDecode = (key, src) => {
+    const entry = { kind: "image", state: "pending", bitmap: null };
+    touch(key, entry);
+    const img = new Image();
+    img.onload = () => {
+      if (disposed) return;
+      entry.state = "ready";
+      entry.bitmap = img;
+      notify();
+    };
+    img.onerror = (e) => {
+      if (disposed) return;
+      entry.state = "error";
+      entry.err = e;
+      notify();
+    };
+    img.src = src;
+  };
+  const startIconRaster = (key, markup, color, sizePx) => {
+    const entry = { kind: "icon", state: "pending", bitmap: null };
+    touch(key, entry);
+    const colored = color ? applySvgColor(markup, color) : markup;
+    const blob = new Blob([colored], { type: "image/svg+xml" });
+    const url = URL.createObjectURL(blob);
+    const img = new Image();
+    img.onload = async () => {
+      URL.revokeObjectURL(url);
+      if (disposed) return;
+      try {
+        const bitmap = await createImageBitmap(img, {
+          resizeWidth: sizePx,
+          resizeHeight: sizePx,
+          resizeQuality: "high"
+        });
+        if (disposed) {
+          bitmap.close?.();
+          return;
+        }
+        entry.state = "ready";
+        entry.bitmap = bitmap;
+        notify();
+      } catch (e) {
+        entry.state = "error";
+        entry.err = e;
+        notify();
+      }
+    };
+    img.onerror = (e) => {
+      URL.revokeObjectURL(url);
+      if (disposed) return;
+      entry.state = "error";
+      entry.err = e;
+      notify();
+    };
+    img.src = url;
+  };
+  return {
+    getImage(src) {
+      const key = `img:${src}`;
+      const existing = entries.get(key);
+      if (existing && existing.kind === "image") {
+        if (existing.state === "ready") {
+          touch(key, existing);
+          return existing.bitmap;
+        }
+        return null;
+      }
+      startImageDecode(key, src);
+      return null;
+    },
+    getIcon(markup, color, devicePixelSize) {
+      const size = bucketSize(Math.max(1, Math.ceil(devicePixelSize)));
+      const key = `icon:${size}:${color ?? ""}:${markup}`;
+      const existing = entries.get(key);
+      if (existing && existing.kind === "icon") {
+        if (existing.state === "ready") {
+          touch(key, existing);
+          return existing.bitmap;
+        }
+        return null;
+      }
+      startIconRaster(key, markup, color, size);
+      return null;
+    },
+    dispose() {
+      disposed = true;
+      for (const entry of entries.values()) {
+        if (entry.kind === "icon" && entry.bitmap) entry.bitmap.close?.();
+      }
+      entries.clear();
+    }
+  };
+};
+
+// src/render/assets/paint.ts
+var PLACEHOLDER_FILL = "#e5e7eb";
+var PLACEHOLDER_TEXT_FILL = "#94a3b8";
+var paintPlaceholder = (ctx, w, h, label) => {
+  ctx.fillStyle = PLACEHOLDER_FILL;
+  ctx.fillRect(0, 0, w, h);
+  if (w >= 32 && h >= 16) {
+    ctx.fillStyle = PLACEHOLDER_TEXT_FILL;
+    ctx.font = "11px system-ui, sans-serif";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(label, w / 2, h / 2);
+  }
+};
+var paintImageNode = (ctx, node, cache4, theme) => {
+  if (node.w <= 0 || node.h <= 0) return;
+  const data = node.data;
+  if (!data?.src) return;
+  const bitmap = cache4.getImage(data.src);
+  const opacity = resolveOpacity(node.style, theme);
+  const needsScope = opacity !== 1;
+  if (needsScope) {
+    ctx.save();
+    ctx.globalAlpha = opacity;
+  }
+  if (bitmap?.complete) {
+    ctx.drawImage(bitmap, 0, 0, node.w, node.h);
+  } else {
+    paintPlaceholder(ctx, node.w, node.h, "loading\u2026");
+  }
+  if (needsScope) ctx.restore();
+};
+var paintIconNode = (ctx, node, cache4, scale, theme) => {
+  if (node.w <= 0 || node.h <= 0) return;
+  const data = node.data;
+  if (!data?.src) return;
+  const sizePx = Math.max(node.w, node.h) * scale;
+  const color = node.style?.iconColor;
+  const bitmap = cache4.getIcon(data.src, color, sizePx);
+  const opacity = resolveOpacity(node.style, theme);
+  const needsScope = opacity !== 1;
+  if (needsScope) {
+    ctx.save();
+    ctx.globalAlpha = opacity;
+  }
+  if (bitmap) {
+    ctx.drawImage(bitmap, 0, 0, node.w, node.h);
+  } else {
+    paintPlaceholder(ctx, node.w, node.h, "svg\u2026");
+  }
+  if (needsScope) ctx.restore();
+};
+
 // src/render/background.ts
 var MIN_PATTERN_SCREEN_PX = 8;
 var MIN_VISIBLE_PATTERN_PX = 2;
@@ -3941,14 +4380,14 @@ var hitTestRotateHandle = (node, worldPoint, cameraZ) => {
 };
 
 // src/render/overlay.ts
-var SELECTION_COLOR = "#3b82f6";
+var DEFAULT_SELECTION_COLOR = "#3b82f6";
 var SELECTION_OUTLINE_PX = 1.5;
-var MARQUEE_FILL = "rgba(59, 130, 246, 0.08)";
+var MARQUEE_FILL_ALPHA = 0.08;
 var MARQUEE_STROKE_PX = 1;
-var drawSelectionOutline = (ctx, node, scale) => {
+var drawSelectionOutline = (ctx, node, scale, color) => {
   if (node.angle === 0) {
     ctx.save();
-    ctx.strokeStyle = SELECTION_COLOR;
+    ctx.strokeStyle = color;
     ctx.lineWidth = SELECTION_OUTLINE_PX / scale;
     ctx.beginPath();
     ctx.rect(node.x, node.y, node.w, node.h);
@@ -3967,7 +4406,7 @@ var drawSelectionOutline = (ctx, node, scale) => {
     { x: -node.w / 2, y: node.h / 2 }
   ].map((p) => ({ x: cx + p.x * cos - p.y * sin, y: cy + p.x * sin + p.y * cos }));
   ctx.save();
-  ctx.strokeStyle = SELECTION_COLOR;
+  ctx.strokeStyle = color;
   ctx.lineWidth = SELECTION_OUTLINE_PX / scale;
   ctx.beginPath();
   const first = corners[0];
@@ -3980,13 +4419,13 @@ var drawSelectionOutline = (ctx, node, scale) => {
   ctx.stroke();
   ctx.restore();
 };
-var drawResizeHandles = (ctx, node, scale) => {
+var drawResizeHandles = (ctx, node, scale, color) => {
   const halfPx = RESIZE_HANDLE_SIZE_PX / 2;
   const halfWorld = halfPx / scale;
   const positions = handleWorldPositions(node);
   ctx.save();
   ctx.fillStyle = "#fff";
-  ctx.strokeStyle = SELECTION_COLOR;
+  ctx.strokeStyle = color;
   ctx.lineWidth = SELECTION_OUTLINE_PX / scale;
   for (const key of Object.keys(positions)) {
     const p = positions[key];
@@ -3997,7 +4436,7 @@ var drawResizeHandles = (ctx, node, scale) => {
   }
   ctx.restore();
 };
-var drawRotateHandle = (ctx, node, scale, cameraZ) => {
+var drawRotateHandle = (ctx, node, scale, cameraZ, color) => {
   const center = rotateHandleWorldPosition(node, cameraZ);
   const radiusWorld = ROTATE_HANDLE_RADIUS_PX / scale;
   const cx = node.x + node.w / 2;
@@ -4010,7 +4449,7 @@ var drawRotateHandle = (ctx, node, scale, cameraZ) => {
     y: cy + 0 * sin + topMidLocalY * cos
   };
   ctx.save();
-  ctx.strokeStyle = SELECTION_COLOR;
+  ctx.strokeStyle = color;
   ctx.lineWidth = SELECTION_OUTLINE_PX / scale;
   ctx.beginPath();
   ctx.moveTo(topMidWorld.x, topMidWorld.y);
@@ -4023,12 +4462,12 @@ var drawRotateHandle = (ctx, node, scale, cameraZ) => {
   ctx.stroke();
   ctx.restore();
 };
-var drawEdgeMidpointHandle = (ctx, midpoint, scale) => {
+var drawEdgeMidpointHandle = (ctx, midpoint, scale, color) => {
   const radiusPx = 5;
   const radiusWorld = radiusPx / scale;
   ctx.save();
   ctx.fillStyle = "#fff";
-  ctx.strokeStyle = SELECTION_COLOR;
+  ctx.strokeStyle = color;
   ctx.lineWidth = SELECTION_OUTLINE_PX / scale;
   ctx.beginPath();
   ctx.arc(midpoint.x, midpoint.y, radiusWorld, 0, Math.PI * 2);
@@ -4036,12 +4475,12 @@ var drawEdgeMidpointHandle = (ctx, midpoint, scale) => {
   ctx.stroke();
   ctx.restore();
 };
-var drawEdgeEndpointHandles = (ctx, source, target, scale) => {
+var drawEdgeEndpointHandles = (ctx, source, target, scale, color) => {
   const radiusPx = 5;
   const radiusWorld = radiusPx / scale;
   ctx.save();
   ctx.fillStyle = "#fff";
-  ctx.strokeStyle = SELECTION_COLOR;
+  ctx.strokeStyle = color;
   ctx.lineWidth = SELECTION_OUTLINE_PX / scale;
   for (const p of [source, target]) {
     ctx.beginPath();
@@ -4051,17 +4490,53 @@ var drawEdgeEndpointHandles = (ctx, source, target, scale) => {
   }
   ctx.restore();
 };
-var drawMarquee = (ctx, rect, scale) => {
+var drawMarquee = (ctx, rect, scale, color) => {
   ctx.save();
-  ctx.fillStyle = MARQUEE_FILL;
+  ctx.globalAlpha = MARQUEE_FILL_ALPHA;
+  ctx.fillStyle = color;
   ctx.fillRect(rect.x, rect.y, rect.w, rect.h);
-  ctx.strokeStyle = SELECTION_COLOR;
+  ctx.globalAlpha = 1;
+  ctx.strokeStyle = color;
   ctx.lineWidth = MARQUEE_STROKE_PX / scale;
   ctx.setLineDash([4 / scale, 3 / scale]);
   ctx.strokeRect(rect.x, rect.y, rect.w, rect.h);
   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) => {
@@ -4134,12 +4609,19 @@ var createRenderer = (opts) => {
   const staticSurface = setupSurface(opts.staticCanvas);
   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;
   let interactiveDirty = false;
   let overlaySet = /* @__PURE__ */ new Set();
   let lastDrawn = 0;
+  const requestRepaint = () => {
+    staticDirty = true;
+    loop.requestFrame();
+  };
+  const assetCache = createAssetCache({ onReady: requestRepaint });
   const isInteractive = (state) => state.mode !== "idle" || store.getSelection().length > 0;
   const drawFrame = () => {
     if (staticDirty) {
@@ -4178,7 +4660,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)) {
@@ -4209,6 +4702,20 @@ var createRenderer = (opts) => {
         drawn++;
         continue;
       }
+      if (node.type === "image") {
+        drawWithNodeTransform(staticSurface.ctx, node, () => {
+          paintImageNode(staticSurface.ctx, node, assetCache, theme);
+        });
+        drawn++;
+        continue;
+      }
+      if (node.type === "icon") {
+        drawWithNodeTransform(staticSurface.ctx, node, () => {
+          paintIconNode(staticSurface.ctx, node, assetCache, scale, theme);
+        });
+        drawn++;
+        continue;
+      }
       if (node.type === "text") {
         drawWithNodeTransform(staticSurface.ctx, node, () => {
           if (isEditingThis) return;
@@ -4367,8 +4874,21 @@ 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") continue;
+        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;
+          }
+          if (node.type === "icon") {
+            paintIconNode(ctx, node, assetCache, scale, theme);
+            return;
+          }
           if (isDrawablePrimitive(node.type)) {
             const useRough = dragRoughEnabled && (node.style?.roughness ?? 0) > 0;
             const roughReady = useRough ? getRoughCanvasCtor() !== null : false;
@@ -4420,32 +4940,32 @@ var createRenderer = (opts) => {
       for (const id of selectedNodeIds) {
         const node = inDragMap.get(id) ?? store.getNode(id);
         if (!node) continue;
-        drawSelectionOutline(ctx, node, scale);
+        drawSelectionOutline(ctx, node, scale, selectionColor);
       }
       if (interaction.mode !== "dragging" && selectedNodeIds.length === 1) {
         const node = inDragMap.get(selectedNodeIds[0]) ?? store.getNode(selectedNodeIds[0]);
         if (node) {
-          drawResizeHandles(ctx, node, scale);
-          drawRotateHandle(ctx, node, scale, camera.z);
+          drawResizeHandles(ctx, node, scale, selectionColor);
+          drawRotateHandle(ctx, node, scale, camera.z, selectionColor);
         }
       }
     }
     for (const id of selectedEdgeIds) {
       const geom = store.getEdgeGeometry(id);
       if (geom) {
-        drawEdgeEndpointHandles(ctx, geom.source, geom.target, scale);
+        drawEdgeEndpointHandles(ctx, geom.source, geom.target, scale, selectionColor);
         const edge = store.getEdge(id);
         if (edge && edge.pathStyle === "bezier") {
           const mid = getPointAndTangentAtArcLength(geom.samples, 0.5).point;
-          drawEdgeMidpointHandle(ctx, mid, scale);
+          drawEdgeMidpointHandle(ctx, mid, scale, selectionColor);
         }
       }
     }
     if (interaction.mode === "marqueeing" && interaction.marqueeRect) {
-      drawMarquee(ctx, interaction.marqueeRect, scale);
+      drawMarquee(ctx, interaction.marqueeRect, scale, selectionColor);
     }
     if (interaction.mode === "creating-shape" && interaction.createDraftRect) {
-      drawMarquee(ctx, interaction.createDraftRect, scale);
+      drawMarquee(ctx, interaction.createDraftRect, scale, selectionColor);
     }
     if ((interaction.mode === "creating-edge" || interaction.mode === "reconnecting-edge") && interaction.draftEdge) {
       const draft = {
@@ -4453,7 +4973,7 @@ var createRenderer = (opts) => {
         source: interaction.draftEdge.source,
         target: interaction.draftEdge.target,
         pathStyle: "bezier",
-        style: { strokeColor: "#3b82f6" }
+        style: { strokeColor: selectionColor }
       };
       const geom = computeEdgeGeometry(draft, (id) => store.getNode(id));
       if (geom) {
@@ -4557,6 +5077,16 @@ var createRenderer = (opts) => {
       staticDirty = true;
       loop.requestFrame();
     },
+    setSelectionColor(color) {
+      selectionColor = color;
+      interactiveDirty = true;
+      loop.requestFrame();
+    },
+    setHideFrames(hidden) {
+      hideFrames = hidden;
+      staticDirty = true;
+      loop.requestFrame();
+    },
     stats: () => loop.stats(),
     lastDrawCount: () => lastDrawn,
     getOverlaySet: () => [...overlaySet],
@@ -4567,6 +5097,7 @@ var createRenderer = (opts) => {
       unsubSelection();
       unsubInteraction();
       unsubFontEpoch();
+      assetCache.dispose();
     }
   };
 };
@@ -4586,6 +5117,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;
@@ -4616,6 +5148,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;
@@ -5616,6 +6149,8 @@ exports.FONT_FAMILY_MAP = FONT_FAMILY_MAP;
 exports.FONT_SIZE_MAP = FONT_SIZE_MAP;
 exports.LINE_HEIGHT_MAP = LINE_HEIGHT_MAP;
 exports.LINK_COLOR = LINK_COLOR;
+exports.MAX_IMAGE_BYTES = MAX_IMAGE_BYTES;
+exports.MAX_SVG_BYTES = MAX_SVG_BYTES;
 exports.MAX_ZOOM = MAX_ZOOM;
 exports.MIN_ZOOM = MIN_ZOOM;
 exports.PALM_REJECTION_GRACE_MS = PALM_REJECTION_GRACE_MS;
@@ -5627,6 +6162,7 @@ exports.SCHEMA_VERSION = SCHEMA_VERSION;
 exports.UniformGrid = UniformGrid;
 exports.VERSION = VERSION;
 exports.applyCameraTransform = applyCameraTransform;
+exports.applySvgColor = applySvgColor;
 exports.arrowheadLength = arrowheadLength;
 exports.asBatchId = asBatchId;
 exports.asClientId = asClientId;
@@ -5635,6 +6171,7 @@ exports.asGroupId = asGroupId;
 exports.asNodeId = asNodeId;
 exports.attachSync = attachSync;
 exports.autoRouteControls = autoRouteControls;
+exports.blobToDataUri = blobToDataUri;
 exports.clampEffectiveScale = clampEffectiveScale;
 exports.clampZoom = clampZoom;
 exports.clearMeasureCache = clearMeasureCache;
@@ -5656,6 +6193,7 @@ exports.defineExtension = defineExtension;
 exports.defineNode = defineNode;
 exports.deserializeClipboard = deserializeClipboard;
 exports.detectConflicts = detectConflicts;
+exports.downscaleImageBlob = downscaleImageBlob;
 exports.drawArrowhead = drawArrowhead;
 exports.drawEdge = drawEdge;
 exports.drawMinimapViewport = drawMinimapViewport;
@@ -5669,6 +6207,7 @@ exports.estimateMarkdownContentHeight = estimateMarkdownContentHeight;
 exports.exportSelection = exportSelection;
 exports.exportSelectionSvg = exportSelectionSvg;
 exports.exportViewport = exportViewport;
+exports.extractSvgDimensions = extractSvgDimensions;
 exports.fromSerialized = fromSerialized;
 exports.fullVisibleClipResult = fullVisibleClipResult;
 exports.getCanvasFont = getCanvasFont;
@@ -5735,6 +6274,7 @@ exports.rotateVecByAngle = rotateVecByAngle;
 exports.sampleBezier = sampleBezier;
 exports.sampleSelfLoop = sampleSelfLoop;
 exports.samplesFor = samplesFor;
+exports.sanitizeSvg = sanitizeSvg;
 exports.sceneBounds = sceneBounds;
 exports.screenToWorld = screenToWorld;
 exports.selfLoopGeometry = selfLoopGeometry;
@@ -5748,6 +6288,7 @@ exports.sizeSurface = sizeSurface;
 exports.storeToJSON = storeToJSON;
 exports.subscribeFontEpoch = subscribeFontEpoch;
 exports.tangentAtArcLength = tangentAtArcLength;
+exports.toImageBlob = toImageBlob;
 exports.toSerialized = toSerialized;
 exports.toggleBold = toggleBold;
 exports.toggleCode = toggleCode;
@@ -5756,6 +6297,8 @@ exports.toggleStrike = toggleStrike;
 exports.toggleUnderline = toggleUnderline;
 exports.tokenize = tokenize;
 exports.unionRects = unionRects;
+exports.validateImageInput = validateImageInput;
+exports.validateSvgMarkup = validateSvgMarkup;
 exports.viewportWorldRect = viewportWorldRect;
 exports.withAutoFitHeight = withAutoFitHeight;
 exports.worldToNodeLocal = worldToNodeLocal;