superdoc-macros 0.6.0 → 0.7.1

package/README.md

@@ -87,7 +87,9 @@ If you must waive isolation (e.g. a CSP that blocks `srcdoc`), switch to the dir
 ## 2. Macro recorder
 
 ```ts
-kit.startRecording();
+if (!kit.startRecording()) {
+  throw new Error('A macro is running or an unsaved recording is pending');
+}
 // the user works normally: typing, formatting, lists...
 const recording = kit.stopRecording('Standard intro', 'Ctrl+Alt+1');
 
@@ -97,6 +99,8 @@ await kit.replayRecording(recording.id);
 
 The recorder captures **commands and typing**, not caret positions — exactly like Word's recorder: replay applies wherever the caret stands. Consecutive keystrokes coalesce into one step, `undo`/`redo` are not recorded (configurable via `RecorderOptions`), and recordings persist as clean JSON that can be exported and shared. `updateRecording({id, name?, shortcut?})` renames a recording or edits its shortcut.
 
+Finalization is loss-aware. A command payload that cannot be stored faithfully is reported instead of silently omitted; `stopRecording()` keeps the stopped capture pending until it is saved or explicitly cancelled. A mixed capture requires `{ allowIncomplete: true }` after the host has obtained user consent, while a capture containing no replayable step is rejected as `recording-uncapturable`. Storage, capacity, and validation failures are retryable: fix the problem and call `stopRecording()` again. Starting a new recording while one is pending is rejected, preventing accidental loss.
+
 ## 3. Snippets and auto-text
 
 ```ts

package/dist/host/superdoc-host.js

@@ -327,6 +327,28 @@ export function createSuperdocHost(options) {
         async getSelection(options) {
             return (await readSelectionDetailed(options?.includeText ?? false)).snapshot;
         },
+        async replaceTextBefore(expected, replacement) {
+            // Auto-text's atomic path: verify and replace inside one ProseMirror
+            // transaction — no window in which the trigger is deleted but the
+            // replacement not yet in.
+            const pm = view();
+            if (!pm)
+                return failed(macroMessages().deletionUnavailable, 'view-unavailable');
+            try {
+                const { from } = pm.state.selection;
+                const start = from - expected.length;
+                if (start < 0 || pm.state.doc.textBetween(start, from) !== expected) {
+                    return failed(macroMessages().actionFailed, 'text-mismatch');
+                }
+                const tr = pm.state.tr;
+                tr.insertText(replacement, start, from);
+                pm.dispatch(tr);
+                return { ok: true };
+            }
+            catch (error) {
+                return failed(error instanceof Error ? error.message : macroMessages().actionFailed, 'threw');
+            }
+        },
         async getTextBefore(count) {
             // Auto-text's verification before it deletes: the answer must reflect
             // the live document, so `null` (unknown) is the only honest reply when

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { createMacroApi, MacroError, type MacroApi, type MacroBridge, type Scrip
 export { createEvalRunner } from './scripting/eval-runner.js';
 export { createIframeRunner, SANDBOX_BOOTSTRAP, isProtocolMessage } from './scripting/iframe-runner.js';
 export type { MacroRunner, MacroRunOptions, MacroRunResult } from './scripting/runner.js';
-export { MacroRecorder, replayMacro, type RecorderOptions, type ReplayOptions, type ReplayResult } from './recorder/recorder.js';
+export { MacroRecorder, replayMacro, type RecorderOptions, type RecordingWarning, type ReplayOptions, type ReplayResult, } from './recorder/recorder.js';
 export { renderSnippet, renderSnippetForHost, expandSnippet, usesSelection, type ExpandOptions, type RenderContext, } from './snippets/snippets.js';
 export { AutoText, type AutoTextOptions, type AutoTextExpansion } from './snippets/autotext.js';
 export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, isBindableKey, codesForKey, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget, } from './shortcuts.js';

package/dist/index.js

@@ -4,7 +4,7 @@ export { createSuperdocHost } from './host/superdoc-host.js';
 export { createMacroApi, MacroError } from './scripting/macro-api.js';
 export { createEvalRunner } from './scripting/eval-runner.js';
 export { createIframeRunner, SANDBOX_BOOTSTRAP, isProtocolMessage } from './scripting/iframe-runner.js';
-export { MacroRecorder, replayMacro } from './recorder/recorder.js';
+export { MacroRecorder, replayMacro, } from './recorder/recorder.js';
 export { renderSnippet, renderSnippetForHost, expandSnippet, usesSelection, } from './snippets/snippets.js';
 export { AutoText } from './snippets/autotext.js';
 export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, isBindableKey, codesForKey, } from './shortcuts.js';

package/dist/manager.d.ts

@@ -80,6 +80,18 @@ export declare class MacroKit {
      * UIs call it directly to show the message before saving.
      */
     validateShortcut(shortcut: string | undefined, excludeId?: string): ShortcutValidation;
+    /**
+     * The context-free binding rules, in one place: parseable, real modifier,
+     * physically-mappable key, not host-reserved. Manual save, import and
+     * legacy-state load all judge a shortcut by exactly this — a file or an
+     * old store must not smuggle in what typing cannot.
+     */
+    private bindingIssue;
+    /**
+     * Strips loaded shortcuts that today's rules reject — see the constructor.
+     * Items survive; only their bindings are dropped.
+     */
+    private sanitizeLoadedShortcuts;
     private findShortcutOwner;
     /** Throws a MacroError when the shortcut is unacceptable. The save paths call this. */
     private requireValidShortcut;
@@ -96,15 +108,33 @@ export declare class MacroKit {
     runSource(source: string): Promise<MacroRunResult>;
     get isRecording(): boolean;
     get recordedStepCount(): number;
-    startRecording(): void;
+    /**
+     * Starts a fresh recording. Returns false instead of overwriting an active
+     * or stopped-but-unsaved capture, or while another macro is running.
+     */
+    startRecording(): boolean;
     /**
      * Stops and saves. `null` when no step was recorded — there is nothing to
-     * save. Throws when the recording cannot be saved *whole* (its splittable
-     * steps still exceed the loader's step cap): a silently partial macro
-     * would replay something other than what the user did.
+     * save.
+     *
+     * Throws — with the stopped recording **retained for retry** (call again;
+     * `cancelRecording` is the explicit way to drop it) — when:
+     * - `recording-uncapturable`: every action was uncapturable, so even an
+     *   explicitly incomplete save would create an empty macro.
+     * - `recording-incomplete`: some actions could not be captured (e.g. an
+     *   inserted image, whose payload is the whole file). Saving that as-is
+     *   would present a macro that replays less than what the user did, so it
+     *   needs an explicit `allowIncomplete: true` from a confirming UI.
+     * - `recording-too-large`: even split, the steps exceed the loader's cap —
+     *   a silently partial macro is not produced.
+     * - a persistence failure (quota, oversized state).
      */
-    stopRecording(name: string, shortcut?: string): RecordedMacro | null;
+    stopRecording(name: string, shortcut?: string, options?: {
+        allowIncomplete?: boolean;
+    }): RecordedMacro | null;
     cancelRecording(): void;
+    /** Whether a stopped recording awaits a retried save (see stopRecording). */
+    get hasPendingRecording(): boolean;
     listRecordings(): readonly RecordedMacro[];
     removeRecording(id: string): void;
     /** Renames a recording or edits its shortcut. `null` when the recording was not found. */

package/dist/manager.js

@@ -49,7 +49,20 @@ export class MacroKit {
         this.runner =
             runner === 'iframe' ? createIframeRunner() : runner === 'eval' ? createEvalRunner() : runner;
         this.scriptsEnabled = options.scriptsEnabled ?? true;
+        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;
         this.state = this.storage.load() ?? emptyState();
+        // Loaded state passed the *structural* validation only. The semantic
+        // shortcut rules (bindable key, reserved list, duplicates) may have
+        // tightened since it was saved — a stale binding must not stay armed.
+        // Offending shortcuts are stripped, their items kept.
+        this.sanitizeLoadedShortcuts();
         this.recorder = new MacroRecorder(this.host, { onAutoStop: options.onRecordingAutoStop });
         this.autoText = new AutoText(this.host, () => this.state.snippets, {
             ...options.autoText,
@@ -61,14 +74,6 @@ export class MacroKit {
                 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 ---------- */
     /**
@@ -82,23 +87,61 @@ export class MacroKit {
         const trimmed = shortcut?.trim();
         if (!trimmed)
             return { ok: true };
-        const parsed = parseShortcut(trimmed);
+        const issue = this.bindingIssue(trimmed);
+        if (issue)
+            return { ok: false, message: issue.message };
+        const owner = this.findShortcutOwner(shortcutSignatures(parseShortcut(trimmed)), excludeId);
+        if (owner)
+            return { ok: false, message: macroMessages().shortcutTaken(owner) };
+        return { ok: true };
+    }
+    /**
+     * The context-free binding rules, in one place: parseable, real modifier,
+     * physically-mappable key, not host-reserved. Manual save, import and
+     * legacy-state load all judge a shortcut by exactly this — a file or an
+     * old store must not smuggle in what typing cannot.
+     */
+    bindingIssue(shortcut) {
+        const parsed = parseShortcut(shortcut);
         if (!parsed)
-            return { ok: false, message: macroMessages().shortcutInvalid };
+            return { message: macroMessages().shortcutInvalid };
         if (!hasBindingModifier(parsed))
-            return { ok: false, message: macroMessages().shortcutNeedsModifier };
+            return { message: macroMessages().shortcutNeedsModifier };
         // Only keys with a physical-code mapping (letters, digits, F-keys):
         // matching is by event.code, so it survives a Hebrew keyboard layout.
         if (!isBindableKey(parsed))
-            return { ok: false, message: macroMessages().shortcutInvalid };
-        const signatures = shortcutSignatures(parsed);
-        if (signatures.some((signature) => this.reservedSignatures.has(signature))) {
-            return { ok: false, message: macroMessages().shortcutReserved };
+            return { message: macroMessages().shortcutInvalid };
+        if (shortcutSignatures(parsed).some((signature) => this.reservedSignatures.has(signature))) {
+            return { message: macroMessages().shortcutReserved };
+        }
+        return null;
+    }
+    /**
+     * Strips loaded shortcuts that today's rules reject — see the constructor.
+     * Items survive; only their bindings are dropped.
+     */
+    sanitizeLoadedShortcuts() {
+        const seen = new Set();
+        const items = [
+            ...this.state.scripts,
+            ...this.state.recordings,
+            ...this.state.snippets,
+        ];
+        for (const item of items) {
+            if (!item.shortcut)
+                continue;
+            if (this.bindingIssue(item.shortcut)) {
+                delete item.shortcut;
+                continue;
+            }
+            const signatures = shortcutSignatures(parseShortcut(item.shortcut));
+            if (signatures.some((signature) => seen.has(signature))) {
+                delete item.shortcut;
+                continue;
+            }
+            for (const signature of signatures)
+                seen.add(signature);
         }
-        const owner = this.findShortcutOwner(signatures, excludeId);
-        if (owner)
-            return { ok: false, message: macroMessages().shortcutTaken(owner) };
-        return { ok: true };
     }
     findShortcutOwner(signatures, excludeId) {
         const items = [
@@ -180,26 +223,56 @@ export class MacroKit {
     get recordedStepCount() {
         return this.recorder.stepCount;
     }
+    /**
+     * Starts a fresh recording. Returns false instead of overwriting an active
+     * or stopped-but-unsaved capture, or while another macro is running.
+     */
     startRecording() {
-        if (this.running)
-            return;
+        if (this.running || this.recorder.recording || this.recorder.hasPending)
+            return false;
         this.recorder.start();
+        return this.recorder.recording;
     }
     /**
      * Stops and saves. `null` when no step was recorded — there is nothing to
-     * save. Throws when the recording cannot be saved *whole* (its splittable
-     * steps still exceed the loader's step cap): a silently partial macro
-     * would replay something other than what the user did.
+     * save.
+     *
+     * Throws — with the stopped recording **retained for retry** (call again;
+     * `cancelRecording` is the explicit way to drop it) — when:
+     * - `recording-uncapturable`: every action was uncapturable, so even an
+     *   explicitly incomplete save would create an empty macro.
+     * - `recording-incomplete`: some actions could not be captured (e.g. an
+     *   inserted image, whose payload is the whole file). Saving that as-is
+     *   would present a macro that replays less than what the user did, so it
+     *   needs an explicit `allowIncomplete: true` from a confirming UI.
+     * - `recording-too-large`: even split, the steps exceed the loader's cap —
+     *   a silently partial macro is not produced.
+     * - a persistence failure (quota, oversized state).
      */
-    stopRecording(name, shortcut) {
-        this.requireValidShortcut(shortcut);
-        this.requireItemLimits({ name, shortcut });
-        this.requireRoom(this.state.recordings);
-        const { steps, truncated } = splitOversizedSteps(this.recorder.stop());
+    stopRecording(name, shortcut, options = {}) {
+        // Stop first. Every failure below must leave the recorder inactive and
+        // its snapshot retryable. Checking capacity before stop() used to leave a
+        // manual recording active behind a stopped UI, and could lose an
+        // auto-stopped recording on the next start.
+        const pending = this.recorder.stop();
+        const { steps, truncated } = splitOversizedSteps(pending.steps);
         if (truncated)
             throw new MacroError(macroMessages().recordingTooLarge, 'recording-too-large');
-        if (steps.length === 0)
+        const commandIds = [...new Set(pending.warnings.map((warning) => warning.commandId))].join(', ');
+        if (pending.warnings.length > 0 && steps.length === 0) {
+            const messages = macroMessages();
+            throw new MacroError(messages.recordingUncapturable?.(commandIds) ?? messages.recordingIncomplete(commandIds), 'recording-uncapturable');
+        }
+        if (steps.length === 0) {
+            this.recorder.discard();
             return null;
+        }
+        this.requireValidShortcut(shortcut);
+        this.requireItemLimits({ name, shortcut });
+        this.requireRoom(this.state.recordings);
+        if (pending.warnings.length > 0 && !options.allowIncomplete) {
+            throw new MacroError(macroMessages().recordingIncomplete(commandIds), 'recording-incomplete');
+        }
         const recording = {
             version: 1,
             id: newId(),
@@ -208,14 +281,22 @@ export class MacroKit {
             ...(shortcut ? { shortcut } : {}),
             steps,
         };
-        return this.commit((draft) => {
+        const saved = this.commit((draft) => {
             draft.recordings.push(recording);
             return recording;
         });
+        // Only after the commit landed: a failed save keeps the recording
+        // retrievable for another attempt (delete an old macro, stop again).
+        this.recorder.discard();
+        return saved;
     }
     cancelRecording() {
         this.recorder.cancel();
     }
+    /** Whether a stopped recording awaits a retried save (see stopRecording). */
+    get hasPendingRecording() {
+        return this.recorder.hasPending;
+    }
     listRecordings() {
         return this.state.recordings;
     }
@@ -416,17 +497,14 @@ export class MacroKit {
         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) };
+            // The exact same context-free rules the manual save path applies —
+            // including the bindable-key restriction (an imported Ctrl+Tab must
+            // not slip in through the event.key fallback).
+            const issue = this.bindingIssue(item.shortcut);
+            if (issue) {
+                return { ok: false, message: macroMessages().importRejectedShortcut(item.name, issue.message) };
             }
-            for (const signature of shortcutSignatures(parsed)) {
-                if (this.reservedSignatures.has(signature)) {
-                    return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutReserved) };
-                }
+            for (const signature of shortcutSignatures(parseShortcut(item.shortcut))) {
                 const owner = seen.get(signature);
                 if (owner !== undefined) {
                     return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutTaken(owner)) };

package/dist/messages.d.ts

@@ -42,6 +42,13 @@ export interface MacroMessages {
     fieldTooLong: (field: string, max: number) => string;
     saveFailed: string;
     recordingTooLarge: string;
+    recordingIncomplete: (commandIds: string) => string;
+    /**
+     * No usable step was captured; saving with allowIncomplete would create an
+     * empty macro. Optional for source compatibility with existing full locale
+     * objects compiled against 0.7.0.
+     */
+    recordingUncapturable?: (commandIds: string) => string;
     shortcutInvalid: string;
     shortcutNeedsModifier: string;
     shortcutReserved: string;

package/dist/messages.js

@@ -42,6 +42,8 @@ export const ENGLISH_MESSAGES = {
     fieldTooLong: (field, max) => `${field} is too long (limit: ${max} characters)`,
     saveFailed: 'Saving failed — the change was not applied',
     recordingTooLarge: 'The recording is too large to save',
+    recordingIncomplete: (commandIds) => `The recording is missing actions that cannot be recorded (${commandIds})`,
+    recordingUncapturable: (commandIds) => `The recording contains only actions that cannot be recorded (${commandIds})`,
     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',
@@ -81,6 +83,8 @@ export const HEBREW_MESSAGES = {
     fieldTooLong: (field, max) => `${field} ארוך מדי (התקרה: ${max} תווים)`,
     saveFailed: 'השמירה נכשלה — השינוי לא הוחל',
     recordingTooLarge: 'ההקלטה גדולה מכדי להישמר',
+    recordingIncomplete: (commandIds) => `בהקלטה חסרות פעולות שאינן ניתנות להקלטה (${commandIds})`,
+    recordingUncapturable: (commandIds) => `ההקלטה מכילה רק פעולות שאינן ניתנות להקלטה (${commandIds})`,
     shortcutInvalid: 'קיצור לא תקין — הצורה הנדרשת היא למשל Ctrl+Alt+M',
     shortcutNeedsModifier: 'קיצור חייב לכלול Ctrl,‏ Alt או Meta',
     shortcutReserved: 'הקיצור הזה שמור לעורך',

package/dist/recorder/recorder.d.ts

@@ -1,4 +1,13 @@
 import type { MacroHost, MacroStep } from '../types.js';
+/**
+ * A user action the recorder could not capture faithfully. Surfaced, never
+ * swallowed: a macro that "saved successfully" but silently misses an image
+ * the user watched go in is a lie told at replay time.
+ */
+export interface RecordingWarning {
+    commandId: string;
+    reason: 'payload-too-large' | 'payload-not-serializable';
+}
 export interface RecorderOptions {
     /** Command filter. The default records everything except undo/redo. */
     shouldRecordCommand?: (id: string) => boolean;
@@ -18,6 +27,15 @@ export declare class MacroRecorder {
     private readonly maxSteps;
     private readonly onAutoStop?;
     private steps;
+    private warnings;
+    /**
+     * A stopped recording, held until `discard()`: the owner may fail to save
+     * it (storage quota, an incomplete recording awaiting confirmation) and
+     * must be able to come back for it. Clearing on stop() was the old
+     * behavior, and it lost recordings at exactly the moments they were
+     * hardest to redo.
+     */
+    private pending;
     private disposers;
     private active;
     /**
@@ -29,14 +47,22 @@ export declare class MacroRecorder {
     constructor(host: MacroHost, options?: RecorderOptions);
     get recording(): boolean;
     get stepCount(): number;
+    /** Whether a stopped recording is waiting to be saved or discarded. */
+    get hasPending(): boolean;
     start(): void;
     /**
-     * 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.
+     * Stops and returns the recording — steps plus any warnings about actions
+     * that could not be captured. The result stays retrievable (calling
+     * `stop()` again returns the same recording) until `discard()`, `cancel()`
+     * or a new `start()`: a save that fails must be retryable.
      */
-    stop(): MacroStep[];
-    /** Stops and discards whatever was recorded. */
+    stop(): {
+        steps: MacroStep[];
+        warnings: RecordingWarning[];
+    };
+    /** Releases a stopped recording after it was successfully saved (or knowingly dropped). */
+    discard(): void;
+    /** Stops and discards whatever was recorded — including a pending stopped recording. */
     cancel(): void;
     /**
      * Rewrites the recorded tail after an auto-text expansion: the user typed
@@ -54,6 +80,13 @@ export declare class MacroRecorder {
     applyAutoTextExpansion(consumed: number, replacement: string): void;
     private teardown;
     private push;
+    private addWarning;
+    /**
+     * Warnings are part of the stopped snapshot just like steps. Counting both
+     * prevents a warning-only recording from growing without bound while never
+     * reaching the ordinary step cap.
+     */
+    private maybeAutoStop;
     /**
      * Records a programmatic insertion the host will not report as typing —
      * e.g. a snippet expanded from a button or shortcut, which writes through

package/dist/recorder/recorder.js

@@ -24,6 +24,15 @@ export class MacroRecorder {
     maxSteps;
     onAutoStop;
     steps = [];
+    warnings = [];
+    /**
+     * A stopped recording, held until `discard()`: the owner may fail to save
+     * it (storage quota, an incomplete recording awaiting confirmation) and
+     * must be able to come back for it. Clearing on stop() was the old
+     * behavior, and it lost recordings at exactly the moments they were
+     * hardest to redo.
+     */
+    pending = null;
     disposers = [];
     active = false;
     /**
@@ -44,31 +53,49 @@ export class MacroRecorder {
     get stepCount() {
         return this.steps.length;
     }
+    /** Whether a stopped recording is waiting to be saved or discarded. */
+    get hasPending() {
+        return this.pending !== null;
+    }
     start() {
         if (this.active)
             return;
         this.active = true;
         this.steps = [];
+        this.warnings = [];
+        // Starting anew is the explicit "I no longer want the unsaved one".
+        this.pending = null;
         this.disposers = [
             this.host.onCommand((id, payload) => this.recordCommand(id, payload)),
             this.host.onTextInput((event) => this.recordTextInput(event)),
         ];
     }
     /**
-     * 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.
+     * Stops and returns the recording — steps plus any warnings about actions
+     * that could not be captured. The result stays retrievable (calling
+     * `stop()` again returns the same recording) until `discard()`, `cancel()`
+     * or a new `start()`: a save that fails must be retryable.
      */
     stop() {
-        this.teardown();
-        const recorded = this.steps;
-        this.steps = [];
-        return recorded;
+        if (this.active)
+            this.teardown();
+        if (!this.pending && (this.steps.length > 0 || this.warnings.length > 0)) {
+            this.pending = { steps: this.steps, warnings: this.warnings };
+            this.steps = [];
+            this.warnings = [];
+        }
+        return this.pending ?? { steps: [], warnings: [] };
+    }
+    /** Releases a stopped recording after it was successfully saved (or knowingly dropped). */
+    discard() {
+        this.pending = null;
     }
-    /** Stops and discards whatever was recorded. */
+    /** Stops and discards whatever was recorded — including a pending stopped recording. */
     cancel() {
         this.teardown();
         this.steps = [];
+        this.warnings = [];
+        this.pending = null;
     }
     /**
      * Rewrites the recorded tail after an auto-text expansion: the user typed
@@ -119,12 +146,27 @@ export class MacroRecorder {
     }
     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();
-            this.onAutoStop?.();
-        }
+        this.maybeAutoStop();
+    }
+    addWarning(warning) {
+        this.warnings.push(warning);
+        this.maybeAutoStop();
+    }
+    /**
+     * Warnings are part of the stopped snapshot just like steps. Counting both
+     * prevents a warning-only recording from growing without bound while never
+     * reaching the ordinary step cap.
+     */
+    maybeAutoStop() {
+        if (!this.active)
+            return;
+        if (this.steps.length + this.warnings.length < this.maxSteps)
+            return;
+        this.teardown();
+        this.pending = { steps: this.steps, warnings: this.warnings };
+        this.steps = [];
+        this.warnings = [];
+        this.onAutoStop?.();
     }
     /**
      * Records a programmatic insertion the host will not report as typing —
@@ -147,17 +189,27 @@ export class MacroRecorder {
         // The payload is opaque engine data, but not unlimited: it must survive
         // a JSON round-trip within the persistence cap, or the recording would
         // be rejected by the loader. A command whose payload cannot be kept
-        // faithfully is skipped whole — replaying it with a mangled payload
-        // would do something other than what was recorded.
+        // faithfully is not stepped — replaying it with a mangled payload would
+        // do something other than what was recorded — but it is never dropped
+        // *silently*: the warning is what lets the owner refuse to present the
+        // recording as complete. Inserting an image is the concrete case — its
+        // payload carries the whole file as a data URL.
         let json;
         try {
             json = JSON.stringify(payload);
         }
         catch {
+            this.addWarning({ commandId: id, reason: 'payload-not-serializable' });
             return;
         }
-        if (typeof json !== 'string' || json.length > IMPORT_LIMITS.maxPayloadLength)
+        if (typeof json !== 'string') {
+            this.addWarning({ commandId: id, reason: 'payload-not-serializable' });
             return;
+        }
+        if (json.length > IMPORT_LIMITS.maxPayloadLength) {
+            this.addWarning({ commandId: id, reason: 'payload-too-large' });
+            return;
+        }
         this.push({ type: 'command', id, payload: JSON.parse(json) });
     }
     recordTextInput(event) {

package/dist/shortcuts.d.ts

@@ -26,6 +26,8 @@ export interface KeyEventLike {
     repeat?: boolean;
     /** Mid-IME-composition — keys belong to the composition, not to bindings. */
     isComposing?: boolean;
+    /** Legacy IME marker: some WebViews report keyCode 229 without isComposing. */
+    keyCode?: number;
     preventDefault?(): void;
     stopPropagation?(): void;
 }

package/dist/shortcuts.js

@@ -117,8 +117,9 @@ export function hasBindingModifier(parsed) {
 export function bindShortcuts(target, getBindings) {
     const listener = (event) => {
         // Auto-repeat must not replay a macro per repeat tick, and keys mid-IME
-        // composition belong to the composition.
-        if (event.repeat || event.isComposing)
+        // composition belong to the composition — including the legacy keyCode
+        // 229 marker some WebViews report without setting isComposing.
+        if (event.repeat || event.isComposing || event.keyCode === 229)
             return;
         for (const binding of getBindings()) {
             const parsed = parseShortcut(binding.shortcut);

package/dist/snippets/autotext.js

@@ -84,27 +84,44 @@ export class AutoText {
             // to the document. Deferring to the task queue guarantees the expansion
             // character is already in before it is deleted along with the trigger.
             await new Promise((resolve) => setTimeout(resolve, 0));
-            // Second line of defense, independent of the event stream: the
-            // document itself must hold the trigger right before the caret. A
-            // caret move the host failed to report (or a race with another
-            // writer) is caught here instead of deleting foreign text.
+            // Fail closed, in both directions: the document must *verifiably*
+            // hold the trigger right before the caret. A mismatch means the caret
+            // moved (or another writer raced us); `null`/`undefined` means the
+            // host cannot tell — and a feature that deletes text on its own
+            // initiative does not get the benefit of the doubt. Auto-text simply
+            // does not expand where it cannot verify.
             const expected = trigger + expandChar;
+            const rendered = renderSnippet(snippet.text, {
+                selectionText: usesSelection(snippet.text)
+                    ? (await this.host.getSelection({ includeText: true })).text
+                    : undefined,
+            });
+            const replacement = rendered + expandChar;
+            // Preferred path: one atomic engine transaction that verifies and
+            // replaces together — nothing to roll back.
+            if (this.host.replaceTextBefore) {
+                const replaced = await this.host.replaceTextBefore(expected, replacement);
+                if (!replaced.ok) {
+                    this.onError?.(replaced.message);
+                    return;
+                }
+                this.onExpand?.(snippet, { trigger, expandChar, rendered });
+                return;
+            }
             const actual = await this.host.getTextBefore?.(expected.length);
-            if (typeof actual === 'string' && actual !== expected)
+            if (actual !== expected)
                 return;
-            const selectionText = usesSelection(snippet.text)
-                ? (await this.host.getSelection({ includeText: true })).text
-                : undefined;
-            const rendered = renderSnippet(snippet.text, { selectionText });
-            // The expansion character is already in the document by now, so it is
-            // included in the deletion and restored at the end.
-            const deleted = await this.host.deleteBackward(trigger.length + 1);
+            // Two-operation fallback for hosts without an atomic replace. If the
+            // insertion fails after the deletion succeeded, the trigger is put
+            // back — the user must not be left with their word silently eaten.
+            const deleted = await this.host.deleteBackward(expected.length);
             if (!deleted.ok) {
                 this.onError?.(deleted.message);
                 return;
             }
-            const inserted = await this.host.insertText(rendered + expandChar);
+            const inserted = await this.host.insertText(replacement);
             if (!inserted.ok) {
+                await this.host.insertText(expected);
                 this.onError?.(inserted.message);
                 return;
             }

package/dist/types.d.ts

@@ -78,6 +78,13 @@ export interface MacroHost {
      * caret move the host failed to report.
      */
     getTextBefore?(count: number): Promise<string | null>;
+    /**
+     * Atomically replaces the `expected.length` characters before the caret
+     * with `replacement` — verifying they equal `expected` first, all inside
+     * one engine transaction. Auto-text prefers this over delete+insert: two
+     * operations leave the trigger deleted when the second fails.
+     */
+    replaceTextBefore?(expected: string, replacement: string): Promise<MacroOutcome>;
     /** Replaces every occurrence of `query` with `replacement`. Returns how many were replaced. */
     replaceAll(query: string, replacement: string): Promise<{
         ok: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superdoc-macros",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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",