@sutrata/editor 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,87 @@
+# @sutrata/editor
+
+The React screenplay editor behind [Sutrata](https://github.com/sutrata/sutrata), for writing scripts in **Sutra**, a plain-text screenplay format for world languages. It's built on ProseMirror and handles Indic and other complex scripts properly:
+- Text is stored in logical order.
+- The cursor and selection move by grapheme cluster (user-perceived character).
+- Find/replace matches after NFC normalization, so differently encoded forms of the same text still match.
+
+This package contains the complete editor:
+- WYSIWYG and source modes, with smart Enter that cycles through screenplay elements.
+- A scene navigator, find/replace, a title-page form and screenplay styles.
+- Statistics, autocomplete and spellcheck.
+- Export to PDF, DOCX, Fountain and workflow reports, including romanized exports.
+- Localized UI.
+
+Sutra parsing and serialization come from [`@sutrata/parser`](https://www.npmjs.com/package/@sutrata/parser).
+
+## Install
+
+```bash
+npm install @sutrata/editor react react-dom
+```
+
+`react` and `react-dom` (^18.3) are peer dependencies.
+
+## Usage
+
+The editor doesn't read or write files itself. You pass it a `StorageAdapter`, and it saves, opens and keeps version history through that adapter. The same editor can therefore run on local files, in a desktop shell or against a server.
+
+```tsx
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import {
+  TranslationProvider,
+  LanguageProvider,
+  DocumentProvider,
+  AppShell,
+  type StorageAdapter,
+} from '@sutrata/editor'
+import '@sutrata/editor/dist/shell/fonts/fonts.css'
+import '@sutrata/editor/dist/styles/screenplay.css'
+
+const storageAdapter: StorageAdapter = {
+  // documents and version history
+  saveDocument: async (path, content) => { /* ... */ },
+  loadDocument: async (path) => null,
+  listVersions: async (path) => [],
+  // file dialogs
+  openFile: async () => null,        // { name, content, handle }
+  openDocx: async () => null,        // { name, buffer }
+  openStyleJson: async () => null,   // { name, text }
+  saveFile: async (name, content, handle) => null, // { savedName, handle }
+  // custom screenplay styles
+  saveStyle: async (style) => {},
+  loadAllStyles: async () => [],
+  deleteStyle: async (id) => {},
+}
+
+createRoot(document.getElementById('root')!).render(
+  <TranslationProvider>
+    <LanguageProvider>
+      <DocumentProvider storageAdapter={storageAdapter}>
+        <AppShell />
+      </DocumentProvider>
+    </LanguageProvider>
+  </TranslationProvider>,
+)
+```
+
+`StorageAdapter` also has optional methods: `saveVersion`, `deleteAllVersions`, `persistFileHandle` and `restoreFileHandle`. For a complete implementation built on IndexedDB and the File System Access API, see [`local-storage-adapter.ts`](https://github.com/sutrata/sutrata/blob/main/packages/app/src/local-storage-adapter.ts) in the Sutrata app.
+
+Inside the providers, `useDocument()` gives you the current Sutra text, its parsed AST and the editor state.
+
+### Fonts
+
+`fonts.css` declares Noto font faces for every supported script, loaded from `/fonts/*.woff2` on your own site. This package does not include the font files. Copy them from [`packages/app/public/fonts`](https://github.com/sutrata/sutrata/tree/main/packages/app/public/fonts) into your app's `/fonts/` path, or use your own `@font-face` rules. Without them, some scripts may display as missing-glyph boxes (tofu).
+
+## Extension points
+
+Beyond `StorageAdapter`, the package exports type definitions for more extension points: `AIProvider`, `SpeechProvider`, `SessionContext`, `PanelRegistry`, `CommandRegistry`, `ExportRegistry`, `CollabBinding` and `DecorationProvider`. **These are type-only previews and are not wired into the editor yet.** Their shapes may change before 1.0.
+
+## Status
+
+Pre-1.0. The API may change between minor versions.
+
+## License
+
+[GPL-3.0-or-later](https://github.com/sutrata/sutrata/blob/main/packages/editor/LICENSE).

package/dist/ai/VoiceConfirmDialog.d.ts

@@ -5,5 +5,6 @@ interface Props {
     onConfirm: (formattedText: string) => void;
     onCancel: () => void;
 }
+/** Rendered only where useAI() is non-null (VoiceToolbar, SelectionMenu's Format). */
 export declare function VoiceConfirmDialog({ rawTranscript, langCode, onConfirm, onCancel }: Props): React.JSX.Element;
 export {};

package/dist/ai/VoiceConfirmDialog.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState, useEffect } from 'react';
-import { callAI, getAIConfig } from './ai-client';
-import { VOICE_FORMAT_SYSTEM_PROMPT } from './prompts';
+import { useAI } from '../extensions/ai-provider';
+import { formatTranscript as formatWithAI } from './format-transcript';
 import { SparklesIcon } from '../shell/icons';
+/** Rendered only where useAI() is non-null (VoiceToolbar, SelectionMenu's Format). */
 export function VoiceConfirmDialog({ rawTranscript, langCode, onConfirm, onCancel }) {
+    const ai = useAI();
     const [formattedText, setFormattedText] = useState('');
     const [isLoading, setIsLoading] = useState(true);
     const [error, setError] = useState('');
@@ -15,9 +17,7 @@ export function VoiceConfirmDialog({ rawTranscript, langCode, onConfirm, onCance
         setIsLoading(true);
         setError('');
         try {
-            const config = getAIConfig();
-            const prompt = `Raw Voice Transcript (${langCode}):\n"${rawTranscript}"`;
-            const result = await callAI(prompt, VOICE_FORMAT_SYSTEM_PROMPT, config, { clean: 'voice' });
+            const result = await formatWithAI(ai, rawTranscript, langCode);
             setFormattedText(result.trim());
         }
         catch (e) {
@@ -33,5 +33,5 @@ export function VoiceConfirmDialog({ rawTranscript, langCode, onConfirm, onCance
         localStorage.setItem('sutrata_always_auto_insert', alwaysAutoInsert ? 'true' : 'false');
         onConfirm(formattedText);
     };
-    return (_jsx("div", { className: "cs-dialog-overlay", onClick: onCancel, style: { zIndex: 310 }, children: _jsxs("div", { className: "cs-dialog cs-voice-confirm-dialog", role: "dialog", "aria-modal": "true", "aria-label": "Confirm Voice Dictation Formatting", onClick: e => e.stopPropagation(), children: [_jsxs("div", { className: "cs-dialog-header", children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '8px' }, children: [_jsx(SparklesIcon, { size: 16 }), _jsx("span", { className: "cs-dialog-title", children: "Review Voice Formatting" })] }), _jsx("button", { type: "button", className: "cs-fr-close", onClick: onCancel, "aria-label": "Close", children: "\u00D7" })] }), _jsx("div", { className: "cs-voice-confirm-body", children: isLoading ? (_jsxs("div", { className: "cs-voice-loading-state", children: [_jsx("div", { className: "cs-spinner", style: { width: '28px', height: '28px', borderWidth: '2.5px' } }), _jsx("span", { style: { fontSize: '13px', color: 'var(--cs-ui-text-dark-secondary, #a8a69d)' }, children: "Formatting speech into Sutra screenplay format..." })] })) : (_jsxs(_Fragment, { children: [error && (_jsxs("div", { className: "cs-voice-error", role: "alert", children: ["AI formatting notice: ", error, " (showing raw input below)"] })), _jsxs("div", { className: "cs-voice-grid", children: [_jsxs("div", { className: "cs-voice-column", children: [_jsx("span", { className: "cs-voice-col-title", children: "Raw Dictation" }), _jsx("div", { className: "cs-voice-box-raw", children: rawTranscript })] }), _jsxs("div", { className: "cs-voice-column", children: [_jsx("span", { className: "cs-voice-col-title", children: "Formatted Sutra" }), _jsx("textarea", { className: "cs-voice-box-formatted", value: formattedText, onChange: e => setFormattedText(e.target.value), rows: 8 })] })] }), _jsx("div", { className: "cs-voice-options", children: _jsxs("label", { className: "cs-voice-checkbox-label", children: [_jsx("input", { type: "checkbox", checked: alwaysAutoInsert, onChange: e => setAlwaysAutoInsert(e.target.checked) }), _jsx("span", { children: "Always auto-insert directly into screenplay (skip review)" })] }) }), _jsxs("div", { className: "cs-dialog-actions", style: { display: 'flex', justifyContent: 'flex-end', gap: '8px', marginTop: '12px' }, children: [_jsx("button", { type: "button", className: "cs-voice-btn-ghost", onClick: onCancel, children: "Discard" }), _jsx("button", { type: "button", className: "cs-voice-btn-primary", onClick: handleConfirm, children: "Insert Into Screenplay" })] })] })) })] }) }));
+    return (_jsx("div", { className: "cs-dialog-overlay", onClick: onCancel, style: { zIndex: 310 }, children: _jsxs("div", { className: "cs-dialog cs-voice-confirm-dialog", role: "dialog", "aria-modal": "true", "aria-label": "Review Formatting", onClick: e => e.stopPropagation(), children: [_jsxs("div", { className: "cs-dialog-header", children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '8px' }, children: [_jsx(SparklesIcon, { size: 16 }), _jsx("span", { className: "cs-dialog-title", children: "Review Formatting" })] }), _jsx("button", { type: "button", className: "cs-fr-close", onClick: onCancel, "aria-label": "Close", children: "\u00D7" })] }), _jsx("div", { className: "cs-voice-confirm-body", children: isLoading ? (_jsxs("div", { className: "cs-voice-loading-state", children: [_jsx("div", { className: "cs-spinner", style: { width: '28px', height: '28px', borderWidth: '2.5px' } }), _jsx("span", { style: { fontSize: '13px', color: 'var(--cs-ui-text-dark-secondary, #a8a69d)' }, children: "Formatting into Sutra screenplay format..." })] })) : (_jsxs(_Fragment, { children: [error && (_jsxs("div", { className: "cs-voice-error", role: "alert", children: ["AI formatting notice: ", error, " (showing raw input below)"] })), _jsxs("div", { className: "cs-voice-grid", children: [_jsxs("div", { className: "cs-voice-column", children: [_jsx("span", { className: "cs-voice-col-title", children: "Raw Content" }), _jsx("div", { className: "cs-voice-box-raw", tabIndex: 0, children: rawTranscript })] }), _jsxs("div", { className: "cs-voice-column", children: [_jsx("span", { className: "cs-voice-col-title", children: "Formatted Sutra" }), _jsx("textarea", { className: "cs-voice-box-formatted", value: formattedText, onChange: e => setFormattedText(e.target.value), rows: 8 })] })] }), _jsx("div", { className: "cs-voice-options", children: _jsxs("label", { className: "cs-voice-checkbox-label", children: [_jsx("input", { type: "checkbox", checked: alwaysAutoInsert, onChange: e => setAlwaysAutoInsert(e.target.checked) }), _jsx("span", { children: "Always auto-insert directly into screenplay (skip review)" })] }) }), _jsxs("div", { className: "cs-dialog-actions", style: { display: 'flex', justifyContent: 'flex-end', gap: '8px', marginTop: '12px' }, children: [_jsx("button", { type: "button", className: "cs-voice-btn-ghost", onClick: onCancel, children: "Discard" }), _jsx("button", { type: "button", className: "cs-voice-btn-primary", onClick: handleConfirm, children: "Insert Into Screenplay" })] })] })) })] }) }));
 }

package/dist/ai/VoiceToolbar.d.ts

@@ -1,2 +1,3 @@
 import React from 'react';
+/** Rendered by AppShell only when useSpeech() (which implies useAI()) is non-null. */
 export declare function VoiceToolbar(): React.JSX.Element;

package/dist/ai/VoiceToolbar.js

@@ -1,9 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useState, useEffect, useRef } from 'react';
 import { useDocument } from '../context/DocumentContext';
-import { voiceServiceInstance } from './voice-service';
-import { getAIConfig, callAI, hasConfiguredApiKey } from './ai-client';
-import { VOICE_FORMAT_SYSTEM_PROMPT } from './prompts';
+import { formatTranscript } from './format-transcript';
+import { useAI } from '../extensions/ai-provider';
+import { useSpeech } from '../extensions/speech-provider';
 import { insertSutra } from '../editor/insert-helper';
 import { VoiceConfirmDialog } from './VoiceConfirmDialog';
 import { LOCALIZED_COMMANDS } from './commands';
@@ -20,8 +20,12 @@ const VOICE_LANGUAGES = [
     { code: 'gu-IN', label: 'ગુજરાતી (Gujarati)', base: 'gu' },
     { code: 'mr-IN', label: 'मराठी (Marathi)', base: 'mr' },
 ];
+/** Rendered by AppShell only when useSpeech() (which implies useAI()) is non-null. */
 export function VoiceToolbar() {
-    const { mode, setVoiceActive, setAIOnboardingVisible, showToast } = useDocument();
+    const { mode, setVoiceActive, showToast } = useDocument();
+    const ai = useAI();
+    const speech = useSpeech();
+    const sessionRef = useRef(null);
     const { locale } = useTranslation();
     const defaultLang = VOICE_LANGUAGES.find(l => l.base === locale)?.code || 'en-US';
     const [langCode, setLangCode] = useState(defaultLang);
@@ -36,7 +40,7 @@ export function VoiceToolbar() {
         setLangCode(matched);
     }, [locale]);
     const canvasRef = useRef(null);
-    const isSupported = voiceServiceInstance.isSupported();
+    const isSupported = speech.isSupported();
     // Audio waveform animation
     useEffect(() => {
         if (!isListening)
@@ -77,9 +81,7 @@ export function VoiceToolbar() {
         if (alwaysAuto) {
             setIsFormatting(true);
             try {
-                const config = getAIConfig();
-                const prompt = `Raw Voice Transcript (${langCode}):\n"${fullTranscript}"`;
-                const result = await callAI(prompt, VOICE_FORMAT_SYSTEM_PROMPT, config, { clean: 'voice' });
+                const result = await formatTranscript(ai, fullTranscript, langCode);
                 insertSutra(result.trim(), mode);
                 setVoiceActive(false);
                 showToast('Voice dictation inserted.', 'success');
@@ -97,16 +99,20 @@ export function VoiceToolbar() {
         }
     };
     const handleStart = async () => {
-        const hasKey = await hasConfiguredApiKey(getAIConfig());
-        if (!hasKey) {
-            showToast('AI keys are required to format dictated text. Opening Setup...', 'info');
-            setAIOnboardingVisible(true);
+        if (!(await ai.isConfigured())) {
+            if (ai.openSetup) {
+                showToast('AI must be set up to format dictated text. Opening Setup...', 'info');
+                ai.openSetup();
+            }
+            else {
+                showToast(`${ai.displayName} is not available right now.`, 'warn');
+            }
             return;
         }
         setError('');
         setInterimResult('');
         setIsListening(true);
-        voiceServiceInstance.start(langCode, {
+        sessionRef.current = speech.listen(langCode, {
             onResult: (text, isFinal) => {
                 if (isFinal) {
                     setTranscript(prev => (prev ? prev + ' ' + text : text));
@@ -131,7 +137,7 @@ export function VoiceToolbar() {
         });
     };
     const handleStopListening = async () => {
-        voiceServiceInstance.stop();
+        sessionRef.current?.stop();
         setIsListening(false);
         const fullTranscript = (transcript + ' ' + interimResult).trim();
         if (fullTranscript) {
@@ -147,7 +153,7 @@ export function VoiceToolbar() {
         await performFormatting(fullTranscript);
     };
     const handleCancel = () => {
-        voiceServiceInstance.abort();
+        sessionRef.current?.abort();
         setIsListening(false);
         setVoiceActive(false);
     };
@@ -169,7 +175,7 @@ export function VoiceToolbar() {
     return (_jsxs("div", { className: "cs-voice-toolbar", role: "region", "aria-label": "Voice Dictation Toolbar", children: [_jsxs("div", { className: "cs-voice-toolbar-row", children: [_jsxs("div", { className: "cs-voice-toolbar-badge", children: [_jsx(MicIcon, { size: 14 }), _jsx("span", { children: "Voice Dictation" })] }), _jsx("select", { className: "cs-voice-select", value: langCode, onChange: e => setLangCode(e.target.value), disabled: isListening, "aria-label": "Voice Language", children: VOICE_LANGUAGES.map(l => (_jsx("option", { value: l.code, children: l.label }, l.code))) }), isListening ? (_jsxs("div", { className: "cs-voice-listening-group", children: [_jsx("button", { type: "button", className: "cs-voice-btn-danger", onClick: handleStopListening, children: "Stop & Format" }), _jsx("canvas", { ref: canvasRef, width: 110, height: 26, className: "cs-voice-waveform", role: "img", "aria-label": "Audio waveform visualization" })] })) : (_jsxs("div", { className: "cs-voice-actions-group", children: [_jsxs("button", { type: "button", className: "cs-voice-btn-primary", onClick: handleStart, disabled: !isSupported || isFormatting, children: [_jsx(MicIcon, { size: 14 }), _jsx("span", { children: isFormatting ? 'Formatting...' : 'Start Dictation' })] }), transcript && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "cs-voice-btn-secondary", onClick: handleFormatCaptured, disabled: isFormatting, children: "Re-format" }), _jsx("button", { type: "button", className: "cs-voice-btn-ghost", onClick: () => {
                                             setTranscript('');
                                             setError('');
-                                        }, children: "Clear" })] }))] })), _jsx("button", { type: "button", className: "cs-voice-btn-ghost", onClick: handleCancel, children: "Close" }), !isSupported && (_jsx("span", { className: "cs-voice-warning", children: "Web Speech API is not supported in this browser." }))] }), (isListening || transcript || interimResult) && (isListening ? (_jsxs("div", { className: "cs-voice-transcript-box", children: [transcript, interimResult && _jsxs("span", { className: "cs-voice-interim", children: [" ", interimResult] }), !transcript && !interimResult && _jsx("span", { className: "cs-voice-placeholder", children: "Speak now to dictate..." })] })) : (_jsx("textarea", { className: "cs-voice-textarea", value: transcript, onChange: (e) => setTranscript(e.target.value), placeholder: "Edit captured text before formatting...", rows: 2 }))), error && (_jsx("div", { className: "cs-voice-error", role: "alert", children: error })), _jsxs("div", { className: "cs-voice-cheatsheet", children: [_jsx("span", { className: "cs-voice-cheatsheet-title", children: "Commands:" }), cheatsheet.map(c => {
+                                        }, children: "Clear" })] }))] })), _jsx("button", { type: "button", className: "cs-voice-btn-ghost", onClick: handleCancel, children: "Close" }), !isSupported && (_jsxs("span", { className: "cs-voice-warning", children: [speech.displayName, " is not supported in this browser."] }))] }), (isListening || transcript || interimResult) && (isListening ? (_jsxs("div", { className: "cs-voice-transcript-box", children: [transcript, interimResult && _jsxs("span", { className: "cs-voice-interim", children: [" ", interimResult] }), !transcript && !interimResult && _jsx("span", { className: "cs-voice-placeholder", children: "Speak now to dictate..." })] })) : (_jsx("textarea", { className: "cs-voice-textarea", value: transcript, onChange: (e) => setTranscript(e.target.value), placeholder: "Edit captured text before formatting...", rows: 2 }))), error && (_jsx("div", { className: "cs-voice-error", role: "alert", children: error })), _jsxs("div", { className: "cs-voice-cheatsheet", children: [_jsx("span", { className: "cs-voice-cheatsheet-title", children: "Commands:" }), cheatsheet.map(c => {
                         if (c.type === 'literal')
                             return null;
                         return (_jsxs("span", { className: "cs-voice-tag", children: [_jsx("span", { className: "cs-voice-tag-type", children: c.type }), ": \u201C", c.keywords[0], "\u201D"] }, c.type));

package/dist/ai/clean-response.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Strip the chatter models wrap around Sutra output (code fences, list
+ * bullets, restated rules, "->" reasoning lines), keeping the blank lines
+ * that separate Sutra blocks. Applied to every AI formatting result before
+ * it is inserted, whichever AIProvider produced it.
+ */
+export declare function cleanVoiceResponse(text: string): string;

package/dist/ai/clean-response.js

@@ -0,0 +1,58 @@
+/**
+ * Strip the chatter models wrap around Sutra output (code fences, list
+ * bullets, restated rules, "->" reasoning lines), keeping the blank lines
+ * that separate Sutra blocks. Applied to every AI formatting result before
+ * it is inserted, whichever AIProvider produced it.
+ */
+export function cleanVoiceResponse(text) {
+    let cleaned = text.trim();
+    // Strip markdown code block wrapper if present
+    cleaned = cleaned.replace(/^```[a-zA-Z0-9]*\n/, '').replace(/\n```$/, '');
+    const lines = cleaned.split('\n');
+    const filteredLines = lines.map(line => {
+        let l = line.trim();
+        // Strip leading list bullet (e.g. *, -, +, •) and spaces
+        l = l.replace(/^[*•\-+]\s*/, '').trim();
+        // Strip leading/trailing backticks if any
+        l = l.replace(/^`+/, '').replace(/`+$/, '').trim();
+        // Strip common explanatory trailing comments in parens
+        l = l.replace(/\s*\(Standard screenplay shorthand[^)]*\)/gi, '');
+        l = l.replace(/\s*\(Standard shorthand[^)]*\)/gi, '');
+        return l;
+    }).filter(line => {
+        const trimmed = line.toLowerCase();
+        // Keep blank lines: they separate Sutra blocks (a blank line ends dialogue).
+        if (!trimmed)
+            return true;
+        // Discard reasoning/mapping/explanation patterns
+        if (trimmed.includes('->') ||
+            trimmed.includes('=>') ||
+            trimmed.startsWith('input:') ||
+            trimmed.startsWith('task:') ||
+            trimmed.startsWith('rules:') ||
+            trimmed.startsWith('instructions:') ||
+            trimmed.startsWith('sutra rules:') ||
+            trimmed.startsWith('scene headings:') ||
+            trimmed.startsWith('scene id:') ||
+            trimmed.startsWith('characters:') ||
+            trimmed.startsWith('parentheticals:') ||
+            trimmed.startsWith('dialogue:') ||
+            trimmed.startsWith('transitions:') ||
+            trimmed.startsWith('lyrics:') ||
+            trimmed.startsWith('action:') ||
+            trimmed.startsWith('format:') ||
+            trimmed.startsWith('components:') ||
+            trimmed.startsWith('output only') ||
+            trimmed.startsWith('no markdown') ||
+            trimmed.includes('convert it into valid sutra') ||
+            trimmed.includes('sutra syntax rules') ||
+            trimmed.includes('clearly a scene heading') ||
+            trimmed.includes('screenplay shorthand') ||
+            trimmed.includes('append as')) {
+            return false;
+        }
+        return true;
+    });
+    // Collapse runs of blank lines left behind by discarded explanation lines.
+    return filteredLines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}

package/dist/ai/format-transcript.d.ts

@@ -0,0 +1,3 @@
+import type { AIProvider } from '../extensions/ai-provider';
+/** Format a dictated (or selected) transcript as Sutra with the injected AI provider. */
+export declare function formatTranscript(ai: AIProvider, transcript: string, langCode: string): Promise<string>;

package/dist/ai/format-transcript.js

@@ -0,0 +1,7 @@
+import { VOICE_FORMAT_SYSTEM_PROMPT } from './prompts';
+import { cleanVoiceResponse } from './clean-response';
+/** Format a dictated (or selected) transcript as Sutra with the injected AI provider. */
+export async function formatTranscript(ai, transcript, langCode) {
+    const prompt = `Raw Voice Transcript (${langCode}):\n"${transcript}"`;
+    return cleanVoiceResponse(await ai.complete({ system: VOICE_FORMAT_SYSTEM_PROMPT, prompt }));
+}

package/dist/ai/prompts.d.ts

@@ -1,4 +1,4 @@
-export declare const VOICE_FORMAT_SYSTEM_PROMPT = "You are Sutrata's AI screenplay formatter.\nYour task is to take a raw voice dictation transcript (which may contain explicit formatting keywords like \"scene\", \"character\", \"dialogue\", \"parenthetical\", \"transition\") and convert it into valid Sutra screenplay format.\n\nSutra syntax rules:\n1. Scene Headings: Start with \"##\" (e.g., \"## INT. COFFEE SHOP - DAY\"). If a scene number/ID is specified (e.g., \"scene #2\", \"scene 2\", or \"scene 3A\"), append it as a Sutra attribute ID at the end of the scene heading, like \"{#2}\" or \"{#3A}\" (e.g., \"## EXT. SWIMMING POOL - DAY {#2}\").\n2. Characters: All-caps, alone on a line (e.g., \"RAJ\").\n3. Parentheticals: In parentheses, on a line by itself under character (e.g., \"(whispering)\").\n4. Dialogue: Indented text directly following a character or parenthetical.\n5. Transitions: In uppercase, prefixed with \">\" or ending with \"TO:\" (e.g., \"> CUT TO:\").\n6. Lyrics: Prefixed with \"~\" (e.g., \"~ Sing a song\").\n7. Action: Standard descriptive paragraph.\n\nCRITICAL INSTRUCTIONS:\n- Preserve Indic/Unicode characters and mixed-language code-switching exactly as transcribed. Do NOT translate non-English text to English.\n- Output ONLY the formatted Sutra text.\n- Do NOT include any explanations, steps, reasoning, bullet points, meta-commentary, or introductory/concluding text.\n- Do NOT output headings, drafts, prefixes, or suffixes.\n- Do NOT wrap in markdown code blocks like ```cine.\n- The output must contain nothing but the final formatted Sutra screenplay lines.\n";
+export declare const VOICE_FORMAT_SYSTEM_PROMPT = "You are Sutrata's AI screenplay formatter.\nYour task is to take a raw voice dictation transcript (which may contain explicit formatting keywords like \"scene\", \"character\", \"dialogue\", \"parenthetical\", \"transition\") and convert it into valid Sutra screenplay format.\n\nSutra syntax rules (one element per block; separate blocks with a blank line):\n1. Scene Headings: Start with \"##\" (e.g., \"## INT. COFFEE SHOP - DAY\"). If a scene number/ID is specified (e.g., \"scene #2\", \"scene 2\", or \"scene 3A\"), append it as a Sutra attribute ID at the end of the scene heading, like \"{#2}\" or \"{#3A}\" (e.g., \"## EXT. SWIMMING POOL - DAY {#2}\").\n2. Scene Metadata: Lines directly under a scene heading starting with \"&\", as \"& key: value\" (e.g., \"& time: DAY\", \"& synopsis: Raj waits for Meera.\"). Only add metadata the speaker actually gave.\n3. Character Cues: Start with \"@\", alone on a line (e.g., \"@RAJ\", \"@\u092E\u0940\u0930\u093E\"). Keep the speaker's casing and script; never rely on ALL CAPS.\n4. Parentheticals: In parentheses, on a line by itself under the character cue (e.g., \"(whispering)\").\n5. Dialogue: The lines directly after the character cue or parenthetical, with no blank line in between. A blank line ends the dialogue block.\n6. Transitions: Start with \">>\" (e.g., \">> CUT TO:\").\n7. Lyrics: Prefixed with \"~ \" (e.g., \"~ Sing a song\").\n8. Action: Standard descriptive paragraph.\n\nCRITICAL INSTRUCTIONS:\n- Preserve Indic/Unicode characters and mixed-language code-switching exactly as transcribed. Do NOT translate non-English text to English.\n- Output ONLY the formatted Sutra text.\n- Do NOT include any explanations, steps, reasoning, bullet points, meta-commentary, or introductory/concluding text.\n- Do NOT output headings, drafts, prefixes, or suffixes.\n- Do NOT wrap in markdown code blocks like ```cine.\n- The output must contain nothing but the final formatted Sutra screenplay lines.\n";
 /**
  * Combined synopsis+duration prompt. Merged into one call (and one JSON
  * response) instead of two separate requests to halve per-scene LLM cost.
@@ -23,3 +23,10 @@ export declare const SCENE_METADATA_SCHEMA: {
     readonly required: readonly ["synopsis", "duration"];
     readonly additionalProperties: false;
 };
+/**
+ * AI-assisted import (import/ai-import.ts): turns a chunk of a screenplay
+ * written elsewhere (Word, plain text, Markdown) into Sutra. The content
+ * check after each call compares words in and out, so the rules below about
+ * never adding, dropping or translating text are enforced, not just asked.
+ */
+export declare const IMPORT_FORMAT_SYSTEM_PROMPT = "You convert screenplay text into Sutra, a plain-text screenplay format. You receive one chunk of a longer script; format only that chunk.\n\nSutra syntax (separate blocks with one blank line):\n1. Scene heading: \"## \" + the heading text as written (e.g. \"## INT. COFFEE SHOP - DAY\", \"## \u0905\u0902\u0926\u0930. \u0930\u0947\u0932\u0935\u0947 \u0938\u094D\u091F\u0947\u0936\u0928 - \u0930\u093E\u0924\"). If the source numbers the scene, append the number as \"{#12}\" at the end of the heading line and drop it from the text.\n2. Action: a plain paragraph with no sigil.\n3. Character cue: \"@\" + the name exactly as written, alone on a line, optionally followed by an extension like \"(V.O.)\". Never change the name's case or script.\n4. Dialogue: the lines directly under the cue, no blank line in between.\n5. Parenthetical: \"(text)\" on its own line inside a dialogue block.\n6. Transition: \">> \" + text (e.g. \">> CUT TO:\").\n7. Centered text: \">> text <<\".\n8. Lyrics: \"~ \" at the start of every lyric line.\n9. Section/act heading: \"# \" + text.\n10. Emphasis already marked with *italic*, **bold** or _underline_ must be kept.\n\nRules:\n- Keep every word of the source, in its original language and script. Never translate, transliterate, summarise, correct, reorder or add text.\n- Do not invent scene headings, character names, metadata (\"& key: value\") or notes.\n- Page numbers, \"CONTINUED\", \"(MORE)\" and \"(CONT'D)\" page furniture may be dropped.\n- If a line's role is unclear, keep it as action.\n- Output only the Sutra text: no explanations, no code fences, no frontmatter.";

package/dist/ai/prompts.js

@@ -1,14 +1,15 @@
 export const VOICE_FORMAT_SYSTEM_PROMPT = `You are Sutrata's AI screenplay formatter.
 Your task is to take a raw voice dictation transcript (which may contain explicit formatting keywords like "scene", "character", "dialogue", "parenthetical", "transition") and convert it into valid Sutra screenplay format.
 
-Sutra syntax rules:
+Sutra syntax rules (one element per block; separate blocks with a blank line):
 1. Scene Headings: Start with "##" (e.g., "## INT. COFFEE SHOP - DAY"). If a scene number/ID is specified (e.g., "scene #2", "scene 2", or "scene 3A"), append it as a Sutra attribute ID at the end of the scene heading, like "{#2}" or "{#3A}" (e.g., "## EXT. SWIMMING POOL - DAY {#2}").
-2. Characters: All-caps, alone on a line (e.g., "RAJ").
-3. Parentheticals: In parentheses, on a line by itself under character (e.g., "(whispering)").
-4. Dialogue: Indented text directly following a character or parenthetical.
-5. Transitions: In uppercase, prefixed with ">" or ending with "TO:" (e.g., "> CUT TO:").
-6. Lyrics: Prefixed with "~" (e.g., "~ Sing a song").
-7. Action: Standard descriptive paragraph.
+2. Scene Metadata: Lines directly under a scene heading starting with "&", as "& key: value" (e.g., "& time: DAY", "& synopsis: Raj waits for Meera."). Only add metadata the speaker actually gave.
+3. Character Cues: Start with "@", alone on a line (e.g., "@RAJ", "@मीरा"). Keep the speaker's casing and script; never rely on ALL CAPS.
+4. Parentheticals: In parentheses, on a line by itself under the character cue (e.g., "(whispering)").
+5. Dialogue: The lines directly after the character cue or parenthetical, with no blank line in between. A blank line ends the dialogue block.
+6. Transitions: Start with ">>" (e.g., ">> CUT TO:").
+7. Lyrics: Prefixed with "~ " (e.g., "~ Sing a song").
+8. Action: Standard descriptive paragraph.
 
 CRITICAL INSTRUCTIONS:
 - Preserve Indic/Unicode characters and mixed-language code-switching exactly as transcribed. Do NOT translate non-English text to English.
@@ -57,3 +58,29 @@ export const SCENE_METADATA_SCHEMA = {
     required: ['synopsis', 'duration'],
     additionalProperties: false,
 };
+/**
+ * AI-assisted import (import/ai-import.ts): turns a chunk of a screenplay
+ * written elsewhere (Word, plain text, Markdown) into Sutra. The content
+ * check after each call compares words in and out, so the rules below about
+ * never adding, dropping or translating text are enforced, not just asked.
+ */
+export const IMPORT_FORMAT_SYSTEM_PROMPT = `You convert screenplay text into Sutra, a plain-text screenplay format. You receive one chunk of a longer script; format only that chunk.
+
+Sutra syntax (separate blocks with one blank line):
+1. Scene heading: "## " + the heading text as written (e.g. "## INT. COFFEE SHOP - DAY", "## अंदर. रेलवे स्टेशन - रात"). If the source numbers the scene, append the number as "{#12}" at the end of the heading line and drop it from the text.
+2. Action: a plain paragraph with no sigil.
+3. Character cue: "@" + the name exactly as written, alone on a line, optionally followed by an extension like "(V.O.)". Never change the name's case or script.
+4. Dialogue: the lines directly under the cue, no blank line in between.
+5. Parenthetical: "(text)" on its own line inside a dialogue block.
+6. Transition: ">> " + text (e.g. ">> CUT TO:").
+7. Centered text: ">> text <<".
+8. Lyrics: "~ " at the start of every lyric line.
+9. Section/act heading: "# " + text.
+10. Emphasis already marked with *italic*, **bold** or _underline_ must be kept.
+
+Rules:
+- Keep every word of the source, in its original language and script. Never translate, transliterate, summarise, correct, reorder or add text.
+- Do not invent scene headings, character names, metadata ("& key: value") or notes.
+- Page numbers, "CONTINUED", "(MORE)" and "(CONT'D)" page furniture may be dropped.
+- If a line's role is unclear, keep it as action.
+- Output only the Sutra text: no explanations, no code fences, no frontmatter.`;

package/dist/autocomplete/suggestions.js

@@ -3,7 +3,7 @@ const PREDEFINED_TRANSITIONS = [
     'MATCH CUT TO:', 'WIPE TO:', 'IRIS IN:', 'IRIS OUT:',
 ];
 const RESERVED_METADATA_KEYS = [
-    'status', 'tags', 'location', 'time', 'number', 'lang', 'mood',
+    'status', 'tags', 'location', 'time', 'lang', 'mood',
     'arc', 'note', 'locked',
 ];
 /**

package/dist/context/DocumentContext.d.ts

@@ -2,6 +2,14 @@ import React from 'react';
 import type { DocumentNode } from '@sutrata/parser';
 import type { EditorMode, VersionEntry } from '../types';
 import type { StorageAdapter } from '../extensions/storage-adapter';
+import type { AIProvider } from '../extensions/ai-provider';
+import type { SpeechProvider } from '../extensions/speech-provider';
+import type { SessionContext } from '../extensions/session';
+import type { PanelRegistry, PanelContribution } from '../extensions/panel-registry';
+import type { CommandRegistry, CommandContribution } from '../extensions/command-registry';
+import type { ExportRegistry, ExportContribution } from '../extensions/export-registry';
+import type { DecorationProvider } from '../extensions/decorations';
+import type { CollabBinding } from '../extensions/collab';
 import type { ScreenplayStyleDefinition } from '../styles/types';
 import type { ConfirmOptions } from '../shell/ConfirmDialog';
 import type { ToastItem } from '../shell/Toast';
@@ -17,7 +25,6 @@ interface DocumentContextValue {
     navVisible: boolean;
     exportVisible: boolean;
     settingsVisible: boolean;
-    aiOnboardingVisible: boolean;
     voiceActive: boolean;
     metadataVisible: boolean;
     findReplaceVisible: boolean;
@@ -37,7 +44,6 @@ interface DocumentContextValue {
     setNavVisible: (v: boolean) => void;
     setExportVisible: (v: boolean) => void;
     setSettingsVisible: (v: boolean) => void;
-    setAIOnboardingVisible: (v: boolean) => void;
     setVoiceActive: (v: boolean) => void;
     setMetadataVisible: (v: boolean) => void;
     setFindReplaceVisible: (visible: boolean) => void;
@@ -60,9 +66,27 @@ interface DocumentContextValue {
     showToast: (message: string, type?: 'info' | 'success' | 'warn' | 'error') => void;
     dismissToast: (id: string) => void;
 }
-export declare function DocumentProvider({ children, storageAdapter }: {
+export interface DocumentProviderProps {
     children: React.ReactNode;
+    /** Required: where documents, versions and styles are stored. */
     storageAdapter: StorageAdapter;
-}): React.JSX.Element;
+    /** Optional LLM access. Without it, AI features are hidden. */
+    aiProvider?: AIProvider;
+    /** Optional speech-to-text. Voice dictation needs it and aiProvider. */
+    speechProvider?: SpeechProvider;
+    /** Optional user/permission/feature-flag context. Default: local user, `edit`. */
+    session?: SessionContext;
+    /** Optional embedder panels: a live registry, or a fixed list. */
+    panels?: PanelRegistry | PanelContribution[];
+    /** Optional embedder commands (toolbar/app-bar entries, shortcuts): a live registry, or a fixed list. */
+    commands?: CommandRegistry | CommandContribution[];
+    /** Optional embedder export formats and reports: a live registry, or a fixed list. */
+    exporters?: ExportRegistry | ExportContribution[];
+    /** Optional annotation sources (comments, breakdown, revisions). Pass a stable array. */
+    decorationProviders?: DecorationProvider[];
+    /** Optional real-time collaboration binding for the formatted editor. */
+    collabBinding?: CollabBinding;
+}
+export declare function DocumentProvider({ children, storageAdapter, aiProvider, speechProvider, session, panels, commands, exporters, decorationProviders, collabBinding, }: DocumentProviderProps): React.JSX.Element;
 export declare function useDocument(): DocumentContextValue;
 export {};