superdoc-macros 0.2.0 → 0.4.0

package/dist/storage.d.ts

@@ -1,6 +1,7 @@
 /**
- * שמירת המאקרו, ההקלטות והקטעים. ברירת המחדל: localStorage; הממשק ניתן
- * להחלפה כדי שמארח יוכל לשמור בקובץ (למשל ב-workspace של תוסף אוצריא).
+ * Persistence for macros, recordings and snippets. Default: localStorage;
+ * the interface is swappable so a host can persist to a file (e.g. a
+ * plugin workspace).
  */
 import type { RecordedMacro, SavedScript, Snippet } from './types.js';
 export interface PersistedMacroState {
@@ -10,15 +11,38 @@ export interface PersistedMacroState {
     snippets: Snippet[];
 }
 export interface MacroStorage {
-    /** `null` כשאין מצב שמור או כשהשמור אינו קריא. */
+    /** `null` when there is no saved state or the saved state is unreadable. */
     load(): PersistedMacroState | null;
     save(state: PersistedMacroState): void;
 }
 export declare function emptyState(): PersistedMacroState;
-/** מפענחת מצב שמור. `null` על כל צורה לא צפויה — לא זורקת. */
+/**
+ * Caps on imported data. Imports come from files users share with each
+ * other, so every field is validated and bounded — a malformed or oversized
+ * export must fail closed, not wedge the store or the UI.
+ */
+export declare const IMPORT_LIMITS: {
+    /** Whole-file size, in UTF-16 code units of the JSON string. */
+    readonly maxJsonLength: 5000000;
+    /** Per list: scripts, recordings, snippets. */
+    readonly maxItems: 500;
+    readonly maxStepsPerRecording: 5000;
+    readonly maxNameLength: 200;
+    readonly maxShortcutLength: 60;
+    readonly maxTriggerLength: 60;
+    /** Snippet text and single recorded insert-text step. */
+    readonly maxTextLength: 100000;
+    readonly maxSourceLength: 200000;
+};
+/**
+ * Parses saved/imported state. `null` on any unexpected shape, oversized
+ * field or oversized file — never throws, never partially accepts: one
+ * invalid item rejects the whole document, so the caller can tell the user
+ * the file is bad instead of silently importing a subset.
+ */
 export declare function parsePersistedState(json: string): PersistedMacroState | null;
 export declare const DEFAULT_STORAGE_KEY = "superdoc-macros:v1";
-/** localStorage עם הגנות: גישה חסומה או מלאה אינה מפילה את הערכה. */
+/** localStorage with guards: blocked or full storage must not take the toolkit down. */
 export declare function createLocalStorage(key?: string, storage?: Pick<Storage, 'getItem' | 'setItem'>): MacroStorage;
-/** אחסון בזיכרון — לבדיקות ולמצבים שבהם אין persistence. */
+/** In-memory storage — for tests and for setups with no persistence. */
 export declare function createMemoryStorage(): MacroStorage;

package/dist/storage.js

@@ -1,17 +1,105 @@
 export function emptyState() {
     return { version: 1, scripts: [], recordings: [], snippets: [] };
 }
+/**
+ * Caps on imported data. Imports come from files users share with each
+ * other, so every field is validated and bounded — a malformed or oversized
+ * export must fail closed, not wedge the store or the UI.
+ */
+export const IMPORT_LIMITS = {
+    /** Whole-file size, in UTF-16 code units of the JSON string. */
+    maxJsonLength: 5_000_000,
+    /** Per list: scripts, recordings, snippets. */
+    maxItems: 500,
+    maxStepsPerRecording: 5_000,
+    maxNameLength: 200,
+    maxShortcutLength: 60,
+    maxTriggerLength: 60,
+    /** Snippet text and single recorded insert-text step. */
+    maxTextLength: 100_000,
+    maxSourceLength: 200_000,
+};
+function boundedString(value, maxLength, allowEmpty = false) {
+    return typeof value === 'string' && value.length <= maxLength && (allowEmpty || value.length > 0);
+}
+function optionalBoundedString(value, maxLength) {
+    return value === undefined || boundedString(value, maxLength);
+}
+function isValidStep(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const step = value;
+    switch (step.type) {
+        case 'command':
+            // The payload is opaque engine data; the id is what replay dispatches on.
+            return boundedString(step.id, IMPORT_LIMITS.maxNameLength);
+        case 'insert-text':
+            return boundedString(step.text, IMPORT_LIMITS.maxTextLength, true);
+        case 'insert-paragraph':
+            return true;
+        case 'delete-backward':
+        case 'delete-forward':
+            return typeof step.count === 'number' && Number.isInteger(step.count) && step.count > 0 && step.count <= IMPORT_LIMITS.maxTextLength;
+        default:
+            return false;
+    }
+}
+function isValidScript(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const script = value;
+    return (boundedString(script.id, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(script.name, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(script.source, IMPORT_LIMITS.maxSourceLength, true) &&
+        optionalBoundedString(script.shortcut, IMPORT_LIMITS.maxShortcutLength));
+}
+function isValidRecording(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const recording = value;
+    return (recording.version === 1 &&
+        boundedString(recording.id, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(recording.name, IMPORT_LIMITS.maxNameLength) &&
+        optionalBoundedString(recording.createdAt, IMPORT_LIMITS.maxNameLength) &&
+        optionalBoundedString(recording.shortcut, IMPORT_LIMITS.maxShortcutLength) &&
+        Array.isArray(recording.steps) &&
+        recording.steps.length <= IMPORT_LIMITS.maxStepsPerRecording &&
+        recording.steps.every(isValidStep));
+}
+function isValidSnippet(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const snippet = value;
+    return (boundedString(snippet.id, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(snippet.name, IMPORT_LIMITS.maxNameLength) &&
+        boundedString(snippet.text, IMPORT_LIMITS.maxTextLength, true) &&
+        optionalBoundedString(snippet.trigger, IMPORT_LIMITS.maxTriggerLength) &&
+        optionalBoundedString(snippet.shortcut, IMPORT_LIMITS.maxShortcutLength));
+}
 function isValidState(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const state = value;
     return (state.version === 1 &&
         Array.isArray(state.scripts) &&
+        state.scripts.length <= IMPORT_LIMITS.maxItems &&
+        state.scripts.every(isValidScript) &&
         Array.isArray(state.recordings) &&
-        Array.isArray(state.snippets));
+        state.recordings.length <= IMPORT_LIMITS.maxItems &&
+        state.recordings.every(isValidRecording) &&
+        Array.isArray(state.snippets) &&
+        state.snippets.length <= IMPORT_LIMITS.maxItems &&
+        state.snippets.every(isValidSnippet));
 }
-/** מפענחת מצב שמור. `null` על כל צורה לא צפויה — לא זורקת. */
+/**
+ * Parses saved/imported state. `null` on any unexpected shape, oversized
+ * field or oversized file — never throws, never partially accepts: one
+ * invalid item rejects the whole document, so the caller can tell the user
+ * the file is bad instead of silently importing a subset.
+ */
 export function parsePersistedState(json) {
+    if (json.length > IMPORT_LIMITS.maxJsonLength)
+        return null;
     try {
         const parsed = JSON.parse(json);
         return isValidState(parsed) ? parsed : null;
@@ -21,7 +109,7 @@ export function parsePersistedState(json) {
     }
 }
 export const DEFAULT_STORAGE_KEY = 'superdoc-macros:v1';
-/** localStorage עם הגנות: גישה חסומה או מלאה אינה מפילה את הערכה. */
+/** localStorage with guards: blocked or full storage must not take the toolkit down. */
 export function createLocalStorage(key = DEFAULT_STORAGE_KEY, storage) {
     const backing = () => {
         if (storage)
@@ -48,12 +136,12 @@ export function createLocalStorage(key = DEFAULT_STORAGE_KEY, storage) {
                 backing()?.setItem(key, JSON.stringify(state));
             }
             catch (error) {
-                console.warn('[superdoc-macros] שמירת המאקרו נכשלה', error);
+                console.warn('[superdoc-macros] saving macros failed', error);
             }
         },
     };
 }
-/** אחסון בזיכרון — לבדיקות ולמצבים שבהם אין persistence. */
+/** In-memory storage — for tests and for setups with no persistence. */
 export function createMemoryStorage() {
     let saved = null;
     return {

package/dist/types.d.ts

@@ -1,12 +1,13 @@
 /**
- * החוזים המשותפים של הערכה.
+ * Shared contracts.
  *
- * `MacroHost` הוא נקודת החיבור היחידה לעורך: כל שלוש היכולות (סקריפטים,
- * מקליט, קטעי טקסט) עובדות מולו ולא מול SuperDoc ישירות. כך אפשר לבדוק את
- * הערכה עם כפיל בזיכרון, וכך מארח אחר (גרסת מנוע אחרת, עורך אחר) מתחבר
- * במימוש אחד של הממשק הזה.
+ * `MacroHost` is the single connection point to the editor: all three
+ * capabilities (scripts, recorder, snippets) work against it rather than
+ * against SuperDoc directly. That is what makes the toolkit testable with an
+ * in-memory double, and what lets another host (a different engine version,
+ * a different editor) plug in with one implementation of this interface.
  */
-/** תוצאת פעולה. אותה צורה כמו `CommandOutcome` של otzaria-word-editor. */
+/** Result of an operation. Same shape as otzaria-word-editor's `CommandOutcome`. */
 export type MacroOutcome = {
     ok: true;
 } | {
@@ -14,20 +15,20 @@ export type MacroOutcome = {
     message: string;
     reason?: string;
 };
-/** תצלום הבחירה במסמך ברגע הקריאה. */
+/** Snapshot of the document selection at the moment of the call. */
 export interface SelectionSnapshot {
-    /** הטקסט המסומן. `''` כשאין בחירה או כשלא התבקש. */
+    /** The selected text. `''` when there is no selection or it was not requested. */
     text: string;
-    /** האם יש טווח מסומן ולא רק סמן. */
+    /** Whether a range is selected, as opposed to a caret only. */
     hasRange: boolean;
-    /** מזהה הפסקה שהבחירה מתחילה בה, או `null`. */
+    /** Id of the block the selection starts in, or `null`. */
     blockId: string | null;
-    /** היעד שפעולות כתיבה (`insert`) צורכות. אטום — נמסר חזרה למנוע כמו שהוא. */
+    /** The target that write operations (`insert`) consume. Opaque — handed back to the engine as-is. */
     selectionTarget: unknown | null;
-    /** האם הבחירה ריקה (סמן בלבד). */
+    /** Whether the selection is empty (caret only). */
     empty: boolean;
 }
-/** אירוע הקלדה שהמארח מדווח למקליט ולהשלמה האוטומטית. */
+/** A typing event the host reports to the recorder and to auto-text. */
 export type TextInputEvent = {
     kind: 'insert-text';
     text: string;
@@ -39,40 +40,42 @@ export type TextInputEvent = {
     kind: 'delete-forward';
 };
 /**
- * מה שהערכה צריכה מהעורך. מימוש ל-SuperDoc v2 נמצא ב-`createSuperdocHost`;
- * לבדיקות יש כפיל בזיכרון.
+ * What the toolkit needs from the editor. The SuperDoc v2 implementation is
+ * `createSuperdocHost`; tests use an in-memory double.
  */
 export interface MacroHost {
     commands: {
-        /** האם המנוע מכיר את הפקודה. */
+        /** Whether the engine recognizes the command. */
         has(id: string): boolean;
-        /** מריצה פקודה מהקטלוג של המנוע ומחזירה תוצאה מנורמלת. */
+        /** Runs a command from the engine's catalog and returns a normalized outcome. */
         execute(id: string, payload?: unknown): Promise<MacroOutcome>;
-        /** מזהי הפקודות המוכרות, אם המארח יודע למנות אותם. */
+        /** The known command ids, when the host can enumerate them. */
         ids(): readonly string[];
     };
-    /** מכניסה טקסט במיקום הסמן (או בסוף המסמך כשאין סמן). */
+    /** Inserts text at the caret (or at the end of the document when there is no caret). */
     insertText(text: string): Promise<MacroOutcome>;
-    /** מוחקת תווים לאחור מהסמן. */
+    /** Deletes characters backwards from the caret. */
     deleteBackward(count: number): Promise<MacroOutcome>;
-    /** תצלום הבחירה הנוכחית. לעולם לא זורקת. */
+    /** Deletes characters forwards from the caret. */
+    deleteForward(count: number): Promise<MacroOutcome>;
+    /** Snapshot of the current selection. Never throws. */
     getSelection(options?: {
         includeText?: boolean;
     }): Promise<SelectionSnapshot>;
-    /** מחליפה את כל המופעים של `query` ב-`replacement`. מחזירה כמה הוחלפו. */
+    /** Replaces every occurrence of `query` with `replacement`. Returns how many were replaced. */
     replaceAll(query: string, replacement: string): Promise<{
         ok: boolean;
         replaced: number;
         message?: string;
     }>;
-    /** הטקסט המלא של גוף המסמך. `''` כשאינו זמין. */
+    /** The full text of the document body. `''` when unavailable. */
     getDocumentText(): Promise<string>;
-    /** מאזינה לכל פקודה שהמנוע מריץ (מכל מקור). מחזירה פונקציית ביטול. */
+    /** Observes every command the engine runs (from any source). Returns a dispose function. */
     onCommand(listener: (id: string, payload: unknown) => void): () => void;
-    /** מאזינה להקלדה במסמך. מחזירה פונקציית ביטול. */
+    /** Observes typing in the document. Returns a dispose function. */
     onTextInput(listener: (event: TextInputEvent) => void): () => void;
 }
-/** צעד אחד במאקרו מוקלט. JSON-serializable במלואו. */
+/** One step of a recorded macro. Fully JSON-serializable. */
 export type MacroStep = {
     type: 'command';
     id: string;
@@ -89,7 +92,7 @@ export type MacroStep = {
     type: 'delete-forward';
     count: number;
 };
-/** מאקרו מוקלט, כפי שהוא נשמר ומיובא/מיוצא. */
+/** A recorded macro, as persisted and imported/exported. */
 export interface RecordedMacro {
     version: 1;
     id: string;
@@ -99,21 +102,21 @@ export interface RecordedMacro {
     shortcut?: string;
     steps: MacroStep[];
 }
-/** מאקרו כתוב — סקריפט JavaScript שרץ מול ה-API של הערכה. */
+/** A written macro — a JavaScript script that runs against the toolkit's API. */
 export interface SavedScript {
     id: string;
     name: string;
     source: string;
     shortcut?: string;
 }
-/** קטע טקסט (Snippet / AutoText). */
+/** A text snippet (AutoText building block). */
 export interface Snippet {
     id: string;
     name: string;
-    /** תוכן הקטע. תומך במשתני `{{...}}` — ראו `renderSnippet`. */
+    /** Snippet content. Supports `{{...}}` variables — see `renderSnippet`. */
     text: string;
-    /** מילת הפעלה להשלמה אוטומטית: הקלדת המילה ואחריה רווח מחליפה אותה בתוכן. */
+    /** Auto-text trigger word: typing the word followed by a space replaces it with the content. */
     trigger?: string;
-    /** קיצור מקלדת, למשל `Ctrl+Alt+1`. */
+    /** Keyboard shortcut, e.g. `Ctrl+Alt+1`. */
     shortcut?: string;
 }

package/dist/types.js

@@ -1,9 +1,10 @@
 /**
- * החוזים המשותפים של הערכה.
+ * Shared contracts.
  *
- * `MacroHost` הוא נקודת החיבור היחידה לעורך: כל שלוש היכולות (סקריפטים,
- * מקליט, קטעי טקסט) עובדות מולו ולא מול SuperDoc ישירות. כך אפשר לבדוק את
- * הערכה עם כפיל בזיכרון, וכך מארח אחר (גרסת מנוע אחרת, עורך אחר) מתחבר
- * במימוש אחד של הממשק הזה.
+ * `MacroHost` is the single connection point to the editor: all three
+ * capabilities (scripts, recorder, snippets) work against it rather than
+ * against SuperDoc directly. That is what makes the toolkit testable with an
+ * in-memory double, and what lets another host (a different engine version,
+ * a different editor) plug in with one implementation of this interface.
  */
 export {};

package/package.json

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