canvas-can-do 0.1.9 → 0.1.13

package/README.md

@@ -21,12 +21,13 @@ app.useTool('select');
 
 ## Key Features
 
+- Frame creation: via API (`addFrame`) and drag-to-draw frame tool (`useTool('frame')` / `F`)
 - Shapes: rectangle, ellipse, line, star, text, image
 - Transform tools: move, resize, rotate, multi-select
 - Shift to constrain resize ratio
 - Undo/redo (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl/Cmd+Y)
-- Export: PNG/JPG/SVG (all objects or selection)
-- Save/Load: JSON with embedded image data URLs
+- Export: PNG/JPG/SVG via node-linked presets
+- Save/Load: JSON with embedded image data URLs + document export preset store
 - Rulers with pan/zoom indicators
 
 ## API Highlights
@@ -34,47 +35,424 @@ app.useTool('select');
 ```ts
 // Tools
 app.useTool('rectangle');
-
-// Export raster (PNG/JPG)
-const png = await app.exportRaster({ type: 'png', scope: 'all' });
-
-// Export SVG (embed images)
-const svg = await app.exportSVG({
-  scope: 'selection',
-  imageEmbed: 'display', // 'original' | 'display' | 'max'
-  imageMaxEdge: 2048,
-});
+app.useTool('frame'); // drag to draw a frame
 
 // Save/Load JSON (embedded images)
 const doc = await app.exportJSON();
 if (doc) await app.importJSON(doc);
 
+// Frames
+const frame = await app.addFrame({
+  name: 'Frame 1',
+  width: 1280,
+  height: 720,
+  backgroundColor: '#ffffff',
+  clipContent: true,
+});
+const frames = app.getFrames();
+
+// Document export preset store linked to node ids (persisted in exportJSON/importJSON)
+const preset = await app.addExportSetting(frame!.id, {
+  format: 'png',
+  scale: 2,
+  suffix: '@2x',
+});
+const asset = preset ? await app.exportNodeByPreset(frame!.id, preset.id) : null;
+if (asset?.contentType === 'dataUrl') {
+  // asset.content => data URL
+}
+
 // Access Pixi Application
 const pixiApp = app.getPixiApp();
+
+// Layers (for external layer panel UIs)
+const flatLayers = app.getFlatLayers({ recursive: true, topFirst: true });
+const canMove = app.canMoveLayers(['node-a'], 'node-b', 'before');
+if (canMove.ok) {
+  await app.moveLayers(['node-a'], 'node-b', 'before');
+}
 ```
 
-## Export Options
+## Layer Reordering API
+
+Use this API when your layer panel UI lives outside this library and you need a stable, id-based way to reorder layers and move nodes in/out of groups.
+
+### Goals
+
+- Keep UI code decoupled from Pixi internals
+- Support reorder and reparent in one atomic operation
+- Preserve visual placement when moving across parents/groups
+- Keep undo/redo clean (`1 drop = 1 history entry`)
+
+### Read Layers
 
 ```ts
-// Raster
-exportRaster({
-  type: 'png' | 'jpg',
-  scope: 'all' | 'selection',
-  quality?: number,        // for JPG
-  padding?: number,        // extra pixels around bounds
-  background?: string,     // e.g. '#ffffff'
+const layers = app.getFlatLayers({
+  parentId: null,   // null = root object layer
+  recursive: true,  // include descendants
+  topFirst: true,   // top-most first (panel-friendly)
 });
+```
+
+Each item includes:
+
+- `id`, `type`, `name`
+- `parentId`, `depth`
+- `zIndex`
+- `isGroup`, `childCount`
+- `visible`, `locked`
+
+### Move Semantics
+
+Position values:
+
+- `'before'`: insert source before target in target's parent
+- `'after'`: insert source after target in target's parent
+- `'inside'`: insert source into target (target must be a group or frame)
+
+Helpers:
+
+```ts
+const checkOne = app.canMoveLayer(sourceId, targetId, 'before');
+const checkMany = app.canMoveLayers(sourceIds, targetId, 'inside');
+
+if (checkMany.ok) {
+  await app.moveLayers(sourceIds, targetId, 'inside');
+}
+```
+
+Write methods:
+
+- `moveLayer(sourceId, targetId, position, options?)`
+- `moveLayers(sourceIds, targetId, position, options?)`
+
+Options:
+
+- `recordHistory?: boolean` (default `true`)
+
+### Validation Rules
+
+Move is rejected (`ok: false`) when:
+
+- source/target ids are invalid
+- source and target are the same node
+- `position === 'inside'` but target is not a group/frame
+- source node is locked
+- destination parent is locked
+- move would create a parent/child cycle (ancestor into descendant)
+- moving a frame into non-root parent (frames are root-only)
+
+### Atomic Move Behavior
 
-// SVG
-exportSVG({
-  scope: 'all' | 'selection',
-  padding?: number,
-  background?: string,
-  imageEmbed?: 'original' | 'display' | 'max',
-  imageMaxEdge?: number,
+`moveLayer(s)` performs one transaction-like operation:
+
+1. Validate request
+2. Normalize source list (avoid parent+child duplicate moves)
+3. Resolve insertion index
+4. Capture each source node world transform
+5. Reparent/reorder
+6. Re-apply transform in destination parent space (so node does not jump)
+7. Emit `layer:changed`
+8. Capture history (unless `recordHistory: false`)
+
+This is what enables: selecting an item inside a group, dragging it above an external layer, and having it both leave the group and land at the correct z-order in one drop.
+
+### Typical External UI Flow
+
+```ts
+// 1) render panel from library state
+const layers = app.getFlatLayers({ recursive: true, topFirst: true });
+
+// 2) while dragging, probe validity
+const probe = app.canMoveLayers(dragSourceIds, hoverTargetId, hoverPosition);
+showDropIndicator(probe.ok);
+
+// 3) on drop, commit once
+if (probe.ok) {
+  await app.moveLayers(dragSourceIds, hoverTargetId, hoverPosition);
+}
+
+// 4) listen and re-render
+app.addEventListener('layer:changed', () => {
+  rerenderPanel(app.getFlatLayers({ recursive: true, topFirst: true }));
 });
 ```
 
+## Frame Concept (Figma-like)
+
+`Frame` is different from `Group`.
+
+- `Group`: logical grouping for transforming multiple nodes together
+- `Frame`: a bounded working area with optional background and clipping
+
+Think of `Frame` as an artboard/container that can also be used as an export boundary.
+
+### Frame Behavior
+
+- Frame is **root-only**:
+  - cannot be grouped
+  - cannot be child of group/frame
+- Can contain child nodes (like a container)
+- Has explicit `width` and `height`
+- Supports background color or transparent background
+- Supports clipping/masking at frame bounds (`clipContent`)
+- Can be target of drag/drop reparent operations (`inside`)
+- Can be used as export target node for preset-based export
+
+### Drawing and Moving In/Out of Frame
+
+- Frame can be created by API (`addFrame`) or drag tool (`frame` / `F`)
+- Drawing non-frame shapes starts in the frame under pointer (if any), otherwise root canvas
+- Drag/drop can move nodes into a frame (`inside`) or out of a frame (`before`/`after` against external target)
+- Reparent + z-order update happen in one atomic operation
+- World transform is preserved when reparenting so nodes do not visually jump
+- Auto drag-reparent is blocked for group-managed nodes (group or descendants of group)
+
+### Canvas Presentation (Editor Visual)
+
+Frame should look visibly different from regular objects so users can immediately identify it as a working boundary.
+
+- Visible frame border at all times (scale-aware stroke)
+- Frame name label near top-left corner
+- Optional background fill (or transparent mode)
+- Clear visual cue when clipping is enabled
+- Distinct `idle`, `hover`, `selected`, and `drop-target` states
+
+Recommended editor-only rendering split:
+
+- `FrameNode` for document content (background + children + clip)
+- `FrameOverlay` for editor cues (border, label, highlight, drop indicator)
+
+This keeps export output clean while still giving strong authoring feedback on canvas.
+
+### Suggested Frame Visual States
+
+- `idle`: neutral border, subtle label
+- `hover`: stronger border to indicate targetability
+- `selected`: accent border + resize handles + prominent label
+- `drop-target`: temporary insertion highlight while dragging
+
+### Export Semantics
+
+- Support exporting by frame id (raster/SVG)
+- If `clipContent=true`, export respects frame bounds
+- If transparent background is selected, exported background remains transparent
+
+### Suggested API Surface
+
+```ts
+// creation / query
+const frame = await app.addFrame({
+  name: 'Frame 1',
+  x: 100,
+  y: 80,
+  width: 1280,
+  height: 720,
+  backgroundColor: '#ffffff', // null for transparent
+  clipContent: true,
+});
+
+const frames = app.getFrames();
+
+// export by preset
+const pngPreset = await app.addExportSetting(frame.id, { format: 'png', scale: 1, suffix: '' });
+const pngAsset = pngPreset ? await app.exportNodeByPreset(frame.id, pngPreset.id) : null;
+```
+
+## Export Presets (Figma-like)
+
+Presets are stored in a centralized document-level registry (`exportStore`) and linked to nodes by id.
+This keeps lookup/edit fast and avoids recursive node scans.
+
+```ts
+type NodeExportPreset = {
+  id: string;
+  format: 'png' | 'jpg' | 'svg';
+  scale: number;
+  suffix: string; // e.g. '', '@2x'
+  quality?: number; // jpg
+  padding?: number;
+  backgroundMode?: 'auto' | 'transparent' | 'solid';
+  backgroundColor?: string; // used when backgroundMode = 'solid'
+  imageEmbed?: 'original' | 'display' | 'max'; // svg
+  imageMaxEdge?: number; // svg
+};
+```
+
+### Preset APIs
+
+```ts
+// add preset and link to node
+const added = await app.addExportSetting(nodeId, {
+  format: 'png',
+  scale: 1,
+  suffix: '',
+});
+
+// get preset entity by id
+const preset = app.getExportSettingById(added!.id);
+
+// edit preset entity
+await app.editExportSetting(added!.id, {
+  scale: 2,
+  suffix: '@2x',
+});
+
+// list preset ids linked to a node
+const presetIds = app.getExportSettingIds(nodeId);
+
+// list all presets in document (without scanning nodes manually)
+const allPresets = app.getAllExportSettings();
+// [{ id, preset, linkedNodeIds }]
+
+// inspect linked nodes before editing shared presets
+const usedBy = app.getExportPresetUsage(preset!.id);
+
+// export one node using its preset
+const asset = await app.exportNodeByPreset(nodeId, preset!.id);
+if (asset) {
+  // asset.filename, asset.mimeType, asset.contentType, asset.content
+}
+
+// export many nodes in one call
+const frameAPreset = await app.addExportSetting(frameA, { format: 'png', scale: 1, suffix: '' });
+const frameBPreset = await app.addExportSetting(frameB, { format: 'svg', scale: 1, suffix: '' });
+const assets = await app.exportNodesByPreset([
+  { nodeId: frameA, presetId: frameAPreset!.id },
+  { nodeId: frameB, presetId: frameBPreset!.id },
+]);
+
+// delete preset entity (and unlink from all nodes)
+await app.deleteExportSetting(added!.id);
+```
+
+## Export Contract
+
+Preset-first only:
+
+- Create preset via `addExportSetting(nodeId, preset)`
+- Edit/delete via `editExportSetting` / `deleteExportSetting`
+- Export only via `exportNodeByPreset(nodeId, presetId)` or `exportNodesByPreset(...)`
+- `presetId` must be explicitly provided and linked to that node
+
+Format behavior:
+
+- `jpg` should use opaque background (`backgroundMode: 'solid'`, `backgroundColor`)
+- `png` / `svg` can keep transparency with `backgroundMode: 'auto'` or `'transparent'`
+
+## Save/Load Contract (Revision)
+
+This section defines the document model expectations after adding frames and expanded layer behavior.
+
+### Document Goals
+
+- Preserve exact hierarchy (parent/child + order).
+- Preserve per-node transform and visibility/locking.
+- Preserve frame-specific properties and behavior.
+- Enforce frame root-only invariant on import/restore.
+
+### Required Frame Fields (logical model)
+
+- geometry: `x`, `y`, `width`, `height`
+- transform: `rotation` (currently fixed to 0 by interaction), `scale`
+- visibility/state: `visible`, `locked`
+- frame style: `backgroundColor`
+- frame behavior: `clipContent`
+- hierarchy: `children[]` in stable z-order
+
+### Round-trip Invariants
+
+After `exportJSON -> importJSON`:
+
+- node count and hierarchy must match
+- z-order must match
+- frame bounds/style/clip settings must match
+- locked/visible state must match
+- export output for same node + preset should remain equivalent
+- frame never appears as a child of group/frame after import normalization
+
+### Versioning and Migration
+
+- Current baseline is `document.version = 1` only.
+- Keep schema simple while not in production.
+- If schema changes later, introduce migrations in the next version.
+
+Import normalization defaults for frame fields:
+
+- `backgroundColor = '#ffffff'`
+- `clipContent = true`
+
+### Server Persistence Flow
+
+Use `exportJSON()` as the payload to your backend.  
+This payload now includes `exportStore` (preset registry + node links), so loading back with `importJSON()` restores export presets too.
+
+```ts
+// save
+const doc = await app.exportJSON();
+await fetch('/api/documents/123', {
+  method: 'PUT',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify(doc),
+});
+
+// load
+const loaded = await fetch('/api/documents/123').then((r) => r.json());
+await app.importJSON(loaded);
+```
+
+### Round-trip (including export presets)
+
+After `exportJSON -> save to server -> load from server -> importJSON`:
+
+- node hierarchy/order must match
+- frame properties must match
+- export registry + node links must match (`id/format/scale/suffix/...`)
+- exporting the same node + preset should produce equivalent output
+
+### Post-change Checklist
+
+- Verify preset-based export for PNG/JPG/SVG on target nodes.
+- Verify frame with `clipContent` on/off.
+- Verify frame remains root-only after save/load.
+- Verify lock/visible states survive save/load.
+- Verify undo/redo still works immediately after load.
+
+## Interaction Policy
+
+- Group-first hit test: pointer hover/click on a group or any descendant selects the group.
+- Frame-child-first hit test: inside frame, children are preferred over selecting frame body.
+- Frame body selection is intentionally disabled on canvas hit-test; select frame via label or layer/API.
+- Layer panel/API can still select specific child ids directly (`selectNodeById` / `selectNodesById`).
+
+## UI Recommendation (Figma-like Export)
+
+Suggested UX in the right sidebar when 1 node is selected:
+
+1. Section title: `Export`
+2. List rows: one row per preset (`PNG 1x`, `PNG 2x`, `SVG`)
+3. Each row editable: `format`, `scale`, `suffix`, advanced options
+4. Row actions: duplicate / delete preset
+5. Primary button: `Export <NodeName>` (export selected preset)
+6. Secondary button: `Export All` (all presets for current node)
+
+Suggested UI behavior:
+
+- Auto-save preset edits immediately via `addExportSetting` / `editExportSetting` / `deleteExportSetting`
+- Keep preset `id` stable; use `id` for persistence and updates (shared ids = shared edits)
+- Export requires explicit `presetId` linked to that node (no implicit fallback preset)
+- Show final filename preview from `name + suffix + extension`
+- When exporting multiple selected nodes, call `exportNodesByPreset`
+
+## Implementation Guide
+
+1. Add an `ExportPanel` in your inspector that reads `getAllExportSettings()` for document-level preset list, and `getExportSettingIds(nodeId)` for per-node links.
+2. Bind form fields to preset objects and debounce writes to `editExportSetting`.
+3. On export click, call `exportNodeByPreset(nodeId, presetId)`.
+4. If `asset.contentType === 'dataUrl'`, download with anchor `href = dataUrl`.
+5. If `asset.contentType === 'text'` (SVG), create `Blob([asset.content], { type: asset.mimeType })`.
+6. For batch export, call `exportNodesByPreset` then zip/download in your app shell.
+
 ## Events
 
 ```ts

package/dist/{SharedSystems-CZrQpXWg.js → SharedSystems-Cg8-nEUA.js}

@@ -1,5 +1,5 @@
-import { x as Oe, n as ie, M as g, G as Fe, a as Le, y as oe, E as u, e as F, z as w, F as He, H as L, I as y, R as H, J as le, K as We, v as m, d as f, k as G, w as W, L as X, N as ze, h as Q, B as k, l as A, O as Ve, u as M, m as S, Q as P, V as Ne, b as je, W as ue, X as de, Y as ce, Z as he, C as U, _ as qe, $ as I, a0 as Z, D as z, a1 as $e, a2 as Ke, P as Ye, i as Je, T as ee, a3 as te, a4 as v, a5 as Xe, a6 as Qe } from "./index-D_NFBR4n.js";
-import { F as Ze, S as et, B as fe, c as tt } from "./colorToUniform-DOf21nfM.js";
+import { x as Oe, n as ie, M as g, G as Fe, a as Le, y as oe, E as u, e as F, z as w, F as He, H as L, I as y, R as H, J as le, K as We, v as m, d as f, k as G, w as W, L as X, N as ze, h as Q, B as k, l as A, O as Ve, u as M, m as S, Q as P, V as Ne, b as je, W as ue, X as de, Y as ce, Z as he, C as U, _ as qe, $ as I, a0 as Z, D as z, a1 as $e, a2 as Ke, P as Ye, i as Je, T as ee, a3 as te, a4 as v, a5 as Xe, a6 as Qe } from "./index-CbUjW4XO.js";
+import { F as Ze, S as et, B as fe, c as tt } from "./colorToUniform-Dy_GZxOz.js";
 var rt = `in vec2 vMaskCoord;
 in vec2 vTextureCoord;
 

package/dist/{WebGLRenderer-guxg9y4k.js → WebGLRenderer-CWOX7V4e.js}

@@ -1,6 +1,6 @@
-import { E as d, c as G, B as T, w as m, D as S, L as K, a as Be, S as U, v as b, a7 as Ae, m as $, a8 as Ne, d as p, Q as w, l as B, k as A, n as F, M as z, a9 as Y, aa as ye, ab as q, ac as Ce, ad as De, A as Ie, R as Ge, e as v } from "./index-D_NFBR4n.js";
-import { S as O, b as Z } from "./colorToUniform-DOf21nfM.js";
-import { e as Ue, G as Fe, c as Oe, b as Pe, U as Me, R as Le, B as Q, d as N, f as we, S as He, a as ke } from "./SharedSystems-CZrQpXWg.js";
+import { E as d, c as G, B as T, w as m, D as S, L as K, a as Be, S as U, v as b, a7 as Ae, m as $, a8 as Ne, d as p, Q as w, l as B, k as A, n as F, M as z, a9 as Y, aa as ye, ab as q, ac as Ce, ad as De, A as Ie, R as Ge, e as v } from "./index-CbUjW4XO.js";
+import { S as O, b as Z } from "./colorToUniform-Dy_GZxOz.js";
+import { e as Ue, G as Fe, c as Oe, b as Pe, U as Me, R as Le, B as Q, d as N, f as we, S as He, a as ke } from "./SharedSystems-Cg8-nEUA.js";
 class J {
   constructor() {
     this._tempState = O.for2d(), this._didUploadHash = {};

package/dist/{WebGPURenderer-v9P1o84e.js → WebGPURenderer-pdpNSHly.js}

@@ -1,6 +1,6 @@
-import { g as E, E as f, c as L, u as ue, f as ce, D as P, d as v, B as T, h as de, i as A, j as M, w as C, k as x, l as he, m as pe, n as D, o as w, M as k, p as z, q as le, s as F, t as fe, S as I, v as R, A as ge, R as me, e as B } from "./index-D_NFBR4n.js";
-import { S as O, l as _e, a as be } from "./colorToUniform-DOf21nfM.js";
-import { c as xe, u as ye, U as Ge, B as Pe, G as Be, e as Se, R as Te, t as ve, S as Ce, a as Ue } from "./SharedSystems-CZrQpXWg.js";
+import { g as E, E as f, c as L, u as ue, f as ce, D as P, d as v, B as T, h as de, i as A, j as M, w as C, k as x, l as he, m as pe, n as D, o as w, M as k, p as z, q as le, s as F, t as fe, S as I, v as R, A as ge, R as me, e as B } from "./index-CbUjW4XO.js";
+import { S as O, l as _e, a as be } from "./colorToUniform-Dy_GZxOz.js";
+import { c as xe, u as ye, U as Ge, B as Pe, G as Be, e as Se, R as Te, t as ve, S as Ce, a as Ue } from "./SharedSystems-Cg8-nEUA.js";
 const y = O.for2d();
 class W {
   start(e, t, r) {

package/dist/{browserAll-CKZpLV_L.js → browserAll-D358sNiQ.js}

@@ -1,5 +1,5 @@
-import { T as M, U as Z, P as m, r as te, E as y, b as ie, w as g, e as P, C as V } from "./index-D_NFBR4n.js";
-import "./webworkerAll-B_02fub1.js";
+import { T as M, U as Z, P as m, r as te, E as y, b as ie, w as g, e as P, C as V } from "./index-CbUjW4XO.js";
+import "./webworkerAll-EieaH4C5.js";
 class q {
   constructor(e) {
     this._lastTransform = "", this._observer = null, this._tickerAttached = !1, this.updateTranslation = () => {

package/dist/canvas-can-do.js

@@ -1,4 +1,4 @@
-import { as as o, at as p, au as r } from "./index-D_NFBR4n.js";
+import { as as o, at as p, au as r } from "./index-CbUjW4XO.js";
 export {
   o as CCDApp,
   p as TOOL_CURSOR,