superdoc-macros 0.5.0 → 0.7.0

package/README.md

@@ -140,11 +140,11 @@ kit.importState(json, { merge: true });
 
 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.
+The same limits hold as a persistence invariant, transactionally: every mutation runs on a clone that must serialize under the loader's exact rules (shape, field caps, whole-file size) *and* be accepted by the storage before it becomes the state — a quota failure or an oversized save leaves memory and disk agreeing on the previous state, and can never wipe the store on the next startup. An oversized recorded paste is split into loadable steps; a recording that cannot be saved whole is refused with a message rather than saved partially.
 
 ## Shortcut safety
 
-Saved bindings go through `kit.validateShortcut(shortcut, excludeId?)` — enforced on every save: a binding must parse, must carry a real modifier (Ctrl/Alt/Meta — a bare letter would fire on ordinary typing), must not collide with another saved item, and must not collide with shortcuts the host declared as reserved:
+Saved bindings go through `kit.validateShortcut(shortcut, excludeId?)` — enforced on every save and on the merged result of every import: a binding must parse, must carry a real modifier (Ctrl/Alt/Meta — a bare letter would fire on ordinary typing), must use a physically-mappable key (letters, digits, F-keys — matching is by `event.code`, so bindings survive non-Latin keyboard layouts), must not collide with another saved item, and must not collide with shortcuts the host declared as reserved. Auto-repeat and keys mid-IME-composition never fire bindings:
 
 ```ts
 const kit = new MacroKit({ host, reservedShortcuts: ['Ctrl+S', 'Ctrl+P', /* … the editor's registry … */] });

package/dist/host/superdoc-host.js

@@ -113,6 +113,25 @@ export function createSuperdocHost(options) {
         if (typeof data === 'string' && data.length > 0)
             emitInput({ kind: 'insert-text', text: data });
     };
+    /* Caret movement: a click or a navigation key breaks the link between the
+       recently-typed characters and what actually sits before the caret.
+       Auto-text resets its buffer on this, and the recorder stops coalescing
+       across it. Reported as an input event so any MacroHost can supply it. */
+    const NAVIGATION_KEYS = new Set([
+        'ArrowLeft',
+        'ArrowRight',
+        'ArrowUp',
+        'ArrowDown',
+        'Home',
+        'End',
+        'PageUp',
+        'PageDown',
+    ]);
+    const onPointerDown = () => emitInput({ kind: 'caret-moved' });
+    const onKeydown = (event) => {
+        if (NAVIGATION_KEYS.has(event.key))
+            emitInput({ kind: 'caret-moved' });
+    };
     const onBeforeInput = (event) => {
         const input = event;
         let mapped = null;
@@ -156,6 +175,8 @@ export function createSuperdocHost(options) {
     container?.addEventListener('beforeinput', onBeforeInput, true);
     container?.addEventListener('compositionstart', onCompositionStart, true);
     container?.addEventListener('compositionend', onCompositionEnd, true);
+    container?.addEventListener('pointerdown', onPointerDown, true);
+    container?.addEventListener('keydown', onKeydown, true);
     /**
      * `failed: true` means the engine call itself threw — as opposed to a
      * clean "no selection" answer. Callers that write relative to the caret
@@ -306,6 +327,44 @@ 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
+            // the view is unavailable — never a guess.
+            const pm = view();
+            if (!pm)
+                return null;
+            try {
+                const { from } = pm.state.selection;
+                const start = Math.max(0, from - Math.max(0, Math.trunc(count)));
+                return pm.state.doc.textBetween(start, from);
+            }
+            catch {
+                return null;
+            }
+        },
         async replaceAll(query, replacement) {
             const handle = search();
             if (!handle)
@@ -367,6 +426,8 @@ export function createSuperdocHost(options) {
             container?.removeEventListener('beforeinput', onBeforeInput, true);
             container?.removeEventListener('compositionstart', onCompositionStart, true);
             container?.removeEventListener('compositionend', onCompositionEnd, true);
+            container?.removeEventListener('pointerdown', onPointerDown, true);
+            container?.removeEventListener('keydown', onKeydown, true);
             commandListeners.clear();
             inputListeners.clear();
         },

package/dist/index.d.ts

@@ -6,8 +6,8 @@ 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 { renderSnippet, expandSnippet, usesSelection, type ExpandOptions, type RenderContext } from './snippets/snippets.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, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget, } from './shortcuts.js';
-export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, type MacroStorage, type PersistedMacroState, } from './storage.js';
+export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, isBindableKey, codesForKey, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget, } from './shortcuts.js';
+export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, serializePersistable, type MacroStorage, type PersistedMacroState, } from './storage.js';

package/dist/index.js

@@ -4,8 +4,8 @@ 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 { renderSnippet, expandSnippet, usesSelection } from './snippets/snippets.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, } from './shortcuts.js';
-export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, } from './storage.js';
+export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, isBindableKey, codesForKey, } from './shortcuts.js';
+export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, serializePersistable, } from './storage.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;
@@ -97,9 +109,26 @@ export declare class MacroKit {
     get isRecording(): boolean;
     get recordedStepCount(): number;
     startRecording(): void;
-    /** Stops and saves. `null` when no step was recorded — there is nothing to save. */
-    stopRecording(name: string, shortcut?: string): RecordedMacro | null;
+    /**
+     * Stops and saves. `null` when no step was recorded — there is nothing to
+     * save.
+     *
+     * Throws — with the stopped recording **retained for retry** (call again;
+     * `cancelRecording` is the explicit way to drop it) — when:
+     * - `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, 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. */
@@ -169,5 +198,19 @@ export declare class MacroKit {
     /** The item-count half of the invariant. `existingId` exempts an in-place update. */
     private requireRoom;
     private upsert;
-    private persist;
+    /**
+     * Applies a mutation transactionally: the change runs on a clone, and the
+     * clone becomes the state only through `adopt` — validation and storage
+     * included. A failure at any stage leaves the previous state fully
+     * intact. Before this, the in-memory state mutated first and a quota
+     * failure left memory and disk silently disagreeing until the next
+     * successful save rewrote history.
+     */
+    private commit;
+    /**
+     * The persistence invariant, in one place: a candidate becomes the state
+     * only if it serializes under the loader's exact rules (shape, field
+     * caps, whole-file size) *and* the storage actually accepted it.
+     */
+    private adopt;
 }

package/dist/manager.js

@@ -12,9 +12,9 @@ import { createEvalRunner } from './scripting/eval-runner.js';
 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 { renderSnippetForHost } from './snippets/snippets.js';
+import { IMPORT_LIMITS, isPersistableState, serializePersistable } from './storage.js';
+import { bindShortcuts, hasBindingModifier, isBindableKey, parseShortcut, shortcutSignatures, } from './shortcuts.js';
 import { MacroError } from './scripting/macro-api.js';
 import { createLocalStorage, emptyState, parsePersistedState } from './storage.js';
 import { macroMessages } from './messages.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,20 +87,62 @@ export class MacroKit {
         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);
+        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 { message: macroMessages().shortcutInvalid };
+        if (!hasBindingModifier(parsed))
+            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 { 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);
+        }
+    }
     findShortcutOwner(signatures, excludeId) {
         const items = [
             ...this.state.scripts,
@@ -126,7 +173,7 @@ export class MacroKit {
     }
     saveScript(input) {
         this.requireValidShortcut(input.shortcut, input.id);
-        this.requireItemLimits({ name: input.name, source: input.source });
+        this.requireItemLimits({ name: input.name, source: input.source, shortcut: input.shortcut });
         this.requireRoom(this.state.scripts, input.id);
         const script = {
             id: input.id ?? newId(),
@@ -134,13 +181,15 @@ export class MacroKit {
             source: input.source,
             ...(input.shortcut ? { shortcut: input.shortcut } : {}),
         };
-        this.upsert(this.state.scripts, script);
-        this.persist();
-        return script;
+        return this.commit((draft) => {
+            this.upsert(draft.scripts, script);
+            return script;
+        });
     }
     removeScript(id) {
-        this.state.scripts = this.state.scripts.filter((script) => script.id !== id);
-        this.persist();
+        this.commit((draft) => {
+            draft.scripts = draft.scripts.filter((script) => script.id !== id);
+        });
     }
     async runScript(id) {
         const script = this.state.scripts.find((entry) => entry.id === id);
@@ -179,14 +228,36 @@ export class MacroKit {
             return;
         this.recorder.start();
     }
-    /** Stops and saves. `null` when no step was recorded — there is nothing to save. */
-    stopRecording(name, shortcut) {
+    /**
+     * Stops and saves. `null` when no step was recorded — there is nothing to
+     * save.
+     *
+     * Throws — with the stopped recording **retained for retry** (call again;
+     * `cancelRecording` is the explicit way to drop it) — when:
+     * - `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, options = {}) {
         this.requireValidShortcut(shortcut);
-        this.requireItemLimits({ name });
+        this.requireItemLimits({ name, shortcut });
         this.requireRoom(this.state.recordings);
-        const steps = splitOversizedSteps(this.recorder.stop());
-        if (steps.length === 0)
+        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) {
+            this.recorder.discard();
             return null;
+        }
+        if (pending.warnings.length > 0 && !options.allowIncomplete) {
+            const commandIds = [...new Set(pending.warnings.map((warning) => warning.commandId))].join(', ');
+            throw new MacroError(macroMessages().recordingIncomplete(commandIds), 'recording-incomplete');
+        }
         const recording = {
             version: 1,
             id: newId(),
@@ -195,39 +266,50 @@ export class MacroKit {
             ...(shortcut ? { shortcut } : {}),
             steps,
         };
-        this.state.recordings.push(recording);
-        this.persist();
-        return recording;
+        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;
     }
     removeRecording(id) {
-        this.state.recordings = this.state.recordings.filter((recording) => recording.id !== id);
-        this.persist();
+        this.commit((draft) => {
+            draft.recordings = draft.recordings.filter((recording) => recording.id !== id);
+        });
     }
     /** Renames a recording or edits its shortcut. `null` when the recording was not found. */
     updateRecording(input) {
-        const recording = this.state.recordings.find((entry) => entry.id === input.id);
-        if (!recording)
+        if (!this.state.recordings.some((entry) => entry.id === input.id))
             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) {
-            if (input.shortcut)
-                recording.shortcut = input.shortcut;
-            else
-                delete recording.shortcut;
-        }
-        this.persist();
-        return recording;
+            this.requireItemLimits({ name: input.name, shortcut: input.shortcut });
+        return this.commit((draft) => {
+            const recording = draft.recordings.find((entry) => entry.id === input.id);
+            if (input.name !== undefined)
+                recording.name = input.name;
+            if (input.shortcut !== undefined) {
+                if (input.shortcut)
+                    recording.shortcut = input.shortcut;
+                else
+                    delete recording.shortcut;
+            }
+            return recording;
+        });
     }
     async replayRecording(id, options) {
         const recording = this.state.recordings.find((entry) => entry.id === id);
@@ -256,7 +338,12 @@ export class MacroKit {
     }
     saveSnippet(input) {
         this.requireValidShortcut(input.shortcut, input.id);
-        this.requireItemLimits({ name: input.name, text: input.text, trigger: input.trigger });
+        this.requireItemLimits({
+            name: input.name,
+            text: input.text,
+            trigger: input.trigger,
+            shortcut: input.shortcut,
+        });
         this.requireRoom(this.state.snippets, input.id);
         const snippet = {
             id: input.id ?? newId(),
@@ -265,20 +352,30 @@ export class MacroKit {
             ...(input.trigger ? { trigger: input.trigger } : {}),
             ...(input.shortcut ? { shortcut: input.shortcut } : {}),
         };
-        this.upsert(this.state.snippets, snippet);
-        this.persist();
-        return snippet;
+        return this.commit((draft) => {
+            this.upsert(draft.snippets, snippet);
+            return snippet;
+        });
     }
     removeSnippet(id) {
-        this.state.snippets = this.state.snippets.filter((snippet) => snippet.id !== id);
-        this.persist();
+        this.commit((draft) => {
+            draft.snippets = draft.snippets.filter((snippet) => snippet.id !== id);
+        });
     }
     async expandSnippet(id, options) {
         const snippet = this.state.snippets.find((entry) => entry.id === id);
         if (!snippet)
             return { ok: false, message: macroMessages().snippetNotFound };
-        const outcome = await expandSnippet(this.host, snippet, options);
-        return outcome.ok ? { ok: true } : { ok: false, message: outcome.message };
+        const rendered = await renderSnippetForHost(this.host, snippet, options);
+        const outcome = await this.host.insertText(rendered);
+        if (!outcome.ok)
+            return { ok: false, message: outcome.message };
+        // A snippet expanded from a button or shortcut writes through the
+        // document API and fires no typing events — recorded explicitly, or a
+        // replay would silently miss text the user watched appear. The auto-text
+        // path needs nothing here: its expansion rewrites the typed tail.
+        this.recorder.recordInsert(rendered);
+        return { ok: true };
     }
     /** Enables auto-text (trigger + space). Returns a disable function. */
     enableAutoText() {
@@ -361,8 +458,12 @@ export class MacroKit {
         const shortcutsOk = this.validateStateShortcuts(candidate);
         if (!shortcutsOk.ok)
             return shortcutsOk;
-        this.state = candidate;
-        this.persist();
+        try {
+            this.adopt(candidate);
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : macroMessages().saveFailed };
+        }
         return { ok: true };
     }
     /**
@@ -381,17 +482,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) };
+            // 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) };
             }
-            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) };
-                }
+            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)) };
@@ -424,6 +522,9 @@ export class MacroKit {
         if (fields.name.length > limits.maxNameLength) {
             throw new MacroError(macroMessages().fieldTooLong('name', limits.maxNameLength), 'invalid-item');
         }
+        if (fields.shortcut !== undefined && fields.shortcut.length > limits.maxShortcutLength) {
+            throw new MacroError(macroMessages().fieldTooLong('shortcut', limits.maxShortcutLength), 'invalid-item');
+        }
         if (fields.text !== undefined && fields.text.length > limits.maxTextLength) {
             throw new MacroError(macroMessages().fieldTooLong('text', limits.maxTextLength), 'invalid-item');
         }
@@ -449,22 +550,42 @@ export class MacroKit {
         else
             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;
+    /**
+     * Applies a mutation transactionally: the change runs on a clone, and the
+     * clone becomes the state only through `adopt` — validation and storage
+     * included. A failure at any stage leaves the previous state fully
+     * intact. Before this, the in-memory state mutated first and a quota
+     * failure left memory and disk silently disagreeing until the next
+     * successful save rewrote history.
+     */
+    commit(mutate) {
+        const draft = JSON.parse(JSON.stringify(this.state));
+        const result = mutate(draft);
+        this.adopt(draft);
+        return result;
+    }
+    /**
+     * The persistence invariant, in one place: a candidate becomes the state
+     * only if it serializes under the loader's exact rules (shape, field
+     * caps, whole-file size) *and* the storage actually accepted it.
+     */
+    adopt(candidate) {
+        if (serializePersistable(candidate) === null) {
+            throw new MacroError(macroMessages().saveFailed, 'invalid-state');
         }
-        this.storage.save(this.state);
+        if (!this.storage.save(candidate)) {
+            throw new MacroError(macroMessages().saveFailed, 'storage-failed');
+        }
+        this.state = candidate;
     }
 }
 /**
  * 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.
+ * keeping the recording loadable. `truncated` reports the pathological case
+ * where even the split exceeds the loader's step limit — the caller refuses
+ * to save then, with a message: a silently partial macro is worse than no
+ * macro.
  */
 function splitOversizedSteps(steps) {
     const max = IMPORT_LIMITS.maxTextLength;
@@ -477,12 +598,5 @@ function splitOversizedSteps(steps) {
         }
         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;
+    return { steps: split, truncated: split.length > IMPORT_LIMITS.maxStepsPerRecording };
 }

package/dist/messages.d.ts

@@ -40,6 +40,9 @@ export interface MacroMessages {
     importTooLarge: string;
     tooManyItems: string;
     fieldTooLong: (field: string, max: number) => string;
+    saveFailed: string;
+    recordingTooLarge: string;
+    recordingIncomplete: (commandIds: string) => string;
     shortcutInvalid: string;
     shortcutNeedsModifier: string;
     shortcutReserved: string;