superdoc-macros 0.2.0 → 0.3.0

package/README.md

@@ -1,61 +1,54 @@
 # superdoc-macros
 
-ערכת מאקרו לעורכים מבוססי **SuperDoc v2**. נכתבה במקור עבור [otzaria-word-editor](https://github.com/Y-PLONI/otzaria-word-editor), אך כללית לחלוטין: אין תלות בו ואף לא בחבילת superdoc עצמה (החיבור למנוע מבני, דרך המשטחים הציבוריים שלו), והליבה עובדת מול כל עורך שמממש ממשק `MacroHost` קטן.
+A macro toolkit for **SuperDoc v2**-based editors. Originally built for [otzaria-word-editor](https://github.com/Y-PLONI/otzaria-word-editor), but fully generic: it has no dependency on that project — nor on the superdoc package itself (the engine is consumed structurally, through its public surfaces), and the core works against any editor that implements a small `MacroHost` interface.
 
-שלוש יכולות, בדומה למאקרו של Word:
+Three capabilities, in the spirit of Word macros:
 
-| יכולת | מה זה נותן |
+| Capability | What it gives you |
 | --- | --- |
-| **סקריפטים** | מאקרו כתובים ב-JavaScript שרצים בארגז חול (iframe מבודד) מול API מצומצם ובטוח של המסמך |
-| **מקליט מאקרו** | "הקלט → עשה פעולות → עצור → נגן" — מקליט פקודות והקלדה, כמו המקליט של Word |
-| **קטעי טקסט (Snippets)** | תבניות עם משתנים (`{{date}}`, `{{selection}}`…), קיצורי מקלדת, והשלמה אוטומטית בהקלדה (הקלדת `בסד` + רווח ← `בס"ד`) |
+| **Scripted macros** | User-written JavaScript macros that run in a real sandbox (an isolated iframe) against a small, safe document API |
+| **Macro recorder** | "Record → work normally → stop → replay" — records commands and typing, like Word's recorder |
+| **Snippets (AutoText)** | Templates with variables (`{{date}}`, `{{selection}}`…), keyboard shortcuts, and auto-expansion while typing (type a trigger word + space) |
 
-בנוסף: שמירה מתמשכת (localStorage או אחסון מותאם), ייבוא/ייצוא JSON, וקישור קיצורי מקלדת.
+Plus: persistence (localStorage or custom storage), JSON import/export, keyboard shortcut binding, and localizable runtime messages (English by default, Hebrew locale included).
 
-> **הערה על VBA:** החבילה אינה מריצה מאקרו VBA מתוך קובצי `.docm` — אין מנוע VBA בדפדפן. היא נותנת מערכת מאקרו מקבילה, מבוססת JavaScript, שמתאימה לעורך רץ-בדפדפן.
+> **A note on VBA:** the toolkit does not execute VBA macros from `.docm` files — there is no VBA engine in the browser. It provides a parallel, JavaScript-based macro system suited to a browser-hosted editor.
 
-## התקנה
+## Installation
 
 ```bash
 npm install superdoc-macros
 ```
 
-או ישירות מגיטהאב (עד הפרסום ב-npm):
-
-```bash
-npm install github:palmoni5/superdoc-macros
-```
-
-## התחלה מהירה (עם SuperDoc)
+## Quick start (with SuperDoc)
 
 ```ts
 import { MacroKit, createSuperdocHost } from 'superdoc-macros';
 
-// superdoc — מופע SuperDoc מוכן (אחרי onReady); container — האלמנט שהמסמך מרונדר בו.
+// superdoc — a ready SuperDoc instance (after onReady); container — the element the document renders in.
 const host = createSuperdocHost({ superdoc, container });
 const kit = new MacroKit({ host });
 
-// קיצורי מקלדת לכל מה ששמור, והשלמה אוטומטית:
+// Keyboard shortcuts for everything saved, and auto-text:
 const unbindKeys = kit.attachShortcuts(container);
 const disableAutoText = kit.enableAutoText();
 
-// בהחלפת מסמך / פירוק:
+// On document swap / teardown:
 unbindKeys();
 disableAutoText();
 host.dispose();
 ```
 
-## 1. מאקרו כתובים (סקריפטים)
+## 1. Scripted macros
 
-סקריפט מקבל אובייקט `api` וכל המתודות שלו א-סינכרוניות:
+A script receives an `api` object; every method is async:
 
 ```ts
 kit.saveScript({
-  name: 'כותרת דבר תורה',
+  name: 'Heading helper',
   shortcut: 'Ctrl+Alt+D',
   source: `
     await api.bold();
-    await api.insertText('בעניין ');
     const selected = await api.getSelectionText();
     if (selected) await api.insertText(selected);
     await api.bold();
@@ -67,91 +60,101 @@ const result = await kit.runScript(kit.listScripts()[0].id);
 if (!result.ok) console.warn(result.message);
 ```
 
-### ה-API שסקריפט מקבל
+### The script API
 
-| מתודה | תיאור |
+| Method | Description |
 | --- | --- |
-| `api.command(id, payload?)` | כל פקודה מקטלוג SuperDoc (`'text-align'`, `'font-size'`…). מחזירה `{ok}` ואינה זורקת |
-| `api.hasCommand(id)` / `api.commandIds()` | בירור יכולות |
-| `api.insertText(text)` / `api.insertParagraph()` | הכנסה במיקום הסמן |
-| `api.deleteBackward(count?)` | מחיקה לאחור |
-| `api.getSelection()` / `api.getSelectionText()` | הבחירה הנוכחית |
-| `api.getDocumentText()` | הטקסט המלא |
-| `api.replaceAll(find, replace)` | החלפה גורפת; מחזירה כמה הוחלפו |
-| `api.bold()` / `italic()` / `underline()` / `bulletList()` / `directionRtl()` … | סוכר לפקודות נפוצות — זורקות בכשל, כדי שהסקריפט ייעצר |
-| `api.log(...)` | יומן ריצה (מגיע ל-`onLog` של ה-Kit) |
+| `api.command(id, payload?)` | Any command from the SuperDoc catalog (`'text-align'`, `'font-size'`…). Returns `{ok}`, never throws |
+| `api.hasCommand(id)` / `api.commandIds()` | Capability discovery |
+| `api.insertText(text)` / `api.insertParagraph()` | Insert at the caret |
+| `api.deleteBackward(count?)` | Delete backwards |
+| `api.getSelection()` / `api.getSelectionText()` | The current selection |
+| `api.getDocumentText()` | The full document text |
+| `api.replaceAll(find, replace)` | Replace everywhere; returns the count |
+| `api.bold()` / `italic()` / `underline()` / `bulletList()` / `directionRtl()` … | Sugar for common commands — these throw on failure, so the script stops |
+| `api.log(...)` | Run log (delivered to the kit's `onLog`) |
 
-### אבטחה
+### Security
 
-ברירת המחדל היא **ארגז חול אמיתי**: הסקריפט רץ ב-iframe עם `sandbox="allow-scripts"` בלבד — origin אטום, בלי גישה ל-DOM של האפליקציה, ל-localStorage, ל-cookies או לרשת עם אישורי המשתמש. הדרך היחידה שלו לגעת במסמך היא ה-API שלמעלה, עם תקרת זמן (ברירת מחדל 30 שניות — נאכפת גם על לולאה אינסופית, ע"י הסרת ה-iframe) ותקרת קריאות (10,000).
+The default is a **real sandbox**: scripts run in an iframe with `sandbox="allow-scripts"` only — an opaque origin, no access to the application's DOM, localStorage, cookies, or credentialed network. The script's only way to touch the document is the API above, with a time cap (default 30 s — enforced even against infinite loops, by removing the iframe) and a call cap (10,000).
 
-מי שחייב לוותר על הבידוד (למשל CSP שחוסם `srcdoc`) יכול לעבור למריץ ישיר: `new MacroKit({ host, runner: 'eval' })` — ראו האזהרות בקוד.
+If you must waive isolation (e.g. a CSP that blocks `srcdoc`), switch to the direct runner: `new MacroKit({ host, runner: 'eval' })` — see the warnings in the code.
 
-## 2. מקליט מאקרו
+## 2. Macro recorder
 
 ```ts
 kit.startRecording();
-// המשתמש עובד רגיל: מקליד, מדגיש, ממספר...
-const recording = kit.stopRecording('פתיח סטנדרטי', 'Ctrl+Alt+1');
+// the user works normally: typing, formatting, lists...
+const recording = kit.stopRecording('Standard intro', 'Ctrl+Alt+1');
 
-// מאוחר יותר, מכל מקום במסמך:
+// later, from anywhere in the document:
 await kit.replayRecording(recording.id);
 ```
 
-המקליט מתעד **פקודות והקלדה**, לא מיקומי סמן — בדיוק כמו המקליט של Word: הניגון חל במקום שבו הסמן עומד. הקשות רצופות מתלכדות לצעד אחד, `undo`/`redo` אינם מוקלטים (ניתן לשינוי ב-`RecorderOptions`), וההקלטה נשמרת כ-JSON נקי שאפשר לייצא ולשתף.
+The recorder captures **commands and typing**, not caret positions — exactly like Word's recorder: replay applies wherever the caret stands. Consecutive keystrokes coalesce into one step, `undo`/`redo` are not recorded (configurable via `RecorderOptions`), and recordings persist as clean JSON that can be exported and shared. `updateRecording({id, name?, shortcut?})` renames a recording or edits its shortcut.
 
-## 3. קטעי טקסט והשלמה אוטומטית
+## 3. Snippets and auto-text
 
 ```ts
-kit.saveSnippet({ name: 'בס"ד', text: 'בס"ד', trigger: 'בסד' });
+kit.saveSnippet({ name: 'BSD', text: 'בס"ד', trigger: 'בסד' });
 kit.saveSnippet({
-  name: 'חתימה',
-  text: 'ונשלם בעז"ה, {{date}}',
+  name: 'Signature',
+  text: 'Best regards, {{date}}',
   shortcut: 'Ctrl+Alt+S',
 });
-kit.saveSnippet({ name: 'ציטוט', text: '(עיין {{selection}})' });
+kit.saveSnippet({ name: 'Citation', text: '(see {{selection}})' });
 
-kit.enableAutoText();          // מעכשיו: הקלדת "בסד" + רווח ⟵ בס"ד
-await kit.expandSnippet(id);   // או הרחבה יזומה / דרך הקיצור
+kit.enableAutoText();          // from now on: typing the trigger + space expands it
+await kit.expandSnippet(id);   // or expand explicitly / via the shortcut
 ```
 
-משתנים מובנים: `{{date}}`, `{{time}}`, `{{datetime}}` (עברית), `{{selection}}`. כל שם אחר נפתר מ-`variables` שנמסרו ל-`expandSnippet`; משתנה ללא ערך נשאר גלוי בטקסט.
+Built-in variables: `{{date}}`, `{{time}}`, `{{datetime}}` (formatted with the browser locale, or an explicit `locale` option), `{{selection}}`. Any other name resolves from the `variables` passed to `expandSnippet`; a variable with no value stays visible in the text.
+
+## Localization
+
+Runtime messages (failures shown to end users) default to English. A host with a localized UI swaps them once at startup:
+
+```ts
+import { setMacroMessages, HEBREW_MESSAGES } from 'superdoc-macros';
+
+setMacroMessages(HEBREW_MESSAGES);          // full Hebrew locale (included)
+setMacroMessages({ scriptNotFound: '…' });  // or a partial override
+```
 
-## שמירה, ייבוא וייצוא
+## Persistence, import and export
 
 ```ts
 import { createLocalStorage } from 'superdoc-macros';
 
 const kit = new MacroKit({ host, storage: createLocalStorage('my-key') });
 
-const json = kit.exportState();       // גיבוי / שיתוף
+const json = kit.exportState();       // backup / sharing
 kit.importState(json, { merge: true });
 ```
 
-`MacroStorage` הוא ממשק בן שתי מתודות — אפשר לממש שמירה לקובץ (למשל ב-workspace של תוסף אוצריא).
+`MacroStorage` is a two-method interface — implement it to persist to a file (e.g. a plugin workspace).
 
-## חיבור למארח אחר
+## Connecting a different host
 
-כל הערכה עובדת מול ממשק `MacroHost` אחד (פקודות, הכנסת טקסט, בחירה, החלפה, אירועי הקלדה). `createSuperdocHost` הוא המימוש ל-SuperDoc v2 במצב `ui: false`; עורך אחר מתחבר במימוש משלו של הממשק — ראו `src/types.ts` ואת הכפיל ב-`tests/fake-host.ts`.
+The whole toolkit works against a single `MacroHost` interface (commands, text insertion, selection, replace, typing events). `createSuperdocHost` is the implementation for SuperDoc v2 in `ui: false` mode; another editor plugs in with its own implementation — see `src/types.ts` and the double in `tests/fake-host.ts`.
 
-## מגבלות ידועות
+## Known limitations
 
-- אין הרצת VBA. קובצי `.docm` נפתחים כרגיל אבל המאקרו שבהם אינו מורץ.
-- המקליט אינו מתעד תנועת סמן ובחירה בעכבר (כמו ב-Word — הניגון פועל מהסמן הנוכחי).
-- `deleteBackward` וטקסט-מלא-של-המסמך משתמשים ב-view הפנימי של המנוע (ProseMirror) — זמינים בדפדפן, לא ב-headless.
-- תקרת הזמן במריץ `eval` אינה עוצרת לולאה סינכרונית אינסופית (במריץ ה-iframe — כן).
+- No VBA execution. `.docm` files open normally but their macros are not run.
+- The recorder does not capture caret movement or mouse selection (as in Word — replay acts from the current caret).
+- `deleteBackward` and full-document text use the engine's internal view (ProseMirror) — available in the browser, not headless.
+- The `eval` runner's time cap cannot stop an infinite synchronous loop (the iframe runner's can).
 
-## פיתוח
+## Development
 
 ```bash
 npm install
-npm test        # vitest — 43 בדיקות
-npm run build   # tsc ⟵ dist/
+npm test        # vitest
+npm run build   # tsc → dist/
 ```
 
-**שחרור גרסה:** מעלים את `version` ב-package.json ודוחפים ל-main — ה-workflow
-(‎.github/workflows/release.yml) מפרסם ל-npm ויוצר GitHub Release אוטומטית.
+**Releasing:** bump `version` in package.json and push to main — the workflow (.github/workflows/release.yml) publishes to npm and creates a GitHub Release automatically.
 
-## רישיון
+## License
 
 MIT

package/dist/host/superdoc-host.d.ts

@@ -1,22 +1,3 @@
-/**
- * מימוש `MacroHost` מעל SuperDoc v2 במצב מנוע-בלבד (`ui: false`) — הקונפיגורציה
- * של otzaria-word-editor.
- *
- * המשטחים שבשימוש, לפי סדר עדיפות:
- *   1. `superdoc.ui.commands` — קטלוג הפקודות של ה-controller (הרצה + תצפית).
- *   2. `superdoc.activeEditor.doc` — ה-Document API הציבורי (בחירה, הכנסה, בלוקים).
- *   3. `superdoc.ui.search` — חיפוש/החלפה.
- *   4. `superdoc.activeEditor.view` — מופע ProseMirror הפנימי, **רק** לפערים
- *      שאין להם משטח ציבורי: מחיקה לאחור וטקסט מלא של המסמך. קיים בדפדפן
- *      ו-null ב-headless.
- *
- * הטיפוסים כאן מבניים (structural) ואינם מייבאים מ-superdoc: הערכה לא תלויה
- * בחבילה, וגרסת מנוע שמשנה שדה תיכשל סגור (הפונקציה תחזיר כשל) ולא תקרוס.
- *
- * תצפית הפקודות למקליט נעשית בעטיפת `executeAsync` על אובייקט ה-commands.
- * זה מכסה כל מסלול שקורא לו — כולל ה-CommandAdapter של otzaria — בלי לשנות
- * את הקוד הקורא. `dispose()` מחזיר את המתודה המקורית.
- */
 import type { MacroHost } from '../types.js';
 interface CommandStateLike {
     reason?: string;
@@ -119,11 +100,11 @@ export interface SuperdocLike {
 }
 export interface SuperdocHostOptions {
     superdoc: SuperdocLike;
-    /** האלמנט שהמסמך מרונדר בתוכו — עליו נקלטים אירועי ההקלדה. */
+    /** The element the document renders in — typing events are captured on it. */
     container?: HTMLElement | null;
 }
 export interface SuperdocMacroHost extends MacroHost {
-    /** מסירה את עטיפת התצפית ואת מאזיני ה-DOM. לקרוא לפני החלפת מסמך. */
+    /** Removes the observation wrapper and the DOM listeners. Call before swapping documents. */
     dispose(): void;
 }
 export declare function createSuperdocHost(options: SuperdocHostOptions): SuperdocMacroHost;

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,17 +40,17 @@ 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 מוחלף בכל פתיחת מסמך.
+    // 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;
     const commandListeners = new Set();
     const inputListeners = new Set();
-    /* תצפית פקודות: עטיפת executeAsync, פעם אחת, עם שחזור ב-dispose. */
+    /* Command observation: wrap executeAsync, once, restored on dispose. */
     const wrapped = commands();
     const originalExecuteAsync = wrapped?.executeAsync;
     if (wrapped && originalExecuteAsync) {
@@ -36,13 +60,13 @@ export function createSuperdocHost(options) {
                     listener(id, payload);
                 }
                 catch (error) {
-                    console.warn('[superdoc-macros] מאזין פקודות זרק', error);
+                    console.warn('[superdoc-macros] command listener threw', error);
                 }
             }
             return originalExecuteAsync.call(wrapped, id, payload);
         };
     }
-    /* הקלדה: beforeinput על ה-container, בשלב הלכידה. */
+    /* Typing: beforeinput on the container, capture phase. */
     const onBeforeInput = (event) => {
         const input = event;
         let mapped = null;
@@ -72,7 +96,7 @@ export function createSuperdocHost(options) {
                 listener(mapped);
             }
             catch (error) {
-                console.warn('[superdoc-macros] מאזין הקלדה זרק', error);
+                console.warn('[superdoc-macros] input listener threw', error);
             }
         }
     };
@@ -119,23 +143,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,7 +167,7 @@ export function createSuperdocHost(options) {
         async insertText(text) {
             const insert = doc()?.insert;
             if (typeof insert === 'function') {
-                // בלי target ההכנסה נופלת לסוף המסמך — לכן היעד נלקח מהבחירה החיה.
+                // Without a target the insertion falls to the end of the document — so the target comes from the live selection.
                 const snapshot = await readSelection(false);
                 try {
                     const receipt = await insert({
@@ -151,13 +175,13 @@ export function createSuperdocHost(options) {
                         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 +192,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,7 +213,7 @@ 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');
             }
         },
         getSelection(options) {
@@ -198,24 +222,28 @@ export function createSuperdocHost(options) {
         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 +251,7 @@ export function createSuperdocHost(options) {
                     handle.close?.();
                 }
                 catch {
-                    /* ניקוי בלבד */
+                    /* cleanup only */
                 }
             }
         },

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

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';

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,18 +17,19 @@ 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'];
 }
 export declare class MacroKit {
@@ -51,17 +52,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 +82,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;