superdoc-macros 0.5.0 → 0.7.0

package/dist/messages.js

@@ -40,6 +40,9 @@ 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',
+    recordingIncomplete: (commandIds) => `The recording is missing actions that cannot be recorded (${commandIds})`,
     shortcutInvalid: 'Invalid shortcut — use a form like Ctrl+Alt+M',
     shortcutNeedsModifier: 'A shortcut must include Ctrl, Alt or Meta',
     shortcutReserved: 'This shortcut is reserved by the editor',
@@ -77,6 +80,9 @@ export const HEBREW_MESSAGES = {
     tooManyItems: 'הרשימה מלאה — יש למחוק פריטים לפני הוספה',
     nameRequired: 'חובה לתת שם',
     fieldTooLong: (field, max) => `${field} ארוך מדי (התקרה: ${max} תווים)`,
+    saveFailed: 'השמירה נכשלה — השינוי לא הוחל',
+    recordingTooLarge: 'ההקלטה גדולה מכדי להישמר',
+    recordingIncomplete: (commandIds) => `בהקלטה חסרות פעולות שאינן ניתנות להקלטה (${commandIds})`,
     shortcutInvalid: 'קיצור לא תקין — הצורה הנדרשת היא למשל Ctrl+Alt+M',
     shortcutNeedsModifier: 'קיצור חייב לכלול Ctrl,‏ Alt או Meta',
     shortcutReserved: 'הקיצור הזה שמור לעורך',

package/dist/recorder/recorder.d.ts

@@ -1,18 +1,13 @@
+import type { MacroHost, MacroStep } from '../types.js';
 /**
- * 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.
+ * A user action the recorder could not capture faithfully. Surfaced, never
+ * swallowed: a macro that "saved successfully" but silently misses an image
+ * the user watched go in is a lie told at replay time.
  */
-import type { MacroHost, MacroStep } from '../types.js';
+export interface RecordingWarning {
+    commandId: string;
+    reason: 'payload-too-large' | 'payload-not-serializable';
+}
 export interface RecorderOptions {
     /** Command filter. The default records everything except undo/redo. */
     shouldRecordCommand?: (id: string) => boolean;
@@ -32,19 +27,42 @@ export declare class MacroRecorder {
     private readonly maxSteps;
     private readonly onAutoStop?;
     private steps;
+    private warnings;
+    /**
+     * A stopped recording, held until `discard()`: the owner may fail to save
+     * it (storage quota, an incomplete recording awaiting confirmation) and
+     * must be able to come back for it. Clearing on stop() was the old
+     * behavior, and it lost recordings at exactly the moments they were
+     * hardest to redo.
+     */
+    private pending;
     private disposers;
     private active;
+    /**
+     * 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;
+    /** Whether a stopped recording is waiting to be saved or discarded. */
+    get hasPending(): boolean;
     start(): void;
     /**
-     * Stops and returns the steps. Empty when nothing was recorded. Also the
-     * way to collect a recording that auto-stopped at the cap — the steps are
-     * kept until someone asks for them.
+     * Stops and returns the recording — steps plus any warnings about actions
+     * that could not be captured. The result stays retrievable (calling
+     * `stop()` again returns the same recording) until `discard()`, `cancel()`
+     * or a new `start()`: a save that fails must be retryable.
      */
-    stop(): MacroStep[];
-    /** Stops and discards whatever was recorded. */
+    stop(): {
+        steps: MacroStep[];
+        warnings: RecordingWarning[];
+    };
+    /** Releases a stopped recording after it was successfully saved (or knowingly dropped). */
+    discard(): void;
+    /** Stops and discards whatever was recorded — including a pending stopped recording. */
     cancel(): void;
     /**
      * Rewrites the recorded tail after an auto-text expansion: the user typed
@@ -62,6 +80,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) {
@@ -9,8 +24,23 @@ export class MacroRecorder {
     maxSteps;
     onAutoStop;
     steps = [];
+    warnings = [];
+    /**
+     * A stopped recording, held until `discard()`: the owner may fail to save
+     * it (storage quota, an incomplete recording awaiting confirmation) and
+     * must be able to come back for it. Clearing on stop() was the old
+     * behavior, and it lost recordings at exactly the moments they were
+     * hardest to redo.
+     */
+    pending = null;
     disposers = [];
     active = false;
+    /**
+     * 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;
@@ -23,31 +53,49 @@ export class MacroRecorder {
     get stepCount() {
         return this.steps.length;
     }
+    /** Whether a stopped recording is waiting to be saved or discarded. */
+    get hasPending() {
+        return this.pending !== null;
+    }
     start() {
         if (this.active)
             return;
         this.active = true;
         this.steps = [];
+        this.warnings = [];
+        // Starting anew is the explicit "I no longer want the unsaved one".
+        this.pending = null;
         this.disposers = [
             this.host.onCommand((id, payload) => this.recordCommand(id, payload)),
             this.host.onTextInput((event) => this.recordTextInput(event)),
         ];
     }
     /**
-     * Stops and returns the steps. Empty when nothing was recorded. Also the
-     * way to collect a recording that auto-stopped at the cap — the steps are
-     * kept until someone asks for them.
+     * Stops and returns the recording — steps plus any warnings about actions
+     * that could not be captured. The result stays retrievable (calling
+     * `stop()` again returns the same recording) until `discard()`, `cancel()`
+     * or a new `start()`: a save that fails must be retryable.
      */
     stop() {
-        this.teardown();
-        const recorded = this.steps;
-        this.steps = [];
-        return recorded;
+        if (this.active)
+            this.teardown();
+        if (!this.pending && (this.steps.length > 0 || this.warnings.length > 0)) {
+            this.pending = { steps: this.steps, warnings: this.warnings };
+            this.steps = [];
+            this.warnings = [];
+        }
+        return this.pending ?? { steps: [], warnings: [] };
     }
-    /** Stops and discards whatever was recorded. */
+    /** Releases a stopped recording after it was successfully saved (or knowingly dropped). */
+    discard() {
+        this.pending = null;
+    }
+    /** Stops and discards whatever was recorded — including a pending stopped recording. */
     cancel() {
         this.teardown();
         this.steps = [];
+        this.warnings = [];
+        this.pending = null;
     }
     /**
      * Rewrites the recorded tail after an auto-text expansion: the user typed
@@ -105,17 +153,59 @@ 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 not stepped — replaying it with a mangled payload would
+        // do something other than what was recorded — but it is never dropped
+        // *silently*: the warning is what lets the owner refuse to present the
+        // recording as complete. Inserting an image is the concrete case — its
+        // payload carries the whole file as a data URL.
+        let json;
+        try {
+            json = JSON.stringify(payload);
+        }
+        catch {
+            this.warnings.push({ commandId: id, reason: 'payload-not-serializable' });
+            return;
+        }
+        if (typeof json !== 'string') {
+            this.warnings.push({ commandId: id, reason: 'payload-not-serializable' });
+            return;
+        }
+        if (json.length > IMPORT_LIMITS.maxPayloadLength) {
+            this.warnings.push({ commandId: id, reason: 'payload-too-large' });
+            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 +216,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 +224,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,35 @@ 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;
+    /** Legacy IME marker: some WebViews report keyCode 229 without isComposing. */
+    keyCode?: number;
     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,11 @@ 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 — including the legacy keyCode
+        // 229 marker some WebViews report without setting isComposing.
+        if (event.repeat || event.isComposing || event.keyCode === 229)
+            return;
         for (const binding of getBindings()) {
             const parsed = parseShortcut(binding.shortcut);
             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,19 +84,44 @@ export class AutoText {
             // to the document. Deferring to the task queue guarantees the expansion
             // character is already in before it is deleted along with the trigger.
             await new Promise((resolve) => setTimeout(resolve, 0));
-            const selectionText = usesSelection(snippet.text)
-                ? (await this.host.getSelection({ includeText: true })).text
-                : undefined;
-            const rendered = renderSnippet(snippet.text, { selectionText });
-            // The expansion character is already in the document by now, so it is
-            // included in the deletion and restored at the end.
-            const deleted = await this.host.deleteBackward(trigger.length + 1);
+            // Fail closed, in both directions: the document must *verifiably*
+            // hold the trigger right before the caret. A mismatch means the caret
+            // moved (or another writer raced us); `null`/`undefined` means the
+            // host cannot tell — and a feature that deletes text on its own
+            // initiative does not get the benefit of the doubt. Auto-text simply
+            // does not expand where it cannot verify.
+            const expected = trigger + expandChar;
+            const rendered = renderSnippet(snippet.text, {
+                selectionText: usesSelection(snippet.text)
+                    ? (await this.host.getSelection({ includeText: true })).text
+                    : undefined,
+            });
+            const replacement = rendered + expandChar;
+            // Preferred path: one atomic engine transaction that verifies and
+            // replaces together — nothing to roll back.
+            if (this.host.replaceTextBefore) {
+                const replaced = await this.host.replaceTextBefore(expected, replacement);
+                if (!replaced.ok) {
+                    this.onError?.(replaced.message);
+                    return;
+                }
+                this.onExpand?.(snippet, { trigger, expandChar, rendered });
+                return;
+            }
+            const actual = await this.host.getTextBefore?.(expected.length);
+            if (actual !== expected)
+                return;
+            // Two-operation fallback for hosts without an atomic replace. If the
+            // insertion fails after the deletion succeeded, the trigger is put
+            // back — the user must not be left with their word silently eaten.
+            const deleted = await this.host.deleteBackward(expected.length);
             if (!deleted.ok) {
                 this.onError?.(deleted.message);
                 return;
             }
-            const inserted = await this.host.insertText(rendered + expandChar);
+            const inserted = await this.host.insertText(replacement);
             if (!inserted.ok) {
+                await this.host.insertText(expected);
                 this.onError?.(inserted.message);
                 return;
             }

package/dist/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;
         },
     };
 }