@nuforge/editor 0.3.0 → 0.3.2

package/dist/react.cjs

@@ -6,27 +6,11 @@ var t = require('@nuforge/types');
 var react = require('react');
 var reactDom = require('react-dom');
 
-/**
- * Wire protocol for `RemoteCanvasHost` <-> `createCanvasReceiver`: a genuinely
- * navigated `/canvas/[id]`-style iframe has its own JS realm, so state and
- * interaction can't cross as direct object references the way `IframeCanvas`'s
- * portal allows — everything here is a structured-clone-safe plain message.
- *
- * Deliberately generic: only the shapes the editor primitive itself needs
- * (state sync, ready handshake, the core interaction events) are typed. Host
- * concerns like theme/preview-mode/overrides ride through `CanvasUiMessage`'s
- * opaque `payload` — this package relays it, never interprets it.
- */
 const CANVAS_CHANNEL = 'nuforge-canvas';
 const CANVAS_PROTOCOL_VERSION = 1;
-/** Namespace the `BroadcastChannel` per canvas instance (derive from the
- *  iframe's own `src`, so a host never has to invent/track a separate id). */
 function canvasChannelName(src) {
     return `${CANVAS_CHANNEL}:${src}`;
 }
-/** Narrow an arbitrary `BroadcastChannel` payload to a message from this
- *  protocol — guards against unrelated traffic on the same channel name and
- *  against a version mismatch across a stale cached bundle. */
 function isCanvasMessage(data) {
     return (!!data &&
         typeof data === 'object' &&
@@ -34,13 +18,6 @@ function isCanvasMessage(data) {
         data.v === CANVAS_PROTOCOL_VERSION);
 }
 
-/**
- * Compute a drop position from the pointer's Y against a target's bounding rect.
- * When `allowInside` is set, the middle band is `inside` (drop as a child) and
- * the outer bands are `before`/`after`; otherwise it's a simple before/after
- * split at the midpoint. Pure — use it from an `onDragOver`/`onPointerMove`
- * handler to drive a drop indicator and the eventual `moveNode`/`pasteNode`.
- */
 function dropPositionFromPointer(clientY, rect, opts = {}) {
     const ratio = rect.height > 0 ? (clientY - rect.top) / rect.height : 0;
     if (opts.allowInside) {
@@ -53,9 +30,6 @@ function dropPositionFromPointer(clientY, rect, opts = {}) {
     return ratio < 0.5 ? 'before' : 'after';
 }
 
-// Tag every rendered element with its template id so a canvas can map a clicked
-// DOM node back to its source node. Covers external components too, so they're
-// independently selectable/highlightable in the editor canvas.
 const decorate = (view) => ({
     'data-nu-id': view.template?.id,
 });
@@ -64,18 +38,6 @@ const AMBIENT_CANVAS_WINDOW = {
     window: typeof window === 'undefined' ? null : window,
 };
 const CanvasWindowContext = react.createContext(AMBIENT_CANVAS_WINDOW);
-/**
- * The real `window`/`document` a canvas-rendered element visually lives in.
- * `IframeCanvas` portals its content into an `<iframe>`, but a portal only
- * relocates DOM nodes — the JS building them still runs in the host page's
- * realm. Any library that reads a bare `window`/`document` global (scroll
- * listeners, `matchMedia`, `ResizeObserver`/`IntersectionObserver` defaults)
- * silently ends up watching the HOST page, not the iframe the user actually
- * sees and scrolls. Build refs/options from `useCanvasWindow()` instead of the
- * ambient global so they resolve to the right realm — this works identically
- * outside `IframeCanvas` too (e.g. `NuFrame`'s direct, non-iframe render),
- * where it's just the ambient `window`/`document`.
- */
 function useCanvasWindow() {
     return react.useContext(CanvasWindowContext);
 }
@@ -83,17 +45,14 @@ const EditorView = react.memo(function EditorView({ view, }) {
     const renderChildren = (views) => views.map((child) => react.createElement(EditorView, { key: child.key, view: child }));
     return react$1.createViewElement(view, renderChildren, decorate);
 });
-/** Reactive renderer for a frame, decorating each element with `data-nu-id`. */
 const EditorFrame = react$1.observer(function EditorFrame({ frame }) {
     return react.createElement(react.Fragment, null, frame.view.children.map((view) => react.createElement(EditorView, { key: view.key, view })));
 });
-/** Map a DOM node (or event target) back to its template id. */
 function templateIdFromElement(target) {
     return (target
         ?.closest('[data-nu-id]')
         ?.getAttribute('data-nu-id') ?? null);
 }
-/** Sensible default styling for the isolated canvas document. */
 const DEFAULT_CANVAS_CSS = `
   *, *::before, *::after { box-sizing: border-box; }
   html, body { margin: 0; }
@@ -112,13 +71,6 @@ const DEFAULT_CANVAS_CSS = `
   img { max-width: 100%; }
   [data-nu-id] { cursor: default; }
 `;
-/**
- * A style-isolated editor canvas: the frame is portaled into an `<iframe>` so
- * the host's CSS can't leak into the preview (and vice-versa). Selection/hover
- * use native capture listeners on the iframe document, so element handlers stay
- * inert while editing. Selection/hover rects are computed (in a layout effect,
- * after the iframe commits) and handed to `renderBox` for the overlay.
- */
 function IframeCanvas({ frame, selectedId = null, hoveredId = null, revision = 0, previewMode = false, onSelect, onHover, onDropOnNode, baseCss = DEFAULT_CANVAS_CSS, srcDoc, className, containerClassName, renderBox, }) {
     const iframeRef = react.useRef(null);
     const [doc, setDoc] = react.useState(null);
@@ -153,9 +105,6 @@ function IframeCanvas({ frame, selectedId = null, hoveredId = null, revision = 0
         if (!doc) {
             return;
         }
-        // In preview mode, only keep the scroll listener alive (so an overlay, if any
-        // lingers during a toggle, stays aligned). Skip the capturing click handler
-        // so element `onClick`s actually fire, and skip hover highlighting.
         const onScroll = () => setTick((x) => x + 1);
         doc.addEventListener('scroll', onScroll, true);
         if (previewMode) {
@@ -178,7 +127,6 @@ function IframeCanvas({ frame, selectedId = null, hoveredId = null, revision = 0
             doc.removeEventListener('scroll', onScroll, true);
         };
     }, [doc, previewMode, onSelect, onHover]);
-    // Drop-on-canvas: compute the drop target node + position from the pointer.
     react.useEffect(() => {
         if (!doc || !onDropOnNode || previewMode) {
             return;
@@ -195,7 +143,7 @@ function IframeCanvas({ frame, selectedId = null, hoveredId = null, revision = 0
                 setDrop(null);
                 return;
             }
-            e.preventDefault(); // allow the drop
+            e.preventDefault();
             setDrop({
                 rect: { top: r.top, left: r.left, width: r.width, height: r.height },
                 position: dropPositionFromPointer(e.clientY, r, { allowInside: true }),
@@ -221,8 +169,6 @@ function IframeCanvas({ frame, selectedId = null, hoveredId = null, revision = 0
             doc.removeEventListener('dragleave', onDragLeave);
         };
     }, [doc, onDropOnNode]);
-    // Recompute overlay rects when the iframe is resized (panel/device resize) or
-    // its content reflows — otherwise the selection box keeps a stale size.
     react.useEffect(() => {
         const iframe = iframeRef.current;
         if (!iframe) {
@@ -235,30 +181,19 @@ function IframeCanvas({ frame, selectedId = null, hoveredId = null, revision = 0
         }
         return () => observer.disconnect();
     }, [doc]);
-    // Drop-on-canvas indicator has no meaning while previewing.
     react.useEffect(() => {
         if (previewMode) {
             setDrop(null);
         }
     }, [previewMode]);
-    const rectOf = (id) => {
-        if (!doc || !id) {
-            return null;
-        }
-        const el = doc.querySelector(`[data-nu-id="${id}"]`);
+    const elementFor = (id) => doc && id ? doc.querySelector(`[data-nu-id="${id}"]`) : null;
+    const rectOfEl = (el) => {
         if (!el) {
             return null;
         }
         const r = el.getBoundingClientRect();
         return { top: r.top, left: r.left, width: r.width, height: r.height };
     };
-    const labelOf = (id) => {
-        if (!doc || !id) {
-            return null;
-        }
-        const el = doc.querySelector(`[data-nu-id="${id}"]`);
-        return el ? el.tagName.toLowerCase() : null;
-    };
     react.useLayoutEffect(() => {
         if (previewMode) {
             setSelected(null);
@@ -266,18 +201,14 @@ function IframeCanvas({ frame, selectedId = null, hoveredId = null, revision = 0
             setSelectedLabel(null);
             return;
         }
-        setSelected(rectOf(selectedId));
-        setHovered(hoveredId && hoveredId !== selectedId ? rectOf(hoveredId) : null);
-        setSelectedLabel(labelOf(selectedId));
+        const selectedEl = elementFor(selectedId);
+        setSelected(rectOfEl(selectedEl));
+        setHovered(hoveredId && hoveredId !== selectedId ? rectOfEl(elementFor(hoveredId)) : null);
+        setSelectedLabel(selectedEl ? selectedEl.tagName.toLowerCase() : null);
     }, [previewMode, selectedId, hoveredId, revision, tick, doc]);
     return react.createElement('div', { className: containerClassName, style: { position: 'relative' } }, react.createElement('iframe', { ref: iframeRef, title: 'nuforge preview', className, srcDoc }, doc?.body
         ? reactDom.createPortal(react.createElement(CanvasWindowContext.Provider, { value: { doc, window: doc.defaultView } }, react.createElement(EditorFrame, { frame })), doc.body)
-        : null), 
-    // The overlay is fully yours: omit `renderBox` for none, or build borders,
-    // labels and action toolbars from the computed rects + selectedLabel. The
-    // container is pointer-events:none; set pointerEvents:'auto' on interactive
-    // bits (e.g. an action toolbar) so clicks land.
-    renderBox && !previewMode
+        : null), renderBox && !previewMode
         ? react.createElement('div', {
             style: {
                 position: 'absolute',
@@ -288,22 +219,6 @@ function IframeCanvas({ frame, selectedId = null, hoveredId = null, revision = 0
         }, renderBox({ selected, hovered, selectedLabel, drop }))
         : null);
 }
-/**
- * The `IframeCanvas` alternative for when a canvas needs its OWN genuine JS
- * realm — e.g. so a third-party library reading bare `window`/`document` at
- * module scope (an animation library's scroll-linked internals, a gesture
- * library, ...) resolves against the canvas's real globals instead of
- * silently binding to the host page's. A portal can't fix this (see
- * `useCanvasWindow`'s docs for that half of the problem) because it only
- * relocates DOM nodes, not the JS module graph building them.
- *
- * Renders a genuinely-`src`-navigated `<iframe>` — no `createPortal`, so
- * nothing here shares object identity with the canvas's own React tree. State
- * flows one-way, host -> canvas, over a `BroadcastChannel` as `t.flatten`'d
- * JSON (see `./canvas-protocol`); interaction (select/hover/drop/keydown/
- * link-click) relays back the other way as small typed messages. Pair with
- * `createCanvasReceiver` (`./canvas-client`) on the canvas route's own end.
- */
 function RemoteCanvasHost({ nu, activeComponent, src, selectedId = null, hoveredId = null, revision = 0, previewMode = false, uiPayload, onSelect, onHover, onDropOnNode, onKeydownRelay, onLinkClick, className, containerClassName, renderBox, }) {
     const iframeRef = react.useRef(null);
     const [doc, setDoc] = react.useState(null);
@@ -332,10 +247,6 @@ function RemoteCanvasHost({ nu, activeComponent, src, selectedId = null, hovered
         onLinkClick,
     };
     const connectionRef = react.useRef(null);
-    // A same-origin `src` navigation still allows the host to read the iframe's
-    // own document for layout geometry — that's a plain DOM read, not blocked
-    // by realm separation (only shared JS object identity is). Used purely to
-    // size/position the overlay; no sync-protocol concern.
     react.useEffect(() => {
         const iframe = iframeRef.current;
         if (!iframe) {
@@ -419,14 +330,6 @@ function RemoteCanvasHost({ nu, activeComponent, src, selectedId = null, hovered
                     mountGen = message.mountGen;
                     ready = true;
                     sendInit();
-                    // The `uiPayload` effect below only fires again when the payload
-                    // itself changes — on a fresh mount (or a remount after an error
-                    // boundary), that push happens before the canvas has attached its
-                    // listener (it hasn't navigated/mounted yet) and is silently lost,
-                    // since BroadcastChannel doesn't buffer for late listeners. Resend
-                    // the CURRENT payload here too, gated on the same readiness signal
-                    // as the state bootstrap, so theme/overrides never depend on some
-                    // unrelated prop changing later to "unstick" them.
                     postUi(props.current.uiPayload);
                     break;
                 case 'select':
@@ -462,12 +365,7 @@ function RemoteCanvasHost({ nu, activeComponent, src, selectedId = null, hovered
             }
             connectionRef.current = null;
         };
-        // `nu` is stable for the app's lifetime; `src` identifies the channel.
-        // Everything else is read fresh off `props.current` inside the handlers.
     }, [src, nu]);
-    // A page switch or preview-mode transition needs a fresh `init`, not just an
-    // incremental `patch` — see `previewMode`'s doc above for why preview mode
-    // specifically must never let a local-only mutation linger into edit mode.
     const resyncKey = `${activeComponent}:${previewMode}`;
     const lastResyncKey = react.useRef(null);
     react.useEffect(() => {
@@ -480,24 +378,14 @@ function RemoteCanvasHost({ nu, activeComponent, src, selectedId = null, hovered
     react.useEffect(() => {
         connectionRef.current?.postUi(uiPayload);
     }, [uiPayload]);
-    const rectOf = (id) => {
-        if (!doc || !id) {
-            return null;
-        }
-        const el = doc.querySelector(`[data-nu-id="${id}"]`);
+    const elementFor = (id) => doc && id ? doc.querySelector(`[data-nu-id="${id}"]`) : null;
+    const rectOfEl = (el) => {
         if (!el) {
             return null;
         }
         const r = el.getBoundingClientRect();
         return { top: r.top, left: r.left, width: r.width, height: r.height };
     };
-    const labelOf = (id) => {
-        if (!doc || !id) {
-            return null;
-        }
-        const el = doc.querySelector(`[data-nu-id="${id}"]`);
-        return el ? el.tagName.toLowerCase() : null;
-    };
     react.useLayoutEffect(() => {
         if (previewMode) {
             setSelected(null);
@@ -505,9 +393,10 @@ function RemoteCanvasHost({ nu, activeComponent, src, selectedId = null, hovered
             setSelectedLabel(null);
             return;
         }
-        setSelected(rectOf(selectedId));
-        setHovered(hoveredId && hoveredId !== selectedId ? rectOf(hoveredId) : null);
-        setSelectedLabel(labelOf(selectedId));
+        const selectedEl = elementFor(selectedId);
+        setSelected(rectOfEl(selectedEl));
+        setHovered(hoveredId && hoveredId !== selectedId ? rectOfEl(elementFor(hoveredId)) : null);
+        setSelectedLabel(selectedEl ? selectedEl.tagName.toLowerCase() : null);
     }, [previewMode, selectedId, hoveredId, revision, tick, doc]);
     return react.createElement('div', { className: containerClassName, style: { position: 'relative' } }, react.createElement('iframe', {
         ref: iframeRef,
@@ -525,26 +414,16 @@ function RemoteCanvasHost({ nu, activeComponent, src, selectedId = null, hovered
         }, renderBox({ selected, hovered, selectedLabel }))
         : null);
 }
-// Structural param types (not the nominal `Editor` class), so these hooks accept
-// an Editor imported from the package's main entry without a dual-bundle clash.
-/** Re-render only when the tree shape changes (add/remove/move). */
 function useStructureRevision(editor) {
     const [rev, setRev] = react.useState(0);
     react.useEffect(() => editor.onStructureChange(() => setRev((r) => r + 1)), [editor]);
     return rev;
 }
-/** Re-render on every committed change (for undo state, inspectors, …). */
 function useEditorRevision(editor) {
     const [rev, setRev] = react.useState(0);
     react.useEffect(() => editor.onChange(() => setRev((r) => r + 1)), [editor]);
     return rev;
 }
-/**
- * A headless inspector renderer: builds a control per {@link PropSchemaField}
- * (text / number / checkbox / select / expression) so you don't hand-write a
- * form per block. Style via `className` and your own CSS; wire `onChange` to the
- * editor's mutation methods.
- */
 function PropFields({ fields, values, onChange, className, }) {
     return react.createElement('div', { className, 'data-nu-propfields': '' }, fields.map((field) => react.createElement(PropFieldControl, {
         key: field.name,
@@ -582,7 +461,6 @@ function PropFieldControl({ field, value, onChange, }) {
             }, (field.options ?? []).map((opt) => react.createElement('option', { key: opt, value: opt }, opt)));
             break;
         default:
-            // 'string' | 'expression'
             control = react.createElement('input', {
                 id,
                 type: 'text',
@@ -603,4 +481,3 @@ exports.templateIdFromElement = templateIdFromElement;
 exports.useCanvasWindow = useCanvasWindow;
 exports.useEditorRevision = useEditorRevision;
 exports.useStructureRevision = useStructureRevision;
-//# sourceMappingURL=react.cjs.map

package/dist/react.d.ts

@@ -3,7 +3,6 @@ import { ReactNode } from 'react';
 import * as t from '@nuforge/types';
 import { MutationEntry } from '@nuforge/reactivity';
 
-/** A control hint for auto-generating inspector fields from a block's props. */
 interface PropSchemaField {
     name: string;
     type: 'string' | 'number' | 'boolean' | 'expression' | 'enum';
@@ -11,11 +10,6 @@ interface PropSchemaField {
     default?: string | number | boolean;
     options?: string[];
 }
-/**
- * A reusable element/block in the palette. `create()` returns a fresh template
- * subtree to insert. `icon` is a name (not a component) so the registry stays
- * framework-agnostic; the UI maps the name to its own icon set.
- */
 interface Block {
     id: string;
     label: string;
@@ -33,20 +27,8 @@ declare class BlockRegistry {
     byCategory(): Record<string, Block[]>;
 }
 
-/** Where a dragged node is dropped relative to a target. */
 type DropPosition = 'before' | 'after' | 'inside';
 
-/**
- * Wire protocol for `RemoteCanvasHost` <-> `createCanvasReceiver`: a genuinely
- * navigated `/canvas/[id]`-style iframe has its own JS realm, so state and
- * interaction can't cross as direct object references the way `IframeCanvas`'s
- * portal allows — everything here is a structured-clone-safe plain message.
- *
- * Deliberately generic: only the shapes the editor primitive itself needs
- * (state sync, ready handshake, the core interaction events) are typed. Host
- * concerns like theme/preview-mode/overrides ride through `CanvasUiMessage`'s
- * opaque `payload` — this package relays it, never interprets it.
- */
 declare const CANVAS_CHANNEL = "nuforge-canvas";
 declare const CANVAS_PROTOCOL_VERSION = 1;
 interface CanvasKeydownMessage {
@@ -61,7 +43,6 @@ interface CanvasKeydownMessage {
     altKey: boolean;
 }
 
-/** A named action a UI can discover and bind to (toolbar buttons, shortcuts). */
 interface Command {
     id: string;
     label: string;
@@ -79,67 +60,37 @@ declare class CommandRegistry {
 }
 
 interface CreateEditorOptions {
-    /** Extra blocks to add to the palette. */
     blocks?: Block[];
-    /** Include the built-in DEFAULT_BLOCKS (default true). */
     defaultBlocks?: boolean;
 }
-/**
- * A high-level facade over a {@link Nu} runtime for building visual page
- * editors. Every mutation goes through `nu.change`, so it is transactional and
- * undoable. Reach for these instead of hand-splicing the AST.
- */
 declare class Editor {
     readonly nu: Nu;
     readonly blocks: BlockRegistry;
     readonly commands: CommandRegistry;
     constructor(nu: Nu, opts?: CreateEditorOptions);
-    /** Append (or insert at `index`) `child` into `parent`'s children. */
     insertNode(parent: t.Template, child: t.Template, index?: number): void;
-    /** Remove a node from its parent. Returns false if it has no parent. */
     removeNode(node: t.Template): boolean;
-    /** Move `dragged` before/after/inside `target`. Refuses to nest into self. */
     moveNode(dragged: t.Template, target: t.Template, position: DropPosition): boolean;
     private clipboardNode;
-    /** Put a node on the editor clipboard (a clone is made on paste). */
     copyNode(node: t.Template): void;
-    /** Copy a node, then remove it. */
     cutNode(node: t.Template): boolean;
-    /** Whether there is something on the clipboard to paste. */
     canPaste(): boolean;
-    /**
-     * Paste a fresh copy (new ids) of the clipboard node before/after/inside
-     * `target`. Returns the inserted node, or null if nothing was pasted.
-     */
     pasteNode(target: t.Template, position?: DropPosition): t.Template | null;
-    /** Duplicate a node in place (inserted right after it). Returns the copy. */
     duplicateNode(node: t.Template): t.Template | null;
-    /**
-     * Insert a detached node before/after/inside a target (undoable). The core of
-     * canvas drag-and-drop: a drop computes a target + position, then calls this.
-     * Returns the inserted node.
-     */
     insertNodeAt(node: t.Template, target: t.Template, position: DropPosition): t.Template | null;
-    /** Create a block and insert it before/after/inside a target. */
     insertBlockAt(blockId: string, target: t.Template, position: DropPosition): t.Template | null;
     private insertCloneRelativeTo;
-    /** Set several props at once. */
     updateProps(node: t.Template, props: Record<string, t.Expression>): void;
     setProp(node: t.Template, key: string, expr: t.Expression): void;
     removeProp(node: t.Template, key: string): void;
-    /** Parse `source` as a nuforge expression and assign it to `key`. */
     setExpression(node: t.Template, key: string, source: string): boolean;
-    /** Update a text node's literal value. */
     setText(node: t.Template, value: string): boolean;
     setTag(node: t.TagTemplate, tag: string): void;
     addClass(node: t.Template, name: string): void;
-    /** Parse `source` and set the condition under which class `name` applies. */
     setClassCondition(node: t.Template, name: string, source: string): boolean;
     removeClass(node: t.Template, name: string): void;
-    /** Set the `@if` condition from source. */
     setCondition(node: t.Template, source: string): boolean;
     clearCondition(node: t.Template): void;
-    /** Repeat a node over `iterator` (a list expression), binding each `alias`. */
     setEach(node: t.Template, iterator: string, alias?: string, indexName?: string): boolean;
     clearEach(node: t.Template): void;
     addState(component: t.NuComponent, name?: string, init?: string): t.Val;
@@ -148,12 +99,9 @@ declare class Editor {
     addComponentProp(component: t.NuComponent, name?: string, init?: string): t.ComponentProp;
     removeComponentProp(component: t.NuComponent, prop: t.ComponentProp): void;
     setComponentPropInit(prop: t.ComponentProp, source: string): boolean;
-    /** Create a block's template and insert it into `parent`. */
     insertBlock(blockId: string, parent: t.Template, index?: number): t.Template | null;
     private uniqueName;
-    /** Add a new component (a "page"). */
     addComponent(name?: string): t.NuComponent;
-    /** Rename a component, updating `<Name/>` references across the program. */
     renameComponent(component: t.NuComponent, name: string): boolean;
     removeComponent(component: t.NuComponent): boolean;
     duplicateComponent(component: t.NuComponent): t.NuComponent;
@@ -164,15 +112,11 @@ declare class Editor {
     getChildren(node: t.Template): t.Template[];
     getSiblings(node: t.Template): t.Template[];
     getNodeIndex(node: t.Template): number;
-    /** Full path from the State root to this node (for selections/serialization). */
     getNodePath(node: t.Type): Array<string | number>;
-    /** Fires with the raw field-level writes of every change (incl. undo/redo). */
     onChange(cb: (entries: MutationEntry[]) => void): () => void;
-    /** Fires only when the tree shape changes (a child array was mutated). */
     onStructureChange(cb: () => void): () => void;
     private spliceFromParent;
     private applyMove;
-    /** Insert an already-detached node relative to `target` (no removal). */
     private insertRelativeTo;
 }
 
@@ -183,76 +127,31 @@ interface Rect {
     height: number;
 }
 interface CanvasWindow {
-    /** The canvas's own document — the iframe's, inside `IframeCanvas`. */
     doc: Document | null;
-    /** The canvas's own window — the iframe's, inside `IframeCanvas`. */
     window: Window | null;
 }
-/**
- * The real `window`/`document` a canvas-rendered element visually lives in.
- * `IframeCanvas` portals its content into an `<iframe>`, but a portal only
- * relocates DOM nodes — the JS building them still runs in the host page's
- * realm. Any library that reads a bare `window`/`document` global (scroll
- * listeners, `matchMedia`, `ResizeObserver`/`IntersectionObserver` defaults)
- * silently ends up watching the HOST page, not the iframe the user actually
- * sees and scrolls. Build refs/options from `useCanvasWindow()` instead of the
- * ambient global so they resolve to the right realm — this works identically
- * outside `IframeCanvas` too (e.g. `NuFrame`'s direct, non-iframe render),
- * where it's just the ambient `window`/`document`.
- */
 declare function useCanvasWindow(): CanvasWindow;
-/** Reactive renderer for a frame, decorating each element with `data-nu-id`. */
 declare const EditorFrame: (props: {
     frame: Frame;
 }) => ReactNode;
-/** Map a DOM node (or event target) back to its template id. */
 declare function templateIdFromElement(target: EventTarget | null): string | null;
-/** Sensible default styling for the isolated canvas document. */
 declare const DEFAULT_CANVAS_CSS = "\n  *, *::before, *::after { box-sizing: border-box; }\n  html, body { margin: 0; }\n  body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; color: #111; line-height: 1.5; padding: 28px; }\n  h1 { font-size: 2rem; font-weight: 700; margin: .5em 0; }\n  h2 { font-size: 1.5rem; font-weight: 600; margin: .6em 0; }\n  h3 { font-size: 1.2rem; font-weight: 600; margin: .7em 0; }\n  p { margin: .8em 0; }\n  ul { list-style: disc; padding-left: 1.5em; margin: .8em 0; }\n  ol { list-style: decimal; padding-left: 1.5em; margin: .8em 0; }\n  a { color: #2563eb; text-decoration: underline; }\n  button { border: 1px solid #d4d4d8; border-radius: 6px; padding: 4px 12px; background: #fafafa; cursor: pointer; font: inherit; }\n  button:hover { background: #f4f4f5; }\n  input, textarea, select { border: 1px solid #d4d4d8; border-radius: 6px; padding: 4px 8px; font: inherit; }\n  section { display: flex; align-items: center; gap: .75rem; margin: .8em 0; }\n  img { max-width: 100%; }\n  [data-nu-id] { cursor: default; }\n";
 interface IframeCanvasProps {
     frame: Frame;
     selectedId?: string | null;
     hoveredId?: string | null;
-    /** Bump to force the overlay to recompute (e.g. on every committed change). */
     revision?: number;
-    /**
-     * Turn the canvas into a live, interactive preview. When `true`, the editing
-     * affordances are switched off: clicks and hovers pass through to the real
-     * elements (buttons fire, links work, inputs focus), drag-and-drop editing is
-     * disabled, and no overlay is drawn. When `false` (the default) the canvas is
-     * in edit mode — clicks select instead of activating, hover highlights, and
-     * `onDropOnNode` / `renderBox` are live. The same reactive `frame` is shown in
-     * both modes, so toggling is instant and state is preserved.
-     */
     previewMode?: boolean;
     onSelect?: (id: string | null) => void;
     onHover?: (id: string | null) => void;
-    /**
-     * Enable drop-on-canvas: fired when something is dropped onto a node. Compute
-     * a block to insert and call `editor.insertBlockAt(blockId, target, position)`.
-     */
     onDropOnNode?: (targetId: string, position: DropPosition, event: DragEvent) => void;
-    /** CSS injected into the isolated document (defaults to DEFAULT_CANVAS_CSS). */
     baseCss?: string;
-    /**
-     * Initial HTML for the iframe document — put anything in the `<head>` (CDN
-     * stylesheets, web fonts, `<script>` tags, a `<base>`, meta). The frame is
-     * portaled into its `<body>`. `baseCss` is still appended on top; pass
-     * `baseCss=""` to fully control styling from here.
-     */
     srcDoc?: string;
     className?: string;
     containerClassName?: string;
-    /**
-     * Build the overlay from the computed selection / hover / drop rects and the
-     * selected element's tag. Omit it for no overlay. The overlay container is
-     * pointer-events:none — set `pointerEvents: 'auto'` on interactive bits (e.g.
-     * an action toolbar) so they receive clicks.
-     */
     renderBox?: (rects: {
         selected: Rect | null;
         hovered: Rect | null;
-        /** Tag name of the selected element, e.g. `"div"`. */
         selectedLabel: string | null;
         drop: {
             rect: Rect;
@@ -260,41 +159,15 @@ interface IframeCanvasProps {
         } | null;
     }) => ReactNode;
 }
-/**
- * A style-isolated editor canvas: the frame is portaled into an `<iframe>` so
- * the host's CSS can't leak into the preview (and vice-versa). Selection/hover
- * use native capture listeners on the iframe document, so element handlers stay
- * inert while editing. Selection/hover rects are computed (in a layout effect,
- * after the iframe commits) and handed to `renderBox` for the overlay.
- */
 declare function IframeCanvas({ frame, selectedId, hoveredId, revision, previewMode, onSelect, onHover, onDropOnNode, baseCss, srcDoc, className, containerClassName, renderBox, }: IframeCanvasProps): ReactNode;
 interface RemoteCanvasHostProps {
-    /** The host's `Nu` instance — flattened and pushed to the canvas realm on
-     *  every committed change. Never referenced directly by the canvas realm: a
-     *  real `src` navigation puts it in a separate JS realm with no shared
-     *  object identity, unlike `IframeCanvas`'s portal. */
     nu: Nu;
-    /** Which component the canvas should render (`Nu.createFrame`'s `component.name`). */
     activeComponent: string;
-    /** The canvas route's URL, e.g. `/canvas/my-project`. The `BroadcastChannel`
-     *  name is derived from it, so `createCanvasReceiver` on the other end just
-     *  needs the SAME `src` — no separate id to keep in sync. */
     src: string;
     selectedId?: string | null;
     hoveredId?: string | null;
-    /** Bump to force the overlay to recompute (e.g. on every committed change). */
     revision?: number;
-    /**
-     * Mirrors `IframeCanvas`'s `previewMode`: when `true`, the canvas is a live,
-     * interactive preview (its own DSL `onClick` handlers run against the
-     * canvas's local `Nu`, since that instance is genuinely loaded and mutable —
-     * see `createCanvasReceiver`'s docs). Toggling this (either direction) forces
-     * a fresh `init` instead of an incremental `patch`, so any preview-only
-     * local mutation never lingers once you're back in edit mode.
-     */
     previewMode?: boolean;
-    /** Opaque host-defined payload (theme CSS, hide/lock overrides, ...) pushed
-     *  to the canvas via a `ui` message whenever this reference changes. */
     uiPayload?: unknown;
     onSelect?: (id: string | null) => void;
     onHover?: (id: string | null) => void;
@@ -303,59 +176,22 @@ interface RemoteCanvasHostProps {
     onLinkClick?: (href: string) => void;
     className?: string;
     containerClassName?: string;
-    /**
-     * Build the overlay from the computed selection / hover rects and the
-     * selected element's tag — same contract as `IframeCanvas`'s `renderBox`
-     * (no `drop` rect: the canvas realm renders its own drop indicator locally,
-     * since it already has the DOM geometry and relaying it every `dragover`
-     * tick would add a message-per-frame the local realm doesn't need). Reading
-     * these rects is a same-origin DOM read (`iframe.contentDocument`), which a
-     * real `src` navigation doesn't block — only shared JS object identity is
-     * blocked, not DOM geometry reads.
-     */
     renderBox?: (rects: {
         selected: Rect | null;
         hovered: Rect | null;
         selectedLabel: string | null;
     }) => ReactNode;
 }
-/**
- * The `IframeCanvas` alternative for when a canvas needs its OWN genuine JS
- * realm — e.g. so a third-party library reading bare `window`/`document` at
- * module scope (an animation library's scroll-linked internals, a gesture
- * library, ...) resolves against the canvas's real globals instead of
- * silently binding to the host page's. A portal can't fix this (see
- * `useCanvasWindow`'s docs for that half of the problem) because it only
- * relocates DOM nodes, not the JS module graph building them.
- *
- * Renders a genuinely-`src`-navigated `<iframe>` — no `createPortal`, so
- * nothing here shares object identity with the canvas's own React tree. State
- * flows one-way, host -> canvas, over a `BroadcastChannel` as `t.flatten`'d
- * JSON (see `./canvas-protocol`); interaction (select/hover/drop/keydown/
- * link-click) relays back the other way as small typed messages. Pair with
- * `createCanvasReceiver` (`./canvas-client`) on the canvas route's own end.
- */
 declare function RemoteCanvasHost({ nu, activeComponent, src, selectedId, hoveredId, revision, previewMode, uiPayload, onSelect, onHover, onDropOnNode, onKeydownRelay, onLinkClick, className, containerClassName, renderBox, }: RemoteCanvasHostProps): ReactNode;
-/** Re-render only when the tree shape changes (add/remove/move). */
 declare function useStructureRevision(editor: Pick<Editor, 'onStructureChange'>): number;
-/** Re-render on every committed change (for undo state, inspectors, …). */
 declare function useEditorRevision(editor: Pick<Editor, 'onChange'>): number;
 type PropFieldValue = string | number | boolean | undefined;
 interface PropFieldsProps {
-    /** The control schema (e.g. a block's `props`). */
     fields: PropSchemaField[];
-    /** Current value per field name. */
     values: Record<string, PropFieldValue>;
-    /** Called when a control changes. Wire to `editor.setProp`/`setExpression`. */
     onChange: (name: string, value: string | number | boolean) => void;
     className?: string;
 }
-/**
- * A headless inspector renderer: builds a control per {@link PropSchemaField}
- * (text / number / checkbox / select / expression) so you don't hand-write a
- * form per block. Style via `className` and your own CSS; wire `onChange` to the
- * editor's mutation methods.
- */
 declare function PropFields({ fields, values, onChange, className, }: PropFieldsProps): ReactNode;
 
 export { DEFAULT_CANVAS_CSS, EditorFrame, IframeCanvas, PropFields, RemoteCanvasHost, templateIdFromElement, useCanvasWindow, useEditorRevision, useStructureRevision };