superdoc-macros 0.3.0 → 0.5.0

package/README.md

@@ -76,10 +76,14 @@ 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.
 
+**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
@@ -134,6 +138,18 @@ 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 **atomically on the final result**: every item and every recorded step is type-checked and size-bounded (see `IMPORT_LIMITS`), every shortcut in the merged state must pass the same binding rules the save paths enforce (modifier required, not host-reserved, no duplicates), and any failure rejects the whole file with the current state untouched — no partial imports.
+
+The same limits hold as a persistence invariant: the save paths refuse oversized fields and full lists, an oversized recorded paste is split into loadable steps, and state that the loader would reject is never written — so a single bad save can never wipe the store on the next startup.
+
+## 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';
@@ -8,6 +8,6 @@ export { createIframeRunner, SANDBOX_BOOTSTRAP, isProtocolMessage } from './scri
 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, 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 { AutoText, type AutoTextOptions, type AutoTextExpansion } from './snippets/autotext.js';
+export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, type ParsedShortcut, type ShortcutBinding, type ShortcutTarget, } from './shortcuts.js';
+export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, type MacroStorage, type PersistedMacroState, } from './storage.js';

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, isPersistableState, } from './storage.js';

package/dist/manager.d.ts

@@ -31,7 +31,34 @@ 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[];
+    /**
+     * 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;
+} | {
+    ok: false;
+    message: string;
+};
 export declare class MacroKit {
     private readonly host;
     private readonly storage;
@@ -41,8 +68,21 @@ export declare class MacroKit {
     private state;
     private readonly recorder;
     private readonly autoText;
+    private readonly reservedSignatures;
+    private readonly scriptsEnabled;
     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;
@@ -98,6 +138,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;
@@ -105,7 +151,23 @@ 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;
 }