superdoc-macros 0.4.0 → 0.6.0

package/README.md

@@ -82,6 +82,8 @@ Honest limits: the browser offers no per-iframe memory cap, and a host call that
 
 If you must waive isolation (e.g. a CSP that blocks `srcdoc`), switch to the direct runner: `new MacroKit({ host, runner: 'eval' })` — see the warnings in the code.
 
+**A real off switch:** `new MacroKit({ host, scriptsEnabled: false })` gates script *execution*, not just UI — `runScript`/`runSource` refuse and saved script shortcuts are not bound, so a pre-existing or imported script cannot run through any path. Recordings and snippets are unaffected.
+
 ## 2. Macro recorder
 
 ```ts
@@ -136,11 +138,13 @@ kit.importState(json, { merge: true });
 
 `MacroStorage` is a two-method interface — implement it to persist to a file (e.g. a plugin workspace).
 
-Imports are strictly validated: every item and every recorded step is type-checked and size-bounded (see `IMPORT_LIMITS`), and one invalid item rejects the whole file — no partial imports.
+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, 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 { AutoText, type AutoTextOptions } 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, type MacroStorage, type PersistedMacroState, } from './storage.js';
+export { renderSnippet, renderSnippetForHost, expandSnippet, usesSelection, type ExpandOptions, type RenderContext, } from './snippets/snippets.js';
+export { AutoText, type AutoTextOptions, type AutoTextExpansion } from './snippets/autotext.js';
+export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, isBindableKey, codesForKey, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget, } from './shortcuts.js';
+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, } 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

@@ -38,6 +38,20 @@ export interface MacroKitOptions {
      * editor shortcut. Unparseable entries are ignored.
      */
     reservedShortcuts?: readonly string[];
+    /**
+     * Whether scripted macros may *execute*. Default: true. When false the
+     * gate is real, not cosmetic: `runScript`/`runSource` refuse, and saved
+     * script shortcuts are not bound — so a pre-existing or imported script
+     * cannot run through any path. Saving and listing still work (a UI may
+     * let the user manage scripts it will not run).
+     */
+    scriptsEnabled?: boolean;
+    /**
+     * Called when a recording hits the step cap and stops on its own. The
+     * steps are kept — `stopRecording(name)` still saves them — but a UI that
+     * shows a live "recording" indicator must update it.
+     */
+    onRecordingAutoStop?: () => void;
 }
 export type ShortcutValidation = {
     ok: true;
@@ -55,6 +69,7 @@ export declare class MacroKit {
     private readonly recorder;
     private readonly autoText;
     private readonly reservedSignatures;
+    private readonly scriptsEnabled;
     private running;
     constructor(options: MacroKitOptions);
     /**
@@ -82,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[];
@@ -123,6 +143,12 @@ export declare class MacroKit {
      * Imports JSON produced by `exportState`. With `merge: true` an imported
      * item with an existing `id` replaces it; without merge the whole state is
      * replaced.
+     *
+     * The check is **atomic, on the final result**: a candidate state is built
+     * first, its size limits and every shortcut in it are validated (the same
+     * rules the save paths enforce — a file cannot smuggle in what typing
+     * cannot), and only a candidate that passed in full is committed. On any
+     * failure the current state is untouched.
      */
     importState(json: string, options?: {
         merge?: boolean;
@@ -130,7 +156,37 @@ export declare class MacroKit {
         ok: boolean;
         message?: string;
     };
+    /**
+     * Every shortcut in a candidate state, under the exact rules of
+     * `validateShortcut`: parseable, real modifier, not host-reserved, and
+     * unique within the candidate. `importState` is the only caller — the
+     * save paths enforce the same rules one item at a time.
+     */
+    private validateStateShortcuts;
     private guardRun;
+    /**
+     * The save-path half of the persistence invariant: field lengths that the
+     * loader would reject are refused at the door. Without this, one oversized
+     * save would make the whole store unloadable — and the next startup would
+     * silently fall back to an empty state, losing everything.
+     */
+    private requireItemLimits;
+    /** 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,8 +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 { 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';
@@ -37,6 +38,7 @@ export class MacroKit {
     recorder;
     autoText;
     reservedSignatures;
+    scriptsEnabled;
     running = false;
     constructor(options) {
         this.host = options.host;
@@ -46,9 +48,19 @@ export class MacroKit {
         const runner = options.runner ?? 'iframe';
         this.runner =
             runner === 'iframe' ? createIframeRunner() : runner === 'eval' ? createEvalRunner() : runner;
+        this.scriptsEnabled = options.scriptsEnabled ?? true;
         this.state = this.storage.load() ?? emptyState();
-        this.recorder = new MacroRecorder(this.host);
-        this.autoText = new AutoText(this.host, () => this.state.snippets, options.autoText);
+        this.recorder = new MacroRecorder(this.host, { onAutoStop: options.onRecordingAutoStop });
+        this.autoText = new AutoText(this.host, () => this.state.snippets, {
+            ...options.autoText,
+            // The recorder rewrite keeps recordings truthful: the user typed a
+            // trigger word, the document holds the expanded text, and a replay of
+            // the raw keystrokes would diverge. See applyAutoTextExpansion.
+            onExpand: (snippet, expansion) => {
+                this.recorder.applyAutoTextExpansion(expansion.trigger.length + expansion.expandChar.length, expansion.rendered + expansion.expandChar);
+                options.autoText?.onExpand?.(snippet, expansion);
+            },
+        });
         const reserved = new Set();
         for (const shortcut of options.reservedShortcuts ?? []) {
             const parsed = parseShortcut(shortcut);
@@ -75,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 };
@@ -114,19 +130,23 @@ export class MacroKit {
     }
     saveScript(input) {
         this.requireValidShortcut(input.shortcut, input.id);
+        this.requireItemLimits({ name: input.name, source: input.source, shortcut: input.shortcut });
+        this.requireRoom(this.state.scripts, input.id);
         const script = {
             id: input.id ?? newId(),
             name: input.name,
             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);
@@ -136,6 +156,11 @@ export class MacroKit {
     }
     /** Runs an unsaved script — e.g. from the macro editor before saving. */
     async runSource(source) {
+        // The real gate: with scripts disabled nothing executes through any
+        // path — not a saved script, not an imported one, not its shortcut.
+        if (!this.scriptsEnabled) {
+            return { ok: false, reason: 'error', message: macroMessages().scriptsDisabled };
+        }
         const guard = this.guardRun();
         if (guard)
             return guard;
@@ -160,10 +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);
-        const steps = this.recorder.stop();
+        this.requireItemLimits({ name, shortcut });
+        this.requireRoom(this.state.recordings);
+        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 = {
@@ -174,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();
@@ -185,26 +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)
-            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);
@@ -233,6 +272,13 @@ export class MacroKit {
     }
     saveSnippet(input) {
         this.requireValidShortcut(input.shortcut, input.id);
+        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(),
             name: input.name,
@@ -240,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() {
@@ -274,9 +330,14 @@ export class MacroKit {
     }
     currentBindings() {
         const bindings = [];
-        for (const script of this.state.scripts) {
-            if (script.shortcut)
-                bindings.push({ shortcut: script.shortcut, run: () => this.runScript(script.id) });
+        // Part of the scripts gate: with scripts disabled their shortcuts are
+        // not bound at all — runScript would refuse anyway, but an unbound key
+        // is better than a key that swallows the event just to show an error.
+        if (this.scriptsEnabled) {
+            for (const script of this.state.scripts) {
+                if (script.shortcut)
+                    bindings.push({ shortcut: script.shortcut, run: () => this.runScript(script.id) });
+            }
         }
         for (const recording of this.state.recordings) {
             if (recording.shortcut)
@@ -296,23 +357,83 @@ export class MacroKit {
      * Imports JSON produced by `exportState`. With `merge: true` an imported
      * item with an existing `id` replaces it; without merge the whole state is
      * replaced.
+     *
+     * The check is **atomic, on the final result**: a candidate state is built
+     * first, its size limits and every shortcut in it are validated (the same
+     * rules the save paths enforce — a file cannot smuggle in what typing
+     * cannot), and only a candidate that passed in full is committed. On any
+     * failure the current state is untouched.
      */
     importState(json, options = {}) {
         const imported = parsePersistedState(json);
         if (!imported)
             return { ok: false, message: macroMessages().invalidImport };
+        let candidate;
         if (options.merge) {
+            candidate = {
+                version: 1,
+                scripts: [...this.state.scripts.map((item) => ({ ...item }))],
+                recordings: [...this.state.recordings.map((item) => ({ ...item }))],
+                snippets: [...this.state.snippets.map((item) => ({ ...item }))],
+            };
             for (const script of imported.scripts)
-                this.upsert(this.state.scripts, script);
+                this.upsert(candidate.scripts, script);
             for (const recording of imported.recordings)
-                this.upsert(this.state.recordings, recording);
+                this.upsert(candidate.recordings, recording);
             for (const snippet of imported.snippets)
-                this.upsert(this.state.snippets, snippet);
+                this.upsert(candidate.snippets, snippet);
         }
         else {
-            this.state = imported;
+            candidate = imported;
+        }
+        // The merged result can exceed what each file alone respected.
+        if (!isPersistableState(candidate))
+            return { ok: false, message: macroMessages().importTooLarge };
+        const shortcutsOk = this.validateStateShortcuts(candidate);
+        if (!shortcutsOk.ok)
+            return shortcutsOk;
+        try {
+            this.adopt(candidate);
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : macroMessages().saveFailed };
+        }
+        return { ok: true };
+    }
+    /**
+     * Every shortcut in a candidate state, under the exact rules of
+     * `validateShortcut`: parseable, real modifier, not host-reserved, and
+     * unique within the candidate. `importState` is the only caller — the
+     * save paths enforce the same rules one item at a time.
+     */
+    validateStateShortcuts(candidate) {
+        const seen = new Map();
+        const items = [
+            ...candidate.scripts,
+            ...candidate.recordings,
+            ...candidate.snippets,
+        ];
+        for (const item of items) {
+            if (!item.shortcut)
+                continue;
+            const parsed = parseShortcut(item.shortcut);
+            if (!parsed) {
+                return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutInvalid) };
+            }
+            if (!hasBindingModifier(parsed)) {
+                return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutNeedsModifier) };
+            }
+            for (const signature of shortcutSignatures(parsed)) {
+                if (this.reservedSignatures.has(signature)) {
+                    return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutReserved) };
+                }
+                const owner = seen.get(signature);
+                if (owner !== undefined) {
+                    return { ok: false, message: macroMessages().importRejectedShortcut(item.name, macroMessages().shortcutTaken(owner)) };
+                }
+                seen.set(signature, item.name);
+            }
         }
-        this.persist();
         return { ok: true };
     }
     /* ---------- Internal ---------- */
@@ -325,6 +446,40 @@ export class MacroKit {
         }
         return null;
     }
+    /**
+     * The save-path half of the persistence invariant: field lengths that the
+     * loader would reject are refused at the door. Without this, one oversized
+     * save would make the whole store unloadable — and the next startup would
+     * silently fall back to an empty state, losing everything.
+     */
+    requireItemLimits(fields) {
+        const limits = IMPORT_LIMITS;
+        if (fields.name.length === 0)
+            throw new MacroError(macroMessages().nameRequired, 'invalid-item');
+        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');
+        }
+        if (fields.source !== undefined && fields.source.length > limits.maxSourceLength) {
+            throw new MacroError(macroMessages().fieldTooLong('source', limits.maxSourceLength), 'invalid-item');
+        }
+        if (fields.trigger !== undefined && fields.trigger.length > limits.maxTriggerLength) {
+            throw new MacroError(macroMessages().fieldTooLong('trigger', limits.maxTriggerLength), 'invalid-item');
+        }
+    }
+    /** The item-count half of the invariant. `existingId` exempts an in-place update. */
+    requireRoom(list, existingId) {
+        if (existingId && list.some((entry) => entry.id === existingId))
+            return;
+        if (list.length >= IMPORT_LIMITS.maxItems) {
+            throw new MacroError(macroMessages().tooManyItems, 'too-many-items');
+        }
+    }
     upsert(list, item) {
         const index = list.findIndex((entry) => entry.id === item.id);
         if (index >= 0)
@@ -332,7 +487,53 @@ export class MacroKit {
         else
             list.push(item);
     }
-    persist() {
-        this.storage.save(this.state);
+    /**
+     * 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.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. `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;
+    const split = steps.flatMap((step) => {
+        if (step.type !== 'insert-text' || step.text.length <= max)
+            return [step];
+        const chunks = [];
+        for (let offset = 0; offset < step.text.length; offset += max) {
+            chunks.push({ type: 'insert-text', text: step.text.slice(offset, offset + max) });
+        }
+        return chunks;
+    });
+    return { steps: split, truncated: split.length > IMPORT_LIMITS.maxStepsPerRecording };
 }

package/dist/messages.d.ts

@@ -33,7 +33,15 @@ export interface MacroMessages {
     snippetNotFound: string;
     cannotRunWhileRecording: string;
     anotherMacroRunning: string;
+    scriptsDisabled: string;
+    nameRequired: string;
     invalidImport: string;
+    importRejectedShortcut: (itemName: string, detail: string) => string;
+    importTooLarge: string;
+    tooManyItems: string;
+    fieldTooLong: (field: string, max: number) => string;
+    saveFailed: string;
+    recordingTooLarge: string;
     shortcutInvalid: string;
     shortcutNeedsModifier: string;
     shortcutReserved: string;