superdoc-macros 0.4.0 → 0.5.0

package/README.md

@@ -82,6 +82,8 @@ Honest limits: the browser offers no per-iframe memory cap, and a host call that
 
 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.
 
+**A real off switch:** `new MacroKit({ host, scriptsEnabled: false })` gates script *execution*, not just UI — `runScript`/`runSource` refuse and saved script shortcuts are not bound, so a pre-existing or imported script cannot run through any path. Recordings and snippets are unaffected.
+
 ## 2. Macro recorder
 
 ```ts
@@ -136,7 +138,9 @@ kit.importState(json, { merge: true });
 
 `MacroStorage` is a two-method interface — implement it to persist to a file (e.g. a plugin workspace).
 
-Imports are strictly validated: every item and every recorded step is type-checked and size-bounded (see `IMPORT_LIMITS`), and one invalid item rejects the whole file — no partial imports.
+Imports are strictly validated **atomically on the final result**: every item and every recorded step is type-checked and size-bounded (see `IMPORT_LIMITS`), every shortcut in the merged state must pass the same binding rules the save paths enforce (modifier required, not host-reserved, no duplicates), and any failure rejects the whole file with the current state untouched — no partial imports.
+
+The same limits hold as a persistence invariant: the save paths refuse oversized fields and full lists, an oversized recorded paste is split into loadable steps, and state that the loader would reject is never written — so a single bad save can never wipe the store on the next startup.
 
 ## Shortcut safety
 

package/dist/index.d.ts

@@ -8,6 +8,6 @@ export { createIframeRunner, SANDBOX_BOOTSTRAP, isProtocolMessage } from './scri
 export type { MacroRunner, MacroRunOptions, MacroRunResult } from './scripting/runner.js';
 export { MacroRecorder, replayMacro, type RecorderOptions, type ReplayOptions, type ReplayResult } from './recorder/recorder.js';
 export { renderSnippet, expandSnippet, usesSelection, type ExpandOptions, type RenderContext } from './snippets/snippets.js';
-export { AutoText, type AutoTextOptions } from './snippets/autotext.js';
+export { AutoText, type AutoTextOptions, type AutoTextExpansion } from './snippets/autotext.js';
 export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget, } from './shortcuts.js';
-export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, type MacroStorage, type PersistedMacroState, } from './storage.js';
+export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, type MacroStorage, type PersistedMacroState, } from './storage.js';

package/dist/index.js

@@ -8,4 +8,4 @@ export { MacroRecorder, replayMacro } from './recorder/recorder.js';
 export { renderSnippet, expandSnippet, usesSelection } from './snippets/snippets.js';
 export { AutoText } from './snippets/autotext.js';
 export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, } from './shortcuts.js';
-export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, } from './storage.js';
+export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, } from './storage.js';

package/dist/manager.d.ts

@@ -38,6 +38,20 @@ export interface MacroKitOptions {
      * editor shortcut. Unparseable entries are ignored.
      */
     reservedShortcuts?: readonly string[];
+    /**
+     * Whether scripted macros may *execute*. Default: true. When false the
+     * gate is real, not cosmetic: `runScript`/`runSource` refuse, and saved
+     * script shortcuts are not bound — so a pre-existing or imported script
+     * cannot run through any path. Saving and listing still work (a UI may
+     * let the user manage scripts it will not run).
+     */
+    scriptsEnabled?: boolean;
+    /**
+     * Called when a recording hits the step cap and stops on its own. The
+     * steps are kept — `stopRecording(name)` still saves them — but a UI that
+     * shows a live "recording" indicator must update it.
+     */
+    onRecordingAutoStop?: () => void;
 }
 export type ShortcutValidation = {
     ok: true;
@@ -55,6 +69,7 @@ export declare class MacroKit {
     private readonly recorder;
     private readonly autoText;
     private readonly reservedSignatures;
+    private readonly scriptsEnabled;
     private running;
     constructor(options: MacroKitOptions);
     /**
@@ -123,6 +138,12 @@ export declare 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: string, options?: {
         merge?: boolean;
@@ -130,7 +151,23 @@ export declare class MacroKit {
         ok: boolean;
         message?: string;
     };
+    /**
+     * 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.
+     */
+    private validateStateShortcuts;
     private guardRun;
+    /**
+     * 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.
+     */
+    private requireItemLimits;
+    /** The item-count half of the invariant. `existingId` exempts an in-place update. */
+    private requireRoom;
     private upsert;
     private persist;
 }

package/dist/manager.js

@@ -13,6 +13,7 @@ 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 { 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';
@@ -37,6 +38,7 @@ export class MacroKit {
     recorder;
     autoText;
     reservedSignatures;
+    scriptsEnabled;
     running = false;
     constructor(options) {
         this.host = options.host;
@@ -46,9 +48,19 @@ 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);
@@ -114,6 +126,8 @@ export class MacroKit {
     }
     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,
@@ -136,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;
@@ -163,7 +182,9 @@ export class MacroKit {
     /** 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();
+        this.requireItemLimits({ name });
+        this.requireRoom(this.state.recordings);
+        const steps = splitOversizedSteps(this.recorder.stop());
         if (steps.length === 0)
             return null;
         const recording = {
@@ -195,6 +216,8 @@ export class MacroKit {
             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) {
@@ -233,6 +256,8 @@ export class MacroKit {
     }
     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,
@@ -274,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)
@@ -296,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) {
@@ -325,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)
@@ -333,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

@@ -33,7 +33,13 @@ export interface MacroMessages {
     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;

package/dist/messages.js

@@ -33,7 +33,13 @@ export const ENGLISH_MESSAGES = {
     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',
@@ -64,7 +70,13 @@ export const HEBREW_MESSAGES = {
     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: 'הקיצור הזה שמור לעורך',

package/dist/recorder/recorder.d.ts

@@ -18,11 +18,19 @@ export interface RecorderOptions {
     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;
@@ -30,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

@@ -7,6 +7,7 @@ export class MacroRecorder {
     host;
     shouldRecordCommand;
     maxSteps;
+    onAutoStop;
     steps = [];
     disposers = [];
     active = false;
@@ -14,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;
@@ -31,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 = [];
@@ -42,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))

package/dist/snippets/autotext.d.ts

@@ -15,13 +15,22 @@
  * better than an expansion that deletes the wrong text.
  */
 import type { MacroHost, Snippet } from '../types.js';
+/** What an expansion actually did — what a recorder needs to stay truthful. */
+export interface AutoTextExpansion {
+    /** The trigger word the user typed. */
+    trigger: string;
+    /** The character that fired the expansion (and was restored at the end). */
+    expandChar: string;
+    /** The rendered snippet text that replaced the trigger. */
+    rendered: string;
+}
 export interface AutoTextOptions {
     /** The expansion characters. Default: space only. */
     expandOn?: readonly string[];
     /** Buffer size. A trigger word longer than this will not be recognized. */
     bufferSize?: number;
     /** Called after a successful expansion. */
-    onExpand?: (snippet: Snippet) => void;
+    onExpand?: (snippet: Snippet, expansion: AutoTextExpansion) => void;
     /** Called when an expansion failed (e.g. a read-only document). */
     onError?: (message: string) => void;
 }

package/dist/snippets/autotext.js

@@ -94,7 +94,7 @@ export class AutoText {
                 this.onError?.(inserted.message);
                 return;
             }
-            this.onExpand?.(snippet);
+            this.onExpand?.(snippet, { trigger, expandChar, rendered });
         }
         finally {
             this.busy = false;

package/dist/storage.d.ts

@@ -34,6 +34,13 @@ export declare const IMPORT_LIMITS: {
     readonly maxTextLength: 100000;
     readonly maxSourceLength: 200000;
 };
+/**
+ * Whether a state object passes the exact validation the loader applies.
+ * The save paths hold this as an invariant: state that would be rejected on
+ * the next load must never be persisted — otherwise a single oversized save
+ * silently wipes everything at the next startup.
+ */
+export declare function isPersistableState(value: unknown): value is PersistedMacroState;
 /**
  * Parses saved/imported state. `null` on any unexpected shape, oversized
  * field or oversized file — never throws, never partially accepts: one

package/dist/storage.js

@@ -91,6 +91,15 @@ function isValidState(value) {
         state.snippets.length <= IMPORT_LIMITS.maxItems &&
         state.snippets.every(isValidSnippet));
 }
+/**
+ * Whether a state object passes the exact validation the loader applies.
+ * The save paths hold this as an invariant: state that would be rejected on
+ * the next load must never be persisted — otherwise a single oversized save
+ * silently wipes everything at the next startup.
+ */
+export function isPersistableState(value) {
+    return isValidState(value);
+}
 /**
  * Parses saved/imported state. `null` on any unexpected shape, oversized
  * field or oversized file — never throws, never partially accepts: one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superdoc-macros",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Macro toolkit for SuperDoc-based editors: sandboxed scripted macros, a Word-style macro recorder, and snippets with auto-text expansion.",
   "license": "MIT",
   "type": "module",