superdoc-macros 0.3.0 → 0.4.0

package/README.md

@@ -76,7 +76,9 @@ if (!result.ok) console.warn(result.message);
 
 ### Security
 
-The default is a **real sandbox**: scripts run in an iframe with `sandbox="allow-scripts"` only — an opaque origin, no access to the application's DOM, localStorage, cookies, or credentialed network. The script's only way to touch the document is the API above, with a time cap (default 30 s — enforced even against infinite loops, by removing the iframe) and a call cap (10,000).
+The default is a **real sandbox**: scripts run in an iframe with `sandbox="allow-scripts"` only — an opaque origin, no access to the application's DOM, localStorage or cookies — plus a `default-src 'none'` CSP inside the iframe, so the script cannot fetch or open sockets to the public internet either. The script's only way to touch the document is the API above, with a time cap (default 30 s — enforced even against infinite loops, by removing the iframe) and a call cap (10,000). When a run ends (result, error or timeout), its bridge is revoked: any late call is rejected and can no longer touch the document.
+
+Honest limits: the browser offers no per-iframe memory cap, and a host call that already reached the engine cannot be aborted mid-flight (the engine exposes no cancellation) — what is guaranteed is that nothing new starts.
 
 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.
 
@@ -134,6 +136,16 @@ 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.
+
+## 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:
+
+```ts
+const kit = new MacroKit({ host, reservedShortcuts: ['Ctrl+S', 'Ctrl+P', /* … the editor's registry … */] });
+```
+
 ## Connecting a different host
 
 The whole toolkit works against a single `MacroHost` interface (commands, text insertion, selection, replace, typing events). `createSuperdocHost` is the implementation for SuperDoc v2 in `ui: false` mode; another editor plugs in with its own implementation — see `src/types.ts` and the double in `tests/fake-host.ts`.

package/dist/host/superdoc-host.d.ts

@@ -102,6 +102,14 @@ export interface SuperdocHostOptions {
     superdoc: SuperdocLike;
     /** The element the document renders in — typing events are captured on it. */
     container?: HTMLElement | null;
+    /**
+     * Whether the adapter may fall back to the engine's internal ProseMirror
+     * view for the operations that have no public surface: backward/forward
+     * deletion, full-document text, and insertion when the Document API is
+     * missing. Default: true. Hosts that want to stay strictly on public
+     * surfaces set false — those operations then fail closed.
+     */
+    viewFallback?: boolean;
 }
 export interface SuperdocMacroHost extends MacroHost {
     /** Removes the observation wrapper and the DOM listeners. Call before swapping documents. */

package/dist/host/superdoc-host.js

@@ -43,40 +43,101 @@ function emptySelection() {
 /* ---------- The implementation ---------- */
 export function createSuperdocHost(options) {
     const { superdoc, container } = options;
+    const viewFallback = options.viewFallback ?? true;
     // Read at call time, never cached: activeEditor is replaced on every document open.
     const commands = () => superdoc.ui?.commands ?? null;
     const doc = () => superdoc.activeEditor?.doc ?? null;
-    const view = () => superdoc.activeEditor?.view ?? null;
     const search = () => superdoc.ui?.search ?? null;
+    /**
+     * The single gate to the internal ProseMirror view. Every use of a
+     * non-public surface goes through here, so disabling the fallback (or a
+     * future engine that hides the view) degrades to closed failures in one
+     * place.
+     */
+    const view = () => viewFallback ? (superdoc.activeEditor?.view ?? null) : null;
     const commandListeners = new Set();
     const inputListeners = new Set();
-    /* Command observation: wrap executeAsync, once, restored on dispose. */
+    const emitInput = (mapped) => {
+        for (const listener of inputListeners) {
+            try {
+                listener(mapped);
+            }
+            catch (error) {
+                console.warn('[superdoc-macros] input listener threw', error);
+            }
+        }
+    };
+    /* Command observation: wrap executeAsync, once, restored on dispose.
+       Listeners are notified only after the engine reports success — a command
+       that was refused (not routed, or a failed receipt) must not enter a
+       recording, or replay would re-fail it or, worse, apply it in a context
+       where it now succeeds unintended. */
     const wrapped = commands();
     const originalExecuteAsync = wrapped?.executeAsync;
     if (wrapped && originalExecuteAsync) {
         wrapped.executeAsync = function (id, payload) {
-            for (const listener of commandListeners) {
-                try {
-                    listener(id, payload);
+            const result = originalExecuteAsync.call(wrapped, id, payload);
+            void Promise.resolve(result)
+                .then((value) => {
+                if (value === false)
+                    return;
+                if (typeof value === 'object' && value !== null && value.success === false)
+                    return;
+                for (const listener of commandListeners) {
+                    try {
+                        listener(id, payload);
+                    }
+                    catch (error) {
+                        console.warn('[superdoc-macros] command listener threw', error);
+                    }
                 }
-                catch (error) {
-                    console.warn('[superdoc-macros] command listener threw', error);
-                }
-            }
-            return originalExecuteAsync.call(wrapped, id, payload);
+            })
+                .catch(() => undefined); // a thrown command is a failure — nothing to record.
+            return result;
         };
     }
-    /* Typing: beforeinput on the container, capture phase. */
+    /* Typing: beforeinput on the container, capture phase.
+  
+       IME composition is folded to a single event: while composing, the
+       engine fires insertCompositionText repeatedly with the growing
+       candidate text, and mapping each one would record the word once per
+       keystroke. The events are suppressed during composition and the final
+       text is emitted once, from compositionend. */
+    let composing = false;
+    const onCompositionStart = () => {
+        composing = true;
+    };
+    const onCompositionEnd = (event) => {
+        composing = false;
+        const data = event.data;
+        if (typeof data === 'string' && data.length > 0)
+            emitInput({ kind: 'insert-text', text: data });
+    };
     const onBeforeInput = (event) => {
         const input = event;
         let mapped = null;
         switch (input.inputType) {
             case 'insertText':
             case 'insertCompositionText':
+                if (composing)
+                    break; // the final text arrives from compositionend.
                 if (typeof input.data === 'string' && input.data.length > 0) {
                     mapped = { kind: 'insert-text', text: input.data };
                 }
                 break;
+            // Paste, drop and spellcheck replacement carry their text either in
+            // `data` or in a dataTransfer — without this branch a recording
+            // silently missed everything the user pasted.
+            case 'insertFromPaste':
+            case 'insertFromDrop':
+            case 'insertReplacementText': {
+                const text = typeof input.data === 'string' && input.data.length > 0
+                    ? input.data
+                    : input.dataTransfer?.getData('text/plain') ?? '';
+                if (text.length > 0)
+                    mapped = { kind: 'insert-text', text };
+                break;
+            }
             case 'insertParagraph':
                 mapped = { kind: 'insert-paragraph' };
                 break;
@@ -89,29 +150,32 @@ export function createSuperdocHost(options) {
             default:
                 break;
         }
-        if (!mapped)
-            return;
-        for (const listener of inputListeners) {
-            try {
-                listener(mapped);
-            }
-            catch (error) {
-                console.warn('[superdoc-macros] input listener threw', error);
-            }
-        }
+        if (mapped)
+            emitInput(mapped);
     };
     container?.addEventListener('beforeinput', onBeforeInput, true);
-    async function readSelection(includeText) {
+    container?.addEventListener('compositionstart', onCompositionStart, true);
+    container?.addEventListener('compositionend', onCompositionEnd, true);
+    /**
+     * `failed: true` means the engine call itself threw — as opposed to a
+     * clean "no selection" answer. Callers that write relative to the caret
+     * must fail closed on it: falling back to "no target" would send the text
+     * to the end of the document, far from where the user is looking.
+     */
+    async function readSelectionDetailed(includeText) {
         const current = doc()?.selection?.current;
         if (typeof current !== 'function')
-            return emptySelection();
+            return { snapshot: emptySelection(), failed: false };
         let info;
         try {
             info = await current(includeText ? { includeText: true } : undefined);
         }
         catch {
-            return emptySelection();
+            return { snapshot: emptySelection(), failed: true };
         }
+        return { snapshot: parseSelectionInfo(info), failed: false };
+    }
+    function parseSelectionInfo(info) {
         if (!info || typeof info !== 'object')
             return emptySelection();
         const segments = Array.isArray(info.target?.segments) ? info.target.segments : [];
@@ -168,7 +232,11 @@ export function createSuperdocHost(options) {
             const insert = doc()?.insert;
             if (typeof insert === 'function') {
                 // Without a target the insertion falls to the end of the document — so the target comes from the live selection.
-                const snapshot = await readSelection(false);
+                const { snapshot, failed: selectionFailed } = await readSelectionDetailed(false);
+                // A failed read is not "no selection": inserting without a target
+                // would land the text at the end of the document. Fail closed.
+                if (selectionFailed)
+                    return failed(macroMessages().selectionUnavailable, 'selection-read-failed');
                 try {
                     const receipt = await insert({
                         value: text,
@@ -216,8 +284,27 @@ export function createSuperdocHost(options) {
                 return failed(error instanceof Error ? error.message : macroMessages().deleteFailed, 'threw');
             }
         },
-        getSelection(options) {
-            return readSelection(options?.includeText ?? false);
+        async deleteForward(count) {
+            const pm = view();
+            if (!pm)
+                return failed(macroMessages().deletionUnavailable, 'view-unavailable');
+            try {
+                const { from } = pm.state.selection;
+                const size = pm.state.doc.content.size;
+                const end = Math.min(size, from + Math.max(0, Math.trunc(count)));
+                if (end === from)
+                    return { ok: true };
+                const tr = pm.state.tr;
+                tr.delete(from, end);
+                pm.dispatch(tr);
+                return { ok: true };
+            }
+            catch (error) {
+                return failed(error instanceof Error ? error.message : macroMessages().deleteFailed, 'threw');
+            }
+        },
+        async getSelection(options) {
+            return (await readSelectionDetailed(options?.includeText ?? false)).snapshot;
         },
         async replaceAll(query, replacement) {
             const handle = search();
@@ -278,6 +365,8 @@ export function createSuperdocHost(options) {
             if (wrapped && originalExecuteAsync)
                 wrapped.executeAsync = originalExecuteAsync;
             container?.removeEventListener('beforeinput', onBeforeInput, true);
+            container?.removeEventListener('compositionstart', onCompositionStart, true);
+            container?.removeEventListener('compositionend', onCompositionEnd, true);
             commandListeners.clear();
             inputListeners.clear();
         },

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { MacroHost, MacroOutcome, MacroStep, RecordedMacro, SavedScript, SelectionSnapshot, Snippet, TextInputEvent, } from './types.js';
-export { MacroKit, type MacroKitOptions } from './manager.js';
+export { MacroKit, type MacroKitOptions, type ShortcutValidation } from './manager.js';
 export { ENGLISH_MESSAGES, HEBREW_MESSAGES, setMacroMessages, type MacroMessages, } from './messages.js';
 export { createSuperdocHost, type SuperdocHostOptions, type SuperdocLike, type SuperdocMacroHost } from './host/superdoc-host.js';
 export { createMacroApi, MacroError, type MacroApi, type MacroBridge, type ScriptSelection } from './scripting/macro-api.js';
@@ -9,5 +9,5 @@ export type { MacroRunner, MacroRunOptions, MacroRunResult } from './scripting/r
 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, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget } from './shortcuts.js';
-export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, type MacroStorage, type PersistedMacroState, } from './storage.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';

package/dist/index.js

@@ -7,5 +7,5 @@ export { createIframeRunner, SANDBOX_BOOTSTRAP, isProtocolMessage } from './scri
 export { MacroRecorder, replayMacro } from './recorder/recorder.js';
 export { renderSnippet, expandSnippet, usesSelection } from './snippets/snippets.js';
 export { AutoText } from './snippets/autotext.js';
-export { parseShortcut, eventMatches, bindShortcuts } from './shortcuts.js';
-export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, } from './storage.js';
+export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, } from './shortcuts.js';
+export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, } from './storage.js';

package/dist/manager.d.ts

@@ -31,7 +31,20 @@ export interface MacroKitOptions {
     autoText?: Omit<AutoTextOptions, 'onExpand' | 'onError'> & AutoTextOptions;
     /** Run log for `api.log`. */
     onLog?: MacroApiOptions['onLog'];
+    /**
+     * Shortcuts the host already owns (e.g. its ribbon registry). A saved
+     * binding that collides with any of these is rejected — otherwise the
+     * macro binding, attached in the capture phase, would silently shadow an
+     * editor shortcut. Unparseable entries are ignored.
+     */
+    reservedShortcuts?: readonly string[];
 }
+export type ShortcutValidation = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
 export declare class MacroKit {
     private readonly host;
     private readonly storage;
@@ -41,8 +54,20 @@ export declare class MacroKit {
     private state;
     private readonly recorder;
     private readonly autoText;
+    private readonly reservedSignatures;
     private running;
     constructor(options: MacroKitOptions);
+    /**
+     * Whether a shortcut is acceptable for a saved binding: parseable, carries
+     * a real modifier, not reserved by the host, and not already used by
+     * another saved item (`excludeId` skips the item being edited). Empty or
+     * undefined means "no shortcut" and is fine. The save paths enforce this;
+     * UIs call it directly to show the message before saving.
+     */
+    validateShortcut(shortcut: string | undefined, excludeId?: string): ShortcutValidation;
+    private findShortcutOwner;
+    /** Throws a MacroError when the shortcut is unacceptable. The save paths call this. */
+    private requireValidShortcut;
     listScripts(): readonly SavedScript[];
     saveScript(input: {
         id?: string;

package/dist/manager.js

@@ -13,7 +13,8 @@ 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 } from './shortcuts.js';
+import { bindShortcuts, hasBindingModifier, parseShortcut, shortcutSignatures, } from './shortcuts.js';
+import { MacroError } from './scripting/macro-api.js';
 import { createLocalStorage, emptyState, parsePersistedState } from './storage.js';
 import { macroMessages } from './messages.js';
 let idCounter = 0;
@@ -35,6 +36,7 @@ export class MacroKit {
     state;
     recorder;
     autoText;
+    reservedSignatures;
     running = false;
     constructor(options) {
         this.host = options.host;
@@ -47,12 +49,71 @@ export class MacroKit {
         this.state = this.storage.load() ?? emptyState();
         this.recorder = new MacroRecorder(this.host);
         this.autoText = new AutoText(this.host, () => this.state.snippets, options.autoText);
+        const reserved = new Set();
+        for (const shortcut of options.reservedShortcuts ?? []) {
+            const parsed = parseShortcut(shortcut);
+            if (parsed)
+                for (const signature of shortcutSignatures(parsed))
+                    reserved.add(signature);
+        }
+        this.reservedSignatures = reserved;
+    }
+    /* ---------- Shortcut validation ---------- */
+    /**
+     * Whether a shortcut is acceptable for a saved binding: parseable, carries
+     * a real modifier, not reserved by the host, and not already used by
+     * another saved item (`excludeId` skips the item being edited). Empty or
+     * undefined means "no shortcut" and is fine. The save paths enforce this;
+     * UIs call it directly to show the message before saving.
+     */
+    validateShortcut(shortcut, excludeId) {
+        const trimmed = shortcut?.trim();
+        if (!trimmed)
+            return { ok: true };
+        const parsed = parseShortcut(trimmed);
+        if (!parsed)
+            return { ok: false, message: macroMessages().shortcutInvalid };
+        if (!hasBindingModifier(parsed))
+            return { ok: false, message: macroMessages().shortcutNeedsModifier };
+        const signatures = shortcutSignatures(parsed);
+        if (signatures.some((signature) => this.reservedSignatures.has(signature))) {
+            return { ok: false, message: macroMessages().shortcutReserved };
+        }
+        const owner = this.findShortcutOwner(signatures, excludeId);
+        if (owner)
+            return { ok: false, message: macroMessages().shortcutTaken(owner) };
+        return { ok: true };
+    }
+    findShortcutOwner(signatures, excludeId) {
+        const items = [
+            ...this.state.scripts,
+            ...this.state.recordings,
+            ...this.state.snippets,
+        ];
+        for (const item of items) {
+            if (!item.shortcut || item.id === excludeId)
+                continue;
+            const parsed = parseShortcut(item.shortcut);
+            if (!parsed)
+                continue;
+            const existing = shortcutSignatures(parsed);
+            if (existing.some((signature) => signatures.includes(signature)))
+                return item.name;
+        }
+        return null;
+    }
+    /** Throws a MacroError when the shortcut is unacceptable. The save paths call this. */
+    requireValidShortcut(shortcut, excludeId) {
+        const validation = this.validateShortcut(shortcut, excludeId);
+        if (!validation.ok)
+            throw new MacroError(validation.message, 'invalid-shortcut');
     }
     /* ---------- Scripts ---------- */
     listScripts() {
         return this.state.scripts;
     }
     saveScript(input) {
+        this.requireValidShortcut(input.shortcut, input.id);
         const script = {
             id: input.id ?? newId(),
             name: input.name,
@@ -101,6 +162,7 @@ export class MacroKit {
     }
     /** Stops and saves. `null` when no step was recorded — there is nothing to save. */
     stopRecording(name, shortcut) {
+        this.requireValidShortcut(shortcut);
         const steps = this.recorder.stop();
         if (steps.length === 0)
             return null;
@@ -131,6 +193,8 @@ export class MacroKit {
         const recording = this.state.recordings.find((entry) => entry.id === input.id);
         if (!recording)
             return null;
+        if (input.shortcut !== undefined)
+            this.requireValidShortcut(input.shortcut, input.id);
         if (input.name !== undefined)
             recording.name = input.name;
         if (input.shortcut !== undefined) {
@@ -168,6 +232,7 @@ export class MacroKit {
         return this.state.snippets;
     }
     saveSnippet(input) {
+        this.requireValidShortcut(input.shortcut, input.id);
         const snippet = {
             id: input.id ?? newId(),
             name: input.name,

package/dist/messages.d.ts

@@ -27,14 +27,19 @@ export interface MacroMessages {
     syntaxError: (detail: string) => string;
     timedOut: (seconds: number) => string;
     callLimitExceeded: (limit: number) => string;
-    deleteForwardUnsupported: string;
+    macroStopped: string;
     scriptNotFound: string;
     recordingNotFound: string;
     snippetNotFound: string;
     cannotRunWhileRecording: string;
     anotherMacroRunning: string;
     invalidImport: string;
+    shortcutInvalid: string;
+    shortcutNeedsModifier: string;
+    shortcutReserved: string;
+    shortcutTaken: (ownerName: string) => string;
     noDocument: string;
+    selectionUnavailable: string;
     unknownCommand: (id: string) => string;
     actionFailed: string;
     deletionUnavailable: string;

package/dist/messages.js

@@ -27,14 +27,19 @@ export const ENGLISH_MESSAGES = {
     syntaxError: (detail) => `Macro syntax error: ${detail}`,
     timedOut: (seconds) => `The macro did not finish within ${seconds} seconds and was stopped`,
     callLimitExceeded: (limit) => `The macro exceeded the API call limit (${limit}) and was stopped`,
-    deleteForwardUnsupported: 'Forward deletion is not supported during replay',
+    macroStopped: 'The macro was stopped — the call was not executed',
     scriptNotFound: 'Macro not found',
     recordingNotFound: 'Recording not found',
     snippetNotFound: 'Snippet not found',
     cannotRunWhileRecording: 'Cannot run a macro while recording',
     anotherMacroRunning: 'Another macro is still running',
     invalidImport: 'The file is not a valid macro export',
+    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',
+    shortcutTaken: (ownerName) => `This shortcut is already used by "${ownerName}"`,
     noDocument: 'No document is open',
+    selectionUnavailable: 'The caret position could not be read — nothing was inserted',
     unknownCommand: (id) => `The engine does not recognize the command ${id}`,
     actionFailed: 'The operation failed',
     deletionUnavailable: 'Deletion is not available in this document',
@@ -53,14 +58,19 @@ export const HEBREW_MESSAGES = {
     syntaxError: (detail) => `שגיאת תחביר במאקרו: ${detail}`,
     timedOut: (seconds) => `המאקרו לא הסתיים תוך ${seconds} שניות ונעצר`,
     callLimitExceeded: (limit) => `המאקרו חצה את תקרת הקריאות (${limit}) ונעצר`,
-    deleteForwardUnsupported: 'מחיקה קדימה אינה נתמכת בניגון',
+    macroStopped: 'המאקרו נעצר — הקריאה לא בוצעה',
     scriptNotFound: 'המאקרו לא נמצא',
     recordingNotFound: 'ההקלטה לא נמצאה',
     snippetNotFound: 'הקטע לא נמצא',
     cannotRunWhileRecording: 'אי אפשר להריץ מאקרו בזמן הקלטה',
     anotherMacroRunning: 'מאקרו אחר עדיין רץ',
     invalidImport: 'הקובץ אינו ייצוא מאקרו תקין',
+    shortcutInvalid: 'קיצור לא תקין — הצורה הנדרשת היא למשל Ctrl+Alt+M',
+    shortcutNeedsModifier: 'קיצור חייב לכלול Ctrl,‏ Alt או Meta',
+    shortcutReserved: 'הקיצור הזה שמור לעורך',
+    shortcutTaken: (ownerName) => `הקיצור כבר בשימוש של "${ownerName}"`,
     noDocument: 'אין מסמך פתוח',
+    selectionUnavailable: 'קריאת מיקום הסמן נכשלה — לא הוכנס דבר',
     unknownCommand: (id) => `הפקודה ${id} אינה מוכרת למנוע`,
     actionFailed: 'הפעולה נכשלה',
     deletionUnavailable: 'מחיקה אינה זמינה במסמך הזה',

package/dist/recorder/recorder.d.ts

@@ -1,3 +1,17 @@
+/**
+ * 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. */

package/dist/recorder/recorder.js

@@ -1,18 +1,3 @@
-/**
- * A Word-style macro recorder: records **commands** and typing, not caret
- * positions.
- *
- * That choice is deliberate. Recording raw ProseMirror steps (with absolute
- * positions) breaks the moment the document differs from what it was at
- * recording time; recording commands ("bold", "bullet-list", typing a
- * greeting) behaves like Word's recorder — the actions apply wherever the
- * caret is at replay time. It is also what makes a recording saveable and
- * shareable: the steps are plain JSON.
- *
- * What is not recorded: caret movement and mouse selection. As in Word, a
- * recorded macro acts from wherever the caret stands when it runs.
- */
-import { macroMessages } from '../messages.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) {
@@ -124,8 +109,7 @@ async function runStep(host, step) {
         case 'delete-backward':
             return host.deleteBackward(step.count);
         case 'delete-forward':
-            // The engine exposes no separate forward deletion; report an explicit failure rather than skipping silently.
-            return { ok: false, message: macroMessages().deleteForwardUnsupported, reason: 'unsupported-step' };
+            return host.deleteForward(step.count);
     }
 }
 export async function replayMacro(host, steps, options = {}) {

package/dist/scripting/eval-runner.d.ts

@@ -2,4 +2,17 @@ import type { MacroBridge } from './macro-api.js';
 import { type MacroRunner } from './runner.js';
 /** Wraps a bridge with a call cap. Exposed so both runners share the same enforcement. */
 export declare function limitCalls(bridge: MacroBridge, maxCalls: number): MacroBridge;
+/**
+ * Wraps a bridge with a kill switch. After `revoke()` every new call is
+ * rejected — so a script that keeps running past its timeout (the eval
+ * runner cannot stop it) can no longer touch the document.
+ *
+ * What this cannot do: abort a host call that already reached the engine.
+ * The engine's public surfaces expose no cancellation, so an in-flight
+ * operation completes; what is guaranteed is that nothing *new* starts.
+ */
+export declare function revocable(bridge: MacroBridge): {
+    bridge: MacroBridge;
+    revoke: () => void;
+};
 export declare function createEvalRunner(): MacroRunner;

package/dist/scripting/eval-runner.js

@@ -29,6 +29,32 @@ export function limitCalls(bridge, maxCalls) {
         },
     };
 }
+/**
+ * Wraps a bridge with a kill switch. After `revoke()` every new call is
+ * rejected — so a script that keeps running past its timeout (the eval
+ * runner cannot stop it) can no longer touch the document.
+ *
+ * What this cannot do: abort a host call that already reached the engine.
+ * The engine's public surfaces expose no cancellation, so an in-flight
+ * operation completes; what is guaranteed is that nothing *new* starts.
+ */
+export function revocable(bridge) {
+    let revoked = false;
+    return {
+        revoke: () => {
+            revoked = true;
+        },
+        bridge: {
+            api: bridge.api,
+            callCount: bridge.callCount,
+            call(method, args) {
+                if (revoked)
+                    return Promise.reject(new Error(macroMessages().macroStopped));
+                return bridge.call(method, args);
+            },
+        },
+    };
+}
 /** An api proxy that routes everything through `bridge.call`, so the cap applies here too. */
 function apiThroughBridge(bridge) {
     return new Proxy({}, {
@@ -43,7 +69,9 @@ export function createEvalRunner() {
     return {
         async run(source, bridge, options = {}) {
             const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-            const limited = limitCalls(bridge, options.maxApiCalls ?? DEFAULT_MAX_API_CALLS);
+            // The revocable wrapper is what contains a timed-out script: eval cannot
+            // stop it from running, but it can no longer reach the document.
+            const { bridge: guarded, revoke } = revocable(limitCalls(bridge, options.maxApiCalls ?? DEFAULT_MAX_API_CALLS));
             let fn;
             try {
                 fn = new AsyncFunction('api', `"use strict";\n${source}`);
@@ -61,7 +89,7 @@ export function createEvalRunner() {
             });
             const run = (async () => {
                 try {
-                    const value = await fn(apiThroughBridge(limited));
+                    const value = await fn(apiThroughBridge(guarded));
                     return { ok: true, value };
                 }
                 catch (error) {
@@ -77,6 +105,7 @@ export function createEvalRunner() {
             }
             finally {
                 clearTimeout(timer);
+                revoke();
             }
         },
     };

package/dist/scripting/iframe-runner.js

@@ -16,7 +16,7 @@
  * `ScriptSelection`).
  */
 import { macroMessages } from '../messages.js';
-import { limitCalls } from './eval-runner.js';
+import { limitCalls, revocable } from './eval-runner.js';
 import { DEFAULT_MAX_API_CALLS, DEFAULT_TIMEOUT_MS, } from './runner.js';
 /** Protocol marker, so the messages cannot collide with others on the page. */
 export const PROTOCOL_MARK = '__otzariaMacro';
@@ -109,18 +109,29 @@ export function createIframeRunner(doc = document) {
     return {
         run(source, bridge, options = {}) {
             const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-            const limited = limitCalls(bridge, options.maxApiCalls ?? DEFAULT_MAX_API_CALLS);
+            // The revocable wrapper closes a small race: a call message that was
+            // already queued when the run finished must not dispatch to the host
+            // after the iframe is gone.
+            const { bridge: guarded, revoke } = revocable(limitCalls(bridge, options.maxApiCalls ?? DEFAULT_MAX_API_CALLS));
             return new Promise((resolve) => {
                 const iframe = doc.createElement('iframe');
                 iframe.setAttribute('sandbox', 'allow-scripts');
                 iframe.style.display = 'none';
-                iframe.srcdoc = `<!doctype html><meta charset="utf-8"><script>${SANDBOX_BOOTSTRAP}</script>`;
+                // The CSP closes the sandbox's remaining hole: an opaque-origin iframe
+                // cannot reach the app, but it can still fetch the public internet.
+                // `default-src 'none'` blocks fetch/XHR/WebSocket/resources inside it;
+                // only the inline bootstrap (and the AsyncFunction it compiles) runs.
+                iframe.srcdoc =
+                    `<!doctype html><meta charset="utf-8">` +
+                        `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline' 'unsafe-eval'">` +
+                        `<script>${SANDBOX_BOOTSTRAP}</script>`;
                 let settled = false;
                 let timer;
                 const finish = (result) => {
                     if (settled)
                         return;
                     settled = true;
+                    revoke();
                     clearTimeout(timer);
                     removeEventListener('message', onMessage);
                     iframe.remove();
@@ -139,7 +150,7 @@ export function createIframeRunner(doc = document) {
                     }
                     if (data.kind === 'call') {
                         const { id, method, args } = data;
-                        limited
+                        guarded
                             .call(method, args)
                             .then((value) => {
                             iframe.contentWindow?.postMessage({ [PROTOCOL_MARK]: true, kind: 'result', id, ok: true, value: toCloneSafe(value) }, '*');

package/dist/shortcuts.d.ts

@@ -25,6 +25,18 @@ export interface KeyEventLike {
 }
 export declare function parseShortcut(shortcut: string): ParsedShortcut | null;
 export declare function eventMatches(parsed: ParsedShortcut, event: KeyEventLike): boolean;
+/**
+ * Comparable signatures for collision checks. `Mod` matches either Ctrl or
+ * Meta at runtime, so it expands to both — a `Mod+K` binding collides with
+ * `Ctrl+K` and with `Meta+K`.
+ */
+export declare function shortcutSignatures(parsed: ParsedShortcut): string[];
+/**
+ * Whether the shortcut is acceptable as a *saved binding*: it must carry a
+ * real modifier (Ctrl/Alt/Meta/Mod). A bare letter would fire on ordinary
+ * typing, and Shift alone is just an uppercase letter.
+ */
+export declare function hasBindingModifier(parsed: ParsedShortcut): boolean;
 export interface ShortcutBinding {
     shortcut: string;
     run(): void | Promise<unknown>;

package/dist/shortcuts.js

@@ -58,6 +58,25 @@ export function eventMatches(parsed, event) {
         event.shiftKey === parsed.shift &&
         event.metaKey === parsed.meta);
 }
+/**
+ * Comparable signatures for collision checks. `Mod` matches either Ctrl or
+ * Meta at runtime, so it expands to both — a `Mod+K` binding collides with
+ * `Ctrl+K` and with `Meta+K`.
+ */
+export function shortcutSignatures(parsed) {
+    const suffix = `${parsed.alt ? 'alt+' : ''}${parsed.shift ? 'shift+' : ''}${parsed.key}`;
+    if (parsed.mod)
+        return [`ctrl+${suffix}`, `meta+${suffix}`];
+    return [`${parsed.ctrl ? 'ctrl+' : ''}${parsed.meta ? 'meta+' : ''}${suffix}`];
+}
+/**
+ * Whether the shortcut is acceptable as a *saved binding*: it must carry a
+ * real modifier (Ctrl/Alt/Meta/Mod). A bare letter would fire on ordinary
+ * typing, and Shift alone is just an uppercase letter.
+ */
+export function hasBindingModifier(parsed) {
+    return parsed.ctrl || parsed.alt || parsed.meta || parsed.mod;
+}
 /**
  * Binds shortcuts to a target. `getBindings` is called on every keystroke —
  * so the macro list can change without rebinding. Returns a dispose

package/dist/storage.d.ts

@@ -16,7 +16,30 @@ export interface MacroStorage {
     save(state: PersistedMacroState): void;
 }
 export declare function emptyState(): PersistedMacroState;
-/** Parses saved state. `null` on any unexpected shape — never throws. */
+/**
+ * Caps on imported data. Imports come from files users share with each
+ * other, so every field is validated and bounded — a malformed or oversized
+ * export must fail closed, not wedge the store or the UI.
+ */
+export declare const IMPORT_LIMITS: {
+    /** Whole-file size, in UTF-16 code units of the JSON string. */
+    readonly maxJsonLength: 5000000;
+    /** Per list: scripts, recordings, snippets. */
+    readonly maxItems: 500;
+    readonly maxStepsPerRecording: 5000;
+    readonly maxNameLength: 200;
+    readonly maxShortcutLength: 60;
+    readonly maxTriggerLength: 60;
+    /** Snippet text and single recorded insert-text step. */
+    readonly maxTextLength: 100000;
+    readonly maxSourceLength: 200000;
+};
+/**
+ * Parses saved/imported state. `null` on any unexpected shape, oversized
+ * field or oversized file — never throws, never partially accepts: one
+ * invalid item rejects the whole document, so the caller can tell the user
+ * the file is bad instead of silently importing a subset.
+ */
 export declare function parsePersistedState(json: string): PersistedMacroState | null;
 export declare const DEFAULT_STORAGE_KEY = "superdoc-macros:v1";
 /** localStorage with guards: blocked or full storage must not take the toolkit down. */

package/dist/storage.js

@@ -1,17 +1,105 @@
 export function emptyState() {
     return { version: 1, scripts: [], recordings: [], snippets: [] };
 }
+/**
+ * Caps on imported data. Imports come from files users share with each
+ * other, so every field is validated and bounded — a malformed or oversized
+ * export must fail closed, not wedge the store or the UI.
+ */
+export const IMPORT_LIMITS = {
+    /** Whole-file size, in UTF-16 code units of the JSON string. */
+    maxJsonLength: 5_000_000,
+    /** Per list: scripts, recordings, snippets. */
+    maxItems: 500,
+    maxStepsPerRecording: 5_000,
+    maxNameLength: 200,
+    maxShortcutLength: 60,
+    maxTriggerLength: 60,
+    /** Snippet text and single recorded insert-text step. */
+    maxTextLength: 100_000,
+    maxSourceLength: 200_000,
+};
+function boundedString(value, maxLength, allowEmpty = false) {
+    return typeof value === 'string' && value.length <= maxLength && (allowEmpty || value.length > 0);
+}
+function optionalBoundedString(value, maxLength) {
+    return value === undefined || boundedString(value, maxLength);
+}
+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);
+        case 'insert-text':
+            return boundedString(step.text, IMPORT_LIMITS.maxTextLength, true);
+        case 'insert-paragraph':
+            return true;
+        case 'delete-backward':
+        case 'delete-forward':
+            return typeof step.count === 'number' && Number.isInteger(step.count) && step.count > 0 && step.count <= IMPORT_LIMITS.maxTextLength;
+        default:
+            return false;
+    }
+}
+function isValidScript(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const script = value;
+    return (boundedString(script.id, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(script.name, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(script.source, IMPORT_LIMITS.maxSourceLength, true) &&
+        optionalBoundedString(script.shortcut, IMPORT_LIMITS.maxShortcutLength));
+}
+function isValidRecording(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const recording = value;
+    return (recording.version === 1 &&
+        boundedString(recording.id, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(recording.name, IMPORT_LIMITS.maxNameLength) &&
+        optionalBoundedString(recording.createdAt, IMPORT_LIMITS.maxNameLength) &&
+        optionalBoundedString(recording.shortcut, IMPORT_LIMITS.maxShortcutLength) &&
+        Array.isArray(recording.steps) &&
+        recording.steps.length <= IMPORT_LIMITS.maxStepsPerRecording &&
+        recording.steps.every(isValidStep));
+}
+function isValidSnippet(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const snippet = value;
+    return (boundedString(snippet.id, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(snippet.name, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(snippet.text, IMPORT_LIMITS.maxTextLength, true) &&
+        optionalBoundedString(snippet.trigger, IMPORT_LIMITS.maxTriggerLength) &&
+        optionalBoundedString(snippet.shortcut, IMPORT_LIMITS.maxShortcutLength));
+}
 function isValidState(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const state = value;
     return (state.version === 1 &&
         Array.isArray(state.scripts) &&
+        state.scripts.length <= IMPORT_LIMITS.maxItems &&
+        state.scripts.every(isValidScript) &&
         Array.isArray(state.recordings) &&
-        Array.isArray(state.snippets));
+        state.recordings.length <= IMPORT_LIMITS.maxItems &&
+        state.recordings.every(isValidRecording) &&
+        Array.isArray(state.snippets) &&
+        state.snippets.length <= IMPORT_LIMITS.maxItems &&
+        state.snippets.every(isValidSnippet));
 }
-/** Parses saved state. `null` on any unexpected shape — never throws. */
+/**
+ * Parses saved/imported state. `null` on any unexpected shape, oversized
+ * field or oversized file — never throws, never partially accepts: one
+ * invalid item rejects the whole document, so the caller can tell the user
+ * the file is bad instead of silently importing a subset.
+ */
 export function parsePersistedState(json) {
+    if (json.length > IMPORT_LIMITS.maxJsonLength)
+        return null;
     try {
         const parsed = JSON.parse(json);
         return isValidState(parsed) ? parsed : null;

package/dist/types.d.ts

@@ -56,6 +56,8 @@ export interface MacroHost {
     insertText(text: string): Promise<MacroOutcome>;
     /** Deletes characters backwards from the caret. */
     deleteBackward(count: number): Promise<MacroOutcome>;
+    /** Deletes characters forwards from the caret. */
+    deleteForward(count: number): Promise<MacroOutcome>;
     /** Snapshot of the current selection. Never throws. */
     getSelection(options?: {
         includeText?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superdoc-macros",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Macro toolkit for SuperDoc-based editors: sandboxed scripted macros, a Word-style macro recorder, and snippets with auto-text expansion.",
   "license": "MIT",
   "type": "module",