@rtif-sdk/web 1.0.0

package/dist/mark-renderer.js

@@ -0,0 +1,210 @@
+/**
+ * Mark renderer registry — maps mark types to DOM rendering functions.
+ *
+ * The renderer consults this registry when creating span elements to apply
+ * visual mark effects (CSS classes, inline styles, data attributes).
+ * Built-in renderers handle bold, italic, underline, strikethrough, code,
+ * and link. Plugins can register custom renderers for additional marks.
+ *
+ * @module
+ */
+/**
+ * Create a new mark renderer registry.
+ *
+ * @returns An empty registry ready for renderer registration
+ *
+ * @example
+ * ```ts
+ * const registry = createMarkRendererRegistry();
+ * registry.register('bold', boldRenderer);
+ * registry.register('italic', italicRenderer);
+ * ```
+ */
+export function createMarkRendererRegistry() {
+    const renderers = new Map();
+    const replacers = new Map();
+    return {
+        register(markType, renderer) {
+            renderers.set(markType, renderer);
+        },
+        get(markType) {
+            return renderers.get(markType);
+        },
+        isAtomic(markType) {
+            const renderer = renderers.get(markType);
+            return renderer?.atomic === true;
+        },
+        isExclusive(markType) {
+            const renderer = renderers.get(markType);
+            return renderer?.exclusive === true;
+        },
+        applyAll(el, marks) {
+            if (!marks)
+                return;
+            for (const [key, value] of Object.entries(marks)) {
+                if (value == null)
+                    continue;
+                const renderer = renderers.get(key);
+                if (renderer) {
+                    renderer.apply(el, value);
+                }
+            }
+        },
+        registerReplacer(markType, replacer) {
+            replacers.set(markType, replacer);
+        },
+        getReplacer(markType) {
+            return replacers.get(markType);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Built-in mark renderers
+// ---------------------------------------------------------------------------
+/**
+ * Built-in renderer for the `bold` mark.
+ * Adds the `rtif-bold` CSS class to the span element.
+ */
+export const boldRenderer = {
+    apply(el) {
+        el.classList.add('rtif-bold');
+    },
+};
+/**
+ * Built-in renderer for the `italic` mark.
+ * Adds the `rtif-italic` CSS class to the span element.
+ */
+export const italicRenderer = {
+    apply(el) {
+        el.classList.add('rtif-italic');
+    },
+};
+/**
+ * Built-in renderer for the `underline` mark.
+ * Adds the `rtif-underline` CSS class to the span element.
+ */
+export const underlineRenderer = {
+    apply(el) {
+        el.classList.add('rtif-underline');
+    },
+};
+/**
+ * Built-in renderer for the `strikethrough` mark.
+ * Adds the `rtif-strikethrough` CSS class to the span element.
+ */
+export const strikethroughRenderer = {
+    apply(el) {
+        el.classList.add('rtif-strikethrough');
+    },
+};
+/**
+ * Built-in renderer for the `code` mark.
+ * Adds the `rtif-code` CSS class to the span element.
+ */
+export const codeRenderer = {
+    apply(el) {
+        el.classList.add('rtif-code');
+    },
+};
+/**
+ * Built-in renderer for the `link` mark.
+ * Adds the `rtif-link` CSS class and sets `data-link-href` attribute.
+ *
+ * @example
+ * ```ts
+ * // Mark value: { href: "https://example.com", title: "Example" }
+ * // Result: <span class="rtif-link" data-link-href="https://example.com" title="Example">
+ * ```
+ */
+export const linkRenderer = {
+    apply(el, value) {
+        el.classList.add('rtif-link');
+        if (typeof value === 'object' && value !== null) {
+            const linkData = value;
+            if (typeof linkData.href === 'string') {
+                el.setAttribute('data-link-href', linkData.href);
+            }
+            if (typeof linkData.title === 'string') {
+                el.setAttribute('title', linkData.title);
+            }
+        }
+    },
+    exclusive: true,
+};
+/**
+ * Built-in renderer for the `color` mark.
+ * Sets the `color` CSS style on the span element.
+ *
+ * @example
+ * ```ts
+ * // Mark value: "#ff0000"
+ * // Result: <span style="color: #ff0000;">
+ * ```
+ */
+export const colorRenderer = {
+    apply(el, value) {
+        if (typeof value === 'string') {
+            el.style.color = value;
+        }
+    },
+};
+/**
+ * Built-in renderer for the `fontSize` mark.
+ * Sets the `font-size` CSS style on the span element in pixels.
+ *
+ * @example
+ * ```ts
+ * // Mark value: 16
+ * // Result: <span style="font-size: 16px;">
+ * ```
+ */
+export const fontSizeRenderer = {
+    apply(el, value) {
+        if (typeof value === 'number') {
+            el.style.fontSize = `${value}px`;
+        }
+    },
+};
+/**
+ * Built-in renderer for the `fontFamily` mark.
+ * Sets the `font-family` CSS style on the span element.
+ *
+ * @example
+ * ```ts
+ * // Mark value: "Georgia, serif"
+ * // Result: <span style="font-family: Georgia, serif;">
+ * ```
+ */
+export const fontFamilyRenderer = {
+    apply(el, value) {
+        if (typeof value === 'string') {
+            el.style.fontFamily = value;
+        }
+    },
+};
+/**
+ * Register all built-in mark renderers into a registry.
+ *
+ * Registers renderers for: bold, italic, underline, strikethrough, code,
+ * link, color, fontSize, fontFamily.
+ *
+ * @param registry - The registry to populate
+ *
+ * @example
+ * ```ts
+ * const registry = createMarkRendererRegistry();
+ * registerBuiltinRenderers(registry);
+ * ```
+ */
+export function registerBuiltinRenderers(registry) {
+    registry.register('bold', boldRenderer);
+    registry.register('italic', italicRenderer);
+    registry.register('underline', underlineRenderer);
+    registry.register('strikethrough', strikethroughRenderer);
+    registry.register('code', codeRenderer);
+    registry.register('link', linkRenderer);
+    registry.register('color', colorRenderer);
+    registry.register('fontSize', fontSizeRenderer);
+    registry.register('fontFamily', fontFamilyRenderer);
+}
+//# sourceMappingURL=mark-renderer.js.map

package/dist/mark-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mark-renderer.js","sourceRoot":"","sources":["../src/mark-renderer.ts"],"names":[],"mappings":"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"}

package/dist/perf.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Performance instrumentation for the RTIF web editor.
+ *
+ * Provides timing helpers built on the Performance API (`performance.mark()` /
+ * `performance.measure()`) to measure each phase of the editor operation cycle:
+ * dispatch, DOM reconciliation, and selection sync.
+ *
+ * When the Performance API is unavailable (e.g. SSR environments), all timing
+ * methods are no-ops and `collect()` returns zero-valued metrics.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Timing metrics for a single editor operation cycle.
+ *
+ * @example
+ * ```ts
+ * const metrics = perf.collect();
+ * console.log(`Total: ${metrics.totalMs}ms`);
+ * ```
+ */
+export interface PerfMetrics {
+    /** Time spent in the engine dispatch (beforeApply + apply + afterApply) */
+    readonly dispatchMs: number;
+    /** Time spent reconciling the DOM to match the new document state */
+    readonly reconcileMs: number;
+    /** Time spent restoring the DOM selection after reconciliation */
+    readonly selectionSyncMs: number;
+    /** Wall-clock time from dispatch start to the last completed phase */
+    readonly totalMs: number;
+}
+/**
+ * Observer that receives timing data after each editor operation cycle.
+ *
+ * @example
+ * ```ts
+ * const observer: PerfObserver = {
+ *   onMeasure(metrics) {
+ *     if (metrics.totalMs > 16) {
+ *       console.warn('Slow frame:', metrics);
+ *     }
+ *   },
+ * };
+ * ```
+ */
+export interface PerfObserver {
+    /** Called after each `collect()` with the computed metrics */
+    onMeasure(metrics: PerfMetrics): void;
+}
+/**
+ * Instrumentation handle for timing editor operation phases.
+ *
+ * @example
+ * ```ts
+ * const perf = createPerfInstrumentation();
+ * perf.markDispatchStart();
+ * engine.dispatch(ops);
+ * perf.markDispatchEnd();
+ * perf.markReconcileStart();
+ * reconcile(root, prev, next);
+ * perf.markReconcileEnd();
+ * perf.markSelectionSyncStart();
+ * setDomSelection(root, doc, sel);
+ * perf.markSelectionSyncEnd();
+ * const metrics = perf.collect();
+ * ```
+ */
+export interface PerfInstrumentation {
+    /** Mark the start of the engine dispatch phase */
+    markDispatchStart(): void;
+    /** Mark the end of the engine dispatch phase */
+    markDispatchEnd(): void;
+    /** Mark the start of DOM reconciliation */
+    markReconcileStart(): void;
+    /** Mark the end of DOM reconciliation */
+    markReconcileEnd(): void;
+    /** Mark the start of selection synchronization */
+    markSelectionSyncStart(): void;
+    /** Mark the end of selection synchronization */
+    markSelectionSyncEnd(): void;
+    /**
+     * Collect all marks, compute metrics, call observer (if set), and clean up.
+     *
+     * @returns The computed timing metrics for this cycle
+     */
+    collect(): PerfMetrics;
+    /**
+     * Set or clear the observer that receives metrics after each `collect()`.
+     *
+     * @param observer - The observer, or `null` to remove
+     */
+    setObserver(observer: PerfObserver | null): void;
+    /** Destroy the instrumentation and prevent further timing */
+    destroy(): void;
+}
+/**
+ * Create a performance instrumentation instance for timing editor operation
+ * phases.
+ *
+ * Uses `performance.mark()` / `performance.measure()` internally. When the
+ * Performance API is not available (SSR, Web Workers without it), all methods
+ * are safe no-ops and `collect()` returns zero-valued metrics.
+ *
+ * Each instrumentation instance maintains an internal counter so mark names
+ * never collide across cycles or across multiple instances.
+ *
+ * @returns A new {@link PerfInstrumentation} instance
+ *
+ * @example
+ * ```ts
+ * const perf = createPerfInstrumentation();
+ * perf.setObserver({
+ *   onMeasure(m) { console.log('dispatch', m.dispatchMs, 'ms'); },
+ * });
+ * perf.markDispatchStart();
+ * // ... engine dispatch ...
+ * perf.markDispatchEnd();
+ * const metrics = perf.collect();
+ * ```
+ */
+export declare function createPerfInstrumentation(): PerfInstrumentation;
+/**
+ * Wrap a synchronous function call with `performance.mark()` timing.
+ *
+ * Places `rtif:<label>:start` and `rtif:<label>:end` marks around the
+ * function execution, and measures the duration. If `perf` is `undefined`,
+ * the function is called without any instrumentation overhead.
+ *
+ * The function's return value is passed through unchanged. If the function
+ * throws, the end mark is still placed before the error propagates.
+ *
+ * @param label - A short descriptive label for the timing (e.g. `"reconcile"`)
+ * @param fn - The function to time
+ * @param perf - Optional instrumentation instance; if omitted, no timing occurs
+ * @returns The return value of `fn()`
+ *
+ * @example
+ * ```ts
+ * const doc = withPerfTiming('reconcile', () => {
+ *   return reconcile(root, prev, next);
+ * }, perf);
+ * ```
+ */
+export declare function withPerfTiming<T>(label: string, fn: () => T, perf?: PerfInstrumentation): T;
+//# sourceMappingURL=perf.d.ts.map

package/dist/perf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,iBAAiB,IAAI,IAAI,CAAC;IAC1B,gDAAgD;IAChD,eAAe,IAAI,IAAI,CAAC;IACxB,2CAA2C;IAC3C,kBAAkB,IAAI,IAAI,CAAC;IAC3B,yCAAyC;IACzC,gBAAgB,IAAI,IAAI,CAAC;IACzB,kDAAkD;IAClD,sBAAsB,IAAI,IAAI,CAAC;IAC/B,gDAAgD;IAChD,oBAAoB,IAAI,IAAI,CAAC;IAC7B;;;;OAIG;IACH,OAAO,IAAI,WAAW,CAAC;IACvB;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC;IACjD,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;CACjB;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,IAAI,mBAAmB,CA+J/D;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,CAAC,EACX,IAAI,CAAC,EAAE,mBAAmB,GACzB,CAAC,CAwBH"}

package/dist/perf.js

@@ -0,0 +1,260 @@
+/**
+ * Performance instrumentation for the RTIF web editor.
+ *
+ * Provides timing helpers built on the Performance API (`performance.mark()` /
+ * `performance.measure()`) to measure each phase of the editor operation cycle:
+ * dispatch, DOM reconciliation, and selection sync.
+ *
+ * When the Performance API is unavailable (e.g. SSR environments), all timing
+ * methods are no-ops and `collect()` returns zero-valued metrics.
+ *
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const ZERO_METRICS = Object.freeze({
+    dispatchMs: 0,
+    reconcileMs: 0,
+    selectionSyncMs: 0,
+    totalMs: 0,
+});
+const PREFIX = 'rtif:';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Check whether the `Performance` API is available in the current environment.
+ */
+function hasPerformanceApi() {
+    return (typeof performance !== 'undefined' &&
+        typeof performance.mark === 'function' &&
+        typeof performance.measure === 'function');
+}
+/**
+ * Safely measure between two named marks, returning the duration in ms.
+ * Returns 0 if either mark is missing or the measure fails.
+ */
+function safeMeasure(measureName, startMark, endMark) {
+    try {
+        const entry = performance.measure(measureName, startMark, endMark);
+        return entry.duration;
+    }
+    catch {
+        return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a performance instrumentation instance for timing editor operation
+ * phases.
+ *
+ * Uses `performance.mark()` / `performance.measure()` internally. When the
+ * Performance API is not available (SSR, Web Workers without it), all methods
+ * are safe no-ops and `collect()` returns zero-valued metrics.
+ *
+ * Each instrumentation instance maintains an internal counter so mark names
+ * never collide across cycles or across multiple instances.
+ *
+ * @returns A new {@link PerfInstrumentation} instance
+ *
+ * @example
+ * ```ts
+ * const perf = createPerfInstrumentation();
+ * perf.setObserver({
+ *   onMeasure(m) { console.log('dispatch', m.dispatchMs, 'ms'); },
+ * });
+ * perf.markDispatchStart();
+ * // ... engine dispatch ...
+ * perf.markDispatchEnd();
+ * const metrics = perf.collect();
+ * ```
+ */
+export function createPerfInstrumentation() {
+    const available = hasPerformanceApi();
+    let destroyed = false;
+    let observer = null;
+    let counter = 0;
+    // Current cycle's mark names (null when not yet placed)
+    let dispatchStartName = null;
+    let dispatchEndName = null;
+    let reconcileStartName = null;
+    let reconcileEndName = null;
+    let selectionSyncStartName = null;
+    let selectionSyncEndName = null;
+    // Track all mark names placed in the current cycle for cleanup
+    let currentCycleMarks = [];
+    function nextId() {
+        return counter++;
+    }
+    function placeMark(phase, edge) {
+        if (destroyed || !available)
+            return null;
+        const name = `${PREFIX}${phase}:${edge}:${nextId()}`;
+        performance.mark(name);
+        currentCycleMarks.push(name);
+        return name;
+    }
+    function cleanup(measureNames) {
+        if (!available)
+            return;
+        for (const name of currentCycleMarks) {
+            try {
+                performance.clearMarks(name);
+            }
+            catch {
+                // Ignore — mark may have already been cleaned up
+            }
+        }
+        for (const name of measureNames) {
+            try {
+                performance.clearMeasures(name);
+            }
+            catch {
+                // Ignore
+            }
+        }
+        currentCycleMarks = [];
+    }
+    function reset() {
+        dispatchStartName = null;
+        dispatchEndName = null;
+        reconcileStartName = null;
+        reconcileEndName = null;
+        selectionSyncStartName = null;
+        selectionSyncEndName = null;
+    }
+    return {
+        markDispatchStart() {
+            dispatchStartName = placeMark('dispatch', 'start');
+        },
+        markDispatchEnd() {
+            dispatchEndName = placeMark('dispatch', 'end');
+        },
+        markReconcileStart() {
+            reconcileStartName = placeMark('reconcile', 'start');
+        },
+        markReconcileEnd() {
+            reconcileEndName = placeMark('reconcile', 'end');
+        },
+        markSelectionSyncStart() {
+            selectionSyncStartName = placeMark('selectionSync', 'start');
+        },
+        markSelectionSyncEnd() {
+            selectionSyncEndName = placeMark('selectionSync', 'end');
+        },
+        collect() {
+            if (destroyed || !available) {
+                const m = { ...ZERO_METRICS };
+                if (observer)
+                    observer.onMeasure(m);
+                reset();
+                return m;
+            }
+            const measureNames = [];
+            const id = nextId();
+            // Measure each phase
+            let dispatchMs = 0;
+            if (dispatchStartName && dispatchEndName) {
+                const mn = `${PREFIX}dispatch:${id}`;
+                dispatchMs = safeMeasure(mn, dispatchStartName, dispatchEndName);
+                measureNames.push(mn);
+            }
+            let reconcileMs = 0;
+            if (reconcileStartName && reconcileEndName) {
+                const mn = `${PREFIX}reconcile:${id}`;
+                reconcileMs = safeMeasure(mn, reconcileStartName, reconcileEndName);
+                measureNames.push(mn);
+            }
+            let selectionSyncMs = 0;
+            if (selectionSyncStartName && selectionSyncEndName) {
+                const mn = `${PREFIX}selectionSync:${id}`;
+                selectionSyncMs = safeMeasure(mn, selectionSyncStartName, selectionSyncEndName);
+                measureNames.push(mn);
+            }
+            // Total: from dispatch start to the last available end mark
+            let totalMs = 0;
+            const totalStart = dispatchStartName;
+            const totalEnd = selectionSyncEndName ?? reconcileEndName ?? dispatchEndName;
+            if (totalStart && totalEnd) {
+                const mn = `${PREFIX}total:${id}`;
+                totalMs = safeMeasure(mn, totalStart, totalEnd);
+                measureNames.push(mn);
+            }
+            const metrics = {
+                dispatchMs,
+                reconcileMs,
+                selectionSyncMs,
+                totalMs,
+            };
+            // Clean up all marks and measures from this cycle
+            cleanup(measureNames);
+            reset();
+            if (observer) {
+                observer.onMeasure(metrics);
+            }
+            return metrics;
+        },
+        setObserver(obs) {
+            observer = obs;
+        },
+        destroy() {
+            destroyed = true;
+            reset();
+            currentCycleMarks = [];
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// withPerfTiming utility
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a synchronous function call with `performance.mark()` timing.
+ *
+ * Places `rtif:<label>:start` and `rtif:<label>:end` marks around the
+ * function execution, and measures the duration. If `perf` is `undefined`,
+ * the function is called without any instrumentation overhead.
+ *
+ * The function's return value is passed through unchanged. If the function
+ * throws, the end mark is still placed before the error propagates.
+ *
+ * @param label - A short descriptive label for the timing (e.g. `"reconcile"`)
+ * @param fn - The function to time
+ * @param perf - Optional instrumentation instance; if omitted, no timing occurs
+ * @returns The return value of `fn()`
+ *
+ * @example
+ * ```ts
+ * const doc = withPerfTiming('reconcile', () => {
+ *   return reconcile(root, prev, next);
+ * }, perf);
+ * ```
+ */
+export function withPerfTiming(label, fn, perf) {
+    if (!perf || !hasPerformanceApi()) {
+        return fn();
+    }
+    const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    const startName = `${PREFIX}${label}:start:${id}`;
+    const endName = `${PREFIX}${label}:end:${id}`;
+    performance.mark(startName);
+    try {
+        return fn();
+    }
+    finally {
+        performance.mark(endName);
+        try {
+            const measureName = `${PREFIX}${label}:${id}`;
+            performance.measure(measureName, startName, endName);
+            performance.clearMarks(startName);
+            performance.clearMarks(endName);
+            performance.clearMeasures(measureName);
+        }
+        catch {
+            // Ignore measurement cleanup errors
+        }
+    }
+}
+//# sourceMappingURL=perf.js.map

package/dist/perf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.js","sourceRoot":"","sources":["../src/perf.ts"],"names":[],"mappings":"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"}