@elytracms/studio 0.0.63 → 0.0.65

package/dist/components/builder/delete-key.js

@@ -0,0 +1,46 @@
+import { clipboardEventBlocked } from './clipboard-actions.js';
+/**
+ * Delete/Backspace removes the selected node (EC-404, scope 3) — the gap the
+ * findings batch surfaced: the studio had no keyboard remove at all except cut
+ * (⌘X). This sits beside the clipboard listeners (`attachClipboardListeners`),
+ * wired on the same two surfaces (the studio window for the page tree, the
+ * iframe document for the canvas), and reuses the SAME editing-context guard so
+ * pressing Backspace while typing in an input or an inline text/rich-text editor
+ * edits the text — never deletes the block.
+ */
+/**
+ * True when a key event's target owns its own text-editing behavior — a form
+ * field or any contenteditable (which includes the EC-158/EC-159 inline
+ * editors). The single guard for the Delete/Backspace remove, kept identical to
+ * the clipboard shortcuts' scope so the two can never disagree.
+ */
+export function isEditingContext(target) {
+    return clipboardEventBlocked(target);
+}
+/**
+ * Wire Delete/Backspace → remove the selected node. Inert when the event
+ * targets an editing context, when nothing (or the root) is selected, or when
+ * disabled. Modifier combinations are ignored so it never shadows a browser
+ * shortcut (⌘Delete etc.).
+ */
+export function attachDeleteKeyListener(target, opts) {
+    const onKeyDown = (e) => {
+        const event = e;
+        if (event.key !== 'Delete' && event.key !== 'Backspace')
+            return;
+        if (event.metaKey || event.ctrlKey || event.altKey)
+            return;
+        if (opts.isDisabled?.() ?? false)
+            return;
+        if (isEditingContext(event.target))
+            return;
+        const selectedId = opts.getSelectedId();
+        if (!selectedId || selectedId === opts.getRootId())
+            return;
+        event.preventDefault();
+        opts.remove(selectedId);
+    };
+    target.addEventListener('keydown', onKeyDown);
+    return () => target.removeEventListener('keydown', onKeyDown);
+}
+//# sourceMappingURL=delete-key.js.map

package/dist/components/builder/delete-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete-key.js","sourceRoot":"","sources":["../../../src/components/builder/delete-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAE3D;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA0B;IACzD,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAA;AACtC,CAAC;AAkBD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAsB,EACtB,IAA8B;IAE9B,MAAM,SAAS,GAAG,CAAC,CAAQ,EAAQ,EAAE;QACnC,MAAM,KAAK,GAAG,CAAkB,CAAA;QAChC,IAAI,KAAK,CAAC,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,KAAK,WAAW;YAAE,OAAM;QAC/D,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM;YAAE,OAAM;QAC1D,IAAI,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,KAAK;YAAE,OAAM;QACxC,IAAI,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,OAAM;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAA;QACvC,IAAI,CAAC,UAAU,IAAI,UAAU,KAAK,IAAI,CAAC,SAAS,EAAE;YAAE,OAAM;QAC1D,KAAK,CAAC,cAAc,EAAE,CAAA;QACtB,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IACzB,CAAC,CAAA;IACD,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;IAC7C,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;AAC/D,CAAC","sourcesContent":["import { clipboardEventBlocked } from './clipboard-actions'\n\n/**\n * Delete/Backspace removes the selected node (EC-404, scope 3) — the gap the\n * findings batch surfaced: the studio had no keyboard remove at all except cut\n * (⌘X). This sits beside the clipboard listeners (`attachClipboardListeners`),\n * wired on the same two surfaces (the studio window for the page tree, the\n * iframe document for the canvas), and reuses the SAME editing-context guard so\n * pressing Backspace while typing in an input or an inline text/rich-text editor\n * edits the text — never deletes the block.\n */\n\n/**\n * True when a key event's target owns its own text-editing behavior — a form\n * field or any contenteditable (which includes the EC-158/EC-159 inline\n * editors). The single guard for the Delete/Backspace remove, kept identical to\n * the clipboard shortcuts' scope so the two can never disagree.\n */\nexport function isEditingContext(target: EventTarget | null): boolean {\n  return clipboardEventBlocked(target)\n}\n\nexport interface DeleteKeyListenerOptions {\n  /** The current selection — the remove subject. */\n  getSelectedId: () => string | null\n  /** Dispatch the remove (the existing `remove` tree action; one undo restores). */\n  remove: (id: string) => void\n  /** The id that must never be removed (the composition root). */\n  getRootId: () => string | null\n  /** Extra suppression (e.g. a read-only published preview). */\n  isDisabled?: () => boolean\n}\n\ninterface ListenerTarget {\n  addEventListener(type: string, listener: (e: Event) => void): void\n  removeEventListener(type: string, listener: (e: Event) => void): void\n}\n\n/**\n * Wire Delete/Backspace → remove the selected node. Inert when the event\n * targets an editing context, when nothing (or the root) is selected, or when\n * disabled. Modifier combinations are ignored so it never shadows a browser\n * shortcut (⌘Delete etc.).\n */\nexport function attachDeleteKeyListener(\n  target: ListenerTarget,\n  opts: DeleteKeyListenerOptions,\n): () => void {\n  const onKeyDown = (e: Event): void => {\n    const event = e as KeyboardEvent\n    if (event.key !== 'Delete' && event.key !== 'Backspace') return\n    if (event.metaKey || event.ctrlKey || event.altKey) return\n    if (opts.isDisabled?.() ?? false) return\n    if (isEditingContext(event.target)) return\n    const selectedId = opts.getSelectedId()\n    if (!selectedId || selectedId === opts.getRootId()) return\n    event.preventDefault()\n    opts.remove(selectedId)\n  }\n  target.addEventListener('keydown', onKeyDown)\n  return () => target.removeEventListener('keydown', onKeyDown)\n}\n"]}

package/dist/components/builder/drag-session.d.ts

@@ -26,6 +26,7 @@ export interface DragSession {
     buildNode?: () => ComponentNode;
 }
 type EndListener = (outcome: DragOutcome, session: DragSession) => void;
+type StartListener = (session: DragSession) => void;
 /** Begin a drag session and stamp the dataTransfer (Firefox requires data to drag). */
 export declare function beginDrag(session: DragSession, dataTransfer: DataTransfer | null): void;
 /** The live session, or null when nothing Elytra-owned is being dragged. */
@@ -38,4 +39,11 @@ export declare function activeDrag(): DragSession | null;
 export declare function endDrag(outcome: DragOutcome): void;
 /** Subscribe to session end (indicator cleanup, blocks-panel close-on-drop). */
 export declare function onDragSessionEnd(listener: EndListener): () => void;
+/**
+ * Subscribe to session start — fired for EVERY drag source (canvas node, tree
+ * row, blocks-panel tile). The canvas insertion affordances (EC-405) use this to
+ * hide while a drag is live: the DnD before/after/into indicators own the "where
+ * it lands" story during a drag, so a competing "+" would be noise.
+ */
+export declare function onDragSessionStart(listener: StartListener): () => void;
 export {};

package/dist/components/builder/drag-session.js

@@ -15,6 +15,7 @@
 export const ELYTRA_DND_MIME = 'application/x-elytra-canvas';
 let active = null;
 const endListeners = new Set();
+const startListeners = new Set();
 /** Begin a drag session and stamp the dataTransfer (Firefox requires data to drag). */
 export function beginDrag(session, dataTransfer) {
     active = session;
@@ -23,6 +24,8 @@ export function beginDrag(session, dataTransfer) {
         dataTransfer.setData('text/plain', session.label);
         dataTransfer.effectAllowed = session.subject.kind === 'node' ? 'move' : 'copy';
     }
+    for (const listener of [...startListeners])
+        listener(session);
 }
 /** The live session, or null when nothing Elytra-owned is being dragged. */
 export function activeDrag() {
@@ -48,4 +51,16 @@ export function onDragSessionEnd(listener) {
         endListeners.delete(listener);
     };
 }
+/**
+ * Subscribe to session start — fired for EVERY drag source (canvas node, tree
+ * row, blocks-panel tile). The canvas insertion affordances (EC-405) use this to
+ * hide while a drag is live: the DnD before/after/into indicators own the "where
+ * it lands" story during a drag, so a competing "+" would be noise.
+ */
+export function onDragSessionStart(listener) {
+    startListeners.add(listener);
+    return () => {
+        startListeners.delete(listener);
+    };
+}
 //# sourceMappingURL=drag-session.js.map

package/dist/components/builder/drag-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"drag-session.js","sourceRoot":"","sources":["../../../src/components/builder/drag-session.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,eAAe,GAAG,6BAA6B,CAAA;AAgB5D,IAAI,MAAM,GAAuB,IAAI,CAAA;AACrC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAe,CAAA;AAE3C,uFAAuF;AACvF,MAAM,UAAU,SAAS,CAAC,OAAoB,EAAE,YAAiC;IAC/E,MAAM,GAAG,OAAO,CAAA;IAChB,IAAI,YAAY,EAAE,CAAC;QACjB,YAAY,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QACpD,YAAY,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QACjD,YAAY,CAAC,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAA;IAChF,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU;IACxB,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,OAAoB;IAC1C,IAAI,CAAC,MAAM;QAAE,OAAM;IACnB,MAAM,OAAO,GAAG,MAAM,CAAA;IACtB,MAAM,GAAG,IAAI,CAAA;IACb,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,YAAY,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AACtE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,QAAqB;IACpD,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAC1B,OAAO,GAAG,EAAE;QACV,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC/B,CAAC,CAAA;AACH,CAAC","sourcesContent":["import type { ComponentNode } from '@elytracms/core/project-graph'\nimport type { DragSubject } from '@elytracms/studio/lib/dnd/drop-rules'\n\n/**\n * The one live drag session (EC-160). HTML5 `dataTransfer` payloads are\n * unreadable during `dragover`, so the canvas, page tree, and blocks panel\n * share this module-level session instead: the source begins it, every\n * surface reads it to resolve drop eligibility (via the pure rules in\n * `lib/dnd/drop-rules`), and exactly one place ends it — the drop handler\n * (`dropped`) or the source's `dragend` (`cancelled`). `endDrag` is\n * idempotent, so the source's trailing `dragend` after a successful drop\n * cannot double-commit or double-notify.\n *\n * The iframe canvas shares the parent window's JS realm (listeners are wired\n * from the parent), so one module instance covers all surfaces.\n */\n\n/** Custom MIME marking Elytra drags (lets surfaces ignore foreign drags). */\nexport const ELYTRA_DND_MIME = 'application/x-elytra-canvas'\n\nexport type DragSource = 'canvas' | 'tree' | 'blocks'\nexport type DragOutcome = 'dropped' | 'cancelled'\n\nexport interface DragSession {\n  subject: DragSubject\n  source: DragSource\n  /** Human label (drag text fallback). */\n  label: string\n  /** For `component` subjects: builds the subtree to insert (ids reassigned by the store). */\n  buildNode?: () => ComponentNode\n}\n\ntype EndListener = (outcome: DragOutcome, session: DragSession) => void\n\nlet active: DragSession | null = null\nconst endListeners = new Set<EndListener>()\n\n/** Begin a drag session and stamp the dataTransfer (Firefox requires data to drag). */\nexport function beginDrag(session: DragSession, dataTransfer: DataTransfer | null): void {\n  active = session\n  if (dataTransfer) {\n    dataTransfer.setData(ELYTRA_DND_MIME, session.label)\n    dataTransfer.setData('text/plain', session.label)\n    dataTransfer.effectAllowed = session.subject.kind === 'node' ? 'move' : 'copy'\n  }\n}\n\n/** The live session, or null when nothing Elytra-owned is being dragged. */\nexport function activeDrag(): DragSession | null {\n  return active\n}\n\n/**\n * End the live session (no-op when none is active) and notify subscribers.\n * Call with `dropped` from the drop handler that dispatched the action, and\n * with `cancelled` from the source's `dragend`.\n */\nexport function endDrag(outcome: DragOutcome): void {\n  if (!active) return\n  const session = active\n  active = null\n  for (const listener of [...endListeners]) listener(outcome, session)\n}\n\n/** Subscribe to session end (indicator cleanup, blocks-panel close-on-drop). */\nexport function onDragSessionEnd(listener: EndListener): () => void {\n  endListeners.add(listener)\n  return () => {\n    endListeners.delete(listener)\n  }\n}\n"]}
+{"version":3,"file":"drag-session.js","sourceRoot":"","sources":["../../../src/components/builder/drag-session.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,eAAe,GAAG,6BAA6B,CAAA;AAiB5D,IAAI,MAAM,GAAuB,IAAI,CAAA;AACrC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAe,CAAA;AAC3C,MAAM,cAAc,GAAG,IAAI,GAAG,EAAiB,CAAA;AAE/C,uFAAuF;AACvF,MAAM,UAAU,SAAS,CAAC,OAAoB,EAAE,YAAiC;IAC/E,MAAM,GAAG,OAAO,CAAA;IAChB,IAAI,YAAY,EAAE,CAAC;QACjB,YAAY,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QACpD,YAAY,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QACjD,YAAY,CAAC,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAA;IAChF,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,cAAc,CAAC;QAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;AAC/D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU;IACxB,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,OAAoB;IAC1C,IAAI,CAAC,MAAM;QAAE,OAAM;IACnB,MAAM,OAAO,GAAG,MAAM,CAAA;IACtB,MAAM,GAAG,IAAI,CAAA;IACb,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,YAAY,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AACtE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,QAAqB;IACpD,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAC1B,OAAO,GAAG,EAAE;QACV,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC/B,CAAC,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAuB;IACxD,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAC5B,OAAO,GAAG,EAAE;QACV,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IACjC,CAAC,CAAA;AACH,CAAC","sourcesContent":["import type { ComponentNode } from '@elytracms/core/project-graph'\nimport type { DragSubject } from '@elytracms/studio/lib/dnd/drop-rules'\n\n/**\n * The one live drag session (EC-160). HTML5 `dataTransfer` payloads are\n * unreadable during `dragover`, so the canvas, page tree, and blocks panel\n * share this module-level session instead: the source begins it, every\n * surface reads it to resolve drop eligibility (via the pure rules in\n * `lib/dnd/drop-rules`), and exactly one place ends it — the drop handler\n * (`dropped`) or the source's `dragend` (`cancelled`). `endDrag` is\n * idempotent, so the source's trailing `dragend` after a successful drop\n * cannot double-commit or double-notify.\n *\n * The iframe canvas shares the parent window's JS realm (listeners are wired\n * from the parent), so one module instance covers all surfaces.\n */\n\n/** Custom MIME marking Elytra drags (lets surfaces ignore foreign drags). */\nexport const ELYTRA_DND_MIME = 'application/x-elytra-canvas'\n\nexport type DragSource = 'canvas' | 'tree' | 'blocks'\nexport type DragOutcome = 'dropped' | 'cancelled'\n\nexport interface DragSession {\n  subject: DragSubject\n  source: DragSource\n  /** Human label (drag text fallback). */\n  label: string\n  /** For `component` subjects: builds the subtree to insert (ids reassigned by the store). */\n  buildNode?: () => ComponentNode\n}\n\ntype EndListener = (outcome: DragOutcome, session: DragSession) => void\ntype StartListener = (session: DragSession) => void\n\nlet active: DragSession | null = null\nconst endListeners = new Set<EndListener>()\nconst startListeners = new Set<StartListener>()\n\n/** Begin a drag session and stamp the dataTransfer (Firefox requires data to drag). */\nexport function beginDrag(session: DragSession, dataTransfer: DataTransfer | null): void {\n  active = session\n  if (dataTransfer) {\n    dataTransfer.setData(ELYTRA_DND_MIME, session.label)\n    dataTransfer.setData('text/plain', session.label)\n    dataTransfer.effectAllowed = session.subject.kind === 'node' ? 'move' : 'copy'\n  }\n  for (const listener of [...startListeners]) listener(session)\n}\n\n/** The live session, or null when nothing Elytra-owned is being dragged. */\nexport function activeDrag(): DragSession | null {\n  return active\n}\n\n/**\n * End the live session (no-op when none is active) and notify subscribers.\n * Call with `dropped` from the drop handler that dispatched the action, and\n * with `cancelled` from the source's `dragend`.\n */\nexport function endDrag(outcome: DragOutcome): void {\n  if (!active) return\n  const session = active\n  active = null\n  for (const listener of [...endListeners]) listener(outcome, session)\n}\n\n/** Subscribe to session end (indicator cleanup, blocks-panel close-on-drop). */\nexport function onDragSessionEnd(listener: EndListener): () => void {\n  endListeners.add(listener)\n  return () => {\n    endListeners.delete(listener)\n  }\n}\n\n/**\n * Subscribe to session start — fired for EVERY drag source (canvas node, tree\n * row, blocks-panel tile). The canvas insertion affordances (EC-405) use this to\n * hide while a drag is live: the DnD before/after/into indicators own the \"where\n * it lands\" story during a drag, so a competing \"+\" would be noise.\n */\nexport function onDragSessionStart(listener: StartListener): () => void {\n  startListeners.add(listener)\n  return () => {\n    startListeners.delete(listener)\n  }\n}\n"]}

package/dist/components/builder/insert-affordance-context.d.ts

@@ -0,0 +1,19 @@
+import type { InsertPosition } from './insert-context.js';
+/**
+ * Bridges the in-canvas insertion affordances (EC-405) to the insert panel state
+ * that lives on the composition-field editor. The `SelectionOverlay` (portaled
+ * inside the canvas iframe) asks this context which positions are insertable for a
+ * node and opens the panel at a chosen one; the editor owns the panel's
+ * `open`/`context` state and the field-level `allow` leash. A separate module (not
+ * the editor) so the deep overlay can consume it without a canvas ↔ editor import
+ * cycle, and so any canvas mount WITHOUT an editor above it (component preview)
+ * simply reads `null` and shows no affordances — the `ReuseProvider` pattern.
+ */
+export interface InsertAffordanceApi {
+    /** The affordance positions (before/after/into) that may actually be inserted at `nodeId`. */
+    positionsFor(nodeId: string): InsertPosition[];
+    /** Select `nodeId` and open the blocks panel targeted at that exact position. */
+    openAt(nodeId: string, position: InsertPosition): void;
+}
+export declare const InsertAffordanceProvider: import("react").Provider<InsertAffordanceApi | null>;
+export declare function useInsertAffordance(): InsertAffordanceApi | null;

package/dist/components/builder/insert-affordance-context.js

@@ -0,0 +1,7 @@
+import { createContext, useContext } from 'react';
+const InsertAffordanceContext = createContext(null);
+export const InsertAffordanceProvider = InsertAffordanceContext.Provider;
+export function useInsertAffordance() {
+    return useContext(InsertAffordanceContext);
+}
+//# sourceMappingURL=insert-affordance-context.js.map

package/dist/components/builder/insert-affordance-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-affordance-context.js","sourceRoot":"","sources":["../../../src/components/builder/insert-affordance-context.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAoBjD,MAAM,uBAAuB,GAAG,aAAa,CAA6B,IAAI,CAAC,CAAA;AAE/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,uBAAuB,CAAC,QAAQ,CAAA;AAExE,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,CAAC,uBAAuB,CAAC,CAAA;AAC5C,CAAC","sourcesContent":["import { createContext, useContext } from 'react'\nimport type { InsertPosition } from './insert-context'\n\n/**\n * Bridges the in-canvas insertion affordances (EC-405) to the insert panel state\n * that lives on the composition-field editor. The `SelectionOverlay` (portaled\n * inside the canvas iframe) asks this context which positions are insertable for a\n * node and opens the panel at a chosen one; the editor owns the panel's\n * `open`/`context` state and the field-level `allow` leash. A separate module (not\n * the editor) so the deep overlay can consume it without a canvas ↔ editor import\n * cycle, and so any canvas mount WITHOUT an editor above it (component preview)\n * simply reads `null` and shows no affordances — the `ReuseProvider` pattern.\n */\nexport interface InsertAffordanceApi {\n  /** The affordance positions (before/after/into) that may actually be inserted at `nodeId`. */\n  positionsFor(nodeId: string): InsertPosition[]\n  /** Select `nodeId` and open the blocks panel targeted at that exact position. */\n  openAt(nodeId: string, position: InsertPosition): void\n}\n\nconst InsertAffordanceContext = createContext<InsertAffordanceApi | null>(null)\n\nexport const InsertAffordanceProvider = InsertAffordanceContext.Provider\n\nexport function useInsertAffordance(): InsertAffordanceApi | null {\n  return useContext(InsertAffordanceContext)\n}\n"]}

package/dist/components/builder/insert-context.d.ts

@@ -23,3 +23,43 @@ import type { InsertContext } from './insert-menu.js';
 export declare function resolveInsertContext(builder: {
     present: ComponentNode;
 }, nodeId: string, fieldAllow?: readonly string[], studio?: StudioRegistry): InsertContext | null;
+/**
+ * An in-canvas insertion position relative to a reference node (EC-405) — the
+ * DnD position vocabulary (`lib/dnd/drop-rules`), narrowed to the three the
+ * insertion affordances offer: `before`/`after` a sibling, or `into` an (empty)
+ * container. `left`/`right` (the wrap-into-columns gesture) are DnD-only.
+ */
+export type InsertPosition = 'before' | 'after' | 'into';
+/**
+ * Resolve an `InsertContext` for an EXPLICIT position relative to `nodeId`
+ * (EC-405) — the position-carrying twin of {@link resolveInsertContext}, so an
+ * affordance click at a chosen edge lands the insert at exactly that spot rather
+ * than the panel re-deriving it from the selection.
+ *
+ * The slot resolution reuses the shared DnD rules — `into` uses
+ * {@link primaryInsertSlot} (the same slot a drop `into` picks; `null` when the
+ * node accepts no children), `before`/`after` use the reference's parent slot at
+ * `index`/`index + 1` — so this surface and drag-insert can never disagree about
+ * where a position lands or what it allows. `fieldAllow` (EC-188) still constrains
+ * ONLY a direct child of the composition root, mirroring `resolveInsertContext`.
+ */
+export declare function resolveInsertContextAt(builder: {
+    present: ComponentNode;
+}, nodeId: string, position: InsertPosition, fieldAllow?: readonly string[], studio?: StudioRegistry): InsertContext | null;
+/**
+ * Which affordance positions are actually insertable at `nodeId` (EC-405 scope 3):
+ * a position is offered only when it structurally exists AND at least one registry
+ * component may land there (the SAME slot-rule filter the tree/DnD and the blocks
+ * panel apply — {@link hasInsertableComponent} over the resolved `slotAllow`), so a
+ * blocked spot shows no dead button.
+ *
+ * An EMPTY, insertable container surfaces ONLY `into` — the meaningful action there
+ * is "add the first child", and an empty container often renders zero-height, so
+ * its own before/after edges are degenerate and would pile the three "+" buttons
+ * onto one point. A filled container and every leaf get before/after instead (each
+ * child already carries its own edge affordances, so a filled container needs no
+ * center "+").
+ */
+export declare function insertablePositions(builder: {
+    present: ComponentNode;
+}, nodeId: string, fieldAllow?: readonly string[], studio?: StudioRegistry): InsertPosition[];

package/dist/components/builder/insert-context.js

@@ -1,7 +1,8 @@
 import { getNode, getParentInfo } from '@elytracms/core/project-graph';
 import { getStudioRegistry } from '@elytracms/studio/lib/registry';
 import { shortId } from '@elytracms/studio/lib/persona/labels';
-import { intersectAllow } from './blocks-model.js';
+import { primaryInsertSlot } from '@elytracms/studio/lib/dnd/drop-rules';
+import { hasInsertableComponent, intersectAllow } from './blocks-model.js';
 /**
  * Where an insert lands: the canvas insert-context resolution, shared by every
  * surface that mounts the canvas engine.
@@ -27,8 +28,7 @@ export function resolveInsertContext(builder, nodeId, fieldAllow, studio = getSt
     if (!node)
         return null;
     const manifest = studio.registry.getManifest(node.componentId);
-    const childSlot = manifest?.slots.find((s) => s.name === 'children') ??
-        manifest?.slots.find((s) => s.name !== 'outlet');
+    const childSlot = manifest?.slots.find((s) => s.name === 'children') ?? manifest?.slots.find((s) => s.name !== 'outlet');
     const ctx = childSlot
         ? {
             target: { parentId: nodeId, slot: childSlot.name },
@@ -58,4 +58,87 @@ function resolveSiblingContext(studio, root, nodeId) {
     }
     return { target: { parentId: nodeId, slot: 'children' }, destinationLabel: 'root' };
 }
+/**
+ * Resolve an `InsertContext` for an EXPLICIT position relative to `nodeId`
+ * (EC-405) — the position-carrying twin of {@link resolveInsertContext}, so an
+ * affordance click at a chosen edge lands the insert at exactly that spot rather
+ * than the panel re-deriving it from the selection.
+ *
+ * The slot resolution reuses the shared DnD rules — `into` uses
+ * {@link primaryInsertSlot} (the same slot a drop `into` picks; `null` when the
+ * node accepts no children), `before`/`after` use the reference's parent slot at
+ * `index`/`index + 1` — so this surface and drag-insert can never disagree about
+ * where a position lands or what it allows. `fieldAllow` (EC-188) still constrains
+ * ONLY a direct child of the composition root, mirroring `resolveInsertContext`.
+ */
+export function resolveInsertContextAt(builder, nodeId, position, fieldAllow, studio = getStudioRegistry()) {
+    const root = builder.present;
+    const node = getNode(root, nodeId);
+    if (!node)
+        return null;
+    let ctx;
+    if (position === 'into') {
+        const manifest = studio.registry.getManifest(node.componentId);
+        const slot = primaryInsertSlot(manifest);
+        if (!slot)
+            return null; // the node accepts no children — no `into` position
+        ctx = {
+            target: {
+                parentId: nodeId,
+                slot: slot.name,
+                index: (node.slots?.[slot.name] ?? []).length,
+            },
+            slotAllow: slot.allow,
+            destinationLabel: `${shortId(node.componentId)} · ${slot.name}`,
+        };
+    }
+    else {
+        const info = getParentInfo(root, nodeId);
+        if (!info)
+            return null; // the root has no siblings — no before/after position
+        const pManifest = studio.registry.getManifest(info.parent.componentId);
+        ctx = {
+            target: {
+                parentId: info.parent.id,
+                slot: info.slot,
+                index: info.index + (position === 'after' ? 1 : 0),
+            },
+            slotAllow: pManifest?.slots.find((s) => s.name === info.slot)?.allow,
+            destinationLabel: `${shortId(info.parent.componentId)} · ${info.slot}`,
+        };
+    }
+    if (fieldAllow && fieldAllow.length > 0 && ctx.target.parentId === root.id) {
+        return { ...ctx, slotAllow: intersectAllow(ctx.slotAllow, fieldAllow) };
+    }
+    return ctx;
+}
+/**
+ * Which affordance positions are actually insertable at `nodeId` (EC-405 scope 3):
+ * a position is offered only when it structurally exists AND at least one registry
+ * component may land there (the SAME slot-rule filter the tree/DnD and the blocks
+ * panel apply — {@link hasInsertableComponent} over the resolved `slotAllow`), so a
+ * blocked spot shows no dead button.
+ *
+ * An EMPTY, insertable container surfaces ONLY `into` — the meaningful action there
+ * is "add the first child", and an empty container often renders zero-height, so
+ * its own before/after edges are degenerate and would pile the three "+" buttons
+ * onto one point. A filled container and every leaf get before/after instead (each
+ * child already carries its own edge affordances, so a filled container needs no
+ * center "+").
+ */
+export function insertablePositions(builder, nodeId, fieldAllow, studio = getStudioRegistry()) {
+    // Empty insertable container → into only.
+    const into = resolveInsertContextAt(builder, nodeId, 'into', fieldAllow, studio);
+    if (into && (into.target.index ?? 0) === 0 && hasInsertableComponent(studio, into.slotAllow)) {
+        return ['into'];
+    }
+    // Otherwise the sibling edges that accept something.
+    const out = [];
+    for (const position of ['before', 'after']) {
+        const ctx = resolveInsertContextAt(builder, nodeId, position, fieldAllow, studio);
+        if (ctx && hasInsertableComponent(studio, ctx.slotAllow))
+            out.push(position);
+    }
+    return out;
+}
 //# sourceMappingURL=insert-context.js.map

package/dist/components/builder/insert-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"insert-context.js","sourceRoot":"","sources":["../../../src/components/builder/insert-context.ts"],"names":[],"mappings":"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","sourcesContent":["import { getNode, getParentInfo } from '@elytracms/core/project-graph'\nimport type { ComponentNode } from '@elytracms/core/project-graph'\nimport { getStudioRegistry } from '@elytracms/studio/lib/registry'\nimport type { StudioRegistry } from '@elytracms/studio/lib/registry'\nimport { shortId } from '@elytracms/studio/lib/persona/labels'\nimport { intersectAllow } from './blocks-model'\nimport type { InsertContext } from './insert-menu'\n\n/**\n * Where an insert lands: the canvas insert-context resolution, shared by every\n * surface that mounts the canvas engine.\n *\n * Extracted from the retired standalone `BuilderShell` (EC-210) so the in-CMS\n * Canvas editor (`composition-field-editor.tsx`, EC-188/AD-12) can own it without\n * importing the dead shell. No UI here — pure graph/registry resolution.\n */\n\n/**\n * Resolve where an insert lands: into the node's child slot, else as a sibling.\n *\n * `fieldAllow` (EC-188) is the composition field's TOP-LEVEL vocabulary\n * (`field.allow`). It constrains ONLY inserts that land as a direct child of the\n * active page root — the top level of a composition field value — where it is\n * intersected into `slotAllow` so forbidden components are never even offered,\n * mirroring the top-level leash in `validateCompositionValue`. Deeper inserts keep\n * following each component's own slot `allow`. Callers that omit `fieldAllow` get\n * an unconstrained top level.\n */\nexport function resolveInsertContext(\n  builder: { present: ComponentNode },\n  nodeId: string,\n  fieldAllow?: readonly string[],\n  studio: StudioRegistry = getStudioRegistry(),\n): InsertContext | null {\n  const root = builder.present\n  const node = getNode(root, nodeId)\n  if (!node) return null\n  const manifest = studio.registry.getManifest(node.componentId)\n  const childSlot =\n    manifest?.slots.find((s) => s.name === 'children') ??\n    manifest?.slots.find((s) => s.name !== 'outlet')\n  const ctx: InsertContext = childSlot\n    ? {\n        target: { parentId: nodeId, slot: childSlot.name },\n        slotAllow: manifest!.slots.find((s) => s.name === childSlot.name)?.allow,\n        destinationLabel: `${shortId(node.componentId)} · ${childSlot.name}`,\n      }\n    : resolveSiblingContext(studio, root, nodeId)\n\n  // The field vocabulary governs only the top level (a direct child of the page\n  // root). `length > 0` matches the validator, which treats an empty allow as\n  // \"allow any\" (validate.ts).\n  if (fieldAllow && fieldAllow.length > 0 && ctx.target.parentId === root.id) {\n    return { ...ctx, slotAllow: intersectAllow(ctx.slotAllow, fieldAllow) }\n  }\n  return ctx\n}\n\n/** Sibling-or-root insert context for a node with no insertable child slot. */\nfunction resolveSiblingContext(\n  studio: StudioRegistry,\n  root: ComponentNode,\n  nodeId: string,\n): InsertContext {\n  const info = getParentInfo(root, nodeId)\n  if (info) {\n    const pManifest = studio.registry.getManifest(info.parent.componentId)\n    const allow = pManifest?.slots.find((s) => s.name === info.slot)?.allow\n    return {\n      target: { parentId: info.parent.id, slot: info.slot, index: info.index + 1 },\n      slotAllow: allow,\n      destinationLabel: `${shortId(info.parent.componentId)} · ${info.slot}`,\n    }\n  }\n  return { target: { parentId: nodeId, slot: 'children' }, destinationLabel: 'root' }\n}\n"]}
+{"version":3,"file":"insert-context.js","sourceRoot":"","sources":["../../../src/components/builder/insert-context.ts"],"names":[],"mappings":"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","sourcesContent":["import { getNode, getParentInfo } from '@elytracms/core/project-graph'\nimport type { ComponentNode } from '@elytracms/core/project-graph'\nimport { getStudioRegistry } from '@elytracms/studio/lib/registry'\nimport type { StudioRegistry } from '@elytracms/studio/lib/registry'\nimport { shortId } from '@elytracms/studio/lib/persona/labels'\nimport { primaryInsertSlot } from '@elytracms/studio/lib/dnd/drop-rules'\nimport { hasInsertableComponent, intersectAllow } from './blocks-model'\nimport type { InsertContext } from './insert-menu'\n\n/**\n * Where an insert lands: the canvas insert-context resolution, shared by every\n * surface that mounts the canvas engine.\n *\n * Extracted from the retired standalone `BuilderShell` (EC-210) so the in-CMS\n * Canvas editor (`composition-field-editor.tsx`, EC-188/AD-12) can own it without\n * importing the dead shell. No UI here — pure graph/registry resolution.\n */\n\n/**\n * Resolve where an insert lands: into the node's child slot, else as a sibling.\n *\n * `fieldAllow` (EC-188) is the composition field's TOP-LEVEL vocabulary\n * (`field.allow`). It constrains ONLY inserts that land as a direct child of the\n * active page root — the top level of a composition field value — where it is\n * intersected into `slotAllow` so forbidden components are never even offered,\n * mirroring the top-level leash in `validateCompositionValue`. Deeper inserts keep\n * following each component's own slot `allow`. Callers that omit `fieldAllow` get\n * an unconstrained top level.\n */\nexport function resolveInsertContext(\n  builder: { present: ComponentNode },\n  nodeId: string,\n  fieldAllow?: readonly string[],\n  studio: StudioRegistry = getStudioRegistry(),\n): InsertContext | null {\n  const root = builder.present\n  const node = getNode(root, nodeId)\n  if (!node) return null\n  const manifest = studio.registry.getManifest(node.componentId)\n  const childSlot =\n    manifest?.slots.find((s) => s.name === 'children') ?? manifest?.slots.find((s) => s.name !== 'outlet')\n  const ctx: InsertContext = childSlot\n    ? {\n        target: { parentId: nodeId, slot: childSlot.name },\n        slotAllow: manifest!.slots.find((s) => s.name === childSlot.name)?.allow,\n        destinationLabel: `${shortId(node.componentId)} · ${childSlot.name}`,\n      }\n    : resolveSiblingContext(studio, root, nodeId)\n\n  // The field vocabulary governs only the top level (a direct child of the page\n  // root). `length > 0` matches the validator, which treats an empty allow as\n  // \"allow any\" (validate.ts).\n  if (fieldAllow && fieldAllow.length > 0 && ctx.target.parentId === root.id) {\n    return { ...ctx, slotAllow: intersectAllow(ctx.slotAllow, fieldAllow) }\n  }\n  return ctx\n}\n\n/** Sibling-or-root insert context for a node with no insertable child slot. */\nfunction resolveSiblingContext(studio: StudioRegistry, root: ComponentNode, nodeId: string): InsertContext {\n  const info = getParentInfo(root, nodeId)\n  if (info) {\n    const pManifest = studio.registry.getManifest(info.parent.componentId)\n    const allow = pManifest?.slots.find((s) => s.name === info.slot)?.allow\n    return {\n      target: { parentId: info.parent.id, slot: info.slot, index: info.index + 1 },\n      slotAllow: allow,\n      destinationLabel: `${shortId(info.parent.componentId)} · ${info.slot}`,\n    }\n  }\n  return { target: { parentId: nodeId, slot: 'children' }, destinationLabel: 'root' }\n}\n\n/**\n * An in-canvas insertion position relative to a reference node (EC-405) — the\n * DnD position vocabulary (`lib/dnd/drop-rules`), narrowed to the three the\n * insertion affordances offer: `before`/`after` a sibling, or `into` an (empty)\n * container. `left`/`right` (the wrap-into-columns gesture) are DnD-only.\n */\nexport type InsertPosition = 'before' | 'after' | 'into'\n\n/**\n * Resolve an `InsertContext` for an EXPLICIT position relative to `nodeId`\n * (EC-405) — the position-carrying twin of {@link resolveInsertContext}, so an\n * affordance click at a chosen edge lands the insert at exactly that spot rather\n * than the panel re-deriving it from the selection.\n *\n * The slot resolution reuses the shared DnD rules — `into` uses\n * {@link primaryInsertSlot} (the same slot a drop `into` picks; `null` when the\n * node accepts no children), `before`/`after` use the reference's parent slot at\n * `index`/`index + 1` — so this surface and drag-insert can never disagree about\n * where a position lands or what it allows. `fieldAllow` (EC-188) still constrains\n * ONLY a direct child of the composition root, mirroring `resolveInsertContext`.\n */\nexport function resolveInsertContextAt(\n  builder: { present: ComponentNode },\n  nodeId: string,\n  position: InsertPosition,\n  fieldAllow?: readonly string[],\n  studio: StudioRegistry = getStudioRegistry(),\n): InsertContext | null {\n  const root = builder.present\n  const node = getNode(root, nodeId)\n  if (!node) return null\n\n  let ctx: InsertContext\n  if (position === 'into') {\n    const manifest = studio.registry.getManifest(node.componentId)\n    const slot = primaryInsertSlot(manifest)\n    if (!slot) return null // the node accepts no children — no `into` position\n    ctx = {\n      target: {\n        parentId: nodeId,\n        slot: slot.name,\n        index: (node.slots?.[slot.name] ?? []).length,\n      },\n      slotAllow: slot.allow,\n      destinationLabel: `${shortId(node.componentId)} · ${slot.name}`,\n    }\n  } else {\n    const info = getParentInfo(root, nodeId)\n    if (!info) return null // the root has no siblings — no before/after position\n    const pManifest = studio.registry.getManifest(info.parent.componentId)\n    ctx = {\n      target: {\n        parentId: info.parent.id,\n        slot: info.slot,\n        index: info.index + (position === 'after' ? 1 : 0),\n      },\n      slotAllow: pManifest?.slots.find((s) => s.name === info.slot)?.allow,\n      destinationLabel: `${shortId(info.parent.componentId)} · ${info.slot}`,\n    }\n  }\n\n  if (fieldAllow && fieldAllow.length > 0 && ctx.target.parentId === root.id) {\n    return { ...ctx, slotAllow: intersectAllow(ctx.slotAllow, fieldAllow) }\n  }\n  return ctx\n}\n\n/**\n * Which affordance positions are actually insertable at `nodeId` (EC-405 scope 3):\n * a position is offered only when it structurally exists AND at least one registry\n * component may land there (the SAME slot-rule filter the tree/DnD and the blocks\n * panel apply — {@link hasInsertableComponent} over the resolved `slotAllow`), so a\n * blocked spot shows no dead button.\n *\n * An EMPTY, insertable container surfaces ONLY `into` — the meaningful action there\n * is \"add the first child\", and an empty container often renders zero-height, so\n * its own before/after edges are degenerate and would pile the three \"+\" buttons\n * onto one point. A filled container and every leaf get before/after instead (each\n * child already carries its own edge affordances, so a filled container needs no\n * center \"+\").\n */\nexport function insertablePositions(\n  builder: { present: ComponentNode },\n  nodeId: string,\n  fieldAllow?: readonly string[],\n  studio: StudioRegistry = getStudioRegistry(),\n): InsertPosition[] {\n  // Empty insertable container → into only.\n  const into = resolveInsertContextAt(builder, nodeId, 'into', fieldAllow, studio)\n  if (into && (into.target.index ?? 0) === 0 && hasInsertableComponent(studio, into.slotAllow)) {\n    return ['into']\n  }\n  // Otherwise the sibling edges that accept something.\n  const out: InsertPosition[] = []\n  for (const position of ['before', 'after'] as const) {\n    const ctx = resolveInsertContextAt(builder, nodeId, position, fieldAllow, studio)\n    if (ctx && hasInsertableComponent(studio, ctx.slotAllow)) out.push(position)\n  }\n  return out\n}\n"]}

package/dist/components/builder/node-title.d.ts

@@ -0,0 +1,60 @@
+import type { ComponentNode } from '@elytracms/core/project-graph';
+import type { ComponentManifest } from '@elytracms/core/component-registry';
+/**
+ * Node display titles (EC-407) — the ONE helper behind both the page-tree row and
+ * the EC-404 selection-overlay frame label.
+ *
+ * A placed instance shows a derived **instance title** (its own text content, e.g. a
+ * heading's words) as the primary label, with the localized **component name** as
+ * muted secondary context; a node with no derivable instance title shows the
+ * component name alone. This replaces the old tree row's redundant `shortId` (mono
+ * id) + `title` pair — the raw id stays one hover away in the inspector header +
+ * the tree row `title=` attribute, so agent-inspectability is not lost.
+ *
+ * Placement: this lives in the studio (not `component-registry`) because the
+ * cheap rich-text head reuses `@elytracms/core/rich-text` `richTextPlainText`,
+ * which the DAG bars `component-registry` from importing. The pure derivation is
+ * mirrored from the CMS `resolveDocumentTitle` pattern (declared field/function +
+ * fallback), not shared with it.
+ */
+/**
+ * Prop names, in priority order, whose value best titles an instance (EC-407). The
+ * name-affinity phase of {@link deriveInstanceTitle}: identity-ish props first
+ * (`title`/`heading`/`label`), then generic text (`text`/`name`/`value`), then media
+ * captions (`caption`/`alt`, so an Image titles by its alt text, not its URL `src`).
+ */
+export declare const INSTANCE_TITLE_AFFINITY: readonly ["title", "heading", "label", "text", "name", "value", "caption", "alt"];
+/** Max characters of a derived instance title before it is truncated for a row/frame. */
+export declare const INSTANCE_TITLE_MAX = 64;
+export interface NodeDisplayTitle {
+    /** The main label a surface shows: the instance title when derivable, else the component name. */
+    primary: string;
+    /** The localized component name — shown as muted secondary context ONLY when an instance title distinguishes `primary`. */
+    secondary?: string;
+    /** The localized component TYPE name (always present). */
+    componentName: string;
+    /** The derived per-instance title (already truncated), when one could be derived. */
+    instanceTitle?: string;
+}
+/**
+ * Derive a placed instance's raw (untruncated) title from its effective prop values
+ * (EC-407), or `undefined` when nothing text-ish is set. Pure; mirrors the CMS
+ * `resolveDocumentTitle` precedence:
+ *
+ * 1. A declared `nodeTitle` **function** — composed from the values (throws are
+ *    swallowed so a bad pattern never breaks the tree).
+ * 2. A declared `nodeTitle` **prop name** — that prop's display text.
+ * 3. **Name-affinity heuristic** — the first {@link INSTANCE_TITLE_AFFINITY} prop
+ *    that carries display text.
+ * 4. **Fallback** — the first declared text-ish prop (declaration order) with a
+ *    non-URL value.
+ */
+export declare function deriveInstanceTitle(manifest: ComponentManifest | undefined, node: ComponentNode): string | undefined;
+/**
+ * The unified node label (EC-407) feeding the page-tree row AND the EC-404 overlay
+ * frame. `primary` is the derived instance title when one exists (truncated), else
+ * the localized component name; `secondary` is the localized component name, present
+ * only when an instance title distinguishes the row. `locale` is optional — omit it
+ * to resolve the component name against the active studio-UI locale.
+ */
+export declare function nodeDisplayTitle(manifest: ComponentManifest | undefined, node: ComponentNode, locale?: string): NodeDisplayTitle;

package/dist/components/builder/node-title.js

@@ -0,0 +1,135 @@
+import { effectivePropValues } from '@elytracms/core/component-registry';
+import { richTextPlainText } from '@elytracms/core/rich-text';
+import { componentDisplayName } from '@elytracms/studio/lib/persona/labels';
+/**
+ * Node display titles (EC-407) — the ONE helper behind both the page-tree row and
+ * the EC-404 selection-overlay frame label.
+ *
+ * A placed instance shows a derived **instance title** (its own text content, e.g. a
+ * heading's words) as the primary label, with the localized **component name** as
+ * muted secondary context; a node with no derivable instance title shows the
+ * component name alone. This replaces the old tree row's redundant `shortId` (mono
+ * id) + `title` pair — the raw id stays one hover away in the inspector header +
+ * the tree row `title=` attribute, so agent-inspectability is not lost.
+ *
+ * Placement: this lives in the studio (not `component-registry`) because the
+ * cheap rich-text head reuses `@elytracms/core/rich-text` `richTextPlainText`,
+ * which the DAG bars `component-registry` from importing. The pure derivation is
+ * mirrored from the CMS `resolveDocumentTitle` pattern (declared field/function +
+ * fallback), not shared with it.
+ */
+/**
+ * Prop names, in priority order, whose value best titles an instance (EC-407). The
+ * name-affinity phase of {@link deriveInstanceTitle}: identity-ish props first
+ * (`title`/`heading`/`label`), then generic text (`text`/`name`/`value`), then media
+ * captions (`caption`/`alt`, so an Image titles by its alt text, not its URL `src`).
+ */
+export const INSTANCE_TITLE_AFFINITY = [
+    'title',
+    'heading',
+    'label',
+    'text',
+    'name',
+    'value',
+    'caption',
+    'alt',
+];
+/** Max characters of a derived instance title before it is truncated for a row/frame. */
+export const INSTANCE_TITLE_MAX = 64;
+/** A value that looks like a URL / path / protocol — never a useful title. */
+const URL_LIKE = /^(https?:\/\/|\/|#|mailto:|tel:|data:)/i;
+/**
+ * Non-empty display text a text-ish prop value carries, else `undefined`.
+ * - `text` props: the trimmed string (rejected when `rejectUrl` and it looks URL-ish).
+ * - `richText` props: the cheap first-run plain-text head (`richTextPlainText`).
+ * - everything else (number/boolean/date/select/relation/asset/blocks/object): not text-ish.
+ */
+function propDisplayText(field, value, rejectUrl) {
+    if (field.type === 'text') {
+        if (typeof value !== 'string')
+            return undefined;
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            return undefined;
+        if (rejectUrl && URL_LIKE.test(trimmed))
+            return undefined;
+        return trimmed;
+    }
+    if (field.type === 'richText') {
+        const head = richTextPlainText(value)?.trim();
+        return head && head.length > 0 ? head : undefined;
+    }
+    return undefined;
+}
+/**
+ * Derive a placed instance's raw (untruncated) title from its effective prop values
+ * (EC-407), or `undefined` when nothing text-ish is set. Pure; mirrors the CMS
+ * `resolveDocumentTitle` precedence:
+ *
+ * 1. A declared `nodeTitle` **function** — composed from the values (throws are
+ *    swallowed so a bad pattern never breaks the tree).
+ * 2. A declared `nodeTitle` **prop name** — that prop's display text.
+ * 3. **Name-affinity heuristic** — the first {@link INSTANCE_TITLE_AFFINITY} prop
+ *    that carries display text.
+ * 4. **Fallback** — the first declared text-ish prop (declaration order) with a
+ *    non-URL value.
+ */
+export function deriveInstanceTitle(manifest, node) {
+    if (!manifest)
+        return undefined;
+    const values = effectivePropValues(manifest, node);
+    const declared = manifest.nodeTitle;
+    if (typeof declared === 'function') {
+        try {
+            const out = declared(values);
+            if (typeof out === 'string' && out.trim())
+                return out.trim();
+        }
+        catch {
+            // A throwing title pattern must never break the editor — fall through.
+        }
+    }
+    else if (typeof declared === 'string') {
+        const field = manifest.props[declared];
+        const text = field ? propDisplayText(field, values[declared], false) : undefined;
+        if (text)
+            return text;
+    }
+    for (const name of INSTANCE_TITLE_AFFINITY) {
+        const field = manifest.props[name];
+        if (!field)
+            continue;
+        const text = propDisplayText(field, values[name], false);
+        if (text)
+            return text;
+    }
+    for (const [name, field] of Object.entries(manifest.props)) {
+        const text = propDisplayText(field, values[name], true);
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+/** Truncate a title for a compact row / frame bar, appending an ellipsis. */
+function truncate(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max - 1).trimEnd()}…`;
+}
+/**
+ * The unified node label (EC-407) feeding the page-tree row AND the EC-404 overlay
+ * frame. `primary` is the derived instance title when one exists (truncated), else
+ * the localized component name; `secondary` is the localized component name, present
+ * only when an instance title distinguishes the row. `locale` is optional — omit it
+ * to resolve the component name against the active studio-UI locale.
+ */
+export function nodeDisplayTitle(manifest, node, locale) {
+    const componentName = componentDisplayName(node.componentId, manifest, locale);
+    const raw = deriveInstanceTitle(manifest, node);
+    const instanceTitle = raw ? truncate(raw, INSTANCE_TITLE_MAX) : undefined;
+    return {
+        componentName,
+        instanceTitle,
+        primary: instanceTitle ?? componentName,
+        secondary: instanceTitle ? componentName : undefined,
+    };
+}
+//# sourceMappingURL=node-title.js.map

package/dist/components/builder/node-title.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-title.js","sourceRoot":"","sources":["../../../src/components/builder/node-title.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ComponentNode } from '@elytracms/core/project-graph'\nimport type { ComponentManifest, PropField } from '@elytracms/core/component-registry'\nimport { effectivePropValues } from '@elytracms/core/component-registry'\nimport { richTextPlainText } from '@elytracms/core/rich-text'\nimport { componentDisplayName } from '@elytracms/studio/lib/persona/labels'\n\n/**\n * Node display titles (EC-407) — the ONE helper behind both the page-tree row and\n * the EC-404 selection-overlay frame label.\n *\n * A placed instance shows a derived **instance title** (its own text content, e.g. a\n * heading's words) as the primary label, with the localized **component name** as\n * muted secondary context; a node with no derivable instance title shows the\n * component name alone. This replaces the old tree row's redundant `shortId` (mono\n * id) + `title` pair — the raw id stays one hover away in the inspector header +\n * the tree row `title=` attribute, so agent-inspectability is not lost.\n *\n * Placement: this lives in the studio (not `component-registry`) because the\n * cheap rich-text head reuses `@elytracms/core/rich-text` `richTextPlainText`,\n * which the DAG bars `component-registry` from importing. The pure derivation is\n * mirrored from the CMS `resolveDocumentTitle` pattern (declared field/function +\n * fallback), not shared with it.\n */\n\n/**\n * Prop names, in priority order, whose value best titles an instance (EC-407). The\n * name-affinity phase of {@link deriveInstanceTitle}: identity-ish props first\n * (`title`/`heading`/`label`), then generic text (`text`/`name`/`value`), then media\n * captions (`caption`/`alt`, so an Image titles by its alt text, not its URL `src`).\n */\nexport const INSTANCE_TITLE_AFFINITY = [\n  'title',\n  'heading',\n  'label',\n  'text',\n  'name',\n  'value',\n  'caption',\n  'alt',\n] as const\n\n/** Max characters of a derived instance title before it is truncated for a row/frame. */\nexport const INSTANCE_TITLE_MAX = 64\n\n/** A value that looks like a URL / path / protocol — never a useful title. */\nconst URL_LIKE = /^(https?:\\/\\/|\\/|#|mailto:|tel:|data:)/i\n\nexport interface NodeDisplayTitle {\n  /** The main label a surface shows: the instance title when derivable, else the component name. */\n  primary: string\n  /** The localized component name — shown as muted secondary context ONLY when an instance title distinguishes `primary`. */\n  secondary?: string\n  /** The localized component TYPE name (always present). */\n  componentName: string\n  /** The derived per-instance title (already truncated), when one could be derived. */\n  instanceTitle?: string\n}\n\n/**\n * Non-empty display text a text-ish prop value carries, else `undefined`.\n * - `text` props: the trimmed string (rejected when `rejectUrl` and it looks URL-ish).\n * - `richText` props: the cheap first-run plain-text head (`richTextPlainText`).\n * - everything else (number/boolean/date/select/relation/asset/blocks/object): not text-ish.\n */\nfunction propDisplayText(field: PropField, value: unknown, rejectUrl: boolean): string | undefined {\n  if (field.type === 'text') {\n    if (typeof value !== 'string') return undefined\n    const trimmed = value.trim()\n    if (trimmed.length === 0) return undefined\n    if (rejectUrl && URL_LIKE.test(trimmed)) return undefined\n    return trimmed\n  }\n  if (field.type === 'richText') {\n    const head = richTextPlainText(value)?.trim()\n    return head && head.length > 0 ? head : undefined\n  }\n  return undefined\n}\n\n/**\n * Derive a placed instance's raw (untruncated) title from its effective prop values\n * (EC-407), or `undefined` when nothing text-ish is set. Pure; mirrors the CMS\n * `resolveDocumentTitle` precedence:\n *\n * 1. A declared `nodeTitle` **function** — composed from the values (throws are\n *    swallowed so a bad pattern never breaks the tree).\n * 2. A declared `nodeTitle` **prop name** — that prop's display text.\n * 3. **Name-affinity heuristic** — the first {@link INSTANCE_TITLE_AFFINITY} prop\n *    that carries display text.\n * 4. **Fallback** — the first declared text-ish prop (declaration order) with a\n *    non-URL value.\n */\nexport function deriveInstanceTitle(\n  manifest: ComponentManifest | undefined,\n  node: ComponentNode,\n): string | undefined {\n  if (!manifest) return undefined\n  const values = effectivePropValues(manifest, node)\n\n  const declared = manifest.nodeTitle\n  if (typeof declared === 'function') {\n    try {\n      const out = declared(values)\n      if (typeof out === 'string' && out.trim()) return out.trim()\n    } catch {\n      // A throwing title pattern must never break the editor — fall through.\n    }\n  } else if (typeof declared === 'string') {\n    const field = manifest.props[declared]\n    const text = field ? propDisplayText(field, values[declared], false) : undefined\n    if (text) return text\n  }\n\n  for (const name of INSTANCE_TITLE_AFFINITY) {\n    const field = manifest.props[name]\n    if (!field) continue\n    const text = propDisplayText(field, values[name], false)\n    if (text) return text\n  }\n\n  for (const [name, field] of Object.entries(manifest.props)) {\n    const text = propDisplayText(field, values[name], true)\n    if (text) return text\n  }\n\n  return undefined\n}\n\n/** Truncate a title for a compact row / frame bar, appending an ellipsis. */\nfunction truncate(value: string, max: number): string {\n  return value.length <= max ? value : `${value.slice(0, max - 1).trimEnd()}…`\n}\n\n/**\n * The unified node label (EC-407) feeding the page-tree row AND the EC-404 overlay\n * frame. `primary` is the derived instance title when one exists (truncated), else\n * the localized component name; `secondary` is the localized component name, present\n * only when an instance title distinguishes the row. `locale` is optional — omit it\n * to resolve the component name against the active studio-UI locale.\n */\nexport function nodeDisplayTitle(\n  manifest: ComponentManifest | undefined,\n  node: ComponentNode,\n  locale?: string,\n): NodeDisplayTitle {\n  const componentName = componentDisplayName(node.componentId, manifest, locale)\n  const raw = deriveInstanceTitle(manifest, node)\n  const instanceTitle = raw ? truncate(raw, INSTANCE_TITLE_MAX) : undefined\n  return {\n    componentName,\n    instanceTitle,\n    primary: instanceTitle ?? componentName,\n    secondary: instanceTitle ? componentName : undefined,\n  }\n}\n"]}