superdoc-macros 0.2.0 → 0.3.0

package/dist/manager.js

@@ -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 { createMacroApi } from './scripting/macro-api.js';
 import { createEvalRunner } from './scripting/eval-runner.js';
@@ -15,6 +15,7 @@ import { AutoText } from './snippets/autotext.js';
 import { expandSnippet } from './snippets/snippets.js';
 import { bindShortcuts } from './shortcuts.js';
 import { createLocalStorage, emptyState, parsePersistedState } from './storage.js';
+import { macroMessages } from './messages.js';
 let idCounter = 0;
 function newId() {
     try {
@@ -47,7 +48,7 @@ export class MacroKit {
         this.recorder = new MacroRecorder(this.host);
         this.autoText = new AutoText(this.host, () => this.state.snippets, options.autoText);
     }
-    /* ---------- סקריפטים ---------- */
+    /* ---------- Scripts ---------- */
     listScripts() {
         return this.state.scripts;
     }
@@ -69,10 +70,10 @@ export class MacroKit {
     async runScript(id) {
         const script = this.state.scripts.find((entry) => entry.id === id);
         if (!script)
-            return { ok: false, reason: 'error', message: 'המאקרו לא נמצא' };
+            return { ok: false, reason: 'error', message: macroMessages().scriptNotFound };
         return this.runSource(script.source);
     }
-    /** מריצה סקריפט שלא נשמר — למשל מתוך עורך המאקרו לפני שמירה. */
+    /** Runs an unsaved script — e.g. from the macro editor before saving. */
     async runSource(source) {
         const guard = this.guardRun();
         if (guard)
@@ -86,7 +87,7 @@ export class MacroKit {
             this.running = false;
         }
     }
-    /* ---------- מקליט ---------- */
+    /* ---------- Recorder ---------- */
     get isRecording() {
         return this.recorder.recording;
     }
@@ -98,7 +99,7 @@ export class MacroKit {
             return;
         this.recorder.start();
     }
-    /** עוצרת ושומרת. `null` כשלא הוקלט אף צעד — אין מה לשמור. */
+    /** Stops and saves. `null` when no step was recorded — there is nothing to save. */
     stopRecording(name, shortcut) {
         const steps = this.recorder.stop();
         if (steps.length === 0)
@@ -125,7 +126,7 @@ export class MacroKit {
         this.state.recordings = this.state.recordings.filter((recording) => recording.id !== id);
         this.persist();
     }
-    /** עדכון שם או קיצור של הקלטה קיימת. `null` כשההקלטה לא נמצאה. */
+    /** Renames a recording or edits its shortcut. `null` when the recording was not found. */
     updateRecording(input) {
         const recording = this.state.recordings.find((entry) => entry.id === input.id);
         if (!recording)
@@ -143,8 +144,13 @@ export class MacroKit {
     }
     async replayRecording(id, options) {
         const recording = this.state.recordings.find((entry) => entry.id === id);
-        if (!recording)
-            return { ok: false, completed: 0, failures: [{ stepIndex: -1, step: { type: 'insert-text', text: '' }, message: 'ההקלטה לא נמצאה' }] };
+        if (!recording) {
+            return {
+                ok: false,
+                completed: 0,
+                failures: [{ stepIndex: -1, step: { type: 'insert-text', text: '' }, message: macroMessages().recordingNotFound }],
+            };
+        }
         const guard = this.guardRun();
         if (guard) {
             return { ok: false, completed: 0, failures: [{ stepIndex: -1, step: { type: 'insert-text', text: '' }, message: guard.message }] };
@@ -157,7 +163,7 @@ export class MacroKit {
             this.running = false;
         }
     }
-    /* ---------- קטעי טקסט ---------- */
+    /* ---------- Snippets ---------- */
     listSnippets() {
         return this.state.snippets;
     }
@@ -180,22 +186,23 @@ export class MacroKit {
     async expandSnippet(id, options) {
         const snippet = this.state.snippets.find((entry) => entry.id === id);
         if (!snippet)
-            return { ok: false, message: 'הקטע לא נמצא' };
+            return { ok: false, message: macroMessages().snippetNotFound };
         const outcome = await expandSnippet(this.host, snippet, options);
         return outcome.ok ? { ok: true } : { ok: false, message: outcome.message };
     }
-    /** מפעילה השלמה אוטומטית (trigger + רווח). מחזירה פונקציית כיבוי. */
+    /** Enables auto-text (trigger + space). Returns a disable function. */
     enableAutoText() {
         return this.autoText.attach();
     }
     disableAutoText() {
         this.autoText.detach();
     }
-    /* ---------- קיצורי מקלדת ---------- */
+    /* ---------- Keyboard shortcuts ---------- */
     /**
-     * קושרת את הקיצורים של כל מה ששמור (סקריפטים, הקלטות, קטעים) ליעד — בדרך
-     * כלל ה-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) {
         return bindShortcuts(target, () => this.currentBindings());
@@ -216,18 +223,19 @@ export class MacroKit {
         }
         return bindings;
     }
-    /* ---------- ייבוא/ייצוא ---------- */
+    /* ---------- Import/export ---------- */
     exportState() {
         return JSON.stringify(this.state, null, 2);
     }
     /**
-     * ייבוא מ-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, options = {}) {
         const imported = parsePersistedState(json);
         if (!imported)
-            return { ok: false, message: 'הקובץ אינו ייצוא מאקרו תקין' };
+            return { ok: false, message: macroMessages().invalidImport };
         if (options.merge) {
             for (const script of imported.scripts)
                 this.upsert(this.state.scripts, script);
@@ -242,13 +250,13 @@ export class MacroKit {
         this.persist();
         return { ok: true };
     }
-    /* ---------- פנימי ---------- */
+    /* ---------- Internal ---------- */
     guardRun() {
         if (this.recorder.recording) {
-            return { ok: false, reason: 'error', message: 'אי אפשר להריץ מאקרו בזמן הקלטה' };
+            return { ok: false, reason: 'error', message: macroMessages().cannotRunWhileRecording };
         }
         if (this.running) {
-            return { ok: false, reason: 'error', message: 'מאקרו אחר עדיין רץ' };
+            return { ok: false, reason: 'error', message: macroMessages().anotherMacroRunning };
         }
         return null;
     }

package/dist/messages.d.ts

@@ -0,0 +1,50 @@
+/**
+ * All user-facing runtime strings, in one place.
+ *
+ * The toolkit reports failures to end users (status bars, dialogs), so the
+ * strings are part of the product, not debug output. Defaults are English;
+ * a host with a localized UI swaps them once at startup:
+ *
+ * ```ts
+ * import { setMacroMessages, HEBREW_MESSAGES } from 'superdoc-macros';
+ * setMacroMessages(HEBREW_MESSAGES);
+ * ```
+ *
+ * A module-level locale rather than per-instance options, deliberately: the
+ * strings surface from many layers (API, runners, host adapter, manager),
+ * and threading an options object through all of them would make every
+ * factory signature about localization. One UI language per page is the
+ * reality these editors live in.
+ */
+export interface MacroMessages {
+    unknownMethod: (method: string) => string;
+    mustBeString: (name: string) => string;
+    commandFailed: (id: string) => string;
+    insertTextFailed: string;
+    insertParagraphFailed: string;
+    deleteFailed: string;
+    replaceFailed: string;
+    syntaxError: (detail: string) => string;
+    timedOut: (seconds: number) => string;
+    callLimitExceeded: (limit: number) => string;
+    deleteForwardUnsupported: string;
+    scriptNotFound: string;
+    recordingNotFound: string;
+    snippetNotFound: string;
+    cannotRunWhileRecording: string;
+    anotherMacroRunning: string;
+    invalidImport: string;
+    noDocument: string;
+    unknownCommand: (id: string) => string;
+    actionFailed: string;
+    deletionUnavailable: string;
+    searchUnavailable: string;
+    searchUnavailableInDocument: string;
+}
+export declare const ENGLISH_MESSAGES: MacroMessages;
+/** Hebrew locale — the strings the toolkit shipped with originally. */
+export declare const HEBREW_MESSAGES: MacroMessages;
+/** Replaces some or all runtime strings. Call once, before creating hosts/kits. */
+export declare function setMacroMessages(messages: Partial<MacroMessages>): void;
+/** The active locale. Internal — modules read strings through this. */
+export declare function macroMessages(): MacroMessages;

package/dist/messages.js

@@ -0,0 +1,78 @@
+/**
+ * All user-facing runtime strings, in one place.
+ *
+ * The toolkit reports failures to end users (status bars, dialogs), so the
+ * strings are part of the product, not debug output. Defaults are English;
+ * a host with a localized UI swaps them once at startup:
+ *
+ * ```ts
+ * import { setMacroMessages, HEBREW_MESSAGES } from 'superdoc-macros';
+ * setMacroMessages(HEBREW_MESSAGES);
+ * ```
+ *
+ * A module-level locale rather than per-instance options, deliberately: the
+ * strings surface from many layers (API, runners, host adapter, manager),
+ * and threading an options object through all of them would make every
+ * factory signature about localization. One UI language per page is the
+ * reality these editors live in.
+ */
+export const ENGLISH_MESSAGES = {
+    unknownMethod: (method) => `Unknown method: ${method}`,
+    mustBeString: (name) => `${name} must be a string`,
+    commandFailed: (id) => `Command ${id} failed`,
+    insertTextFailed: 'Failed to insert text',
+    insertParagraphFailed: 'Failed to insert paragraph',
+    deleteFailed: 'Delete failed',
+    replaceFailed: 'Replace failed',
+    syntaxError: (detail) => `Macro syntax error: ${detail}`,
+    timedOut: (seconds) => `The macro did not finish within ${seconds} seconds and was stopped`,
+    callLimitExceeded: (limit) => `The macro exceeded the API call limit (${limit}) and was stopped`,
+    deleteForwardUnsupported: 'Forward deletion is not supported during replay',
+    scriptNotFound: 'Macro not found',
+    recordingNotFound: 'Recording not found',
+    snippetNotFound: 'Snippet not found',
+    cannotRunWhileRecording: 'Cannot run a macro while recording',
+    anotherMacroRunning: 'Another macro is still running',
+    invalidImport: 'The file is not a valid macro export',
+    noDocument: 'No document is open',
+    unknownCommand: (id) => `The engine does not recognize the command ${id}`,
+    actionFailed: 'The operation failed',
+    deletionUnavailable: 'Deletion is not available in this document',
+    searchUnavailable: 'Search is not available',
+    searchUnavailableInDocument: 'Search is not available in this document',
+};
+/** Hebrew locale — the strings the toolkit shipped with originally. */
+export const HEBREW_MESSAGES = {
+    unknownMethod: (method) => `מתודה לא מוכרת: ${method}`,
+    mustBeString: (name) => `${name} חייב להיות מחרוזת`,
+    commandFailed: (id) => `הפקודה ${id} נכשלה`,
+    insertTextFailed: 'הכנסת הטקסט נכשלה',
+    insertParagraphFailed: 'הכנסת הפסקה נכשלה',
+    deleteFailed: 'המחיקה נכשלה',
+    replaceFailed: 'ההחלפה נכשלה',
+    syntaxError: (detail) => `שגיאת תחביר במאקרו: ${detail}`,
+    timedOut: (seconds) => `המאקרו לא הסתיים תוך ${seconds} שניות ונעצר`,
+    callLimitExceeded: (limit) => `המאקרו חצה את תקרת הקריאות (${limit}) ונעצר`,
+    deleteForwardUnsupported: 'מחיקה קדימה אינה נתמכת בניגון',
+    scriptNotFound: 'המאקרו לא נמצא',
+    recordingNotFound: 'ההקלטה לא נמצאה',
+    snippetNotFound: 'הקטע לא נמצא',
+    cannotRunWhileRecording: 'אי אפשר להריץ מאקרו בזמן הקלטה',
+    anotherMacroRunning: 'מאקרו אחר עדיין רץ',
+    invalidImport: 'הקובץ אינו ייצוא מאקרו תקין',
+    noDocument: 'אין מסמך פתוח',
+    unknownCommand: (id) => `הפקודה ${id} אינה מוכרת למנוע`,
+    actionFailed: 'הפעולה נכשלה',
+    deletionUnavailable: 'מחיקה אינה זמינה במסמך הזה',
+    searchUnavailable: 'החיפוש אינו זמין',
+    searchUnavailableInDocument: 'החיפוש אינו זמין במסמך הזה',
+};
+let current = { ...ENGLISH_MESSAGES };
+/** Replaces some or all runtime strings. Call once, before creating hosts/kits. */
+export function setMacroMessages(messages) {
+    current = { ...current, ...messages };
+}
+/** The active locale. Internal — modules read strings through this. */
+export function macroMessages() {
+    return current;
+}

package/dist/recorder/recorder.d.ts

@@ -1,20 +1,8 @@
-/**
- * מקליט מאקרו בסגנון Word: מקליט **פקודות** והקלדה, לא מיקומי סמן.
- *
- * הבחירה הזאת מכוונת. הקלטת צעדי ProseMirror גולמיים (עם מיקומים אבסולוטיים)
- * נשברת ברגע שהמסמך שונה ממה שהיה בזמן ההקלטה; הקלטת פקודות ("bold",
- * "bullet-list", הקלדת "בס\"ד") מתנהגת כמו המקליט של Word — הפעולות חלות
- * במקום שבו הסמן נמצא בזמן הניגון. זה גם מה שהופך הקלטה לניתנת לשמירה
- * ולשיתוף: הצעדים JSON בלבד.
- *
- * מה לא נקלט: תנועת סמן ובחירה בעכבר. כמו ב-Word, מאקרו מוקלט פועל מהמקום
- * שבו הסמן עומד כשמריצים אותו.
- */
 import type { MacroHost, MacroStep } from '../types.js';
 export interface RecorderOptions {
-    /** סינון פקודות. ברירת המחדל מקליטה הכול חוץ מ-undo/redo. */
+    /** Command filter. The default records everything except undo/redo. */
     shouldRecordCommand?: (id: string) => boolean;
-    /** תקרת צעדים להקלטה אחת, נגד הקלטה שנשכחה פתוחה. */
+    /** Step cap per recording, against a recording left running by mistake. */
     maxSteps?: number;
 }
 export declare class MacroRecorder {
@@ -28,9 +16,9 @@ export declare class MacroRecorder {
     get recording(): boolean;
     get stepCount(): number;
     start(): void;
-    /** עוצרת ומחזירה את הצעדים. ריקה כשלא הוקלט דבר. */
+    /** Stops and returns the steps. Empty when nothing was recorded. */
     stop(): MacroStep[];
-    /** עוצרת וזורקת את מה שהוקלט. */
+    /** Stops and discards whatever was recorded. */
     cancel(): void;
     private teardown;
     private push;
@@ -44,14 +32,14 @@ export interface ReplayFailure {
 }
 export interface ReplayResult {
     ok: boolean;
-    /** כמה צעדים הושלמו בהצלחה. */
+    /** How many steps completed successfully. */
     completed: number;
     failures: ReplayFailure[];
 }
 export interface ReplayOptions {
-    /** עצירה בכשל הראשון. ברירת מחדל: true — מאקרו שנכשל באמצע לא ממשיך לרוץ עיוור. */
+    /** Stop at the first failure. Default: true — a macro that failed midway must not keep running blind. */
     stopOnError?: boolean;
-    /** נקראת לפני כל צעד; מאפשרת מד התקדמות. */
+    /** Called before each step; enables a progress indicator. */
     onStep?: (index: number, step: MacroStep) => void;
 }
 export declare function replayMacro(host: MacroHost, steps: readonly MacroStep[], options?: ReplayOptions): Promise<ReplayResult>;

package/dist/recorder/recorder.js

@@ -1,5 +1,20 @@
+/**
+ * A Word-style macro recorder: records **commands** and typing, not caret
+ * positions.
+ *
+ * That choice is deliberate. Recording raw ProseMirror steps (with absolute
+ * positions) breaks the moment the document differs from what it was at
+ * recording time; recording commands ("bold", "bullet-list", typing a
+ * greeting) behaves like Word's recorder — the actions apply wherever the
+ * caret is at replay time. It is also what makes a recording saveable and
+ * shareable: the steps are plain JSON.
+ *
+ * What is not recorded: caret movement and mouse selection. As in Word, a
+ * recorded macro acts from wherever the caret stands when it runs.
+ */
+import { macroMessages } from '../messages.js';
 const DEFAULT_MAX_STEPS = 5_000;
-/** undo/redo בזמן הקלטה מתקנים את ההקלטה עצמה — ניגון שלהם היה משחזר גם את הטעות. */
+/** Undo/redo during recording fix the recording itself — replaying them would replay the mistake too. */
 function defaultShouldRecord(id) {
     return id !== 'undo' && id !== 'redo';
 }
@@ -31,7 +46,7 @@ export class MacroRecorder {
             this.host.onTextInput((event) => this.recordTextInput(event)),
         ];
     }
-    /** עוצרת ומחזירה את הצעדים. ריקה כשלא הוקלט דבר. */
+    /** Stops and returns the steps. Empty when nothing was recorded. */
     stop() {
         if (!this.active)
             return [];
@@ -40,7 +55,7 @@ export class MacroRecorder {
         this.steps = [];
         return recorded;
     }
-    /** עוצרת וזורקת את מה שהוקלט. */
+    /** Stops and discards whatever was recorded. */
     cancel() {
         if (!this.active)
             return;
@@ -68,7 +83,7 @@ export class MacroRecorder {
         const last = this.steps[this.steps.length - 1];
         switch (event.kind) {
             case 'insert-text': {
-                // הקשות רצופות מתלכדות לצעד אחד — גם קריא יותר וגם ניגון מהיר יותר.
+                // Consecutive keystrokes coalesce into one step — more readable, faster to replay.
                 if (last?.type === 'insert-text') {
                     last.text += event.text;
                     return;
@@ -109,8 +124,8 @@ async function runStep(host, step) {
         case 'delete-backward':
             return host.deleteBackward(step.count);
         case 'delete-forward':
-            // המנוע אינו חושף מחיקה קדימה נפרדת; מדווח ככשל מפורש ולא מדלג בשקט.
-            return { ok: false, message: 'מחיקה קדימה אינה נתמכת בניגון', reason: 'unsupported-step' };
+            // The engine exposes no separate forward deletion; report an explicit failure rather than skipping silently.
+            return { ok: false, message: macroMessages().deleteForwardUnsupported, reason: 'unsupported-step' };
     }
 }
 export async function replayMacro(host, steps, options = {}) {

package/dist/scripting/eval-runner.d.ts

@@ -1,16 +1,5 @@
-/**
- * מריץ סקריפטים ישיר — `AsyncFunction` באותו הקשר של הדף.
- *
- * **אינו ארגז חול.** סקריפט שרץ כאן מקבל גישה לכל מה שהדף מכיר. מיועד לשני
- * מצבים: בדיקות, וסביבה שבה כל המאקרו נכתבים בידי המשתמש עצמו והוחלט
- * במפורש לוותר על בידוד (למשל בגלל CSP שחוסם iframe). ברירת המחדל של
- * `MacroKit` היא מריץ ה-iframe.
- *
- * תקרת הזמן כאן היא race על ההבטחה בלבד: לולאה סינכרונית אינסופית תחסום את
- * ה-thread ולא תיעצר. תקרת הקריאות כן נאכפת, דרך ה-bridge.
- */
 import type { MacroBridge } from './macro-api.js';
 import { type MacroRunner } from './runner.js';
-/** עוטפת bridge בתקרת קריאות. חשופה כדי ששני המריצים ישתמשו באותה אכיפה. */
+/** Wraps a bridge with a call cap. Exposed so both runners share the same enforcement. */
 export declare function limitCalls(bridge: MacroBridge, maxCalls: number): MacroBridge;
 export declare function createEvalRunner(): MacroRunner;

package/dist/scripting/eval-runner.js

@@ -1,21 +1,35 @@
+/**
+ * Direct script runner — `AsyncFunction` in the page's own context.
+ *
+ * **Not a sandbox.** A script running here can reach everything the page
+ * can. It exists for two situations: tests, and environments where every
+ * macro is written by the user themselves and isolation was explicitly
+ * waived (e.g. a CSP that blocks iframes). `MacroKit` defaults to the
+ * iframe runner.
+ *
+ * The time cap here is only a race on the promise: an infinite synchronous
+ * loop blocks the thread and will not be stopped. The call cap is enforced
+ * for real, through the bridge.
+ */
+import { macroMessages } from '../messages.js';
 import { DEFAULT_MAX_API_CALLS, DEFAULT_TIMEOUT_MS, } from './runner.js';
 const AsyncFunction = Object.getPrototypeOf(async function () {
-    /* טיפוס בלבד */
+    /* type only */
 }).constructor;
-/** עוטפת bridge בתקרת קריאות. חשופה כדי ששני המריצים ישתמשו באותה אכיפה. */
+/** Wraps a bridge with a call cap. Exposed so both runners share the same enforcement. */
 export function limitCalls(bridge, maxCalls) {
     return {
         api: bridge.api,
         callCount: bridge.callCount,
         call(method, args) {
             if (bridge.callCount() >= maxCalls) {
-                return Promise.reject(new Error(`המאקרו חצה את תקרת הקריאות (${maxCalls}) ונעצר`));
+                return Promise.reject(new Error(macroMessages().callLimitExceeded(maxCalls)));
             }
             return bridge.call(method, args);
         },
     };
 }
-/** proxy של api שמנתב הכול דרך `bridge.call`, כדי שהתקרה תיאכף גם כאן. */
+/** An api proxy that routes everything through `bridge.call`, so the cap applies here too. */
 function apiThroughBridge(bridge) {
     return new Proxy({}, {
         get(_target, method) {
@@ -38,12 +52,12 @@ export function createEvalRunner() {
                 return {
                     ok: false,
                     reason: 'error',
-                    message: `שגיאת תחביר במאקרו: ${error instanceof Error ? error.message : String(error)}`,
+                    message: macroMessages().syntaxError(error instanceof Error ? error.message : String(error)),
                 };
             }
             let timer;
             const timeout = new Promise((resolve) => {
-                timer = setTimeout(() => resolve({ ok: false, reason: 'timeout', message: `המאקרו לא הסתיים תוך ${timeoutMs / 1000} שניות ונעצר` }), timeoutMs);
+                timer = setTimeout(() => resolve({ ok: false, reason: 'timeout', message: macroMessages().timedOut(timeoutMs / 1000) }), timeoutMs);
             });
             const run = (async () => {
                 try {

package/dist/scripting/iframe-runner.d.ts

@@ -1,5 +1,5 @@
 import { type MacroRunner } from './runner.js';
-/** סימון ההודעות של הפרוטוקול, כדי לא להתנגש בהודעות אחרות בדף. */
+/** Protocol marker, so the messages cannot collide with others on the page. */
 export declare const PROTOCOL_MARK: "__otzariaMacro";
 export type SandboxMessage = {
     [PROTOCOL_MARK]: true;
@@ -31,11 +31,12 @@ export type HostMessage = {
     value?: unknown;
     message?: string;
 };
-/** האם הודעה שייכת לפרוטוקול. חשופה לבדיקות. */
+/** Whether a message belongs to the protocol. Exposed for tests. */
 export declare function isProtocolMessage(data: unknown): data is SandboxMessage;
 /**
- * הקוד שרץ בתוך ה-iframe. מחרוזת ולא פונקציה מוסרלת — כדי שה-build לא ישנה
- * אותו (minify של שמות היה שובר את הפרוטוקול).
+ * The code that runs inside the iframe. A string rather than a serialized
+ * function, so the build cannot touch it (minifying names would break the
+ * protocol).
  */
 export declare const SANDBOX_BOOTSTRAP: string;
 export declare function createIframeRunner(doc?: Document): MacroRunner;

package/dist/scripting/iframe-runner.js

@@ -1,8 +1,26 @@
+/**
+ * Sandboxed script runner — an iframe with `sandbox="allow-scripts"` only.
+ *
+ * The iframe gets an opaque origin: no access to the page's DOM, to
+ * localStorage, to cookies, or to the network with the user's credentials.
+ * Its only way to touch the document is RPC over postMessage to the
+ * `MacroApi` methods — every call goes through `bridge.call`, which enforces
+ * a closed method list and a call cap.
+ *
+ * The time cap here is real: when it expires the iframe is removed from the
+ * DOM, which also kills an infinite synchronous loop — it runs on the
+ * iframe's event loop, not the page's.
+ *
+ * Return values and arguments cross a structured-clone boundary; the API is
+ * already shaped so everything it returns is JSON-safe (see
+ * `ScriptSelection`).
+ */
+import { macroMessages } from '../messages.js';
 import { limitCalls } from './eval-runner.js';
 import { DEFAULT_MAX_API_CALLS, DEFAULT_TIMEOUT_MS, } from './runner.js';
-/** סימון ההודעות של הפרוטוקול, כדי לא להתנגש בהודעות אחרות בדף. */
+/** Protocol marker, so the messages cannot collide with others on the page. */
 export const PROTOCOL_MARK = '__otzariaMacro';
-/** האם הודעה שייכת לפרוטוקול. חשופה לבדיקות. */
+/** Whether a message belongs to the protocol. Exposed for tests. */
 export function isProtocolMessage(data) {
     return (typeof data === 'object' &&
         data !== null &&
@@ -10,8 +28,9 @@ export function isProtocolMessage(data) {
         typeof data.kind === 'string');
 }
 /**
- * הקוד שרץ בתוך ה-iframe. מחרוזת ולא פונקציה מוסרלת — כדי שה-build לא ישנה
- * אותו (minify של שמות היה שובר את הפרוטוקול).
+ * The code that runs inside the iframe. A string rather than a serialized
+ * function, so the build cannot touch it (minifying names would break the
+ * protocol).
  */
 export const SANDBOX_BOOTSTRAP = `
 'use strict';
@@ -28,7 +47,7 @@ export const SANDBOX_BOOTSTRAP = `
   var api = new Proxy({}, {
     get: function (_target, method) {
       if (typeof method !== 'string') return undefined;
-      if (method === 'then') return undefined; // ש-await api לא יתפרש כ-thenable
+      if (method === 'then') return undefined; // so "await api" is not treated as a thenable
       return function () {
         var args = Array.prototype.slice.call(arguments);
         return new Promise(function (resolve, reject) {
@@ -75,7 +94,7 @@ export const SANDBOX_BOOTSTRAP = `
   post({ kind: 'ready' });
 })();
 `;
-/** ערך בטוח למסירה חזרה ל-iframe (structured clone עלול להיכשל על אובייקטי מנוע). */
+/** A value safe to hand back to the iframe (structured clone can fail on engine objects). */
 function toCloneSafe(value) {
     if (value === undefined || value === null)
         return value;
@@ -108,7 +127,7 @@ export function createIframeRunner(doc = document) {
                     resolve(result);
                 };
                 const onMessage = (event) => {
-                    // רק הודעות מה-iframe הזה: דף יכול להריץ כמה מאקרו במקביל.
+                    // Only messages from this iframe: a page may run several macros at once.
                     if (event.source !== iframe.contentWindow)
                         return;
                     const data = event.data;
@@ -142,7 +161,7 @@ export function createIframeRunner(doc = document) {
                         finish({ ok: false, reason: 'error', message: data.message });
                 };
                 addEventListener('message', onMessage);
-                timer = setTimeout(() => finish({ ok: false, reason: 'timeout', message: `המאקרו לא הסתיים תוך ${timeoutMs / 1000} שניות ונעצר` }), timeoutMs);
+                timer = setTimeout(() => finish({ ok: false, reason: 'timeout', message: macroMessages().timedOut(timeoutMs / 1000) }), timeoutMs);
                 doc.body.appendChild(iframe);
             });
         },