superdoc-macros 0.2.0 → 0.4.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';
@@ -13,8 +13,10 @@ import { createIframeRunner } from './scripting/iframe-runner.js';
 import { MacroRecorder, replayMacro } from './recorder/recorder.js';
 import { AutoText } from './snippets/autotext.js';
 import { expandSnippet } from './snippets/snippets.js';
-import { bindShortcuts } from './shortcuts.js';
+import { bindShortcuts, hasBindingModifier, parseShortcut, shortcutSignatures, } from './shortcuts.js';
+import { MacroError } from './scripting/macro-api.js';
 import { createLocalStorage, emptyState, parsePersistedState } from './storage.js';
+import { macroMessages } from './messages.js';
 let idCounter = 0;
 function newId() {
     try {
@@ -34,6 +36,7 @@ export class MacroKit {
     state;
     recorder;
     autoText;
+    reservedSignatures;
     running = false;
     constructor(options) {
         this.host = options.host;
@@ -46,12 +49,71 @@ export class MacroKit {
         this.state = this.storage.load() ?? emptyState();
         this.recorder = new MacroRecorder(this.host);
         this.autoText = new AutoText(this.host, () => this.state.snippets, options.autoText);
+        const reserved = new Set();
+        for (const shortcut of options.reservedShortcuts ?? []) {
+            const parsed = parseShortcut(shortcut);
+            if (parsed)
+                for (const signature of shortcutSignatures(parsed))
+                    reserved.add(signature);
+        }
+        this.reservedSignatures = reserved;
+    }
+    /* ---------- Shortcut validation ---------- */
+    /**
+     * 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, excludeId) {
+        const trimmed = shortcut?.trim();
+        if (!trimmed)
+            return { ok: true };
+        const parsed = parseShortcut(trimmed);
+        if (!parsed)
+            return { ok: false, message: macroMessages().shortcutInvalid };
+        if (!hasBindingModifier(parsed))
+            return { ok: false, message: macroMessages().shortcutNeedsModifier };
+        const signatures = shortcutSignatures(parsed);
+        if (signatures.some((signature) => this.reservedSignatures.has(signature))) {
+            return { ok: false, message: macroMessages().shortcutReserved };
+        }
+        const owner = this.findShortcutOwner(signatures, excludeId);
+        if (owner)
+            return { ok: false, message: macroMessages().shortcutTaken(owner) };
+        return { ok: true };
     }
-    /* ---------- סקריפטים ---------- */
+    findShortcutOwner(signatures, excludeId) {
+        const items = [
+            ...this.state.scripts,
+            ...this.state.recordings,
+            ...this.state.snippets,
+        ];
+        for (const item of items) {
+            if (!item.shortcut || item.id === excludeId)
+                continue;
+            const parsed = parseShortcut(item.shortcut);
+            if (!parsed)
+                continue;
+            const existing = shortcutSignatures(parsed);
+            if (existing.some((signature) => signatures.includes(signature)))
+                return item.name;
+        }
+        return null;
+    }
+    /** Throws a MacroError when the shortcut is unacceptable. The save paths call this. */
+    requireValidShortcut(shortcut, excludeId) {
+        const validation = this.validateShortcut(shortcut, excludeId);
+        if (!validation.ok)
+            throw new MacroError(validation.message, 'invalid-shortcut');
+    }
+    /* ---------- Scripts ---------- */
     listScripts() {
         return this.state.scripts;
     }
     saveScript(input) {
+        this.requireValidShortcut(input.shortcut, input.id);
         const script = {
             id: input.id ?? newId(),
             name: input.name,
@@ -69,10 +131,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 +148,7 @@ export class MacroKit {
             this.running = false;
         }
     }
-    /* ---------- מקליט ---------- */
+    /* ---------- Recorder ---------- */
     get isRecording() {
         return this.recorder.recording;
     }
@@ -98,8 +160,9 @@ 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) {
+        this.requireValidShortcut(shortcut);
         const steps = this.recorder.stop();
         if (steps.length === 0)
             return null;
@@ -125,11 +188,13 @@ 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)
             return null;
+        if (input.shortcut !== undefined)
+            this.requireValidShortcut(input.shortcut, input.id);
         if (input.name !== undefined)
             recording.name = input.name;
         if (input.shortcut !== undefined) {
@@ -143,8 +208,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,11 +227,12 @@ export class MacroKit {
             this.running = false;
         }
     }
-    /* ---------- קטעי טקסט ---------- */
+    /* ---------- Snippets ---------- */
     listSnippets() {
         return this.state.snippets;
     }
     saveSnippet(input) {
+        this.requireValidShortcut(input.shortcut, input.id);
         const snippet = {
             id: input.id ?? newId(),
             name: input.name,
@@ -180,22 +251,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 +288,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 +315,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,55 @@
+/**
+ * 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;
+    macroStopped: string;
+    scriptNotFound: string;
+    recordingNotFound: string;
+    snippetNotFound: string;
+    cannotRunWhileRecording: string;
+    anotherMacroRunning: string;
+    invalidImport: string;
+    shortcutInvalid: string;
+    shortcutNeedsModifier: string;
+    shortcutReserved: string;
+    shortcutTaken: (ownerName: string) => string;
+    noDocument: string;
+    selectionUnavailable: 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,88 @@
+/**
+ * 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`,
+    macroStopped: 'The macro was stopped — the call was not executed',
+    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',
+    shortcutInvalid: 'Invalid shortcut — use a form like Ctrl+Alt+M',
+    shortcutNeedsModifier: 'A shortcut must include Ctrl, Alt or Meta',
+    shortcutReserved: 'This shortcut is reserved by the editor',
+    shortcutTaken: (ownerName) => `This shortcut is already used by "${ownerName}"`,
+    noDocument: 'No document is open',
+    selectionUnavailable: 'The caret position could not be read — nothing was inserted',
+    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}) ונעצר`,
+    macroStopped: 'המאקרו נעצר — הקריאה לא בוצעה',
+    scriptNotFound: 'המאקרו לא נמצא',
+    recordingNotFound: 'ההקלטה לא נמצאה',
+    snippetNotFound: 'הקטע לא נמצא',
+    cannotRunWhileRecording: 'אי אפשר להריץ מאקרו בזמן הקלטה',
+    anotherMacroRunning: 'מאקרו אחר עדיין רץ',
+    invalidImport: 'הקובץ אינו ייצוא מאקרו תקין',
+    shortcutInvalid: 'קיצור לא תקין — הצורה הנדרשת היא למשל Ctrl+Alt+M',
+    shortcutNeedsModifier: 'קיצור חייב לכלול Ctrl,‏ Alt או Meta',
+    shortcutReserved: 'הקיצור הזה שמור לעורך',
+    shortcutTaken: (ownerName) => `הקיצור כבר בשימוש של "${ownerName}"`,
+    noDocument: 'אין מסמך פתוח',
+    selectionUnavailable: 'קריאת מיקום הסמן נכשלה — לא הוכנס דבר',
+    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,22 @@
 /**
- * מקליט מאקרו בסגנון Word: מקליט **פקודות** והקלדה, לא מיקומי סמן.
+ * A Word-style macro recorder: records **commands** and typing, not caret
+ * positions.
  *
- * הבחירה הזאת מכוונת. הקלטת צעדי ProseMirror גולמיים (עם מיקומים אבסולוטיים)
- * נשברת ברגע שהמסמך שונה ממה שהיה בזמן ההקלטה; הקלטת פקודות ("bold",
- * "bullet-list", הקלדת "בס\"ד") מתנהגת כמו המקליט של Word — הפעולות חלות
- * במקום שבו הסמן נמצא בזמן הניגון. זה גם מה שהופך הקלטה לניתנת לשמירה
- * ולשיתוף: הצעדים JSON בלבד.
+ * 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.
  *
- * מה לא נקלט: תנועת סמן ובחירה בעכבר. כמו ב-Word, מאקרו מוקלט פועל מהמקום
- * שבו הסמן עומד כשמריצים אותו.
+ * 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 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 +30,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 +46,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,5 @@
 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 +31,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 +40,7 @@ export class MacroRecorder {
         this.steps = [];
         return recorded;
     }
-    /** עוצרת וזורקת את מה שהוקלט. */
+    /** Stops and discards whatever was recorded. */
     cancel() {
         if (!this.active)
             return;
@@ -68,7 +68,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 +109,7 @@ async function runStep(host, step) {
         case 'delete-backward':
             return host.deleteBackward(step.count);
         case 'delete-forward':
-            // המנוע אינו חושף מחיקה קדימה נפרדת; מדווח ככשל מפורש ולא מדלג בשקט.
-            return { ok: false, message: 'מחיקה קדימה אינה נתמכת בניגון', reason: 'unsupported-step' };
+            return host.deleteForward(step.count);
     }
 }
 export async function replayMacro(host, steps, options = {}) {

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

@@ -1,16 +1,18 @@
-/**
- * מריץ סקריפטים ישיר — `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;
+/**
+ * Wraps a bridge with a kill switch. After `revoke()` every new call is
+ * rejected — so a script that keeps running past its timeout (the eval
+ * runner cannot stop it) can no longer touch the document.
+ *
+ * What this cannot do: abort a host call that already reached the engine.
+ * The engine's public surfaces expose no cancellation, so an in-flight
+ * operation completes; what is guaranteed is that nothing *new* starts.
+ */
+export declare function revocable(bridge: MacroBridge): {
+    bridge: MacroBridge;
+    revoke: () => void;
+};
 export declare function createEvalRunner(): MacroRunner;

package/dist/scripting/eval-runner.js

@@ -1,21 +1,61 @@
+/**
+ * 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`, כדי שהתקרה תיאכף גם כאן. */
+/**
+ * Wraps a bridge with a kill switch. After `revoke()` every new call is
+ * rejected — so a script that keeps running past its timeout (the eval
+ * runner cannot stop it) can no longer touch the document.
+ *
+ * What this cannot do: abort a host call that already reached the engine.
+ * The engine's public surfaces expose no cancellation, so an in-flight
+ * operation completes; what is guaranteed is that nothing *new* starts.
+ */
+export function revocable(bridge) {
+    let revoked = false;
+    return {
+        revoke: () => {
+            revoked = true;
+        },
+        bridge: {
+            api: bridge.api,
+            callCount: bridge.callCount,
+            call(method, args) {
+                if (revoked)
+                    return Promise.reject(new Error(macroMessages().macroStopped));
+                return bridge.call(method, args);
+            },
+        },
+    };
+}
+/** An api proxy that routes everything through `bridge.call`, so the cap applies here too. */
 function apiThroughBridge(bridge) {
     return new Proxy({}, {
         get(_target, method) {
@@ -29,7 +69,9 @@ export function createEvalRunner() {
     return {
         async run(source, bridge, options = {}) {
             const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-            const limited = limitCalls(bridge, options.maxApiCalls ?? DEFAULT_MAX_API_CALLS);
+            // The revocable wrapper is what contains a timed-out script: eval cannot
+            // stop it from running, but it can no longer reach the document.
+            const { bridge: guarded, revoke } = revocable(limitCalls(bridge, options.maxApiCalls ?? DEFAULT_MAX_API_CALLS));
             let fn;
             try {
                 fn = new AsyncFunction('api', `"use strict";\n${source}`);
@@ -38,16 +80,16 @@ 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 {
-                    const value = await fn(apiThroughBridge(limited));
+                    const value = await fn(apiThroughBridge(guarded));
                     return { ok: true, value };
                 }
                 catch (error) {
@@ -63,6 +105,7 @@ export function createEvalRunner() {
             }
             finally {
                 clearTimeout(timer);
+                revoke();
             }
         },
     };