superdoc-macros 0.8.0 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 A macro toolkit for **SuperDoc v2**-based editors. Originally built for [otzaria-word-editor](https://github.com/Y-PLONI/otzaria-word-editor), but fully generic: it has no dependency on that project — nor on the superdoc package itself (the engine is consumed structurally, through its public surfaces), and the core works against any editor that implements a small `MacroHost` interface.
 
-Three capabilities, in the spirit of Word macros:
+The capabilities, in the spirit of Word macros:
 
 | Capability | What it gives you |
 | --- | --- |
@@ -10,10 +10,11 @@ Three capabilities, in the spirit of Word macros:
 | **Macro recorder** | "Record → work normally → stop → replay" — records commands and typing, like Word's recorder |
 | **Snippets (AutoText)** | Templates with variables (`{{date}}`, `{{selection}}`…), keyboard shortcuts, and auto-expansion while typing (type a trigger word + space) |
 | **VBA import (read-only)** | Reads the macros already inside a `.docm` and shows the user their real source, so they can port it. Nothing is executed |
+| **Built-in tools** | Host-implemented document actions registered on the kit — listed, run and shortcut-bound alongside everything else |
 
 Plus: persistence (localStorage or custom storage), JSON import/export, keyboard shortcut binding, and localizable runtime messages (English by default, Hebrew locale included).
 
-> **A note on VBA:** the toolkit does not *execute* VBA — there is no VBA engine in the browser, and running document-supplied code is not something it will grow into. What it does instead is two things: it lets a user **see** the macros a `.docm` already contains (section 4), and it provides a parallel, JavaScript-based macro system to rewrite them in.
+> **A note on VBA:** the toolkit does not *execute* VBA — there is no VBA engine in the browser, and running document-supplied code is not something it will grow into. What it does instead is two things: it lets a user **see** the macros a `.docm` already contains (section 5), and it provides a parallel, JavaScript-based macro system to rewrite them in.
 
 ## Installation
 
@@ -119,7 +120,26 @@ await kit.expandSnippet(id);   // or expand explicitly / via the shortcut
 
 Built-in variables: `{{date}}`, `{{time}}`, `{{datetime}}` (formatted with the browser locale, or an explicit `locale` option), `{{selection}}`. Any other name resolves from the `variables` passed to `expandSnippet`; a variable with no value stays visible in the text.
 
-## 4. Reading the VBA in an existing `.docm`
+## 4. Built-in tools
+
+A host often ships native document-processing actions of its own — implemented against its full engine access, beyond what the sandboxed script API exposes. Registering them on the kit puts them next to recordings and scripts: one management UI, one run-at-a-time guard, and one shortcut system with persistence and collision rules.
+
+```ts
+kit.registerTool({
+  id: 'typography.first-word',
+  name: 'Format first word',
+  description: 'Enlarges the first word of every selected paragraph',
+  run: () => applyFirstWordDesign(editor),   // host code, returns { ok } / { ok: false, message }
+});
+
+kit.listTools();                              // [{ id, name, description, shortcut? }]
+await kit.runTool('typography.first-word');   // refused while recording or while another macro runs
+kit.setToolShortcut('typography.first-word', 'Ctrl+Alt+1');  // persisted; validated like every binding
+```
+
+Tools are runtime registrations — they are never persisted or exported. Only their shortcuts are, keyed by the tool id, so a shortcut survives restarts and waits for the day its tool is registered again; an unregistered tool's shortcut is never bound.
+
+## 5. Reading the VBA in an existing `.docm`
 
 A user who has relied on a macro-enabled document for years should not be told their macros are simply gone. This reads the macro project out of the package and hands back each module's real source text:
 

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';

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,6 +1,6 @@
 {
   "name": "superdoc-macros",
-  "version": "0.8.0",
+  "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",