@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/design-canvas/validate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pre-write validation for scene operations. Every rule runs against a
+ * `SceneDocument` snapshot BEFORE any mutation, so a rejected batch leaves no
+ * partial state. Batch errors carry the shape `operation N (type): reason` —
+ * precise enough for an LLM planner to repair the offending operation and
+ * resubmit.
+ *
+ * Validation is static: a batch is checked against the document as given, so
+ * an operation may not reference entities created by an earlier operation in
+ * the same batch. Dispatchers that chain operations must refresh the document
+ * between applications and validate per-operation.
+ *
+ * Slot typing contract (for apply_data bindings):
+ *   text    elements  → value is any string
+ *   image   elements  → value must pass assertSceneMediaSrc (src rewrite)
+ *   video   elements  → value must pass assertSceneMediaSrc (src rewrite)
+ *   rect    elements  → value must pass assertColor (fill recolor)
+ *   ellipse elements  → value must pass assertColor (fill recolor)
+ *   line    elements  → value must pass assertColor (stroke recolor)
+ *   group   elements  → value must pass assertColor (fill/stroke passed down to children)
+ */
+import type { SceneDocument, SceneElementKind } from './model';
+import type { SceneOperation } from './operations';
+/** Validate each scene operation against the document and throw detailed errors for invalid operations */
+export declare function validateSceneOperations(document: SceneDocument, operations: SceneOperation[]): void;
+/** Validate a scene operation against the document to ensure it meets required constraints */
+export declare function validateSceneOperation(document: SceneDocument, operation: SceneOperation): void;
+/**
+ * Validates that a slot binding value matches the slot element's kind.
+ * text → any string; image/video → media src; rect/ellipse/line/group → color.
+ */
+export declare function validateSlotValue(slotName: string, elementKind: SceneElementKind, value: string): void;

package/dist/design-canvas-react/components/BleedTrimOverlay.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Semi-transparent bleed tint drawn OUTSIDE the page bounds, with trim-mark
+ * corner indicators. Renders as an absolutely-positioned div layered over the
+ * workspace canvas; node name 'overlay:bleed' lets automated tests target it.
+ *
+ * Conditionally rendered: parent mounts this only when `showBleed && bleed`.
+ * All dimensions are in SCREEN pixels (caller applies the zoom factor).
+ */
+interface BleedTrimOverlayProps {
+    /** Page dimensions in screen pixels (already multiplied by zoom). */
+    pageWidthPx: number;
+    pageHeightPx: number;
+    /** Bleed extents in SCREEN pixels (caller multiplies doc-px by zoom). */
+    bleed: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+export declare function BleedTrimOverlay({ pageWidthPx, pageHeightPx, bleed }: BleedTrimOverlayProps): import("react").JSX.Element;
+export {};

package/dist/design-canvas-react/components/BrandKnot.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Load the canonical Tangle knot only when a canvas surface renders it.
+ * `/brand` imports the optional `@tangle-network/brand` peer, so a failed load
+ * renders a fixed-size spacer instead of crashing the editor.
+ */
+interface BrandKnotProps {
+    size?: number;
+    className?: string;
+}
+export declare function BrandKnot({ size, className }: BrandKnotProps): import("react").JSX.Element;
+export {};

package/dist/design-canvas-react/components/CanvasEmptyState.d.ts

@@ -0,0 +1,32 @@
+/**
+ * In-canvas empty state — the first move on a blank design. Shown by
+ * WorkspaceView as a centered overlay while the active page has no user
+ * content, so a fresh canvas reads as "ready to start" rather than "broken or
+ * empty". Three doors cover the two ways people begin and the agent path:
+ *   - Start with a template — drop a starter element via the same command stack.
+ *   - Add an element — insert a text block by hand.
+ *   - Ask the agent — surfaced only when the host wires `onAskAgent` (an agent
+ *     panel exists); otherwise the door is omitted rather than rendered dead.
+ *
+ * Token-styled only (CSS-var tokens + Tailwind semantic names) and stamped with
+ * the Tangle mark so the blank state is on-brand. Pointer-events stay scoped to
+ * the card: clicking the surrounding canvas still starts a marquee.
+ */
+export interface CanvasEmptyStateProps {
+    /** Drop a starter template element through the command stack. */
+    onStartTemplate(): void;
+    /** Insert a single editable element by hand. */
+    onAddElement(): void;
+    /** Focus the agent panel / open the agent. Omitted → the door is hidden. */
+    onAskAgent?(): void;
+    /** Heading copy. Overridable; defaults to the cold-open prompt. */
+    title?: string;
+    /** Supporting line under the heading. Overridable. */
+    subtitle?: string;
+    className?: string;
+}
+/**
+ * The three-door empty state. Each door is a real action wired to the editor's
+ * command stack (or the agent), never a placeholder.
+ */
+export declare function CanvasEmptyState({ onStartTemplate, onAddElement, onAskAgent, title, subtitle, className, }: CanvasEmptyStateProps): import("react").JSX.Element;

package/dist/design-canvas-react/components/CanvasInsertPanel.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The human "add element to the canvas" side panel — a reusable left rail any
+ * canvas consumer can mount so a person (not just the agent) can put images,
+ * shapes, and text on the canvas. Designed for the `renderSidePanel` slot of
+ * {@link DesignCanvasProps}; pass `renderSidePanel={(ctx) => <CanvasInsertPanel … />}`.
+ *
+ * Endpoints are per-app, so every I/O path is a callback — no product route is
+ * hardcoded:
+ *  - `onUploadImage(file) => Promise<url>` — optional. When provided, the host
+ *    stores the file and returns the src to insert. The url MUST be http(s) or
+ *    a rooted `/api/` path (enforced by `assertSceneMediaSrc` before insertion);
+ *    a `data:` url is rejected, matching the scene model's media boundary.
+ *  - `loadGenerations?()` — optional provider for "already generated in this
+ *    workspace" images; omit to hide the tab.
+ *  - `templates?` — optional template set; defaults to {@link DEFAULT_INSERT_TEMPLATES}.
+ *    A host-passed (composed) set labels its tab "Templates"; the built-in
+ *    primitives label it "Elements".
+ *
+ * Insertion goes through `onInsert`, which the host wires to its
+ * `onApplyOperations` pipeline (server-validated, undoable) — the same path
+ * every other edit takes.
+ *
+ * Tokens/icons follow the canvas convention: CSS-var design tokens and inline
+ * SVG glyphs, no icon-library or Tailwind-semantic-token dependency.
+ */
+import type { SceneOperation } from '../../design-canvas/operations';
+import { type InsertPageGeometry, type InsertTemplate } from '../insert-builders';
+/** An already-generated image the panel can offer for one-click insertion. */
+export interface InsertGeneration {
+    id: string;
+    /** The image url to insert. Must satisfy the scene media boundary
+     *  (http(s) or rooted `/api/`); rejected otherwise at insert time. */
+    url: string;
+    /** Optional prompt/label shown as the tile's title. */
+    label?: string;
+}
+export interface CanvasInsertPanelProps {
+    canWrite: boolean;
+    /** The active page new elements are added to. */
+    page: InsertPageGeometry;
+    /** Submit operations through the host's apply pipeline. */
+    onInsert(operations: SceneOperation[]): Promise<unknown>;
+    /** Store an uploaded file and return its src (http(s) or rooted `/api/`). */
+    onUploadImage?(file: File): Promise<string>;
+    /** Optional provider for the Generations tab; omit to hide it. */
+    loadGenerations?(): Promise<InsertGeneration[]>;
+    /** Drop-in templates; defaults to the built-in starter set. */
+    templates?: readonly InsertTemplate[];
+    /** Accepted upload mime types. Default: PNG/JPEG/GIF/WebP. */
+    accept?: string;
+    className?: string;
+}
+export declare function CanvasInsertPanel({ canWrite, page, onInsert, onUploadImage, loadGenerations, templates, accept, className, }: CanvasInsertPanelProps): import("react").JSX.Element;

package/dist/{lazy-DrkVyDpe.d.ts → design-canvas-react/components/DesignCanvas.d.ts}

@@ -1,10 +1,31 @@
-import * as react from 'react';
-import { c as SceneDocument } from './model-DnfO_PdJ.js';
-import { D as DesignCanvasProps, c as createSceneCommandStack, E as ExportTriggerOptions } from './command-stack-TNPWJCzW.js';
-
+/**
+ * Root editor shell. Products mount exactly this component. Layout mirrors
+ * Polotno: optional left side panel | main column | optional right agent panel.
+ *
+ * Main column stacks top→bottom:
+ *   Toolbar (undo/redo, view toggles, selection attrs, page props)
+ *   Rulers + Workspace  (the Workspace is injected by the integrator via the
+ *                        `renderWorkspace` prop — it owns Konva and is Konva-
+ *                        specific; this chrome stays canvas-free)
+ *   bottom row: PagesStrip + ZoomControls
+ *
+ * Command lifecycle:
+ * - The command stack lives here; every panel receives callbacks, never the
+ *   stack itself.
+ * - `onApplyOperations` is called optimistically after every command. If it
+ *   rejects, the command is rolled back locally. If it resolves with a fresh
+ *   `document`, the stack rebases via `stack.reset(document)` — this preserves
+ *   history while reconciling server-minted ids or normalised values.
+ * - `setView` (zoom/pan/selection/toggles) never enters history.
+ * - Keyboard: Mod+Z undo · Shift+Mod+Z / Mod+Y redo · Delete/Backspace deletes
+ *   the selection · F fits the page (forwarded to workspace via ref).
+ */
+import type { SceneDocument } from '../../design-canvas/model';
+import type { DesignCanvasProps, ExportTriggerOptions } from '../contracts';
+import { createSceneCommandStack } from '../engine/command-stack';
 /** Callers inject a workspace renderer so this chrome stays Konva-free. The
  *  workspace occupies the scrollable area between the rulers and the bottom bar. */
-interface DesignCanvasFullProps extends DesignCanvasProps {
+export interface DesignCanvasFullProps extends DesignCanvasProps {
     /**
      * Render the Konva canvas workspace into the slot this shell provides.
      * The shell passes viewport dimensions, view-state, and the shared command
@@ -59,18 +80,4 @@ interface DesignCanvasFullProps extends DesignCanvasProps {
      */
     renderThumbnail(page: SceneDocument['pages'][number]): Promise<string | null>;
 }
-declare function DesignCanvas({ document: initialDocument, rev: initialRev, canWrite, mode, onApplyOperations, onSelectionChange, renderAgentPanel, renderSidePanel, onExport, exportDefaults, className, fitOnMount, onReady, render, showEmptyState, onAskAgent, pageSizeLabel, enableBleedLabel, fitLabel, renderWorkspace, renderThumbnail, }: DesignCanvasFullProps): react.JSX.Element;
-
-/**
- * Mount this component to get the full editor: toolbar, rulers, layers panel,
- * pages strip, zoom controls, and the Konva canvas — all sharing one command
- * stack so undo/redo and selection are coherent across every surface.
- */
-declare function DesignCanvasEditor(props: DesignCanvasProps): react.JSX.Element;
-
-/** Batteries-included editor: chrome + workspace on one shared stack. */
-declare const DesignCanvasLazy: react.LazyExoticComponent<typeof DesignCanvasEditor>;
-/** Raw chrome only — use when supplying a custom renderWorkspace/renderThumbnail. */
-declare const DesignCanvasChromeLazy: react.LazyExoticComponent<typeof DesignCanvas>;
-
-export { DesignCanvas as D, DesignCanvasChromeLazy as a, DesignCanvasEditor as b, type DesignCanvasFullProps as c, DesignCanvasLazy as d };
+export declare function DesignCanvas({ document: initialDocument, rev: initialRev, canWrite, mode, onApplyOperations, onSelectionChange, renderAgentPanel, renderSidePanel, onExport, exportDefaults, className, fitOnMount, onReady, render, showEmptyState, onAskAgent, pageSizeLabel, enableBleedLabel, fitLabel, renderWorkspace, renderThumbnail, }: DesignCanvasFullProps): import("react").JSX.Element;

package/dist/design-canvas-react/components/DesignCanvasEditor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Batteries-included composition: DesignCanvas chrome + WorkspaceView sharing
+ * one command stack. This is the component products mount.
+ *
+ * Stack ownership:
+ * DesignCanvas (chrome) owns the command stack. WorkspaceView receives that
+ * same stack via renderWorkspace(ctx), so every gesture, undo, redo, and
+ * layers-panel selection mutation touches exactly one state machine.
+ *
+ * Thumbnail rendering:
+ * Thumbnails are produced imperatively with the Konva JS API (no React tree)
+ * on an off-DOM stage at ~96px height. Only geometry + solid-fill shapes are
+ * rendered — image nodes are skipped because async loading would require a
+ * second pass. Cache key: `${pageId}:${cheapHash(elements)}`. Thumbnail
+ * absence is cosmetic; PagesStrip handles a null result gracefully.
+ */
+import type { DesignCanvasProps } from '../contracts';
+/**
+ * Mount this component to get the full editor: toolbar, rulers, layers panel,
+ * pages strip, zoom controls, and the Konva canvas — all sharing one command
+ * stack so undo/redo and selection are coherent across every surface.
+ */
+export declare function DesignCanvasEditor(props: DesignCanvasProps): import("react").JSX.Element;

package/dist/design-canvas-react/components/ElementNode.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Per-kind Konva node rendering for SceneElement. Each element kind maps to
+ * the appropriate Konva primitive; geometry is converted from the model's
+ * top-left convention where needed.
+ *
+ * Ellipse center-offset invariant: the model stores (x, y) as the top-left
+ * corner of the bounding box. Konva.Ellipse draws from its center point.
+ * The conversion is: centerX = x + width/2, centerY = y + height/2,
+ * radiusX = width/2, radiusY = height/2. The reverse applies when reading
+ * back from transformer output (see transform-math.ts:ellipseTopLeftFromCenter).
+ *
+ * Image loading: src is loaded async into an HTMLImageElement via useEffect,
+ * cached per src in a module-level Map so repeated renders of the same src
+ * don't re-fetch. A broken-image placeholder rect is shown while loading or on
+ * error; its `name` carries the src for diagnostics.
+ *
+ * Video elements render as their poster image when posterSrc is set, or a
+ * placeholder rect. This is intentional — motion belongs to the sequences
+ * surface; the canvas surface is for static layout.
+ *
+ * Node name: each node's `name` prop carries the element id so hit→model
+ * mapping in Workspace works: `stage.getIntersection(pos)?.name()`.
+ *
+ * locked → listening(false) except on the click handler for selection.
+ * hidden → not rendered.
+ */
+import { type CanvasRenderPalette } from '../../theme/theme';
+import type { SceneElement } from '../../design-canvas/model';
+export interface ElementNodeProps {
+    element: SceneElement;
+    isSelected: boolean;
+    zoom: number;
+    /** Theme render palette. Omitted → light defaults (byte-identical history). */
+    render?: CanvasRenderPalette;
+    onClick?(elementId: string): void;
+    onDragStart?(elementId: string): void;
+    onDragMove?(elementId: string, dx: number, dy: number): void;
+    onDragEnd?(elementId: string, finalX: number, finalY: number): void;
+    onDoubleClick?(elementId: string): void;
+}
+declare function ElementNodeImpl(props: ElementNodeProps): import("react").JSX.Element | null;
+/**
+ * Memoized so a `stack.notify()` (fired ~120/s during a pan/marquee) that
+ * re-renders WorkspaceView does NOT re-render every element. With stable
+ * handler identities supplied by WorkspaceView, an ElementNode re-renders only
+ * when its OWN `element` reference, `isSelected`, `zoom`, or `render` palette
+ * change — i.e. when it actually moved, was (de)selected, or the view scaled.
+ * Pan-only frames change none of these props, so the N nodes stay reconciled.
+ */
+export declare const ElementNode: import("react").MemoExoticComponent<typeof ElementNodeImpl>;
+export {};

package/dist/design-canvas-react/components/ExportControl.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Compact Export control for the editor chrome's top-right slot. A single
+ * button opens a small popover to choose format (PNG/JPEG) and scale (1x/2x);
+ * confirming calls `onExport({ format, pixelRatio })`.
+ *
+ * The chrome is Konva-free, so this control does NOT render the image — it only
+ * collects the format/scale and delegates to the workspace (which owns the
+ * stage) via the callback the DesignCanvas shell wires through `onExportRef`.
+ *
+ * Tokens/glyphs follow the canvas convention: CSS-var design tokens and inline
+ * SVG glyphs, no icon-library or browser-default `<select>`.
+ */
+import type { ExportTriggerOptions } from '../contracts';
+export interface ExportControlProps {
+    /** Pre-selected format/scale when the popover opens. Default PNG @ 1x. */
+    defaults?: ExportTriggerOptions;
+    /** Called with the chosen format/scale when the user confirms. */
+    onExport(opts: ExportTriggerOptions): void;
+    className?: string;
+}
+export declare function ExportControl({ defaults, onExport, className }: ExportControlProps): import("react").JSX.Element;

package/dist/design-canvas-react/components/GridLayer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Grid overlay rendered beneath page content. The whole grid is painted by a
+ * SINGLE Konva node — a custom Shape whose `sceneFunc` strokes every grid line
+ * in one pass — rather than one Konva.Line per line. At ~hundreds of lines on a
+ * page this turns a per-pan-frame reconciliation of hundreds of React/Konva
+ * nodes into a single node whose only changing props are the transform; panning
+ * no longer churns the scene graph.
+ *
+ * Grid lines are skipped entirely when they would be closer than 4 screen
+ * pixels apart — below that density the grid becomes visual noise rather than
+ * guidance (gridVisible density-skip, unchanged).
+ *
+ * COORDINATE SYSTEM: the lines are authored in document space and wrapped in a
+ * Group carrying the SAME (panX, panY, zoom) transform the content layer uses,
+ * so the grid tracks the page exactly on pan and zoom. A Konva.Layer cannot
+ * live inside a Group, so the transform is applied to an inner Group, not the
+ * Layer. The grid is its own Layer (not merged into the content Layer) so the
+ * content draws on top without per-frame z-ordering churn.
+ *
+ * EXPORT EXCLUSION: the Layer carries the name prefix 'overlay:' and the Shape
+ * is named 'overlay:grid-shape' so export logic excludes the whole grid from
+ * rasterization.
+ */
+export interface GridLayerProps {
+    /** Page width in document px. */
+    pageWidth: number;
+    /** Page height in document px. */
+    pageHeight: number;
+    /** Document px between grid lines. */
+    gridSize: number;
+    /** Screen px per document px. */
+    zoom: number;
+    /** Horizontal pan offset in screen px (content Group x). */
+    panX: number;
+    /** Vertical pan offset in screen px (content Group y). */
+    panY: number;
+    /** Grid line color. */
+    color?: string;
+    /** Grid line opacity (0–1). */
+    opacity?: number;
+}
+/** Document-space x positions of every vertical grid line on the page. Pure so
+ *  the single-Shape sceneFunc and tests share one definition (no drift). */
+export declare function gridVerticalLines(pageWidth: number, gridSize: number): number[];
+/** Document-space y positions of every horizontal grid line on the page. */
+export declare function gridHorizontalLines(pageHeight: number, gridSize: number): number[];
+export declare function GridLayer({ pageWidth, pageHeight, gridSize, zoom, panX, panY, color, opacity, }: GridLayerProps): import("react").JSX.Element | null;

package/dist/design-canvas-react/components/InlineTextEditor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Inline text editor: a positioned <textarea> that appears over a text element
+ * on double-click, mirroring its font properties at the current zoom. The
+ * parent Workspace mounts this when `editingElementId` is set and unmounts it
+ * on commit/cancel.
+ *
+ * V1 simplification: rotation is NOT applied to the textarea — rotated text
+ * elements are edited in a non-rotated overlay at the element's AABB origin.
+ * The textarea stays axis-aligned to avoid browser textarea rotation bugs.
+ * Document the intent: a v2 pass may add a CSS transform to align with rotation.
+ *
+ * Commit: Meta+Enter or blur → emits `onCommit(newText)`.
+ * Cancel: Escape → emits `onCancel()` and restores pre-edit text.
+ */
+import type { TextElement } from '../../design-canvas/model';
+interface InlineTextEditorProps {
+    element: TextElement;
+    zoom: number;
+    panX: number;
+    panY: number;
+    onCommit(text: string): void;
+    onCancel(): void;
+}
+export declare function InlineTextEditor({ element, zoom, panX, panY, onCommit, onCancel, }: InlineTextEditorProps): import("react").JSX.Element;
+export {};

package/dist/design-canvas-react/components/LayersPanel.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Layers panel — reverse-z list of the active page's elements. Highest z-index
+ * is at the top. Groups show their children indented beneath them. Clicking
+ * selects an element; meta-click adds to selection. Double-clicking the name
+ * opens an inline rename input. Eye and lock icons toggle visibility/locked.
+ * Rows can be drag-reordered within the list (siblings only; cross-group reorder
+ * is a pending integrator concern). Capped at LAYERS_PANEL_ROW_LIMIT rows.
+ */
+import type { SceneElement, ScenePage } from '../../design-canvas/model';
+export interface LayersPanelProps {
+    page: ScenePage;
+    selectedElementIds: string[];
+    canWrite: boolean;
+    /** Emit a set_attrs command for the given element. */
+    onSetAttrs(elementId: string, attrs: Partial<Pick<SceneElement, 'name' | 'visible' | 'locked'>>): void;
+    /** Emit a reorder_element command. */
+    onReorder(elementId: string, toIndex: number): void;
+    onSelect(elementId: string, additive: boolean): void;
+}
+export declare function LayersPanel({ page, selectedElementIds, canWrite, onSetAttrs, onReorder, onSelect }: LayersPanelProps): import("react").JSX.Element;

package/dist/design-canvas-react/components/PagesStrip.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Horizontal page-thumbnail strip shown at the bottom of the editor. The active
+ * page is highlighted. Thumbnails are rendered externally (Konva; the host
+ * injects `renderThumbnail` so this component stays canvas-free and testable).
+ *
+ * Actions: add page, duplicate active page, delete active page (disabled when
+ * only one page remains), drag-reorder pages. The strip is read-only when
+ * `canWrite` is false.
+ */
+import type { ScenePage } from '../../design-canvas/model';
+export interface PagesStripProps {
+    pages: ScenePage[];
+    activePageId: string;
+    canWrite: boolean;
+    /**
+     * The host provides this to generate thumbnail data-URLs. The strip calls it
+     * on mount and debounces re-calls on document changes. Returns null when the
+     * thumbnail is not yet available (the strip renders a placeholder instead).
+     */
+    renderThumbnail(page: ScenePage): Promise<string | null>;
+    onSelectPage(pageId: string): void;
+    onAddPage(): void;
+    onDuplicatePage(pageId: string): void;
+    onDeletePage(pageId: string): void;
+    onReorderPage(pageId: string, toIndex: number): void;
+    /** Show page-management affordances (add / duplicate / delete). Default true.
+     *  The review surface passes false: pages are navigated, not authored. */
+    canManagePages?: boolean;
+    /** Heading shown above the strip so it reads as page management. Overridable;
+     *  defaults to "Pages". Set to '' to hide the visible label (the container
+     *  keeps its accessible name regardless). */
+    label?: string;
+}
+export declare function PagesStrip({ pages, activePageId, canWrite, renderThumbnail, onSelectPage, onAddPage, onDuplicatePage, onDeletePage, onReorderPage, canManagePages, label, }: PagesStripProps): import("react").JSX.Element;

package/dist/design-canvas-react/components/Rulers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Horizontal (top) and vertical (left) canvas rulers. Each ruler:
+ * - Draws zoom-scaled tick marks via `buildRulerTicks` / `selectTickStep`.
+ * - Shows a pointer-position indicator (a hairline that follows the cursor).
+ * - Supports guide creation by dragging OUT of the ruler: a live preview line
+ *   appears while dragging; on drop a `set_page_guides` command is emitted.
+ * - Existing guides that are dragged BACK into the ruler are deleted.
+ * - Renders saved guides persistently, Figma-style: a marker in the ruler
+ *   track at each guide position, plus a thin line spanning the canvas (the
+ *   GuidesCanvasOverlay sibling, aligned with the track coordinate space).
+ *
+ * All interaction math lives in ruler-math.ts and is testable without a DOM.
+ * The rulers themselves are pure DOM (no Konva); they sit in a CSS grid slot
+ * next to the workspace canvas.
+ */
+import type { PageGuides } from '../../design-canvas/model';
+export interface RulersProps {
+    /** Page width in document px. */
+    pageWidth: number;
+    /** Page height in document px. */
+    pageHeight: number;
+    zoom: number;
+    /** How many doc-px of the canvas are scrolled off-screen left/top. */
+    scrollLeft: number;
+    scrollTop: number;
+    showRulers: boolean;
+    guides: PageGuides;
+    /** Emitted when the user drops a guide or deletes one back into the ruler. */
+    onGuidesChange(guides: PageGuides): void;
+}
+export declare function Rulers({ pageWidth, pageHeight, zoom, scrollLeft, scrollTop, showRulers, guides, onGuidesChange }: RulersProps): import("react").JSX.Element | null;

package/dist/design-canvas-react/components/SelectionLayer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Transformer-based selection layer. Attaches a Konva.Transformer to all
+ * currently-selected Konva nodes so the user can resize and rotate them.
+ *
+ * SINGLE vs. MULTI:
+ * - Single selection: resize + rotate.
+ * - Multi-selection: rigid resize (keepRatio enforced) + rotate.
+ *
+ * Rotation snap: within 5° of 0/45/90/135/180 the rotation locks to the
+ * nearest cardinal/diagonal (same threshold as the snapRotation pure function).
+ *
+ * Scale baking: Konva's Transformer sets scaleX/scaleY on the node during
+ * a transform gesture. On transformend we read the final x/y/width/height/
+ * scaleX/scaleY/rotation from each node, bake scale into width/height, and
+ * emit ONE multiSetAttrsCommand. Scale never persists on Konva nodes across
+ * render cycles — the next render resets scaleX=scaleY=1 by rendering from
+ * model attrs.
+ *
+ * Special baking per kind:
+ * - rect/ellipse/image/video/group: bakeRectTransform (scale → width/height).
+ * - line: bakeLineTransform (scale baked into points array).
+ * - text: bakeTextTransform (scaleX→width, scaleY→fontSize).
+ * - ellipse: center position is adjusted back to top-left model coords via
+ *   ellipseTopLeftFromCenter before emitting attrs.
+ *
+ * Min-size guard: width/height are clamped to ≥ 4px after baking so users
+ * cannot collapse an element to zero and lose it.
+ *
+ * The overlay: prefix on the Transformer name lets export logic skip it.
+ */
+import type Konva from 'konva';
+import type { MultiSetAttrsEntry } from '../engine/commands';
+import type { SceneElement } from '../../design-canvas/model';
+import { type CanvasRenderPalette } from '../../theme/theme';
+export interface SelectionLayerProps {
+    /** Konva stage reference to look up selected nodes by name. */
+    stageRef: React.RefObject<Konva.Stage | null>;
+    /** Selected element ids from editor state. */
+    selectedIds: string[];
+    /** The model elements corresponding to selectedIds (pre-gesture snapshot). */
+    selectedElements: SceneElement[];
+    /** Whether the canvas is writable. False → transformer renders but is not interactive. */
+    canWrite: boolean;
+    /** Emitted when a transform gesture completes with final attrs per element. */
+    onTransformEnd(entries: MultiSetAttrsEntry[]): void;
+    /** Active page id — every entry in onTransformEnd carries this. */
+    pageId: string;
+    /** Theme render palette. Omitted → light defaults (byte-identical history). */
+    render?: CanvasRenderPalette;
+}
+export declare function SelectionLayer({ stageRef, selectedIds, selectedElements, canWrite, onTransformEnd, pageId, render, }: SelectionLayerProps): import("react").JSX.Element;

package/dist/design-canvas-react/components/SnapGuidesOverlay.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Active snap guides rendered as full-page-extent lines during drag gestures.
+ * Renders into a dedicated Konva.Layer (name 'overlay:snap') so export logic
+ * can exclude it.
+ *
+ * Guide line colors differ by kind so users can distinguish grid snaps (faint)
+ * from element-edge/center snaps (accent) from saved ruler guides (blue).
+ */
+import type { SnapTarget } from '../contracts';
+import { type CanvasRenderPalette } from '../../theme/theme';
+interface SnapGuidesOverlayProps {
+    /** Page dimensions in document px. */
+    pageWidth: number;
+    pageHeight: number;
+    /** Active vertical guide, or null when not snapping. */
+    activeVertical: SnapTarget | null;
+    /** Active horizontal guide, or null when not snapping. */
+    activeHorizontal: SnapTarget | null;
+    /** Screen px per document px — used to compute 1-px-screen stroke widths. */
+    zoom: number;
+    /** Theme render palette. Omitted → light defaults (byte-identical history). */
+    render?: CanvasRenderPalette;
+}
+export declare function SnapGuidesOverlay({ pageWidth, pageHeight, activeVertical, activeHorizontal, zoom, render, }: SnapGuidesOverlayProps): import("react").JSX.Element | null;
+export {};

package/dist/design-canvas-react/components/Toolbar.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Selection-aware toolbar. When elements are selected it shows per-kind
+ * attribute controls; when nothing is selected it shows page-props controls.
+ * Every number input commits on blur or Enter as a single command (not
+ * per-keystroke). The toolbar is stateless beyond transient input focus;
+ * the caller owns the command stack.
+ *
+ * Layout: the root never scrolls horizontally. Global controls (undo/redo +
+ * view toggles) are pinned left; the selection/page attribute group wraps so
+ * the whole bar fits the editor's center column (viewport minus the w-64 side
+ * panel and w-80 agent panel) at 1024–1280px with nothing clipped.
+ */
+import type { SceneElement, ScenePage } from '../../design-canvas/model';
+import type { SceneAttrsPatch } from '../../design-canvas/operations';
+import type { PageBleed } from '../../design-canvas/model';
+import type { DesignCanvasMode } from '../contracts';
+export interface ToolbarProps {
+    page: ScenePage;
+    selectedElements: SceneElement[];
+    canWrite: boolean;
+    /** Capability mode. `'review'` (the lean reviewer) hides the view toggles,
+     *  page-props controls, and the destructive/structural selection controls
+     *  (z-order, group/ungroup, lock, slot, delete), keeping only safe direct
+     *  edits: text content, image fit/replace, opacity/rotation, undo/redo.
+     *  Defaults to `'edit'` (the full authoring toolbar). */
+    mode?: DesignCanvasMode;
+    canUndo: boolean;
+    canRedo: boolean;
+    gridEnabled: boolean;
+    snapEnabled: boolean;
+    showRulers: boolean;
+    showBleed: boolean;
+    onUndo(): void;
+    onRedo(): void;
+    onToggleGrid(): void;
+    onToggleSnap(): void;
+    onToggleRulers(): void;
+    onToggleBleed(): void;
+    /** Emit attrs patch for each selected element. */
+    onSetAttrs(elementId: string, attrs: SceneAttrsPatch): void;
+    onSetPageProps(props: {
+        name?: string;
+        width?: number;
+        height?: number;
+        background?: string;
+        bleed?: PageBleed | null;
+    }): void;
+    onSetPageGuides(guides: {
+        vertical: number[];
+        horizontal: number[];
+    }): void;
+    onReorder(elementId: string, toIndex: number, ownerLength: number, direction: 'front' | 'back' | 'forward' | 'backward'): void;
+    onGroup(elementIds: string[]): void;
+    onUngroup(groupId: string): void;
+    onDelete(elementIds: string[]): void;
+    onBindSlot(elementId: string, slot: string | null): void;
+    /** Field label for the page-size control. Defaults to the clearer "Page size";
+     *  overridable for consumers that want the older "Preset" wording. */
+    pageSizeLabel?: string;
+    /** Title for the "turn on print bleed" action. Defaults to "Show print bleed"
+     *  (the outcome) rather than the print-shop term "bleed". */
+    enableBleedLabel?: string;
+}
+export declare function Toolbar({ page, selectedElements, canWrite, mode, canUndo, canRedo, gridEnabled, snapEnabled, showRulers, showBleed, onUndo, onRedo, onToggleGrid, onToggleSnap, onToggleRulers, onToggleBleed, onSetAttrs, onSetPageProps, onSetPageGuides, onReorder, onGroup, onUngroup, onDelete, onBindSlot, pageSizeLabel, enableBleedLabel, }: ToolbarProps): import("react").JSX.Element;