@sutrata/editor 0.1.2 → 0.3.0

package/dist/context/DocumentContext.js

@@ -2,10 +2,22 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useState, useCallback, useEffect, useMemo, useRef } from 'react';
 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, 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';
+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 { runCommand, getEditorView } 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 { makeSetBlock, makeSetOrToggleNote } from '../shell/toolbar-actions';
+import { builtinCommands } from '../shell/builtin-commands';
 import { resolveStyle } from '../styles/registry';
 const DocumentContext = createContext(null);
 const EMPTY_DOC = '## Scene 1\n\nAction.\n';
@@ -48,11 +60,30 @@ function clearRecoveryPointer() {
         // ignore
     }
 }
-export function DocumentProvider({ children, storageAdapter }) {
+const NO_DECORATIONS = [];
+/** A registry prop as a registry: a fixed list becomes a registry of its own. */
+function useRegistryProp(value, create) {
+    return useMemo(() => (Array.isArray(value) || !value ? create(value ?? []) : value), [value]); // eslint-disable-line react-hooks/exhaustive-deps
+}
+export function DocumentProvider({ children, storageAdapter, aiProvider, speechProvider, session, panels, commands, exporters, decorationProviders, collabBinding, }) {
+    const panelRegistry = useRegistryProp(panels, createPanelRegistry);
+    const commandRegistry = useRegistryProp(commands, createCommandRegistry);
+    const exportRegistry = useRegistryProp(exporters, createExportRegistry);
     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
@@ -64,7 +95,6 @@ export function DocumentProvider({ children, storageAdapter }) {
     const [navVisible, setNavVisible] = useState(() => window.innerWidth > 640);
     const [exportVisible, setExportVisible] = useState(false);
     const [settingsVisible, setSettingsVisible] = useState(false);
-    const [aiOnboardingVisible, setAIOnboardingVisible] = useState(false);
     const [voiceActive, setVoiceActive] = useState(false);
     const [metadataVisible, setMetadataVisible] = useState(true);
     const [findReplaceVisible, setFindReplaceVisible] = useState(false);
@@ -112,10 +142,15 @@ export function DocumentProvider({ children, storageAdapter }) {
         }
     }, [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;
@@ -143,10 +178,18 @@ export function DocumentProvider({ children, storageAdapter }) {
         })();
         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'];
@@ -157,19 +200,48 @@ export function DocumentProvider({ children, storageAdapter }) {
         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 filePathRef = useRef(filePath);
-    useEffect(() => { filePathRef.current = filePath; }, [filePath]);
+    const modeRef = useRef(mode);
+    modeRef.current = mode;
     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
@@ -189,7 +261,20 @@ export function DocumentProvider({ children, storageAdapter }) {
                 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) {
@@ -224,6 +309,8 @@ export function DocumentProvider({ children, storageAdapter }) {
         });
     }, [isDirty, showConfirm]);
     const openFile = useCallback(async () => {
+        if (!localFilesRef.current)
+            return;
         const doOpen = async () => {
             const result = await storageAdapter.openFile();
             if (!result)
@@ -306,6 +393,8 @@ export function DocumentProvider({ children, storageAdapter }) {
         }
     }, [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) {
@@ -441,10 +530,36 @@ export function DocumentProvider({ children, storageAdapter }) {
         window.addEventListener('beforeunload', onBeforeUnload);
         return () => window.removeEventListener('beforeunload', onBeforeUnload);
     }, [isDirty]);
+    const canEditRef = useRef(true);
+    canEditRef.current = (session ?? DEFAULT_SESSION).permission === 'edit';
     useEffect(() => {
         const onKeyDown = (e) => {
             const mod = e.ctrlKey || e.metaKey;
             const cs = mod && e.shiftKey;
+            // Read-only sessions: only find, mode and panel toggles.
+            if (!canEditRef.current) {
+                if (mod && !e.shiftKey && !e.altKey && e.code === 'KeyF') {
+                    e.preventDefault();
+                    setFindMode('find');
+                    setFindReplaceVisible(v => !v);
+                }
+                else if (cs && !e.altKey && e.code === 'KeyE') {
+                    e.preventDefault();
+                    setMode(m => m === 'formatted' ? 'source' : 'formatted');
+                }
+                else if (cs && !e.altKey && e.code === 'KeyB') {
+                    e.preventDefault();
+                    setNavVisible(v => !v);
+                }
+                else {
+                    const cmd = commandRegistry.list().find(c => c.readOnly && c.shortcut && matchesShortcut(c.shortcut, e));
+                    if (cmd) {
+                        e.preventDefault();
+                        cmd.run({ view: getEditorView(), sourceView: getSourceView(), mode: modeRef.current, text: textRef.current, setText });
+                    }
+                }
+                return;
+            }
             // File operations — use e.code for layout-independence
             if (mod && !e.shiftKey && !e.altKey && e.code === 'KeyS') {
                 e.preventDefault();
@@ -468,27 +583,13 @@ export function DocumentProvider({ children, storageAdapter }) {
                 setFindReplaceVisible(true);
                 return;
             }
-            // Block type shortcuts  Alt+Shift+letter
-            if (e.altKey && e.shiftKey && !mod) {
-                if (e.code === 'KeyN') {
-                    e.preventDefault();
-                    runCommand(makeSetOrToggleNote());
-                    return;
-                }
-                const blockMap = {
-                    'KeyH': ['scene_heading', { id: null }],
-                    'KeyA': ['action'],
-                    'KeyC': ['character', { extension: null, isDual: false }],
-                    'KeyD': ['dialogue'],
-                    'KeyP': ['parenthetical'],
-                    'KeyX': ['transition'],
-                };
-                if (e.code in blockMap) {
-                    e.preventDefault();
-                    const [type, attrs] = blockMap[e.code];
-                    runCommand(makeSetBlock(type, attrs ?? {}));
-                    return;
-                }
+            // Command shortcuts (built-in element types, embedder commands)
+            const cmd = withBuiltins(builtinCommands(k => k), commandRegistry.list())
+                .find(c => c.shortcut && matchesShortcut(c.shortcut, e));
+            if (cmd) {
+                e.preventDefault();
+                cmd.run({ view: getEditorView(), sourceView: getSourceView(), mode: modeRef.current, text: textRef.current, setText });
+                return;
             }
             // UI toggles  Ctrl+Shift+letter
             if (cs && !e.altKey) {
@@ -511,7 +612,7 @@ export function DocumentProvider({ children, storageAdapter }) {
         };
         window.addEventListener('keydown', onKeyDown);
         return () => window.removeEventListener('keydown', onKeyDown);
-    }, [saveFile, openFile]);
+    }, [saveFile, openFile, commandRegistry, setText]);
     // Native menu IPC (Desktop wrapper only) — receives commands from the main process menu
     useEffect(() => {
         const api = window.desktopAPI;
@@ -585,17 +686,17 @@ export function DocumentProvider({ children, storageAdapter }) {
         });
         return off;
     }, [saveFile, showConfirm]);
-    return (_jsx(StorageAdapterProvider, { value: storageAdapter, children: _jsx(DocumentContext.Provider, { value: {
-                text, ast, mode, filePath, isDirty, lastSaveTarget, ribbonVisible, navVisible, exportVisible, settingsVisible,
-                aiOnboardingVisible, voiceActive, metadataVisible,
-                findReplaceVisible, findMode, styleVisible, customStyles, resolvedStyle, watermarkText,
-                confirmModal, toasts, versions, versionHistoryVisible,
-                setText, setMode, setFilePath, setRibbonVisible, setNavVisible, setExportVisible, setSettingsVisible,
-                setAIOnboardingVisible, setVoiceActive, setMetadataVisible,
-                setFindReplaceVisible, setFindMode, setStyleVisible, setVersionHistoryVisible, setDocumentStyle, reloadCustomStyles,
-                markClean, save, newDocument, openFile, saveFile, saveFileAs, importDocx, restoreVersion, clearVersionHistory,
-                showConfirm, closeConfirm, showToast, dismissToast,
-            }, children: children }) }));
+    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, fileDisplayName, isDirty, lastSaveTarget, ribbonVisible, navVisible, exportVisible, settingsVisible,
+                                                voiceActive, metadataVisible,
+                                                findReplaceVisible, findMode, styleVisible, customStyles, resolvedStyle, watermarkText,
+                                                confirmModal, toasts, versions, versionHistoryVisible,
+                                                setText, setMode, setFilePath, setRibbonVisible, setNavVisible, setExportVisible, setSettingsVisible,
+                                                setVoiceActive, setMetadataVisible,
+                                                setFindReplaceVisible, setFindMode, setStyleVisible, setVersionHistoryVisible, setDocumentStyle, reloadCustomStyles,
+                                                markClean, save, newDocument, openFile, saveFile, saveFileAs, importDocx, restoreVersion, clearVersionHistory,
+                                                showConfirm, closeConfirm, showToast, dismissToast,
+                                            }, children: children }) }) }) }) }) }) }) }) }) }));
 }
 export function useDocument() {
     const ctx = useContext(DocumentContext);

package/dist/editor/EditorView.js

@@ -12,8 +12,29 @@ import { useDocument } from '../context/DocumentContext';
 import { SceneHeadingView } from './scene-heading-view';
 import { FrontmatterFieldView } from './frontmatter-field-view';
 import { applyStyleVars } from '../styles/css-adapter';
+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, setText, resolvedStyle } = useDocument();
+    const { text, ast, setText, resolvedStyle } = useDocument();
+    const astRef = useRef(ast);
+    astRef.current = ast;
+    // Embedder decorations and collab plugins join the built-in ones every time
+    // the state is (re)created. Both are read once per state: pass stable values.
+    const decorationProviders = useDecorationProviders();
+    const collab = useCollabBinding();
+    const plugins = () => [
+        ...buildPlugins(),
+        ...(decorationProviders.length > 0 ? [createExternalDecorationsPlugin(decorationProviders, () => astRef.current)] : []),
+        ...(collab ? collab.plugins(schema) : []),
+    ];
+    // Read-only sessions: not editable, and every doc-changing transaction —
+    // typed, or dispatched by a toolbar/navigator/node view — is dropped here.
+    const canEdit = useCanEdit();
+    const canEditRef = useRef(canEdit);
+    canEditRef.current = canEdit;
     const mountRef = useRef(null);
     const viewRef = useRef(null);
     const textRef = useRef(text);
@@ -26,21 +47,25 @@ export function EditorView() {
         if (!mountRef.current)
             return;
         const doc = sutraToProsemirror(parse(textRef.current));
-        const state = EditorState.create({ doc, schema, plugins: buildPlugins() });
+        const state = EditorState.create({ doc, schema, plugins: plugins() });
         const view = new PmEditorView(mountRef.current, {
             state,
             nodeViews: {
                 scene_heading: (node, view, getPos) => new SceneHeadingView(node, view, getPos),
                 frontmatter_field: (node, view, getPos) => new FrontmatterFieldView(node, view, getPos),
             },
+            editable: () => canEditRef.current,
             dispatchTransaction(tr) {
+                if (tr.docChanged && !canEditRef.current && !tr.getMeta(EXTERNAL_CHANGE))
+                    return;
                 const newState = view.state.apply(tr);
                 view.updateState(newState);
                 if (tr.docChanged) {
                     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();
@@ -48,7 +73,8 @@ export function EditorView() {
         });
         viewRef.current = view;
         setEditorView(view);
-        return () => { setEditorView(null); view.destroy(); viewRef.current = null; };
+        const detachCollab = collab?.attach(view);
+        return () => { detachCollab?.(); setEditorView(null); view.destroy(); viewRef.current = null; };
     }, []); // eslint-disable-line react-hooks/exhaustive-deps
     // Sync external text changes into ProseMirror (e.g. switching from source mode).
     // Skip when the editor itself produced the change — it already has the right state.
@@ -63,10 +89,14 @@ export function EditorView() {
         const currentText = prosemirrorToSutra(view.state.doc);
         if (currentText !== text) {
             const doc = sutraToProsemirror(parse(text));
-            const state = EditorState.create({ doc, schema, plugins: buildPlugins() });
+            const state = EditorState.create({ doc, schema, plugins: plugins() });
             view.updateState(state);
         }
     }, [text]);
+    // Re-evaluate `editable` when the session's permission changes.
+    useEffect(() => {
+        viewRef.current?.setProps({});
+    }, [canEdit]);
     // Apply the document's resolved style as CSS custom properties on the mount element.
     // Works identically for built-in and user-imported styles — both are plain
     // ScreenplayStyleDefinition objects by the time they reach here.

package/dist/editor/SelectionMenu.js

@@ -1,10 +1,11 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState, useEffect } from 'react';
 import { useLanguage } from '../i18n/LanguageContext';
 import { useDocument } from '../context/DocumentContext';
 import { insertSutra } from './insert-helper';
 import { VoiceConfirmDialog } from '../ai/VoiceConfirmDialog';
 import { SparklesIcon } from '../shell/icons';
+import { useAI } from '../extensions/ai-provider';
 const VOICE_LANG_MAP = {
     en: 'en-US',
     hi: 'hi-IN',
@@ -34,6 +35,7 @@ function isSelectionInEditor(sel) {
 export function SelectionMenu() {
     const { currentLanguage } = useLanguage();
     const { mode } = useDocument();
+    const ai = useAI();
     const [menuPosition, setMenuPosition] = useState(null);
     const [selectedText, setSelectedText] = useState('');
     const [showConfirm, setShowConfirm] = useState(false);
@@ -84,7 +86,7 @@ export function SelectionMenu() {
         setShowConfirm(true);
         setMenuPosition(null);
     };
-    if (showConfirm) {
+    if (showConfirm && ai) {
         const langCode = VOICE_LANG_MAP[currentLanguage] || 'en-US';
         return (_jsx(VoiceConfirmDialog, { rawTranscript: selectedText, langCode: langCode, onConfirm: (formattedText) => {
                 insertSutra(formattedText, mode);
@@ -98,5 +100,5 @@ export function SelectionMenu() {
     return (_jsxs("div", { className: "cs-selection-menu", style: {
             left: `${menuPosition.x}px`,
             top: `${menuPosition.y}px`,
-        }, role: "toolbar", "aria-label": "Text Selection Actions", children: [_jsxs("button", { type: "button", className: "cs-selection-btn cs-selection-btn-format", onClick: handleFormat, title: "Format selected text using AI", children: [_jsx(SparklesIcon, { size: 12 }), _jsx("span", { children: "Format" })] }), _jsx("div", { className: "cs-selection-sep" }), _jsx("button", { type: "button", className: "cs-selection-btn", onClick: handleCut, children: "Cut" }), _jsx("button", { type: "button", className: "cs-selection-btn", onClick: handleCopy, children: "Copy" })] }));
+        }, role: "toolbar", "aria-label": "Text Selection Actions", children: [ai && (_jsxs(_Fragment, { children: [_jsxs("button", { type: "button", className: "cs-selection-btn cs-selection-btn-format", onClick: handleFormat, title: "Format selected text using AI", children: [_jsx(SparklesIcon, { size: 12 }), _jsx("span", { children: "Format" })] }), _jsx("div", { className: "cs-selection-sep" })] })), _jsx("button", { type: "button", className: "cs-selection-btn", onClick: handleCut, children: "Cut" }), _jsx("button", { type: "button", className: "cs-selection-btn", onClick: handleCopy, children: "Copy" })] }));
 }

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/external-decorations-plugin.d.ts

@@ -0,0 +1,23 @@
+import { Plugin, PluginKey } from 'prosemirror-state';
+import { DecorationSet } from 'prosemirror-view';
+import type { Node as PmNode } from 'prosemirror-model';
+import type { DocumentNode } from '@sutrata/parser';
+import type { DecorationProvider } from '../extensions/decorations';
+/**
+ * Renders DecorationProvider output (extensions/decorations.ts) in the
+ * formatted editor. Anchors are { sceneId, from?, to? } with offsets into the
+ * scene's text; this plugin maps them to document positions, recomputes on
+ * every document change and whenever a provider signals a change, and routes
+ * clicks on decorated elements to the spec's onClick (in any session mode).
+ */
+export declare const externalDecorationsKey: PluginKey<DecorationSet>;
+interface SceneRange {
+    from: number;
+    to: number;
+}
+/** Top-level position range of every scene with an id, heading through the block before the next heading. */
+export declare function sceneRanges(doc: PmNode): Map<string, SceneRange>;
+/** Scene text as anchors see it: blocks joined with '\n', line breaks as '\n'. */
+export declare function textOf(doc: PmNode, range: SceneRange, to?: number): string;
+export declare function createExternalDecorationsPlugin(providers: readonly DecorationProvider[], getAst: () => DocumentNode): Plugin<DecorationSet>;
+export {};