@fieldnotes/core 0.50.7 → 0.51.0

package/dist/index.cjs

@@ -239,6 +239,17 @@ function sanitizeAttributes(el, tag) {
 
 // src/core/state-serializer.ts
 var CURRENT_VERSION = 2;
+var ELEMENT_TYPES = [
+  "stroke",
+  "note",
+  "arrow",
+  "image",
+  "html",
+  "text",
+  "shape",
+  "grid",
+  "template"
+];
 function exportState(elements, camera, layers = [], activeLayerId) {
   const state = {
     version: CURRENT_VERSION,
@@ -264,37 +275,42 @@ function parseState(json) {
   return data;
 }
 function validateState(data) {
-  if (!data || typeof data !== "object") {
+  if (!isRecord(data)) {
     throw new Error("Invalid state: expected an object");
   }
   const obj = data;
-  if (typeof obj["version"] !== "number") {
+  if (!Number.isInteger(obj["version"]) || obj["version"] < 1) {
     throw new Error("Invalid state: missing or invalid version");
   }
-  if (!obj["camera"] || typeof obj["camera"] !== "object") {
+  if (obj["version"] > CURRENT_VERSION) {
+    throw new Error(`Invalid state: unsupported version ${String(obj["version"])}`);
+  }
+  if (!isRecord(obj["camera"])) {
     throw new Error("Invalid state: missing camera");
   }
   const cam = obj["camera"];
-  if (!cam["position"] || typeof cam["position"] !== "object") {
+  if (!isRecord(cam["position"])) {
     throw new Error("Invalid state: missing camera.position");
   }
-  const pos = cam["position"];
-  if (typeof pos["x"] !== "number" || typeof pos["y"] !== "number") {
-    throw new Error("Invalid state: camera.position must have x and y numbers");
+  if (!isPoint(cam["position"])) {
+    throw new Error("Invalid state: camera.position must have finite x and y numbers");
   }
-  if (typeof cam["zoom"] !== "number") {
-    throw new Error("Invalid state: missing camera.zoom");
+  if (!isFiniteNumber(cam["zoom"]) || cam["zoom"] <= 0) {
+    throw new Error("Invalid state: camera.zoom must be a positive finite number");
   }
   if (!Array.isArray(obj["elements"])) {
     throw new Error("Invalid state: elements must be an array");
   }
-  for (const el of obj["elements"]) {
-    validateElement(el);
-    migrateElement(el);
+  if (obj["layers"] !== void 0 && !Array.isArray(obj["layers"])) {
+    throw new Error("Invalid state: layers must be an array");
   }
-  cleanBindings(obj["elements"]);
-  const layers = obj["layers"];
-  if (!Array.isArray(layers) || layers.length === 0) {
+  const elements = obj["elements"];
+  const hasLayers = Array.isArray(obj["layers"]) && obj["layers"].length > 0;
+  for (const el of elements) {
+    if (!isRecord(el)) throw new Error("Invalid element: expected an object");
+    migrateElement(el, !hasLayers);
+  }
+  if (!hasLayers) {
     obj["layers"] = [
       {
         id: "default-layer",
@@ -306,31 +322,73 @@ function validateState(data) {
       }
     ];
   }
+  const layers = obj["layers"];
+  const layerIds = /* @__PURE__ */ new Set();
+  for (const layer of layers) {
+    validateLayer(layer);
+    if (layerIds.has(layer.id)) throw new Error(`Invalid state: duplicate layer id "${layer.id}"`);
+    layerIds.add(layer.id);
+  }
+  const elementIds = /* @__PURE__ */ new Set();
+  for (const el of elements) {
+    validateElement(el);
+    if (elementIds.has(el.id)) throw new Error(`Invalid state: duplicate element id "${el.id}"`);
+    elementIds.add(el.id);
+    if (!layerIds.has(el.layerId)) {
+      throw new Error(`Invalid element "${el.id}": unknown layerId "${el.layerId}"`);
+    }
+  }
+  if (obj["activeLayerId"] !== void 0) {
+    if (typeof obj["activeLayerId"] !== "string" || !layerIds.has(obj["activeLayerId"])) {
+      throw new Error("Invalid state: activeLayerId must reference an existing layer");
+    }
+  }
+  cleanBindings(elements);
 }
-var VALID_TYPES = /* @__PURE__ */ new Set([
-  "stroke",
-  "note",
-  "arrow",
-  "image",
-  "html",
-  "text",
-  "shape",
-  "grid",
-  "template"
-]);
 function validateElement(el) {
-  if (!el || typeof el !== "object") {
+  if (!isRecord(el)) {
     throw new Error("Invalid element: expected an object");
   }
-  const obj = el;
-  if (typeof obj["id"] !== "string") {
+  if (typeof el["id"] !== "string" || el["id"].length === 0) {
     throw new Error("Invalid element: missing id");
   }
-  if (typeof obj["type"] !== "string" || !VALID_TYPES.has(obj["type"])) {
-    throw new Error(`Invalid element: unknown type "${String(obj["type"])}"`);
+  if (!isEnum(el["type"], ELEMENT_TYPES)) {
+    throw new Error(`Invalid element: unknown type "${String(el["type"])}"`);
+  }
+  if (!isFiniteNumber(el["zIndex"])) {
+    throw new Error(`Invalid element "${el["id"]}": missing or invalid zIndex`);
+  }
+  if (!isPoint(el["position"]) || typeof el["locked"] !== "boolean" || typeof el["layerId"] !== "string" || !isOptional(el["groupId"], isString) || !isOptional(el["rotation"], isFiniteNumber)) {
+    throw new Error(`Invalid element "${el["id"]}": invalid base fields or geometry`);
+  }
+  const valid = validateTypeFields(el, el["type"]);
+  if (!valid) throw new Error(`Invalid element "${el["id"]}": malformed ${el["type"]} data`);
+}
+function validateTypeFields(el, type) {
+  switch (type) {
+    case "stroke":
+      return Array.isArray(el["points"]) && el["points"].every(isStrokePoint) && isString(el["color"]) && isFiniteNumber(el["width"]) && isFiniteNumber(el["opacity"]) && isOptionalEnum(el["blendMode"], ["multiply"]);
+    case "note":
+      return isSize(el["size"]) && isString(el["text"]) && isString(el["backgroundColor"]) && isString(el["textColor"]) && isOptional(el["fontSize"], isFiniteNumber);
+    case "arrow":
+      return isPoint(el["from"]) && isPoint(el["to"]) && isFiniteNumber(el["bend"]) && isString(el["color"]) && isFiniteNumber(el["width"]) && isOptional(el["fromBinding"], isBinding) && isOptional(el["toBinding"], isBinding) && isOptional(el["cachedControlPoint"], isPoint) && isOptional(el["label"], isString) && isOptionalEnum(el["strokeStyle"], ["solid", "dashed", "dotted"]);
+    case "image":
+      return isSize(el["size"]) && isString(el["src"]);
+    case "html":
+      return isSize(el["size"]) && isOptional(el["domId"], isString) && isOptional(el["interactive"], isBoolean) && isOptional(el["htmlType"], isString) && isOptional(el["data"], isRecord);
+    case "text":
+      return isSize(el["size"]) && isString(el["text"]) && isFiniteNumber(el["fontSize"]) && isString(el["color"]) && isEnum(el["textAlign"], ["left", "center", "right"]);
+    case "shape":
+      return isEnum(el["shape"], ["rectangle", "ellipse", "line"]) && isSize(el["size"]) && isString(el["strokeColor"]) && isFiniteNumber(el["strokeWidth"]) && isString(el["fillColor"]) && isOptional(el["flip"], isBoolean);
+    case "grid":
+      return isEnum(el["gridType"], ["square", "hex"]) && isEnum(el["hexOrientation"], ["pointy", "flat"]) && isFiniteNumber(el["cellSize"]) && isString(el["strokeColor"]) && isFiniteNumber(el["strokeWidth"]) && isFiniteNumber(el["opacity"]);
+    case "template":
+      return isEnum(el["templateShape"], ["circle", "cone", "line", "square", "rectangle"]) && isFiniteNumber(el["radius"]) && isFiniteNumber(el["angle"]) && isOptional(el["width"], isFiniteNumber) && isString(el["fillColor"]) && isString(el["strokeColor"]) && isFiniteNumber(el["strokeWidth"]) && isFiniteNumber(el["opacity"]) && isOptional(el["feetPerCell"], isFiniteNumber) && isOptional(el["radiusFeet"], isFiniteNumber) && isOptionalEnum(el["renderStyle"], ["cells", "geometric"]);
   }
-  if (typeof obj["zIndex"] !== "number") {
-    throw new Error("Invalid element: missing zIndex");
+}
+function validateLayer(layer) {
+  if (!isRecord(layer) || typeof layer["id"] !== "string" || layer["id"].length === 0 || typeof layer["name"] !== "string" || typeof layer["visible"] !== "boolean" || typeof layer["locked"] !== "boolean" || !isFiniteNumber(layer["order"]) || !isFiniteNumber(layer["opacity"]) || layer["opacity"] < 0 || layer["opacity"] > 1) {
+    throw new Error("Invalid state: malformed layer");
   }
 }
 function cleanBindings(elements) {
@@ -347,30 +405,63 @@ function cleanBindings(elements) {
     }
   }
 }
-function migrateElement(obj) {
-  if (typeof obj["layerId"] !== "string") {
+function migrateElement(obj, useDefaultLayer) {
+  if (obj["layerId"] === void 0 || useDefaultLayer && obj["layerId"] === "") {
     obj["layerId"] = "default-layer";
   }
-  if (obj["type"] === "arrow" && typeof obj["bend"] !== "number") {
+  if (obj["type"] === "arrow" && obj["bend"] === void 0) {
     obj["bend"] = 0;
   }
   if (obj["type"] === "stroke" && Array.isArray(obj["points"])) {
     for (const pt of obj["points"]) {
-      if (typeof pt["pressure"] !== "number") {
+      if (pt["pressure"] === void 0) {
         pt["pressure"] = 0.5;
       }
     }
   }
-  if (obj["type"] === "shape" && typeof obj["shape"] !== "string") {
+  if (obj["type"] === "shape" && obj["shape"] === void 0) {
     obj["shape"] = "rectangle";
   }
-  if (obj["type"] === "note" && typeof obj["textColor"] !== "string") {
+  if (obj["type"] === "note" && obj["textColor"] === void 0) {
     obj["textColor"] = "#000000";
   }
   if ((obj["type"] === "note" || obj["type"] === "text") && typeof obj["text"] === "string") {
     obj["text"] = sanitizeNoteHtml(obj["text"]);
   }
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function isBoolean(value) {
+  return typeof value === "boolean";
+}
+function isOptional(value, validate) {
+  return value === void 0 || validate(value);
+}
+function isEnum(value, values) {
+  return typeof value === "string" && values.includes(value);
+}
+function isOptionalEnum(value, values) {
+  return value === void 0 || isEnum(value, values);
+}
+function isPoint(value) {
+  return isRecord(value) && isFiniteNumber(value["x"]) && isFiniteNumber(value["y"]);
+}
+function isSize(value) {
+  return isRecord(value) && isFiniteNumber(value["w"]) && isFiniteNumber(value["h"]);
+}
+function isStrokePoint(value) {
+  return isRecord(value) && isPoint(value) && isFiniteNumber(value["pressure"]);
+}
+function isBinding(value) {
+  return isRecord(value) && typeof value["elementId"] === "string";
+}
 
 // src/core/storage/local-storage-adapter.ts
 var LocalStorageAdapter = class {
@@ -5352,6 +5443,9 @@ function renderTextOnCanvas(ctx, text) {
 }
 
 // src/canvas/export-image.ts
+var DEFAULT_IMAGE_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_DIMENSION = 16384;
+var DEFAULT_MAX_PIXELS = 67108864;
 var center = (b) => ({ x: b.x + b.w / 2, y: b.y + b.h / 2 });
 function getStrokeBounds(el) {
   if (el.type !== "stroke") return null;
@@ -5461,12 +5555,53 @@ function renderGridForBounds(ctx, grid, bounds) {
     );
   }
 }
-function loadImages(elements) {
+function positiveOption(value, fallback, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isFinite(resolved) || resolved <= 0) {
+    throw new RangeError(`${name} must be a finite number greater than 0`);
+  }
+  return resolved;
+}
+function nonNegativeOption(value, fallback, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isFinite(resolved) || resolved < 0) {
+    throw new RangeError(`${name} must be a finite number greater than or equal to 0`);
+  }
+  return resolved;
+}
+function assertExportSize(width, height, options) {
+  const maxDimension = positiveOption(options.maxDimension, DEFAULT_MAX_DIMENSION, "maxDimension");
+  const maxPixels = positiveOption(options.maxPixels, DEFAULT_MAX_PIXELS, "maxPixels");
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    throw new RangeError("Export dimensions must be finite numbers greater than 0");
+  }
+  if (width > maxDimension || height > maxDimension) {
+    throw new RangeError(
+      `Export dimensions ${width}x${height} exceed the maximum dimension of ${maxDimension}`
+    );
+  }
+  if (width * height > maxPixels) {
+    throw new RangeError(
+      `Export size ${width}x${height} exceeds the maximum of ${maxPixels} pixels`
+    );
+  }
+}
+function validateExportResourceOptions(options) {
+  positiveOption(options.imageTimeoutMs, DEFAULT_IMAGE_TIMEOUT_MS, "imageTimeoutMs");
+  positiveOption(options.maxDimension, DEFAULT_MAX_DIMENSION, "maxDimension");
+  positiveOption(options.maxPixels, DEFAULT_MAX_PIXELS, "maxPixels");
+}
+function loadImages(elements, options = {}) {
   const imageElements = elements.filter(
     (el) => el.type === "image" && "src" in el
   );
   const cache3 = /* @__PURE__ */ new Map();
   if (imageElements.length === 0) return Promise.resolve(cache3);
+  const timeoutMs = positiveOption(
+    options.imageTimeoutMs,
+    DEFAULT_IMAGE_TIMEOUT_MS,
+    "imageTimeoutMs"
+  );
   return new Promise((resolve) => {
     let remaining = imageElements.length;
     const done = () => {
@@ -5476,19 +5611,41 @@ function loadImages(elements) {
     for (const el of imageElements) {
       const img = new Image();
       img.crossOrigin = "anonymous";
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        img.onload = null;
+        img.onerror = null;
+        options.onAssetError?.({ elementId: el.id, src: el.src, reason: "timeout" });
+        done();
+      }, timeoutMs);
+      const settle = () => {
+        if (settled) return false;
+        settled = true;
+        clearTimeout(timer);
+        img.onload = null;
+        img.onerror = null;
+        return true;
+      };
       img.onload = () => {
+        if (!settle()) return;
         cache3.set(el.id, img);
         done();
       };
-      img.onerror = done;
-      const sep = el.src.includes("?") ? "&" : "?";
-      img.src = `${el.src}${sep}_cors=1`;
+      img.onerror = (cause) => {
+        if (!settle()) return;
+        options.onAssetError?.({ elementId: el.id, src: el.src, reason: "load", cause });
+        done();
+      };
+      img.src = el.src;
     }
   });
 }
 async function exportImage(store, options = {}, layerManager) {
-  const scale = options.scale ?? 2;
-  const padding = options.padding ?? 0;
+  const scale = positiveOption(options.scale, 2, "scale");
+  const padding = nonNegativeOption(options.padding, 0, "padding");
+  validateExportResourceOptions(options);
   const background = options.background ?? "#ffffff";
   const filter = options.filter;
   const allElements = store.getAll();
@@ -5498,10 +5655,13 @@ async function exportImage(store, options = {}, layerManager) {
   }
   const bounds = computeBounds(visibleElements, padding);
   if (!bounds) return null;
-  const imageCache = await loadImages(visibleElements);
+  const width = Math.ceil(bounds.w * scale);
+  const height = Math.ceil(bounds.h * scale);
+  assertExportSize(width, height, options);
+  const imageCache = await loadImages(visibleElements, options);
   const canvas = document.createElement("canvas");
-  canvas.width = Math.ceil(bounds.w * scale);
-  canvas.height = Math.ceil(bounds.h * scale);
+  canvas.width = width;
+  canvas.height = height;
   const ctx = canvas.getContext("2d");
   if (!ctx) return null;
   ctx.scale(scale, scale);
@@ -5684,14 +5844,17 @@ function emitImage(image, dataUri) {
   const { w, h } = image.size;
   return `<image href="${esc(href)}" x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" />`;
 }
-function emitText(text, rasterScale) {
+function emitText(text, rasterScale, resourceOptions) {
   if (!text.text) return "";
   const { x, y } = text.position;
   const { w, h } = text.size;
   if (typeof document === "undefined") return "";
+  const width = Math.max(1, Math.ceil(w * rasterScale));
+  const height = Math.max(1, Math.ceil(h * rasterScale));
+  assertExportSize(width, height, resourceOptions);
   const canvas = document.createElement("canvas");
-  canvas.width = Math.max(1, Math.ceil(w * rasterScale));
-  canvas.height = Math.max(1, Math.ceil(h * rasterScale));
+  canvas.width = width;
+  canvas.height = height;
   const ctx = canvas.getContext("2d");
   if (!ctx) return "";
   ctx.scale(rasterScale, rasterScale);
@@ -5706,13 +5869,16 @@ function emitText(text, rasterScale) {
   if (!dataUri || !dataUri.startsWith("data:")) return "";
   return `<image href="${esc(dataUri)}" x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" />`;
 }
-function emitNote(note, rasterScale) {
+function emitNote(note, rasterScale, resourceOptions) {
   const { x, y } = note.position;
   const { w, h } = note.size;
   if (typeof document === "undefined") return emitNotePlaceholder(note);
+  const width = Math.max(1, Math.ceil(w * rasterScale));
+  const height = Math.max(1, Math.ceil(h * rasterScale));
+  assertExportSize(width, height, resourceOptions);
   const canvas = document.createElement("canvas");
-  canvas.width = Math.max(1, Math.ceil(w * rasterScale));
-  canvas.height = Math.max(1, Math.ceil(h * rasterScale));
+  canvas.width = width;
+  canvas.height = height;
   const ctx = canvas.getContext("2d");
   if (!ctx) return emitNotePlaceholder(note);
   ctx.scale(rasterScale, rasterScale);
@@ -5873,8 +6039,9 @@ function emitHexTemplate(t, grid) {
   return `<path d="${d}" fill="${esc(t.fillColor)}" stroke="${esc(t.strokeColor)}" stroke-width="${n(t.strokeWidth)}" opacity="${n(t.opacity)}" />`;
 }
 async function exportSvg(store, options = {}, layerManager) {
-  const padding = options.padding ?? 0;
-  const rasterScale = options.rasterScale ?? 2;
+  const padding = nonNegativeOption(options.padding, 0, "padding");
+  const rasterScale = positiveOption(options.rasterScale, 2, "rasterScale");
+  validateExportResourceOptions(options);
   const filter = options.filter;
   const allElements = store.getAll();
   let visibleElements = layerManager ? allElements.filter((el) => layerManager.isLayerVisible(el.layerId)) : allElements;
@@ -5883,11 +6050,12 @@ async function exportSvg(store, options = {}, layerManager) {
   if (!bounds) {
     return `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0" viewBox="0 0 0 0"></svg>`;
   }
+  assertExportSize(Math.ceil(bounds.w), Math.ceil(bounds.h), options);
   const remoteImages = visibleElements.filter(
     (el) => el.type === "image" && !el.src.startsWith("data:")
   );
-  const imageCache = await loadImages(remoteImages);
-  const imageDataUris = encodeImages(visibleElements, imageCache, rasterScale);
+  const imageCache = await loadImages(remoteImages, options);
+  const imageDataUris = encodeImages(visibleElements, imageCache, rasterScale, options);
   const grids = visibleElements.filter((el) => el.type === "grid");
   const firstGrid = grids[0];
   let body = "";
@@ -5896,7 +6064,7 @@ async function exportSvg(store, options = {}, layerManager) {
   }
   const layerBodies = /* @__PURE__ */ new Map();
   for (const el of visibleElements) {
-    const emitted = emitElement(el, imageDataUris, rasterScale, firstGrid, store);
+    const emitted = emitElement(el, imageDataUris, rasterScale, firstGrid, store, options);
     layerBodies.set(el.layerId, (layerBodies.get(el.layerId) ?? "") + emitted);
   }
   for (const [layerId, emitted] of layerBodies) {
@@ -5910,7 +6078,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) {
+function emitElement(el, imageDataUris, rasterScale, firstGrid, store, resourceOptions) {
   switch (el.type) {
     case "stroke":
       return withRotationSvg(el, emitStroke(el));
@@ -5921,9 +6089,9 @@ function emitElement(el, imageDataUris, rasterScale, firstGrid, store) {
     case "image":
       return withRotationSvg(el, emitImage(el, imageDataUris.get(el.id)));
     case "text":
-      return withRotationSvg(el, emitText(el, rasterScale));
+      return withRotationSvg(el, emitText(el, rasterScale, resourceOptions));
     case "note":
-      return withRotationSvg(el, emitNote(el, rasterScale));
+      return withRotationSvg(el, emitNote(el, rasterScale, resourceOptions));
     case "template":
       return emitTemplate(el, firstGrid);
     case "grid":
@@ -5934,7 +6102,7 @@ function emitElement(el, imageDataUris, rasterScale, firstGrid, store) {
       return "";
   }
 }
-function encodeImages(elements, imageCache, rasterScale) {
+function encodeImages(elements, imageCache, rasterScale, resourceOptions) {
   const out = /* @__PURE__ */ new Map();
   for (const el of elements) {
     if (el.type !== "image") continue;
@@ -5944,16 +6112,24 @@ function encodeImages(elements, imageCache, rasterScale) {
     }
     const img = imageCache.get(el.id);
     if (!img || typeof document === "undefined") continue;
+    const width = Math.max(1, Math.ceil(el.size.w * rasterScale));
+    const height = Math.max(1, Math.ceil(el.size.h * rasterScale));
+    assertExportSize(width, height, resourceOptions);
     const canvas = document.createElement("canvas");
-    canvas.width = Math.max(1, Math.ceil(el.size.w * rasterScale));
-    canvas.height = Math.max(1, Math.ceil(el.size.h * rasterScale));
+    canvas.width = width;
+    canvas.height = height;
     const ctx = canvas.getContext("2d");
-    if (!ctx) continue;
+    if (!ctx) {
+      resourceOptions.onAssetError?.({ elementId: el.id, src: el.src, reason: "encode" });
+      continue;
+    }
     try {
       ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
       const uri = canvas.toDataURL();
       if (uri.startsWith("data:")) out.set(el.id, uri);
-    } catch {
+      else resourceOptions.onAssetError?.({ elementId: el.id, src: el.src, reason: "encode" });
+    } catch (cause) {
+      resourceOptions.onAssetError?.({ elementId: el.id, src: el.src, reason: "encode", cause });
     }
   }
   return out;
@@ -10726,7 +10902,7 @@ var LaserTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.50.7";
+var VERSION = "0.51.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArrowTool,