superdoc-macros 0.2.0 → 0.4.0

package/dist/host/superdoc-host.js

@@ -1,5 +1,29 @@
-/* ---------- עזרים ---------- */
-const NOT_READY = { ok: false, message: 'אין מסמך פתוח', reason: 'not-ready' };
+/**
+ * The `MacroHost` implementation on top of SuperDoc v2 in engine-only mode
+ * (`ui: false`) — the configuration otzaria-word-editor runs.
+ *
+ * The surfaces used, in order of preference:
+ *   1. `superdoc.ui.commands` — the controller's command catalog (execution + observation).
+ *   2. `superdoc.activeEditor.doc` — the public Document API (selection, insertion, blocks).
+ *   3. `superdoc.ui.search` — find/replace.
+ *   4. `superdoc.activeEditor.view` — the internal ProseMirror instance,
+ *      **only** for gaps that have no public surface: backward deletion and
+ *      the document's full text. Present in the browser, null headless.
+ *
+ * The types here are structural and do not import from superdoc: the toolkit
+ * does not depend on the package, and an engine version that changes a field
+ * fails closed (the function returns a failure) rather than crashing.
+ *
+ * Command observation for the recorder wraps `executeAsync` on the commands
+ * object. That covers every path that calls it — including otzaria's
+ * CommandAdapter — without changing the calling code. `dispose()` restores
+ * the original method.
+ */
+import { macroMessages } from '../messages.js';
+/* ---------- Helpers ---------- */
+function notReady() {
+    return { ok: false, message: macroMessages().noDocument, reason: 'not-ready' };
+}
 function failed(message, reason) {
     return { ok: false, message, reason };
 }
@@ -16,43 +40,104 @@ function receiptOutcome(receipt, failedAction) {
 function emptySelection() {
     return { text: '', hasRange: false, blockId: null, selectionTarget: null, empty: true };
 }
-/* ---------- המימוש ---------- */
+/* ---------- The implementation ---------- */
 export function createSuperdocHost(options) {
     const { superdoc, container } = options;
-    // נקראים ברגע השימוש ולא נשמרים: activeEditor מוחלף בכל פתיחת מסמך.
+    const viewFallback = options.viewFallback ?? true;
+    // Read at call time, never cached: activeEditor is replaced on every document open.
     const commands = () => superdoc.ui?.commands ?? null;
     const doc = () => superdoc.activeEditor?.doc ?? null;
-    const view = () => superdoc.activeEditor?.view ?? null;
     const search = () => superdoc.ui?.search ?? null;
+    /**
+     * The single gate to the internal ProseMirror view. Every use of a
+     * non-public surface goes through here, so disabling the fallback (or a
+     * future engine that hides the view) degrades to closed failures in one
+     * place.
+     */
+    const view = () => viewFallback ? (superdoc.activeEditor?.view ?? null) : null;
     const commandListeners = new Set();
     const inputListeners = new Set();
-    /* תצפית פקודות: עטיפת executeAsync, פעם אחת, עם שחזור ב-dispose. */
+    const emitInput = (mapped) => {
+        for (const listener of inputListeners) {
+            try {
+                listener(mapped);
+            }
+            catch (error) {
+                console.warn('[superdoc-macros] input listener threw', error);
+            }
+        }
+    };
+    /* Command observation: wrap executeAsync, once, restored on dispose.
+       Listeners are notified only after the engine reports success — a command
+       that was refused (not routed, or a failed receipt) must not enter a
+       recording, or replay would re-fail it or, worse, apply it in a context
+       where it now succeeds unintended. */
     const wrapped = commands();
     const originalExecuteAsync = wrapped?.executeAsync;
     if (wrapped && originalExecuteAsync) {
         wrapped.executeAsync = function (id, payload) {
-            for (const listener of commandListeners) {
-                try {
-                    listener(id, payload);
+            const result = originalExecuteAsync.call(wrapped, id, payload);
+            void Promise.resolve(result)
+                .then((value) => {
+                if (value === false)
+                    return;
+                if (typeof value === 'object' && value !== null && value.success === false)
+                    return;
+                for (const listener of commandListeners) {
+                    try {
+                        listener(id, payload);
+                    }
+                    catch (error) {
+                        console.warn('[superdoc-macros] command listener threw', error);
+                    }
                 }
-                catch (error) {
-                    console.warn('[superdoc-macros] מאזין פקודות זרק', error);
-                }
-            }
-            return originalExecuteAsync.call(wrapped, id, payload);
+            })
+                .catch(() => undefined); // a thrown command is a failure — nothing to record.
+            return result;
         };
     }
-    /* הקלדה: beforeinput על ה-container, בשלב הלכידה. */
+    /* Typing: beforeinput on the container, capture phase.
+  
+       IME composition is folded to a single event: while composing, the
+       engine fires insertCompositionText repeatedly with the growing
+       candidate text, and mapping each one would record the word once per
+       keystroke. The events are suppressed during composition and the final
+       text is emitted once, from compositionend. */
+    let composing = false;
+    const onCompositionStart = () => {
+        composing = true;
+    };
+    const onCompositionEnd = (event) => {
+        composing = false;
+        const data = event.data;
+        if (typeof data === 'string' && data.length > 0)
+            emitInput({ kind: 'insert-text', text: data });
+    };
     const onBeforeInput = (event) => {
         const input = event;
         let mapped = null;
         switch (input.inputType) {
             case 'insertText':
             case 'insertCompositionText':
+                if (composing)
+                    break; // the final text arrives from compositionend.
                 if (typeof input.data === 'string' && input.data.length > 0) {
                     mapped = { kind: 'insert-text', text: input.data };
                 }
                 break;
+            // Paste, drop and spellcheck replacement carry their text either in
+            // `data` or in a dataTransfer — without this branch a recording
+            // silently missed everything the user pasted.
+            case 'insertFromPaste':
+            case 'insertFromDrop':
+            case 'insertReplacementText': {
+                const text = typeof input.data === 'string' && input.data.length > 0
+                    ? input.data
+                    : input.dataTransfer?.getData('text/plain') ?? '';
+                if (text.length > 0)
+                    mapped = { kind: 'insert-text', text };
+                break;
+            }
             case 'insertParagraph':
                 mapped = { kind: 'insert-paragraph' };
                 break;
@@ -65,29 +150,32 @@ export function createSuperdocHost(options) {
             default:
                 break;
         }
-        if (!mapped)
-            return;
-        for (const listener of inputListeners) {
-            try {
-                listener(mapped);
-            }
-            catch (error) {
-                console.warn('[superdoc-macros] מאזין הקלדה זרק', error);
-            }
-        }
+        if (mapped)
+            emitInput(mapped);
     };
     container?.addEventListener('beforeinput', onBeforeInput, true);
-    async function readSelection(includeText) {
+    container?.addEventListener('compositionstart', onCompositionStart, true);
+    container?.addEventListener('compositionend', onCompositionEnd, true);
+    /**
+     * `failed: true` means the engine call itself threw — as opposed to a
+     * clean "no selection" answer. Callers that write relative to the caret
+     * must fail closed on it: falling back to "no target" would send the text
+     * to the end of the document, far from where the user is looking.
+     */
+    async function readSelectionDetailed(includeText) {
         const current = doc()?.selection?.current;
         if (typeof current !== 'function')
-            return emptySelection();
+            return { snapshot: emptySelection(), failed: false };
         let info;
         try {
             info = await current(includeText ? { includeText: true } : undefined);
         }
         catch {
-            return emptySelection();
+            return { snapshot: emptySelection(), failed: true };
         }
+        return { snapshot: parseSelectionInfo(info), failed: false };
+    }
+    function parseSelectionInfo(info) {
         if (!info || typeof info !== 'object')
             return emptySelection();
         const segments = Array.isArray(info.target?.segments) ? info.target.segments : [];
@@ -119,23 +207,23 @@ export function createSuperdocHost(options) {
             async execute(id, payload) {
                 const bus = commands();
                 if (!bus)
-                    return NOT_READY;
+                    return notReady();
                 if (!bus.has(id))
-                    return failed(`הפקודה ${id} אינה מוכרת למנוע`, 'unknown-command');
+                    return failed(macroMessages().unknownCommand(id), 'unknown-command');
                 let result;
                 try {
                     result = await bus.executeAsync(id, payload);
                 }
                 catch (error) {
-                    return failed(error instanceof Error ? error.message : 'הפעולה נכשלה', 'threw');
+                    return failed(error instanceof Error ? error.message : macroMessages().actionFailed, 'threw');
                 }
-                // false = ה-controller לא ניתב את הפקודה; מצב הפקד מסביר למה.
+                // false = the controller did not route the command; the command state explains why.
                 if (result === false) {
                     const reason = bus.get(id).getState().reason;
-                    return failed(reason ? `הפעולה נכשלה (${reason})` : 'הפעולה נכשלה', reason);
+                    return failed(reason ? `${macroMessages().actionFailed} (${reason})` : macroMessages().actionFailed, reason);
                 }
                 if (typeof result === 'object' && result !== null) {
-                    return receiptOutcome(result, `הפקודה ${id} נכשלה`);
+                    return receiptOutcome(result, macroMessages().commandFailed(id));
                 }
                 return { ok: true };
             },
@@ -143,21 +231,25 @@ export function createSuperdocHost(options) {
         async insertText(text) {
             const insert = doc()?.insert;
             if (typeof insert === 'function') {
-                // בלי target ההכנסה נופלת לסוף המסמך — לכן היעד נלקח מהבחירה החיה.
-                const snapshot = await readSelection(false);
+                // Without a target the insertion falls to the end of the document — so the target comes from the live selection.
+                const { snapshot, failed: selectionFailed } = await readSelectionDetailed(false);
+                // A failed read is not "no selection": inserting without a target
+                // would land the text at the end of the document. Fail closed.
+                if (selectionFailed)
+                    return failed(macroMessages().selectionUnavailable, 'selection-read-failed');
                 try {
                     const receipt = await insert({
                         value: text,
                         type: 'text',
                         ...(snapshot.selectionTarget ? { target: snapshot.selectionTarget } : {}),
                     });
-                    return receiptOutcome(receipt, 'הכנסת הטקסט נכשלה');
+                    return receiptOutcome(receipt, macroMessages().insertTextFailed);
                 }
                 catch (error) {
-                    return failed(error instanceof Error ? error.message : 'הכנסת הטקסט נכשלה', 'threw');
+                    return failed(error instanceof Error ? error.message : macroMessages().insertTextFailed, 'threw');
                 }
             }
-            // נפילה לאחור: ProseMirror ישיר, כשה-Document API אינו זמין.
+            // Fallback: direct ProseMirror, when the Document API is unavailable.
             const pm = view();
             if (pm) {
                 try {
@@ -168,16 +260,16 @@ export function createSuperdocHost(options) {
                     return { ok: true };
                 }
                 catch (error) {
-                    return failed(error instanceof Error ? error.message : 'הכנסת הטקסט נכשלה', 'threw');
+                    return failed(error instanceof Error ? error.message : macroMessages().insertTextFailed, 'threw');
                 }
             }
-            return NOT_READY;
+            return notReady();
         },
         async deleteBackward(count) {
-            // אין משטח ציבורי למחיקה — זה השימוש המרכזי ב-escape hatch של ProseMirror.
+            // No public deletion surface — this is the main use of the ProseMirror escape hatch.
             const pm = view();
             if (!pm)
-                return failed('מחיקה אינה זמינה במסמך הזה', 'view-unavailable');
+                return failed(macroMessages().deletionUnavailable, 'view-unavailable');
             try {
                 const { from } = pm.state.selection;
                 const start = Math.max(0, from - Math.max(0, Math.trunc(count)));
@@ -189,33 +281,56 @@ export function createSuperdocHost(options) {
                 return { ok: true };
             }
             catch (error) {
-                return failed(error instanceof Error ? error.message : 'המחיקה נכשלה', 'threw');
+                return failed(error instanceof Error ? error.message : macroMessages().deleteFailed, 'threw');
+            }
+        },
+        async deleteForward(count) {
+            const pm = view();
+            if (!pm)
+                return failed(macroMessages().deletionUnavailable, 'view-unavailable');
+            try {
+                const { from } = pm.state.selection;
+                const size = pm.state.doc.content.size;
+                const end = Math.min(size, from + Math.max(0, Math.trunc(count)));
+                if (end === from)
+                    return { ok: true };
+                const tr = pm.state.tr;
+                tr.delete(from, end);
+                pm.dispatch(tr);
+                return { ok: true };
+            }
+            catch (error) {
+                return failed(error instanceof Error ? error.message : macroMessages().deleteFailed, 'threw');
             }
         },
-        getSelection(options) {
-            return readSelection(options?.includeText ?? false);
+        async getSelection(options) {
+            return (await readSelectionDetailed(options?.includeText ?? false)).snapshot;
         },
         async replaceAll(query, replacement) {
             const handle = search();
             if (!handle)
-                return { ok: false, replaced: 0, message: 'החיפוש אינו זמין' };
+                return { ok: false, replaced: 0, message: macroMessages().searchUnavailable };
             try {
                 handle.open?.();
                 const slice = handle.search(query);
                 if (slice?.available === false) {
-                    return { ok: false, replaced: 0, message: 'החיפוש אינו זמין במסמך הזה' };
+                    return { ok: false, replaced: 0, message: macroMessages().searchUnavailableInDocument };
                 }
                 const total = typeof slice?.total === 'number' ? slice.total : 0;
                 if (total === 0)
                     return { ok: true, replaced: 0 };
                 const result = await handle.replaceAll(replacement);
                 if (result && result.ok === false) {
-                    return { ok: false, replaced: 0, message: `ההחלפה נכשלה${result.reason ? ` (${result.reason})` : ''}` };
+                    return {
+                        ok: false,
+                        replaced: 0,
+                        message: `${macroMessages().replaceFailed}${result.reason ? ` (${result.reason})` : ''}`,
+                    };
                 }
                 return { ok: true, replaced: total };
             }
             catch (error) {
-                return { ok: false, replaced: 0, message: error instanceof Error ? error.message : 'ההחלפה נכשלה' };
+                return { ok: false, replaced: 0, message: error instanceof Error ? error.message : macroMessages().replaceFailed };
             }
             finally {
                 try {
@@ -223,7 +338,7 @@ export function createSuperdocHost(options) {
                     handle.close?.();
                 }
                 catch {
-                    /* ניקוי בלבד */
+                    /* cleanup only */
                 }
             }
         },
@@ -250,6 +365,8 @@ export function createSuperdocHost(options) {
             if (wrapped && originalExecuteAsync)
                 wrapped.executeAsync = originalExecuteAsync;
             container?.removeEventListener('beforeinput', onBeforeInput, true);
+            container?.removeEventListener('compositionstart', onCompositionStart, true);
+            container?.removeEventListener('compositionend', onCompositionEnd, true);
             commandListeners.clear();
             inputListeners.clear();
         },

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export type { MacroHost, MacroOutcome, MacroStep, RecordedMacro, SavedScript, SelectionSnapshot, Snippet, TextInputEvent, } from './types.js';
-export { MacroKit, type MacroKitOptions } from './manager.js';
+export { MacroKit, type MacroKitOptions, type ShortcutValidation } from './manager.js';
+export { ENGLISH_MESSAGES, HEBREW_MESSAGES, setMacroMessages, type MacroMessages, } from './messages.js';
 export { createSuperdocHost, type SuperdocHostOptions, type SuperdocLike, type SuperdocMacroHost } from './host/superdoc-host.js';
 export { createMacroApi, MacroError, type MacroApi, type MacroBridge, type ScriptSelection } from './scripting/macro-api.js';
 export { createEvalRunner } from './scripting/eval-runner.js';
@@ -8,5 +9,5 @@ export type { MacroRunner, MacroRunOptions, MacroRunResult } from './scripting/r
 export { MacroRecorder, replayMacro, type RecorderOptions, type ReplayOptions, type ReplayResult } from './recorder/recorder.js';
 export { renderSnippet, expandSnippet, usesSelection, type ExpandOptions, type RenderContext } from './snippets/snippets.js';
 export { AutoText, type AutoTextOptions } from './snippets/autotext.js';
-export { parseShortcut, eventMatches, bindShortcuts, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget } from './shortcuts.js';
-export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, type MacroStorage, type PersistedMacroState, } from './storage.js';
+export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget, } from './shortcuts.js';
+export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, type MacroStorage, type PersistedMacroState, } from './storage.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { MacroKit } from './manager.js';
+export { ENGLISH_MESSAGES, HEBREW_MESSAGES, setMacroMessages, } from './messages.js';
 export { createSuperdocHost } from './host/superdoc-host.js';
 export { createMacroApi, MacroError } from './scripting/macro-api.js';
 export { createEvalRunner } from './scripting/eval-runner.js';
@@ -6,5 +7,5 @@ export { createIframeRunner, SANDBOX_BOOTSTRAP, isProtocolMessage } from './scri
 export { MacroRecorder, replayMacro } from './recorder/recorder.js';
 export { renderSnippet, expandSnippet, usesSelection } from './snippets/snippets.js';
 export { AutoText } from './snippets/autotext.js';
-export { parseShortcut, eventMatches, bindShortcuts } from './shortcuts.js';
-export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, } from './storage.js';
+export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, } from './shortcuts.js';
+export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, } from './storage.js';

package/dist/manager.d.ts

@@ -1,11 +1,11 @@
 /**
- * `MacroKit` — הפאסדה שמארח מתקין פעם אחת ומקבל את שלוש היכולות מחווטות:
- * סקריפטים (עם ארגז חול), מקליט, וקטעי טקסט עם השלמה אוטומטית — פלוס שמירה,
- * ייבוא/ייצוא וקיצורי מקלדת.
+ * `MacroKit` — the facade a host installs once to get all three capabilities
+ * wired together: scripts (sandboxed), the recorder, and snippets with
+ * auto-text — plus persistence, import/export and keyboard shortcuts.
  *
- * כלל בטיחות אחד נאכף כאן: אין ריצה בזמן הקלטה ואין שתי ריצות במקביל.
- * ניגון או סקריפט שרצים תוך כדי הקלטה היו מוקלטים בעצמם ומכפילים את עצמם
- * בניגון הבא.
+ * One safety rule is enforced here: no running while recording, and no two
+ * runs at once. A replay or script running during a recording would be
+ * recorded itself and duplicate itself on the next replay.
  */
 import { type MacroApiOptions } from './scripting/macro-api.js';
 import type { MacroRunner, MacroRunOptions, MacroRunResult } from './scripting/runner.js';
@@ -17,20 +17,34 @@ import { type MacroStorage } from './storage.js';
 import type { MacroHost, RecordedMacro, SavedScript, Snippet } from './types.js';
 export interface MacroKitOptions {
     host: MacroHost;
-    /** ברירת מחדל: localStorage. */
+    /** Default: localStorage. */
     storage?: MacroStorage;
     /**
-     * `'iframe'` (ברירת המחדל) מריץ סקריפטים בארגז חול; `'eval'` מריץ ישירות —
-     * ראו את האזהרה ב-eval-runner. אפשר גם למסור מריץ מותאם.
+     * `'iframe'` (the default) runs scripts in a sandbox; `'eval'` runs them
+     * directly — see the warning in eval-runner. A custom runner can also be
+     * passed.
      */
     runner?: MacroRunner | 'iframe' | 'eval';
-    /** אפשרויות ריצה לסקריפטים (זמן, תקרת קריאות). */
+    /** Run options for scripts (time, call cap). */
     runOptions?: MacroRunOptions;
-    /** אפשרויות ההשלמה האוטומטית. */
+    /** Auto-text options. */
     autoText?: Omit<AutoTextOptions, 'onExpand' | 'onError'> & AutoTextOptions;
-    /** יומן ריצה של `api.log`. */
+    /** Run log for `api.log`. */
     onLog?: MacroApiOptions['onLog'];
+    /**
+     * Shortcuts the host already owns (e.g. its ribbon registry). A saved
+     * binding that collides with any of these is rejected — otherwise the
+     * macro binding, attached in the capture phase, would silently shadow an
+     * editor shortcut. Unparseable entries are ignored.
+     */
+    reservedShortcuts?: readonly string[];
 }
+export type ShortcutValidation = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
 export declare class MacroKit {
     private readonly host;
     private readonly storage;
@@ -40,8 +54,20 @@ export declare class MacroKit {
     private state;
     private readonly recorder;
     private readonly autoText;
+    private readonly reservedSignatures;
     private running;
     constructor(options: MacroKitOptions);
+    /**
+     * Whether a shortcut is acceptable for a saved binding: parseable, carries
+     * a real modifier, not reserved by the host, and not already used by
+     * another saved item (`excludeId` skips the item being edited). Empty or
+     * undefined means "no shortcut" and is fine. The save paths enforce this;
+     * UIs call it directly to show the message before saving.
+     */
+    validateShortcut(shortcut: string | undefined, excludeId?: string): ShortcutValidation;
+    private findShortcutOwner;
+    /** Throws a MacroError when the shortcut is unacceptable. The save paths call this. */
+    private requireValidShortcut;
     listScripts(): readonly SavedScript[];
     saveScript(input: {
         id?: string;
@@ -51,17 +77,17 @@ export declare class MacroKit {
     }): SavedScript;
     removeScript(id: string): void;
     runScript(id: string): Promise<MacroRunResult>;
-    /** מריצה סקריפט שלא נשמר — למשל מתוך עורך המאקרו לפני שמירה. */
+    /** Runs an unsaved script — e.g. from the macro editor before saving. */
     runSource(source: string): Promise<MacroRunResult>;
     get isRecording(): boolean;
     get recordedStepCount(): number;
     startRecording(): void;
-    /** עוצרת ושומרת. `null` כשלא הוקלט אף צעד — אין מה לשמור. */
+    /** Stops and saves. `null` when no step was recorded — there is nothing to save. */
     stopRecording(name: string, shortcut?: string): RecordedMacro | null;
     cancelRecording(): void;
     listRecordings(): readonly RecordedMacro[];
     removeRecording(id: string): void;
-    /** עדכון שם או קיצור של הקלטה קיימת. `null` כשההקלטה לא נמצאה. */
+    /** Renames a recording or edits its shortcut. `null` when the recording was not found. */
     updateRecording(input: {
         id: string;
         name?: string;
@@ -81,20 +107,22 @@ export declare class MacroKit {
         ok: boolean;
         message?: string;
     }>;
-    /** מפעילה השלמה אוטומטית (trigger + רווח). מחזירה פונקציית כיבוי. */
+    /** Enables auto-text (trigger + space). Returns a disable function. */
     enableAutoText(): () => void;
     disableAutoText(): void;
     /**
-     * קושרת את הקיצורים של כל מה ששמור (סקריפטים, הקלטות, קטעים) ליעד — בדרך
-     * כלל ה-container של העורך או `window`. הרשימה חיה: שמירה חדשה נקלטת בלי
-     * לקשור מחדש. מחזירה פונקציית ניתוק.
+     * Binds the shortcuts of everything saved (scripts, recordings, snippets)
+     * to a target — usually the editor container or `window`. The list is
+     * live: a new save is picked up without rebinding. Returns a dispose
+     * function.
      */
     attachShortcuts(target: ShortcutTarget): () => void;
     private currentBindings;
     exportState(): string;
     /**
-     * ייבוא מ-JSON שיוצא ב-`exportState`. במיזוג (`merge: true`) פריט מיובא עם
-     * `id` קיים מחליף את הקיים; בלי מיזוג המצב כולו מוחלף.
+     * Imports JSON produced by `exportState`. With `merge: true` an imported
+     * item with an existing `id` replaces it; without merge the whole state is
+     * replaced.
      */
     importState(json: string, options?: {
         merge?: boolean;