@sutrata/editor 0.1.2 → 0.2.0

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 {};

package/dist/context/DocumentContext.js

@@ -2,10 +2,19 @@ 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 } 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 } from '../editor/editor-bus';
 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,7 +57,15 @@ 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');
@@ -64,7 +81,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);
@@ -162,6 +178,8 @@ export function DocumentProvider({ children, storageAdapter }) {
     // 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);
@@ -441,10 +459,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 +512,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 +541,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 +615,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, 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);