@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/hooks/use-anchored-rect.d.ts

@@ -0,0 +1,68 @@
+export interface AnchoredRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Tracks where an anchor element actually is, for the fixed overlays that edit
+ * a canvas element in place (AGL-1644).
+ *
+ * ## The bug this fixes
+ *
+ * `inline-text-editor` and `inline-markdown-editor` both anchored on a
+ * `getBoundingClientRect()` taken ONCE, when the double-click opened them. The
+ * rect was never recomputed, so scrolling the canvas — or resizing the window,
+ * or switching the artboard's device preview — left the editor sitting over
+ * unrelated chrome while the element it was editing had moved away. It matters
+ * most for the markdown editor, where the document is routinely taller than the
+ * viewport and scrolling mid-edit is ordinary rather than exceptional.
+ *
+ * ## Why the live rect IS "the canvas's own coordinate system"
+ *
+ * The overlays render outside the canvas' CLOSED shadow root, so viewport
+ * coordinates are the only frame of reference the two sides share — there is no
+ * canvas-space transform to be had from outside. `getBoundingClientRect()` on
+ * the live element is that shared frame, continuously: it already accounts for
+ * every ancestor's scroll, for the shadow host's own layout, and for any CSS
+ * transform in between.
+ *
+ * That last point is the pan/zoom answer. `ZoomablePanningComponent` is NOT
+ * currently mounted — the only reference to it in the canvas is a commented-out
+ * import in `viewport-canvas.component.tsx` — so there is no transform to
+ * handle today. If one is ever mounted, a live rect follows it with no further
+ * work, which a stored rect plus a hand-written transform never would.
+ *
+ * ## The listeners, and why they are the ones NodeOverlay already uses
+ *
+ * This is deliberately the same recipe as `node-overlay.tsx`, which solved this
+ * exact problem for the selection outline: a `ResizeObserver` on the element and
+ * on its shadow host, `resize` on the window, and — the one that matters here —
+ * a CAPTURE-phase `scroll` listener, because scroll does not bubble and the
+ * scrolling ancestor may be the canvas container, a panel, or the page body.
+ *
+ * ## The anchor is passed in, not looked up
+ *
+ * `Besigner.refs.get($id)` would cover three of the four ways these editors
+ * open, and silently miss the fourth: an instance prop edit (AGL-1304) anchors
+ * on a GRAFTED preview leaf, which is not a canvas node and has no ref. The
+ * call site already holds the exact element it measured, so it hands it over.
+ *
+ * With no anchor — a store opened without one, or a test — the fallback rect is
+ * returned unchanged, so the previous behavior is what a caller gets for free.
+ */
+export declare function useAnchoredRect(anchor: Element | undefined, fallback: AnchoredRect): AnchoredRect;
+/**
+ * Keeps a following overlay reachable when its anchor leaves the viewport.
+ *
+ * The clamp is not a substitute for the tracking above and is not a second one:
+ * AGL-1624 clamped a rect that never changed, which is why its own author
+ * called it a floor rather than a fix. Applied to a LIVE rect it means what it
+ * says — while the element is off-screen the editor waits at the nearest edge,
+ * and it slides back onto the element the moment the element is visible again.
+ *
+ * Reading the viewport size at render is safe precisely because the hook above
+ * re-renders on every scroll and resize, so the value is never stale.
+ */
+export declare function clampToViewport(value: number, size: number, extent: number, margin?: number): number;
+export default useAnchoredRect;

package/src/lib/hooks/use-anchored-rect.js

@@ -0,0 +1,131 @@
+/**
+ * @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.
+ */ 'use client';
+import { useIsomorphicLayoutEffect } from "@aglyn/shared-ui-jsx";
+import { useState } from "react";
+/**
+ * Tracks where an anchor element actually is, for the fixed overlays that edit
+ * a canvas element in place (AGL-1644).
+ *
+ * ## The bug this fixes
+ *
+ * `inline-text-editor` and `inline-markdown-editor` both anchored on a
+ * `getBoundingClientRect()` taken ONCE, when the double-click opened them. The
+ * rect was never recomputed, so scrolling the canvas — or resizing the window,
+ * or switching the artboard's device preview — left the editor sitting over
+ * unrelated chrome while the element it was editing had moved away. It matters
+ * most for the markdown editor, where the document is routinely taller than the
+ * viewport and scrolling mid-edit is ordinary rather than exceptional.
+ *
+ * ## Why the live rect IS "the canvas's own coordinate system"
+ *
+ * The overlays render outside the canvas' CLOSED shadow root, so viewport
+ * coordinates are the only frame of reference the two sides share — there is no
+ * canvas-space transform to be had from outside. `getBoundingClientRect()` on
+ * the live element is that shared frame, continuously: it already accounts for
+ * every ancestor's scroll, for the shadow host's own layout, and for any CSS
+ * transform in between.
+ *
+ * That last point is the pan/zoom answer. `ZoomablePanningComponent` is NOT
+ * currently mounted — the only reference to it in the canvas is a commented-out
+ * import in `viewport-canvas.component.tsx` — so there is no transform to
+ * handle today. If one is ever mounted, a live rect follows it with no further
+ * work, which a stored rect plus a hand-written transform never would.
+ *
+ * ## The listeners, and why they are the ones NodeOverlay already uses
+ *
+ * This is deliberately the same recipe as `node-overlay.tsx`, which solved this
+ * exact problem for the selection outline: a `ResizeObserver` on the element and
+ * on its shadow host, `resize` on the window, and — the one that matters here —
+ * a CAPTURE-phase `scroll` listener, because scroll does not bubble and the
+ * scrolling ancestor may be the canvas container, a panel, or the page body.
+ *
+ * ## The anchor is passed in, not looked up
+ *
+ * `Besigner.refs.get($id)` would cover three of the four ways these editors
+ * open, and silently miss the fourth: an instance prop edit (AGL-1304) anchors
+ * on a GRAFTED preview leaf, which is not a canvas node and has no ref. The
+ * call site already holds the exact element it measured, so it hands it over.
+ *
+ * With no anchor — a store opened without one, or a test — the fallback rect is
+ * returned unchanged, so the previous behavior is what a caller gets for free.
+ */ export function useAnchoredRect(anchor, fallback) {
+    const [rect, setRect] = useState(null);
+    useIsomorphicLayoutEffect(()=>{
+        var _ref;
+        var _anchor_getRootNode;
+        if (!anchor || typeof anchor.getBoundingClientRect !== 'function') {
+            setRect(null);
+            return;
+        }
+        const update = ()=>{
+            const next = anchor.getBoundingClientRect();
+            setRect({
+                left: next.left,
+                top: next.top,
+                width: next.width,
+                height: next.height
+            });
+        };
+        update();
+        // ResizeObserver is not in every jsdom setup; the listeners below still
+        // carry the case this issue is actually about.
+        const observer = typeof ResizeObserver === 'function' ? new ResizeObserver(update) : null;
+        observer == null ? void 0 : observer.observe(anchor);
+        const shadowHost = (_ref = (_anchor_getRootNode = anchor.getRootNode()) == null ? void 0 : _anchor_getRootNode.host) != null ? _ref : null;
+        if (shadowHost) observer == null ? void 0 : observer.observe(shadowHost);
+        window.addEventListener('resize', update, {
+            passive: true
+        });
+        // Scroll does not bubble: only a capture-phase listener on the window sees
+        // an ancestor scroll, and an ancestor scroll is the whole bug.
+        window.addEventListener('scroll', update, {
+            passive: true,
+            capture: true
+        });
+        return ()=>{
+            observer == null ? void 0 : observer.disconnect();
+            window.removeEventListener('resize', update);
+            window.removeEventListener('scroll', update, {
+                capture: true
+            });
+        };
+    }, [
+        anchor
+    ]);
+    return rect != null ? rect : fallback;
+}
+/**
+ * Keeps a following overlay reachable when its anchor leaves the viewport.
+ *
+ * The clamp is not a substitute for the tracking above and is not a second one:
+ * AGL-1624 clamped a rect that never changed, which is why its own author
+ * called it a floor rather than a fix. Applied to a LIVE rect it means what it
+ * says — while the element is off-screen the editor waits at the nearest edge,
+ * and it slides back onto the element the moment the element is visible again.
+ *
+ * Reading the viewport size at render is safe precisely because the hook above
+ * re-renders on every scroll and resize, so the value is never stale.
+ */ export function clampToViewport(value, size, extent, margin = 8) {
+    const max = extent - size - margin;
+    // A viewport smaller than the overlay has no satisfying answer; pin to the
+    // near edge rather than letting the clamp invert and push it off the other.
+    if (max <= margin) return margin;
+    return Math.min(Math.max(value, margin), max);
+}
+export default useAnchoredRect;
+
+//# sourceMappingURL=use-anchored-rect.js.map

package/src/lib/hooks/use-anchored-rect.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/hooks/use-anchored-rect.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport { useIsomorphicLayoutEffect } from '@aglyn/shared-ui-jsx'\nimport { useState } from 'react'\n\nexport interface AnchoredRect {\n  left: number\n  top: number\n  width: number\n  height: number\n}\n\n/**\n * Tracks where an anchor element actually is, for the fixed overlays that edit\n * a canvas element in place (AGL-1644).\n *\n * ## The bug this fixes\n *\n * `inline-text-editor` and `inline-markdown-editor` both anchored on a\n * `getBoundingClientRect()` taken ONCE, when the double-click opened them. The\n * rect was never recomputed, so scrolling the canvas — or resizing the window,\n * or switching the artboard's device preview — left the editor sitting over\n * unrelated chrome while the element it was editing had moved away. It matters\n * most for the markdown editor, where the document is routinely taller than the\n * viewport and scrolling mid-edit is ordinary rather than exceptional.\n *\n * ## Why the live rect IS \"the canvas's own coordinate system\"\n *\n * The overlays render outside the canvas' CLOSED shadow root, so viewport\n * coordinates are the only frame of reference the two sides share — there is no\n * canvas-space transform to be had from outside. `getBoundingClientRect()` on\n * the live element is that shared frame, continuously: it already accounts for\n * every ancestor's scroll, for the shadow host's own layout, and for any CSS\n * transform in between.\n *\n * That last point is the pan/zoom answer. `ZoomablePanningComponent` is NOT\n * currently mounted — the only reference to it in the canvas is a commented-out\n * import in `viewport-canvas.component.tsx` — so there is no transform to\n * handle today. If one is ever mounted, a live rect follows it with no further\n * work, which a stored rect plus a hand-written transform never would.\n *\n * ## The listeners, and why they are the ones NodeOverlay already uses\n *\n * This is deliberately the same recipe as `node-overlay.tsx`, which solved this\n * exact problem for the selection outline: a `ResizeObserver` on the element and\n * on its shadow host, `resize` on the window, and — the one that matters here —\n * a CAPTURE-phase `scroll` listener, because scroll does not bubble and the\n * scrolling ancestor may be the canvas container, a panel, or the page body.\n *\n * ## The anchor is passed in, not looked up\n *\n * `Besigner.refs.get($id)` would cover three of the four ways these editors\n * open, and silently miss the fourth: an instance prop edit (AGL-1304) anchors\n * on a GRAFTED preview leaf, which is not a canvas node and has no ref. The\n * call site already holds the exact element it measured, so it hands it over.\n *\n * With no anchor — a store opened without one, or a test — the fallback rect is\n * returned unchanged, so the previous behavior is what a caller gets for free.\n */\nexport function useAnchoredRect(\n  anchor: Element | undefined,\n  fallback: AnchoredRect,\n): AnchoredRect {\n  const [rect, setRect] = useState<AnchoredRect | null>(null)\n\n  useIsomorphicLayoutEffect(() => {\n    if (!anchor || typeof anchor.getBoundingClientRect !== 'function') {\n      setRect(null)\n      return\n    }\n    const update = () => {\n      const next = anchor.getBoundingClientRect()\n      setRect({\n        left: next.left,\n        top: next.top,\n        width: next.width,\n        height: next.height,\n      })\n    }\n    update()\n\n    // ResizeObserver is not in every jsdom setup; the listeners below still\n    // carry the case this issue is actually about.\n    const observer =\n      typeof ResizeObserver === 'function' ? new ResizeObserver(update) : null\n    observer?.observe(anchor)\n    const shadowHost = (anchor.getRootNode() as ShadowRoot | null)?.host ?? null\n    if (shadowHost) observer?.observe(shadowHost)\n\n    window.addEventListener('resize', update, { passive: true })\n    // Scroll does not bubble: only a capture-phase listener on the window sees\n    // an ancestor scroll, and an ancestor scroll is the whole bug.\n    window.addEventListener('scroll', update, { passive: true, capture: true })\n\n    return () => {\n      observer?.disconnect()\n      window.removeEventListener('resize', update)\n      window.removeEventListener('scroll', update, { capture: true })\n    }\n  }, [anchor])\n\n  return rect ?? fallback\n}\n\n/**\n * Keeps a following overlay reachable when its anchor leaves the viewport.\n *\n * The clamp is not a substitute for the tracking above and is not a second one:\n * AGL-1624 clamped a rect that never changed, which is why its own author\n * called it a floor rather than a fix. Applied to a LIVE rect it means what it\n * says — while the element is off-screen the editor waits at the nearest edge,\n * and it slides back onto the element the moment the element is visible again.\n *\n * Reading the viewport size at render is safe precisely because the hook above\n * re-renders on every scroll and resize, so the value is never stale.\n */\nexport function clampToViewport(\n  value: number,\n  size: number,\n  extent: number,\n  margin = 8,\n): number {\n  const max = extent - size - margin\n  // A viewport smaller than the overlay has no satisfying answer; pin to the\n  // near edge rather than letting the clamp invert and push it off the other.\n  if (max <= margin) return margin\n  return Math.min(Math.max(value, margin), max)\n}\n\nexport default useAnchoredRect\n"],"names":["useIsomorphicLayoutEffect","useState","useAnchoredRect","anchor","fallback","rect","setRect","getBoundingClientRect","update","next","left","top","width","height","observer","ResizeObserver","observe","shadowHost","getRootNode","host","window","addEventListener","passive","capture","disconnect","removeEventListener","clampToViewport","value","size","extent","margin","max","Math","min"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAEA,SAASA,yBAAyB,QAAQ,uBAAsB;AAChE,SAASC,QAAQ,QAAQ,QAAO;AAShC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CC,GACD,OAAO,SAASC,gBACdC,MAA2B,EAC3BC,QAAsB;IAEtB,MAAM,CAACC,MAAMC,QAAQ,GAAGL,SAA8B;IAEtDD,0BAA0B;;YAqBJG;QApBpB,IAAI,CAACA,UAAU,OAAOA,OAAOI,qBAAqB,KAAK,YAAY;YACjED,QAAQ;YACR;QACF;QACA,MAAME,SAAS;YACb,MAAMC,OAAON,OAAOI,qBAAqB;YACzCD,QAAQ;gBACNI,MAAMD,KAAKC,IAAI;gBACfC,KAAKF,KAAKE,GAAG;gBACbC,OAAOH,KAAKG,KAAK;gBACjBC,QAAQJ,KAAKI,MAAM;YACrB;QACF;QACAL;QAEA,wEAAwE;QACxE,+CAA+C;QAC/C,MAAMM,WACJ,OAAOC,mBAAmB,aAAa,IAAIA,eAAeP,UAAU;QACtEM,4BAAAA,SAAUE,OAAO,CAACb;QAClB,MAAMc,sBAAcd,sBAAAA,OAAOe,WAAW,uBAAnB,AAACf,oBAA4CgB,IAAI,mBAAI;QACxE,IAAIF,YAAYH,4BAAAA,SAAUE,OAAO,CAACC;QAElCG,OAAOC,gBAAgB,CAAC,UAAUb,QAAQ;YAAEc,SAAS;QAAK;QAC1D,2EAA2E;QAC3E,+DAA+D;QAC/DF,OAAOC,gBAAgB,CAAC,UAAUb,QAAQ;YAAEc,SAAS;YAAMC,SAAS;QAAK;QAEzE,OAAO;YACLT,4BAAAA,SAAUU,UAAU;YACpBJ,OAAOK,mBAAmB,CAAC,UAAUjB;YACrCY,OAAOK,mBAAmB,CAAC,UAAUjB,QAAQ;gBAAEe,SAAS;YAAK;QAC/D;IACF,GAAG;QAACpB;KAAO;IAEX,OAAOE,eAAAA,OAAQD;AACjB;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASsB,gBACdC,KAAa,EACbC,IAAY,EACZC,MAAc,EACdC,SAAS,CAAC;IAEV,MAAMC,MAAMF,SAASD,OAAOE;IAC5B,2EAA2E;IAC3E,4EAA4E;IAC5E,IAAIC,OAAOD,QAAQ,OAAOA;IAC1B,OAAOE,KAAKC,GAAG,CAACD,KAAKD,GAAG,CAACJ,OAAOG,SAASC;AAC3C;AAEA,eAAe7B,gBAAe"}

package/src/lib/hooks/use-besigner-app-context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022 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.
+ */
+export { useBesignerAppContext, default as BesignerAppContext, } from '../contexts/besigner-app-context';
+export { useBesignerAppContext as default } from '../contexts/besigner-app-context';

package/src/lib/hooks/use-besigner-app-context.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2022 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.
+ */ export { useBesignerAppContext, default as BesignerAppContext } from "../contexts/besigner-app-context.js";
+export { useBesignerAppContext as default } from "../contexts/besigner-app-context.js";
+
+//# sourceMappingURL=use-besigner-app-context.js.map

package/src/lib/hooks/use-besigner-app-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/besigner/feature/designer/src/lib/hooks/use-besigner-app-context.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport {\n  useBesignerAppContext,\n  default as BesignerAppContext,\n} from '../contexts/besigner-app-context'\nexport { useBesignerAppContext as default } from '../contexts/besigner-app-context'\n"],"names":["useBesignerAppContext","default","BesignerAppContext"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,qBAAqB,EACrBC,WAAWC,kBAAkB,QACxB,sCAAkC;AACzC,SAASF,yBAAyBC,OAAO,QAAQ,sCAAkC"}

package/src/lib/hooks/use-besigner-document.d.ts

@@ -0,0 +1,309 @@
+/**
+ * @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 { Firestore } from 'firebase/firestore';
+import type * as Aglyn from '@aglyn/aglyn';
+import { type BesignerDraftIds } from '../drafts/besigner-draft-store';
+import { type ServerDraftWrite } from '../drafts/besigner-server-draft';
+import { type BesignerDraftState } from './use-besigner-draft';
+/**
+ * How the host application surfaces a message. Deliberately a plain
+ * callback rather than a snackbar dependency: the console passes its
+ * `enqueueSnackbar`, and an embedder outside the console passes whatever it
+ * has (a toast, a console.log, nothing at all).
+ */
+export type BesignerNotify = (message: string, options?: {
+    variant?: 'info' | 'success' | 'warning' | 'error';
+    /**
+     * Presentation hints, passed through rather than derived from `variant`
+     * because the console's four editors deliberately mix them — a
+     * near-limit warning is transient, a concurrent-edit warning is not.
+     * An embedder without these concepts can ignore them.
+     */
+    persist?: boolean;
+    allowDuplicate?: boolean;
+}) => void;
+/**
+ * Begins a loading indication and returns the function that ends it. Same
+ * contract as the console's `queueLoading`; defaults to a no-op.
+ */
+export type BesignerQueueLoading = () => () => void;
+/**
+ * What this editor believes the stored document looked like when it last
+ * agreed with it, handed to `save` so a store can make the write
+ * conditional (AGL-1301) — a Firestore provider runs the same comparison
+ * inside a transaction, closing the window where a save lands between
+ * another writer's commit and the local snapshot's delivery.
+ */
+export interface BesignerSaveBaseline {
+    /** `versionStamp(...)` of the stored `updatedAt` at load/last agreement. */
+    baseStamp: string | null;
+    /** The stored nodes as of that agreement, in STORED shape. */
+    baseNodes: Aglyn.ProcessableNodes | undefined;
+}
+export interface BesignerDocumentSource<TData = unknown> {
+    /** The stored node map, or undefined while loading. */
+    nodes: Aglyn.ProcessableNodes | undefined;
+    /** Whatever the store stamps on write; used to detect concurrent edits. */
+    updatedAt?: unknown;
+    /**
+     * The snapshot `nodes` came from still carries writes this client made
+     * that the store has NOT acknowledged (Firestore's
+     * `snapshot.metadata.hasPendingWrites`).
+     *
+     * It decides whether the loaded document may be adopted as the *saved*
+     * state. It may not: a queued write is replayed into the first snapshot
+     * after a reload, so believing it would mean recording work the server
+     * never took as "already saved" — after which the editor is clean, Save is
+     * dead, and the canvas and the document disagree in silence (AGL-1262).
+     * Omitted (undefined) reads as confirmed, which is right for every store
+     * that has no such queue.
+     */
+    pendingWrites?: boolean;
+    status?: 'idle' | 'loading' | 'success' | 'error';
+    error?: {
+        message?: string;
+    } | null;
+    /**
+     * Persists the node map. Rejecting surfaces as an error notification —
+     * except `ConcurrentEditError`, which surfaces through the same refusal
+     * UX as the listener-side guard (AGL-1301). `baseline` is what this
+     * editor last agreed the stored document looked like; a store that can
+     * make the write conditional should (see `saveNodesGuarded`), and one
+     * that cannot may ignore it.
+     */
+    save: (nodes: Record<string, unknown>, baseline?: BesignerSaveBaseline) => Promise<void>;
+    data?: TData;
+}
+export interface UseBesignerDocumentOptions<TData = unknown> extends BesignerDocumentSource<TData> {
+    /**
+     * The word used in user-facing copy — 'screen', 'layout', 'component',
+     * 'template', 'email'. Keeps each editor's messages accurate without
+     * forking the logic.
+     */
+    noun: string;
+    /** Canvas view type; reset to SCREEN on unmount. */
+    viewType?: Aglyn.HostViewType;
+    /**
+     * Identity of the open document. Changing it re-arms the canvas reset,
+     * which is what stops one document's nodes leaking into the next.
+     */
+    documentKey?: string;
+    /**
+     * Identity for the local crash-recovery draft (AGL-1256). Omit and drafts
+     * are simply off for this editor.
+     *
+     * Deliberately separate from `documentKey`, which is not unique enough to
+     * key storage on: both email editors build it as
+     * `${templateKey}:${versionId}`, so a platform template and every host's
+     * override of the same key produce the same string.
+     */
+    draft?: BesignerDraftIds;
+    /**
+     * Enables the SHARED working draft — the one `Save draft` writes and
+     * `Save & publish` clears. Omit and the editor keeps the local crash net
+     * alone, which is what a document with no versions to hang a draft off
+     * should do.
+     */
+    firestore?: Firestore;
+    /**
+     * Other live editing sessions in this document's room, or null while
+     * presence has not settled — see `recoverableRoomSessions` (AGL-2486).
+     *
+     * Only the crash-recovery prompt reads it. The conflict guard deliberately
+     * does NOT: a room is a live-collaboration fact and saving must be
+     * protected whether or not presence is working at all.
+     */
+    roomSessions?: number | null;
+    notify?: BesignerNotify;
+    queueLoading?: BesignerQueueLoading;
+    /** Called after a successful save, for activity logging. */
+    onSaved?: () => void;
+    /**
+     * Called when a save was REFUSED or FAILED — the document does not hold the
+     * canvas.
+     *
+     * `onSaved` not firing is not enough to tell a caller that, because it also
+     * stays silent for "nothing to save", where the document already holds the
+     * canvas and every follow-on step is safe. The two need opposite handling by
+     * anything that acts on a save: `handleSaveAndPublish` promotes the version
+     * pointer afterwards, and promoting past a refusal publishes a version whose
+     * document never received the edit.
+     *
+     * Fired for every path that leaves the stored tree unchanged against the
+     * author's intent: a stale-baseline conflict, an unpreparable canvas, the
+     * size guard, and a thrown write. Each has already explained itself in a
+     * toast, so a caller's job is only to stop.
+     */
+    onSaveRefused?: () => void;
+    /**
+     * Overrides the success message. Defaults to `"<Noun> saved successfully"`;
+     * templates say simply "Template saved" and that copy is preserved rather
+     * than normalised by the extraction.
+     */
+    savedMessage?: string;
+    /**
+     * Maps the stored node map into what the canvas should render, for
+     * documents whose storage shape is not a canvas tree.
+     *
+     * Reusable components and component-kind templates store a *definition*,
+     * rooted at the promoted node rather than the canvas root — rendering one
+     * unwrapped gives a canvas with no root and a blank editor (AGL-680).
+     * Defaults to identity; putting a document back into its stored shape is
+     * the caller's `save`, which already owns that direction (AGL-681).
+     */
+    toCanvasNodes?: (nodes: Aglyn.ProcessableNodes) => Aglyn.ProcessableNodes;
+    /**
+     * The inverse of `toCanvasNodes`: maps the canvas tree back into the
+     * stored shape, and may refuse the save with a message.
+     *
+     * Runs *before* the size guard, so the guard measures what will actually
+     * be written rather than the canvas representation of it. A component-kind
+     * template that no longer has a single top-level element is rejected here
+     * (AGL-681).
+     */
+    fromCanvasNodes?: (canvasNodes: Record<string, unknown>) => {
+        nodes: Record<string, unknown>;
+    } | {
+        error: string;
+    };
+}
+/** Who a shared working draft records as its last writer. */
+export interface BesignerDraftAuthor {
+    uid?: string | null;
+    email?: string | null;
+}
+export interface UseBesignerDocumentResult {
+    /** True when the canvas differs from the last agreed state. */
+    saveAvailable: boolean;
+    /** True when someone else wrote this document since we loaded it. */
+    remoteChanged: boolean;
+    handleSave: () => Promise<void> | void;
+    /**
+     * Writes the SHARED working draft — what `Save draft` stores and
+     * `Save & publish` clears.
+     *
+     * Here rather than in each editor because of the one field an editor
+     * cannot get right on its own: `baseStamp`. A recovered draft is measured
+     * against `storedStamp`, which is this document's `updatedAt` — the
+     * VERSION document — and every console editor was stamping its draft from
+     * the PARENT document instead (`screens/{id}`, `components/{id}`, …). Two
+     * documents, two `updatedAt` fields, so the two values could only agree by
+     * coincidence: every working draft read back as "someone else saved this
+     * while you were editing", Restore was never offered, and the draft could
+     * never be recovered by anyone. Taking the stamp where the comparison is
+     * made is what stops the two drifting apart again.
+     *
+     * Resolves `'failed'` when this document cannot hold a shared draft — no
+     * `firestore`, or no draft ids — which is the same answer a rejected write
+     * gives, and the caller's handling of both is identical.
+     *
+     * Resolves `'unchanged'` WITHOUT writing when the canvas is clean
+     * (AGL-2874). A clean canvas is the stored document, so there is no draft
+     * to take — and writing one anyway would replace whatever saved draft the
+     * slot holds with a copy of the document it was drafted against.
+     */
+    saveWorkingDraft: (author?: BesignerDraftAuthor) => Promise<ServerDraftWrite>;
+    /**
+     * Refuses, and says why, an action that would leave behind a saved draft
+     * this author has been offered and has not opened (AGL-2874). Returns true
+     * when the caller must stop.
+     *
+     * `'publish'` for Save & publish and a Publish click: publishing stores and
+     * promotes the canvas, and a canvas that never took the draft in would go
+     * live without it — after which the draft is cleared as published. `'save'`
+     * for a draft save, which would overwrite it, and for a save of the
+     * document, which moves the stamp the draft was taken against and leaves
+     * it unopenable.
+     *
+     * Only while the offer is ON SCREEN and can be opened: the refusal points
+     * at the banner's Open draft and Discard, and must never point at buttons
+     * that are not there.
+     */
+    refuseOverUnopenedDraft: (action: 'save' | 'publish') => boolean;
+    /**
+     * Announce a write this editor is about to make to the SAME document
+     * outside `handleSave` — component properties are the first (AGL-1247).
+     *
+     * Without it the write's own echo is indistinguishable from a colleague's
+     * and trips the conflict guard, which pauses saving until reload: the
+     * editor accuses you of being someone else.
+     */
+    markOwnWrite: () => void;
+    /**
+     * Unsaved work recovered from local storage after a crash or reload, and
+     * the two things the author can do about it (AGL-1256). Always present;
+     * `available` is false when there is nothing to offer.
+     */
+    draft: BesignerDraftState;
+    /** JSON editor plumbing, identical in every editor. */
+    jsonOpen: boolean;
+    openJsonEditor: () => void;
+    closeJsonEditor: () => void;
+    handleJsonSave: (event: unknown, value: unknown) => void;
+    /**
+     * The document could not be read AND there is nothing to show for it
+     * (AGL-1066).
+     *
+     * Deliberately NOT "the read errored". Under `persistentLocalCache` a
+     * refused listen still serves the document from IndexedDB, and a refused
+     * listen can now reach `status: 'error'` — so an editor with a canvas full
+     * of the author's work would otherwise be replaced by "Not found" about two
+     * seconds into a stale session, mid-edit. Whether the console should keep
+     * SERVING that cached document is the question AGL-1066 settled as "keep
+     * serving, but stop presenting it as live"; the presentation half is the
+     * shell's re-auth banner and the refusal on save, not blanking the canvas.
+     *
+     * When the read failed and nothing ever arrived there is genuinely nothing
+     * to render, and this is true — which is the state the "Not found" branch
+     * was written for.
+     */
+    hasError: boolean;
+    notFound: boolean;
+    /**
+     * The document is on screen but the server has stopped answering for it
+     * (AGL-1066) — cached content, no refresh coming. Saving is already refused
+     * by the seed guards; this is what an editor would surface to say why.
+     */
+    staleContent: boolean;
+}
+/**
+ * Pushes a stored node map into the shared canvas singleton.
+ *
+ * The canvas root is guaranteed here rather than per editor (AGL-931). A map
+ * without one leaves the hierarchy showing 'Invalid node' with Add Element
+ * disabled — an editor the document can never be repaired from — and only
+ * the two definition-shaped editors passed a `toCanvasNodes` that repaired
+ * it. Doing it at the one point every editor loads through means no route
+ * can be added that forgets.
+ */
+export declare function setLocalNodes(value: Aglyn.ProcessableNodes): Aglyn.CanvasManager;
+/**
+ * The document-agnostic half of a besigner editor.
+ *
+ * Everything here was copy-pasted across the console's four besigner routes
+ * (screens, layouts, components, templates) — canvas lifecycle, first load,
+ * concurrent-write detection (AGL-674), the size-guarded save (AGL-678) and
+ * the JSON editor. None of it is about hosts, orgs, themes or publishing,
+ * so none of it belongs in a console route.
+ *
+ * It has **no console and no host dependency** by design: the caller
+ * supplies the document source and the notify/loading adapters. That is
+ * what lets besigner drive a document that has no host — the platform email
+ * templates — and, longer term, run outside the console entirely.
+ */
+export declare function useBesignerDocument<TData = unknown>(options: UseBesignerDocumentOptions<TData>): UseBesignerDocumentResult;
+export default useBesignerDocument;