superdoc-macros 0.5.0 → 0.6.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,22 @@ export function createSuperdocHost(options) {
         async getSelection(options) {
             return (await readSelectionDetailed(options?.includeText ?? false)).snapshot;
         },
+        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 +404,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

@@ -7,7 +7,7 @@ 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 { 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

@@ -5,7 +5,7 @@ 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 { 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

@@ -97,7 +97,12 @@ 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. */
+    /**
+     * 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.
+     */
     stopRecording(name: string, shortcut?: string): RecordedMacro | null;
     cancelRecording(): void;
     listRecordings(): readonly RecordedMacro[];
@@ -169,5 +174,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';
@@ -87,6 +87,10 @@ export class MacroKit {
             return { ok: false, message: macroMessages().shortcutInvalid };
         if (!hasBindingModifier(parsed))
             return { ok: false, 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 };
@@ -126,7 +130,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 +138,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,12 +185,19 @@ export class MacroKit {
             return;
         this.recorder.start();
     }
-    /** Stops and saves. `null` when no step was recorded — there is nothing to save. */
+    /**
+     * 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.
+     */
     stopRecording(name, shortcut) {
         this.requireValidShortcut(shortcut);
-        this.requireItemLimits({ name });
+        this.requireItemLimits({ name, shortcut });
         this.requireRoom(this.state.recordings);
-        const steps = splitOversizedSteps(this.recorder.stop());
+        const { steps, truncated } = splitOversizedSteps(this.recorder.stop());
+        if (truncated)
+            throw new MacroError(macroMessages().recordingTooLarge, 'recording-too-large');
         if (steps.length === 0)
             return null;
         const recording = {
@@ -195,9 +208,10 @@ export class MacroKit {
             ...(shortcut ? { shortcut } : {}),
             steps,
         };
-        this.state.recordings.push(recording);
-        this.persist();
-        return recording;
+        return this.commit((draft) => {
+            draft.recordings.push(recording);
+            return recording;
+        });
     }
     cancelRecording() {
         this.recorder.cancel();
@@ -206,28 +220,30 @@ export class MacroKit {
         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 +272,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 +286,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 +392,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 };
     }
     /**
@@ -424,6 +459,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 +487,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');
+        }
+        if (!this.storage.save(candidate)) {
+            throw new MacroError(macroMessages().saveFailed, 'storage-failed');
         }
-        this.storage.save(this.state);
+        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 +535,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,8 @@ export interface MacroMessages {
     importTooLarge: string;
     tooManyItems: string;
     fieldTooLong: (field: string, max: number) => string;
+    saveFailed: string;
+    recordingTooLarge: string;
     shortcutInvalid: string;
     shortcutNeedsModifier: string;
     shortcutReserved: string;

package/dist/messages.js

@@ -40,6 +40,8 @@ export const ENGLISH_MESSAGES = {
     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)`,
+    saveFailed: 'Saving failed — the change was not applied',
+    recordingTooLarge: 'The recording is too large to save',
     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',
@@ -77,6 +79,8 @@ export const HEBREW_MESSAGES = {
     tooManyItems: 'הרשימה מלאה — יש למחוק פריטים לפני הוספה',
     nameRequired: 'חובה לתת שם',
     fieldTooLong: (field, max) => `${field} ארוך מדי (התקרה: ${max} תווים)`,
+    saveFailed: 'השמירה נכשלה — השינוי לא הוחל',
+    recordingTooLarge: 'ההקלטה גדולה מכדי להישמר',
     shortcutInvalid: 'קיצור לא תקין — הצורה הנדרשת היא למשל Ctrl+Alt+M',
     shortcutNeedsModifier: 'קיצור חייב לכלול Ctrl,‏ Alt או Meta',
     shortcutReserved: 'הקיצור הזה שמור לעורך',

package/dist/recorder/recorder.d.ts

@@ -1,17 +1,3 @@
-/**
- * A Word-style macro recorder: records **commands** and typing, not caret
- * positions.
- *
- * That choice is deliberate. Recording raw ProseMirror steps (with absolute
- * positions) breaks the moment the document differs from what it was at
- * recording time; recording commands ("bold", "bullet-list", typing a
- * greeting) behaves like Word's recorder — the actions apply wherever the
- * caret is at replay time. It is also what makes a recording saveable and
- * shareable: the steps are plain JSON.
- *
- * What is not recorded: caret movement and mouse selection. As in Word, a
- * recorded macro acts from wherever the caret stands when it runs.
- */
 import type { MacroHost, MacroStep } from '../types.js';
 export interface RecorderOptions {
     /** Command filter. The default records everything except undo/redo. */
@@ -34,6 +20,12 @@ export declare class MacroRecorder {
     private steps;
     private disposers;
     private active;
+    /**
+     * Set by a caret move: the next typed character starts a fresh step
+     * instead of coalescing — text typed at a new position is not a
+     * continuation of the text typed at the old one.
+     */
+    private tailInterrupted;
     constructor(host: MacroHost, options?: RecorderOptions);
     get recording(): boolean;
     get stepCount(): number;
@@ -62,6 +54,13 @@ export declare class MacroRecorder {
     applyAutoTextExpansion(consumed: number, replacement: string): void;
     private teardown;
     private push;
+    /**
+     * Records a programmatic insertion the host will not report as typing —
+     * e.g. a snippet expanded from a button or shortcut, which writes through
+     * the document API and never fires beforeinput. Without this, a replay
+     * would silently miss text the user watched appear.
+     */
+    recordInsert(text: string): void;
     private recordCommand;
     private recordTextInput;
 }

package/dist/recorder/recorder.js

@@ -1,3 +1,18 @@
+/**
+ * A Word-style macro recorder: records **commands** and typing, not caret
+ * positions.
+ *
+ * That choice is deliberate. Recording raw ProseMirror steps (with absolute
+ * positions) breaks the moment the document differs from what it was at
+ * recording time; recording commands ("bold", "bullet-list", typing a
+ * greeting) behaves like Word's recorder — the actions apply wherever the
+ * caret is at replay time. It is also what makes a recording saveable and
+ * shareable: the steps are plain JSON.
+ *
+ * What is not recorded: caret movement and mouse selection. As in Word, a
+ * recorded macro acts from wherever the caret stands when it runs.
+ */
+import { IMPORT_LIMITS } from '../storage.js';
 const DEFAULT_MAX_STEPS = 5_000;
 /** Undo/redo during recording fix the recording itself — replaying them would replay the mistake too. */
 function defaultShouldRecord(id) {
@@ -11,6 +26,12 @@ export class MacroRecorder {
     steps = [];
     disposers = [];
     active = false;
+    /**
+     * Set by a caret move: the next typed character starts a fresh step
+     * instead of coalescing — text typed at a new position is not a
+     * continuation of the text typed at the old one.
+     */
+    tailInterrupted = false;
     constructor(host, options = {}) {
         this.host = host;
         this.shouldRecordCommand = options.shouldRecordCommand ?? defaultShouldRecord;
@@ -105,17 +126,49 @@ export class MacroRecorder {
             this.onAutoStop?.();
         }
     }
+    /**
+     * Records a programmatic insertion the host will not report as typing —
+     * e.g. a snippet expanded from a button or shortcut, which writes through
+     * the document API and never fires beforeinput. Without this, a replay
+     * would silently miss text the user watched appear.
+     */
+    recordInsert(text) {
+        if (!this.active || text.length === 0)
+            return;
+        this.recordTextInput({ kind: 'insert-text', text });
+    }
     recordCommand(id, payload) {
         if (!this.shouldRecordCommand(id))
             return;
-        this.push(payload === undefined ? { type: 'command', id } : { type: 'command', id, payload });
+        if (payload === undefined) {
+            this.push({ type: 'command', id });
+            return;
+        }
+        // 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.
+        let json;
+        try {
+            json = JSON.stringify(payload);
+        }
+        catch {
+            return;
+        }
+        if (typeof json !== 'string' || json.length > IMPORT_LIMITS.maxPayloadLength)
+            return;
+        this.push({ type: 'command', id, payload: JSON.parse(json) });
     }
     recordTextInput(event) {
+        const interrupted = this.tailInterrupted;
+        this.tailInterrupted = false;
         const last = this.steps[this.steps.length - 1];
         switch (event.kind) {
             case 'insert-text': {
-                // Consecutive keystrokes coalesce into one step — more readable, faster to replay.
-                if (last?.type === 'insert-text') {
+                // Consecutive keystrokes coalesce into one step — more readable,
+                // faster to replay — but never across a caret move.
+                if (!interrupted && last?.type === 'insert-text') {
                     last.text += event.text;
                     return;
                 }
@@ -126,7 +179,7 @@ export class MacroRecorder {
                 this.push({ type: 'insert-paragraph' });
                 return;
             case 'delete-backward': {
-                if (last?.type === 'delete-backward') {
+                if (!interrupted && last?.type === 'delete-backward') {
                     last.count += 1;
                     return;
                 }
@@ -134,13 +187,18 @@ export class MacroRecorder {
                 return;
             }
             case 'delete-forward': {
-                if (last?.type === 'delete-forward') {
+                if (!interrupted && last?.type === 'delete-forward') {
                     last.count += 1;
                     return;
                 }
                 this.push({ type: 'delete-forward', count: 1 });
                 return;
             }
+            case 'caret-moved':
+                // Not a step — replay acts from the live caret — but the recorded
+                // tail is no longer "where the user is typing".
+                this.tailInterrupted = true;
+                return;
         }
     }
 }

package/dist/shortcuts.d.ts

@@ -16,14 +16,33 @@ export interface ParsedShortcut {
 /** The subset of KeyboardEvent that matching needs. Enables DOM-free tests. */
 export interface KeyEventLike {
     key: string;
+    /** The physical key. When present, letters and digits match by it — see `eventMatches`. */
+    code?: string;
     ctrlKey: boolean;
     altKey: boolean;
     shiftKey: boolean;
     metaKey: boolean;
+    /** Key held down — auto-repeat must not re-fire a macro. */
+    repeat?: boolean;
+    /** Mid-IME-composition — keys belong to the composition, not to bindings. */
+    isComposing?: boolean;
     preventDefault?(): void;
     stopPropagation?(): void;
 }
 export declare function parseShortcut(shortcut: string): ParsedShortcut | null;
+/**
+ * The physical `event.code` values a binding key stands for. Letters and
+ * digits get a deterministic mapping; anything else returns empty and falls
+ * back to `event.key`.
+ *
+ * Physical-key matching is what keeps a binding alive across keyboard
+ * layouts: on a Hebrew layout Ctrl+Alt+R reports `key: 'ר'`, and a
+ * key-based match would die the moment the user switches to Hebrew — the
+ * exact bug the host editor once had with its own shortcuts.
+ */
+export declare function codesForKey(key: string): readonly string[];
+/** Whether the key can be bound reliably (has a physical-code mapping). */
+export declare function isBindableKey(parsed: ParsedShortcut): boolean;
 export declare function eventMatches(parsed: ParsedShortcut, event: KeyEventLike): boolean;
 /**
  * Comparable signatures for collision checks. `Mod` matches either Ctrl or

package/dist/shortcuts.js

@@ -44,8 +44,40 @@ function normalizeKey(key) {
         return 'escape';
     return lower;
 }
+/**
+ * The physical `event.code` values a binding key stands for. Letters and
+ * digits get a deterministic mapping; anything else returns empty and falls
+ * back to `event.key`.
+ *
+ * Physical-key matching is what keeps a binding alive across keyboard
+ * layouts: on a Hebrew layout Ctrl+Alt+R reports `key: 'ר'`, and a
+ * key-based match would die the moment the user switches to Hebrew — the
+ * exact bug the host editor once had with its own shortcuts.
+ */
+export function codesForKey(key) {
+    if (/^[a-z]$/.test(key))
+        return [`Key${key.toUpperCase()}`];
+    if (/^[0-9]$/.test(key))
+        return [`Digit${key}`, `Numpad${key}`];
+    if (/^f([1-9]|1[0-2])$/.test(key))
+        return [key.toUpperCase()];
+    if (key === ' ')
+        return ['Space'];
+    if (key === 'escape')
+        return ['Escape'];
+    return [];
+}
+/** Whether the key can be bound reliably (has a physical-code mapping). */
+export function isBindableKey(parsed) {
+    return codesForKey(parsed.key).length > 0;
+}
 export function eventMatches(parsed, event) {
-    if (normalizeKey(event.key) !== parsed.key)
+    const codes = codesForKey(parsed.key);
+    const keyMatched = normalizeKey(event.key) === parsed.key;
+    // The physical code decides whenever both sides have one; `event.key` is
+    // the fallback for keys with no mapping or hosts that do not report codes.
+    const matched = codes.length > 0 && event.code !== undefined ? codes.includes(event.code) : keyMatched;
+    if (!matched)
         return false;
     if (parsed.mod) {
         if (!event.ctrlKey && !event.metaKey)
@@ -84,6 +116,10 @@ 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)
+            return;
         for (const binding of getBindings()) {
             const parsed = parseShortcut(binding.shortcut);
             if (!parsed || !eventMatches(parsed, event))

package/dist/snippets/autotext.js

@@ -50,6 +50,12 @@ export class AutoText {
             case 'delete-forward':
                 this.buffer = '';
                 return;
+            // A click or navigation key moved the caret: the buffer no longer
+            // describes what sits before it, and expanding on it would delete
+            // text at the new position. Missing an expansion is the cheap error.
+            case 'caret-moved':
+                this.buffer = '';
+                return;
             case 'delete-backward':
                 this.buffer = this.buffer.slice(0, -1);
                 return;
@@ -78,6 +84,14 @@ 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.
+            const expected = trigger + expandChar;
+            const actual = await this.host.getTextBefore?.(expected.length);
+            if (typeof actual === 'string' && actual !== expected)
+                return;
             const selectionText = usesSelection(snippet.text)
                 ? (await this.host.getSelection({ includeText: true })).text
                 : undefined;

package/dist/snippets/snippets.d.ts

@@ -26,5 +26,11 @@ export interface ExpandOptions {
     now?: Date;
     locale?: string;
 }
+/**
+ * Renders a snippet against the live document (reads the selection only
+ * when the snippet needs it). Split from the insertion so a caller that
+ * must know what text actually landed — e.g. a recorder — can.
+ */
+export declare function renderSnippetForHost(host: MacroHost, snippet: Pick<Snippet, 'text'>, options?: ExpandOptions): Promise<string>;
 /** Expands a snippet at the caret. */
 export declare function expandSnippet(host: MacroHost, snippet: Pick<Snippet, 'text'>, options?: ExpandOptions): Promise<MacroOutcome>;

package/dist/snippets/snippets.js

@@ -24,17 +24,23 @@ export function renderSnippet(text, context = {}) {
 export function usesSelection(text) {
     return /\{\{\s*selection\s*\}\}/iu.test(text);
 }
-/** Expands a snippet at the caret. */
-export async function expandSnippet(host, snippet, options = {}) {
-    // The selection is read only when needed: extracting its text has an engine cost.
+/**
+ * Renders a snippet against the live document (reads the selection only
+ * when the snippet needs it). Split from the insertion so a caller that
+ * must know what text actually landed — e.g. a recorder — can.
+ */
+export async function renderSnippetForHost(host, snippet, options = {}) {
     const selectionText = usesSelection(snippet.text)
         ? (await host.getSelection({ includeText: true })).text
         : undefined;
-    const rendered = renderSnippet(snippet.text, {
+    return renderSnippet(snippet.text, {
         variables: options.variables,
         selectionText,
         now: options.now,
         locale: options.locale,
     });
-    return host.insertText(rendered);
+}
+/** Expands a snippet at the caret. */
+export async function expandSnippet(host, snippet, options = {}) {
+    return host.insertText(await renderSnippetForHost(host, snippet, options));
 }

package/dist/storage.d.ts

@@ -13,7 +13,12 @@ export interface PersistedMacroState {
 export interface MacroStorage {
     /** `null` when there is no saved state or the saved state is unreadable. */
     load(): PersistedMacroState | null;
-    save(state: PersistedMacroState): void;
+    /**
+     * Persists the state. Returns whether it actually landed — quota and
+     * serialization failures come back as `false`, never as a throw, so the
+     * caller can refuse to adopt an in-memory change its storage rejected.
+     */
+    save(state: PersistedMacroState): boolean;
 }
 export declare function emptyState(): PersistedMacroState;
 /**
@@ -33,13 +38,18 @@ export declare const IMPORT_LIMITS: {
     /** Snippet text and single recorded insert-text step. */
     readonly maxTextLength: 100000;
     readonly maxSourceLength: 200000;
+    /** A recorded command payload, serialized. Engine payloads are small config objects. */
+    readonly maxPayloadLength: 10000;
 };
 /**
- * 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.
+ * Serializes state iff it passes the exact validation the loader applies —
+ * including the whole-file size cap the loader enforces on read. `null`
+ * otherwise. 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 serializePersistable(value: unknown): string | null;
+/** Whether `serializePersistable` would accept the state. */
 export declare function isPersistableState(value: unknown): value is PersistedMacroState;
 /**
  * Parses saved/imported state. `null` on any unexpected shape, oversized

package/dist/storage.js

@@ -18,6 +18,8 @@ export const IMPORT_LIMITS = {
     /** Snippet text and single recorded insert-text step. */
     maxTextLength: 100_000,
     maxSourceLength: 200_000,
+    /** A recorded command payload, serialized. Engine payloads are small config objects. */
+    maxPayloadLength: 10_000,
 };
 function boundedString(value, maxLength, allowEmpty = false) {
     return typeof value === 'string' && value.length <= maxLength && (allowEmpty || value.length > 0);
@@ -25,14 +27,26 @@ function boundedString(value, maxLength, allowEmpty = false) {
 function optionalBoundedString(value, maxLength) {
     return value === undefined || boundedString(value, maxLength);
 }
+/** Whether a recorded payload is JSON-clean and bounded. Opaque otherwise — but not unlimited. */
+function isValidPayload(payload) {
+    if (payload === undefined)
+        return true;
+    let json;
+    try {
+        json = JSON.stringify(payload);
+    }
+    catch {
+        return false;
+    }
+    return typeof json === 'string' && json.length <= IMPORT_LIMITS.maxPayloadLength;
+}
 function isValidStep(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const step = value;
     switch (step.type) {
         case 'command':
-            // The payload is opaque engine data; the id is what replay dispatches on.
-            return boundedString(step.id, IMPORT_LIMITS.maxNameLength);
+            return boundedString(step.id, IMPORT_LIMITS.maxNameLength) && isValidPayload(step.payload);
         case 'insert-text':
             return boundedString(step.text, IMPORT_LIMITS.maxTextLength, true);
         case 'insert-paragraph':
@@ -92,13 +106,27 @@ function isValidState(value) {
         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.
+ * Serializes state iff it passes the exact validation the loader applies —
+ * including the whole-file size cap the loader enforces on read. `null`
+ * otherwise. 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 serializePersistable(value) {
+    if (!isValidState(value))
+        return null;
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        return null;
+    }
+    return json.length <= IMPORT_LIMITS.maxJsonLength ? json : null;
+}
+/** Whether `serializePersistable` would accept the state. */
 export function isPersistableState(value) {
-    return isValidState(value);
+    return serializePersistable(value) !== null;
 }
 /**
  * Parses saved/imported state. `null` on any unexpected shape, oversized
@@ -142,10 +170,17 @@ export function createLocalStorage(key = DEFAULT_STORAGE_KEY, storage) {
         },
         save(state) {
             try {
-                backing()?.setItem(key, JSON.stringify(state));
+                const store = backing();
+                if (!store)
+                    return false;
+                store.setItem(key, JSON.stringify(state));
+                return true;
             }
             catch (error) {
+                // Quota or serialization — reported, not swallowed: the caller must
+                // know the change did not land.
                 console.warn('[superdoc-macros] saving macros failed', error);
+                return false;
             }
         },
     };
@@ -157,6 +192,7 @@ export function createMemoryStorage() {
         load: () => (saved ? JSON.parse(JSON.stringify(saved)) : null),
         save(state) {
             saved = JSON.parse(JSON.stringify(state));
+            return true;
         },
     };
 }

package/dist/types.d.ts

@@ -38,6 +38,15 @@ export type TextInputEvent = {
     kind: 'delete-backward';
 } | {
     kind: 'delete-forward';
+}
+/**
+ * The caret moved by pointer or navigation keys. Not an edit — the
+ * recorder records no step — but both consumers depend on it: auto-text
+ * resets its typed-word buffer (the buffer no longer describes what sits
+ * before the caret), and the recorder stops coalescing across it.
+ */
+ | {
+    kind: 'caret-moved';
 };
 /**
  * What the toolkit needs from the editor. The SuperDoc v2 implementation is
@@ -62,6 +71,13 @@ export interface MacroHost {
     getSelection(options?: {
         includeText?: boolean;
     }): Promise<SelectionSnapshot>;
+    /**
+     * The `count` characters immediately before the caret, or `null` when the
+     * host cannot tell. Auto-text verifies the document actually holds the
+     * trigger word before deleting it — the buffer alone can lie after a
+     * caret move the host failed to report.
+     */
+    getTextBefore?(count: number): Promise<string | null>;
     /** 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.5.0",
+  "version": "0.6.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",