@sutrata/editor 0.2.0 → 0.3.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/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/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/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;
 }
 

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.3.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",