@sutrata/editor 0.1.2 → 0.3.0

package/dist/editor/prosemirror-to-sutra.js

@@ -1,94 +1,196 @@
+import { parseFrontmatter, formatAttributeBlock } from '@sutrata/parser';
 import { schema } from './schema';
+import { frontmatterFields } from './sutra-to-prosemirror';
+/** Plain text of a block, with hard_break nodes as '\n'. */
 function nodeText(node) {
-    return node.textContent;
-}
-function inlineToMarkdown(node) {
     let result = '';
     node.forEach(child => {
-        if (child.isText) {
-            let text = child.text ?? '';
-            if (child.marks.find(m => m.type === schema.marks['bold']))
-                text = `**${text}**`;
-            else if (child.marks.find(m => m.type === schema.marks['italic']))
-                text = `*${text}*`;
-            else if (child.marks.find(m => m.type === schema.marks['underline']))
-                text = `_${text}_`;
-            else if (child.marks.find(m => m.type === schema.marks['note_mark']))
-                text = `[[${text}]]`;
-            result += text;
-        }
+        if (child.isText)
+            result += child.text ?? '';
+        else if (child.type === schema.nodes['hard_break'])
+            result += '\n';
     });
     return result;
 }
+const DELIMITERS = {
+    bold: ['**', '**'],
+    italic: ['*', '*'],
+    underline: ['_', '_'],
+    note_mark: ['[[', ']]'],
+};
+/**
+ * Inline content → Sutra emphasis markup. Marks are opened and closed as a
+ * stack (ProseMirror orders them bold → italic → underline → note), so
+ * overlapping marks nest: bold+italic text becomes `***text***`.
+ *
+ * With `closeAtNewline`, every line is closed off on its own. Lyrics need
+ * that (the parser reads each `~` line separately); action does not (its
+ * whole paragraph is parsed as one run, so emphasis may span lines).
+ */
+function inlineToMarkdown(node, closeAtNewline = false) {
+    let out = '';
+    let open = [];
+    const closeTo = (depth) => {
+        while (open.length > depth)
+            out += DELIMITERS[open.pop().type.name]?.[1] ?? '';
+    };
+    const write = (text, marks) => {
+        const wanted = marks.filter(m => DELIMITERS[m.type.name]);
+        let common = 0;
+        while (common < open.length && common < wanted.length && open[common].eq(wanted[common]))
+            common++;
+        closeTo(common);
+        for (const m of wanted.slice(common)) {
+            out += DELIMITERS[m.type.name][0];
+            open.push(m);
+        }
+        out += text;
+    };
+    node.forEach(child => {
+        if (child.type === schema.nodes['hard_break']) {
+            closeTo(0);
+            out += '\n';
+        }
+        else if (child.isText) {
+            const text = child.text ?? '';
+            if (!closeAtNewline) {
+                write(text, child.marks);
+                return;
+            }
+            text.split('\n').forEach((line, i) => {
+                if (i > 0) {
+                    closeTo(0);
+                    out += '\n';
+                }
+                if (line)
+                    write(line, child.marks);
+            });
+        }
+    });
+    closeTo(0);
+    open = [];
+    return out;
+}
+function attributeBlock(node) {
+    return formatAttributeBlock(node.attrs['id'] ?? null, node.attrs['attrs'] ?? []);
+}
+/** `& key: value`, or `& key:` followed by `  - item` lines for a list value. */
+function metadataLines(node) {
+    const key = node.attrs['metaKey'];
+    const value = nodeText(node);
+    if (node.attrs['list']) {
+        const items = value.split('\n');
+        return [`& ${key}:`, ...items.map(item => (item.trim() ? `  - ${item.trim()}` : '  -'))];
+    }
+    return [`& ${key}: ${value}`.trimEnd()];
+}
 /**
  * Extract the text value of a frontmatter_field node, converting hard_break
  * nodes back to '\n' so multi-line values round-trip correctly.
  */
 function fieldText(node) {
-    let result = '';
-    node.forEach(child => {
-        if (child.isText)
-            result += child.text ?? '';
-        else if (child.type === schema.nodes['hard_break'])
-            result += '\n';
-    });
-    return result.trim();
+    return nodeText(node).trim();
 }
 /**
- * title_page node → frontmatter text block. Dotted keys ("title.hi") are
- * reassembled into one-level nested maps (2-space indent, matching the
- * parser's minimal-YAML frontmatter format). Fields with empty key AND
- * empty value are skipped; returns '' if nothing remains.
- * Multi-line values are serialized as YAML literal block scalars (|).
+ * title_page fields → one value per top-level key. Dotted keys ("title.hi")
+ * are reassembled into one-level nested maps. Fields without a key are skipped.
  */
-function serializeTitlePage(node) {
+function groupFields(fields) {
     const data = new Map();
-    node.forEach(field => {
-        if (field.type.name !== 'frontmatter_field')
-            return;
-        const key = (field.attrs['fmKey'] ?? '').trim();
-        const value = fieldText(field);
+    for (const [rawKey, value] of fields) {
+        const key = rawKey.trim();
         if (!key)
-            return;
+            continue;
         const dot = key.indexOf('.');
         if (dot > 0 && dot < key.length - 1) {
             const parent = key.slice(0, dot);
-            const sub = key.slice(dot + 1);
             const existing = data.get(parent);
             const map = existing !== undefined && typeof existing === 'object' ? existing : {};
-            map[sub] = value;
+            map[key.slice(dot + 1)] = value;
             data.set(parent, map);
         }
         else {
             data.set(key, value);
         }
+    }
+    return data;
+}
+/**
+ * YAML lines for one key, in the subset the parser's minimal YAML reader
+ * understands: plain scalars, `|` literal blocks for multi-line values, and
+ * one level of nested map (2-space indent).
+ */
+function keyLines(key, value) {
+    if (typeof value !== 'string') {
+        return [`${key}:`, ...Object.entries(value).map(([sub, sv]) => `  ${sub}: ${sv}`)];
+    }
+    if (value === '')
+        return [`${key}:`];
+    if (value.includes('\n'))
+        return [`${key}: |`, ...value.split('\n').map(ln => `  ${ln}`)];
+    return [`${key}: ${value}`];
+}
+function sameValue(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+const YAML_KEY = /^([a-zA-Z0-9_-]+):/;
+/**
+ * title_page node → frontmatter text block (ending in a blank line), or ''.
+ *
+ * When the node was built from frontmatter source (its `raw` attr), that
+ * source is kept: unchanged keys keep their original lines — including
+ * comments, lists, quoting and order the fields cannot represent — and only
+ * keys whose value changed are rewritten, removed, or appended.
+ */
+function serializeTitlePage(node) {
+    const fields = [];
+    node.forEach(field => {
+        if (field.type.name === 'frontmatter_field')
+            fields.push([field.attrs['fmKey'] ?? '', fieldText(field)]);
     });
-    if (data.size === 0)
-        return '';
-    const lines = ['---'];
-    for (const [key, value] of data) {
-        if (typeof value === 'string') {
-            if (value === '') {
-                lines.push(`${key}:`);
-            }
-            else if (value.includes('\n')) {
-                // YAML literal block scalar: preserves newlines verbatim
-                lines.push(`${key}: |`);
-                for (const ln of value.split('\n'))
-                    lines.push(`  ${ln}`);
-            }
-            else {
-                lines.push(`${key}: ${value}`);
-            }
+    const current = groupFields(fields);
+    const raw = node.attrs['raw'];
+    const parsed = raw ? parseFrontmatter(raw.endsWith('\n') ? raw : raw + '\n') : null;
+    if (!raw || !parsed) {
+        if (current.size === 0)
+            return '';
+        return ['---', ...[...current].flatMap(([k, v]) => keyLines(k, v)), '---'].join('\n') + '\n\n';
+    }
+    const original = groupFields(frontmatterFields(parsed.data).map(([k, v]) => [k, v.trim()]));
+    const lines = raw.replace(/\n$/, '').split('\n');
+    const body = lines.slice(1, -1); // between the --- fences
+    // Group raw lines into entries: a key line plus its continuation lines.
+    const entries = [];
+    for (const line of body) {
+        const m = YAML_KEY.exec(line);
+        if (m)
+            entries.push({ key: m[1], lines: [line] });
+        else if (entries.length > 0)
+            entries[entries.length - 1].lines.push(line);
+        else
+            entries.push({ key: null, lines: [line] });
+    }
+    const out = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        const key = entry.key;
+        if (key === null || !original.has(key) || sameValue(original.get(key), current.get(key))) {
+            if (key !== null && original.has(key) && !current.has(key))
+                continue; // removed
+            out.push(...entry.lines);
         }
-        else {
-            lines.push(`${key}:`);
-            for (const [sub, sv] of Object.entries(value))
-                lines.push(`  ${sub}: ${sv}`);
+        else if (current.has(key)) {
+            out.push(...keyLines(key, current.get(key)));
         }
+        if (key !== null)
+            seen.add(key);
     }
-    lines.push('---');
-    return lines.join('\n') + '\n\n';
+    for (const [key, value] of current)
+        if (!seen.has(key))
+            out.push(...keyLines(key, value));
+    if (!out.some(l => l.trim() !== ''))
+        return '';
+    return ['---', ...out, '---'].join('\n') + '\n\n';
 }
 export function prosemirrorToSutra(doc) {
     // Collect all top-level nodes into an array first
@@ -105,11 +207,12 @@ export function prosemirrorToSutra(doc) {
         const node = pmNodes[i];
         const type = node.type.name;
         if (type === 'character') {
-            // Group: character cue + following dialogue/parenthetical lines (no blank line between them).
+            // Group: character cue + following registry metadata and
+            // dialogue/parenthetical lines (no blank line between them).
             // Name, extension and dual-marker are all just typed text now — see
             // character-decoration-plugin.ts — so the node's own text is the
             // whole cue line, verbatim.
-            const lines = [`@${nodeText(node)}`];
+            const lines = [`@${nodeText(node)}${attributeBlock(node)}`];
             i++;
             while (i < pmNodes.length) {
                 const next = pmNodes[i];
@@ -122,6 +225,11 @@ export function prosemirrorToSutra(doc) {
                     lines.push(`( ${nodeText(next)} )`);
                     i++;
                 }
+                else if (nextType === 'scene_metadata') {
+                    // Only produced after a cue for {#characters} registry entries (§8.2).
+                    lines.push(...metadataLines(next));
+                    i++;
+                }
                 else {
                     break;
                 }
@@ -130,14 +238,12 @@ export function prosemirrorToSutra(doc) {
             continue;
         }
         if (type === 'scene_heading') {
-            const id = node.attrs['id'] ? ` {#${node.attrs['id']}}` : '';
-            // Group heading + optional synopsis + metadata lines with single newlines (no blank
-            // line between them), so the parser recognises them as one heading block.
-            const headingLines = [`## ${nodeText(node)}${id}`];
+            // Group heading + metadata lines with single newlines (no blank line
+            // between them), so the parser recognises them as one heading block.
+            const headingLines = [`## ${nodeText(node)}${attributeBlock(node)}`];
             i++;
             while (i < pmNodes.length && pmNodes[i].type.name === 'scene_metadata') {
-                const m = pmNodes[i];
-                headingLines.push(`& ${m.attrs['metaKey']}: ${nodeText(m)}`);
+                headingLines.push(...metadataLines(pmNodes[i]));
                 i++;
             }
             blocks.push(headingLines.join('\n'));
@@ -145,13 +251,12 @@ export function prosemirrorToSutra(doc) {
         }
         if (type === 'scene_metadata') {
             // Orphan metadata (outside a heading group) — emit as-is
-            blocks.push(`& ${node.attrs['metaKey']}: ${nodeText(node)}`);
+            blocks.push(metadataLines(node).join('\n'));
             i++;
             continue;
         }
         if (type === 'section') {
-            const id = node.attrs['id'] ? ` {#${node.attrs['id']}}` : '';
-            blocks.push(`# ${nodeText(node)}${id}`);
+            blocks.push(`# ${nodeText(node)}${attributeBlock(node)}`);
             i++;
             continue;
         }
@@ -173,17 +278,17 @@ export function prosemirrorToSutra(doc) {
             continue;
         }
         if (type === 'transition') {
-            blocks.push(`>> ${nodeText(node)}`);
+            blocks.push(nodeText(node).split('\n').map(l => `>> ${l}`).join('\n'));
             i++;
             continue;
         }
         if (type === 'centered') {
-            blocks.push(`>> ${nodeText(node)} <<`);
+            blocks.push(nodeText(node).split('\n').map(l => `>> ${l} <<`).join('\n'));
             i++;
             continue;
         }
         if (type === 'lyrics') {
-            blocks.push(`~ ${inlineToMarkdown(node)}`);
+            blocks.push(inlineToMarkdown(node, true).split('\n').map(l => `~ ${l}`).join('\n'));
             i++;
             continue;
         }

package/dist/editor/scene-heading-view.js

@@ -34,6 +34,7 @@ export class SceneHeadingView {
         this.input.value = node.attrs['id'] ?? '';
         this.input.setAttribute('aria-label', 'Scene number');
         this.input.spellcheck = false;
+        this.input.readOnly = !view.editable;
         this.input.addEventListener('keydown', this.onInputKeydown);
         this.input.addEventListener('blur', this.onInputBlur);
         // Prevent PM from handling clicks inside the input
@@ -116,6 +117,7 @@ export class SceneHeadingView {
             this.dom.dataset['sceneId'] = id;
         else
             delete this.dom.dataset['sceneId'];
+        this.input.readOnly = !this.pmView.editable;
         // Only update input if it doesn't have focus (avoid clobbering in-progress edits)
         if (document.activeElement !== this.input) {
             this.input.value = id;

package/dist/editor/schema.js

@@ -1,10 +1,34 @@
 import { Schema } from 'prosemirror-model';
+/**
+ * Attributes (format spec §10) other than the id, kept in source order as
+ * `{ key, value }` pairs so unknown ones round-trip. Serialized into the DOM
+ * as JSON so copy/paste inside the editor keeps them.
+ */
+function readAttrs(dom) {
+    try {
+        const parsed = JSON.parse(dom.dataset['attrs'] ?? '[]');
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function withAttrs(dom, node) {
+    const attrs = node.attrs['attrs'];
+    if (attrs.length > 0)
+        dom['data-attrs'] = JSON.stringify(attrs);
+    return dom;
+}
 const nodes = {
     doc: { content: 'title_page? block+' },
     // Frontmatter rendered as an editable card at the top of the document.
     // Only valid as the first child of doc (not in the block group).
     title_page: {
         content: 'frontmatter_field+',
+        // The frontmatter source this node was built from. prosemirror-to-sutra
+        // re-emits it verbatim (or edits only the changed keys), so comments,
+        // lists, quoting and key order the fields cannot represent survive.
+        attrs: { raw: { default: null } },
         toDOM: () => ['div', { class: 'cs-title-page-block' }, 0],
         parseDOM: [{ tag: 'div.cs-title-page-block' }],
     },
@@ -12,20 +36,27 @@ const nodes = {
         content: '(text | hard_break)*',
         marks: '',
         attrs: { fmKey: { default: '' } },
-        toDOM: (node) => ['div', { class: 'cs-fm-field', 'data-key': node.attrs['fmKey'] }, 0],
+        toDOM: (node) => {
+            const key = node.attrs['fmKey'];
+            // Tool-private `x-` keys (format spec §5, §7.1) stay in the text but are not shown.
+            return ['div', { class: 'cs-fm-field', 'data-key': key, ...(key.startsWith('x-') ? { 'data-private': 'true' } : {}) }, 0];
+        },
         parseDOM: [{ tag: 'div.cs-fm-field', getAttrs: (dom) => ({ fmKey: dom.dataset['key'] ?? '' }) }],
     },
     scene_heading: {
         group: 'block',
         content: 'inline*',
-        attrs: { id: { default: null } },
+        attrs: { id: { default: null }, attrs: { default: [] } },
         toDOM: (node) => {
             const attrs = { class: 'cs-scene-heading' };
             if (node.attrs['id'])
                 attrs['data-scene-id'] = node.attrs['id'];
-            return ['div', attrs, 0];
+            return ['div', withAttrs(attrs, node), 0];
         },
-        parseDOM: [{ tag: 'div.cs-scene-heading', getAttrs: (dom) => ({ id: dom.dataset['sceneId'] ?? null }) }],
+        parseDOM: [{
+                tag: 'div.cs-scene-heading',
+                getAttrs: (dom) => ({ id: dom.dataset['sceneId'] ?? null, attrs: readAttrs(dom) }),
+            }],
     },
     action: {
         group: 'block',
@@ -36,8 +67,17 @@ const nodes = {
     character: {
         group: 'block',
         content: 'inline*',
-        toDOM: () => ['div', { class: 'cs-character' }, 0],
-        parseDOM: [{ tag: 'div.cs-character' }],
+        attrs: { id: { default: null }, attrs: { default: [] } },
+        toDOM: (node) => {
+            const attrs = { class: 'cs-character' };
+            if (node.attrs['id'])
+                attrs['data-id'] = node.attrs['id'];
+            return ['div', withAttrs(attrs, node), 0];
+        },
+        parseDOM: [{
+                tag: 'div.cs-character',
+                getAttrs: (dom) => ({ id: dom.dataset['id'] ?? null, attrs: readAttrs(dom) }),
+            }],
     },
     dialogue: {
         group: 'block',
@@ -72,9 +112,25 @@ const nodes = {
     scene_metadata: {
         group: 'block',
         content: 'inline*',
-        attrs: { metaKey: { default: '' } },
-        toDOM: (node) => ['div', { class: 'cs-scene-metadata', 'data-key': node.attrs['metaKey'] }, 0],
-        parseDOM: [{ tag: 'div.cs-scene-metadata', getAttrs: (dom) => ({ metaKey: dom.dataset['key'] ?? '' }) }],
+        // list: the value is a `- item` list (§7.1), one item per line of content.
+        attrs: { metaKey: { default: '' }, list: { default: false } },
+        toDOM: (node) => {
+            const attrs = { class: 'cs-scene-metadata', 'data-key': node.attrs['metaKey'] };
+            if (node.attrs['list'])
+                attrs['data-list'] = 'true';
+            // `x-` keys belong to a tool (format spec §7.1): kept, but not shown
+            // (private-metadata-plugin keeps the caret out).
+            if (node.attrs['metaKey'].startsWith('x-'))
+                attrs['data-private'] = 'true';
+            return ['div', attrs, 0];
+        },
+        parseDOM: [{
+                tag: 'div.cs-scene-metadata',
+                getAttrs: (dom) => ({
+                    metaKey: dom.dataset['key'] ?? '',
+                    list: dom.dataset['list'] === 'true',
+                }),
+            }],
     },
     note: {
         group: 'block',
@@ -96,11 +152,16 @@ const nodes = {
     section: {
         group: 'block',
         content: 'inline*',
-        attrs: { level: { default: 1 }, id: { default: null } },
-        toDOM: (node) => [`h${node.attrs['level'] + 1}`, { class: 'cs-section' }, 0],
+        attrs: { level: { default: 1 }, id: { default: null }, attrs: { default: [] } },
+        toDOM: (node) => {
+            const attrs = { class: 'cs-section' };
+            if (node.attrs['id'])
+                attrs['data-id'] = node.attrs['id'];
+            return [`h${node.attrs['level'] + 1}`, withAttrs(attrs, node), 0];
+        },
         parseDOM: [
-            { tag: 'h2.cs-section', getAttrs: () => ({ level: 1 }) },
-            { tag: 'h3.cs-section', getAttrs: () => ({ level: 2 }) },
+            { tag: 'h2.cs-section', getAttrs: (dom) => ({ level: 1, id: dom.dataset['id'] ?? null, attrs: readAttrs(dom) }) },
+            { tag: 'h3.cs-section', getAttrs: (dom) => ({ level: 2, id: dom.dataset['id'] ?? null, attrs: readAttrs(dom) }) },
         ],
     },
     hard_break: {

package/dist/editor/sutra-to-prosemirror.d.ts

@@ -1,3 +1,5 @@
 import { Node as PmNode } from 'prosemirror-model';
 import type { DocumentNode } from '@sutrata/parser';
+/** The (fmKey, value) pairs a title_page shows for parsed frontmatter data. */
+export declare function frontmatterFields(data: Record<string, unknown>): [string, string][];
 export declare function sutraToProsemirror(doc: DocumentNode): PmNode;

package/dist/editor/sutra-to-prosemirror.js

@@ -13,7 +13,8 @@ function spansToNodes(spans) {
         const markType = schema.marks[span.type];
         if (!markType || inner.length === 0)
             return inner;
-        return inner.map(n => n.mark([markType.create()]));
+        // addToSet, not a replacement: nested emphasis keeps every mark.
+        return inner.map(n => n.mark(markType.create().addToSet(n.marks)));
     });
 }
 function textNodes(text) {
@@ -28,6 +29,13 @@ function textNodes(text) {
     }
     return nodes;
 }
+/** `& key: value` → scene_metadata; a list value becomes one line per item. */
+function metadataNode(meta) {
+    if (meta.items) {
+        return schema.nodes['scene_metadata'].create({ metaKey: meta.key, list: true }, textNodes(meta.items.join('\n')));
+    }
+    return schema.nodes['scene_metadata'].create({ metaKey: meta.key }, textNodes(meta.value));
+}
 function sceneContentToNodes(nodes) {
     const result = [];
     for (const node of nodes) {
@@ -43,7 +51,10 @@ function sceneContentToNodes(nodes) {
                 const cueText = [node.name, node.extension, node.isDual ? '^' : null]
                     .filter((part) => !!part)
                     .join(' ');
-                result.push(schema.nodes['character'].create({}, textNodes(cueText)));
+                result.push(schema.nodes['character'].create({ id: node.id, attrs: node.attrs }, textNodes(cueText)));
+                // Character-registry metadata (§8.2) follows the cue, before any dialogue.
+                for (const meta of node.metadata ?? [])
+                    result.push(metadataNode(meta));
                 for (const child of node.children) {
                     if (child.type === 'dialogue') {
                         result.push(schema.nodes['dialogue'].create({}, spansToNodes(child.spans)));
@@ -88,20 +99,25 @@ function frontmatterToNode(doc) {
     const fm = doc.frontmatter;
     if (!fm)
         return null;
+    const fields = frontmatterFields(fm.data).map(([key, value]) => schema.nodes['frontmatter_field'].create({ fmKey: key }, textNodes(value)));
+    if (fields.length === 0)
+        return null;
+    return schema.nodes['title_page'].create({ raw: fm.raw }, fields);
+}
+/** The (fmKey, value) pairs a title_page shows for parsed frontmatter data. */
+export function frontmatterFields(data) {
     const fields = [];
-    for (const [key, value] of Object.entries(fm.data)) {
+    for (const [key, value] of Object.entries(data)) {
         if (value !== null && typeof value === 'object') {
             for (const [sub, subVal] of Object.entries(value)) {
-                fields.push(schema.nodes['frontmatter_field'].create({ fmKey: `${key}.${sub}` }, textNodes(String(subVal))));
+                fields.push([`${key}.${sub}`, String(subVal)]);
             }
         }
         else {
-            fields.push(schema.nodes['frontmatter_field'].create({ fmKey: key }, textNodes(String(value ?? ''))));
+            fields.push([key, String(value ?? '')]);
         }
     }
-    if (fields.length === 0)
-        return null;
-    return schema.nodes['title_page'].create({}, fields);
+    return fields;
 }
 export function sutraToProsemirror(doc) {
     const topNodes = [];
@@ -111,38 +127,20 @@ export function sutraToProsemirror(doc) {
     for (const node of doc.children) {
         switch (node.type) {
             case 'section':
-                topNodes.push(schema.nodes['section'].create({ level: node.level, id: node.id }, textNodes(node.text)));
+                topNodes.push(schema.nodes['section'].create({ level: node.level, id: node.id, attrs: node.attrs }, textNodes(node.text)));
                 break;
             case 'scene-heading': {
                 const sceneNode = node;
-                topNodes.push(schema.nodes['scene_heading'].create({ id: sceneNode.id }, textNodes(sceneNode.text)));
-                for (const meta of sceneNode.metadata) {
-                    topNodes.push(schema.nodes['scene_metadata'].create({ metaKey: meta.key }, textNodes(meta.value)));
-                }
+                topNodes.push(schema.nodes['scene_heading'].create({ id: sceneNode.id, attrs: sceneNode.attrs }, textNodes(sceneNode.text)));
+                for (const meta of sceneNode.metadata)
+                    topNodes.push(metadataNode(meta));
                 topNodes.push(...sceneContentToNodes(sceneNode.children));
                 break;
             }
-            case 'action':
-                topNodes.push(schema.nodes['action'].create({}, spansToNodes(node.spans)));
-                break;
-            case 'transition':
-                topNodes.push(schema.nodes['transition'].create({}, textNodes(node.text)));
-                break;
-            case 'centered':
-                topNodes.push(schema.nodes['centered'].create({}, textNodes(node.text)));
-                break;
-            case 'lyrics':
-                topNodes.push(schema.nodes['lyrics'].create({}, spansToNodes(node.spans)));
-                break;
-            case 'note':
-                topNodes.push(schema.nodes['note'].create({}, textNodes(node.text)));
-                break;
-            case 'comment':
-                topNodes.push(schema.nodes['comment'].create({}, textNodes(node.text)));
-                break;
-            case 'page-break':
-                topNodes.push(schema.nodes['page_break'].create());
-                break;
+            default:
+                // Everything else (including cues outside a scene, e.g. a cold open
+                // or the {#characters} registry) maps exactly as inside a scene.
+                topNodes.push(...sceneContentToNodes([node]));
         }
     }
     // doc content is 'title_page? block+' — always need at least one body block

package/dist/extensions/ai-provider.d.ts

@@ -0,0 +1,44 @@
+/** Opaque JSON Schema object describing a structured response. */
+export type JsonSchema = Record<string, unknown>;
+export interface AIRequest {
+    /** System prompt. The editor's prompts (prompts.ts) describe Sutra, not a provider. */
+    system?: string;
+    prompt: string;
+    signal?: AbortSignal;
+}
+/** One in-flight AI call, for the status bar ("Calling <label>..."). */
+export interface AIActivity {
+    label: string;
+}
+/**
+ * LLM access, injected by the embedder (OSS spec §11.5). The OSS app supplies
+ * a bring-your-own-key provider; Sutrata Cloud supplies its own agents.
+ * Optional: without one, the editor hides every AI feature.
+ */
+export interface AIProvider {
+    id: string;
+    displayName: string;
+    /** Shown before any document content is sent (e.g. AI-assisted import). */
+    dataPolicyText: string;
+    /** Whether a call can succeed right now (e.g. an API key is set). */
+    isConfigured(): boolean | Promise<boolean>;
+    /** Free-text completion. */
+    complete(req: AIRequest): Promise<string>;
+    /** Completion that returns a value matching `schema`; the provider validates/parses it. */
+    completeStructured<T = unknown>(req: AIRequest & {
+        schema: JsonSchema;
+    }): Promise<T>;
+    /** Optional: in-flight calls, for the status bar. Calls `cb` immediately with the current list. */
+    subscribeActivity?(cb: (calls: AIActivity[]) => void): () => void;
+    /** Optional: open the embedder's setup UI, used when isConfigured() is false. */
+    openSetup?(): void;
+}
+export declare const AIProviderProvider: import("react").Provider<AIProvider | null>;
+/**
+ * The AI provider, or null when AI is unavailable in this session: no
+ * provider was injected, the session cannot edit, or `featureFlags.ai` is off.
+ * Components hide their AI UI when this is null.
+ */
+export declare function useAI(): AIProvider | null;
+/** `Calling <label>...` text for the status bar; '' when idle. */
+export declare function formatActivity(calls: AIActivity[]): string;