@sutrata/editor 0.2.0 → 0.4.0

package/dist/context/DocumentContext.d.ts

@@ -19,6 +19,8 @@ interface DocumentContextValue {
     ast: DocumentNode;
     mode: EditorMode;
     filePath: string | null;
+    /** What to call the open document: StorageAdapter.displayName, else filePath. */
+    fileDisplayName: string | null;
     isDirty: boolean;
     lastSaveTarget: 'file' | 'local' | null;
     ribbonVisible: boolean;
@@ -37,7 +39,10 @@ interface DocumentContextValue {
     toasts: ToastItem[];
     versions: VersionEntry[];
     versionHistoryVisible: boolean;
-    setText: (next: string) => void;
+    /** `markDirty: false` for changes that are not user edits (e.g. applied from storage). */
+    setText: (next: string, options?: {
+        markDirty?: boolean;
+    }) => void;
     setMode: (mode: EditorMode) => void;
     setFilePath: (path: string | null) => void;
     setRibbonVisible: (v: boolean) => void;

package/dist/context/DocumentContext.js

@@ -4,7 +4,7 @@ import { parse, importFountain, fountainDocToSutra } from '@sutrata/parser';
 import { StorageAdapterProvider } from '../extensions/storage-adapter';
 import { AIProviderProvider } from '../extensions/ai-provider';
 import { SpeechProviderProvider } from '../extensions/speech-provider';
-import { SessionProvider, DEFAULT_SESSION } from '../extensions/session';
+import { SessionProvider, DEFAULT_SESSION, isFeatureEnabled } from '../extensions/session';
 import { PanelRegistryProvider, createPanelRegistry } from '../extensions/panel-registry';
 import { CommandRegistryProvider, createCommandRegistry, matchesShortcut } from '../extensions/command-registry';
 import { ExportRegistryProvider, createExportRegistry } from '../extensions/export-registry';
@@ -12,7 +12,10 @@ import { withBuiltins } from '../extensions/registry-store';
 import { DecorationProvidersProvider } from '../extensions/decorations';
 import { CollabBindingProvider } from '../extensions/collab';
 import { importDocx as importDocxToSutra } from '../file/docx-importer';
-import { getEditorView, getSourceView } from '../editor/editor-bus';
+import { getEditorView, getSourceView, markExternalText } from '../editor/editor-bus';
+import { externalChange } from '../editor/external-change';
+import { sutraToProsemirror } from '../editor/sutra-to-prosemirror';
+import { prosemirrorToSutra } from '../editor/prosemirror-to-sutra';
 import { setFlatFrontmatterField } from '../editor/frontmatter-field';
 import { builtinCommands } from '../shell/builtin-commands';
 import { resolveStyle } from '../styles/registry';
@@ -69,7 +72,18 @@ export function DocumentProvider({ children, storageAdapter, aiProvider, speechP
     const [text, setTextState] = useState(EMPTY_DOC);
     const [ast, setAst] = useState(() => parse(EMPTY_DOC));
     const [mode, setMode] = useState('formatted');
-    const [filePath, setFilePath] = useState(null);
+    const [filePath, setFilePathState] = useState(null);
+    // Updated at once (like textRef), so a save right after setFilePath, even
+    // from a child's effect in the same commit, goes to the new path.
+    const filePathRef = useRef(filePath);
+    // Mirrored in render, not in an effect: a parent's effect runs after its
+    // children's, and would overwrite a newer path set by a child's effect.
+    filePathRef.current = filePath;
+    const setFilePath = useCallback((path) => {
+        filePathRef.current = path;
+        setFilePathState(path);
+    }, []);
+    const fileDisplayName = filePath ? storageAdapter.displayName?.(filePath) ?? filePath : null;
     const [isDirty, setIsDirty] = useState(false);
     // Where the most recent save attempt went. isDirty tracks "does this differ
     // from the real file on disk" (VS Code-style) — a local autosave backs the
@@ -128,10 +142,15 @@ export function DocumentProvider({ children, storageAdapter, aiProvider, speechP
         }
     }, [storageAdapter]);
     useEffect(() => { void reloadCustomStyles(); }, [reloadCustomStyles]);
+    // `localFiles: false` (SessionContext): the embedder's documents are not local
+    // files, so there is no file to open or save as, and no local-session recovery
+    // (the embedder opens its documents and keeps its own offline copy).
+    const localFilesRef = useRef(true);
+    localFilesRef.current = isFeatureEnabled(session ?? DEFAULT_SESSION, 'localFiles');
     // Recover autosaved-but-unsaved content on boot (Ctrl-R, a crash, or the tab closing
     // without an explicit save) instead of always starting from a blank document.
     useEffect(() => {
-        const pointer = readRecoveryPointer();
+        const pointer = localFilesRef.current ? readRecoveryPointer() : null;
         if (!pointer)
             return;
         let cancelled = false;
@@ -159,10 +178,18 @@ export function DocumentProvider({ children, storageAdapter, aiProvider, speechP
         })();
         return () => { cancelled = true; };
     }, [storageAdapter, showToast]);
-    const setText = useCallback((next) => {
+    // Refs so the autosave path always writes the latest text/filePath without
+    // needing them in a dependency array that would tear down the timers below
+    // on every keystroke. setText also updates textRef at once, so a save that
+    // is waiting on storage can tell whether the user typed in the meantime.
+    const textRef = useRef(text);
+    textRef.current = text; // in render, for the same reason as filePathRef
+    const setText = useCallback((next, options) => {
+        textRef.current = next;
         setTextState(next);
         setAst(parse(next));
-        setDirty(true);
+        if (options?.markDirty !== false)
+            setDirty(true);
     }, []);
     const frontmatterData = ast.frontmatter?.data;
     const documentStyleId = frontmatterData?.['style'];
@@ -173,21 +200,48 @@ export function DocumentProvider({ children, storageAdapter, aiProvider, speechP
         setFlatFrontmatterField(getEditorView(), text, setText, 'style', id);
     }, [text, setText]);
     const markClean = useCallback(() => setDirty(false), []);
-    // Refs so the autosave path always writes the latest text/filePath without
-    // needing them in a dependency array that would tear down the timers below
-    // on every keystroke.
-    const textRef = useRef(text);
-    useEffect(() => { textRef.current = text; }, [text]);
     const modeRef = useRef(mode);
     modeRef.current = mode;
-    const filePathRef = useRef(filePath);
-    useEffect(() => { filePathRef.current = filePath; }, [filePath]);
     const autosaveFailedRef = useRef(false);
+    // The text last written to or received from storage, for filePath.
+    const syncedRef = useRef(null);
+    /**
+     * Applies a document from storage (a SaveResult or a remote update, OSS spec
+     * §11.5): one change, kept out of undo history, not a user edit. In the
+     * formatted editor only the blocks that differ are replaced.
+     */
+    const applyExternalText = useCallback((path, next) => {
+        const view = getEditorView();
+        if (modeRef.current === 'formatted' && view) {
+            const tr = externalChange(view.state, sutraToProsemirror(parse(next)));
+            if (tr)
+                view.dispatch(tr);
+            // The editor writes its own serialization of `next`; that is what is synced.
+            syncedRef.current = { path, text: prosemirrorToSutra(view.state.doc) };
+        }
+        else {
+            markExternalText(next);
+            setText(next, { markDirty: false });
+            syncedRef.current = { path, text: next };
+        }
+    }, [setText]);
     const save = useCallback(async () => {
         const path = filePathRef.current ?? '__autosave__';
+        const sent = textRef.current;
+        if (syncedRef.current?.path === path && syncedRef.current.text === sent)
+            return;
         try {
-            await storageAdapter.saveDocument(path, textRef.current);
-            writeRecoveryPointer(path);
+            const result = await storageAdapter.saveDocument(path, sent);
+            syncedRef.current = { path, text: sent };
+            const content = result ? result.content : undefined;
+            // Only if nothing was typed while the save was in flight; otherwise the
+            // next save carries those edits and the adapter merges again.
+            const samePath = (filePathRef.current ?? '__autosave__') === path;
+            if (content !== undefined && content !== sent && textRef.current === sent && samePath) {
+                applyExternalText(path, content);
+            }
+            if (localFilesRef.current)
+                writeRecoveryPointer(path);
             setLastSaveTarget('local');
             autosaveFailedRef.current = false;
             // Deliberately NOT setDirty(false) here — this is a local backup, not a
@@ -207,7 +261,20 @@ export function DocumentProvider({ children, storageAdapter, aiProvider, speechP
                 showToast('Autosave failed — your browser storage may be full or unavailable.', 'warn');
             }
         }
-    }, [storageAdapter, showToast]);
+    }, [storageAdapter, showToast, applyExternalText]);
+    // Changes saved elsewhere (OSS spec §11.5), applied only while there are no
+    // unsaved local edits; otherwise the next save merges them.
+    useEffect(() => {
+        if (!filePath || !storageAdapter.subscribe)
+            return;
+        return storageAdapter.subscribe(filePath, content => {
+            const synced = syncedRef.current;
+            if (filePathRef.current !== filePath || synced?.path !== filePath || textRef.current !== synced.text)
+                return;
+            if (content !== textRef.current)
+                applyExternalText(filePath, content);
+        });
+    }, [filePath, storageAdapter, applyExternalText]);
     const newDocument = useCallback((initialContent) => {
         const doNew = () => {
             if (pauseTimerRef.current) {
@@ -242,6 +309,8 @@ export function DocumentProvider({ children, storageAdapter, aiProvider, speechP
         });
     }, [isDirty, showConfirm]);
     const openFile = useCallback(async () => {
+        if (!localFilesRef.current)
+            return;
         const doOpen = async () => {
             const result = await storageAdapter.openFile();
             if (!result)
@@ -324,6 +393,8 @@ export function DocumentProvider({ children, storageAdapter, aiProvider, speechP
         }
     }, [filePath, text, showToast, storageAdapter, refreshVersions]);
     const saveFileAs = useCallback(async () => {
+        if (!localFilesRef.current)
+            return;
         const name = filePath ?? 'untitled.sutra';
         const result = await storageAdapter.saveFile(name, text, null);
         if (result) {
@@ -616,7 +687,7 @@ export function DocumentProvider({ children, storageAdapter, aiProvider, speechP
         return off;
     }, [saveFile, showConfirm]);
     return (_jsx(StorageAdapterProvider, { value: storageAdapter, children: _jsx(SessionProvider, { value: session ?? DEFAULT_SESSION, children: _jsx(AIProviderProvider, { value: aiProvider ?? null, children: _jsx(SpeechProviderProvider, { value: speechProvider ?? null, children: _jsx(PanelRegistryProvider, { value: panelRegistry, children: _jsx(CommandRegistryProvider, { value: commandRegistry, children: _jsx(ExportRegistryProvider, { value: exportRegistry, children: _jsx(DecorationProvidersProvider, { value: decorationProviders ?? NO_DECORATIONS, children: _jsx(CollabBindingProvider, { value: collabBinding ?? null, children: _jsx(DocumentContext.Provider, { value: {
-                                                text, ast, mode, filePath, isDirty, lastSaveTarget, ribbonVisible, navVisible, exportVisible, settingsVisible,
+                                                text, ast, mode, filePath, fileDisplayName, isDirty, lastSaveTarget, ribbonVisible, navVisible, exportVisible, settingsVisible,
                                                 voiceActive, metadataVisible,
                                                 findReplaceVisible, findMode, styleVisible, customStyles, resolvedStyle, watermarkText,
                                                 confirmModal, toasts, versions, versionHistoryVisible,

package/dist/editor/EditorView.js

@@ -16,6 +16,7 @@ import { useCanEdit } from '../extensions/session';
 import { useDecorationProviders } from '../extensions/decorations';
 import { useCollabBinding } from '../extensions/collab';
 import { createExternalDecorationsPlugin } from './external-decorations-plugin';
+import { EXTERNAL_CHANGE } from './external-change';
 export function EditorView() {
     const { text, ast, setText, resolvedStyle } = useDocument();
     const astRef = useRef(ast);
@@ -55,7 +56,7 @@ export function EditorView() {
             },
             editable: () => canEditRef.current,
             dispatchTransaction(tr) {
-                if (tr.docChanged && !canEditRef.current)
+                if (tr.docChanged && !canEditRef.current && !tr.getMeta(EXTERNAL_CHANGE))
                     return;
                 const newState = view.state.apply(tr);
                 view.updateState(newState);
@@ -63,7 +64,8 @@ export function EditorView() {
                     const newText = prosemirrorToSutra(newState.doc);
                     if (newText !== textRef.current) {
                         selfChangeRef.current = true;
-                        setText(newText);
+                        // A change applied from storage is not a user edit.
+                        setText(newText, tr.getMeta(EXTERNAL_CHANGE) ? { markDirty: false } : undefined);
                     }
                 }
                 emit();

package/dist/editor/editor-bus.d.ts

@@ -12,3 +12,6 @@ export declare function emit(): void;
 /** Window event that opens the title page form (TitlePageDialog, mounted by AppShell). */
 export declare const OPEN_TITLE_PAGE_EVENT = "cs:open-title-page";
 export declare function openTitlePageForm(): void;
+export declare function markExternalText(text: string): void;
+/** True, once, if `text` is the one marked by markExternalText. */
+export declare function takeExternalText(text: string): boolean;

package/dist/editor/editor-bus.js

@@ -37,3 +37,16 @@ export const OPEN_TITLE_PAGE_EVENT = 'cs:open-title-page';
 export function openTitlePageForm() {
     window.dispatchEvent(new CustomEvent(OPEN_TITLE_PAGE_EVENT));
 }
+// Text the document context is applying from storage (a SaveResult or a
+// remote update). The source view applies it outside its undo history.
+let externalText = null;
+export function markExternalText(text) {
+    externalText = text;
+}
+/** True, once, if `text` is the one marked by markExternalText. */
+export function takeExternalText(text) {
+    const hit = externalText === text;
+    if (hit)
+        externalText = null;
+    return hit;
+}

package/dist/editor/external-change.d.ts

@@ -0,0 +1,11 @@
+import type { Node } from 'prosemirror-model';
+import type { EditorState, Transaction } from 'prosemirror-state';
+/** Transaction meta marking a change that came from storage, not the user. */
+export declare const EXTERNAL_CHANGE = "sutrataExternalChange";
+/**
+ * A transaction turning `state.doc` into `next` that replaces only the
+ * top-level blocks that differ (a block whose only change is its attributes
+ * keeps its content), so the selection in untouched blocks stays where it is.
+ * Kept out of undo history and marked EXTERNAL_CHANGE. Null if they are equal.
+ */
+export declare function externalChange(state: EditorState, next: Node): Transaction | null;

package/dist/editor/external-change.js

@@ -0,0 +1,105 @@
+/** Transaction meta marking a change that came from storage, not the user. */
+export const EXTERNAL_CHANGE = 'sutrataExternalChange';
+/** Above this many block pairs the diff gives up and replaces the whole changed middle. */
+const MAX_DIFF_CELLS = 4_000_000;
+/**
+ * A transaction turning `state.doc` into `next` that replaces only the
+ * top-level blocks that differ (a block whose only change is its attributes
+ * keeps its content), so the selection in untouched blocks stays where it is.
+ * Kept out of undo history and marked EXTERNAL_CHANGE. Null if they are equal.
+ */
+export function externalChange(state, next) {
+    if (state.doc.eq(next))
+        return null;
+    const a = children(state.doc);
+    const b = children(next);
+    let start = 0;
+    while (start < a.length && start < b.length && a[start].eq(b[start]))
+        start++;
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1].eq(b[endB - 1])) {
+        endA--;
+        endB--;
+    }
+    const runs = diffRuns(a, b, start, endA, start, endB);
+    const posA = offsets(a);
+    const posB = offsets(b);
+    const tr = state.tr;
+    // Last run first, so earlier positions stay valid.
+    for (const r of runs.reverse()) {
+        const one = r.aTo - r.aFrom === 1 && r.bTo - r.bFrom === 1;
+        const x = a[r.aFrom];
+        const y = b[r.bFrom];
+        if (one && x && y && x.type === y.type && x.content.eq(y.content) && x.sameMarkup(y) === false &&
+            y.type.validContent(x.content)) {
+            tr.setNodeMarkup(posA[r.aFrom], undefined, y.attrs, y.marks);
+        }
+        else {
+            tr.replace(posA[r.aFrom], posA[r.aTo], next.slice(posB[r.bFrom], posB[r.bTo]));
+        }
+    }
+    return tr.setMeta('addToHistory', false).setMeta(EXTERNAL_CHANGE, true);
+}
+function children(doc) {
+    const list = [];
+    doc.forEach(n => { list.push(n); });
+    return list;
+}
+/** Start position of each top-level child, plus the end of the content. */
+function offsets(nodes) {
+    const pos = [0];
+    for (const n of nodes)
+        pos.push(pos.at(-1) + n.nodeSize);
+    return pos;
+}
+/** Runs of unmatched blocks between a[aStart..aEnd) and b[bStart..bEnd), by longest common subsequence. */
+function diffRuns(a, b, aStart, aEnd, bStart, bEnd) {
+    const n = aEnd - aStart;
+    const m = bEnd - bStart;
+    if (n === 0 && m === 0)
+        return [];
+    if (n === 0 || m === 0 || n * m > MAX_DIFF_CELLS)
+        return [{ aFrom: aStart, aTo: aEnd, bFrom: bStart, bTo: bEnd }];
+    // lcs[i][j]: LCS length of a[aStart+i..aEnd) and b[bStart+j..bEnd).
+    const w = m + 1;
+    const lcs = new Uint32Array((n + 1) * w);
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i * w + j] = a[aStart + i].eq(b[bStart + j])
+                ? lcs[(i + 1) * w + j + 1] + 1
+                : Math.max(lcs[(i + 1) * w + j], lcs[i * w + j + 1]);
+        }
+    }
+    const runs = [];
+    let run = null;
+    let i = 0;
+    let j = 0;
+    const extend = (di, dj) => {
+        if (!run)
+            run = { aFrom: aStart + i, aTo: aStart + i, bFrom: bStart + j, bTo: bStart + j };
+        run.aTo += di;
+        run.bTo += dj;
+    };
+    while (i < n || j < m) {
+        if (i < n && j < m && a[aStart + i].eq(b[bStart + j])) {
+            if (run) {
+                runs.push(run);
+                run = null;
+            }
+            i++;
+            j++;
+        }
+        else if (j < m && (i === n || lcs[i * w + j + 1] >= lcs[(i + 1) * w + j])) {
+            extend(0, 1);
+            j++;
+        }
+        else {
+            extend(1, 0);
+            i++;
+        }
+    }
+    if (run)
+        runs.push(run);
+    return runs;
+}

package/dist/editor/frontmatter-field-view.js

@@ -6,6 +6,9 @@ export class FrontmatterFieldView {
         this.dom = document.createElement('div');
         this.dom.className = 'cs-fm-field';
         this.dom.dataset['key'] = node.attrs['fmKey'];
+        // Tool-private `x-` keys (format spec §5, §7.1) are hidden.
+        if (node.attrs['fmKey'].startsWith('x-'))
+            this.dom.dataset['private'] = 'true';
         this.contentDOM = document.createElement('span');
         this.contentDOM.className = 'cs-fm-field-content';
         this.dom.appendChild(this.contentDOM);

package/dist/editor/private-metadata-plugin.d.ts

@@ -1,10 +1,13 @@
 import { Plugin } from 'prosemirror-state';
 import type { Node as PmNode } from 'prosemirror-model';
 /**
- * Tool-private `x-` scene metadata (format spec §7.1) stays in the document
- * but is hidden (`data-private`, see schema.ts). This plugin keeps the caret
- * out of those hidden blocks and stops Backspace/Delete from merging text
- * into or out of them; a range deletion that spans one still removes it.
+ * Tool-private `x-` scene metadata and frontmatter keys (format spec §5, §7.1)
+ * stay in the document but are hidden (`data-private`, see schema.ts). This
+ * plugin keeps the caret out of those hidden blocks and title-page fields and
+ * stops Backspace/Delete from merging text into or out of them; a range
+ * deletion that spans one still removes it.
  */
 export declare function isPrivateBlock(node: PmNode | null | undefined): boolean;
+/** A hidden `x-` field of the title page. */
+export declare function isPrivateField(node: PmNode | null | undefined): boolean;
 export declare function createPrivateMetadataPlugin(): Plugin;

package/dist/editor/private-metadata-plugin.js

@@ -1,13 +1,36 @@
-import { Plugin, TextSelection } from 'prosemirror-state';
+import { Plugin, Selection, TextSelection } from 'prosemirror-state';
 /**
- * Tool-private `x-` scene metadata (format spec §7.1) stays in the document
- * but is hidden (`data-private`, see schema.ts). This plugin keeps the caret
- * out of those hidden blocks and stops Backspace/Delete from merging text
- * into or out of them; a range deletion that spans one still removes it.
+ * Tool-private `x-` scene metadata and frontmatter keys (format spec §5, §7.1)
+ * stay in the document but are hidden (`data-private`, see schema.ts). This
+ * plugin keeps the caret out of those hidden blocks and title-page fields and
+ * stops Backspace/Delete from merging text into or out of them; a range
+ * deletion that spans one still removes it.
  */
 export function isPrivateBlock(node) {
     return !!node && node.type.name === 'scene_metadata' && node.attrs['metaKey'].startsWith('x-');
 }
+/** A hidden `x-` field of the title page. */
+export function isPrivateField(node) {
+    return !!node && node.type.name === 'frontmatter_field' && node.attrs['fmKey'].startsWith('x-');
+}
+function isHidden($pos) {
+    return ($pos.depth >= 1 && isPrivateBlock($pos.node(1))) || isPrivateField($pos.parent);
+}
+/** The nearest text selection outside hidden blocks and fields, from a hidden field at `$head`. */
+function leaveField(state, $head, dir) {
+    for (const d of [dir, -dir]) {
+        let pos = d === 1 ? $head.after() : $head.before();
+        for (;;) {
+            const sel = Selection.findFrom(state.doc.resolve(pos), d, true);
+            if (!sel)
+                break;
+            if (!isHidden(sel.$head))
+                return state.tr.setSelection(sel);
+            pos = d === 1 ? sel.$head.after() : sel.$head.before();
+        }
+    }
+    return null;
+}
 /** Position just inside the nearest visible top-level block from `index` in `dir`, or null. */
 function visibleBlockPos(doc, index, dir) {
     for (let i = index; i >= 0 && i < doc.childCount; i += dir) {
@@ -28,11 +51,13 @@ export function createPrivateMetadataPlugin() {
     return new Plugin({
         appendTransaction(trs, oldState, state) {
             const { $head, empty } = state.selection;
-            if (!empty || $head.depth < 1 || !isPrivateBlock($head.node(1)))
-                return null;
-            if (!trs.some(tr => tr.selectionSet || tr.docChanged))
+            if (!empty || !trs.some(tr => tr.selectionSet || tr.docChanged))
                 return null;
             const dir = $head.pos < oldState.selection.head ? -1 : 1;
+            if (isPrivateField($head.parent))
+                return leaveField(state, $head, dir);
+            if ($head.depth < 1 || !isPrivateBlock($head.node(1)))
+                return null;
             return moveOut(state, $head.index(0), dir);
         },
         props: {
@@ -40,9 +65,24 @@ export function createPrivateMetadataPlugin() {
                 if (event.key !== 'Backspace' && event.key !== 'Delete')
                     return false;
                 const { $head, empty } = view.state.selection;
-                if (!empty || $head.depth !== 1)
+                if (!empty)
                     return false;
                 const back = event.key === 'Backspace';
+                if ($head.parent.type.name === 'frontmatter_field') {
+                    // Between title-page fields: step over hidden ones instead of merging.
+                    if (back ? $head.parentOffset !== 0 : $head.parentOffset !== $head.parent.content.size)
+                        return false;
+                    const page = $head.node($head.depth - 1);
+                    const neighbour = $head.index($head.depth - 1) + (back ? -1 : 1);
+                    if (neighbour < 0 || neighbour >= page.childCount || !isPrivateField(page.child(neighbour)))
+                        return false;
+                    const tr = leaveField(view.state, view.state.doc.resolve(back ? $head.before() - 1 : $head.after() + 1), back ? -1 : 1);
+                    if (tr)
+                        view.dispatch(tr);
+                    return true;
+                }
+                if ($head.depth !== 1)
+                    return false;
                 if (back ? $head.parentOffset !== 0 : $head.parentOffset !== $head.parent.content.size)
                     return false;
                 const index = $head.index(0);

package/dist/editor/schema.js

@@ -36,7 +36,11 @@ 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: {

package/dist/extensions/session.d.ts

@@ -11,7 +11,10 @@
  * - `comment`: like `read`; decoration providers (comment threads) may still
  *   handle clicks.
  *
- * `featureFlags`: `ai: false` hides AI features, `voice: false` hides voice
+ * `featureFlags`: `ai: false` hides AI features, `voice: false` hides voice;
+ * `localFiles: false` hides New, Open and Save As, for embedders whose
+ * documents are not local files (Save stays: it saves through the adapter).
+ *
  * dictation. Unset flags count as enabled.
  */
 export interface SessionContext {

package/dist/extensions/storage-adapter.d.ts

@@ -9,8 +9,30 @@ import type { ScreenplayStyleDefinition } from '../styles/types';
  * has no equivalent in a non-web adapter. Callers just thread whatever the
  * adapter returned back into a later saveFile() call without inspecting it.
  */
+/**
+ * What a networked adapter may return from saveDocument (OSS spec §11.5).
+ */
+export interface SaveResult {
+    /**
+     * The document as the adapter now holds it, e.g. merged with changes saved
+     * elsewhere, or with lines the adapter adds (such as tool-private `x-` keys).
+     * The editor applies it if it differs from what was saved, as one change kept
+     * out of undo history, so long as the document has not been edited since the
+     * save began; otherwise it is dropped and the next save carries the edits.
+     */
+    content?: string;
+}
 export interface StorageAdapter {
-    saveDocument(path: string, content: string): Promise<void>;
+    /**
+     * Autosave. Local adapters return nothing; networked ones may return a
+     * SaveResult (see there).
+     *
+     * A dropped result or remote update (see subscribe) is never lost as long as
+     * the adapter bases its next save on the content it was last *sent*, not on
+     * what it returned: the next save then carries the local edits, and the
+     * adapter merges it again.
+     */
+    saveDocument(path: string, content: string): Promise<void | SaveResult>;
     loadDocument(path: string): Promise<string | null>;
     listVersions(path: string): Promise<VersionEntry[]>;
     openFile(): Promise<{
@@ -54,6 +76,19 @@ export interface StorageAdapter {
      * persist a new version entry when there is a difference against the previous version.
      */
     saveVersion?(path: string, content: string): Promise<boolean>;
+    /**
+     * Optional: changes to `path` saved elsewhere (another device, a merge).
+     * `onRemote` receives the whole document. The editor applies it like a
+     * SaveResult, and only if there are no local edits since the last save;
+     * otherwise it is dropped and the next save merges them. Returns an
+     * unsubscribe function. Called for the open document's path (filePath).
+     */
+    subscribe?(path: string, onRemote: (content: string) => void): () => void;
+    /**
+     * Optional: the name to show for `path` (e.g. a document title when paths
+     * are opaque ids). Defaults to the path itself.
+     */
+    displayName?(path: string): string;
 }
 export declare const StorageAdapterProvider: import("react").Provider<StorageAdapter | null>;
 export declare function useStorageAdapter(): StorageAdapter;

package/dist/findreplace/FindReplace.js

@@ -19,16 +19,24 @@ export function FindReplace() {
     const [currentIndex, setCurrentIndex] = useState(0);
     const queryRef = useRef(null);
     const nextIndexAfterReplace = useRef(null);
-    // Recompute matches whenever query/text/caseSensitive/mode changes.
+    // What the next highlight pass should scroll: 'none' (text edits), 'soft'
+    // (query typing: only if the match is off-screen), 'center' (navigation).
+    const pendingScroll = useRef('none');
+    const lastSearch = useRef({ query: '', caseSensitive: false, mode: mode });
+    // Recompute matches whenever query/text/caseSensitive/mode changes — but only
+    // while the panel is open, so a leftover query never affects the editor.
     // In formatted mode we search the PM doc's display text (not raw Sutra) so
     // offsets are correct; in source mode the CodeMirror doc *is* the raw Sutra
     // text, so raw-offset matches from find-engine map directly onto it.
     useEffect(() => {
+        if (!findReplaceVisible)
+            return;
         if (!query) {
             setMatches([]);
             setCurrentIndex(0);
             clearFindHighlights();
             clearSourceFindHighlights();
+            lastSearch.current = { query, caseSensitive, mode };
             return;
         }
         let found;
@@ -41,44 +49,43 @@ export function FindReplace() {
             const view = getEditorView();
             found = view ? findInPmDoc(view.state.doc, query, { caseSensitive }) : [];
         }
+        const prev = lastSearch.current;
+        const searchChanged = prev.query !== query || prev.caseSensitive !== caseSensitive || prev.mode !== mode;
+        lastSearch.current = { query, caseSensitive, mode };
         setMatches(found);
-        const highlight = mode === 'source' ? setSourceFindHighlights : setFindHighlights;
-        const scrollTo = mode === 'source' ? scrollToSourceMatch : scrollToPmMatch;
         if (nextIndexAfterReplace.current !== null) {
             const idx = Math.min(nextIndexAfterReplace.current, Math.max(0, found.length - 1));
             setCurrentIndex(idx);
             nextIndexAfterReplace.current = null;
-            highlight(found, idx);
-            if (found.length > 0)
-                scrollTo(found[idx]);
+            pendingScroll.current = 'center';
         }
         else {
             setCurrentIndex(0);
-            highlight(found, 0);
-            if (found.length > 0)
-                scrollTo(found[0]);
+            // Plain document edits must not move the viewport.
+            pendingScroll.current = searchChanged ? 'soft' : 'none';
         }
         // text in deps so we re-search after replace; view not in deps (stable ref)
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [query, text, caseSensitive, mode]);
-    // Scroll to current match and update active highlight whenever index changes.
-    const didMount = useRef(false);
+    }, [query, text, caseSensitive, mode, findReplaceVisible]);
+    // Update the active highlight (and scroll if requested) whenever matches/index change.
     useEffect(() => {
-        if (!didMount.current) {
-            didMount.current = true;
+        if (!findReplaceVisible || !query)
             return;
-        }
+        const scroll = pendingScroll.current;
+        pendingScroll.current = 'none';
+        const cur = matches[currentIndex];
         if (mode === 'source') {
             setSourceFindHighlights(matches, currentIndex);
-            if (matches.length > 0)
-                scrollToSourceMatch(matches[currentIndex]);
+            if (cur && scroll !== 'none')
+                scrollToSourceMatch(cur, scroll === 'center');
         }
         else {
             setFindHighlights(matches, currentIndex);
-            if (matches.length > 0)
-                scrollToPmMatch(matches[currentIndex]);
+            if (cur && scroll !== 'none')
+                scrollToPmMatch(cur, scroll === 'center');
         }
-    }, [currentIndex, matches, mode]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [currentIndex, matches, mode, findReplaceVisible]);
     // Clear highlights when the panel closes.
     useEffect(() => {
         if (!findReplaceVisible) {
@@ -94,11 +101,13 @@ export function FindReplace() {
     const goNext = useCallback(() => {
         if (matches.length === 0)
             return;
+        pendingScroll.current = 'center';
         setCurrentIndex(i => (i + 1) % matches.length);
     }, [matches.length]);
     const goPrev = useCallback(() => {
         if (matches.length === 0)
             return;
+        pendingScroll.current = 'center';
         setCurrentIndex(i => (i - 1 + matches.length) % matches.length);
     }, [matches.length]);
     const handleReplaceOne = useCallback(() => {

package/dist/findreplace/scroll-to-match.d.ts

@@ -24,6 +24,6 @@ export declare function findInPmDoc(doc: Node, query: string, options?: {
  * Highlighting is handled by the find-highlight plugin (decorations) — no selection
  * dispatch here so focus stays in the find input.
  */
-export declare function scrollToPmMatch(match: PmMatch): void;
+export declare function scrollToPmMatch(match: PmMatch, center?: boolean): void;
 /** Legacy: maps a flat text-space offset to PM position. Used by tests only. */
 export declare function textOffsetToPmPos(doc: Node, textOffset: number): number | null;

package/dist/findreplace/scroll-to-match.js

@@ -52,14 +52,24 @@ export function findInPmDoc(doc, query, options = {}) {
  * Highlighting is handled by the find-highlight plugin (decorations) — no selection
  * dispatch here so focus stays in the find input.
  */
-export function scrollToPmMatch(match) {
+export function scrollToPmMatch(match, center = true) {
     const view = getEditorView();
     if (!view)
         return;
     try {
         const domNode = view.nodeDOM(match.pmFrom);
         const el = domNode instanceof Element ? domNode : domNode?.parentElement;
-        el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        if (!el)
+            return;
+        if (!center) {
+            // While typing: only scroll when the match is off-screen, and don't animate.
+            const r = el.getBoundingClientRect();
+            if (r.top >= 0 && r.bottom <= window.innerHeight)
+                return;
+            el.scrollIntoView({ block: 'center' });
+            return;
+        }
+        el.scrollIntoView({ behavior: 'smooth', block: 'center' });
     }
     catch {
         // At doc boundary — ignore

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { LanguageProvider, useLanguage } from './i18n/LanguageContext';
 export { TranslationProvider, useTranslation } from './i18n/useTranslation';
 export type { EditorMode, VersionEntry } from './types';
 export type { ScreenplayStyleDefinition } from './styles/types';
-export type { StorageAdapter } from './extensions/storage-adapter';
+export type { StorageAdapter, SaveResult } from './extensions/storage-adapter';
 export { useStorageAdapter } from './extensions/storage-adapter';
 export type { AIProvider, AIRequest, AIActivity, JsonSchema } from './extensions/ai-provider';
 export { useAI } from './extensions/ai-provider';

package/dist/navigator/SceneNavigator.js

@@ -3,7 +3,7 @@ import React, { useEffect, useState, useCallback } from 'react';
 import { TextSelection } from 'prosemirror-state';
 import { useDocument } from '../context/DocumentContext';
 import { useTranslation } from '../i18n/useTranslation';
-import { buildSceneList } from './scene-list';
+import { buildSceneList, buildSectionList } from './scene-list';
 import { getEditorView, getSourceView } from '../editor/editor-bus';
 import { schema } from '../editor/schema';
 import { EditorView as CmView } from '@codemirror/view';
@@ -198,6 +198,7 @@ export function SceneNavigator() {
     const ai = useAI();
     const canEdit = useCanEdit();
     const [scenes, setScenes] = useState([]);
+    const [sections, setSections] = useState([]);
     const [dragIndex, setDragIndex] = useState(null);
     const [dropIndex, setDropIndex] = useState(null);
     // New States
@@ -213,6 +214,7 @@ export function SceneNavigator() {
     // Rebuild scene list whenever text changes
     useEffect(() => {
         setScenes(buildSceneList(text));
+        setSections(buildSectionList(text));
     }, [text]);
     // Numbers that need renumbering (missing/duplicate/out of order; §7.4).
     // Nothing is flagged until at least one scene has a number.
@@ -389,6 +391,47 @@ export function SceneNavigator() {
             /* at doc boundary — ignore */
         }
     }, [setNavVisible]);
+    const handleSectionJump = useCallback((section) => {
+        const view = getEditorView();
+        if (!view) {
+            const cmView = getSourceView();
+            if (cmView) {
+                cmView.dispatch({
+                    selection: { anchor: section.textOffset },
+                    effects: CmView.scrollIntoView(section.textOffset, { y: 'start' }),
+                });
+                cmView.focus();
+                if (typeof window !== 'undefined' && window.innerWidth <= 640)
+                    setNavVisible(false);
+            }
+            return;
+        }
+        try {
+            let pos = null;
+            let count = 0;
+            view.state.doc.forEach((node, offset) => {
+                if (pos !== null)
+                    return;
+                if (node.type.name === 'section') {
+                    count++;
+                    if (count === section.index)
+                        pos = offset;
+                }
+            });
+            if (pos === null)
+                return;
+            view.dispatch(view.state.tr.setSelection(TextSelection.near(view.state.doc.resolve(pos + 1))));
+            view.focus();
+            const domNode = view.nodeDOM(pos);
+            const el = domNode instanceof Element ? domNode : domNode?.parentElement;
+            el?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+            if (typeof window !== 'undefined' && window.innerWidth <= 640)
+                setNavVisible(false);
+        }
+        catch {
+            /* at doc boundary — ignore */
+        }
+    }, [setNavVisible]);
     const handleDragStart = useCallback((idx) => {
         setDragIndex(idx);
     }, []);
@@ -498,6 +541,12 @@ export function SceneNavigator() {
         const omitted = scene.status.toLowerCase() === 'omitted';
         applyTextEdit(omitted ? restoreSceneInText(current, idx) : omitSceneInText(current, idx), setText);
     }, [liveText, setText]);
+    const renderSection = (section) => (_jsx("div", { role: "button", tabIndex: 0, className: "cs-nav-item cs-nav-section-anchor", "aria-label": `Jump to section ${section.heading}`, onClick: () => handleSectionJump(section), onKeyDown: (e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                handleSectionJump(section);
+            }
+        }, children: _jsx("div", { className: "cs-nav-scene-info", children: _jsx("div", { className: "cs-nav-heading", children: section.heading || '—' }) }) }, `section:${section.index}`));
     return (_jsxs("div", { className: "cs-navigator", role: "navigation", "aria-label": "Scene Navigator", children: [_jsxs("div", { className: "cs-nav-mobile-bar", children: [_jsx("span", { className: "cs-nav-mobile-title", children: t('navigator.title') }), _jsx("button", { type: "button", className: "cs-nav-mobile-close", "aria-label": "Close navigator", onClick: () => setNavVisible(false), children: _jsx(CloseIcon, { size: 18 }) })] }), _jsxs("div", { className: "cs-nav-list", children: [_jsx("button", { type: "button", className: "cs-nav-section-header cs-nav-frontmatter-btn", onClick: handleFrontmatter, title: t('navigator.frontmatter'), children: _jsx("span", { className: "cs-nav-title", children: t('navigator.frontmatter') }) }), _jsxs("div", { className: "cs-nav-section-header cs-nav-scenes-header", style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '8px' }, children: [_jsx("span", { className: "cs-nav-title", children: t('navigator.title') }), _jsx("span", { className: "cs-nav-count", children: scenes.length })] }), _jsxs("div", { style: { display: 'flex', gap: '4px', alignItems: 'center' }, onClick: e => e.stopPropagation(), children: [_jsx("button", { type: "button", className: "cs-nav-action-btn", onClick: () => setShowNavSynopsis(!showNavSynopsis), title: showNavSynopsis ? 'Hide Synopsis & Duration' : 'Show Synopsis & Duration', "aria-label": showNavSynopsis ? 'Hide Synopsis & Duration' : 'Show Synopsis & Duration', children: showNavSynopsis ? _jsx(EyeIcon, { size: 14 }) : _jsx(EyeOffIcon, { size: 14 }) }), ai && (_jsx("button", { type: "button", className: "cs-nav-action-btn", onClick: handleGenerateAllSceneMetadata, disabled: isProcessing, title: "Generate synopsis & estimate duration (all scenes)", "aria-label": "Generate synopsis & estimate duration (all scenes)", style: { opacity: isProcessing ? 0.5 : 1 }, children: _jsx(SparklesIcon, { size: 14 }) })), canEdit && (_jsx("button", { type: "button", className: "cs-nav-action-btn", onClick: handleRenumber, title: t('navigator.renumber'), "aria-label": t('navigator.renumber'), children: _jsx(RenumberIcon, { size: 14 }) }))] })] }), isProcessing && progressText && (_jsxs("div", { className: "cs-nav-progress", style: {
                             display: 'flex',
                             alignItems: 'center',
@@ -509,58 +558,65 @@ export function SceneNavigator() {
                             borderBottom: '1px solid var(--cs-ui-border-light, #e2e0d6)',
                             fontWeight: 500,
                         }, children: [_jsx("span", { className: "cs-spinner", style: { width: '10px', height: '10px', borderWidth: '1.5px' } }), _jsx("span", { children: progressText })] })), scenes.map((scene, idx) => {
+                        // Sections that start before this scene (and after the previous one) render as anchors above it.
+                        const prevOffset = idx === 0 ? -1 : scenes[idx - 1].textOffset;
+                        const leading = sections.filter(sec => sec.textOffset > prevOffset && sec.textOffset < scene.textOffset);
                         const issue = numberIssues[idx] ?? null;
                         const omitted = scene.status.toLowerCase() === 'omitted';
                         // The id is the scene number, so a missing id is one note, not two.
                         const note = issue ? issueLabel(issue) : scene.id ? null : t('navigator.missingId');
                         const notes = note ? [note] : [];
-                        return (_jsxs("div", { role: "button", tabIndex: 0, "aria-label": `Jump to ${scene.heading}${notes.length ? ` (${notes.join('; ')})` : ''}`, onKeyDown: (e) => {
-                                if (e.key === 'Enter' || e.key === ' ') {
-                                    e.preventDefault();
-                                    handleJump(scene);
-                                }
-                            }, className: [
-                                'cs-nav-item',
-                                // No {#id}: comments, scene-level diff, and page locking can't anchor to it.
-                                scene.id ? '' : 'cs-nav-scene-missing-id',
-                                issue ? 'cs-nav-scene-number-issue' : '',
-                                omitted ? 'cs-nav-scene-omitted' : '',
-                                dragIndex === idx ? 'cs-nav-dragging' : '',
-                                dropIndex === idx ? 'cs-nav-drop-target' : '',
-                            ]
-                                .filter(Boolean)
-                                .join(' '), draggable: canEdit, onClick: () => handleJump(scene), onDragStart: () => handleDragStart(idx), onDragOver: (e) => handleDragOver(e, idx), onDrop: (e) => handleDrop(e, idx), onDragEnd: () => {
-                                setDragIndex(null);
-                                setDropIndex(null);
-                            }, children: [_jsxs("div", { className: "cs-nav-scene-info", children: [_jsx("div", { className: "cs-nav-heading", children: scene.heading }), showNavSynopsis && (_jsxs("div", { className: "cs-nav-synopsis-row", style: { marginTop: '4px' }, children: [_jsx("div", { style: { flex: 1, minWidth: 0 }, children: !canEdit ? (scene.synopsis ? _jsx("div", { className: "cs-nav-scene-synopsis", children: scene.synopsis }) : null) : editingSceneIdx === idx ? (_jsx("input", { type: "text", className: "cs-nav-synopsis-input", value: editVal, onChange: e => setEditVal(e.target.value), onBlur: () => commitSynopsis(idx, scene), onKeyDown: e => {
-                                                            if (e.key === 'Enter')
-                                                                commitSynopsis(idx, scene);
-                                                            if (e.key === 'Escape')
-                                                                setEditingSceneIdx(null);
-                                                        }, autoFocus: true, onClick: e => e.stopPropagation() })) : scene.synopsis ? (_jsx("div", { className: "cs-nav-scene-synopsis", onClick: e => {
-                                                            e.stopPropagation();
-                                                            setEditingSceneIdx(idx);
-                                                            setEditVal(scene.synopsis);
-                                                        }, title: "Click to edit synopsis", children: scene.synopsis })) : (_jsx("div", { className: "cs-nav-scene-synopsis cs-nav-synopsis-placeholder", onClick: e => {
-                                                            e.stopPropagation();
-                                                            setEditingSceneIdx(idx);
-                                                            setEditVal('');
-                                                        }, role: "button", tabIndex: 0, "aria-label": "Add synopsis", onKeyDown: e => {
-                                                            if (e.key === 'Enter' || e.key === ' ') {
-                                                                e.stopPropagation();
-                                                                e.preventDefault();
-                                                                setEditingSceneIdx(idx);
-                                                                setEditVal('');
-                                                            }
-                                                        }, children: "+ Synopsis" })) }), ai && _jsx("button", { type: "button", onClick: (e) => { e.stopPropagation(); void handleSceneMetadata(scene); }, disabled: isProcessing, title: "Generate synopsis & estimate duration", "aria-label": "Generate synopsis & estimate duration", className: "cs-nav-action-btn cs-nav-synopsis-ai-btn", style: { color: 'var(--cs-ui-accent, #c4760a)', ...(isProcessing ? { opacity: 0.5 } : {}) }, children: _jsx(SparklesIcon, { size: 12 }) })] })), (scene.status || (showNavSynopsis && scene.estDuration)) && (_jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: '6px', alignItems: 'center', marginTop: '6px' }, children: [scene.status && (_jsx("span", { className: `cs-nav-status cs-status-${scene.status
-                                                        .toLowerCase()
-                                                        .replace(/\s+/g, '-')}`, children: scene.status })), showNavSynopsis && scene.estDuration && (_jsxs("span", { className: "cs-nav-status", title: "Estimated Onscreen Duration", style: {
-                                                        background: 'rgba(217, 119, 6, 0.1)',
-                                                        color: 'var(--cs-ui-accent, #c4760a)',
-                                                        border: '1px solid rgba(217, 119, 6, 0.25)',
-                                                        fontWeight: 600,
-                                                    }, children: ["\u23F1 ", scene.estDuration] }))] }))] }), _jsxs("div", { className: "cs-nav-scene-side", children: [scene.id ? (_jsx("div", { className: `cs-nav-scene-num${issue ? ' cs-nav-num-issue' : ''}`, title: issue ? issueLabel(issue) : undefined, children: scene.id })) : (_jsx("div", { className: "cs-nav-missing-id-icon", title: issue ? issueLabel(issue) : t('navigator.missingId'), "aria-hidden": "true", children: "\u26A0" })), canEdit && (_jsx("button", { type: "button", className: "cs-nav-action-btn cs-nav-omit-btn", title: omitted ? t('navigator.restoreScene') : t('navigator.omitScene'), "aria-label": `${omitted ? t('navigator.restoreScene') : t('navigator.omitScene')}: ${scene.heading}`, onClick: e => { e.stopPropagation(); handleOmitToggle(scene); }, children: omitted ? _jsx(RestoreIcon, { size: 12 }) : _jsx(OmitIcon, { size: 12 }) }))] })] }, `${idx}:${scene.id ?? ''}`));
-                    }), scenes.length === 0 && (_jsx("div", { className: "cs-nav-empty", children: t('navigator.empty') })), _jsx("div", { style: { marginTop: '20px', padding: '0 8px 10px', borderTop: '1px solid #eee', paddingTop: '15px' }, children: _jsxs("button", { type: "button", className: "cs-nav-section-header cs-nav-frontmatter-btn", onClick: () => setStatsOpen(true), style: { width: '100%', textAlign: 'left', display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }, children: [_jsx(StatsIcon, { size: 14 }), " ", _jsx("span", { className: "cs-nav-title", children: "Statistics" })] }) })] }), statsOpen && _jsx(StatisticsDialog, { onClose: () => setStatsOpen(false) })] }));
+                        return (_jsxs(React.Fragment, { children: [leading.map(renderSection), _jsxs("div", { 
+                                    // Ids can repeat until the writer renumbers (§7.4), so the index keeps keys unique.
+                                    role: "button", tabIndex: 0, "aria-label": `Jump to ${scene.heading}${notes.length ? ` (${notes.join('; ')})` : ''}`, onKeyDown: (e) => {
+                                        if (e.key === 'Enter' || e.key === ' ') {
+                                            e.preventDefault();
+                                            handleJump(scene);
+                                        }
+                                    }, className: [
+                                        'cs-nav-item',
+                                        // No {#id}: comments, scene-level diff, and page locking can't anchor to it.
+                                        scene.id ? '' : 'cs-nav-scene-missing-id',
+                                        issue ? 'cs-nav-scene-number-issue' : '',
+                                        omitted ? 'cs-nav-scene-omitted' : '',
+                                        dragIndex === idx ? 'cs-nav-dragging' : '',
+                                        dropIndex === idx ? 'cs-nav-drop-target' : '',
+                                    ]
+                                        .filter(Boolean)
+                                        .join(' '), draggable: canEdit, onClick: () => handleJump(scene), onDragStart: () => handleDragStart(idx), onDragOver: (e) => handleDragOver(e, idx), onDrop: (e) => handleDrop(e, idx), onDragEnd: () => {
+                                        setDragIndex(null);
+                                        setDropIndex(null);
+                                    }, children: [_jsxs("div", { className: "cs-nav-scene-info", children: [_jsx("div", { className: "cs-nav-heading", children: scene.heading }), showNavSynopsis && (_jsxs("div", { className: "cs-nav-synopsis-row", style: { marginTop: '4px' }, children: [_jsx("div", { style: { flex: 1, minWidth: 0 }, children: !canEdit ? (scene.synopsis ? _jsx("div", { className: "cs-nav-scene-synopsis", children: scene.synopsis }) : null) : editingSceneIdx === idx ? (_jsx("input", { type: "text", className: "cs-nav-synopsis-input", value: editVal, onChange: e => setEditVal(e.target.value), onBlur: () => commitSynopsis(idx, scene), onKeyDown: e => {
+                                                                    if (e.key === 'Enter')
+                                                                        commitSynopsis(idx, scene);
+                                                                    if (e.key === 'Escape')
+                                                                        setEditingSceneIdx(null);
+                                                                }, autoFocus: true, onClick: e => e.stopPropagation() })) : scene.synopsis ? (_jsx("div", { className: "cs-nav-scene-synopsis", onClick: e => {
+                                                                    e.stopPropagation();
+                                                                    setEditingSceneIdx(idx);
+                                                                    setEditVal(scene.synopsis);
+                                                                }, title: "Click to edit synopsis", children: scene.synopsis })) : (_jsx("div", { className: "cs-nav-scene-synopsis cs-nav-synopsis-placeholder", onClick: e => {
+                                                                    e.stopPropagation();
+                                                                    setEditingSceneIdx(idx);
+                                                                    setEditVal('');
+                                                                }, role: "button", tabIndex: 0, "aria-label": "Add synopsis", onKeyDown: e => {
+                                                                    if (e.key === 'Enter' || e.key === ' ') {
+                                                                        e.stopPropagation();
+                                                                        e.preventDefault();
+                                                                        setEditingSceneIdx(idx);
+                                                                        setEditVal('');
+                                                                    }
+                                                                }, children: "+ Synopsis" })) }), ai && _jsx("button", { type: "button", onClick: (e) => { e.stopPropagation(); void handleSceneMetadata(scene); }, disabled: isProcessing, title: "Generate synopsis & estimate duration", "aria-label": "Generate synopsis & estimate duration", className: "cs-nav-action-btn cs-nav-synopsis-ai-btn", style: { color: 'var(--cs-ui-accent, #c4760a)', ...(isProcessing ? { opacity: 0.5 } : {}) }, children: _jsx(SparklesIcon, { size: 12 }) })] })), (scene.status || (showNavSynopsis && scene.estDuration)) && (_jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: '6px', alignItems: 'center', marginTop: '6px' }, children: [scene.status && (_jsx("span", { className: `cs-nav-status cs-status-${scene.status
+                                                                .toLowerCase()
+                                                                .replace(/\s+/g, '-')}`, children: scene.status })), showNavSynopsis && scene.estDuration && (_jsxs("span", { className: "cs-nav-status", title: "Estimated Onscreen Duration", style: {
+                                                                background: 'rgba(217, 119, 6, 0.1)',
+                                                                color: 'var(--cs-ui-accent, #c4760a)',
+                                                                border: '1px solid rgba(217, 119, 6, 0.25)',
+                                                                fontWeight: 600,
+                                                            }, children: ["\u23F1 ", scene.estDuration] }))] }))] }), _jsxs("div", { className: "cs-nav-scene-side", children: [scene.id ? (_jsx("div", { className: `cs-nav-scene-num${issue ? ' cs-nav-num-issue' : ''}`, title: issue ? issueLabel(issue) : undefined, children: scene.id })) : (_jsx("div", { className: "cs-nav-missing-id-icon", title: issue ? issueLabel(issue) : t('navigator.missingId'), "aria-hidden": "true", children: "\u26A0" })), canEdit && (_jsx("button", { type: "button", className: "cs-nav-action-btn cs-nav-omit-btn", title: omitted ? t('navigator.restoreScene') : t('navigator.omitScene'), "aria-label": `${omitted ? t('navigator.restoreScene') : t('navigator.omitScene')}: ${scene.heading}`, onClick: e => { e.stopPropagation(); handleOmitToggle(scene); }, children: omitted ? _jsx(RestoreIcon, { size: 12 }) : _jsx(OmitIcon, { size: 12 }) }))] })] })] }, `${idx}:${scene.id ?? ''}`));
+                    }), sections
+                        .filter(sec => scenes.length === 0 || sec.textOffset > scenes[scenes.length - 1].textOffset)
+                        .map(renderSection), scenes.length === 0 && sections.length === 0 && (_jsx("div", { className: "cs-nav-empty", children: t('navigator.empty') })), _jsx("div", { style: { marginTop: '20px', padding: '0 8px 10px', borderTop: '1px solid #eee', paddingTop: '15px' }, children: _jsxs("button", { type: "button", className: "cs-nav-section-header cs-nav-frontmatter-btn", onClick: () => setStatsOpen(true), style: { width: '100%', textAlign: 'left', display: 'flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }, children: [_jsx(StatsIcon, { size: 14 }), " ", _jsx("span", { className: "cs-nav-title", children: "Statistics" })] }) })] }), statsOpen && _jsx(StatisticsDialog, { onClose: () => setStatsOpen(false) })] }));
 }
 /**
  * Reorder scene blocks in the source text.

package/dist/navigator/scene-list.d.ts

@@ -14,3 +14,10 @@ export interface SceneEntry {
  * Scenes are identified by scene heading lines (## prefix).
  */
 export declare function buildSceneList(text: string): SceneEntry[];
+export interface SectionEntry {
+    heading: string;
+    index: number;
+    textOffset: number;
+}
+/** Derive the `# ` section headings (acts, sequences, …) from Sutra source text. */
+export declare function buildSectionList(text: string): SectionEntry[];

package/dist/navigator/scene-list.js

@@ -68,3 +68,17 @@ export function buildSceneList(text) {
     }
     return scenes;
 }
+/** Derive the `# ` section headings (acts, sequences, …) from Sutra source text. */
+export function buildSectionList(text) {
+    const sections = [];
+    let offset = 0;
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '#' || trimmed.startsWith('# ') || trimmed.startsWith('#\t')) {
+            const { body } = splitAttributeBlock(trimmed.slice(1).trim());
+            sections.push({ heading: body.trim(), index: sections.length + 1, textOffset: offset });
+        }
+        offset += line.length + 1;
+    }
+    return sections;
+}

package/dist/shell/AppBar.js

@@ -9,7 +9,7 @@ import { SutrataLogo } from './SutrataLogo';
 import { getTemplate } from '../templates/templates';
 import { openTitlePageForm } from '../titlepage/TitlePageDialog';
 import { useSpeech } from '../extensions/speech-provider';
-import { useCanEdit } from '../extensions/session';
+import { useCanEdit, useSession, isFeatureEnabled } from '../extensions/session';
 import { usePanels } from '../extensions/panel-registry';
 import { usePanelContext } from './use-panel-context';
 import { useCommands, useCommandContext, displayShortcut } from './use-commands';
@@ -18,7 +18,7 @@ function AbBtn({ label, shortcut, active, variant, onClick, children }) {
     return (_jsxs("button", { type: "button", "aria-label": label, className: `cs-ab-btn${active ? ' cs-ab-active' : ''}${variantClass}`, onClick: onClick, children: [children, _jsxs("span", { className: "cs-tb-tip", role: "tooltip", children: [_jsx("span", { children: label }), shortcut ? _jsx("span", { className: "cs-tb-key", children: shortcut }) : null] })] }));
 }
 export function AppBar() {
-    const { mode, setMode, isDirty, filePath, ribbonVisible, setRibbonVisible, navVisible, setNavVisible, exportVisible, setExportVisible, settingsVisible, setSettingsVisible, metadataVisible, setMetadataVisible, voiceActive, setVoiceActive, newDocument, openFile, saveFile, saveFileAs, setText, importDocx, styleVisible, setStyleVisible, showConfirm, showToast, } = useDocument();
+    const { mode, setMode, isDirty, filePath, fileDisplayName, ribbonVisible, setRibbonVisible, navVisible, setNavVisible, exportVisible, setExportVisible, settingsVisible, setSettingsVisible, metadataVisible, setMetadataVisible, voiceActive, setVoiceActive, newDocument, openFile, saveFile, saveFileAs, setText, importDocx, styleVisible, setStyleVisible, showConfirm, showToast, } = useDocument();
     const { t, locale } = useTranslation();
     const speech = useSpeech();
     // AI-assisted import needs a provider and an edit session (useAI covers both).
@@ -33,7 +33,9 @@ export function AppBar() {
     const commandContext = useCommandContext();
     const panelContext = usePanelContext();
     const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
-    const name = filePath ?? 'untitled.sutra';
+    const name = fileDisplayName ?? filePath ?? 'untitled.sutra';
+    // Embedders whose documents are not local files turn these off.
+    const localFiles = isFeatureEnabled(useSession(), 'localFiles');
     const nextMode = mode === 'formatted' ? 'source' : 'formatted';
     const handleNew = () => {
         newDocument(getTemplate(locale));
@@ -49,5 +51,5 @@ export function AppBar() {
             showToast(err instanceof Error ? err.message : 'Failed to import the Word document.', 'error');
         }
     };
-    return (_jsxs("header", { className: "cs-app-bar", role: "banner", "aria-label": "Application header", children: [_jsxs("div", { className: "cs-ab-group cs-ab-left", children: [_jsxs("div", { className: "cs-ab-brand", title: "Sutrata Multilingual Screenplay Editor", children: [_jsx(SutrataLogo, { size: 20, showText: false }), _jsx("span", { className: "cs-ab-brand-title", children: "Sutrata" })] }), _jsx("span", { className: "cs-ab-sep cs-ab-desktop-only" }), _jsx(AbBtn, { label: t('appbar.navigator'), shortcut: "Ctrl+Shift+B", active: navVisible, onClick: () => setNavVisible(!navVisible), children: _jsx(NavigatorIcon, { size: 18 }) }), canEdit && (_jsx("span", { className: "cs-ab-desktop-only", children: _jsx(AbBtn, { label: t('appbar.titlePage'), onClick: openTitlePageForm, children: _jsx(TitlePageIcon, { size: 18 }) }) })), _jsxs("div", { className: "cs-ab-file-pill", title: filePath ?? 'untitled.sutra', children: [_jsx("span", { className: "cs-ab-file-name", children: name }), isDirty && _jsx("span", { className: "cs-ab-dirty", title: "Unsaved edits" })] })] }), _jsx("span", { className: "cs-ab-spacer cs-ab-desktop-only" }), _jsxs("div", { className: "cs-ab-group cs-ab-desktop-group", children: [_jsx(AbBtn, { label: mode === 'formatted' ? t('appbar.switchToSource') : t('appbar.switchToFormatted'), shortcut: "Ctrl+Shift+E", onClick: () => setMode(nextMode), children: mode === 'formatted' ? _jsx(SourceIcon, { size: 18 }) : _jsx(FormattedIcon, { size: 18 }) }), canEdit && (_jsx(AbBtn, { label: ribbonVisible ? t('appbar.hideToolbar') : t('appbar.showToolbar'), shortcut: "Ctrl+Shift+H", active: ribbonVisible, onClick: () => setRibbonVisible(!ribbonVisible), children: _jsx(RibbonIcon, { size: 18 }) })), speech && (_jsx(AbBtn, { label: "Voice Dictation", shortcut: "Ctrl+Shift+V", active: voiceActive, onClick: () => setVoiceActive(!voiceActive), children: _jsx(MicIcon, { size: 18 }) })), _jsx(AbBtn, { label: metadataVisible ? 'Hide Metadata' : 'Show Metadata', active: metadataVisible, onClick: () => setMetadataVisible(!metadataVisible), children: _jsx("span", { style: { fontWeight: 700, fontSize: '13px' }, children: "&" }) })] }), _jsx("span", { className: "cs-ab-spacer cs-ab-desktop-only" }), _jsxs("div", { className: "cs-ab-group cs-ab-desktop-group", children: [canEdit && (_jsxs(_Fragment, { children: [_jsx(AbBtn, { label: t('appbar.new'), onClick: handleNew, children: _jsx(NewIcon, { size: 18 }) }), _jsx(AbBtn, { label: t('appbar.open'), shortcut: "Ctrl+O", onClick: () => { void openFile(); }, children: _jsx(OpenIcon, { size: 18 }) }), _jsx(AbBtn, { label: t('appbar.importDocx'), onClick: () => { void handleImportDocx(); }, children: _jsx(ImportDocxIcon, { size: 18 }) }), ai && (_jsx(AbBtn, { label: "Import with AI", onClick: () => setAiImportOpen(true), children: _jsx(SparklesIcon, { size: 18 }) })), _jsx("span", { className: "cs-ab-sep" }), _jsx(AbBtn, { label: t('appbar.save'), shortcut: "Ctrl+S", variant: "primary", onClick: () => { void saveFile(); }, children: _jsx(SaveIcon, { size: 17 }) }), _jsx(AbBtn, { label: t('appbar.saveAs'), shortcut: "Ctrl+Shift+S", onClick: () => { void saveFileAs(); }, children: _jsx(SaveAsIcon, { size: 17 }) }), _jsx("span", { className: "cs-ab-sep" })] })), _jsx(AbBtn, { label: t('appbar.export'), variant: "secondary", active: exportVisible, onClick: () => setExportVisible(!exportVisible), children: _jsx(ExportIcon, { size: 18 }) }), canEdit && (_jsx(AbBtn, { label: t('appbar.style'), active: styleVisible, onClick: () => setStyleVisible(!styleVisible), children: _jsx(StyleIcon, { size: 18 }) })), (appbarCommands.length > 0 || appbarPanels.length > 0) && _jsx("span", { className: "cs-ab-sep" }), appbarCommands.map(c => (_jsx(AbBtn, { label: c.label, shortcut: displayShortcut(c.shortcut ?? c.shortcutHint), onClick: () => c.run(commandContext()), children: c.icon ? c.icon(18) : _jsx("span", { className: "cs-ab-text-label", children: c.label }) }, c.id))), appbarPanels.map(p => (_jsx("span", { className: "cs-ab-panel", "aria-label": p.title, children: p.render(panelContext) }, p.id))), _jsx(AbBtn, { label: t('settings.title'), active: settingsVisible, onClick: () => setSettingsVisible(!settingsVisible), children: _jsx(SettingsIcon, { size: 18 }) })] }), _jsxs("div", { className: "cs-ab-group cs-ab-mobile-controls", children: [canEdit && (_jsx(AbBtn, { label: t('appbar.save'), variant: isDirty ? 'primary' : undefined, onClick: () => { void saveFile(); }, children: _jsx(SaveIcon, { size: 17 }) })), _jsx(AbBtn, { label: "Menu", active: mobileMenuOpen, onClick: () => setMobileMenuOpen(!mobileMenuOpen), children: mobileMenuOpen ? _jsx(CloseIcon, { size: 18 }) : _jsx(MenuIcon, { size: 18 }) })] }), mobileMenuOpen && (_jsxs(_Fragment, { children: [_jsx("div", { className: "cs-mobile-menu-backdrop", "aria-hidden": "true", onClick: () => setMobileMenuOpen(false) }), _jsxs("div", { className: "cs-mobile-menu-drawer", role: "dialog", "aria-modal": "true", "aria-label": "Application Menu", children: [_jsxs("div", { className: "cs-mm-header", children: [_jsxs("div", { className: "cs-mm-brand", children: [_jsx(SutrataLogo, { size: 22, showText: false }), _jsx("span", { children: "Sutrata" })] }), _jsx("button", { type: "button", className: "cs-mm-close", "aria-label": "Close menu", onClick: () => setMobileMenuOpen(false), children: _jsx(CloseIcon, { size: 18 }) })] }), _jsxs("div", { className: "cs-mm-file-info", children: [_jsx("span", { className: "cs-mm-file-name", children: name }), isDirty && _jsx("span", { className: "cs-ab-dirty", title: "Unsaved edits" })] }), _jsxs("div", { className: "cs-mm-section", children: [_jsx("div", { className: "cs-mm-section-title", children: "Views & Tools" }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setMode(nextMode); setMobileMenuOpen(false); }, children: [mode === 'formatted' ? _jsx(SourceIcon, { size: 18 }) : _jsx(FormattedIcon, { size: 18 }), _jsx("span", { children: mode === 'formatted' ? t('appbar.switchToSource') : t('appbar.switchToFormatted') })] }), _jsxs("button", { type: "button", className: `cs-mm-item${navVisible ? ' cs-mm-active' : ''}`, onClick: () => { setNavVisible(!navVisible); setMobileMenuOpen(false); }, children: [_jsx(NavigatorIcon, { size: 18 }), _jsx("span", { children: t('appbar.navigator') })] }), canEdit && _jsxs("button", { type: "button", className: `cs-mm-item${ribbonVisible ? ' cs-mm-active' : ''}`, onClick: () => { setRibbonVisible(!ribbonVisible); setMobileMenuOpen(false); }, children: [_jsx(RibbonIcon, { size: 18 }), _jsx("span", { children: ribbonVisible ? t('appbar.hideToolbar') : t('appbar.showToolbar') })] }), speech && _jsxs("button", { type: "button", className: `cs-mm-item${voiceActive ? ' cs-mm-active' : ''}`, onClick: () => { setVoiceActive(!voiceActive); setMobileMenuOpen(false); }, children: [_jsx(MicIcon, { size: 18 }), _jsx("span", { children: "Voice Dictation" })] }), _jsxs("button", { type: "button", className: `cs-mm-item${metadataVisible ? ' cs-mm-active' : ''}`, onClick: () => { setMetadataVisible(!metadataVisible); setMobileMenuOpen(false); }, children: [_jsx("span", { style: { fontWeight: 700, width: 18, textAlign: 'center' }, children: "&" }), _jsx("span", { children: metadataVisible ? 'Hide Metadata' : 'Show Metadata' })] })] }), canEdit && _jsxs("div", { className: "cs-mm-section", children: [_jsx("div", { className: "cs-mm-section-title", children: "File Operations" }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { openTitlePageForm(); setMobileMenuOpen(false); }, children: [_jsx(TitlePageIcon, { size: 18 }), _jsx("span", { children: t('appbar.titlePage') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { handleNew(); setMobileMenuOpen(false); }, children: [_jsx(NewIcon, { size: 18 }), _jsx("span", { children: t('appbar.new') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { void openFile(); setMobileMenuOpen(false); }, children: [_jsx(OpenIcon, { size: 18 }), _jsx("span", { children: t('appbar.open') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { void handleImportDocx(); setMobileMenuOpen(false); }, children: [_jsx(ImportDocxIcon, { size: 18 }), _jsx("span", { children: t('appbar.importDocx') })] }), ai && _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setAiImportOpen(true); setMobileMenuOpen(false); }, children: [_jsx(SparklesIcon, { size: 18 }), _jsx("span", { children: "Import with AI" })] }), _jsxs("button", { type: "button", className: "cs-mm-item cs-mm-primary", onClick: () => { void saveFile(); setMobileMenuOpen(false); }, children: [_jsx(SaveIcon, { size: 18 }), _jsx("span", { children: t('appbar.save') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { void saveFileAs(); setMobileMenuOpen(false); }, children: [_jsx(SaveAsIcon, { size: 18 }), _jsx("span", { children: t('appbar.saveAs') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setExportVisible(true); setMobileMenuOpen(false); }, children: [_jsx(ExportIcon, { size: 18 }), _jsx("span", { children: t('appbar.export') })] })] }), !canEdit && _jsx("div", { className: "cs-mm-section", children: _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setExportVisible(true); setMobileMenuOpen(false); }, children: [_jsx(ExportIcon, { size: 18 }), _jsx("span", { children: t('appbar.export') })] }) }), appbarCommands.length > 0 && _jsx("div", { className: "cs-mm-section", children: appbarCommands.map(c => (_jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { c.run(commandContext()); setMobileMenuOpen(false); }, children: [c.icon?.(18), _jsx("span", { children: c.label })] }, c.id))) }), _jsxs("div", { className: "cs-mm-section", children: [_jsx("div", { className: "cs-mm-section-title", children: "Preferences" }), canEdit && _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setStyleVisible(true); setMobileMenuOpen(false); }, children: [_jsx(StyleIcon, { size: 18 }), _jsx("span", { children: t('appbar.style') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setSettingsVisible(true); setMobileMenuOpen(false); }, children: [_jsx(SettingsIcon, { size: 18 }), _jsx("span", { children: t('settings.title') })] })] })] })] })), aiImportOpen && _jsx(AIImportDialog, { onClose: () => setAiImportOpen(false) })] }));
+    return (_jsxs("header", { className: "cs-app-bar", role: "banner", "aria-label": "Application header", children: [_jsxs("div", { className: "cs-ab-group cs-ab-left", children: [_jsxs("div", { className: "cs-ab-brand", title: "Sutrata Multilingual Screenplay Editor", children: [_jsx(SutrataLogo, { size: 20, showText: false }), _jsx("span", { className: "cs-ab-brand-title", children: "Sutrata" })] }), _jsx("span", { className: "cs-ab-sep cs-ab-desktop-only" }), _jsx(AbBtn, { label: t('appbar.navigator'), shortcut: "Ctrl+Shift+B", active: navVisible, onClick: () => setNavVisible(!navVisible), children: _jsx(NavigatorIcon, { size: 18 }) }), canEdit && (_jsx("span", { className: "cs-ab-desktop-only", children: _jsx(AbBtn, { label: t('appbar.titlePage'), onClick: openTitlePageForm, children: _jsx(TitlePageIcon, { size: 18 }) }) })), _jsxs("div", { className: "cs-ab-file-pill", title: name, children: [_jsx("span", { className: "cs-ab-file-name", children: name }), isDirty && _jsx("span", { className: "cs-ab-dirty", title: "Unsaved edits" })] })] }), _jsx("span", { className: "cs-ab-spacer cs-ab-desktop-only" }), _jsxs("div", { className: "cs-ab-group cs-ab-desktop-group", children: [_jsx(AbBtn, { label: mode === 'formatted' ? t('appbar.switchToSource') : t('appbar.switchToFormatted'), shortcut: "Ctrl+Shift+E", onClick: () => setMode(nextMode), children: mode === 'formatted' ? _jsx(SourceIcon, { size: 18 }) : _jsx(FormattedIcon, { size: 18 }) }), canEdit && (_jsx(AbBtn, { label: ribbonVisible ? t('appbar.hideToolbar') : t('appbar.showToolbar'), shortcut: "Ctrl+Shift+H", active: ribbonVisible, onClick: () => setRibbonVisible(!ribbonVisible), children: _jsx(RibbonIcon, { size: 18 }) })), speech && (_jsx(AbBtn, { label: "Voice Dictation", shortcut: "Ctrl+Shift+V", active: voiceActive, onClick: () => setVoiceActive(!voiceActive), children: _jsx(MicIcon, { size: 18 }) })), _jsx(AbBtn, { label: metadataVisible ? 'Hide Metadata' : 'Show Metadata', active: metadataVisible, onClick: () => setMetadataVisible(!metadataVisible), children: _jsx("span", { style: { fontWeight: 700, fontSize: '13px' }, children: "&" }) })] }), _jsx("span", { className: "cs-ab-spacer cs-ab-desktop-only" }), _jsxs("div", { className: "cs-ab-group cs-ab-desktop-group", children: [canEdit && (_jsxs(_Fragment, { children: [localFiles && (_jsxs(_Fragment, { children: [_jsx(AbBtn, { label: t('appbar.new'), onClick: handleNew, children: _jsx(NewIcon, { size: 18 }) }), _jsx(AbBtn, { label: t('appbar.open'), shortcut: "Ctrl+O", onClick: () => { void openFile(); }, children: _jsx(OpenIcon, { size: 18 }) })] })), _jsx(AbBtn, { label: t('appbar.importDocx'), onClick: () => { void handleImportDocx(); }, children: _jsx(ImportDocxIcon, { size: 18 }) }), ai && (_jsx(AbBtn, { label: "Import with AI", onClick: () => setAiImportOpen(true), children: _jsx(SparklesIcon, { size: 18 }) })), _jsx("span", { className: "cs-ab-sep" }), _jsx(AbBtn, { label: t('appbar.save'), shortcut: "Ctrl+S", variant: "primary", onClick: () => { void saveFile(); }, children: _jsx(SaveIcon, { size: 17 }) }), localFiles && (_jsx(AbBtn, { label: t('appbar.saveAs'), shortcut: "Ctrl+Shift+S", onClick: () => { void saveFileAs(); }, children: _jsx(SaveAsIcon, { size: 17 }) })), _jsx("span", { className: "cs-ab-sep" })] })), _jsx(AbBtn, { label: t('appbar.export'), variant: "secondary", active: exportVisible, onClick: () => setExportVisible(!exportVisible), children: _jsx(ExportIcon, { size: 18 }) }), canEdit && (_jsx(AbBtn, { label: t('appbar.style'), active: styleVisible, onClick: () => setStyleVisible(!styleVisible), children: _jsx(StyleIcon, { size: 18 }) })), (appbarCommands.length > 0 || appbarPanels.length > 0) && _jsx("span", { className: "cs-ab-sep" }), appbarCommands.map(c => (_jsx(AbBtn, { label: c.label, shortcut: displayShortcut(c.shortcut ?? c.shortcutHint), onClick: () => c.run(commandContext()), children: c.icon ? c.icon(18) : _jsx("span", { className: "cs-ab-text-label", children: c.label }) }, c.id))), appbarPanels.map(p => (_jsx("span", { className: "cs-ab-panel", "aria-label": p.title, children: p.render(panelContext) }, p.id))), _jsx(AbBtn, { label: t('settings.title'), active: settingsVisible, onClick: () => setSettingsVisible(!settingsVisible), children: _jsx(SettingsIcon, { size: 18 }) })] }), _jsxs("div", { className: "cs-ab-group cs-ab-mobile-controls", children: [appbarPanels.map(p => (_jsx("span", { className: "cs-ab-panel", "aria-label": p.title, children: p.render(panelContext) }, p.id))), canEdit && (_jsx(AbBtn, { label: t('appbar.save'), variant: isDirty ? 'primary' : undefined, onClick: () => { void saveFile(); }, children: _jsx(SaveIcon, { size: 17 }) })), _jsx(AbBtn, { label: "Menu", active: mobileMenuOpen, onClick: () => setMobileMenuOpen(!mobileMenuOpen), children: mobileMenuOpen ? _jsx(CloseIcon, { size: 18 }) : _jsx(MenuIcon, { size: 18 }) })] }), mobileMenuOpen && (_jsxs(_Fragment, { children: [_jsx("div", { className: "cs-mobile-menu-backdrop", "aria-hidden": "true", onClick: () => setMobileMenuOpen(false) }), _jsxs("div", { className: "cs-mobile-menu-drawer", role: "dialog", "aria-modal": "true", "aria-label": "Application Menu", children: [_jsxs("div", { className: "cs-mm-header", children: [_jsxs("div", { className: "cs-mm-brand", children: [_jsx(SutrataLogo, { size: 22, showText: false }), _jsx("span", { children: "Sutrata" })] }), _jsx("button", { type: "button", className: "cs-mm-close", "aria-label": "Close menu", onClick: () => setMobileMenuOpen(false), children: _jsx(CloseIcon, { size: 18 }) })] }), _jsxs("div", { className: "cs-mm-file-info", children: [_jsx("span", { className: "cs-mm-file-name", children: name }), isDirty && _jsx("span", { className: "cs-ab-dirty", title: "Unsaved edits" })] }), _jsxs("div", { className: "cs-mm-section", children: [_jsx("div", { className: "cs-mm-section-title", children: "Views & Tools" }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setMode(nextMode); setMobileMenuOpen(false); }, children: [mode === 'formatted' ? _jsx(SourceIcon, { size: 18 }) : _jsx(FormattedIcon, { size: 18 }), _jsx("span", { children: mode === 'formatted' ? t('appbar.switchToSource') : t('appbar.switchToFormatted') })] }), _jsxs("button", { type: "button", className: `cs-mm-item${navVisible ? ' cs-mm-active' : ''}`, onClick: () => { setNavVisible(!navVisible); setMobileMenuOpen(false); }, children: [_jsx(NavigatorIcon, { size: 18 }), _jsx("span", { children: t('appbar.navigator') })] }), canEdit && _jsxs("button", { type: "button", className: `cs-mm-item${ribbonVisible ? ' cs-mm-active' : ''}`, onClick: () => { setRibbonVisible(!ribbonVisible); setMobileMenuOpen(false); }, children: [_jsx(RibbonIcon, { size: 18 }), _jsx("span", { children: ribbonVisible ? t('appbar.hideToolbar') : t('appbar.showToolbar') })] }), speech && _jsxs("button", { type: "button", className: `cs-mm-item${voiceActive ? ' cs-mm-active' : ''}`, onClick: () => { setVoiceActive(!voiceActive); setMobileMenuOpen(false); }, children: [_jsx(MicIcon, { size: 18 }), _jsx("span", { children: "Voice Dictation" })] }), _jsxs("button", { type: "button", className: `cs-mm-item${metadataVisible ? ' cs-mm-active' : ''}`, onClick: () => { setMetadataVisible(!metadataVisible); setMobileMenuOpen(false); }, children: [_jsx("span", { style: { fontWeight: 700, width: 18, textAlign: 'center' }, children: "&" }), _jsx("span", { children: metadataVisible ? 'Hide Metadata' : 'Show Metadata' })] })] }), canEdit && _jsxs("div", { className: "cs-mm-section", children: [_jsx("div", { className: "cs-mm-section-title", children: "File Operations" }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { openTitlePageForm(); setMobileMenuOpen(false); }, children: [_jsx(TitlePageIcon, { size: 18 }), _jsx("span", { children: t('appbar.titlePage') })] }), localFiles && _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { handleNew(); setMobileMenuOpen(false); }, children: [_jsx(NewIcon, { size: 18 }), _jsx("span", { children: t('appbar.new') })] }), localFiles && _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { void openFile(); setMobileMenuOpen(false); }, children: [_jsx(OpenIcon, { size: 18 }), _jsx("span", { children: t('appbar.open') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { void handleImportDocx(); setMobileMenuOpen(false); }, children: [_jsx(ImportDocxIcon, { size: 18 }), _jsx("span", { children: t('appbar.importDocx') })] }), ai && _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setAiImportOpen(true); setMobileMenuOpen(false); }, children: [_jsx(SparklesIcon, { size: 18 }), _jsx("span", { children: "Import with AI" })] }), _jsxs("button", { type: "button", className: "cs-mm-item cs-mm-primary", onClick: () => { void saveFile(); setMobileMenuOpen(false); }, children: [_jsx(SaveIcon, { size: 18 }), _jsx("span", { children: t('appbar.save') })] }), localFiles && _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { void saveFileAs(); setMobileMenuOpen(false); }, children: [_jsx(SaveAsIcon, { size: 18 }), _jsx("span", { children: t('appbar.saveAs') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setExportVisible(true); setMobileMenuOpen(false); }, children: [_jsx(ExportIcon, { size: 18 }), _jsx("span", { children: t('appbar.export') })] })] }), !canEdit && _jsx("div", { className: "cs-mm-section", children: _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setExportVisible(true); setMobileMenuOpen(false); }, children: [_jsx(ExportIcon, { size: 18 }), _jsx("span", { children: t('appbar.export') })] }) }), appbarCommands.length > 0 && _jsx("div", { className: "cs-mm-section", children: appbarCommands.map(c => (_jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { c.run(commandContext()); setMobileMenuOpen(false); }, children: [c.icon?.(18), _jsx("span", { children: c.label })] }, c.id))) }), _jsxs("div", { className: "cs-mm-section", children: [_jsx("div", { className: "cs-mm-section-title", children: "Preferences" }), canEdit && _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setStyleVisible(true); setMobileMenuOpen(false); }, children: [_jsx(StyleIcon, { size: 18 }), _jsx("span", { children: t('appbar.style') })] }), _jsxs("button", { type: "button", className: "cs-mm-item", onClick: () => { setSettingsVisible(true); setMobileMenuOpen(false); }, children: [_jsx(SettingsIcon, { size: 18 }), _jsx("span", { children: t('settings.title') })] })] })] })] })), aiImportOpen && _jsx(AIImportDialog, { onClose: () => setAiImportOpen(false) })] }));
 }

package/dist/source/SourceView.js

@@ -1,13 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef } from 'react';
-import { Annotation, Compartment, EditorState } from '@codemirror/state';
+import { Annotation, Compartment, EditorState, Transaction } from '@codemirror/state';
 import { EditorView, keymap } from '@codemirror/view';
 import { defaultKeymap, history, historyKeymap } from '@codemirror/commands';
 import { HighlightStyle, syntaxHighlighting } from '@codemirror/language';
 import { tags } from '@lezer/highlight';
 import { sutraLanguage } from './sutra-lang';
 import { useDocument } from '../context/DocumentContext';
-import { setSourceView } from '../editor/editor-bus';
+import { setSourceView, takeExternalText } from '../editor/editor-bus';
 import { sourceFindHighlightExtension } from './find-highlight-source';
 import { useCanEdit } from '../extensions/session';
 /** Marks the transaction that mirrors an external text change into the view. */
@@ -84,7 +84,8 @@ export function SourceView() {
                     editableCompartment.current.of([EditorView.editable.of(canEdit), EditorState.readOnly.of(!canEdit)]),
                     EditorState.transactionFilter.of(tr => tr.docChanged && !canEditRef.current && !tr.annotation(externalSync) ? [] : tr),
                     EditorView.updateListener.of(update => {
-                        if (update.docChanged) {
+                        // Mirrored text (externalSync) is already the document's text.
+                        if (update.docChanged && !update.transactions.some(t => t.annotation(externalSync))) {
                             const newText = update.state.doc.toString();
                             lastTextRef.current = newText;
                             setText(newText);
@@ -109,6 +110,24 @@ export function SourceView() {
         if (!view || text === lastTextRef.current)
             return;
         lastTextRef.current = text;
+        if (takeExternalText(text)) {
+            // From storage: change only what differs, keep the cursor, not undoable.
+            const old = view.state.doc.toString();
+            let from = 0;
+            while (from < old.length && from < text.length && old[from] === text[from])
+                from++;
+            let endOld = old.length;
+            let endNew = text.length;
+            while (endOld > from && endNew > from && old[endOld - 1] === text[endNew - 1]) {
+                endOld--;
+                endNew--;
+            }
+            view.dispatch({
+                changes: { from, to: endOld, insert: text.slice(from, endNew) },
+                annotations: [externalSync.of(true), Transaction.addToHistory.of(false)],
+            });
+            return;
+        }
         view.dispatch({
             changes: { from: 0, to: view.state.doc.length, insert: text },
             annotations: externalSync.of(true),

package/dist/source/find-highlight-source.d.ts

@@ -11,4 +11,4 @@ export declare function setSourceFindHighlights(matches: SourceMatch[], activeIn
 /** Called by FindReplace when the panel closes — clears all source-view highlights. */
 export declare function clearSourceFindHighlights(): void;
 /** Scroll the source view so the given match is visible. */
-export declare function scrollToSourceMatch(match: SourceMatch): void;
+export declare function scrollToSourceMatch(match: SourceMatch, center?: boolean): void;

package/dist/source/find-highlight-source.js

@@ -39,9 +39,10 @@ export function clearSourceFindHighlights() {
     setSourceFindHighlights([], 0);
 }
 /** Scroll the source view so the given match is visible. */
-export function scrollToSourceMatch(match) {
+export function scrollToSourceMatch(match, center = true) {
     const view = getSourceView();
     if (!view)
         return;
-    view.dispatch({ effects: EditorView.scrollIntoView(match.start, { y: 'center' }) });
+    // 'nearest' only scrolls when the match is off-screen (used while typing).
+    view.dispatch({ effects: EditorView.scrollIntoView(match.start, { y: center ? 'center' : 'nearest' }) });
 }

package/dist/styles/screenplay.css

@@ -508,7 +508,8 @@ html, body, #root { height: 100%; margin: 0; padding: 0; overflow: hidden; }
 }
 
 /* Tool-private `x-` keys (format spec §7.1) stay in the text but are not shown */
-.cs-scene-metadata[data-private] {
+.cs-scene-metadata[data-private],
+.cs-fm-field[data-private] {
   display: none;
 }
 
@@ -3116,3 +3117,15 @@ html, body, #root { height: 100%; margin: 0; padding: 0; overflow: hidden; }
   color: var(--cs-ui-warning, #c2410c); background: var(--cs-ui-warning-subtle, #fff7ed);
   user-select: none; vertical-align: middle;
 }
+
+/* Section headings (acts, sequences) shown as anchors in the navigator. */
+.cs-nav-section-anchor {
+  background: var(--cs-ui-bg-panel-subtle, #f4f2ea);
+  border-bottom: 1px solid var(--cs-ui-border-light, #e2e0d6);
+}
+.cs-nav-section-anchor .cs-nav-heading {
+  font-weight: 700;
+  text-transform: uppercase;
+  font-size: 11px;
+  letter-spacing: 0.04em;
+}

package/dist/titlepage/frontmatter-form.js

@@ -87,7 +87,7 @@ export function readTitlePage(data) {
     f.watermark = str(data['watermark']);
     const managed = new Set(MANAGED_KEYS);
     for (const [key, value] of Object.entries(data)) {
-        if (managed.has(key) || HIDDEN_KEYS.has(key))
+        if (managed.has(key) || HIDDEN_KEYS.has(key) || key.startsWith('x-'))
             continue;
         if (typeof value === 'string' && !value.includes('\n'))
             f.custom.push({ key, value });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sutrata/editor",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "React + ProseMirror screenplay editor for Sutra, with first-class support for Indic and other complex scripts.",
   "license": "GPL-3.0-or-later",
   "keywords": [
@@ -46,7 +46,7 @@
     "prosemirror-state": "^1.4.3",
     "prosemirror-transform": "^1.9.0",
     "prosemirror-view": "^1.33.0",
-    "@sutrata/parser": "0.2.0"
+    "@sutrata/parser": "0.3.0"
   },
   "peerDependencies": {
     "react": "^18.3.0",