@fieldnotes/core 0.51.0 → 0.52.1

package/README.md

@@ -80,7 +80,8 @@ card.querySelector('button').addEventListener('click', () => {
 const elementId = viewport.addHtmlElement(card, { x: 100, y: 200 }, { w: 250, h: 150 });
 ```
 
-HTML elements pan, zoom, and resize with the canvas. They use a **two-mode interaction model**:
+HTML elements pan, zoom, resize, and interleave by layer/`zIndex` with canvas-rendered content. They
+use a **two-mode interaction model**:
 
 - **Default** — the element can be selected, dragged, and resized like any other element
 - **Double-click** — enters interact mode, making buttons, inputs, and links work
@@ -164,9 +165,30 @@ const blob = await viewport.exportImage({
 });
 ```
 
-HTML elements are currently excluded from image exports. Remote images are requested with anonymous
-CORS using their original URLs; failures are omitted from the result and reported through
-`onAssetError` when supplied.
+Remote images are requested with anonymous CORS using their original URLs; failures are omitted from
+the result and reported through `onAssetError` when supplied.
+
+Application-owned HTML embeds require an explicit rasterization hook. Return a ready canvas-compatible
+image source; Field Notes applies the element's size, rotation, paint order, and layer opacity in both
+PNG and SVG exports:
+
+```typescript
+const options = {
+  htmlTimeoutMs: 10_000,
+  renderHtml: async (element) => {
+    const node = document.querySelector(`[data-element-id="${element.id}"]`);
+    return node ? rasterizeToCanvas(node) : null; // application or library implementation
+  },
+  onHtmlError: ({ elementId, reason }) => {
+    console.warn(`Could not export HTML element ${elementId}: ${reason}`);
+  },
+};
+
+const png = await viewport.exportImage(options);
+const svg = await viewport.exportSVG(options);
+```
+
+Without `renderHtml`, embeds remain omitted and can be observed through `onHtmlError`.
 
 ## Performance Monitoring
 

package/dist/index.cjs

@@ -4921,6 +4921,57 @@ function createDomLayer() {
   });
   return el;
 }
+function createPaintStack() {
+  const el = createDomLayer();
+  el.dataset["fieldnotesPaintStack"] = "";
+  el.style.transformOrigin = "";
+  return el;
+}
+
+// src/canvas/hybrid-render-surface.ts
+var HybridRenderSurface = class {
+  constructor(root) {
+    this.root = root;
+  }
+  canvases = /* @__PURE__ */ new Map();
+  beginFrame(activeOrders, width, height) {
+    for (const [order, canvas] of this.canvases) {
+      if (!activeOrders.has(order)) {
+        canvas.remove();
+        this.canvases.delete(order);
+      }
+    }
+    for (const order of activeOrders) {
+      const canvas = this.getCanvas(order);
+      if (canvas.width !== width) canvas.width = width;
+      if (canvas.height !== height) canvas.height = height;
+      canvas.style.zIndex = String(order);
+    }
+  }
+  getContext(order) {
+    return this.getCanvas(order).getContext("2d");
+  }
+  clear() {
+    for (const canvas of this.canvases.values()) canvas.remove();
+    this.canvases.clear();
+  }
+  getCanvas(order) {
+    let canvas = this.canvases.get(order);
+    if (canvas) return canvas;
+    canvas = document.createElement("canvas");
+    canvas.dataset["paintOrder"] = String(order);
+    Object.assign(canvas.style, {
+      position: "absolute",
+      inset: "0",
+      width: "100%",
+      height: "100%",
+      pointerEvents: "none"
+    });
+    this.root.appendChild(canvas);
+    this.canvases.set(order, canvas);
+    return canvas;
+  }
+};
 
 // src/elements/arrow-label-editor.ts
 var ArrowLabelEditor = class {
@@ -5442,6 +5493,67 @@ function renderTextOnCanvas(ctx, text) {
   ctx.restore();
 }
 
+// src/canvas/html-export.ts
+var DEFAULT_HTML_TIMEOUT_MS = 1e4;
+var TIMEOUT = /* @__PURE__ */ Symbol("html-export-timeout");
+function validateHtmlExportOptions(options) {
+  const timeoutMs = options.htmlTimeoutMs ?? DEFAULT_HTML_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new RangeError("htmlTimeoutMs must be a finite number greater than 0");
+  }
+  return timeoutMs;
+}
+async function renderHtmlElements(elements, options) {
+  const timeoutMs = validateHtmlExportOptions(options);
+  const sources = /* @__PURE__ */ new Map();
+  await Promise.all(
+    elements.map(async (element) => {
+      if (!options.renderHtml) {
+        options.onHtmlError?.({
+          elementId: element.id,
+          htmlType: element.htmlType,
+          reason: "unsupported"
+        });
+        return;
+      }
+      let timer;
+      try {
+        const timeout = new Promise((resolve) => {
+          timer = setTimeout(() => resolve(TIMEOUT), timeoutMs);
+        });
+        const result = await Promise.race([Promise.resolve(options.renderHtml(element)), timeout]);
+        if (result === TIMEOUT) {
+          options.onHtmlError?.({
+            elementId: element.id,
+            htmlType: element.htmlType,
+            reason: "timeout"
+          });
+          return;
+        }
+        if (!result) {
+          options.onHtmlError?.({
+            elementId: element.id,
+            htmlType: element.htmlType,
+            reason: "render"
+          });
+          return;
+        }
+        sources.set(element.id, result);
+      } catch (cause) {
+        options.onHtmlError?.({
+          elementId: element.id,
+          htmlType: element.htmlType,
+          reason: "render",
+          cause
+        });
+      } finally {
+        if (timer !== void 0) clearTimeout(timer);
+      }
+    })
+  );
+  return sources;
+}
+
 // src/canvas/export-image.ts
 var DEFAULT_IMAGE_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_DIMENSION = 16384;
@@ -5646,6 +5758,7 @@ async function exportImage(store, options = {}, layerManager) {
   const scale = positiveOption(options.scale, 2, "scale");
   const padding = nonNegativeOption(options.padding, 0, "padding");
   validateExportResourceOptions(options);
+  validateHtmlExportOptions(options);
   const background = options.background ?? "#ffffff";
   const filter = options.filter;
   const allElements = store.getAll();
@@ -5659,6 +5772,8 @@ async function exportImage(store, options = {}, layerManager) {
   const height = Math.ceil(bounds.h * scale);
   assertExportSize(width, height, options);
   const imageCache = await loadImages(visibleElements, options);
+  const htmlElements = visibleElements.filter((el) => el.type === "html");
+  const htmlSources = await renderHtmlElements(htmlElements, options);
   const canvas = document.createElement("canvas");
   canvas.width = width;
   canvas.height = height;
@@ -5683,6 +5798,24 @@ async function exportImage(store, options = {}, layerManager) {
       return;
     }
     if (el.type === "html") {
+      const source = htmlSources.get(el.id);
+      if (!source) return;
+      const b = getElementBounds(el);
+      try {
+        withRotation(
+          target,
+          el,
+          b ? center(b) : el.position,
+          () => target.drawImage(source, el.position.x, el.position.y, el.size.w, el.size.h)
+        );
+      } catch (cause) {
+        options.onHtmlError?.({
+          elementId: el.id,
+          htmlType: el.htmlType,
+          reason: "render",
+          cause
+        });
+      }
       return;
     }
     if (el.type === "image") {
@@ -5838,7 +5971,7 @@ function emitArrow(arrow, store) {
   return out;
 }
 function emitImage(image, dataUri) {
-  const href = dataUri ?? image.src;
+  const href = dataUri ?? ("src" in image ? image.src : "");
   if (!href) return "";
   const { x, y } = image.position;
   const { w, h } = image.size;
@@ -6042,6 +6175,7 @@ async function exportSvg(store, options = {}, layerManager) {
   const padding = nonNegativeOption(options.padding, 0, "padding");
   const rasterScale = positiveOption(options.rasterScale, 2, "rasterScale");
   validateExportResourceOptions(options);
+  validateHtmlExportOptions(options);
   const filter = options.filter;
   const allElements = store.getAll();
   let visibleElements = layerManager ? allElements.filter((el) => layerManager.isLayerVisible(el.layerId)) : allElements;
@@ -6056,6 +6190,9 @@ async function exportSvg(store, options = {}, layerManager) {
   );
   const imageCache = await loadImages(remoteImages, options);
   const imageDataUris = encodeImages(visibleElements, imageCache, rasterScale, options);
+  const htmlElements = visibleElements.filter((el) => el.type === "html");
+  const htmlSources = await renderHtmlElements(htmlElements, options);
+  const htmlDataUris = encodeHtmlElements(htmlElements, htmlSources, rasterScale, options);
   const grids = visibleElements.filter((el) => el.type === "grid");
   const firstGrid = grids[0];
   let body = "";
@@ -6064,7 +6201,15 @@ async function exportSvg(store, options = {}, layerManager) {
   }
   const layerBodies = /* @__PURE__ */ new Map();
   for (const el of visibleElements) {
-    const emitted = emitElement(el, imageDataUris, rasterScale, firstGrid, store, options);
+    const emitted = emitElement(
+      el,
+      imageDataUris,
+      htmlDataUris,
+      rasterScale,
+      firstGrid,
+      store,
+      options
+    );
     layerBodies.set(el.layerId, (layerBodies.get(el.layerId) ?? "") + emitted);
   }
   for (const [layerId, emitted] of layerBodies) {
@@ -6078,7 +6223,7 @@ async function exportSvg(store, options = {}, layerManager) {
   }
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${n(bounds.w)}" height="${n(bounds.h)}" viewBox="${n(bounds.x)} ${n(bounds.y)} ${n(bounds.w)} ${n(bounds.h)}">${body}</svg>`;
 }
-function emitElement(el, imageDataUris, rasterScale, firstGrid, store, resourceOptions) {
+function emitElement(el, imageDataUris, htmlDataUris, rasterScale, firstGrid, store, resourceOptions) {
   switch (el.type) {
     case "stroke":
       return withRotationSvg(el, emitStroke(el));
@@ -6097,11 +6242,62 @@ function emitElement(el, imageDataUris, rasterScale, firstGrid, store, resourceO
     case "grid":
       return "";
     case "html":
-      return "";
+      return withRotationSvg(el, emitImage(el, htmlDataUris.get(el.id)));
     default:
       return "";
   }
 }
+function encodeHtmlElements(elements, sources, rasterScale, options) {
+  const encoded = /* @__PURE__ */ new Map();
+  for (const element of elements) {
+    const source = sources.get(element.id);
+    if (!source) continue;
+    const width = Math.max(1, Math.ceil(element.size.w * rasterScale));
+    const height = Math.max(1, Math.ceil(element.size.h * rasterScale));
+    assertExportSize(width, height, options);
+    if (typeof document === "undefined") {
+      options.onHtmlError?.({
+        elementId: element.id,
+        htmlType: element.htmlType,
+        reason: "encode"
+      });
+      continue;
+    }
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) {
+      options.onHtmlError?.({
+        elementId: element.id,
+        htmlType: element.htmlType,
+        reason: "encode"
+      });
+      continue;
+    }
+    try {
+      ctx.drawImage(source, 0, 0, width, height);
+      const dataUri = canvas.toDataURL();
+      if (dataUri.startsWith("data:")) {
+        encoded.set(element.id, dataUri);
+      } else {
+        options.onHtmlError?.({
+          elementId: element.id,
+          htmlType: element.htmlType,
+          reason: "encode"
+        });
+      }
+    } catch (cause) {
+      options.onHtmlError?.({
+        elementId: element.id,
+        htmlType: element.htmlType,
+        reason: "encode",
+        cause
+      });
+    }
+  }
+  return encoded;
+}
 function encodeImages(elements, imageCache, rasterScale, resourceOptions) {
   const out = /* @__PURE__ */ new Map();
   for (const el of elements) {
@@ -6394,6 +6590,7 @@ var DoubleTapDetector = class {
 // src/canvas/dom-node-manager.ts
 var DomNodeManager = class {
   domNodes = /* @__PURE__ */ new Map();
+  strata = /* @__PURE__ */ new Map();
   htmlContent = /* @__PURE__ */ new Map();
   domLayer;
   onEditRequest;
@@ -6402,6 +6599,7 @@ var DomNodeManager = class {
   lastSyncedVersion = /* @__PURE__ */ new Map();
   lastSyncedZIndex = /* @__PURE__ */ new Map();
   lastSyncedOpacity = /* @__PURE__ */ new Map();
+  cameraTransform = "";
   constructor(deps) {
     this.domLayer = deps.domLayer;
     this.onEditRequest = deps.onEditRequest;
@@ -6411,6 +6609,11 @@ var DomNodeManager = class {
   getNode(id) {
     return this.domNodes.get(id);
   }
+  setCameraTransform(transform) {
+    if (transform === this.cameraTransform) return;
+    this.cameraTransform = transform;
+    for (const stratum of this.strata.values()) stratum.style.transform = transform;
+  }
   storeHtmlContent(elementId, dom) {
     this.htmlContent.set(elementId, dom);
   }
@@ -6438,7 +6641,7 @@ var DomNodeManager = class {
         position: "absolute",
         pointerEvents: "auto"
       });
-      this.domLayer.appendChild(node);
+      this.getStratum(zIndex).appendChild(node);
       this.domNodes.set(element.id, node);
     } else if (this.getVersion) {
       const currentVersion = this.getVersion(element.id);
@@ -6449,6 +6652,15 @@ var DomNodeManager = class {
         return;
       }
     }
+    if (node.parentElement !== this.getStratum(zIndex)) {
+      const previousStratum = node.parentElement;
+      this.getStratum(zIndex).appendChild(node);
+      if (previousStratum?.childElementCount === 0) {
+        const previousOrder = Number(previousStratum.dataset["paintOrder"]);
+        previousStratum.remove();
+        this.strata.delete(previousOrder);
+      }
+    }
     if (this.getVersion) {
       this.lastSyncedVersion.set(element.id, this.getVersion(element.id));
       this.lastSyncedZIndex.set(element.id, zIndex);
@@ -6470,7 +6682,10 @@ var DomNodeManager = class {
   }
   hideDomNode(id) {
     const node = this.domNodes.get(id);
-    if (node) node.style.display = "none";
+    if (node) {
+      node.style.display = "none";
+      this.lastSyncedVersion.delete(id);
+    }
   }
   removeDomNode(id) {
     this.htmlContent.delete(id);
@@ -6479,8 +6694,14 @@ var DomNodeManager = class {
     this.lastSyncedOpacity.delete(id);
     const node = this.domNodes.get(id);
     if (node) {
+      const stratum = node.parentElement;
       node.remove();
       this.domNodes.delete(id);
+      if (stratum?.childElementCount === 0) {
+        const order = Number(stratum.dataset["paintOrder"]);
+        stratum.remove();
+        this.strata.delete(order);
+      }
     }
   }
   clearDomNodes() {
@@ -6490,6 +6711,27 @@ var DomNodeManager = class {
     this.lastSyncedVersion.clear();
     this.lastSyncedZIndex.clear();
     this.lastSyncedOpacity.clear();
+    for (const stratum of this.strata.values()) stratum.remove();
+    this.strata.clear();
+  }
+  getStratum(order) {
+    let stratum = this.strata.get(order);
+    if (stratum) return stratum;
+    stratum = document.createElement("div");
+    stratum.dataset["paintOrder"] = String(order);
+    Object.assign(stratum.style, {
+      position: "absolute",
+      inset: "0",
+      width: "100%",
+      height: "100%",
+      pointerEvents: "none",
+      transformOrigin: "0 0",
+      transform: this.cameraTransform,
+      zIndex: String(order)
+    });
+    this.domLayer.appendChild(stratum);
+    this.strata.set(order, stratum);
+    return stratum;
   }
   reattachHtmlContent(store) {
     for (const el of store.getElementsByType("html")) {
@@ -6671,6 +6913,7 @@ var RenderLoop = class {
   domNodeManager;
   layerCache;
   marginViewport;
+  hybridSurface;
   activeDrawingLayerId = null;
   gridCacheDirty = true;
   // set on recenter/viewport-change; consumed by the grid block
@@ -6690,6 +6933,7 @@ var RenderLoop = class {
     this.domNodeManager = deps.domNodeManager;
     this.layerCache = deps.layerCache;
     this.marginViewport = deps.marginViewport;
+    this.hybridSurface = deps.hybridSurface;
   }
   requestRender() {
     this.needsRender = true;
@@ -6810,9 +7054,19 @@ var RenderLoop = class {
       h: cullBounds.h + cullPad * 2
     };
     const allElements = this.store.getAll();
+    const visibleElements = allElements.filter(
+      (element) => this.layerManager.isLayerVisible(element.layerId)
+    );
+    const firstDomIndex = visibleElements.findIndex(
+      (element) => this.renderer.isDomElement(element)
+    );
+    const hybridActive = firstDomIndex >= 0 && visibleElements.slice(firstDomIndex + 1).some((element) => !this.renderer.isDomElement(element));
+    const hybridCanvasRuns = /* @__PURE__ */ new Map();
+    const hybridOrders = /* @__PURE__ */ new Set();
+    let activeHybridOrder = null;
     this.layerGroups.clear();
     const gridElements = [];
-    let domZIndex = 0;
+    let paintOrder = 0;
     for (const element of allElements) {
       if (!this.layerManager.isLayerVisible(element.layerId)) {
         if (this.renderer.isDomElement(element)) {
@@ -6820,16 +7074,29 @@ var RenderLoop = class {
         }
         continue;
       }
+      const order = ++paintOrder;
       if (this.renderer.isDomElement(element)) {
+        activeHybridOrder = null;
         const layerOpacity = this.layerManager.getLayer?.(element.layerId)?.opacity ?? 1;
         const elBounds = getElementBounds(element);
         if (elBounds && !boundsIntersect(elBounds, cullingRect)) {
           this.domNodeManager.hideDomNode(element.id);
         } else {
-          this.domNodeManager.syncDomNode(element, domZIndex++, layerOpacity);
+          this.domNodeManager.syncDomNode(element, order, layerOpacity);
         }
         continue;
       }
+      if (hybridActive && paintOrder > firstDomIndex + 1 && element.type !== "grid") {
+        activeHybridOrder ??= order;
+        let run = hybridCanvasRuns.get(activeHybridOrder);
+        if (!run) {
+          run = [];
+          hybridCanvasRuns.set(activeHybridOrder, run);
+          hybridOrders.add(activeHybridOrder);
+        }
+        run.push(element);
+        continue;
+      }
       if (element.type === "grid") {
         gridElements.push(element);
         continue;
@@ -6841,6 +7108,10 @@ var RenderLoop = class {
       }
       group.push(element);
     }
+    const activeTool = this.toolManager.activeTool;
+    const overlayOrder = visibleElements.length + 1;
+    if (hybridActive && activeTool?.renderOverlay) hybridOrders.add(overlayOrder);
+    this.hybridSurface.beginFrame(hybridOrders, this.canvasEl.width, this.canvasEl.height);
     for (const [layerId, elements] of this.layerGroups) {
       const isActiveDrawingLayer = layerId === this.activeDrawingLayerId;
       const layerOpacity = this.layerManager.getLayer?.(layerId)?.opacity ?? 1;
@@ -6930,9 +7201,37 @@ var RenderLoop = class {
     } else {
       this.lastGridRefs = [];
     }
+    for (const [order, elements] of hybridCanvasRuns) {
+      const hybridCtx = this.hybridSurface.getContext(order);
+      if (!hybridCtx) continue;
+      hybridCtx.clearRect(0, 0, this.canvasEl.width, this.canvasEl.height);
+      hybridCtx.save();
+      hybridCtx.scale(dpr, dpr);
+      hybridCtx.translate(this.camera.position.x, this.camera.position.y);
+      hybridCtx.scale(this.camera.zoom, this.camera.zoom);
+      for (const element of elements) {
+        const elBounds = getElementBounds(element);
+        if (elBounds && !boundsIntersect(elBounds, cullingRect)) continue;
+        hybridCtx.save();
+        hybridCtx.globalAlpha = this.layerManager.getLayer?.(element.layerId)?.opacity ?? 1;
+        this.renderer.renderCanvasElement(hybridCtx, element);
+        hybridCtx.restore();
+      }
+      hybridCtx.restore();
+    }
     const overlayT0 = performance.now();
-    const activeTool = this.toolManager.activeTool;
-    if (activeTool?.renderOverlay) {
+    if (hybridActive && activeTool?.renderOverlay) {
+      const overlayCtx = this.hybridSurface.getContext(overlayOrder);
+      if (overlayCtx) {
+        overlayCtx.clearRect(0, 0, this.canvasEl.width, this.canvasEl.height);
+        overlayCtx.save();
+        overlayCtx.scale(dpr, dpr);
+        overlayCtx.translate(this.camera.position.x, this.camera.position.y);
+        overlayCtx.scale(this.camera.zoom, this.camera.zoom);
+        activeTool.renderOverlay(overlayCtx);
+        overlayCtx.restore();
+      }
+    } else if (activeTool?.renderOverlay) {
       activeTool.renderOverlay(ctx);
     }
     const overlayMs = performance.now() - overlayT0;
@@ -7683,8 +7982,11 @@ var Viewport = class {
     });
     this.wrapper = createWrapper();
     this.canvasEl = createCanvas();
+    this.paintStack = createPaintStack();
     this.domLayer = createDomLayer();
+    this.domLayer.style.zIndex = "2147483647";
     this.wrapper.appendChild(this.canvasEl);
+    this.wrapper.appendChild(this.paintStack);
     this.wrapper.appendChild(this.domLayer);
     this.container.appendChild(this.wrapper);
     this.toolContext = {
@@ -7754,11 +8056,12 @@ var Viewport = class {
       this.minimap.scheduleDraw();
     }
     this.domNodeManager = new DomNodeManager({
-      domLayer: this.domLayer,
+      domLayer: this.paintStack,
       onEditRequest: (id) => this.interactions.startEditingElement(id),
       isEditingElement: (id) => this.noteEditor.isEditing && this.noteEditor.editingElementId === id,
       getVersion: (id) => this.store.getVersion(id)
     });
+    this.domNodeManager.setCameraTransform(this.camera.toCSSTransform());
     this.interactMode = new InteractMode({
       getNode: (id) => this.domNodeManager.getNode(id)
     });
@@ -7779,7 +8082,8 @@ var Viewport = class {
       layerManager: this.layerManager,
       domNodeManager: this.domNodeManager,
       layerCache,
-      marginViewport: this.marginViewport
+      marginViewport: this.marginViewport,
+      hybridSurface: new HybridRenderSurface(this.paintStack)
     });
     this.unsubCamera = this.camera.onChange(() => {
       this.applyCameraTransform();
@@ -7866,6 +8170,7 @@ var Viewport = class {
   history;
   domLayer;
   canvasEl;
+  paintStack;
   wrapper;
   unsubCamera;
   unsubToolChange;
@@ -8221,7 +8526,9 @@ var Viewport = class {
     }
   }
   applyCameraTransform() {
-    this.domLayer.style.transform = this.camera.toCSSTransform();
+    const transform = this.camera.toCSSTransform();
+    this.domLayer.style.transform = transform;
+    this.domNodeManager.setCameraTransform(transform);
   }
   syncCanvasSize() {
     const rect = this.container.getBoundingClientRect();
@@ -10902,7 +11209,7 @@ var LaserTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.51.0";
+var VERSION = "0.52.1";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArrowTool,