@aglyn/aglyn 1.0.0-beta.143

package/src/lib/canvas-manager/canvas-manager.d.ts

@@ -0,0 +1,549 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ObservableMap } from 'mobx';
+import type { Aglyn } from '../aglyn';
+import type { NodeInteraction } from '../app-utils/node-interactions';
+import type { PluginId } from '../plugin-manager';
+import { type ComponentId, type ComponentSchema, type NodeBreadcrumbPath, type NodeId, type NodeSchema, type NodeSchemaJSON, type NodeSchemaNested, type NodesMap, NodeType, type PresetSchema, type ProcessableNodes } from '../types/nodes';
+export declare const NODE_ROOT_ID = "_@_";
+export declare const NODE_ROOT_LABEL = "Document";
+export declare class AglynNode<P = JSX.AnyProps> implements NodeSchema<P> {
+    store: CanvasManager;
+    $id: NodeId;
+    name?: string;
+    type: NodeType | string;
+    pluginId?: PluginId;
+    componentId?: ComponentId;
+    parentId?: NodeId;
+    nodes?: NodeId[];
+    props: P;
+    sx?: JSX.SxProps;
+    className?: string;
+    /**
+     * Per-instance style overrides (AGL-1306) — see `NodeSchema`. Assigned
+     * by name like every other field: this constructor DROPS unknown
+     * top-level keys, so forgetting a field here silently strips it from
+     * every canvas round-trip.
+     */
+    styleOverrides?: Record<string, JSX.SxProps>;
+    /**
+     * Per-instance attribute overrides (AGL-1899) — see `NodeSchema`. Same
+     * three-touch-point rule as `styleOverrides` above: declared here,
+     * assigned in the constructor, emitted in `toJSON`. Miss one and the
+     * field survives in memory but not across a save.
+     */
+    attrOverrides?: Record<string, Record<string, unknown>>;
+    /**
+     * Interactions authored on this element — see `NodeSchema`.
+     * Third field under the same three-touch-point rule as the two above:
+     * declared here, assigned in the constructor, emitted in `toJSON`.
+     */
+    interactions?: NodeInteraction[];
+    /**
+     * Hidden by the author — see `NodeSchema`. Same three touch
+     * points, and it needs all of them for a second reason as well: an
+     * undeclared field assigned at runtime is not observable, so the hierarchy
+     * row would not repaint when the eye was clicked.
+     */
+    hidden?: boolean;
+    get parent(): NodeSchema<any> | undefined;
+    get index(): number | null;
+    get children(): NodeSchema<any>[];
+    get labelShort(): string;
+    get breadcrumbPath(): NodeBreadcrumbPath;
+    get componentSchema(): ComponentSchema | undefined;
+    get hasNodes(): boolean;
+    get resolvedProps(): P;
+    get asJSON(): NodeSchemaJSON<P>;
+    constructor(schema: NodeSchema<P>, store: CanvasManager);
+    delete(): void;
+    toJSON: () => NodeSchemaJSON<P>;
+}
+export declare class CanvasManager {
+    aglyn: Aglyn;
+    /**
+     * How long a coalesced burst stays open. Comfortably above typing cadence
+     * and slider tick rate, well below the pause that means "a new adjustment".
+     */
+    static readonly COALESCE_WINDOW_MS = 500;
+    private _initial;
+    /**
+     * Whether {@link _initial} is a state the STORE has confirmed, or merely
+     * one the client believes. See {@link updateInitialNodes}.
+     */
+    private _initialConfirmed;
+    private _history;
+    /** The open {@link transact} burst, if any. See that method. */
+    private _coalescing;
+    /** How deep the running {@link batch} calls are nested; 0 outside one. */
+    private _batchDepth;
+    /**
+     * Monotonic counter, bumped once per node a REMOTE session changes. See
+     * {@link markRemoteNode} and {@link restoreSnapshot} (AGL-1958).
+     */
+    private _epoch;
+    /** Node id → the {@link _epoch} at which a remote session last touched it. */
+    private _foreignAt;
+    constructor(aglyn: Aglyn);
+    get nodes(): ObservableMap<string, NodeSchema<any>>;
+    get canRedo(): boolean;
+    get canUndo(): boolean;
+    /**
+     * True when the canvas matches the last state the store is known to hold —
+     * i.e. there is nothing to save.
+     *
+     * An UNCONFIRMED baseline (see {@link updateInitialNodes}) always reads as
+     * different. The editor is loaded, but nothing in it is known to be
+     * persisted, and "clean" here disables Save: claiming a state is saved on
+     * the strength of a snapshot the server never acknowledged is how unsaved
+     * work becomes unsavable work (AGL-1262).
+     */
+    get isInitialSame(): boolean;
+    get didSetInitial(): boolean;
+    /** Whether the recorded baseline is one the store confirmed. */
+    get isInitialConfirmed(): boolean;
+    get rootNode(): NodeSchema<any>;
+    get nestedNodes(): NodeSchemaNested<any>;
+    hasNode: ($id: NodeId) => boolean;
+    getNode: ($id: NodeId) => NodeSchema<any> | undefined;
+    nodesAreEqual: (left: NodesMap, right?: NodesMap) => boolean;
+    getNodeParent: (node: NodeSchema<any>) => NodeSchema<any> | undefined;
+    getNodeIndex: (node: NodeSchema<any>) => number;
+    isRootNodeId: (id: NodeId) => id is string & typeof NODE_ROOT_ID;
+    isRootNode: (node: NodeSchema<any>) => boolean;
+    getNodeBreadcrumbPath: (nodeOrId: NodeId | NodeSchema<any>) => NodeBreadcrumbPath;
+    getNodeLabelShort: (node: NodeSchema<any>) => any;
+    /**
+     * Whether a node can host inserted child nodes. The document root and
+     * layout containers (Stack, Section, Container — anything with a real
+     * children slot) can; a leaf whose component is self-closing or renders
+     * its `children` as inline text (a screen link, button, icon, image) has
+     * no slot to receive them and can't. Components with no registered schema
+     * default to accepting children.
+     *
+     * `flags.dropping: DISABLED` is the third way to say "no canvas child
+     * slot" (AGL-1388), for components that are neither self-closing nor text
+     * leaves but still have nowhere to put a dropped node:
+     *
+     * - Markdown renders the parsed `content` prop and nothing else, so a
+     *   dropped element lands somewhere the markdown source cannot say.
+     * - A Reusable Component instance is opaque: compose REPLACES its child
+     *   list with the grafted definition subtree, so a canvas-dropped child is
+     *   destroyed before the page is rendered.
+     * - A Layout Slot's children come from screen composition.
+     *
+     * The flag was declared on all three, and until now nothing read it —
+     * which is exactly how three /press screenshots came to be parented under
+     * a Markdown node, shipped in the page payload, and never drawn. A
+     * container that accepts children in the hierarchy and discards them at
+     * render is silent data loss: the author sees the nodes in the tree and
+     * the published page does not have them.
+     *
+     * The rule itself lives in {@link schemaAcceptsChildren} (AGL-1389) so the
+     * registry audit that enforces it cannot be checking a *copy* of it — a
+     * second implementation would drift, and would then certify the editor's
+     * behaviour against a rule the editor no longer follows.
+     */
+    nodeAcceptsChildren: (node: NodeSchema<any>) => boolean;
+    /**
+     * Resolve where a newly inserted node should attach, given the node the
+     * user had selected (the Insert menu passes the current selection). A
+     * container target — including the document-root fallback for a missing,
+     * stale, or non-node target (AGL-537) — receives the node as an appended
+     * child. A leaf target has no child slot, so the node lands as the leaf's
+     * next sibling in its own container instead, mirroring how a
+     * drag-and-drop side-drop resolves rather than nesting the node where it
+     * can never render.
+     */
+    resolveInsertTarget(target?: NodeSchema<any>): {
+        parent: NodeSchema<any>;
+        index: number;
+    };
+    makeNested: (node: NodeSchema<any>) => NodeSchemaNested<any>;
+    private serializeNodes;
+    toJSON(): {
+        nodes: NodesMap;
+    };
+    redo(): this;
+    undo(): this;
+    saveHistory(): this;
+    /**
+     * Records that a REMOTE session changed `nodeId`, so a later local undo
+     * does not roll that change back (AGL-1958).
+     *
+     * Call this from the co-editing apply path for every node a peer creates,
+     * changes or deletes — including the delete, whose absence is as much a
+     * remote state as a value is.
+     *
+     * ## Why this is needed at all
+     *
+     * Applying a remote change deliberately does NOT record local history
+     * (AGL-677 rule 1), which keeps a colleague's edit out of your undo
+     * stack. That is necessary and it is not sufficient. Every entry already
+     * in the stack is a snapshot of the WHOLE document taken before one of
+     * your edits, and a colleague's later edit is by definition not in it. So
+     * an undo that replays such a snapshot wholesale reverts their node too,
+     * and — because the reverted map is then diffed against the co-editing
+     * shadow like any other local edit — publishes that revert back to them
+     * under YOUR session id. Their work is destroyed on their screen, with no
+     * signal and nothing that restores it.
+     *
+     * Measured before this fix: a peer's edit came back reverted, and a node
+     * the peer had CREATED was deleted outright.
+     *
+     * ## An apply that changed nothing is not a peer edit (AGL-2486)
+     *
+     * `previousJson` is the node's serialization from BEFORE the apply. When
+     * the apply left it byte-for-byte identical, this records nothing: no
+     * mark, no epoch bump. That is not an optimisation, it is the difference
+     * between a peer edit and an ECHO, and getting it wrong broke undo
+     * outright.
+     *
+     * The mirror is per node and every session in the room republishes what it
+     * holds, so a value you wrote can come back to you from ANOTHER SESSION —
+     * your own second tab most of all, which is ordinary once same-account
+     * sessions count as co-editors. The room already drops your own tab's
+     * echoes by session id, but not another session's echo of your value.
+     *
+     * Marking that echo is fatal because the mark is what {@link
+     * restoreSnapshot} reads. It lands with a FRESH epoch, therefore newer
+     * than every snapshot already on your stack, so the overlay puts the live
+     * value back over each one of them. Undo then consumed its entry and
+     * changed nothing at all — measured on the running editor, one account,
+     * two tabs on one screen: `past: 0, future: 1, canUndo: false`, the node
+     * still holding the edit that had just been undone.
+     *
+     * Note what this deliberately does NOT do: it does not ask whose session
+     * or whose account the change came from. A genuinely different value from
+     * your other tab is a real concurrent edit with its own undo stack and is
+     * protected like any other. "Foreign" keeps its one meaning — a session
+     * other than this tab moved this node — and the defect was counting a
+     * non-change as a change.
+     */
+    markRemoteNode(nodeId: NodeId, previousJson?: string): this;
+    /**
+     * A node's serialization as it stands right now, for handing back to
+     * {@link markRemoteNode} after an apply — the "before" half of the echo
+     * test. `undefined` when the node is not in the map.
+     */
+    serializeNode(nodeId: NodeId): string | undefined;
+    /**
+     * Restores a history snapshot, keeping every node a remote session has
+     * touched SINCE that snapshot was taken (AGL-1958).
+     *
+     * The epoch comparison is the whole mechanism, and it is what keeps undo
+     * honest rather than merely safe:
+     *
+     * * `foreignAt > snapshot.epoch` — the peer's change landed *after* this
+     *   snapshot, so the snapshot predates it and would roll it back. Keep
+     *   what is live now: the current value, or the node's absence when the
+     *   peer deleted it.
+     * * `foreignAt <= snapshot.epoch` — the snapshot was taken after the
+     *   peer's change and therefore already contains it. Restore it normally,
+     *   or undo would stop rewinding your own edits to co-edited nodes.
+     *
+     * A node both you and a peer changed resolves to the peer's value, which
+     * is the same last-writer-wins rule the per-node mirror applies
+     * everywhere else (AGL-677) rather than a new one invented here.
+     *
+     * A peer that adds a child republishes the parent's child list, so the
+     * parent is marked too and its list survives with the child.
+     *
+     * ## Both directions, and why redo is not the special case it looks like
+     *
+     * This serves {@link redo} as well as {@link undo}, and the stamp is what
+     * makes that work rather than a second rule (AGL-2486). A `future` entry
+     * replays a state from before the undo, so the intuition is that it must
+     * predate any later peer change and roll it back. It does not:
+     * `HistoryManager.undo` captures the present and stamps it with the epoch
+     * AT THE TIME OF THE UNDO, so a peer change that lands between the undo
+     * and the redo is strictly newer than `snapshot.epoch` and is kept here —
+     * including a node the peer CREATED in that gap, which the `future` entry
+     * has no key for at all and a bare replace would broadcast as a delete.
+     */
+    private restoreSnapshot;
+    /**
+     * Overlays the nodes a remote session has touched since `sinceEpoch` onto a
+     * map about to REPLACE the canvas — the current value, or the node's
+     * absence when the peer deleted it (AGL-1958).
+     *
+     * Shared by {@link restoreSnapshot} and {@link applyNodes} because it is
+     * one rule, not two: any wholesale replace composed without knowledge of a
+     * peer's change would otherwise roll that change back and — through the
+     * co-editing diff — publish the rollback to its author.
+     *
+     * Mutates and returns `json`; callers pass a map they own.
+     */
+    private withForeignNodes;
+    /**
+     * Whether any REMOTE session has changed this canvas since it loaded
+     * (AGL-2486).
+     *
+     * The draft prompt reads it to decide whether offering a private
+     * per-browser snapshot back is still honest: once a colleague's live work
+     * is on the canvas, applying an older whole-document snapshot is not
+     * "restore my unsaved changes" but "roll the shared canvas back".
+     *
+     * `_epoch` only ever moves in {@link markRemoteNode}, so a non-zero epoch
+     * IS "a peer has touched this canvas", and {@link reset} returns it to zero
+     * with the rest of the session.
+     */
+    get hasRemoteEdits(): boolean;
+    /**
+     * Runs `mutate` as one undoable step (AGL-1204).
+     *
+     * Every mutator on this class records history for itself, but a panel that
+     * writes `node.sx` directly does not go through any of them — the Styles and
+     * custom-CSS forms assign to the node, so an undo after a style change
+     * restored the last *recorded* snapshot instead, silently discarding
+     * everything done since. This is the seam those panels were missing.
+     *
+     * **`coalesceKey` is what makes it usable for a live-applying control.**
+     * Those forms fire on every change — one per character typed, one per drag
+     * tick of a slider — so recording unconditionally would replace "undo does
+     * not step back far enough" with "undo steps back one character", which is
+     * no better. Consecutive calls sharing a key inside {@link
+     * COALESCE_WINDOW_MS} record **once**, at the start of the burst, so the
+     * snapshot is the state *before* the adjustment began. Omit the key for a
+     * discrete commit (a toggle, an Apply button) that deserves its own step.
+     *
+     * The window is evaluated on call rather than by a timer: a burst ends
+     * because the next edit arrives late, not because something fired in the
+     * background. That keeps the canvas free of pending timers it would have to
+     * cancel on {@link reset}, and keeps this testable without fake clocks.
+     *
+     * The key should identify *what* is being adjusted, not just the node —
+     * moving from Gap to Padding is a second adjustment even if it happens
+     * within the window.
+     */
+    transact<T>(mutate: () => T, coalesceKey?: string): T;
+    /**
+     * Runs several mutations as ONE undoable step, all or nothing.
+     *
+     * `transact` records one snapshot and then runs code that assigns to nodes
+     * directly. That is right for a panel writing `node.sx`, and wrong for a
+     * caller that composes the guarded mutators — `addNodeFromNested`,
+     * `updateNodeProps`, `reparentNode`, `deleteNode` — because each of those
+     * records its own step. A change made of five of them would take five
+     * undos to take back, and an undo that stops part-way leaves the document
+     * in a state nobody authored.
+     *
+     * So inside a batch the mutators keep every guard and record nothing: the
+     * batch's own snapshot, taken before `mutate` runs, is the step. A nested
+     * batch folds into the outer one.
+     *
+     * A mutation that throws — a guard refusing a stale parent, a move into
+     * the node's own subtree — rolls the whole batch back to that snapshot
+     * and removes the snapshot from both stacks before the error propagates.
+     * Half a batch is not an edit anyone asked for, and a refused batch must
+     * not leave an undo step that restores a state identical to the present.
+     */
+    batch<T>(mutate: () => T): T;
+    /**
+     * Drops BOTH history stacks and any open {@link transact} burst.
+     *
+     * Both, deliberately (AGL-2486). This used to clear `past` alone, which
+     * left a caller that had just "cleared history" holding a live redo stack
+     * — `canRedo` still true, still offering a snapshot of the state before
+     * the clear. `reset` was the only caller and compensated for it a line
+     * later, which is exactly how the next caller inherits the trap.
+     *
+     * A stale redo is worse than a stale undo in a co-editing session: redo
+     * replays a WHOLE-DOCUMENT snapshot, and the restored map is diffed
+     * against the co-editing shadow and published, so every node the snapshot
+     * does not have goes out as a delete under this session's id.
+     */
+    clearHistory(): void;
+    createNodeId(): NodeId;
+    createNode(schema: PartialKeys<NodeSchema<any>, '$id'>): NodeSchema<any>;
+    clearNodes(): this;
+    /**
+     * Returns the canvas to its pristine state (no nodes, no history, no
+     * recorded initial snapshot). The canvas is an app-level singleton shared
+     * by every editing session — call this when a session ends so the next
+     * document doesn't inherit stale content.
+     */
+    reset(): this;
+    /**
+     * Record the state the canvas should be considered saved against.
+     *
+     * `confirmed` is what makes this honest. Pass `false` when the map came
+     * from a source the STORE has not acknowledged — a Firestore snapshot
+     * carrying this client's own pending write is the case that motivated it
+     * (AGL-1262): the document is loaded and must be shown, but nothing in it
+     * is known to have reached the server, so it must not be adopted as
+     * "already saved". An unconfirmed baseline keeps {@link isInitialSame}
+     * false — the editor stays savable — until a real save records a
+     * confirmed one.
+     */
+    updateInitialNodes(nodes?: NodesMap, options?: {
+        confirmed?: boolean;
+    }): this;
+    /**
+     * Promote an UNCONFIRMED baseline to a confirmed one, once the store has
+     * acknowledged the write that made it unconfirmed (AGL-2486).
+     *
+     * Without this there is no way back. `_initialConfirmed` moves to true in
+     * only two other places — {@link reset} and {@link updateInitialNodes} —
+     * and the editor records its baseline exactly once, on the first snapshot
+     * that carries nodes. A document whose first snapshot happens to carry
+     * this client's own queued write therefore reads dirty for the rest of the
+     * session over content nobody has edited.
+     *
+     * Conditional on the canvas still MATCHING the baseline, which is what
+     * keeps AGL-1262 intact. The acknowledgement is for the write that was in
+     * flight, and says nothing about work the author has done since; adopting
+     * a canvas that has moved on would call that work saved and take away the
+     * only control that could still write it.
+     *
+     * @returns whether the baseline is confirmed as a result.
+     */
+    confirmInitialNodes(): boolean;
+    /**
+     * Registers a node in the map AND lists it on `parent`, in one action
+     * (AGL-1366).
+     *
+     * `parent` is required, and that is the whole point: this was the last way
+     * left to put an entry in `this.nodes` with no parent linkage at all. The
+     * besigner saves a flat map and renders a tree — `serializeNodes` dumps
+     * every entry in the map while the renderer walks child lists down from
+     * `NODE_ROOT_ID` — so a node the map holds and no parent lists is not a
+     * rendering glitch that a reload clears. It is saved on every save,
+     * shipped in every payload, counted against the 1 MiB ceiling, and never
+     * drawn. That is the mechanism behind the 61 unreachable nodes `/product`
+     * served, 26 of them carrying the only copy of two Hero sections' text
+     * (AGL-1363).
+     *
+     * An *optional* parent would not have closed it, because the caller who
+     * omits it is precisely the caller who creates the orphan. So the linkage
+     * is not a second step a caller may forget — it happens here, and the
+     * parent is resolved through `getNode($id)` and throws on a miss: the same
+     * guard `addNodeFromNested` has carried since AGL-537 and `reparentNode`
+     * took on in AGL-1363, rather than a second mechanism. A stale instance a
+     * panel closure kept across a co-editor's merge, or a parent a peer has
+     * since deleted, therefore fails loud instead of stranding the node.
+     *
+     * Linking is idempotent: re-setting a node its parent already lists
+     * replaces the map entry and leaves the child list untouched, so this
+     * stays usable as an update.
+     *
+     * The root is refused outright — it has no parent to be listed on, and
+     * seeding it belongs to `setNodes`, which alone keeps its canonical id.
+     */
+    setNode(node: NodeSchema<any>, parent: NodeSchema<any> | NodeId, index?: number, create?: boolean): NodeSchema<any>;
+    setNodes(schemas: NodesMap, merge?: boolean): this;
+    /**
+     * Replaces the whole node map with a map the USER supplied — the raw-JSON
+     * editor, and the local draft the crash net offers back (AGL-2486).
+     *
+     * Snapshots first, so the replacement is undoable — unlike `setNodes`,
+     * which also serves the history-restore and initial-load paths.
+     *
+     * **Every node a remote session has touched survives it**, on exactly the
+     * reasoning AGL-1958 established for undo. A wholesale replace is the same
+     * shape of write as a snapshot restore: the map being applied was composed
+     * without any knowledge of the peer's later changes, and the result is
+     * diffed against the co-editing shadow and published, so a node the map
+     * happens to lack is broadcast as a DELETE under this session's id.
+     * Measured on the running editor before this changed (AGL-2486): a peer
+     * created a node, the other session pressed Restore, and the node vanished
+     * from the peer's own canvas with an RTDB tombstone to show for it.
+     *
+     * Every mark counts, not only those newer than some epoch: unlike a
+     * snapshot, an applied map carries no epoch of its own, and a draft was by
+     * definition composed before this page joined the room.
+     */
+    applyNodes(value: ProcessableNodes): this;
+    deleteNode(node: NodeSchema<any>): this;
+    /**
+     * Moves a node under `newParent`, resolving BOTH ends through the live
+     * node map first (AGL-1363).
+     *
+     * The resolution is the guard, and it is the same one `addNodeFromNested`
+     * has carried since AGL-537. This method splices the node out of its
+     * *live* old parent and then attaches it to the object it was handed — so
+     * a `newParent` that is merely SHAPED like a node (a stale instance a
+     * panel closure kept across a co-editor's merge, a node a peer has since
+     * deleted, historically a click event) took the node out of the tree and
+     * pushed its id onto a detached array. Nothing put it back.
+     *
+     * That is not a recoverable glitch: `serializeNodes` dumps the whole map
+     * while the renderer walks the tree from `NODE_ROOT_ID`, so a node in the
+     * map that no live parent lists is saved on every save, shipped in every
+     * payload, counted against the 1 MiB ceiling — and never drawn. It is why
+     * `/product` served 61 unreachable nodes, 26 of them carrying the only
+     * copy of two Hero sections' text. Fail loud instead.
+     *
+     * `index` is the node's position in the resulting sibling list — i.e. it is
+     * read AFTER the node has been spliced out of wherever it was. A caller
+     * holding a drop marker ("put it before the sibling currently at 3") is
+     * describing the list BEFORE the removal and has to convert; the dnd
+     * manager does exactly that for same-parent drops.
+     */
+    reparentNode(node: NodeSchema<any>, newParent: NodeSchema<any>, index?: number): typeof node;
+    reorderNode(node: NodeSchema<any>, index?: number): typeof node;
+    duplicateNode(node: NodeSchema<any>): NodeSchema<any>;
+    createDuplicateNode(node: NodeSchemaNested<any>): NodeSchemaNested<any>;
+    /**
+     * Insert a *detached* nested subtree as a child of `parent`, minting a
+     * fresh id for every node in it (AGL-1202).
+     *
+     * The subtree is plain JSON with no ties to this canvas, so the source can
+     * be anything — an element preset, the besigner clipboard, or a subtree
+     * copied out of a different document altogether. Callers are responsible
+     * for checking that the root's component is registered and that the
+     * lineal relationship with `parent` is allowed; this method only does the
+     * structural work.
+     */
+    addNodeFromNested(nested: NodeSchemaNested<any>, parent: NodeSchema<any>, index?: number): NodeSchema<any>;
+    addNodeFromPreset(preset: PresetSchema<any>, parent: NodeSchema<any>, index?: number): NodeSchema<any>;
+    /**
+     * REPLACES a node's props — callers spread the current ones to merge.
+     *
+     * An editor form submits every field it renders, so keys the author left
+     * empty arrive as `undefined`. Those are dropped here rather than stored as
+     * own keys (AGL-1334): for a props bag that is REPLACED wholesale, absent IS
+     * cleared, and an `undefined` member is a value no storage layer accepts.
+     * `AglynNode.toJSON` strips again at the write boundary — this one keeps the
+     * live tree honest for everything that reads it before a save.
+     */
+    /**
+     * Writes top-level node FIELDS, with an undo step.
+     *
+     * The sibling of {@link updateNodeProps}, and it exists for the same two
+     * reasons that one documents. An edit with no `saveHistory` is an edit the
+     * author cannot take back — and every panel that assigned to a node
+     * directly was quietly in that state. And it re-resolves by `$id`: callers
+     * hold node objects across time (the focus store keeps the selection that
+     * way), while every wholesale replace of the map — `undo`, `redo`,
+     * `applyNodes`, a draft restore — builds fresh instances. Assigning to the
+     * caller's copy then mutates an orphan: no error, no dirty state, and the
+     * author's edit is simply gone.
+     *
+     * Only the keys the patch names are touched, and `undefined` clears one —
+     * which is how a cleared style or a shown element is stored, since `toJSON`
+     * omits what is undefined.
+     */
+    updateNodeFields(node: NodeSchema<any>, patch: Partial<NodeSchema<any>>): void;
+    updateNodeProps(node: NodeSchema<any>, props: NodeSchema<any>['props']): void;
+    static nestDenormalizedNodes(nodes: NodesMap, rootId?: NodeId): NodeSchemaNested<any>;
+    denormalizeNodes(nodes: NodeSchemaNested<any>[], parentId: NodeId, accumulator?: NodesMap): NodesMap;
+    static denormalizeNodes(nodes: NodeSchemaNested<any>[], parentId: NodeId, accumulator?: NodesMap): NodesMap;
+    processNodesToDenormalized(value: ProcessableNodes): NodesMap;
+    static processNodesToDenormalized(value: ProcessableNodes): NodesMap;
+}
+export default CanvasManager;