superdoc-macros 0.2.0 → 0.4.0

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

@@ -1,5 +1,5 @@
 import { type MacroRunner } from './runner.js';
-/** סימון ההודעות של הפרוטוקול, כדי לא להתנגש בהודעות אחרות בדף. */
+/** Protocol marker, so the messages cannot collide with others on the page. */
 export declare const PROTOCOL_MARK: "__otzariaMacro";
 export type SandboxMessage = {
     [PROTOCOL_MARK]: true;
@@ -31,11 +31,12 @@ export type HostMessage = {
     value?: unknown;
     message?: string;
 };
-/** האם הודעה שייכת לפרוטוקול. חשופה לבדיקות. */
+/** Whether a message belongs to the protocol. Exposed for tests. */
 export declare function isProtocolMessage(data: unknown): data is SandboxMessage;
 /**
- * הקוד שרץ בתוך ה-iframe. מחרוזת ולא פונקציה מוסרלת — כדי שה-build לא ישנה
- * אותו (minify של שמות היה שובר את הפרוטוקול).
+ * The code that runs inside the iframe. A string rather than a serialized
+ * function, so the build cannot touch it (minifying names would break the
+ * protocol).
  */
 export declare const SANDBOX_BOOTSTRAP: string;
 export declare function createIframeRunner(doc?: Document): MacroRunner;

package/dist/scripting/iframe-runner.js

@@ -1,8 +1,26 @@
-import { limitCalls } from './eval-runner.js';
+/**
+ * Sandboxed script runner — an iframe with `sandbox="allow-scripts"` only.
+ *
+ * The iframe gets an opaque origin: no access to the page's DOM, to
+ * localStorage, to cookies, or to the network with the user's credentials.
+ * Its only way to touch the document is RPC over postMessage to the
+ * `MacroApi` methods — every call goes through `bridge.call`, which enforces
+ * a closed method list and a call cap.
+ *
+ * The time cap here is real: when it expires the iframe is removed from the
+ * DOM, which also kills an infinite synchronous loop — it runs on the
+ * iframe's event loop, not the page's.
+ *
+ * Return values and arguments cross a structured-clone boundary; the API is
+ * already shaped so everything it returns is JSON-safe (see
+ * `ScriptSelection`).
+ */
+import { macroMessages } from '../messages.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';
-/** האם הודעה שייכת לפרוטוקול. חשופה לבדיקות. */
+/** Whether a message belongs to the protocol. Exposed for tests. */
 export function isProtocolMessage(data) {
     return (typeof data === 'object' &&
         data !== null &&
@@ -10,8 +28,9 @@ export function isProtocolMessage(data) {
         typeof data.kind === 'string');
 }
 /**
- * הקוד שרץ בתוך ה-iframe. מחרוזת ולא פונקציה מוסרלת — כדי שה-build לא ישנה
- * אותו (minify של שמות היה שובר את הפרוטוקול).
+ * The code that runs inside the iframe. A string rather than a serialized
+ * function, so the build cannot touch it (minifying names would break the
+ * protocol).
  */
 export const SANDBOX_BOOTSTRAP = `
 'use strict';
@@ -28,7 +47,7 @@ export const SANDBOX_BOOTSTRAP = `
   var api = new Proxy({}, {
     get: function (_target, method) {
       if (typeof method !== 'string') return undefined;
-      if (method === 'then') return undefined; // ש-await api לא יתפרש כ-thenable
+      if (method === 'then') return undefined; // so "await api" is not treated as a thenable
       return function () {
         var args = Array.prototype.slice.call(arguments);
         return new Promise(function (resolve, reject) {
@@ -75,7 +94,7 @@ export const SANDBOX_BOOTSTRAP = `
   post({ kind: 'ready' });
 })();
 `;
-/** ערך בטוח למסירה חזרה ל-iframe (structured clone עלול להיכשל על אובייקטי מנוע). */
+/** A value safe to hand back to the iframe (structured clone can fail on engine objects). */
 function toCloneSafe(value) {
     if (value === undefined || value === null)
         return value;
@@ -90,25 +109,36 @@ 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();
                     resolve(result);
                 };
                 const onMessage = (event) => {
-                    // רק הודעות מה-iframe הזה: דף יכול להריץ כמה מאקרו במקביל.
+                    // Only messages from this iframe: a page may run several macros at once.
                     if (event.source !== iframe.contentWindow)
                         return;
                     const data = event.data;
@@ -120,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) }, '*');
@@ -142,7 +172,7 @@ export function createIframeRunner(doc = document) {
                         finish({ ok: false, reason: 'error', message: data.message });
                 };
                 addEventListener('message', onMessage);
-                timer = setTimeout(() => finish({ ok: false, reason: 'timeout', message: `המאקרו לא הסתיים תוך ${timeoutMs / 1000} שניות ונעצר` }), timeoutMs);
+                timer = setTimeout(() => finish({ ok: false, reason: 'timeout', message: macroMessages().timedOut(timeoutMs / 1000) }), timeoutMs);
                 doc.body.appendChild(iframe);
             });
         },

package/dist/scripting/macro-api.d.ts

@@ -1,34 +1,23 @@
-/**
- * ה-API שסקריפט מאקרו מקבל.
- *
- * שני צרכנים לאותו מימוש: מריץ ה-eval מקבל את האובייקט `api` ישירות, ומריץ
- * ה-iframe מדבר איתו דרך `call(method, args)` — RPC על postMessage. לכן כל
- * מתודה רשומה במילון אחד, וה-proxy בתוך ה-iframe פונה לאותם שמות בדיוק.
- *
- * כללי כשל: פעולות כתיבה זורקות `MacroError` כשהן נכשלות, כדי שסקריפט ייעצר
- * במקום להמשיך על מסמך במצב לא צפוי. `command()` הגולמית מחזירה את התוצאה
- * ואינה זורקת — למי שרוצה לבדוק בעצמו.
- */
 import type { MacroHost, MacroOutcome } from '../types.js';
-/** כשל של פעולת מאקרו. השם מאפשר לסקריפט להבחין בינו ובין TypeError שלו. */
+/** A macro operation failure. Named so a script can tell it apart from its own TypeError. */
 export declare class MacroError extends Error {
     readonly reason?: string;
     constructor(message: string, reason?: string);
 }
-/** תצלום בחירה בטוח למסירה ל-iframe (בלי היעד האטום של המנוע). */
+/** Selection snapshot that is safe to hand to the iframe (without the engine's opaque target). */
 export interface ScriptSelection {
     text: string;
     hasRange: boolean;
     blockId: string | null;
     empty: boolean;
 }
-/** מה שסקריפט מקבל בתור `api`. כל המתודות א-סינכרוניות. */
+/** What a script receives as `api`. Every method is async. */
 export interface MacroApi {
-    /** מריצה פקודה מקטלוג המנוע. מחזירה תוצאה ואינה זורקת. */
+    /** Runs a command from the engine catalog. Returns the outcome, never throws. */
     command(id: string, payload?: unknown): Promise<MacroOutcome>;
-    /** האם המנוע מכיר את הפקודה. */
+    /** Whether the engine recognizes the command. */
     hasCommand(id: string): Promise<boolean>;
-    /** מזהי הפקודות המוכרות. */
+    /** The known command ids. */
     commandIds(): Promise<readonly string[]>;
     insertText(text: string): Promise<void>;
     insertParagraph(): Promise<void>;
@@ -36,7 +25,7 @@ export interface MacroApi {
     getSelection(): Promise<ScriptSelection>;
     getSelectionText(): Promise<string>;
     getDocumentText(): Promise<string>;
-    /** מחליפה את כל המופעים. מחזירה כמה הוחלפו. */
+    /** Replaces every occurrence. Returns how many were replaced. */
     replaceAll(query: string, replacement: string): Promise<number>;
     bold(): Promise<void>;
     italic(): Promise<void>;
@@ -51,19 +40,19 @@ export interface MacroApi {
     directionLtr(): Promise<void>;
     undo(): Promise<void>;
     redo(): Promise<void>;
-    /** כותבת שורה ליומן הריצה (מוצג למשתמש, לא ל-console). */
+    /** Writes a line to the run log (shown to the user, not to the console). */
     log(...parts: unknown[]): Promise<void>;
 }
 export interface MacroApiOptions {
-    /** מקבלת כל שורת `api.log`. ברירת המחדל: console.info. */
+    /** Receives every `api.log` line. Default: console.info. */
     onLog?: (line: string) => void;
 }
 export interface MacroBridge {
     api: MacroApi;
-    /** מסלול ה-RPC: מפעילה מתודה לפי שם. זורקת על מתודה שאינה קיימת. */
+    /** The RPC path: invokes a method by name. Throws on an unknown method. */
     call(method: string, args: readonly unknown[]): Promise<unknown>;
-    /** מספר הקריאות שבוצעו עד כה. משמש לתקרת קריאות במריצים. */
+    /** Number of calls made so far. Used by the runners' call limit. */
     callCount(): number;
 }
-/** בונה את ה-API מעל מארח. */
+/** Builds the API on top of a host. */
 export declare function createMacroApi(host: MacroHost, options?: MacroApiOptions): MacroBridge;

package/dist/scripting/macro-api.js

@@ -1,4 +1,19 @@
-/** כשל של פעולת מאקרו. השם מאפשר לסקריפט להבחין בינו ובין TypeError שלו. */
+/**
+ * The API a macro script receives.
+ *
+ * Two consumers share one implementation: the eval runner hands the `api`
+ * object to the script directly, and the iframe runner talks to it through
+ * `call(method, args)` — RPC over postMessage. Every method therefore lives
+ * in a single dictionary, and the proxy inside the iframe addresses exactly
+ * the same names.
+ *
+ * Failure rules: write operations throw a `MacroError` when they fail, so a
+ * script stops instead of continuing against a document in an unexpected
+ * state. The raw `command()` returns the outcome and does not throw — for
+ * scripts that want to check it themselves.
+ */
+import { macroMessages } from '../messages.js';
+/** A macro operation failure. Named so a script can tell it apart from its own TypeError. */
 export class MacroError extends Error {
     reason;
     constructor(message, reason) {
@@ -14,7 +29,7 @@ function requireOk(outcome, action) {
 }
 function asText(value, name) {
     if (typeof value !== 'string')
-        throw new MacroError(`${name} חייב להיות מחרוזת`);
+        throw new MacroError(macroMessages().mustBeString(name));
     return value;
 }
 function formatLogPart(part) {
@@ -27,27 +42,27 @@ function formatLogPart(part) {
         return String(part);
     }
 }
-/** בונה את ה-API מעל מארח. */
+/** Builds the API on top of a host. */
 export function createMacroApi(host, options = {}) {
     const onLog = options.onLog ?? ((line) => console.info('[superdoc-macros]', line));
     const commandSugar = async (id) => {
-        requireOk(await host.commands.execute(id), `הפקודה ${id} נכשלה`);
+        requireOk(await host.commands.execute(id), macroMessages().commandFailed(id));
     };
     const api = {
         command: (id, payload) => host.commands.execute(asText(id, 'id'), payload),
         hasCommand: async (id) => host.commands.has(asText(id, 'id')),
         commandIds: async () => host.commands.ids(),
         async insertText(text) {
-            requireOk(await host.insertText(asText(text, 'text')), 'הכנסת הטקסט נכשלה');
+            requireOk(await host.insertText(asText(text, 'text')), macroMessages().insertTextFailed);
         },
         async insertParagraph() {
-            requireOk(await host.insertText('\n'), 'הכנסת הפסקה נכשלה');
+            requireOk(await host.insertText('\n'), macroMessages().insertParagraphFailed);
         },
         async deleteBackward(count = 1) {
             const n = Math.max(0, Math.trunc(Number(count)));
             if (n === 0)
                 return;
-            requireOk(await host.deleteBackward(n), 'המחיקה נכשלה');
+            requireOk(await host.deleteBackward(n), macroMessages().deleteFailed);
         },
         async getSelection() {
             const snapshot = await host.getSelection({ includeText: true });
@@ -65,7 +80,7 @@ export function createMacroApi(host, options = {}) {
         async replaceAll(query, replacement) {
             const result = await host.replaceAll(asText(query, 'query'), asText(replacement, 'replacement'));
             if (!result.ok)
-                throw new MacroError(result.message ?? 'ההחלפה נכשלה');
+                throw new MacroError(result.message ?? macroMessages().replaceFailed);
             return result.replaced;
         },
         bold: () => commandSugar('bold'),
@@ -92,7 +107,7 @@ export function createMacroApi(host, options = {}) {
         async call(method, args) {
             const fn = methods[method];
             if (typeof fn !== 'function' || !Object.prototype.hasOwnProperty.call(api, method)) {
-                throw new MacroError(`מתודה לא מוכרת: ${String(method)}`);
+                throw new MacroError(macroMessages().unknownMethod(String(method)));
             }
             calls += 1;
             return fn.apply(api, args);

package/dist/scripting/runner.d.ts

@@ -1,4 +1,4 @@
-/** חוזה משותף לשני המריצים (eval ו-iframe). */
+/** Contract shared by the two runners (eval and iframe). */
 import type { MacroBridge } from './macro-api.js';
 export type MacroRunResult = {
     ok: true;
@@ -9,9 +9,9 @@ export type MacroRunResult = {
     reason?: 'timeout' | 'error' | 'call-limit';
 };
 export interface MacroRunOptions {
-    /** תקרת זמן לריצה כולה. ברירת מחדל: 30 שניות. */
+    /** Time cap for the whole run. Default: 30 seconds. */
     timeoutMs?: number;
-    /** תקרת קריאות API, נגד לולאה בורחת. ברירת מחדל: 10,000. */
+    /** API call cap, against runaway loops. Default: 10,000. */
     maxApiCalls?: number;
 }
 export declare const DEFAULT_TIMEOUT_MS = 30000;

package/dist/shortcuts.d.ts

@@ -1,7 +1,8 @@
 /**
- * קיצורי מקלדת למאקרו ולקטעים: ניתוח מחרוזת `Ctrl+Alt+M` והתאמה לאירוע.
+ * Keyboard shortcuts for macros and snippets: parsing a `Ctrl+Alt+M` string
+ * and matching it against an event.
  *
- * ההתאמה לפי `event.key` באותיות קטנות. `Mod` פירושו Ctrl (או ⌘ במק).
+ * Matching is by lowercased `event.key`. `Mod` means Ctrl (or ⌘ on macOS).
  */
 export interface ParsedShortcut {
     key: string;
@@ -9,10 +10,10 @@ export interface ParsedShortcut {
     alt: boolean;
     shift: boolean;
     meta: boolean;
-    /** Ctrl או Meta — לקיצורים שנכתבו עם `Mod`. */
+    /** Ctrl or Meta — for shortcuts written with `Mod`. */
     mod: boolean;
 }
-/** תת-הצורה של KeyboardEvent שההתאמה צריכה. מאפשר בדיקות בלי DOM. */
+/** The subset of KeyboardEvent that matching needs. Enables DOM-free tests. */
 export interface KeyEventLike {
     key: string;
     ctrlKey: boolean;
@@ -24,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>;
@@ -33,7 +46,8 @@ export interface ShortcutTarget {
     removeEventListener(type: 'keydown', listener: (event: KeyboardEvent) => void, options?: boolean): void;
 }
 /**
- * קושרת קיצורים ליעד. `getBindings` נקראת בכל הקשה — כך רשימת המאקרו יכולה
- * להשתנות בלי לקשור מחדש. מחזירה פונקציית ניתוק.
+ * Binds shortcuts to a target. `getBindings` is called on every keystroke —
+ * so the macro list can change without rebinding. Returns a dispose
+ * function.
  */
 export declare function bindShortcuts(target: ShortcutTarget, getBindings: () => readonly ShortcutBinding[]): () => void;

package/dist/shortcuts.js

@@ -29,7 +29,7 @@ export function parseShortcut(shortcut) {
                 break;
             default: {
                 if (parsed.key)
-                    return null; // שני מקשים שאינם modifiers — קיצור פסול.
+                    return null; // two non-modifier keys — an invalid shortcut.
                 parsed.key = normalizeKey(part);
             }
         }
@@ -50,7 +50,7 @@ export function eventMatches(parsed, event) {
     if (parsed.mod) {
         if (!event.ctrlKey && !event.metaKey)
             return false;
-        // עם Mod לא בודקים ctrl/meta בנפרד — אבל alt/shift חייבים להתאים בדיוק.
+        // With Mod, ctrl/meta are not checked individually — but alt/shift must match exactly.
         return event.altKey === parsed.alt && event.shiftKey === parsed.shift;
     }
     return (event.ctrlKey === parsed.ctrl &&
@@ -59,8 +59,28 @@ export function eventMatches(parsed, event) {
         event.metaKey === parsed.meta);
 }
 /**
- * קושרת קיצורים ליעד. `getBindings` נקראת בכל הקשה — כך רשימת המאקרו יכולה
- * להשתנות בלי לקשור מחדש. מחזירה פונקציית ניתוק.
+ * 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
+ * function.
  */
 export function bindShortcuts(target, getBindings) {
     const listener = (event) => {

package/dist/snippets/autotext.d.ts

@@ -1,25 +1,28 @@
 /**
- * השלמה אוטומטית (AutoText): הקלדת מילת ההפעלה של קטע ואחריה רווח מחליפה את
- * המילה בתוכן הקטע.
+ * Auto-text: typing a snippet's trigger word followed by a space replaces
+ * the word with the snippet's content.
  *
- * איך זה עובד: נשמר חוצץ קטן של התווים שהוקלדו ברצף הנוכחי (מתוך אירועי
- * `TextInputEvent` של המארח). כשמוקלד תו הרחבה (רווח כברירת מחדל) והמילה
- * שלפניו היא trigger של קטע — המילה ותו ההרחבה נמחקים לאחור, והתוכן המורחב
- * מוכנס במקומם עם תו ההרחבה בסופו.
+ * How it works: a small buffer keeps the characters typed in the current run
+ * (from the host's `TextInputEvent`s). When an expansion character (space by
+ * default) is typed and the word before it is some snippet's trigger, the
+ * word and the expansion character are deleted backwards and the rendered
+ * content is inserted in their place, with the expansion character restored
+ * at the end.
  *
- * החוצץ מתאפס על פסקה חדשה, על מחיקה קדימה ועל פקודה שרצה באמצע — כל דבר
- * שמנתק את הרצף בין מה שהוקלד ובין מה שנמצא בפועל לפני הסמן. עדיף פספוס
- * הרחבה על הרחבה שמוחקת טקסט לא נכון.
+ * The buffer resets on a new paragraph, on forward deletion and on a command
+ * running mid-typing — anything that breaks the correspondence between what
+ * was typed and what actually sits before the caret. A missed expansion is
+ * better than an expansion that deletes the wrong text.
  */
 import type { MacroHost, Snippet } from '../types.js';
 export interface AutoTextOptions {
-    /** תווי ההרחבה. ברירת מחדל: רווח בלבד. */
+    /** The expansion characters. Default: space only. */
     expandOn?: readonly string[];
-    /** גודל החוצץ. מילת הפעלה ארוכה מזה לא תזוהה. */
+    /** Buffer size. A trigger word longer than this will not be recognized. */
     bufferSize?: number;
-    /** נקראת אחרי הרחבה מוצלחת. */
+    /** Called after a successful expansion. */
     onExpand?: (snippet: Snippet) => void;
-    /** נקראת כשהרחבה נכשלה (למשל מסמך לקריאה בלבד). */
+    /** Called when an expansion failed (e.g. a read-only document). */
     onError?: (message: string) => void;
 }
 export declare class AutoText {

package/dist/snippets/autotext.js

@@ -27,7 +27,7 @@ export class AutoText {
             return () => this.detach();
         this.buffer = '';
         this.disposeInput = this.host.onTextInput((event) => void this.handleInput(event));
-        // פקודה באמצע הקלדה (עיצוב, הדבקה) מנתקת את הקשר בין החוצץ למסמך.
+        // A command mid-typing (formatting, paste) breaks the buffer's link to the document.
         this.disposeCommand = this.host.onCommand(() => {
             if (!this.busy)
                 this.buffer = '';
@@ -42,7 +42,7 @@ export class AutoText {
         this.buffer = '';
     }
     async handleInput(event) {
-        // קלט שנוצר בזמן שההרחבה עצמה כותבת — לא חלק מההקלדה של המשתמש.
+        // Input generated while the expansion itself is writing — not the user's typing.
         if (this.busy)
             return;
         switch (event.kind) {
@@ -74,14 +74,16 @@ export class AutoText {
     async expand(snippet, trigger, expandChar) {
         this.busy = true;
         try {
-            // אירוע הקלט (beforeinput) נורה לפני שהתו נכתב למסמך. הדחייה לתור
-            // המשימות מבטיחה שתו ההרחבה כבר בפנים לפני שמוחקים אותו יחד עם ה-trigger.
+            // The input event (beforeinput) fires before the character is written
+            // to the document. Deferring to the task queue guarantees the expansion
+            // character is already in before it is deleted along with the trigger.
             await new Promise((resolve) => setTimeout(resolve, 0));
             const selectionText = usesSelection(snippet.text)
                 ? (await this.host.getSelection({ includeText: true })).text
                 : undefined;
             const rendered = renderSnippet(snippet.text, { selectionText });
-            // תו ההרחבה כבר נכתב למסמך כשמגיעים לכאן, ולכן הוא נכלל במחיקה ומוחזר בסוף.
+            // The expansion character is already in the document by now, so it is
+            // included in the deletion and restored at the end.
             const deleted = await this.host.deleteBackward(trigger.length + 1);
             if (!deleted.ok) {
                 this.onError?.(deleted.message);
@@ -99,7 +101,7 @@ export class AutoText {
         }
     }
 }
-/** המילה שבסוף החוצץ — רצף שאינו רווח לבן. */
+/** The word at the end of the buffer — a run of non-whitespace. */
 function trailingWord(buffer) {
     const match = /(\S+)$/u.exec(buffer);
     return match?.[1] ?? null;

package/dist/snippets/snippets.d.ts

@@ -1,26 +1,30 @@
 /**
- * קטעי טקסט (Snippets): תבניות שמוכנסות במיקום הסמן, עם משתני `{{...}}`.
+ * Text snippets: templates inserted at the caret, with `{{...}}` variables.
  *
- * משתנים מובנים: `{{date}}`, `{{time}}`, `{{datetime}}` (בעברית, לפי שעון
- * המערכת), `{{selection}}` (הטקסט המסומן ברגע ההרחבה). כל שם אחר נפתר מתוך
- * `variables` שנמסרו בקריאה; משתנה שאין לו ערך נשאר כמו שהוא בטקסט — כדי
- * שטעות כתיב תיראה במסמך ולא תיעלם בשקט.
+ * Built-in variables: `{{date}}`, `{{time}}`, `{{datetime}}` (system clock,
+ * formatted with the configured locale) and `{{selection}}` (the selected
+ * text at expansion time). Any other name resolves from the `variables`
+ * passed to the call; a variable with no value stays visible in the text —
+ * so a typo shows up in the document instead of vanishing silently.
  */
 import type { MacroHost, MacroOutcome, Snippet } from '../types.js';
 export interface RenderContext {
-    /** ערכים למשתנים מותאמים. */
+    /** Values for custom variables. */
     variables?: Readonly<Record<string, string>>;
-    /** הטקסט שיוצב ב-`{{selection}}`. */
+    /** The text substituted for `{{selection}}`. */
     selectionText?: string;
-    /** הזמן ל-`{{date}}`/`{{time}}`. ברירת מחדל: עכשיו. קיים בשביל בדיקות. */
+    /** The time for `{{date}}`/`{{time}}`. Default: now. Exists for tests. */
     now?: Date;
+    /** BCP-47 locale for date/time formatting. Default: the browser's. */
+    locale?: string;
 }
 export declare function renderSnippet(text: string, context?: RenderContext): string;
-/** האם הקטע משתמש ב-`{{selection}}` — ואז ההרחבה צריכה לקרוא את הבחירה. */
+/** Whether the snippet uses `{{selection}}` — in which case expansion must read the selection. */
 export declare function usesSelection(text: string): boolean;
 export interface ExpandOptions {
     variables?: Readonly<Record<string, string>>;
     now?: Date;
+    locale?: string;
 }
-/** מרחיבה קטע במיקום הסמן. */
+/** Expands a snippet at the caret. */
 export declare function expandSnippet(host: MacroHost, snippet: Pick<Snippet, 'text'>, options?: ExpandOptions): Promise<MacroOutcome>;

package/dist/snippets/snippets.js

@@ -1,15 +1,16 @@
 const VARIABLE_PATTERN = /\{\{\s*([\p{L}\p{N}_-]+)\s*\}\}/gu;
 export function renderSnippet(text, context = {}) {
     const now = context.now ?? new Date();
+    const locale = context.locale;
     return text.replace(VARIABLE_PATTERN, (whole, rawName) => {
         const name = rawName.toLowerCase();
         switch (name) {
             case 'date':
-                return now.toLocaleDateString('he-IL');
+                return now.toLocaleDateString(locale);
             case 'time':
-                return now.toLocaleTimeString('he-IL', { hour: '2-digit', minute: '2-digit' });
+                return now.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' });
             case 'datetime':
-                return `${now.toLocaleDateString('he-IL')} ${now.toLocaleTimeString('he-IL', { hour: '2-digit', minute: '2-digit' })}`;
+                return `${now.toLocaleDateString(locale)} ${now.toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit' })}`;
             case 'selection':
                 return context.selectionText ?? '';
             default: {
@@ -19,13 +20,13 @@ export function renderSnippet(text, context = {}) {
         }
     });
 }
-/** האם הקטע משתמש ב-`{{selection}}` — ואז ההרחבה צריכה לקרוא את הבחירה. */
+/** Whether the snippet uses `{{selection}}` — in which case expansion must read the selection. */
 export function usesSelection(text) {
     return /\{\{\s*selection\s*\}\}/iu.test(text);
 }
-/** מרחיבה קטע במיקום הסמן. */
+/** Expands a snippet at the caret. */
 export async function expandSnippet(host, snippet, options = {}) {
-    // הבחירה נקראת רק כשנחוצה: חילוץ טקסט הבחירה עולה בביצועים במנוע.
+    // The selection is read only when needed: extracting its text has an engine cost.
     const selectionText = usesSelection(snippet.text)
         ? (await host.getSelection({ includeText: true })).text
         : undefined;
@@ -33,6 +34,7 @@ export async function expandSnippet(host, snippet, options = {}) {
         variables: options.variables,
         selectionText,
         now: options.now,
+        locale: options.locale,
     });
     return host.insertText(rendered);
 }