@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/design-canvas-react/engine/command-stack.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Undo/redo command stack over immutable `EditorSceneState`.
+ *
+ * History entries hold COMMANDS (state transforms + durable operations
+ * captured at construction), never snapshots. Rebasing the document via
+ * `reset()` therefore cannot stale the history: a later undo re-applies the
+ * inverse transform to whatever document is current. If the rebase removed an
+ * element a historical command targets, that transform throws (fail loud)
+ * rather than silently editing the wrong element.
+ *
+ * `setView` updates volatile view state (zoom/pan/selection/toggles) without
+ * touching history — view changes are never undo steps.
+ */
+import type { SceneDocument } from '../../design-canvas/model';
+import type { SceneCommand, SceneCommandStack } from '../contracts';
+/** Oldest entries are dropped past this bound; redo stack is cleared on execute. */
+export declare const SCENE_COMMAND_HISTORY_LIMIT = 200;
+/**
+ * The base {@link SceneCommandStack} plus the two command-specific recovery
+ * primitives the undo/redo persistence path needs. `rollback` (on the base
+ * contract) undoes a failed COMMIT; these undo a failed UNDO/REDO persist.
+ * Defined here (not on the shared contract) so consumers that take the stack as
+ * `ReturnType<typeof createSceneCommandStack>` see them without a contract bump.
+ */
+export interface SceneCommandStackWithReapply extends SceneCommandStack {
+    /**
+     * A persisted UNDO rejected: re-apply that command's FORWARD transform (move
+     * it redo→undo). Mirrors `rollback`'s command-specific contract — it acts on
+     * the captured command, not blindly on the redo-stack top, so an interleaved
+     * edit cannot make it re-apply the wrong command. No-op if the command is not
+     * the top of the redo stack (a newer edit reshaped history — the next
+     * `reset()` reconciles).
+     */
+    reexecute(command: SceneCommand): void;
+    /**
+     * A persisted REDO rejected: re-apply that command's INVERSE transform (move
+     * it undo→redo). The redo-side mirror of `reexecute`. No-op unless the command
+     * is the top of the undo stack.
+     */
+    reundo(command: SceneCommand): void;
+}
+/** Create a command stack for scene editing with reapply capabilities based on the given document and page ID */
+export declare function createSceneCommandStack(document: SceneDocument, activePageId: string): SceneCommandStackWithReapply;

package/dist/design-canvas-react/engine/commands.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Concrete `SceneCommand` factories for the design-canvas editor. Every factory
+ * captures the inverse from PRE-state at construction — undo is a value
+ * computed once, never re-derived from current state later. Local execute/undo
+ * update `EditorSceneState` immutably by routing through `applySceneOperation`
+ * so optimistic state matches what the server-side dispatcher will persist.
+ *
+ * Drag gestures coalesce: pointer moves update volatile state, ONE command
+ * executes on pointer release with (finalAttrs, priorAttrs). `setAttrsCommand`
+ * is that gesture command — one undo step per drag/transform/toolbar change.
+ * `multiSetAttrsCommand` collects N set_attrs ops into one undo step for
+ * multi-select transforms.
+ *
+ * Group/ungroup route through `applySceneOperation` so the group-origin
+ * rebasing in `apply.ts` is the single source of truth for both optimistic and
+ * server state.
+ */
+import type { SceneDocument, SceneElement } from '../../design-canvas/model';
+import type { SceneAttrsPatch } from '../../design-canvas/operations';
+import type { SceneCommand } from '../contracts';
+/** Define input parameters for adding a scene element with optional index and parent group ID */
+export interface AddElementInput {
+    pageId: string;
+    element: SceneElement;
+    /** Insertion z-index within owner; omitted → top. */
+    index?: number;
+    /** Parent group id; omitted → page root. */
+    parentGroupId?: string;
+}
+/** Create a command to add an element to a scene with optional positioning and grouping */
+export declare function addElementCommand(input: AddElementInput): SceneCommand;
+/** Define input parameters for setting element attributes within a specific page context */
+export interface SetAttrsInput {
+    pageId: string;
+    elementId: string;
+    /** Final attribute values after the gesture. */
+    attrs: SceneAttrsPatch;
+    /** Attribute values BEFORE the gesture began — inverse is built from these. */
+    priorAttrs: SceneAttrsPatch;
+}
+/** Create a command to set attributes on a scene element with undo capability */
+export declare function setAttrsCommand(input: SetAttrsInput): SceneCommand;
+/** Define an entry linking page and element IDs with current and prior scene attribute patches */
+export interface MultiSetAttrsEntry {
+    pageId: string;
+    elementId: string;
+    attrs: SceneAttrsPatch;
+    priorAttrs: SceneAttrsPatch;
+}
+/** Build a scene command to set multiple attributes on elements across pages */
+export declare function multiSetAttrsCommand(entries: MultiSetAttrsEntry[]): SceneCommand;
+/** Define input parameters to reorder an element within a page */
+export interface ReorderElementInput {
+    pageId: string;
+    elementId: string;
+    toIndex: number;
+}
+/** Resolve a command to reorder an element within a scene by moving it to a specified index */
+export declare function reorderElementCommand(input: ReorderElementInput): SceneCommand;
+/** Define input parameters required to delete an element from a specific page in a document */
+export interface DeleteElementInput {
+    document: SceneDocument;
+    pageId: string;
+    elementId: string;
+}
+/** Resolve a command to delete an element from a specified page in the document */
+export declare function deleteElementCommand(input: DeleteElementInput): SceneCommand;
+/** Define input parameters for grouping elements within a scene document on a specific page */
+export interface GroupElementsInput {
+    document: SceneDocument;
+    pageId: string;
+    elementIds: string[];
+    groupId: string;
+    name?: string;
+}
+/** Create a command to group multiple elements into a single group within a scene */
+export declare function groupElementsCommand(input: GroupElementsInput): SceneCommand;
+/** Define input parameters required to ungroup elements within a specific page and group */
+export interface UngroupElementInput {
+    document: SceneDocument;
+    pageId: string;
+    groupId: string;
+}
+/** Resolve a command to ungroup a group element into its child elements within a scene */
+export declare function ungroupElementCommand(input: UngroupElementInput): SceneCommand;
+/** Define input parameters for adding a new page with optional settings and position index */
+export interface AddPageInput {
+    pageId: string;
+    options?: import('../../design-canvas/model').NewPageOptions;
+    index?: number;
+}
+/** Create a command to add a page with optional settings and index in the scene */
+export declare function addPageCommand(input: AddPageInput): SceneCommand;
+/** Define input parameters required to duplicate a page within a scene document */
+export interface DuplicatePageInput {
+    document: SceneDocument;
+    sourcePageId: string;
+    /** Caller-minted id for the copy. */
+    pageId: string;
+}
+/** Create a command to duplicate a page and prepare its deletion operation in the scene */
+export declare function duplicatePageCommand(input: DuplicatePageInput): SceneCommand;
+/** Define input parameters required to delete a page from a scene document */
+export interface DeletePageInput {
+    document: SceneDocument;
+    pageId: string;
+}
+/** Delete a page from a document ensuring it is not the last remaining page */
+export declare function deletePageCommand(input: DeletePageInput): SceneCommand;
+/** Define input parameters to reorder a page by specifying its ID and target index */
+export interface ReorderPageInput {
+    pageId: string;
+    toIndex: number;
+}
+/** Create a command to reorder a page to a specified index within a scene */
+export declare function reorderPageCommand(input: ReorderPageInput): SceneCommand;
+/** Define input parameters for setting properties on a specific page within a scene document */
+export interface SetPagePropsInput {
+    document: SceneDocument;
+    pageId: string;
+    props: {
+        name?: string;
+        width?: number;
+        height?: number;
+        background?: string;
+        bleed?: import('../../design-canvas/model').PageBleed | null;
+    };
+}
+/** Build a command to update page properties based on the provided input */
+export declare function setPagePropsCommand(input: SetPagePropsInput): SceneCommand;
+/** Define input parameters for setting guides on a specific page within a document */
+export interface SetPageGuidesInput {
+    document: SceneDocument;
+    pageId: string;
+    guides: import('../../design-canvas/model').PageGuides;
+}
+/** Create a command to update page guides with undo support */
+export declare function setPageGuidesCommand(input: SetPageGuidesInput): SceneCommand;
+/** Define input parameters for binding a slot within a scene document element */
+export interface BindSlotInput {
+    document: SceneDocument;
+    pageId: string;
+    elementId: string;
+    slot: string | null;
+}
+/** Bind a slot to an element within a page and generate the corresponding scene command */
+export declare function bindSlotCommand(input: BindSlotInput): SceneCommand;
+/** Define input parameters for setting the title of a scene document */
+export interface SetDocumentTitleInput {
+    document: SceneDocument;
+    title: string;
+}
+/** Resolve a command to rename a document title with undo and redo operations */
+export declare function setDocumentTitleCommand(input: SetDocumentTitleInput): SceneCommand;

package/dist/design-canvas-react/engine/selection.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Selection math for the design-canvas editor: marquee hit-tests, keyboard
+ * nudge deltas, and the duplicate offset constant. Pure functions — no DOM, no
+ * Konva, no React.
+ *
+ * Marquee inclusion: by default any element whose AABB intersects the marquee
+ * rect is included (the "touch" model). Pass `requireFullContainment: true` for
+ * the "surround" model where the marquee must fully contain the element. Locked
+ * and invisible elements are never selected regardless.
+ */
+import type { Bounds, ScenePage } from '../../design-canvas/model';
+/**
+ * Top-most selectable element whose AABB contains the document-space point, or
+ * null when the point is over empty space.
+ *
+ * This is the authoritative "is the pointer over an element?" test for the
+ * pointer-down gesture router. It runs against the scene model in document
+ * coordinates rather than Konva's hit-graph canvas, so it is independent of
+ * clip groups, listening flags, and hit-canvas redraw timing — all of which
+ * could make `stage.getIntersection` misclassify a press as empty space and
+ * silently start a marquee instead of an element drag.
+ *
+ * Z-order: later elements paint on top, so we scan the array in reverse and
+ * return the first hit. Groups descend into children (top child wins); a hit on
+ * a group child resolves to the group itself, matching drag/selection which
+ * operate on the group as a unit. Locked and invisible elements never hit.
+ */
+export declare function hitTestPoint(page: ScenePage, x: number, y: number): string | null;
+/** Define options to configure marquee selection behavior including containment requirements */
+export interface MarqueeSelectOptions {
+    /** When true, the element's AABB must be fully inside the marquee; default is
+     *  intersection (any overlap selects). */
+    requireFullContainment?: boolean;
+}
+/** Returns the ids of selectable elements on `page` whose AABB intersects (or
+ *  is contained by) `rect`. Locked and invisible elements are excluded. */
+export declare function marqueeSelect(page: ScenePage, rect: Bounds, opts?: MarqueeSelectOptions): string[];
+/** Represent horizontal and vertical displacement values for nudging elements */
+export interface NudgeDelta {
+    dx: number;
+    dy: number;
+}
+/** Map an arrow key to a document-px delta. `shift` engages the 10× step.
+ *  Throws on unknown keys so callers handle only real nudge keys. */
+export declare function nudgeDelta(key: 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown', shift: boolean): NudgeDelta;
+/** Document-px offset applied to duplicated elements so the copy is visually
+ *  separated from the original (matching common design-tool convention). */
+export declare const DUPLICATE_OFFSET: NudgeDelta;

package/dist/design-canvas-react/engine/snap.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 2-axis snap engine for the design-canvas editor. Targets come from element
+ * AABBs (edges + centers), page edges + center, saved guides, and grid lines
+ * near the moving bounds. Grid lines are generated lazily in the neighborhood
+ * of the moving element, not the full page — avoids allocating thousands of
+ * targets on large pages with fine grids.
+ *
+ * Threshold is a SCREEN distance (pixels), divided by zoom to convert to
+ * document units — what "feels close" is a screen distance.
+ *
+ * Tie-breaking: non-grid kinds beat grid on equal distance; among equals of
+ * the same priority the first in iteration order wins.
+ */
+import type { Bounds, ScenePage } from '../../design-canvas/model';
+import type { SnapEngine, SnapTarget } from '../contracts';
+/** Build a SnapEngine instance to manage snapping targets and behavior within an editor scene */
+export declare function createSnapEngine(): SnapEngine;
+/** Generate grid line targets within a neighborhood around the moving bounds.
+ *  Call this and append to `SnapTargets.vertical`/`horizontal` before
+ *  passing to `apply()` when `state.gridEnabled`. */
+export declare function collectGridTargets(bounds: Bounds, gridSize: number, page: ScenePage, thresholdDocPx: number): {
+    vertical: SnapTarget[];
+    horizontal: SnapTarget[];
+};

package/dist/design-canvas-react/engine/zoom-pan.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Zoom + pan coordinate math for the design-canvas editor. Zoom is pixels-per-
+ * document-px (e.g. 2 = 200% magnification). The key invariant for wheel-zoom
+ * is that the document point under the cursor stays fixed in screen space:
+ *
+ *   docPoint = (screenPoint - pan) / zoom
+ *   newPan   = screenPoint - docPoint * newZoom
+ *
+ * This module is pure math — no DOM, no Konva, no React.
+ */
+import type { ZoomPanMath } from '../contracts';
+/** Define configuration options for minimum and maximum zoom levels in a zoom-pan interface */
+export interface ZoomPanConfig {
+    minZoom: number;
+    maxZoom: number;
+}
+/** Create zoom and pan math utilities enforcing valid zoom range constraints */
+export declare function createZoomPanMath(config: ZoomPanConfig): ZoomPanMath;