superdoc-macros 0.3.0 → 0.5.0

package/dist/manager.js

@@ -13,7 +13,9 @@ 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 { IMPORT_LIMITS, isPersistableState } from './storage.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;
@@ -35,6 +37,8 @@ export class MacroKit {
     state;
     recorder;
     autoText;
+    reservedSignatures;
+    scriptsEnabled;
     running = false;
     constructor(options) {
         this.host = options.host;
@@ -44,15 +48,86 @@ export class MacroKit {
         const runner = options.runner ?? 'iframe';
         this.runner =
             runner === 'iframe' ? createIframeRunner() : runner === 'eval' ? createEvalRunner() : runner;
+        this.scriptsEnabled = options.scriptsEnabled ?? true;
         this.state = this.storage.load() ?? emptyState();
-        this.recorder = new MacroRecorder(this.host);
-        this.autoText = new AutoText(this.host, () => this.state.snippets, options.autoText);
+        this.recorder = new MacroRecorder(this.host, { onAutoStop: options.onRecordingAutoStop });
+        this.autoText = new AutoText(this.host, () => this.state.snippets, {
+            ...options.autoText,
+            // The recorder rewrite keeps recordings truthful: the user typed a
+            // trigger word, the document holds the expanded text, and a replay of
+            // the raw keystrokes would diverge. See applyAutoTextExpansion.
+            onExpand: (snippet, expansion) => {
+                this.recorder.applyAutoTextExpansion(expansion.trigger.length + expansion.expandChar.length, expansion.rendered + expansion.expandChar);
+                options.autoText?.onExpand?.(snippet, expansion);
+            },
+        });
+        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);
+        this.requireItemLimits({ name: input.name, source: input.source });
+        this.requireRoom(this.state.scripts, input.id);
         const script = {
             id: input.id ?? newId(),
             name: input.name,
@@ -75,6 +150,11 @@ export class MacroKit {
     }
     /** Runs an unsaved script — e.g. from the macro editor before saving. */
     async runSource(source) {
+        // The real gate: with scripts disabled nothing executes through any
+        // path — not a saved script, not an imported one, not its shortcut.
+        if (!this.scriptsEnabled) {
+            return { ok: false, reason: 'error', message: macroMessages().scriptsDisabled };
+        }
         const guard = this.guardRun();
         if (guard)
             return guard;
@@ -101,7 +181,10 @@ export class MacroKit {
     }
     /** Stops and saves. `null` when no step was recorded — there is nothing to save. */
     stopRecording(name, shortcut) {
-        const steps = this.recorder.stop();
+        this.requireValidShortcut(shortcut);
+        this.requireItemLimits({ name });
+        this.requireRoom(this.state.recordings);
+        const steps = splitOversizedSteps(this.recorder.stop());
         if (steps.length === 0)
             return null;
         const recording = {
@@ -131,6 +214,10 @@ export class MacroKit {
         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)
+            this.requireItemLimits({ name: input.name });
         if (input.name !== undefined)
             recording.name = input.name;
         if (input.shortcut !== undefined) {
@@ -168,6 +255,9 @@ export class MacroKit {
         return this.state.snippets;
     }
     saveSnippet(input) {
+        this.requireValidShortcut(input.shortcut, input.id);
+        this.requireItemLimits({ name: input.name, text: input.text, trigger: input.trigger });
+        this.requireRoom(this.state.snippets, input.id);
         const snippet = {
             id: input.id ?? newId(),
             name: input.name,
@@ -209,9 +299,14 @@ export class MacroKit {
     }
     currentBindings() {
         const bindings = [];
-        for (const script of this.state.scripts) {
-            if (script.shortcut)
-                bindings.push({ shortcut: script.shortcut, run: () => this.runScript(script.id) });
+        // Part of the scripts gate: with scripts disabled their shortcuts are
+        // not bound at all — runScript would refuse anyway, but an unbound key
+        // is better than a key that swallows the event just to show an error.
+        if (this.scriptsEnabled) {
+            for (const script of this.state.scripts) {
+                if (script.shortcut)
+                    bindings.push({ shortcut: script.shortcut, run: () => this.runScript(script.id) });
+            }
         }
         for (const recording of this.state.recordings) {
             if (recording.shortcut)
@@ -231,25 +326,81 @@ export class MacroKit {
      * Imports JSON produced by `exportState`. With `merge: true` an imported
      * item with an existing `id` replaces it; without merge the whole state is
      * replaced.
+     *
+     * The check is **atomic, on the final result**: a candidate state is built
+     * first, its size limits and every shortcut in it are validated (the same
+     * rules the save paths enforce — a file cannot smuggle in what typing
+     * cannot), and only a candidate that passed in full is committed. On any
+     * failure the current state is untouched.
      */
     importState(json, options = {}) {
         const imported = parsePersistedState(json);
         if (!imported)
             return { ok: false, message: macroMessages().invalidImport };
+        let candidate;
         if (options.merge) {
+            candidate = {
+                version: 1,
+                scripts: [...this.state.scripts.map((item) => ({ ...item }))],
+                recordings: [...this.state.recordings.map((item) => ({ ...item }))],
+                snippets: [...this.state.snippets.map((item) => ({ ...item }))],
+            };
             for (const script of imported.scripts)
-                this.upsert(this.state.scripts, script);
+                this.upsert(candidate.scripts, script);
             for (const recording of imported.recordings)
-                this.upsert(this.state.recordings, recording);
+                this.upsert(candidate.recordings, recording);
             for (const snippet of imported.snippets)
-                this.upsert(this.state.snippets, snippet);
+                this.upsert(candidate.snippets, snippet);
         }
         else {
-            this.state = imported;
+            candidate = imported;
         }
+        // The merged result can exceed what each file alone respected.
+        if (!isPersistableState(candidate))
+            return { ok: false, message: macroMessages().importTooLarge };
+        const shortcutsOk = this.validateStateShortcuts(candidate);
+        if (!shortcutsOk.ok)
+            return shortcutsOk;
+        this.state = candidate;
         this.persist();
         return { ok: true };
     }
+    /**
+     * Every shortcut in a candidate state, under the exact rules of
+     * `validateShortcut`: parseable, real modifier, not host-reserved, and
+     * unique within the candidate. `importState` is the only caller — the
+     * save paths enforce the same rules one item at a time.
+     */
+    validateStateShortcuts(candidate) {
+        const seen = new Map();
+        const items = [
+            ...candidate.scripts,
+            ...candidate.recordings,
+            ...candidate.snippets,
+        ];
+        for (const item of items) {
+            if (!item.shortcut)
+                continue;
+            const parsed = parseShortcut(item.shortcut);
+            if (!parsed) {
+                return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutInvalid) };
+            }
+            if (!hasBindingModifier(parsed)) {
+                return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutNeedsModifier) };
+            }
+            for (const signature of shortcutSignatures(parsed)) {
+                if (this.reservedSignatures.has(signature)) {
+                    return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutReserved) };
+                }
+                const owner = seen.get(signature);
+                if (owner !== undefined) {
+                    return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutTaken(owner)) };
+                }
+                seen.set(signature, item.name);
+            }
+        }
+        return { ok: true };
+    }
     /* ---------- Internal ---------- */
     guardRun() {
         if (this.recorder.recording) {
@@ -260,6 +411,37 @@ export class MacroKit {
         }
         return null;
     }
+    /**
+     * The save-path half of the persistence invariant: field lengths that the
+     * loader would reject are refused at the door. Without this, one oversized
+     * save would make the whole store unloadable — and the next startup would
+     * silently fall back to an empty state, losing everything.
+     */
+    requireItemLimits(fields) {
+        const limits = IMPORT_LIMITS;
+        if (fields.name.length === 0)
+            throw new MacroError(macroMessages().nameRequired, 'invalid-item');
+        if (fields.name.length > limits.maxNameLength) {
+            throw new MacroError(macroMessages().fieldTooLong('name', limits.maxNameLength), 'invalid-item');
+        }
+        if (fields.text !== undefined && fields.text.length > limits.maxTextLength) {
+            throw new MacroError(macroMessages().fieldTooLong('text', limits.maxTextLength), 'invalid-item');
+        }
+        if (fields.source !== undefined && fields.source.length > limits.maxSourceLength) {
+            throw new MacroError(macroMessages().fieldTooLong('source', limits.maxSourceLength), 'invalid-item');
+        }
+        if (fields.trigger !== undefined && fields.trigger.length > limits.maxTriggerLength) {
+            throw new MacroError(macroMessages().fieldTooLong('trigger', limits.maxTriggerLength), 'invalid-item');
+        }
+    }
+    /** The item-count half of the invariant. `existingId` exempts an in-place update. */
+    requireRoom(list, existingId) {
+        if (existingId && list.some((entry) => entry.id === existingId))
+            return;
+        if (list.length >= IMPORT_LIMITS.maxItems) {
+            throw new MacroError(macroMessages().tooManyItems, 'too-many-items');
+        }
+    }
     upsert(list, item) {
         const index = list.findIndex((entry) => entry.id === item.id);
         if (index >= 0)
@@ -268,6 +450,39 @@ export class MacroKit {
             list.push(item);
     }
     persist() {
+        // Final safety net for the invariant: state the loader would reject is
+        // never written. Reaching this branch is a bug in a save path above —
+        // the warning is what surfaces it — but the user's stored macros
+        // surviving that bug is the point.
+        if (!isPersistableState(this.state)) {
+            console.warn('[superdoc-macros] refusing to persist state that would fail to load');
+            return;
+        }
         this.storage.save(this.state);
     }
 }
+/**
+ * A recorded insert-text step can exceed the loader's per-step cap (one huge
+ * paste coalesces into one step). Splitting preserves the exact text while
+ * keeping the recording loadable.
+ */
+function splitOversizedSteps(steps) {
+    const max = IMPORT_LIMITS.maxTextLength;
+    const split = steps.flatMap((step) => {
+        if (step.type !== 'insert-text' || step.text.length <= max)
+            return [step];
+        const chunks = [];
+        for (let offset = 0; offset < step.text.length; offset += max) {
+            chunks.push({ type: 'insert-text', text: step.text.slice(offset, offset + max) });
+        }
+        return chunks;
+    });
+    // Splitting can push a cap-length recording past the loader's step limit.
+    // Truncating the tail is the honest option left: the alternative is a
+    // recording the loader rejects, which loses the whole store's worth more.
+    if (split.length > IMPORT_LIMITS.maxStepsPerRecording) {
+        console.warn('[superdoc-macros] recording truncated to the step limit');
+        return split.slice(0, IMPORT_LIMITS.maxStepsPerRecording);
+    }
+    return split;
+}

package/dist/messages.d.ts

@@ -27,14 +27,25 @@ export interface MacroMessages {
     syntaxError: (detail: string) => string;
     timedOut: (seconds: number) => string;
     callLimitExceeded: (limit: number) => string;
-    deleteForwardUnsupported: string;
+    macroStopped: string;
     scriptNotFound: string;
     recordingNotFound: string;
     snippetNotFound: string;
     cannotRunWhileRecording: string;
     anotherMacroRunning: string;
+    scriptsDisabled: string;
+    nameRequired: string;
     invalidImport: string;
+    importRejectedShortcut: (itemName: string, detail: string) => string;
+    importTooLarge: string;
+    tooManyItems: string;
+    fieldTooLong: (field: string, max: number) => string;
+    shortcutInvalid: string;
+    shortcutNeedsModifier: string;
+    shortcutReserved: string;
+    shortcutTaken: (ownerName: string) => string;
     noDocument: string;
+    selectionUnavailable: string;
     unknownCommand: (id: string) => string;
     actionFailed: string;
     deletionUnavailable: string;

package/dist/messages.js

@@ -27,14 +27,25 @@ export const ENGLISH_MESSAGES = {
     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',
+    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',
+    scriptsDisabled: 'Scripted macros are disabled',
     invalidImport: 'The file is not a valid macro export',
+    importRejectedShortcut: (itemName, detail) => `Import rejected: the shortcut of "${itemName}" is not acceptable — ${detail}`,
+    importTooLarge: 'Import rejected: the merged result exceeds the item limits',
+    tooManyItems: 'The list is full — delete items before adding new ones',
+    nameRequired: 'A name is required',
+    fieldTooLong: (field, max) => `${field} is too long (limit: ${max} characters)`,
+    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',
@@ -53,14 +64,25 @@ export const HEBREW_MESSAGES = {
     syntaxError: (detail) => `שגיאת תחביר במאקרו: ${detail}`,
     timedOut: (seconds) => `המאקרו לא הסתיים תוך ${seconds} שניות ונעצר`,
     callLimitExceeded: (limit) => `המאקרו חצה את תקרת הקריאות (${limit}) ונעצר`,
-    deleteForwardUnsupported: 'מחיקה קדימה אינה נתמכת בניגון',
+    macroStopped: 'המאקרו נעצר — הקריאה לא בוצעה',
     scriptNotFound: 'המאקרו לא נמצא',
     recordingNotFound: 'ההקלטה לא נמצאה',
     snippetNotFound: 'הקטע לא נמצא',
     cannotRunWhileRecording: 'אי אפשר להריץ מאקרו בזמן הקלטה',
     anotherMacroRunning: 'מאקרו אחר עדיין רץ',
+    scriptsDisabled: 'מאקרו כתובים מושבתים',
     invalidImport: 'הקובץ אינו ייצוא מאקרו תקין',
+    importRejectedShortcut: (itemName, detail) => `הייבוא נדחה: הקיצור של "${itemName}" אינו קביל — ${detail}`,
+    importTooLarge: 'הייבוא נדחה: התוצאה הממוזגת חורגת מתקרת הפריטים',
+    tooManyItems: 'הרשימה מלאה — יש למחוק פריטים לפני הוספה',
+    nameRequired: 'חובה לתת שם',
+    fieldTooLong: (field, max) => `${field} ארוך מדי (התקרה: ${max} תווים)`,
+    shortcutInvalid: 'קיצור לא תקין — הצורה הנדרשת היא למשל Ctrl+Alt+M',
+    shortcutNeedsModifier: 'קיצור חייב לכלול Ctrl,‏ Alt או Meta',
+    shortcutReserved: 'הקיצור הזה שמור לעורך',
+    shortcutTaken: (ownerName) => `הקיצור כבר בשימוש של "${ownerName}"`,
     noDocument: 'אין מסמך פתוח',
+    selectionUnavailable: 'קריאת מיקום הסמן נכשלה — לא הוכנס דבר',
     unknownCommand: (id) => `הפקודה ${id} אינה מוכרת למנוע`,
     actionFailed: 'הפעולה נכשלה',
     deletionUnavailable: 'מחיקה אינה זמינה במסמך הזה',

package/dist/recorder/recorder.d.ts

@@ -1,14 +1,36 @@
+/**
+ * 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 type { MacroHost, MacroStep } from '../types.js';
 export interface RecorderOptions {
     /** 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;
+    /**
+     * Called when the step cap stops the recording. The steps are kept —
+     * `stop()` still returns them — but listening has ceased, and a UI that
+     * shows "recording" must be told, or its indicator would keep promising a
+     * recording that is no longer happening.
+     */
+    onAutoStop?: () => void;
 }
 export declare class MacroRecorder {
     private readonly host;
     private readonly shouldRecordCommand;
     private readonly maxSteps;
+    private readonly onAutoStop?;
     private steps;
     private disposers;
     private active;
@@ -16,10 +38,28 @@ export declare class MacroRecorder {
     get recording(): boolean;
     get stepCount(): number;
     start(): void;
-    /** Stops and returns the steps. Empty when nothing was recorded. */
+    /**
+     * Stops and returns the steps. Empty when nothing was recorded. Also the
+     * way to collect a recording that auto-stopped at the cap — the steps are
+     * kept until someone asks for them.
+     */
     stop(): MacroStep[];
     /** Stops and discards whatever was recorded. */
     cancel(): void;
+    /**
+     * Rewrites the recorded tail after an auto-text expansion: the user typed
+     * a trigger word plus the expansion character, but what the document now
+     * holds is the expanded text — a replay of the raw keystrokes would
+     * diverge (and would depend on auto-text being active at replay time).
+     * The trailing `consumed` characters are removed from the recorded
+     * insert-text steps and the expanded text is recorded in their place.
+     *
+     * If the tail does not hold `consumed` plain characters (a command landed
+     * mid-word, or the recording started mid-trigger), the rewrite is skipped
+     * and the raw keystrokes stay — a truthful raw recording beats a guessed
+     * edit of steps that do not match.
+     */
+    applyAutoTextExpansion(consumed: number, replacement: string): void;
     private teardown;
     private push;
     private recordCommand;

package/dist/recorder/recorder.js

@@ -1,18 +1,3 @@
-/**
- * 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 during recording fix the recording itself — replaying them would replay the mistake too. */
 function defaultShouldRecord(id) {
@@ -22,6 +7,7 @@ export class MacroRecorder {
     host;
     shouldRecordCommand;
     maxSteps;
+    onAutoStop;
     steps = [];
     disposers = [];
     active = false;
@@ -29,6 +15,7 @@ export class MacroRecorder {
         this.host = host;
         this.shouldRecordCommand = options.shouldRecordCommand ?? defaultShouldRecord;
         this.maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+        this.onAutoStop = options.onAutoStop;
     }
     get recording() {
         return this.active;
@@ -46,10 +33,12 @@ export class MacroRecorder {
             this.host.onTextInput((event) => this.recordTextInput(event)),
         ];
     }
-    /** Stops and returns the steps. Empty when nothing was recorded. */
+    /**
+     * Stops and returns the steps. Empty when nothing was recorded. Also the
+     * way to collect a recording that auto-stopped at the cap — the steps are
+     * kept until someone asks for them.
+     */
     stop() {
-        if (!this.active)
-            return [];
         this.teardown();
         const recorded = this.steps;
         this.steps = [];
@@ -57,22 +46,64 @@ export class MacroRecorder {
     }
     /** Stops and discards whatever was recorded. */
     cancel() {
-        if (!this.active)
-            return;
         this.teardown();
         this.steps = [];
     }
+    /**
+     * Rewrites the recorded tail after an auto-text expansion: the user typed
+     * a trigger word plus the expansion character, but what the document now
+     * holds is the expanded text — a replay of the raw keystrokes would
+     * diverge (and would depend on auto-text being active at replay time).
+     * The trailing `consumed` characters are removed from the recorded
+     * insert-text steps and the expanded text is recorded in their place.
+     *
+     * If the tail does not hold `consumed` plain characters (a command landed
+     * mid-word, or the recording started mid-trigger), the rewrite is skipped
+     * and the raw keystrokes stay — a truthful raw recording beats a guessed
+     * edit of steps that do not match.
+     */
+    applyAutoTextExpansion(consumed, replacement) {
+        if (!this.active || consumed <= 0)
+            return;
+        // Verify the tail is entirely typed text before touching anything.
+        let remaining = consumed;
+        let index = this.steps.length - 1;
+        while (remaining > 0 && index >= 0) {
+            const step = this.steps[index];
+            if (step?.type !== 'insert-text')
+                return;
+            remaining -= step.text.length;
+            index -= 1;
+        }
+        if (remaining > 0)
+            return;
+        let toRemove = consumed;
+        while (toRemove > 0) {
+            const last = this.steps[this.steps.length - 1];
+            if (last?.type !== 'insert-text')
+                return; // unreachable after the check above
+            if (last.text.length > toRemove) {
+                last.text = last.text.slice(0, -toRemove);
+                break;
+            }
+            toRemove -= last.text.length;
+            this.steps.pop();
+        }
+        this.recordTextInput({ kind: 'insert-text', text: replacement });
+    }
     teardown() {
         this.active = false;
         for (const dispose of this.disposers.splice(0))
             dispose();
     }
     push(step) {
+        this.steps.push(step);
         if (this.steps.length >= this.maxSteps) {
+            // The cap stops the *listening*, not the data: the steps stay for
+            // stop() to collect, and the owner is told the recording ended.
             this.teardown();
-            return;
+            this.onAutoStop?.();
         }
-        this.steps.push(step);
     }
     recordCommand(id, payload) {
         if (!this.shouldRecordCommand(id))
@@ -124,8 +155,7 @@ async function runStep(host, step) {
         case 'delete-backward':
             return host.deleteBackward(step.count);
         case 'delete-forward':
-            // The engine exposes no separate forward deletion; report an explicit failure rather than skipping silently.
-            return { ok: false, message: macroMessages().deleteForwardUnsupported, reason: 'unsupported-step' };
+            return host.deleteForward(step.count);
     }
 }
 export async function replayMacro(host, steps, options = {}) {

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

@@ -2,4 +2,17 @@ import type { MacroBridge } from './macro-api.js';
 import { type MacroRunner } from './runner.js';
 /** 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;