superdoc-macros 0.7.0 → 0.7.1

package/README.md

@@ -87,7 +87,9 @@ If you must waive isolation (e.g. a CSP that blocks `srcdoc`), switch to the dir
 ## 2. Macro recorder
 
 ```ts
-kit.startRecording();
+if (!kit.startRecording()) {
+  throw new Error('A macro is running or an unsaved recording is pending');
+}
 // the user works normally: typing, formatting, lists...
 const recording = kit.stopRecording('Standard intro', 'Ctrl+Alt+1');
 
@@ -97,6 +99,8 @@ await kit.replayRecording(recording.id);
 
 The recorder captures **commands and typing**, not caret positions — exactly like Word's recorder: replay applies wherever the caret stands. Consecutive keystrokes coalesce into one step, `undo`/`redo` are not recorded (configurable via `RecorderOptions`), and recordings persist as clean JSON that can be exported and shared. `updateRecording({id, name?, shortcut?})` renames a recording or edits its shortcut.
 
+Finalization is loss-aware. A command payload that cannot be stored faithfully is reported instead of silently omitted; `stopRecording()` keeps the stopped capture pending until it is saved or explicitly cancelled. A mixed capture requires `{ allowIncomplete: true }` after the host has obtained user consent, while a capture containing no replayable step is rejected as `recording-uncapturable`. Storage, capacity, and validation failures are retryable: fix the problem and call `stopRecording()` again. Starting a new recording while one is pending is rejected, preventing accidental loss.
+
 ## 3. Snippets and auto-text
 
 ```ts

package/dist/manager.d.ts

@@ -108,13 +108,19 @@ export declare class MacroKit {
     runSource(source: string): Promise<MacroRunResult>;
     get isRecording(): boolean;
     get recordedStepCount(): number;
-    startRecording(): void;
+    /**
+     * Starts a fresh recording. Returns false instead of overwriting an active
+     * or stopped-but-unsaved capture, or while another macro is running.
+     */
+    startRecording(): boolean;
     /**
      * Stops and saves. `null` when no step was recorded — there is nothing to
      * save.
      *
      * Throws — with the stopped recording **retained for retry** (call again;
      * `cancelRecording` is the explicit way to drop it) — when:
+     * - `recording-uncapturable`: every action was uncapturable, so even an
+     *   explicitly incomplete save would create an empty macro.
      * - `recording-incomplete`: some actions could not be captured (e.g. an
      *   inserted image, whose payload is the whole file). Saving that as-is
      *   would present a macro that replays less than what the user did, so it

package/dist/manager.js

@@ -223,10 +223,15 @@ export class MacroKit {
     get recordedStepCount() {
         return this.recorder.stepCount;
     }
+    /**
+     * Starts a fresh recording. Returns false instead of overwriting an active
+     * or stopped-but-unsaved capture, or while another macro is running.
+     */
     startRecording() {
-        if (this.running)
-            return;
+        if (this.running || this.recorder.recording || this.recorder.hasPending)
+            return false;
         this.recorder.start();
+        return this.recorder.recording;
     }
     /**
      * Stops and saves. `null` when no step was recorded — there is nothing to
@@ -234,6 +239,8 @@ export class MacroKit {
      *
      * Throws — with the stopped recording **retained for retry** (call again;
      * `cancelRecording` is the explicit way to drop it) — when:
+     * - `recording-uncapturable`: every action was uncapturable, so even an
+     *   explicitly incomplete save would create an empty macro.
      * - `recording-incomplete`: some actions could not be captured (e.g. an
      *   inserted image, whose payload is the whole file). Saving that as-is
      *   would present a macro that replays less than what the user did, so it
@@ -243,19 +250,27 @@ export class MacroKit {
      * - a persistence failure (quota, oversized state).
      */
     stopRecording(name, shortcut, options = {}) {
-        this.requireValidShortcut(shortcut);
-        this.requireItemLimits({ name, shortcut });
-        this.requireRoom(this.state.recordings);
+        // Stop first. Every failure below must leave the recorder inactive and
+        // its snapshot retryable. Checking capacity before stop() used to leave a
+        // manual recording active behind a stopped UI, and could lose an
+        // auto-stopped recording on the next start.
         const pending = this.recorder.stop();
         const { steps, truncated } = splitOversizedSteps(pending.steps);
         if (truncated)
             throw new MacroError(macroMessages().recordingTooLarge, 'recording-too-large');
+        const commandIds = [...new Set(pending.warnings.map((warning) => warning.commandId))].join(', ');
+        if (pending.warnings.length > 0 && steps.length === 0) {
+            const messages = macroMessages();
+            throw new MacroError(messages.recordingUncapturable?.(commandIds) ?? messages.recordingIncomplete(commandIds), 'recording-uncapturable');
+        }
         if (steps.length === 0) {
             this.recorder.discard();
             return null;
         }
+        this.requireValidShortcut(shortcut);
+        this.requireItemLimits({ name, shortcut });
+        this.requireRoom(this.state.recordings);
         if (pending.warnings.length > 0 && !options.allowIncomplete) {
-            const commandIds = [...new Set(pending.warnings.map((warning) => warning.commandId))].join(', ');
             throw new MacroError(macroMessages().recordingIncomplete(commandIds), 'recording-incomplete');
         }
         const recording = {

package/dist/messages.d.ts

@@ -43,6 +43,12 @@ export interface MacroMessages {
     saveFailed: string;
     recordingTooLarge: string;
     recordingIncomplete: (commandIds: string) => string;
+    /**
+     * No usable step was captured; saving with allowIncomplete would create an
+     * empty macro. Optional for source compatibility with existing full locale
+     * objects compiled against 0.7.0.
+     */
+    recordingUncapturable?: (commandIds: string) => string;
     shortcutInvalid: string;
     shortcutNeedsModifier: string;
     shortcutReserved: string;

package/dist/messages.js

@@ -43,6 +43,7 @@ export const ENGLISH_MESSAGES = {
     saveFailed: 'Saving failed — the change was not applied',
     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})`,
     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',
@@ -83,6 +84,7 @@ export const HEBREW_MESSAGES = {
     saveFailed: 'השמירה נכשלה — השינוי לא הוחל',
     recordingTooLarge: 'ההקלטה גדולה מכדי להישמר',
     recordingIncomplete: (commandIds) => `בהקלטה חסרות פעולות שאינן ניתנות להקלטה (${commandIds})`,
+    recordingUncapturable: (commandIds) => `ההקלטה מכילה רק פעולות שאינן ניתנות להקלטה (${commandIds})`,
     shortcutInvalid: 'קיצור לא תקין — הצורה הנדרשת היא למשל Ctrl+Alt+M',
     shortcutNeedsModifier: 'קיצור חייב לכלול Ctrl,‏ Alt או Meta',
     shortcutReserved: 'הקיצור הזה שמור לעורך',

package/dist/recorder/recorder.d.ts

@@ -80,6 +80,13 @@ export declare class MacroRecorder {
     applyAutoTextExpansion(consumed: number, replacement: string): void;
     private teardown;
     private push;
+    private addWarning;
+    /**
+     * Warnings are part of the stopped snapshot just like steps. Counting both
+     * prevents a warning-only recording from growing without bound while never
+     * reaching the ordinary step cap.
+     */
+    private maybeAutoStop;
     /**
      * Records a programmatic insertion the host will not report as typing —
      * e.g. a snippet expanded from a button or shortcut, which writes through

package/dist/recorder/recorder.js

@@ -146,12 +146,27 @@ export class MacroRecorder {
     }
     push(step) {
         this.steps.push(step);
-        if (this.steps.length >= this.maxSteps) {
-            // The cap stops the *listening*, not the data: the steps stay for
-            // stop() to collect, and the owner is told the recording ended.
-            this.teardown();
-            this.onAutoStop?.();
-        }
+        this.maybeAutoStop();
+    }
+    addWarning(warning) {
+        this.warnings.push(warning);
+        this.maybeAutoStop();
+    }
+    /**
+     * Warnings are part of the stopped snapshot just like steps. Counting both
+     * prevents a warning-only recording from growing without bound while never
+     * reaching the ordinary step cap.
+     */
+    maybeAutoStop() {
+        if (!this.active)
+            return;
+        if (this.steps.length + this.warnings.length < this.maxSteps)
+            return;
+        this.teardown();
+        this.pending = { steps: this.steps, warnings: this.warnings };
+        this.steps = [];
+        this.warnings = [];
+        this.onAutoStop?.();
     }
     /**
      * Records a programmatic insertion the host will not report as typing —
@@ -184,15 +199,15 @@ export class MacroRecorder {
             json = JSON.stringify(payload);
         }
         catch {
-            this.warnings.push({ commandId: id, reason: 'payload-not-serializable' });
+            this.addWarning({ commandId: id, reason: 'payload-not-serializable' });
             return;
         }
         if (typeof json !== 'string') {
-            this.warnings.push({ commandId: id, reason: 'payload-not-serializable' });
+            this.addWarning({ commandId: id, reason: 'payload-not-serializable' });
             return;
         }
         if (json.length > IMPORT_LIMITS.maxPayloadLength) {
-            this.warnings.push({ commandId: id, reason: 'payload-too-large' });
+            this.addWarning({ commandId: id, reason: 'payload-too-large' });
             return;
         }
         this.push({ type: 'command', id, payload: JSON.parse(json) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superdoc-macros",
-  "version": "0.7.0",
+  "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.",
   "license": "MIT",
   "type": "module",