@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/date-range-field/date-range-field.types.ts

@@ -0,0 +1,84 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+/**
+ * A date or date-time range value expressed as ISO-8601 local strings.
+ * Both `start` and `end` are optional so the consumer can represent partial input.
+ */
+export type DateRangeValue = {
+  /** Start of the range as an ISO-8601 local string, or undefined when not set. */
+  start: string | undefined;
+  /** End of the range as an ISO-8601 local string, or undefined when not set. */
+  end: string | undefined;
+};
+
+export type DateRangeGranularity = 'day' | 'hour' | 'minute' | 'second';
+
+/**
+ * A preset time-window option that the consumer can offer to the user.
+ */
+export type DateRangeDatePreset = {
+  /** Unique identifier for the preset. */
+  id: string;
+  /** Visible label rendered in the preset button. */
+  label: string;
+  /** Returns the date range this preset represents, evaluated at call time. */
+  resolve: () => DateRangeValue;
+};
+
+/**
+ * Props for the DateRangeField component.
+ *
+ * Scope:
+ * - Accepts and emits ISO-8601 local strings for start and end.
+ * - `granularity="day"` uses native date inputs and emits `YYYY-MM-DD`.
+ * - `granularity="hour" | "minute" | "second"` uses native datetime-local
+ *   inputs and emits `YYYY-MM-DDTHH:mm` or `YYYY-MM-DDTHH:mm:ss`.
+ * - Timezone conversion is caller-owned; browser `datetime-local` values are
+ *   local wall-clock values by design.
+ * - Sets the native inputs' min/max so the browser picker hints valid bounds
+ *   (end's min = start, start's max = end), but does NOT block out-of-order
+ *   entry. Validation feedback is the consumer's responsibility via `error`.
+ * - Supports optional consumer-supplied presets (e.g. last 7 days).
+ * - Does not own routing, query-string sync, or data fetching.
+ */
+export type DateRangeFieldProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'class' | 'children' | 'onchange'
+> & {
+  /**
+   * Unique identifier used to generate accessible IDs for labels and error
+   * regions. Optional — a stable id is generated via `$props.id()` when omitted.
+   */
+  id?: string;
+  /** Current date range value. Bindable. Both fields start undefined when unset. */
+  value?: DateRangeValue;
+  /** Visible legend rendered above the start/end inputs. */
+  label?: string;
+  /** Accessible label for the start input. Defaults to "Start date" for day granularity and "Start date and time" for datetime granularities. */
+  startLabel?: string;
+  /** Accessible label for the end input. Defaults to "End date" for day granularity and "End date and time" for datetime granularities. */
+  endLabel?: string;
+  /** Date-time precision. Defaults to day precision. */
+  granularity?: DateRangeGranularity;
+  /**
+   * Consumer-defined preset options shown above the date inputs.
+   * Each preset has a label and a resolve() function that returns a DateRangeValue.
+   * Defaults to today, yesterday-today, last-7d built-ins when omitted.
+   */
+  presets?: DateRangeDatePreset[];
+  /** When true, hides the preset buttons and shows only the date inputs. */
+  hidePresets?: boolean;
+  /** Helper text displayed below the field; wired via aria-describedby. */
+  description?: string;
+  /**
+   * Validation error message. When provided, marks both inputs as aria-invalid="true"
+   * and renders the message in a live region.
+   */
+  error?: string;
+  /** Disables the entire field including presets and date inputs. */
+  disabled?: boolean;
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+  /** Called when the user changes the date range (preset or manual input). */
+  onchange?: (value: DateRangeValue) => void;
+};

package/src/components/date-range-field/date-range-field.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/date-range-field/index.ts

@@ -0,0 +1,11 @@
+import './date-range-field.css';
+import DateRangeField from './date-range-field.svelte';
+
+export default DateRangeField;
+export type {
+  DateRangeDatePreset,
+  DateRangeFieldProps,
+  DateRangeGranularity,
+  DateRangeValue,
+} from './date-range-field.types.ts';
+export { DateRangeField };

package/src/components/description-list/description-list.schema.ts

@@ -0,0 +1,35 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    variant: {
+      enum: ['default', 'striped', 'two-column', 'narrow'],
+      description:
+        'Controls the visual layout:\n- `default`: stacked rows with visible terms.\n- `striped`: alternating row backgrounds.\n- `two-column`: term and definition share a row; collapses to stacked at narrow widths.\n- `narrow`: `<dt>` is visually hidden via `.cinder-sr-only`. Only appropriate when\n  surrounding context already labels the value. NOT a general compact mode.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class merged onto the `.cinder-description-list` root element.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'actions',
+        reason: 'function-or-snippet',
+        description:
+          'Optional snippet rendered once per row. Receives the full `DescriptionListItem` so\nconsumers can build disambiguated `aria-label` strings (e.g. `aria-label="Edit ${item.term}"`).\nAny interactive element in `actions` MUST set an unambiguous `aria-label`.',
+      },
+      {
+        name: 'items',
+        reason: 'unknown-shape',
+        required: true,
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/description-list/description-list.svelte

@@ -0,0 +1,62 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+let { items, variant = 'default', class: className, actions, ...rest } = $props();
+// The each-block keys on `item.id ?? item.term`. Two rows that share a term and
+// omit `id` collide, which Svelte surfaces as a hard `each_key_duplicate` error
+// in dev and as broken DOM reconciliation in production. Surface the misuse with
+// an actionable diagnostic before the reconciler trips, so the consumer is told
+// to supply `id` rather than left to debug a cryptic error.
+const duplicateKey = $derived.by(() => {
+    const seen = new Set();
+    for (const item of items) {
+        const key = item.id ?? item.term;
+        if (seen.has(key))
+            return key;
+        seen.add(key);
+    }
+    return undefined;
+});
+// Warn at most once per distinct duplicate key. devWarn does not dedupe, so without
+// this latch the effect would re-spam the console on every reactive update (item
+// edits, unrelated prop changes) while the duplicate persists.
+let lastWarnedDuplicateKey;
+$effect(() => {
+    if (duplicateKey === undefined) {
+        lastWarnedDuplicateKey = undefined;
+        return;
+    }
+    if (duplicateKey !== lastWarnedDuplicateKey) {
+        lastWarnedDuplicateKey = duplicateKey;
+        devWarn(`[cinder/DescriptionList] Duplicate key "${duplicateKey}". Two items share a term and no \`id\`. Provide a unique \`id\` on each DescriptionListItem to avoid broken reconciliation.`);
+    }
+});
+</script>
+
+<dl
+  {...rest}
+  class={classNames('cinder-description-list', className)}
+  data-cinder-variant={variant}
+>
+  {#each items as item (item.id ?? item.term)}
+    <div class="cinder-description-list__row">
+      <dt class={variant === 'narrow' ? 'cinder-sr-only' : undefined}>{item.term}</dt>
+      <dd>
+        <div class="cinder-description-list__definition">
+          {#if typeof item.definition === 'string'}
+            {item.definition}
+          {:else}
+            {@render item.definition()}
+          {/if}
+        </div>
+        {#if actions}
+          <div class="cinder-description-list__actions">{@render actions(item)}</div>
+        {/if}
+      </dd>
+    </div>
+  {/each}
+</dl>

package/src/components/description-list/description-list.types.ts

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/** Layout variant for the description list. */
+export type DescriptionListVariant = 'default' | 'striped' | 'two-column' | 'narrow';
+/** Term definition content: plain text or rich snippet content. */
+export type DescriptionListDefinition = string | Snippet;
+export type DescriptionListItem = {
+  /**
+   * Stable identity for keyed rendering. Falls back to `term` when omitted.
+   * Provide an explicit `id` when the list may contain duplicate terms.
+   */
+  id?: string;
+  /** The label rendered inside `<dt>`. */
+  term: string;
+  /** The value rendered inside `<dd>`. May be plain text or a snippet. */
+  definition: DescriptionListDefinition;
+};
+export type DescriptionListProps = Omit<HTMLAttributes<HTMLDListElement>, 'class'> & {
+  items: DescriptionListItem[];
+  /**
+   * Controls the visual layout:
+   * - `default`: stacked rows with visible terms.
+   * - `striped`: alternating row backgrounds.
+   * - `two-column`: term and definition share a row; collapses to stacked at narrow widths.
+   * - `narrow`: `<dt>` is visually hidden via `.cinder-sr-only`. Only appropriate when
+   *   surrounding context already labels the value. NOT a general compact mode.
+   */
+  variant?: DescriptionListVariant;
+  /** Additional class merged onto the `.cinder-description-list` root element. */
+  class?: string;
+  /**
+   * Optional snippet rendered once per row. Receives the full `DescriptionListItem` so
+   * consumers can build disambiguated `aria-label` strings (e.g. `aria-label="Edit ${item.term}"`).
+   * Any interactive element in `actions` MUST set an unambiguous `aria-label`.
+   */
+  actions?: Snippet<[DescriptionListItem]>;
+};

package/src/components/description-list/description-list.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/description-list/index.ts

@@ -0,0 +1,11 @@
+import './description-list.css';
+import DescriptionList from './description-list.svelte';
+
+export default DescriptionList;
+export type {
+  DescriptionListDefinition,
+  DescriptionListItem,
+  DescriptionListProps,
+  DescriptionListVariant,
+} from './description-list.types.ts';
+export { DescriptionList };

package/src/components/diff-statistics/diff-statistics.schema.ts

@@ -0,0 +1,42 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    added: {
+      type: 'number',
+      description: 'Number of added lines.',
+    },
+    removed: {
+      type: 'number',
+      description: 'Number of removed lines.',
+    },
+    modified: {
+      type: 'number',
+      description: 'Number of modified lines.',
+    },
+    variant: {
+      enum: ['default', 'compact'],
+      description:
+        'Layout variant. `default` shows full statistic markup; `compact` trims it\nfor tight surfaces. Distinct from `density`, which adjusts control height.',
+    },
+    density: {
+      const: 'toolbar',
+      description:
+        'Toolbar density opt-in (compact variant only). When set, pills snap to\nthe shared `--cinder-control-height-sm` tier.',
+    },
+    hideZero: {
+      type: 'boolean',
+      description: 'Hide statistics with a zero value.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-diff-statistics`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['added', 'modified', 'removed'],
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/diff-statistics/diff-statistics.svelte

@@ -0,0 +1,78 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+let { added, removed, modified, variant = 'default', density, hideZero = false, class: customClassName, ...rest } = $props();
+const total = $derived(added + removed + modified);
+const pluralize = (count, singular, plural) => count === 1 ? singular : plural;
+const addedLabel = $derived(`${added} ${pluralize(added, 'line', 'lines')} added`);
+const removedLabel = $derived(`${removed} ${pluralize(removed, 'line', 'lines')} removed`);
+const modifiedLabel = $derived(`${modified} ${pluralize(modified, 'line', 'lines')} modified`);
+const showAdded = $derived(!hideZero || added > 0);
+const showRemoved = $derived(!hideZero || removed > 0);
+const showModified = $derived(!hideZero || modified > 0);
+const hasAnyStatistics = $derived(showAdded || showRemoved || showModified);
+</script>
+
+<!--
+  Static summary, not a live region. `role="group"` + `aria-label` labels the
+  cluster ("N lines changed") while keeping the visible added/removed/modified
+  breakdown readable by assistive technology — unlike `role="img"`, which would
+  hide that inner text, and unlike `role="status"`, which would re-announce on
+  every render. Diff stats describe a fixed diff, not a value that updates in place.
+-->
+<div
+  class={classNames('cinder-diff-statistics', customClassName)}
+  data-cinder-variant={variant}
+  data-cinder-density={density === 'toolbar' ? 'toolbar' : undefined}
+  role="group"
+  aria-label={`${total} ${pluralize(total, 'line', 'lines')} changed`}
+  {...rest}
+>
+  {#if hasAnyStatistics}
+    {#if showAdded}
+      <span
+        class="cinder-diff-statistics__stat cinder-diff-statistics__stat--added"
+        aria-label={addedLabel}
+      >
+        <span class="cinder-diff-statistics__prefix" aria-hidden="true">+</span>
+        <span class="cinder-diff-statistics__value">{added}</span>
+        {#if variant === 'default'}
+          <span class="cinder-diff-statistics__label">added</span>
+        {/if}
+      </span>
+    {/if}
+
+    {#if showRemoved}
+      <span
+        class="cinder-diff-statistics__stat cinder-diff-statistics__stat--removed"
+        aria-label={removedLabel}
+      >
+        <span class="cinder-diff-statistics__prefix" aria-hidden="true">-</span>
+        <span class="cinder-diff-statistics__value">{removed}</span>
+        {#if variant === 'default'}
+          <span class="cinder-diff-statistics__label">removed</span>
+        {/if}
+      </span>
+    {/if}
+
+    {#if showModified}
+      <span
+        class="cinder-diff-statistics__stat cinder-diff-statistics__stat--modified"
+        aria-label={modifiedLabel}
+      >
+        <span class="cinder-diff-statistics__prefix" aria-hidden="true">~</span>
+        <span class="cinder-diff-statistics__value">{modified}</span>
+        {#if variant === 'default'}
+          <span class="cinder-diff-statistics__label">modified</span>
+        {/if}
+      </span>
+    {/if}
+  {:else}
+    <span class="cinder-diff-statistics__stat cinder-diff-statistics__stat--none">
+      No changes
+    </span>
+  {/if}
+</div>

package/src/components/diff-statistics/diff-statistics.types.ts

@@ -0,0 +1,32 @@
+import type { HTMLAttributes } from 'svelte/elements';
+/** Layout variant for the statistics display: `default` shows full markup, `compact` trims it. */
+export type DiffStatisticsVariant = 'default' | 'compact';
+/**
+ * Opt the compact-variant pills into the shared toolbar height
+ * (`--cinder-control-height-sm`) so they line up with sibling Button
+ * (size="sm") and SegmentedControl (density="toolbar") in editor toolbars.
+ * Only meaningful when `variant="compact"`.
+ */
+export type DiffStatisticsDensity = 'toolbar';
+export type DiffStatisticsProps = Omit<HTMLAttributes<HTMLDivElement>, 'class'> & {
+  /** Number of added lines. */
+  added: number;
+  /** Number of removed lines. */
+  removed: number;
+  /** Number of modified lines. */
+  modified: number;
+  /**
+   * Layout variant. `default` shows full statistic markup; `compact` trims it
+   * for tight surfaces. Distinct from `density`, which adjusts control height.
+   */
+  variant?: DiffStatisticsVariant;
+  /**
+   * Toolbar density opt-in (compact variant only). When set, pills snap to
+   * the shared `--cinder-control-height-sm` tier.
+   */
+  density?: DiffStatisticsDensity;
+  /** Hide statistics with a zero value. */
+  hideZero?: boolean;
+  /** Additional class names merged with `.cinder-diff-statistics`. */
+  class?: string;
+};

package/src/components/diff-statistics/diff-statistics.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/diff-statistics/index.ts

@@ -0,0 +1,10 @@
+import './diff-statistics.css';
+import DiffStatistics from './diff-statistics.svelte';
+
+export default DiffStatistics;
+export type {
+  DiffStatisticsDensity,
+  DiffStatisticsProps,
+  DiffStatisticsVariant,
+} from './diff-statistics.types.ts';
+export { DiffStatistics };

package/src/components/diff-viewer/diff-controller.svelte.ts

@@ -0,0 +1,250 @@
+/**
+ * DiffController with size-based gating (DEP-47).
+ *
+ * Manages diff computation strategy based on document size:
+ * - <20KB: Real-time diff computation
+ * - 20-100KB: Debounced (500ms) with warning badge
+ * - >100KB: Manual trigger only, shows stale diff with "Outdated" badge
+ *
+ * This protects UI responsiveness for large documents while maintaining
+ * full functionality for typical document sizes.
+ */
+import { computeLineDiff } from '@lostgradient/cinder/markdown/diff/line-diff';
+import { formatBytes } from '../../utilities/format-bytes.ts';
+const DEFAULT_OPTIONS = {
+    debouncedThreshold: 20_000, // 20KB
+    manualThreshold: 100_000, // 100KB
+    debounceMs: 500,
+};
+/**
+ * Create a diff controller with size-based gating.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createDiffController } from './diff-controller.svelte';
+ *
+ *   const controller = createDiffController();
+ *
+ *   $effect(() => controller.setOriginal(normalizedOriginal));
+ *   $effect(() => controller.setCurrent(normalizedCurrent));
+ *
+ *   const { state } = controller;
+ * </script>
+ *
+ * {#if state.warning}
+ *   <div class="warning">{state.warning}</div>
+ * {/if}
+ * ```
+ */
+export function createDiffController(options = {}) {
+    const config = { ...DEFAULT_OPTIONS, ...options };
+    // Internal state
+    let original = $state('');
+    let current = $state('');
+    let diffs = $state([]);
+    let isComputing = $state(false);
+    let lastComputeTime = $state(null);
+    let isStale = $state(false);
+    // Tracks which version of inputs was computed for cancellation logic.
+    // NOT reactive - this is internal bookkeeping only, and making it reactive
+    // would create a cycle: effect reads computeVersion → writes computeVersion → effect re-runs.
+    let computeVersion = 0;
+    // Timeouts and async handles
+    let computeTimeout = null;
+    let idleCallbackHandle = null;
+    let asyncComputeTimeout = null;
+    // Derived values
+    const documentSize = $derived(Math.max(original.length, current.length));
+    const tier = $derived.by(() => {
+        if (documentSize >= config.manualThreshold)
+            return 'manual';
+        if (documentSize >= config.debouncedThreshold)
+            return 'debounced';
+        return 'realtime';
+    });
+    const warning = $derived.by(() => {
+        if (tier === 'manual') {
+            return `Large document (${formatBytes(documentSize)}). Diff updates require manual trigger.`;
+        }
+        if (tier === 'debounced') {
+            return `Medium document (${formatBytes(documentSize)}). Diff updates are debounced.`;
+        }
+        return null;
+    });
+    /**
+     * Perform diff computation.
+     * Uses requestIdleCallback for large docs to avoid blocking UI.
+     *
+     * @param orig - Original/baseline content to diff against
+     * @param curr - Current/modified content to diff
+     * @param size - Document size in bytes (for scheduling strategy)
+     */
+    function performCompute(orig, curr, size) {
+        const version = ++computeVersion;
+        isComputing = true;
+        const doCompute = () => {
+            // Bail if inputs changed while waiting.
+            // Check both version (to detect concurrent performCompute calls) and actual content
+            // (to detect content changes that didn't trigger performCompute, e.g., in manual tier
+            // where scheduleCompute only sets isStale without calling performCompute).
+            if (computeVersion !== version || original !== orig || current !== curr) {
+                // Only clear isComputing if we're still the current version.
+                // If a newer computation has started (computeVersion !== version), it has already
+                // set isComputing = true, and we shouldn't clear it.
+                if (computeVersion === version) {
+                    isComputing = false;
+                }
+                return;
+            }
+            const start = performance.now();
+            try {
+                diffs = computeLineDiff(orig, curr);
+                lastComputeTime = performance.now() - start;
+                // Only clear stale if content still matches what we computed.
+                // This prevents a race where content changes between compute start and end.
+                if (original === orig && current === curr) {
+                    isStale = false;
+                }
+            }
+            catch (error) {
+                console.error('Diff computation failed:', error);
+                diffs = [];
+                lastComputeTime = null;
+            }
+            finally {
+                isComputing = false;
+            }
+        };
+        // Cancel any pending async computation before scheduling new one
+        if (idleCallbackHandle !== null && typeof cancelIdleCallback !== 'undefined') {
+            cancelIdleCallback(idleCallbackHandle);
+            idleCallbackHandle = null;
+        }
+        if (asyncComputeTimeout !== null) {
+            clearTimeout(asyncComputeTimeout);
+            asyncComputeTimeout = null;
+        }
+        // Use requestIdleCallback for 50KB+ to avoid blocking main thread
+        if (size > 50_000 && typeof requestIdleCallback !== 'undefined') {
+            idleCallbackHandle = requestIdleCallback(doCompute, { timeout: 2000 });
+        }
+        else if (size > 50_000) {
+            // Safari fallback - use setTimeout to yield to browser
+            asyncComputeTimeout = setTimeout(doCompute, 10);
+        }
+        else {
+            doCompute();
+        }
+    }
+    /**
+     * Schedule diff computation based on tier.
+     *
+     * @param orig - Original/baseline content
+     * @param curr - Current/modified content
+     */
+    function scheduleCompute(orig, curr) {
+        // Clear any pending computation
+        if (computeTimeout) {
+            clearTimeout(computeTimeout);
+            computeTimeout = null;
+        }
+        // Compute tier locally from passed arguments to avoid reading derived state
+        const size = Math.max(orig.length, curr.length);
+        const currentTier = size >= config.manualThreshold
+            ? 'manual'
+            : size >= config.debouncedThreshold
+                ? 'debounced'
+                : 'realtime';
+        if (currentTier === 'manual') {
+            // For manual tier, mark as stale to show "Outdated" badge.
+            // This indicates computation is needed, whether or not we have existing diffs.
+            // Users see the badge + "Compute Diff" button to understand action is required.
+            isStale = true;
+            return;
+        }
+        if (currentTier === 'debounced') {
+            // Debounce for medium documents
+            isStale = true; // Show as stale during debounce
+            computeTimeout = setTimeout(() => {
+                performCompute(orig, curr, size);
+            }, config.debounceMs);
+            return;
+        }
+        // Real-time for small documents
+        performCompute(orig, curr, size);
+    }
+    // Watch for content changes and schedule diff computation.
+    // Dependencies are explicit via function arguments - Svelte tracks `original` and `current`
+    // because they're read to be passed as arguments.
+    $effect(() => {
+        scheduleCompute(original, current);
+        return () => {
+            if (computeTimeout) {
+                clearTimeout(computeTimeout);
+                computeTimeout = null;
+            }
+            if (idleCallbackHandle !== null && typeof cancelIdleCallback !== 'undefined') {
+                cancelIdleCallback(idleCallbackHandle);
+                idleCallbackHandle = null;
+            }
+            if (asyncComputeTimeout !== null) {
+                clearTimeout(asyncComputeTimeout);
+                asyncComputeTimeout = null;
+            }
+        };
+    });
+    return {
+        get state() {
+            return {
+                tier,
+                diffs,
+                isComputing,
+                lastComputeTime,
+                documentSize,
+                warning,
+                isStale,
+            };
+        },
+        get original() {
+            return original;
+        },
+        set original(value) {
+            original = value;
+        },
+        get current() {
+            return current;
+        },
+        set current(value) {
+            current = value;
+        },
+        setOriginal(value) {
+            original = value;
+        },
+        setCurrent(value) {
+            current = value;
+        },
+        triggerCompute() {
+            // Don't set isStale = false here - for large docs (>50KB), performCompute
+            // schedules async work via requestIdleCallback/setTimeout. If content changes
+            // before the callback runs, we'd incorrectly show the diff as up-to-date.
+            // Instead, doCompute() sets isStale = false after verifying content matches.
+            const size = Math.max(original.length, current.length);
+            performCompute(original, current, size);
+        },
+        destroy() {
+            if (computeTimeout) {
+                clearTimeout(computeTimeout);
+                computeTimeout = null;
+            }
+            if (idleCallbackHandle !== null && typeof cancelIdleCallback !== 'undefined') {
+                cancelIdleCallback(idleCallbackHandle);
+                idleCallbackHandle = null;
+            }
+            if (asyncComputeTimeout !== null) {
+                clearTimeout(asyncComputeTimeout);
+                asyncComputeTimeout = null;
+            }
+        },
+    };
+}