superdoc-macros 0.7.1 → 0.9.0

package/dist/import/zip.d.ts

@@ -0,0 +1,35 @@
+export declare const ZIP_LIMITS: {
+    readonly maxEntries: 5000;
+    /** Uncompressed size of any single part this reader will inflate. */
+    readonly maxEntryBytes: number;
+    readonly maxNameLength: 1024;
+};
+export interface ZipEntry {
+    readonly name: string;
+    readonly compressedSize: number;
+    readonly uncompressedSize: number;
+}
+export interface ZipReadOptions {
+    /**
+     * Hard ceiling on the bytes this read may produce, defaulting to
+     * `ZIP_LIMITS.maxEntryBytes`. Enforced *during* decompression, so a part
+     * that inflates past it is abandoned rather than buffered and then
+     * rejected. Callers who know a part should be small (a `.rels` file) should
+     * say so — that is the difference between refusing a bomb and hosting it.
+     */
+    maxBytes?: number;
+}
+export interface ZipArchive {
+    readonly entries: readonly ZipEntry[];
+    has(name: string): boolean;
+    /**
+     * The inflated bytes of one entry.
+     *
+     * @throws {VbaParseError} when the entry is absent, encrypted, compressed
+     * with an unsupported method, larger than the cap, or its data runs past
+     * the end of the file.
+     */
+    read(name: string, options?: ZipReadOptions): Promise<Uint8Array>;
+}
+/** Parses the central directory. Reading an entry's data stays lazy. */
+export declare function openZip(bytes: Uint8Array): ZipArchive;

package/dist/import/zip.js

@@ -0,0 +1,253 @@
+/**
+ * A read-only ZIP reader, enough to pull named parts out of an OOXML package.
+ *
+ * A `.docm` is a ZIP whose entries are the document's parts. To reach the
+ * macro project we need two or three specific parts by name, never the whole
+ * archive — so this reader parses the central directory up front (cheap) and
+ * inflates only what a caller asks for.
+ *
+ * Inflation uses the platform's own `DecompressionStream` — Baseline across
+ * browsers since 2023, and present in Node 18+. That keeps the toolkit
+ * dependency-free and puts the decompression itself in audited native code
+ * rather than in a hand-rolled inflater. Where it is genuinely absent, the
+ * reader says so rather than failing obscurely. Nothing else is assumed of the
+ * platform: no `Blob`, no `fetch`, no `Response` — only streams, so this also
+ * runs under jsdom, where a host's tests live.
+ *
+ * Safety posture, because these bytes come from a file someone was sent:
+ *
+ * - Entry count and name length are capped, and the per-part size cap is
+ *   enforced against the bytes decompression actually produces — not against
+ *   the size the archive claims, which a decompression bomb simply lies about.
+ * - Encrypted and ZIP64 entries are refused explicitly rather than guessed at.
+ * - Nothing here writes, and no entry name is ever used as a filesystem path,
+ *   so the classic zip-slip traversal has no surface to attack.
+ */
+import { VbaParseError } from './errors.js';
+export const ZIP_LIMITS = {
+    maxEntries: 5_000,
+    /** Uncompressed size of any single part this reader will inflate. */
+    maxEntryBytes: 64 * 1024 * 1024,
+    maxNameLength: 1_024,
+};
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const LOCAL_SIGNATURE = 0x04034b50;
+const ZIP64_LOCATOR_SIGNATURE = 0x07064b50;
+const EOCD_MIN_BYTES = 22;
+/** The trailing comment a ZIP may carry is at most 64 KiB. */
+const MAX_COMMENT_BYTES = 0xffff;
+const ZIP64_MARKER_32 = 0xffffffff;
+const ZIP64_MARKER_16 = 0xffff;
+const METHOD_STORED = 0;
+const METHOD_DEFLATE = 8;
+/** Parses the central directory. Reading an entry's data stays lazy. */
+export function openZip(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const u16 = (offset) => {
+        if (offset < 0 || offset + 2 > bytes.length) {
+            throw new VbaParseError('malformed', 'package: read past the end of the file');
+        }
+        return view.getUint16(offset, true);
+    };
+    const u32 = (offset) => {
+        if (offset < 0 || offset + 4 > bytes.length) {
+            throw new VbaParseError('malformed', 'package: read past the end of the file');
+        }
+        return view.getUint32(offset, true);
+    };
+    if (bytes.length < EOCD_MIN_BYTES) {
+        throw new VbaParseError('malformed', 'package: file is too short to be a ZIP archive');
+    }
+    // The end-of-central-directory record sits at the very end, behind an
+    // optional comment — so it has to be found by scanning backwards.
+    const scanFloor = Math.max(0, bytes.length - EOCD_MIN_BYTES - MAX_COMMENT_BYTES);
+    let eocd = -1;
+    for (let at = bytes.length - EOCD_MIN_BYTES; at >= scanFloor; at -= 1) {
+        if (view.getUint32(at, true) === EOCD_SIGNATURE) {
+            eocd = at;
+            break;
+        }
+    }
+    if (eocd < 0) {
+        throw new VbaParseError('malformed', 'package: not a ZIP archive (no end-of-directory record)');
+    }
+    const entryCount = u16(eocd + 10);
+    const directorySize = u32(eocd + 12);
+    const directoryOffset = u32(eocd + 16);
+    if (entryCount === ZIP64_MARKER_16 ||
+        directoryOffset === ZIP64_MARKER_32 ||
+        directorySize === ZIP64_MARKER_32 ||
+        (eocd >= 20 && view.getUint32(eocd - 20, true) === ZIP64_LOCATOR_SIGNATURE)) {
+        throw new VbaParseError('unsupported', 'package: ZIP64 archives are not supported');
+    }
+    if (entryCount > ZIP_LIMITS.maxEntries) {
+        throw new VbaParseError('too-large', 'package: too many entries');
+    }
+    if (directoryOffset + directorySize > bytes.length) {
+        throw new VbaParseError('malformed', 'package: central directory lies outside the file');
+    }
+    const decoder = new TextDecoder('utf-8');
+    const byName = new Map();
+    const entries = [];
+    const directoryEnd = directoryOffset + directorySize;
+    let at = directoryOffset;
+    for (let i = 0; i < entryCount; i += 1) {
+        // Confined to the region the archive declared for its directory, so a
+        // crafted file cannot have us read "entries" out of arbitrary bytes
+        // elsewhere in the package.
+        if (at + 46 > directoryEnd) {
+            throw new VbaParseError('malformed', 'package: central directory is shorter than it claims');
+        }
+        if (u32(at) !== CENTRAL_SIGNATURE) {
+            throw new VbaParseError('malformed', 'package: damaged central directory');
+        }
+        const flags = u16(at + 8);
+        const method = u16(at + 10);
+        const compressedSize = u32(at + 20);
+        const uncompressedSize = u32(at + 24);
+        const nameLength = u16(at + 28);
+        const extraLength = u16(at + 30);
+        const commentLength = u16(at + 32);
+        const localOffset = u32(at + 42);
+        if (nameLength > ZIP_LIMITS.maxNameLength) {
+            throw new VbaParseError('too-large', 'package: entry name is too long');
+        }
+        if (compressedSize === ZIP64_MARKER_32 || uncompressedSize === ZIP64_MARKER_32) {
+            throw new VbaParseError('unsupported', 'package: ZIP64 entry sizes are not supported');
+        }
+        const nameStart = at + 46;
+        if (nameStart + nameLength > directoryEnd) {
+            throw new VbaParseError('malformed', 'package: entry name lies outside the central directory');
+        }
+        // OOXML part names are ASCII, which UTF-8 and CP437 agree on — so the
+        // flag-11 distinction cannot change the names we look up.
+        const name = decoder.decode(bytes.subarray(nameStart, nameStart + nameLength));
+        const entry = {
+            name,
+            method,
+            compressedSize,
+            uncompressedSize,
+            localOffset,
+            encrypted: (flags & 0x0001) !== 0,
+        };
+        entries.push({ name, compressedSize, uncompressedSize });
+        // First entry wins, so a duplicated name cannot shadow the part that was
+        // already announced in `entries`.
+        if (!byName.has(name))
+            byName.set(name, entry);
+        at = nameStart + nameLength + extraLength + commentLength;
+    }
+    return {
+        entries,
+        has: (name) => byName.has(name),
+        async read(name, options) {
+            const entry = byName.get(name);
+            if (!entry) {
+                throw new VbaParseError('malformed', `package: no such part (${name})`);
+            }
+            if (entry.encrypted) {
+                throw new VbaParseError('unsupported', `package: ${name} is encrypted`);
+            }
+            const requested = options?.maxBytes;
+            const cap = Math.min(typeof requested === 'number' && Number.isFinite(requested) && requested > 0
+                ? Math.floor(requested)
+                : ZIP_LIMITS.maxEntryBytes, ZIP_LIMITS.maxEntryBytes);
+            // The declared size is only a claim, so it is a cheap early rejection
+            // rather than the real defence — the real one is enforced against the
+            // bytes actually produced, below.
+            if (entry.uncompressedSize > cap) {
+                throw new VbaParseError('too-large', `package: ${name} exceeds the part size cap`);
+            }
+            if (u32(entry.localOffset) !== LOCAL_SIGNATURE) {
+                throw new VbaParseError('malformed', `package: ${name} has a damaged local header`);
+            }
+            const localNameLength = u16(entry.localOffset + 26);
+            const localExtraLength = u16(entry.localOffset + 28);
+            const dataStart = entry.localOffset + 30 + localNameLength + localExtraLength;
+            const dataEnd = dataStart + entry.compressedSize;
+            if (dataEnd > bytes.length) {
+                throw new VbaParseError('malformed', `package: ${name} runs past the end of the file`);
+            }
+            const data = bytes.subarray(dataStart, dataEnd);
+            if (entry.method === METHOD_STORED) {
+                // A stored entry's real length is its compressed length; the declared
+                // uncompressed size may disagree, so the cap is applied to what we
+                // would actually return.
+                if (data.length > cap) {
+                    throw new VbaParseError('too-large', `package: ${name} exceeds the part size cap`);
+                }
+                return data.slice();
+            }
+            if (entry.method !== METHOD_DEFLATE) {
+                throw new VbaParseError('unsupported', `package: ${name} uses compression method ${entry.method}`);
+            }
+            return inflateRaw(data, name, cap);
+        },
+    };
+}
+/**
+ * Inflates one entry, enforcing `cap` as the bytes arrive.
+ *
+ * Reading the stream chunk by chunk rather than with `Response.arrayBuffer()`
+ * is the whole point. Buffering first and checking the length afterwards
+ * means a part that declares a kilobyte and expands to a gigabyte has already
+ * been fully materialized by the time the limit is consulted — the classic
+ * decompression bomb. Here the read is abandoned the moment the total would
+ * exceed the cap.
+ */
+async function inflateRaw(data, name, cap) {
+    if (typeof DecompressionStream !== 'function' || typeof ReadableStream !== 'function') {
+        throw new VbaParseError('unsupported', 'package: this environment cannot decompress ZIP entries');
+    }
+    // The bytes are wrapped in a stream directly rather than via
+    // `new Blob([data]).stream()`. Both work in a browser, but `Blob.stream` is
+    // one of the pieces jsdom does not implement — and a host's own test suite
+    // running in jsdom is a place this code has to work, not fall over.
+    // `BufferSource` and not `Uint8Array`: that is what `DecompressionStream`
+    // declares its writable side accepts, and `pipeThrough` matches on it.
+    const source = new ReadableStream({
+        start(controller) {
+            // The cast covers a modelling gap, not a real one: since TypeScript 5.7
+            // a bare `Uint8Array` may be backed by a `SharedArrayBuffer`, which
+            // `BufferSource` excludes. These bytes are a view over the caller's
+            // package, and the stream accepts any array-buffer view at runtime.
+            // Copying to prove it to the compiler would duplicate the whole part.
+            controller.enqueue(data);
+            controller.close();
+        },
+    });
+    const stream = source.pipeThrough(new DecompressionStream('deflate-raw'));
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > cap) {
+                throw new VbaParseError('too-large', `package: ${name} inflates past the part size cap`);
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        // Release the decompressor before rethrowing, so an abandoned bomb does
+        // not leave a stream pulling in the background.
+        await reader.cancel().catch(() => undefined);
+        if (error instanceof VbaParseError)
+            throw error;
+        throw new VbaParseError('malformed', `package: ${name} could not be decompressed`);
+    }
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { MacroHost, MacroOutcome, MacroStep, RecordedMacro, SavedScript, SelectionSnapshot, Snippet, TextInputEvent, } from './types.js';
+export type { BuiltinTool, BuiltinToolInfo, MacroHost, MacroOutcome, MacroStep, RecordedMacro, SavedScript, SelectionSnapshot, Snippet, TextInputEvent, } from './types.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';
@@ -10,4 +10,14 @@ export { MacroRecorder, replayMacro, type RecorderOptions, type RecordingWarning
 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';
+/**
+ * Reading the VBA macros already inside a `.docm`, for review only. Separate
+ * from `MacroKit` on purpose: extraction touches no saved macro, binds no
+ * shortcut, and executes nothing — see `src/import/vba.ts`.
+ */
+export { extractVbaFromDocx, extractVbaProject, findVbaPart, scanForAutoRunProcedures, VBA_LIMITS, type VbaExtraction, type VbaFailureReason, type VbaModule, type VbaModuleKind, type VbaProcedureRef, type VbaProject, type VbaWarning, } from './import/vba.js';
+export { VbaParseError, isVbaParseError, type VbaParseErrorCode } from './import/errors.js';
+export { readCfb, CFB_LIMITS, type CfbContainer, type CfbEntry, type CfbEntryType } from './import/cfb.js';
+export { openZip, ZIP_LIMITS, type ZipArchive, type ZipEntry } from './import/zip.js';
+export { decompressOvba, OVBA_LIMITS, type DecompressOvbaOptions } from './import/ms-ovba.js';
 export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, serializePersistable, type MacroStorage, type PersistedMacroState, } from './storage.js';

package/dist/index.js

@@ -8,4 +8,14 @@ export { MacroRecorder, replayMacro, } from './recorder/recorder.js';
 export { renderSnippet, renderSnippetForHost, expandSnippet, usesSelection, } from './snippets/snippets.js';
 export { AutoText } from './snippets/autotext.js';
 export { parseShortcut, eventMatches, bindShortcuts, shortcutSignatures, hasBindingModifier, isBindableKey, codesForKey, } from './shortcuts.js';
+/**
+ * Reading the VBA macros already inside a `.docm`, for review only. Separate
+ * from `MacroKit` on purpose: extraction touches no saved macro, binds no
+ * shortcut, and executes nothing — see `src/import/vba.ts`.
+ */
+export { extractVbaFromDocx, extractVbaProject, findVbaPart, scanForAutoRunProcedures, VBA_LIMITS, } from './import/vba.js';
+export { VbaParseError, isVbaParseError } from './import/errors.js';
+export { readCfb, CFB_LIMITS } from './import/cfb.js';
+export { openZip, ZIP_LIMITS } from './import/zip.js';
+export { decompressOvba, OVBA_LIMITS } from './import/ms-ovba.js';
 export { createLocalStorage, createMemoryStorage, emptyState, parsePersistedState, DEFAULT_STORAGE_KEY, IMPORT_LIMITS, isPersistableState, serializePersistable, } from './storage.js';

package/dist/manager.d.ts

@@ -14,7 +14,7 @@ import { type AutoTextOptions } from './snippets/autotext.js';
 import { type ExpandOptions } from './snippets/snippets.js';
 import { type ShortcutTarget } from './shortcuts.js';
 import { type MacroStorage } from './storage.js';
-import type { MacroHost, RecordedMacro, SavedScript, Snippet } from './types.js';
+import type { BuiltinTool, BuiltinToolInfo, MacroHost, MacroOutcome, RecordedMacro, SavedScript, Snippet } from './types.js';
 export interface MacroKitOptions {
     host: MacroHost;
     /** Default: localStorage. */
@@ -66,6 +66,8 @@ export declare class MacroKit {
     private readonly runOptions;
     private readonly onLog?;
     private state;
+    /** Built-in tools, by id. Runtime registrations — never persisted (see BuiltinTool). */
+    private readonly tools;
     private readonly recorder;
     private readonly autoText;
     private readonly reservedSignatures;
@@ -160,6 +162,25 @@ export declare class MacroKit {
     /** Enables auto-text (trigger + space). Returns a disable function. */
     enableAutoText(): () => void;
     disableAutoText(): void;
+    /**
+     * Registers a built-in tool (see BuiltinTool in types.ts). Throws on a
+     * duplicate id or an invalid name — a silent replace would let two host
+     * modules fight over one id without anyone noticing.
+     */
+    registerTool(tool: BuiltinTool): void;
+    /** The registered tools, each with its persisted shortcut (if any). */
+    listTools(): readonly BuiltinToolInfo[];
+    /**
+     * Runs a registered tool under the same guard as scripts and replays: not
+     * while recording, and never two runs at once. A thrown error is reported
+     * as a failed outcome, never rethrown.
+     */
+    runTool(id: string): Promise<MacroOutcome>;
+    /**
+     * Sets or clears (undefined/empty) the persisted shortcut of a registered
+     * tool, under the exact validation of every other saved binding.
+     */
+    setToolShortcut(id: string, shortcut: string | undefined): void;
     /**
      * Binds the shortcuts of everything saved (scripts, recordings, snippets)
      * to a target — usually the editor container or `window`. The list is

package/dist/manager.js

@@ -35,6 +35,8 @@ export class MacroKit {
     runOptions;
     onLog;
     state;
+    /** Built-in tools, by id. Runtime registrations — never persisted (see BuiltinTool). */
+    tools = new Map();
     recorder;
     autoText;
     reservedSignatures;
@@ -142,6 +144,22 @@ export class MacroKit {
             for (const signature of signatures)
                 seen.add(signature);
         }
+        const toolShortcuts = this.state.toolShortcuts;
+        if (!toolShortcuts)
+            return;
+        for (const [toolId, shortcut] of Object.entries(toolShortcuts)) {
+            if (this.bindingIssue(shortcut)) {
+                delete toolShortcuts[toolId];
+                continue;
+            }
+            const signatures = shortcutSignatures(parseShortcut(shortcut));
+            if (signatures.some((signature) => seen.has(signature))) {
+                delete toolShortcuts[toolId];
+                continue;
+            }
+            for (const signature of signatures)
+                seen.add(signature);
+        }
     }
     findShortcutOwner(signatures, excludeId) {
         const items = [
@@ -159,6 +177,19 @@ export class MacroKit {
             if (existing.some((signature) => signatures.includes(signature)))
                 return item.name;
         }
+        for (const [toolId, shortcut] of Object.entries(this.state.toolShortcuts ?? {})) {
+            if (toolId === excludeId)
+                continue;
+            const parsed = parseShortcut(shortcut);
+            if (!parsed)
+                continue;
+            const existing = shortcutSignatures(parsed);
+            if (existing.some((signature) => signatures.includes(signature))) {
+                // A stored shortcut can belong to a tool that is not registered in
+                // this session; its id is then the only name there is.
+                return this.tools.get(toolId)?.name ?? toolId;
+            }
+        }
         return null;
     }
     /** Throws a MacroError when the shortcut is unacceptable. The save paths call this. */
@@ -399,6 +430,80 @@ export class MacroKit {
     disableAutoText() {
         this.autoText.detach();
     }
+    /* ---------- Built-in tools ---------- */
+    /**
+     * Registers a built-in tool (see BuiltinTool in types.ts). Throws on a
+     * duplicate id or an invalid name — a silent replace would let two host
+     * modules fight over one id without anyone noticing.
+     */
+    registerTool(tool) {
+        if (!tool.id || tool.id.length > IMPORT_LIMITS.maxNameLength) {
+            throw new MacroError(macroMessages().fieldTooLong('id', IMPORT_LIMITS.maxNameLength), 'invalid-item');
+        }
+        this.requireItemLimits({ name: tool.name });
+        if (this.tools.has(tool.id)) {
+            const messages = macroMessages();
+            throw new MacroError(messages.toolAlreadyRegistered?.(tool.id) ?? messages.saveFailed, 'invalid-item');
+        }
+        this.tools.set(tool.id, tool);
+    }
+    /** The registered tools, each with its persisted shortcut (if any). */
+    listTools() {
+        return [...this.tools.values()].map((tool) => ({
+            id: tool.id,
+            name: tool.name,
+            ...(tool.description ? { description: tool.description } : {}),
+            ...(this.state.toolShortcuts?.[tool.id] ? { shortcut: this.state.toolShortcuts[tool.id] } : {}),
+        }));
+    }
+    /**
+     * Runs a registered tool under the same guard as scripts and replays: not
+     * while recording, and never two runs at once. A thrown error is reported
+     * as a failed outcome, never rethrown.
+     */
+    async runTool(id) {
+        const tool = this.tools.get(id);
+        if (!tool) {
+            const messages = macroMessages();
+            return { ok: false, message: messages.toolNotFound ?? messages.actionFailed, reason: 'tool-not-found' };
+        }
+        const guard = this.guardRun();
+        if (guard)
+            return { ok: false, message: guard.message };
+        this.running = true;
+        try {
+            return await tool.run();
+        }
+        catch (error) {
+            return { ok: false, message: error instanceof Error ? error.message : macroMessages().actionFailed, reason: 'threw' };
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    /**
+     * Sets or clears (undefined/empty) the persisted shortcut of a registered
+     * tool, under the exact validation of every other saved binding.
+     */
+    setToolShortcut(id, shortcut) {
+        if (!this.tools.has(id)) {
+            const messages = macroMessages();
+            throw new MacroError(messages.toolNotFound ?? messages.actionFailed, 'tool-not-found');
+        }
+        const trimmed = shortcut?.trim();
+        if (trimmed) {
+            this.requireValidShortcut(trimmed, id);
+            this.requireItemLimits({ name: this.tools.get(id).name, shortcut: trimmed });
+        }
+        this.commit((draft) => {
+            const map = draft.toolShortcuts ?? {};
+            if (trimmed)
+                map[id] = trimmed;
+            else
+                delete map[id];
+            draft.toolShortcuts = map;
+        });
+    }
     /* ---------- Keyboard shortcuts ---------- */
     /**
      * Binds the shortcuts of everything saved (scripts, recordings, snippets)
@@ -428,6 +533,12 @@ export class MacroKit {
             if (snippet.shortcut)
                 bindings.push({ shortcut: snippet.shortcut, run: () => this.expandSnippet(snippet.id) });
         }
+        for (const [toolId, shortcut] of Object.entries(this.state.toolShortcuts ?? {})) {
+            // Only registered tools bind: a stored shortcut of a tool the host did
+            // not register this session must not swallow the key.
+            if (this.tools.has(toolId))
+                bindings.push({ shortcut, run: () => this.runTool(toolId) });
+        }
         return bindings;
     }
     /* ---------- Import/export ---------- */
@@ -456,6 +567,9 @@ export class MacroKit {
                 scripts: [...this.state.scripts.map((item) => ({ ...item }))],
                 recordings: [...this.state.recordings.map((item) => ({ ...item }))],
                 snippets: [...this.state.snippets.map((item) => ({ ...item }))],
+                ...(this.state.toolShortcuts || imported.toolShortcuts
+                    ? { toolShortcuts: { ...this.state.toolShortcuts, ...imported.toolShortcuts } }
+                    : {}),
             };
             for (const script of imported.scripts)
                 this.upsert(candidate.scripts, script);
@@ -493,6 +607,10 @@ export class MacroKit {
             ...candidate.scripts,
             ...candidate.recordings,
             ...candidate.snippets,
+            ...Object.entries(candidate.toolShortcuts ?? {}).map(([toolId, shortcut]) => ({
+                name: this.tools.get(toolId)?.name ?? toolId,
+                shortcut,
+            })),
         ];
         for (const item of items) {
             if (!item.shortcut)

package/dist/messages.d.ts

@@ -49,6 +49,12 @@ export interface MacroMessages {
      * objects compiled against 0.7.0.
      */
     recordingUncapturable?: (commandIds: string) => string;
+    /**
+     * Built-in tools. Optional for source compatibility with full locale
+     * objects compiled against 0.8.0 (same reasoning as recordingUncapturable).
+     */
+    toolNotFound?: string;
+    toolAlreadyRegistered?: (id: string) => string;
     shortcutInvalid: string;
     shortcutNeedsModifier: string;
     shortcutReserved: string;

package/dist/messages.js

@@ -44,6 +44,8 @@ export const ENGLISH_MESSAGES = {
     recordingTooLarge: 'The recording is too large to save',
     recordingIncomplete: (commandIds) => `The recording is missing actions that cannot be recorded (${commandIds})`,
     recordingUncapturable: (commandIds) => `The recording contains only actions that cannot be recorded (${commandIds})`,
+    toolNotFound: 'Tool not found',
+    toolAlreadyRegistered: (id) => `A tool with the id "${id}" is already registered`,
     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',
@@ -85,6 +87,8 @@ export const HEBREW_MESSAGES = {
     recordingTooLarge: 'ההקלטה גדולה מכדי להישמר',
     recordingIncomplete: (commandIds) => `בהקלטה חסרות פעולות שאינן ניתנות להקלטה (${commandIds})`,
     recordingUncapturable: (commandIds) => `ההקלטה מכילה רק פעולות שאינן ניתנות להקלטה (${commandIds})`,
+    toolNotFound: 'הכלי לא נמצא',
+    toolAlreadyRegistered: (id) => `כלי עם המזהה "${id}" כבר רשום`,
     shortcutInvalid: 'קיצור לא תקין — הצורה הנדרשת היא למשל Ctrl+Alt+M',
     shortcutNeedsModifier: 'קיצור חייב לכלול Ctrl,‏ Alt או Meta',
     shortcutReserved: 'הקיצור הזה שמור לעורך',

package/dist/storage.d.ts

@@ -9,6 +9,12 @@ export interface PersistedMacroState {
     scripts: SavedScript[];
     recordings: RecordedMacro[];
     snippets: Snippet[];
+    /**
+     * Keyboard shortcuts of built-in tools, keyed by tool id. Optional for
+     * backward compatibility: stores written before tools existed lack it,
+     * and they must keep loading as-is.
+     */
+    toolShortcuts?: Record<string, string>;
 }
 export interface MacroStorage {
     /** `null` when there is no saved state or the saved state is unreadable. */

package/dist/storage.js

@@ -90,11 +90,24 @@ function isValidSnippet(value) {
         optionalBoundedString(snippet.trigger, IMPORT_LIMITS.maxTriggerLength) &&
         optionalBoundedString(snippet.shortcut, IMPORT_LIMITS.maxShortcutLength));
 }
+/** Tool-shortcut map: bounded ids to bounded shortcut strings, capped like the item lists. */
+function isValidToolShortcuts(value) {
+    if (value === undefined)
+        return true;
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const entries = Object.entries(value);
+    if (entries.length > IMPORT_LIMITS.maxItems)
+        return false;
+    return entries.every(([id, shortcut]) => boundedString(id, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(shortcut, IMPORT_LIMITS.maxShortcutLength));
+}
 function isValidState(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const state = value;
     return (state.version === 1 &&
+        isValidToolShortcuts(state.toolShortcuts) &&
         Array.isArray(state.scripts) &&
         state.scripts.length <= IMPORT_LIMITS.maxItems &&
         state.scripts.every(isValidScript) &&

package/dist/types.d.ts

@@ -125,6 +125,31 @@ export interface RecordedMacro {
     shortcut?: string;
     steps: MacroStep[];
 }
+/**
+ * A built-in tool the host registers on the kit: a native document-processing
+ * action (implemented by the host against its own engine access) that the kit
+ * exposes alongside recordings and scripts — listable in a management UI,
+ * runnable under the same one-run-at-a-time guard, and bindable to a
+ * persisted keyboard shortcut. Tools are runtime registrations, never
+ * persisted themselves; only their shortcuts are.
+ */
+export interface BuiltinTool {
+    /** Stable identifier, e.g. `'shulchan.first-word'`. Shortcut persistence is keyed by it. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** One-line description for management UIs. */
+    description?: string;
+    /** Runs the tool. A thrown error is reported as a failed outcome. */
+    run(): Promise<MacroOutcome> | MacroOutcome;
+}
+/** A registered tool as listed to UIs — the registration plus its persisted shortcut. */
+export interface BuiltinToolInfo {
+    id: string;
+    name: string;
+    description?: string;
+    shortcut?: string;
+}
 /** A written macro — a JavaScript script that runs against the toolkit's API. */
 export interface SavedScript {
     id: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "superdoc-macros",
-  "version": "0.7.1",
-  "description": "Macro toolkit for SuperDoc-based editors: sandboxed scripted macros, a Word-style macro recorder, and snippets with auto-text expansion.",
+  "version": "0.9.0",
+  "description": "Macro toolkit for SuperDoc-based editors: sandboxed scripted macros, a Word-style macro recorder, snippets with auto-text expansion, and read-only VBA import from .docm files.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,6 +34,8 @@
     "snippets",
     "autotext",
     "docx",
+    "docm",
+    "vba",
     "editor",
     "otzaria"
   ],