@fieldnotes/core 0.6.0 → 0.7.0

package/README.md

@@ -7,12 +7,15 @@ A lightweight, framework-agnostic infinite canvas SDK for the web — with first
 - **Infinite canvas** — pan, zoom, pinch-to-zoom
 - **Freehand drawing** — pencil tool with stroke smoothing and pressure-sensitive width
 - **Sticky notes** — editable text notes with customizable colors
-- **Arrows** — curved bezier arrows with draggable control points
-- **Images** — drag & drop or programmatic placement
+- **Arrows** — curved bezier arrows with element binding
+- **Shapes** — rectangles, ellipses with fill and stroke
+- **Text** — standalone text elements with font size and alignment
+- **Images** — drag & drop or programmatic placement (canvas-rendered for proper layer ordering)
 - **HTML embedding** — add any DOM element as a fully interactive canvas citizen
-- **Select & multi-select** — click, drag box, move, resize
+- **Layers** — named layers with visibility, locking, and absolute ordering
+- **Select & multi-select** — click, drag box, move, resize (layer-aware)
 - **Undo / redo** — full history stack with configurable depth
-- **State serialization** — export/import JSON snapshots
+- **State serialization** — export/import JSON snapshots with automatic migration
 - **Touch & tablet** — Pointer Events API, pinch-to-zoom, two-finger pan, stylus pressure
 - **Zero dependencies** — vanilla TypeScript, no framework required
 - **Tree-shakeable** — ESM + CJS output
@@ -91,10 +94,13 @@ viewport.stopInteracting();
 ```typescript
 // Programmatic
 viewport.addImage('https://example.com/photo.jpg', { x: 0, y: 0 });
+viewport.addImage('/assets/map.png', { x: 0, y: 0 }, { w: 800, h: 600 });
 
 // Drag & drop is handled automatically — drop images onto the canvas
 ```
 
+> **Important: Use URLs, not base64 data URLs.** Images are stored inline in the serialized state. A single base64-encoded photo can be 2-5MB, which will blow past the `localStorage` ~5MB quota and make JSON exports impractical. Upload images to your server or CDN and use the URL. For offline/local-first apps, store blobs in IndexedDB and reference them by URL.
+
 ## Camera Control
 
 ```typescript
@@ -147,6 +153,45 @@ viewport.history.onChange(() => {
 });
 ```
 
+## Layers
+
+Organize elements into named layers with visibility, lock, and ordering controls. All elements on a higher layer render above all elements on a lower layer, regardless of individual z-index.
+
+```typescript
+const { layerManager } = viewport;
+
+// Create layers
+const background = layerManager.activeLayer; // "Layer 1" exists by default
+layerManager.renameLayer(background.id, 'Map');
+const tokens = layerManager.createLayer('Tokens');
+const notes = layerManager.createLayer('Notes');
+
+// Set active layer — new elements are created on the active layer
+layerManager.setActiveLayer(tokens.id);
+
+// Visibility and locking
+layerManager.setLayerVisible(background.id, false); // hide
+layerManager.setLayerLocked(background.id, true); // prevent selection/editing
+
+// Move elements between layers
+layerManager.moveElementToLayer(elementId, notes.id);
+
+// Reorder layers
+layerManager.reorderLayer(tokens.id, 5); // higher order = renders on top
+
+// Query
+layerManager.getLayers(); // sorted by order
+layerManager.isLayerVisible(id);
+layerManager.isLayerLocked(id);
+
+// Listen for changes
+layerManager.on('change', () => {
+  /* update UI */
+});
+```
+
+Locked layers prevent selection, erasing, and arrow binding on their elements. Hidden layers are invisible and non-interactive. The active layer cannot be hidden or locked — if you try, it automatically switches to the next available layer.
+
 ## State Serialization
 
 ```typescript
@@ -158,6 +203,8 @@ localStorage.setItem('canvas', json);
 viewport.loadJSON(localStorage.getItem('canvas'));
 ```
 
+> **Note:** Serialized state includes all layers and element `layerId` assignments. States saved before layers were introduced are automatically migrated — elements are placed on a default "Layer 1".
+
 ## Tool Switching
 
 ```typescript
@@ -296,16 +343,19 @@ interface BaseElement {
   position: { x: number; y: number };
   zIndex: number;
   locked: boolean;
+  layerId: string;
 }
 ```
 
-| Type     | Key Fields                                           |
-| -------- | ---------------------------------------------------- |
-| `stroke` | `points: StrokePoint[]`, `color`, `width`, `opacity` |
-| `note`   | `size`, `text`, `backgroundColor`                    |
-| `arrow`  | `from`, `to`, `bend`, `color`, `width`               |
-| `image`  | `size`, `src`                                        |
-| `html`   | `size`                                               |
+| Type     | Key Fields                                                             |
+| -------- | ---------------------------------------------------------------------- |
+| `stroke` | `points: StrokePoint[]`, `color`, `width`, `opacity`                   |
+| `note`   | `size`, `text`, `backgroundColor`, `textColor`                         |
+| `arrow`  | `from`, `to`, `bend`, `color`, `width`, `fromBinding`, `toBinding`     |
+| `image`  | `size`, `src`                                                          |
+| `shape`  | `size`, `shape` (`rectangle` \| `ellipse`), `strokeColor`, `fillColor` |
+| `text`   | `size`, `text`, `fontSize`, `color`, `textAlign`                       |
+| `html`   | `size`                                                                 |
 
 ## Built-in Interactions
 

package/dist/index.cjs

@@ -52,6 +52,7 @@ __export(index_exports, {
   Viewport: () => Viewport,
   clearStaleBindings: () => clearStaleBindings,
   createArrow: () => createArrow,
+  createGrid: () => createGrid,
   createHtmlElement: () => createHtmlElement,
   createId: () => createId,
   createImage: () => createImage,
@@ -165,7 +166,7 @@ function validateState(data) {
     ];
   }
 }
-var VALID_TYPES = /* @__PURE__ */ new Set(["stroke", "note", "arrow", "image", "html", "text", "shape"]);
+var VALID_TYPES = /* @__PURE__ */ new Set(["stroke", "note", "arrow", "image", "html", "text", "shape", "grid"]);
 function validateElement(el) {
   if (!el || typeof el !== "object") {
     throw new Error("Invalid element: expected an object");
@@ -286,7 +287,11 @@ var AutoSave = class {
     if (typeof localStorage === "undefined") return;
     const layers = this.layerManager?.snapshot() ?? [];
     const state = exportState(this.store.snapshot(), this.camera, layers);
-    localStorage.setItem(this.key, JSON.stringify(state));
+    try {
+      localStorage.setItem(this.key, JSON.stringify(state));
+    } catch {
+      console.warn("Auto-save failed: storage quota exceeded. State too large for localStorage.");
+    }
   }
 };
 
@@ -1022,6 +1027,118 @@ function smoothToSegments(points) {
   return segments;
 }
 
+// src/elements/grid-renderer.ts
+function getSquareGridLines(bounds, cellSize) {
+  if (cellSize <= 0) return { verticals: [], horizontals: [] };
+  const verticals = [];
+  const startX = Math.floor(bounds.minX / cellSize) * cellSize;
+  const endX = Math.ceil(bounds.maxX / cellSize) * cellSize;
+  for (let x = startX; x <= endX; x += cellSize) {
+    verticals.push(x);
+  }
+  const horizontals = [];
+  const startY = Math.floor(bounds.minY / cellSize) * cellSize;
+  const endY = Math.ceil(bounds.maxY / cellSize) * cellSize;
+  for (let y = startY; y <= endY; y += cellSize) {
+    horizontals.push(y);
+  }
+  return { verticals, horizontals };
+}
+function getHexVertices(cx, cy, circumradius, orientation) {
+  const vertices = [];
+  const angleOffset = orientation === "pointy" ? -Math.PI / 2 : 0;
+  for (let i = 0; i < 6; i++) {
+    const angle = Math.PI / 3 * i + angleOffset;
+    vertices.push({
+      x: cx + circumradius * Math.cos(angle),
+      y: cy + circumradius * Math.sin(angle)
+    });
+  }
+  return vertices;
+}
+function getHexCenters(bounds, circumradius, orientation) {
+  if (circumradius <= 0) return [];
+  const centers = [];
+  if (orientation === "pointy") {
+    const hexW = Math.sqrt(3) * circumradius;
+    const hexH = 2 * circumradius;
+    const rowH = hexH * 0.75;
+    const startRow = Math.floor((bounds.minY - circumradius) / rowH);
+    const endRow = Math.ceil((bounds.maxY + circumradius) / rowH);
+    const startCol = Math.floor((bounds.minX - hexW) / hexW);
+    const endCol = Math.ceil((bounds.maxX + hexW) / hexW);
+    for (let row = startRow; row <= endRow; row++) {
+      const offsetX = row % 2 !== 0 ? hexW / 2 : 0;
+      for (let col = startCol; col <= endCol; col++) {
+        centers.push({
+          x: col * hexW + offsetX,
+          y: row * rowH
+        });
+      }
+    }
+  } else {
+    const hexW = 2 * circumradius;
+    const hexH = Math.sqrt(3) * circumradius;
+    const colW = hexW * 0.75;
+    const startCol = Math.floor((bounds.minX - circumradius) / colW);
+    const endCol = Math.ceil((bounds.maxX + circumradius) / colW);
+    const startRow = Math.floor((bounds.minY - hexH) / hexH);
+    const endRow = Math.ceil((bounds.maxY + hexH) / hexH);
+    for (let col = startCol; col <= endCol; col++) {
+      const offsetY = col % 2 !== 0 ? hexH / 2 : 0;
+      for (let row = startRow; row <= endRow; row++) {
+        centers.push({
+          x: col * colW,
+          y: row * hexH + offsetY
+        });
+      }
+    }
+  }
+  return centers;
+}
+function renderSquareGrid(ctx, bounds, cellSize, strokeColor, strokeWidth, opacity) {
+  if (cellSize <= 0) return;
+  const { verticals, horizontals } = getSquareGridLines(bounds, cellSize);
+  ctx.save();
+  ctx.strokeStyle = strokeColor;
+  ctx.lineWidth = strokeWidth;
+  ctx.globalAlpha = opacity;
+  ctx.beginPath();
+  for (const x of verticals) {
+    ctx.moveTo(x, bounds.minY);
+    ctx.lineTo(x, bounds.maxY);
+  }
+  for (const y of horizontals) {
+    ctx.moveTo(bounds.minX, y);
+    ctx.lineTo(bounds.maxX, y);
+  }
+  ctx.stroke();
+  ctx.restore();
+}
+function renderHexGrid(ctx, bounds, cellSize, orientation, strokeColor, strokeWidth, opacity) {
+  if (cellSize <= 0) return;
+  const centers = getHexCenters(bounds, cellSize, orientation);
+  ctx.save();
+  ctx.strokeStyle = strokeColor;
+  ctx.lineWidth = strokeWidth;
+  ctx.globalAlpha = opacity;
+  ctx.beginPath();
+  for (const center of centers) {
+    const verts = getHexVertices(center.x, center.y, cellSize, orientation);
+    const first = verts[0];
+    if (!first) continue;
+    ctx.moveTo(first.x, first.y);
+    for (let i = 1; i < verts.length; i++) {
+      const v = verts[i];
+      if (!v) continue;
+      ctx.lineTo(v.x, v.y);
+    }
+    ctx.closePath();
+  }
+  ctx.stroke();
+  ctx.restore();
+}
+
 // src/elements/element-renderer.ts
 var DOM_ELEMENT_TYPES = /* @__PURE__ */ new Set(["note", "html", "text"]);
 var ARROWHEAD_LENGTH = 12;
@@ -1030,12 +1147,20 @@ var ElementRenderer = class {
   store = null;
   imageCache = /* @__PURE__ */ new Map();
   onImageLoad = null;
+  camera = null;
+  canvasSize = null;
   setStore(store) {
     this.store = store;
   }
   setOnImageLoad(callback) {
     this.onImageLoad = callback;
   }
+  setCamera(camera) {
+    this.camera = camera;
+  }
+  setCanvasSize(w, h) {
+    this.canvasSize = { w, h };
+  }
   isDomElement(element) {
     return DOM_ELEMENT_TYPES.has(element.type);
   }
@@ -1053,6 +1178,9 @@ var ElementRenderer = class {
       case "image":
         this.renderImage(ctx, element);
         break;
+      case "grid":
+        this.renderGrid(ctx, element);
+        break;
     }
   }
   renderStroke(ctx, stroke) {
@@ -1188,6 +1316,42 @@ var ElementRenderer = class {
       }
     }
   }
+  renderGrid(ctx, grid) {
+    if (!this.canvasSize) return;
+    const cam = this.camera;
+    if (!cam) return;
+    const topLeft = cam.screenToWorld({ x: 0, y: 0 });
+    const bottomRight = cam.screenToWorld({
+      x: this.canvasSize.w,
+      y: this.canvasSize.h
+    });
+    const bounds = {
+      minX: topLeft.x,
+      minY: topLeft.y,
+      maxX: bottomRight.x,
+      maxY: bottomRight.y
+    };
+    if (grid.gridType === "hex") {
+      renderHexGrid(
+        ctx,
+        bounds,
+        grid.cellSize,
+        grid.hexOrientation,
+        grid.strokeColor,
+        grid.strokeWidth,
+        grid.opacity
+      );
+    } else {
+      renderSquareGrid(
+        ctx,
+        bounds,
+        grid.cellSize,
+        grid.strokeColor,
+        grid.strokeWidth,
+        grid.opacity
+      );
+    }
+  }
   renderImage(ctx, image) {
     const img = this.getImage(image.src);
     if (!img) return;
@@ -1630,6 +1794,22 @@ function createShape(input) {
     fillColor: input.fillColor ?? "none"
   };
 }
+function createGrid(input) {
+  return {
+    id: createId("grid"),
+    type: "grid",
+    position: input.position ?? { x: 0, y: 0 },
+    zIndex: input.zIndex ?? 0,
+    locked: input.locked ?? false,
+    layerId: input.layerId ?? "",
+    gridType: input.gridType ?? "square",
+    hexOrientation: input.hexOrientation ?? "pointy",
+    cellSize: input.cellSize ?? 40,
+    strokeColor: input.strokeColor ?? "#000000",
+    strokeWidth: input.strokeWidth ?? 1,
+    opacity: input.opacity ?? 1
+  };
+}
 function createText(input) {
   return {
     id: createId("text"),
@@ -1807,6 +1987,7 @@ var Viewport = class {
     this.toolManager = new ToolManager();
     this.renderer = new ElementRenderer();
     this.renderer.setStore(this.store);
+    this.renderer.setCamera(this.camera);
     this.renderer.setOnImageLoad(() => this.requestRender());
     this.noteEditor = new NoteEditor();
     this.noteEditor.setOnStop((id) => this.onTextEditStop(id));
@@ -1953,6 +2134,34 @@ var Viewport = class {
     this.requestRender();
     return el.id;
   }
+  addGrid(input) {
+    const existing = this.store.getElementsByType("grid")[0];
+    this.historyRecorder.begin();
+    if (existing) {
+      this.store.remove(existing.id);
+    }
+    const grid = createGrid({ ...input, layerId: this.layerManager.activeLayerId });
+    this.store.add(grid);
+    this.historyRecorder.commit();
+    this.requestRender();
+    return grid.id;
+  }
+  updateGrid(updates) {
+    const grid = this.store.getElementsByType("grid")[0];
+    if (!grid) return;
+    this.historyRecorder.begin();
+    this.store.update(grid.id, updates);
+    this.historyRecorder.commit();
+    this.requestRender();
+  }
+  removeGrid() {
+    const grid = this.store.getElementsByType("grid")[0];
+    if (!grid) return;
+    this.historyRecorder.begin();
+    this.store.remove(grid.id);
+    this.historyRecorder.commit();
+    this.requestRender();
+  }
   destroy() {
     cancelAnimationFrame(this.animFrameId);
     this.stopInteracting();
@@ -1984,6 +2193,7 @@ var Viewport = class {
     const dpr = typeof devicePixelRatio !== "undefined" ? devicePixelRatio : 1;
     ctx.save();
     ctx.scale(dpr, dpr);
+    this.renderer.setCanvasSize(this.canvasEl.clientWidth, this.canvasEl.clientHeight);
     this.background.render(ctx, this.camera);
     ctx.save();
     ctx.translate(this.camera.position.x, this.camera.position.y);
@@ -2970,6 +3180,7 @@ var SelectTool = class {
     for (const el of ctx.store.getAll()) {
       if (ctx.isLayerVisible && !ctx.isLayerVisible(el.layerId)) continue;
       if (ctx.isLayerLocked && ctx.isLayerLocked(el.layerId)) continue;
+      if (el.type === "grid") continue;
       const bounds = this.getElementBounds(el);
       if (bounds && this.rectsOverlap(marquee, bounds)) {
         ids.push(el.id);
@@ -3006,11 +3217,13 @@ var SelectTool = class {
     for (const el of elements) {
       if (ctx.isLayerVisible && !ctx.isLayerVisible(el.layerId)) continue;
       if (ctx.isLayerLocked && ctx.isLayerLocked(el.layerId)) continue;
+      if (el.type === "grid") continue;
       if (this.isInsideBounds(world, el)) return el;
     }
     return null;
   }
   isInsideBounds(point, el) {
+    if (el.type === "grid") return false;
     if ("size" in el) {
       const s = el.size;
       return point.x >= el.position.x && point.x <= el.position.x + s.w && point.y >= el.position.y && point.y <= el.position.y + s.h;
@@ -3436,7 +3649,7 @@ var UpdateLayerCommand = class {
 };
 
 // src/index.ts
-var VERSION = "0.6.0";
+var VERSION = "0.6.1";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AddElementCommand,
@@ -3471,6 +3684,7 @@ var VERSION = "0.6.0";
   Viewport,
   clearStaleBindings,
   createArrow,
+  createGrid,
   createHtmlElement,
   createId,
   createImage,