superdoc-macros 0.4.0 → 0.6.0

package/dist/messages.js

@@ -33,7 +33,15 @@ export const ENGLISH_MESSAGES = {
     snippetNotFound: 'Snippet not found',
     cannotRunWhileRecording: 'Cannot run a macro while recording',
     anotherMacroRunning: 'Another macro is still running',
+    scriptsDisabled: 'Scripted macros are disabled',
     invalidImport: 'The file is not a valid macro export',
+    importRejectedShortcut: (itemName, detail) => `Import rejected: the shortcut of "${itemName}" is not acceptable — ${detail}`,
+    importTooLarge: 'Import rejected: the merged result exceeds the item limits',
+    tooManyItems: 'The list is full — delete items before adding new ones',
+    nameRequired: 'A name is required',
+    fieldTooLong: (field, max) => `${field} is too long (limit: ${max} characters)`,
+    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',
@@ -64,7 +72,15 @@ export const HEBREW_MESSAGES = {
     snippetNotFound: 'הקטע לא נמצא',
     cannotRunWhileRecording: 'אי אפשר להריץ מאקרו בזמן הקלטה',
     anotherMacroRunning: 'מאקרו אחר עדיין רץ',
+    scriptsDisabled: 'מאקרו כתובים מושבתים',
     invalidImport: 'הקובץ אינו ייצוא מאקרו תקין',
+    importRejectedShortcut: (itemName, detail) => `הייבוא נדחה: הקיצור של "${itemName}" אינו קביל — ${detail}`,
+    importTooLarge: 'הייבוא נדחה: התוצאה הממוזגת חורגת מתקרת הפריטים',
+    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,41 +1,66 @@
-/**
- * A Word-style macro recorder: records **commands** and typing, not caret
- * positions.
- *
- * That choice is deliberate. Recording raw ProseMirror steps (with absolute
- * positions) breaks the moment the document differs from what it was at
- * recording time; recording commands ("bold", "bullet-list", typing a
- * greeting) behaves like Word's recorder — the actions apply wherever the
- * caret is at replay time. It is also what makes a recording saveable and
- * shareable: the steps are plain JSON.
- *
- * What is not recorded: caret movement and mouse selection. As in Word, a
- * recorded macro acts from wherever the caret stands when it runs.
- */
 import type { MacroHost, MacroStep } from '../types.js';
 export interface RecorderOptions {
     /** Command filter. The default records everything except undo/redo. */
     shouldRecordCommand?: (id: string) => boolean;
     /** Step cap per recording, against a recording left running by mistake. */
     maxSteps?: number;
+    /**
+     * Called when the step cap stops the recording. The steps are kept —
+     * `stop()` still returns them — but listening has ceased, and a UI that
+     * shows "recording" must be told, or its indicator would keep promising a
+     * recording that is no longer happening.
+     */
+    onAutoStop?: () => void;
 }
 export declare class MacroRecorder {
     private readonly host;
     private readonly shouldRecordCommand;
     private readonly maxSteps;
+    private readonly onAutoStop?;
     private steps;
     private disposers;
     private active;
+    /**
+     * 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;
     start(): void;
-    /** Stops and returns the steps. Empty when nothing was recorded. */
+    /**
+     * Stops and returns the steps. Empty when nothing was recorded. Also the
+     * way to collect a recording that auto-stopped at the cap — the steps are
+     * kept until someone asks for them.
+     */
     stop(): MacroStep[];
     /** Stops and discards whatever was recorded. */
     cancel(): void;
+    /**
+     * Rewrites the recorded tail after an auto-text expansion: the user typed
+     * a trigger word plus the expansion character, but what the document now
+     * holds is the expanded text — a replay of the raw keystrokes would
+     * diverge (and would depend on auto-text being active at replay time).
+     * The trailing `consumed` characters are removed from the recorded
+     * insert-text steps and the expanded text is recorded in their place.
+     *
+     * If the tail does not hold `consumed` plain characters (a command landed
+     * mid-word, or the recording started mid-trigger), the rewrite is skipped
+     * and the raw keystrokes stay — a truthful raw recording beats a guessed
+     * edit of steps that do not match.
+     */
+    applyAutoTextExpansion(consumed: number, replacement: string): void;
     private teardown;
     private push;
+    /**
+     * 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) {
@@ -7,13 +22,21 @@ export class MacroRecorder {
     host;
     shouldRecordCommand;
     maxSteps;
+    onAutoStop;
     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;
         this.maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+        this.onAutoStop = options.onAutoStop;
     }
     get recording() {
         return this.active;
@@ -31,10 +54,12 @@ export class MacroRecorder {
             this.host.onTextInput((event) => this.recordTextInput(event)),
         ];
     }
-    /** Stops and returns the steps. Empty when nothing was recorded. */
+    /**
+     * Stops and returns the steps. Empty when nothing was recorded. Also the
+     * way to collect a recording that auto-stopped at the cap — the steps are
+     * kept until someone asks for them.
+     */
     stop() {
-        if (!this.active)
-            return [];
         this.teardown();
         const recorded = this.steps;
         this.steps = [];
@@ -42,34 +67,108 @@ export class MacroRecorder {
     }
     /** Stops and discards whatever was recorded. */
     cancel() {
-        if (!this.active)
-            return;
         this.teardown();
         this.steps = [];
     }
+    /**
+     * Rewrites the recorded tail after an auto-text expansion: the user typed
+     * a trigger word plus the expansion character, but what the document now
+     * holds is the expanded text — a replay of the raw keystrokes would
+     * diverge (and would depend on auto-text being active at replay time).
+     * The trailing `consumed` characters are removed from the recorded
+     * insert-text steps and the expanded text is recorded in their place.
+     *
+     * If the tail does not hold `consumed` plain characters (a command landed
+     * mid-word, or the recording started mid-trigger), the rewrite is skipped
+     * and the raw keystrokes stay — a truthful raw recording beats a guessed
+     * edit of steps that do not match.
+     */
+    applyAutoTextExpansion(consumed, replacement) {
+        if (!this.active || consumed <= 0)
+            return;
+        // Verify the tail is entirely typed text before touching anything.
+        let remaining = consumed;
+        let index = this.steps.length - 1;
+        while (remaining > 0 && index >= 0) {
+            const step = this.steps[index];
+            if (step?.type !== 'insert-text')
+                return;
+            remaining -= step.text.length;
+            index -= 1;
+        }
+        if (remaining > 0)
+            return;
+        let toRemove = consumed;
+        while (toRemove > 0) {
+            const last = this.steps[this.steps.length - 1];
+            if (last?.type !== 'insert-text')
+                return; // unreachable after the check above
+            if (last.text.length > toRemove) {
+                last.text = last.text.slice(0, -toRemove);
+                break;
+            }
+            toRemove -= last.text.length;
+            this.steps.pop();
+        }
+        this.recordTextInput({ kind: 'insert-text', text: replacement });
+    }
     teardown() {
         this.active = false;
         for (const dispose of this.disposers.splice(0))
             dispose();
     }
     push(step) {
+        this.steps.push(step);
         if (this.steps.length >= this.maxSteps) {
+            // The cap stops the *listening*, not the data: the steps stay for
+            // stop() to collect, and the owner is told the recording ended.
             this.teardown();
-            return;
+            this.onAutoStop?.();
         }
-        this.steps.push(step);
+    }
+    /**
+     * 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;
                 }
@@ -80,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;
                 }
@@ -88,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.d.ts

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

package/dist/snippets/autotext.js

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

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,7 +38,19 @@ 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;
 };
+/**
+ * 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
  * field or oversized file — never throws, never partially accepts: one

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':
@@ -91,6 +105,29 @@ function isValidState(value) {
         state.snippets.length <= IMPORT_LIMITS.maxItems &&
         state.snippets.every(isValidSnippet));
 }
+/**
+ * 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 serializePersistable(value) !== null;
+}
 /**
  * Parses saved/imported state. `null` on any unexpected shape, oversized
  * field or oversized file — never throws, never partially accepts: one
@@ -133,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;
             }
         },
     };
@@ -148,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;