@yewdiel21/motion-kit 0.17.0 → 0.19.0

package/src/components/signature-pad/engine.ts

@@ -1,437 +1,550 @@
-import { gsap, EASE, registerMotion } from '../../core/gsap';
-import { reduced } from '../../core/reduced';
-import { createScope } from '../../core/scope';
-import { inert, type Instance } from '../../core/types';
-
-/** Coordinates are fractions of the drawing area, independent of its size. */
-export interface SignaturePoint { x: number; y: number }
-export interface SignatureStroke { points: SignaturePoint[]; color: string; width: number }
-export interface SignatureData { version: 1; strokes: SignatureStroke[] }
-export type SignaturePadChangeReason = 'draw' | 'undo' | 'redo' | 'clear' | 'import' | 'reset';
-export interface SignaturePadChangeDetail {
-  data: SignatureData;
-  reason: SignaturePadChangeReason;
-  isEmpty: boolean;
-  canUndo: boolean;
-  canRedo: boolean;
-}
-export interface SignatureExportOptions {
-  /** CSS pixels; default is the current drawing area, or 640 × 240 before layout. */
-  width?: number;
-  height?: number;
-  /** Omit for transparency. Accepts a literal CSS color, without variables or URLs. */
-  background?: string;
-}
-export interface SignaturePNGOptions extends SignatureExportOptions {
-  /** Raster resolution multiplier, clamped to 1–4 (default 2). */
-  scale?: number;
-}
-export interface SignaturePadOptions {
-  data?: SignatureData;
-  label?: string;
-  hint?: string;
-  placeholder?: string;
-  /** Literal CSS ink color; defaults to the theme's text color. */
-  color?: string;
-  /** Ink width in CSS pixels, default 2.4. */
-  width?: number;
-  disabled?: boolean;
-  readOnly?: boolean;
-  /** Include native undo, redo and clear buttons (default true). */
-  toolbar?: boolean;
-  /** Adds a hidden input containing the versioned JSON data. */
-  name?: string;
-  /** Maximum undo steps, clamped to 1–100 (default 50). */
-  historyLimit?: number;
-  onChange?: (data: SignatureData, detail: SignaturePadChangeDetail) => void;
-}
-export interface SignaturePadInstance extends Instance {
-  readonly data: SignatureData;
-  readonly isEmpty: boolean;
-  readonly canUndo: boolean;
-  readonly canRedo: boolean;
-  undo(): void;
-  redo(): void;
-  clear(): void;
-  /** Invalid input returns false and leaves the signature untouched. Import resets history. */
-  importData(data: unknown, notify?: boolean): boolean;
-  exportData(): SignatureData;
-  exportSVG(options?: SignatureExportOptions): string;
-  /** Returns null when rasterization is unavailable or fails. */
-  exportPNG(options?: SignaturePNGOptions): Promise<Blob | null>;
-  setDisabled(disabled: boolean): void;
-  setReadOnly(readOnly: boolean): void;
-}
-
-const SVG_NS = 'http://www.w3.org/2000/svg';
-const MAX_STROKES = 500;
-const MAX_POINTS = 50_000;
-const emptyData = (): SignatureData => ({ version: 1, strokes: [] });
-const cloneStrokes = (strokes: SignatureStroke[]) => strokes.map((stroke) => ({ ...stroke, points: stroke.points.map((point) => ({ ...point })) }));
-const sameStrokes = (left: SignatureStroke[], right: SignatureStroke[]) => left.length === right.length && left.every((stroke, index) => {
-  const other = right[index]!;
-  return stroke.color === other.color && stroke.width === other.width && stroke.points.length === other.points.length && stroke.points.every((point, index) => point.x === other.points[index]!.x && point.y === other.points[index]!.y);
-});
-const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
-const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
-
-/** Reject paint servers, CSS variables and markup so exports stay self-contained. */
-function validColor(value: unknown): value is string {
-  if (typeof value !== 'string' || value.length > 100) return false;
-  if (/^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.test(value)) return true;
-  if (!/^(?:rgba?|hsla?)\([\d\s.,%/+\-degratun]+\)$/i.test(value) && !/^[a-z]+$/i.test(value)) return false;
-  if (/^(?:inherit|initial|unset|revert|revertlayer|currentcolor)$/i.test(value)) return false;
-  if (typeof document === 'undefined') return /^(?:black|white|transparent)$/i.test(value);
-  const probe = document.createElement('span');
-  probe.style.color = value;
-  return probe.style.color !== '';
-}
-
-function validatedData(value: unknown): SignatureData | null {
-  if (!value || typeof value !== 'object') return null;
-  const data = value as Record<string, unknown>;
-  if (data.version !== 1 || !Array.isArray(data.strokes) || data.strokes.length > MAX_STROKES) return null;
-  const strokes: SignatureStroke[] = [];
-  let count = 0;
-  for (const candidate of data.strokes) {
-    if (!candidate || typeof candidate !== 'object') return null;
-    const stroke = candidate as Record<string, unknown>;
-    if (!validColor(stroke.color) || !finite(stroke.width) || stroke.width < 0.1 || stroke.width > 64 || !Array.isArray(stroke.points) || !stroke.points.length) return null;
-    count += stroke.points.length;
-    if (count > MAX_POINTS) return null;
-    const points: SignaturePoint[] = [];
-    for (const candidate of stroke.points) {
-      if (!candidate || typeof candidate !== 'object') return null;
-      const point = candidate as Record<string, unknown>;
-      if (!finite(point.x) || !finite(point.y) || point.x < 0 || point.x > 1 || point.y < 0 || point.y > 1) return null;
-      points.push({ x: point.x, y: point.y });
-    }
-    strokes.push({ color: stroke.color, width: stroke.width, points });
-  }
-  return { version: 1, strokes };
-}
-
-const rounded = (value: number) => Number(value.toFixed(3));
-function strokePath(points: SignaturePoint[], width: number, height: number) {
-  const coordinates = points.map((point) => [rounded(point.x * width), rounded(point.y * height)] as const);
-  const first = coordinates[0]!;
-  let path = `M ${first[0]} ${first[1]}`;
-  if (coordinates.length === 1) return `${path} l 0.001 0`;
-  for (let i = 1; i < coordinates.length - 1; i++) {
-    const current = coordinates[i]!;
-    const next = coordinates[i + 1]!;
-    path += ` Q ${current[0]} ${current[1]} ${rounded((current[0] + next[0]) / 2)} ${rounded((current[1] + next[1]) / 2)}`;
-  }
-  const last = coordinates[coordinates.length - 1]!;
-  return `${path} L ${last[0]} ${last[1]}`;
-}
-
-function makePath(stroke: SignatureStroke, width: number, height: number) {
-  const path = document.createElementNS(SVG_NS, 'path');
-  path.setAttribute('d', strokePath(stroke.points, width, height));
-  path.setAttribute('fill', 'none');
-  path.setAttribute('stroke', stroke.color);
-  path.setAttribute('stroke-width', String(stroke.width));
-  path.setAttribute('stroke-linecap', 'round');
-  path.setAttribute('stroke-linejoin', 'round');
-  return path;
-}
-
-let nextId = 0;
-
-/** A responsive SVG drawing pad. Drawing is immediate; only toolbar feedback uses motion. */
-export function createSignaturePad(root: HTMLElement | null, options: SignaturePadOptions = {}): SignaturePadInstance {
-  if (!root) return inert<SignaturePadInstance>({
-    data: emptyData(), isEmpty: true, canUndo: false, canRedo: false,
-    undo() {}, redo() {}, clear() {}, importData: () => false, exportData: emptyData,
-    exportSVG: () => '', exportPNG: async () => null, setDisabled() {}, setReadOnly() {},
-  });
-  registerMotion();
-  const scope = createScope();
-  let strokes = validatedData(options.data)?.strokes ?? [];
-  const initialStrokes = cloneStrokes(strokes);
-  let disabled = Boolean(options.disabled);
-  let readOnly = Boolean(options.readOnly);
-  let undoStack: SignatureStroke[][] = [];
-  let redoStack: SignatureStroke[][] = [];
-  const historyLimit = finite(options.historyLimit) ? clamp(Math.floor(options.historyLimit), 1, 100) : 50;
-  const inkWidth = finite(options.width) ? clamp(options.width, 0.1, 64) : 2.4;
-  const exportData = (): SignatureData => ({ version: 1, strokes: cloneStrokes(strokes) });
-  const wrapper = document.createElement('div');
-  wrapper.dataset.mkSignatureBody = '';
-  const surface = document.createElement('div');
-  surface.dataset.mkSignatureSurface = '';
-  const svg = document.createElementNS(SVG_NS, 'svg');
-  svg.dataset.mkSignatureDrawing = '';
-  svg.setAttribute('role', 'img');
-  svg.setAttribute('aria-label', options.label ?? 'Área de firma');
-  svg.setAttribute('preserveAspectRatio', 'none');
-  const placeholder = document.createElement('span');
-  placeholder.dataset.mkSignaturePlaceholder = '';
-  placeholder.setAttribute('aria-hidden', 'true');
-  placeholder.textContent = options.placeholder ?? 'Firma aquí';
-  surface.append(svg, placeholder);
-  const footer = document.createElement('div');
-  footer.dataset.mkSignatureFooter = '';
-  const toolbar = document.createElement('div');
-  toolbar.dataset.mkSignatureToolbar = '';
-  toolbar.setAttribute('role', 'group');
-  toolbar.setAttribute('aria-label', 'Herramientas de firma');
-  const makeButton = (action: string, text: string) => {
-    const button = document.createElement('button');
-    button.type = 'button';
-    button.dataset.mkSignatureAction = action;
-    button.textContent = text;
-    toolbar.append(button);
-    return button;
-  };
-  const undoButton = makeButton('undo', 'Deshacer');
-  const redoButton = makeButton('redo', 'Rehacer');
-  const clearButton = makeButton('clear', 'Limpiar');
-  if (options.toolbar !== false) footer.append(toolbar);
-  const status = document.createElement('span');
-  status.dataset.mkSignatureStatus = '';
-  status.setAttribute('role', 'status');
-  status.setAttribute('aria-live', 'polite');
-  footer.append(status);
-  const hint = document.createElement('p');
-  hint.dataset.mkSignatureHint = '';
-  hint.id = `mk-signature-hint-${++nextId}`;
-  hint.textContent = options.hint ?? 'Dibuja con el ratón, el dedo o un lápiz. Puedes deshacer cada trazo.';
-  svg.setAttribute('aria-describedby', hint.id);
-  wrapper.append(surface, footer, hint);
-  let hidden: HTMLInputElement | null = null;
-  if (options.name) {
-    hidden = document.createElement('input');
-    hidden.type = 'hidden';
-    hidden.name = options.name;
-    wrapper.append(hidden);
-  }
-  root.append(wrapper);
-  scope.add(() => wrapper.remove());
-  for (const name of ['data-mk-disabled', 'data-mk-readonly', 'data-mk-drawing', 'data-mk-empty']) scope.attr(root, name, null);
-  scope.attr(root, 'data-mk-ready', '');
-  let dimensions = { width: 640, height: 240 };
-  let active: { pointerId: number; stroke: SignatureStroke; path: SVGPathElement } | null = null;
-  let feedback: gsap.core.Tween | null = null;
-  const locked = () => disabled || readOnly;
-
-  const update = () => {
-    root.toggleAttribute('data-mk-empty', !strokes.length && !active);
-    root.toggleAttribute('data-mk-disabled', disabled);
-    root.toggleAttribute('data-mk-readonly', readOnly);
-    svg.setAttribute('aria-disabled', String(disabled));
-    placeholder.hidden = strokes.length > 0 || active !== null;
-    undoButton.disabled = locked() || !undoStack.length;
-    redoButton.disabled = locked() || !redoStack.length;
-    clearButton.disabled = locked() || !strokes.length;
-    status.textContent = strokes.length ? `${strokes.length} ${strokes.length === 1 ? 'trazo' : 'trazos'} · ${readOnly ? 'Solo lectura' : 'Firma capturada'}` : 'Sin firma';
-    if (hidden) {
-      hidden.disabled = disabled;
-      hidden.value = JSON.stringify(exportData());
-    }
-  };
-  const render = () => {
-    const rect = surface.getBoundingClientRect();
-    if (rect.width > 0 && rect.height > 0) dimensions = { width: rect.width, height: rect.height };
-    svg.setAttribute('viewBox', `0 0 ${dimensions.width} ${dimensions.height}`);
-    svg.replaceChildren(...strokes.map((stroke) => makePath(stroke, dimensions.width, dimensions.height)));
-    if (active) {
-      active.path = makePath(active.stroke, dimensions.width, dimensions.height);
-      svg.append(active.path);
-    }
-  };
-  const emit = (reason: SignaturePadChangeReason) => {
-    const detail: SignaturePadChangeDetail = { data: exportData(), reason, isEmpty: !strokes.length, canUndo: !!undoStack.length, canRedo: !!redoStack.length };
-    options.onChange?.(exportData(), { ...detail, data: exportData() });
-    if (scope.disposed) return;
-    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail }));
-  };
-  const release = (pointerId: number) => {
-    try { surface.releasePointerCapture?.(pointerId); } catch { /* The pointer may already be released. */ }
-  };
-  const cancel = () => {
-    if (!active) return;
-    const pointerId = active.pointerId;
-    active = null;
-    root.removeAttribute('data-mk-drawing');
-    release(pointerId);
-    render();
-    update();
-  };
-  const remember = () => {
-    undoStack.push(strokes);
-    if (undoStack.length > historyLimit) undoStack.shift();
-    redoStack = [];
-  };
-  const pulse = (button: HTMLButtonElement) => {
-    feedback?.progress(1).kill();
-    if (reduced()) return;
-    feedback = gsap.fromTo(button, { scale: 0.95 }, { scale: 1, duration: 0.24, ease: EASE.click });
-  };
-  const undo = () => {
-    if (scope.disposed) return;
-    cancel();
-    if (!undoStack.length) return;
-    redoStack.push(strokes);
-    strokes = undoStack.pop()!;
-    render(); update(); emit('undo');
-  };
-  const redo = () => {
-    if (scope.disposed) return;
-    cancel();
-    if (!redoStack.length) return;
-    undoStack.push(strokes);
-    strokes = redoStack.pop()!;
-    render(); update(); emit('redo');
-  };
-  const clear = () => {
-    if (scope.disposed) return;
-    cancel();
-    if (!strokes.length) return;
-    remember(); strokes = [];
-    render(); update(); emit('clear');
-  };
-  const form = hidden?.form;
-  if (form) scope.on(form, 'reset', (event) => {
-    // Native reset runs after dispatch. Waiting also observes preventDefault from later listeners.
-    scope.timeout(() => {
-      if (scope.disposed || event.defaultPrevented || hidden?.form !== form) return;
-      const changed = !sameStrokes(strokes, initialStrokes);
-      cancel(); strokes = cloneStrokes(initialStrokes); undoStack = []; redoStack = [];
-      render(); update();
-      if (changed) emit('reset');
-    }, 0);
-  });
-  const pointFrom = (event: PointerEvent): SignaturePoint | null => {
-    const rect = surface.getBoundingClientRect();
-    if (!rect.width || !rect.height || !finite(event.clientX) || !finite(event.clientY)) return null;
-    return { x: clamp((event.clientX - rect.left) / rect.width, 0, 1), y: clamp((event.clientY - rect.top) / rect.height, 0, 1) };
-  };
-  const addPoint = (event: PointerEvent) => {
-    if (!active) return;
-    const point = pointFrom(event);
-    if (!point || active.stroke.points.length >= MAX_POINTS - strokes.reduce((sum, stroke) => sum + stroke.points.length, 0)) return;
-    const last = active.stroke.points[active.stroke.points.length - 1]!;
-    if (point.x === last.x && point.y === last.y) return;
-    active.stroke.points.push(point);
-    active.path.setAttribute('d', strokePath(active.stroke.points, dimensions.width, dimensions.height));
-  };
-  scope.on(surface, 'pointerdown', (event) => {
-    const pointer = event as PointerEvent;
-    if (locked() || active || pointer.button !== 0 || pointer.isPrimary === false || strokes.length >= MAX_STROKES || strokes.reduce((sum, stroke) => sum + stroke.points.length, 0) >= MAX_POINTS) return;
-    const point = pointFrom(pointer);
-    if (!point) return;
-    pointer.preventDefault();
-    const themed = getComputedStyle(root).getPropertyValue('--mk-signature-ink').trim() || getComputedStyle(root).color;
-    const color = validColor(options.color) ? options.color : validColor(themed) ? themed : '#252735';
-    const stroke: SignatureStroke = { points: [point], color, width: inkWidth };
-    active = { pointerId: pointer.pointerId, stroke, path: makePath(stroke, dimensions.width, dimensions.height) };
-    render(); update();
-    root.setAttribute('data-mk-drawing', '');
-    try { surface.setPointerCapture?.(pointer.pointerId); } catch { /* Synthetic events have no active pointer. */ }
-  });
-  // Window listeners also finish safely when capture is unavailable in an embedded browser.
-  scope.on(window, 'pointermove', (event) => {
-    const pointer = event as PointerEvent;
-    if (!active || pointer.pointerId !== active.pointerId) return;
-    pointer.preventDefault();
-    const samples = typeof pointer.getCoalescedEvents === 'function' ? pointer.getCoalescedEvents() : [];
-    for (const sample of samples) addPoint(sample);
-    addPoint(pointer);
-  }, { passive: false });
-  scope.on(window, 'pointerup', (event) => {
-    const pointer = event as PointerEvent;
-    if (!active || pointer.pointerId !== active.pointerId) return;
-    addPoint(pointer);
-    const completed = active;
-    active = null;
-    root.removeAttribute('data-mk-drawing');
-    release(completed.pointerId);
-    remember(); strokes = [...strokes, completed.stroke];
-    update(); emit('draw');
-  });
-  for (const type of ['pointercancel', 'lostpointercapture']) scope.on(type === 'pointercancel' ? window : surface, type, (event) => {
-    if (active?.pointerId === (event as PointerEvent).pointerId) cancel();
-  });
-  scope.on(window, 'blur', cancel);
-  scope.on(document, 'visibilitychange', () => { if (document.hidden) cancel(); });
-  for (const [button, action] of [[undoButton, undo], [redoButton, redo], [clearButton, clear]] as const) scope.on(button, 'click', () => {
-    if (locked() || button.disabled) return;
-    pulse(button); action();
-  });
-  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(render)).observe(surface);
-  scope.on(window, 'resize', render);
-  scope.add(() => { cancel(); feedback?.kill(); });
-  render(); update();
-
-  const exportSVG = (settings: SignatureExportOptions = {}) => {
-    const width = finite(settings.width) ? clamp(settings.width, 1, 4096) : dimensions.width;
-    const height = finite(settings.height) ? clamp(settings.height, 1, 4096) : dimensions.height;
-    const output = document.createElementNS(SVG_NS, 'svg');
-    output.setAttribute('width', String(rounded(width)));
-    output.setAttribute('height', String(rounded(height)));
-    output.setAttribute('viewBox', `0 0 ${width} ${height}`);
-    if (validColor(settings.background)) {
-      const background = document.createElementNS(SVG_NS, 'rect');
-      background.setAttribute('width', '100%'); background.setAttribute('height', '100%'); background.setAttribute('fill', settings.background);
-      output.append(background);
-    }
-    output.append(...strokes.map((stroke) => makePath(stroke, width, height)));
-    return new XMLSerializer().serializeToString(output);
-  };
-  const pending = new Set<() => void>();
-  scope.add(() => { for (const cancelExport of pending) cancelExport(); pending.clear(); });
-  return {
-    get data() { return exportData(); },
-    get isEmpty() { return !strokes.length; },
-    get canUndo() { return !!undoStack.length; },
-    get canRedo() { return !!redoStack.length; },
-    undo, redo, clear, exportData,
-    importData(value, notify = true) {
-      if (scope.disposed) return false;
-      const next = validatedData(value);
-      if (!next) return false;
-      if (sameStrokes(next.strokes, strokes)) return true;
-      cancel(); strokes = next.strokes; undoStack = []; redoStack = [];
-      render(); update();
-      if (notify) emit('import');
-      return true;
-    },
-    exportSVG: (settings) => scope.disposed ? '' : exportSVG(settings),
-    exportPNG(settings = {}) {
-      if (scope.disposed) return Promise.resolve(null);
-      const canvas = document.createElement('canvas');
-      let context: CanvasRenderingContext2D | null;
-      try { context = canvas.getContext('2d'); }
-      catch { return Promise.resolve(null); }
-      if (!context || typeof canvas.toBlob !== 'function') return Promise.resolve(null);
-      const scale = finite(settings.scale) ? clamp(settings.scale, 1, 4) : 2;
-      canvas.width = Math.round((finite(settings.width) ? clamp(settings.width, 1, 4096) : dimensions.width) * scale);
-      canvas.height = Math.round((finite(settings.height) ? clamp(settings.height, 1, 4096) : dimensions.height) * scale);
-      return new Promise<Blob | null>((resolve) => {
-        const image = new Image();
-        let finished = false;
-        const done = (blob: Blob | null) => {
-          if (finished) return;
-          finished = true; image.onload = null; image.onerror = null;
-          pending.delete(cancelExport); clearTimeout(timer); resolve(scope.disposed ? null : blob);
-        };
-        const cancelExport = () => { done(null); image.src = ''; };
-        const timer = setTimeout(cancelExport, 10_000);
-        pending.add(cancelExport);
-        image.onerror = () => done(null);
-        image.onload = () => {
-          try {
-            context.drawImage(image, 0, 0, canvas.width, canvas.height);
-            canvas.toBlob(done, 'image/png');
-          } catch { done(null); }
-        };
-        image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(exportSVG(settings))}`;
-      });
-    },
-    setDisabled(value) { if (!scope.disposed) { cancel(); disabled = Boolean(value); update(); } },
-    setReadOnly(value) { if (!scope.disposed) { cancel(); readOnly = Boolean(value); update(); } },
-    destroy: () => scope.dispose(),
-  };
-}
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { press, blurIn, rollDigits } from '../../motion/micro';
+
+/** Coordinates are fractions of the drawing area, independent of its size. */
+export interface SignaturePoint { x: number; y: number }
+export interface SignatureStroke { points: SignaturePoint[]; color: string; width: number }
+export interface SignatureData { version: 1; strokes: SignatureStroke[] }
+export type SignaturePadChangeReason = 'draw' | 'undo' | 'redo' | 'clear' | 'import' | 'reset';
+export interface SignaturePadChangeDetail {
+  data: SignatureData;
+  reason: SignaturePadChangeReason;
+  isEmpty: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+export interface SignatureExportOptions {
+  /** CSS pixels; default is the current drawing area, or 640 × 240 before layout. */
+  width?: number;
+  height?: number;
+  /** Omit for transparency. Accepts a literal CSS color, without variables or URLs. */
+  background?: string;
+}
+export interface SignaturePNGOptions extends SignatureExportOptions {
+  /** Raster resolution multiplier, clamped to 1–4 (default 2). */
+  scale?: number;
+}
+export interface SignaturePadOptions {
+  data?: SignatureData;
+  label?: string;
+  hint?: string;
+  placeholder?: string;
+  /** Literal CSS ink color; defaults to the theme's text color. */
+  color?: string;
+  /** Ink width in CSS pixels, default 2.4. */
+  width?: number;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /** Include native undo, redo and clear buttons (default true). */
+  toolbar?: boolean;
+  /** Adds a hidden input containing the versioned JSON data. */
+  name?: string;
+  /** Maximum undo steps, clamped to 1–100 (default 50). */
+  historyLimit?: number;
+  onChange?: (data: SignatureData, detail: SignaturePadChangeDetail) => void;
+}
+export interface SignaturePadInstance extends Instance {
+  readonly data: SignatureData;
+  readonly isEmpty: boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  undo(): void;
+  redo(): void;
+  clear(): void;
+  /** Invalid input returns false and leaves the signature untouched. Import resets history. */
+  importData(data: unknown, notify?: boolean): boolean;
+  exportData(): SignatureData;
+  exportSVG(options?: SignatureExportOptions): string;
+  /** Returns null when rasterization is unavailable or fails. */
+  exportPNG(options?: SignaturePNGOptions): Promise<Blob | null>;
+  setDisabled(disabled: boolean): void;
+  setReadOnly(readOnly: boolean): void;
+}
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const MAX_STROKES = 500;
+const MAX_POINTS = 50_000;
+const emptyData = (): SignatureData => ({ version: 1, strokes: [] });
+const cloneStrokes = (strokes: SignatureStroke[]) => strokes.map((stroke) => ({ ...stroke, points: stroke.points.map((point) => ({ ...point })) }));
+const sameStrokes = (left: SignatureStroke[], right: SignatureStroke[]) => left.length === right.length && left.every((stroke, index) => {
+  const other = right[index]!;
+  return stroke.color === other.color && stroke.width === other.width && stroke.points.length === other.points.length && stroke.points.every((point, index) => point.x === other.points[index]!.x && point.y === other.points[index]!.y);
+});
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
+
+/** Reject paint servers, CSS variables and markup so exports stay self-contained. */
+function validColor(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length > 100) return false;
+  if (/^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i.test(value)) return true;
+  if (!/^(?:rgba?|hsla?)\([\d\s.,%/+\-degratun]+\)$/i.test(value) && !/^[a-z]+$/i.test(value)) return false;
+  if (/^(?:inherit|initial|unset|revert|revertlayer|currentcolor)$/i.test(value)) return false;
+  if (typeof document === 'undefined') return /^(?:black|white|transparent)$/i.test(value);
+  const probe = document.createElement('span');
+  probe.style.color = value;
+  return probe.style.color !== '';
+}
+
+function validatedData(value: unknown): SignatureData | null {
+  if (!value || typeof value !== 'object') return null;
+  const data = value as Record<string, unknown>;
+  if (data.version !== 1 || !Array.isArray(data.strokes) || data.strokes.length > MAX_STROKES) return null;
+  const strokes: SignatureStroke[] = [];
+  let count = 0;
+  for (const candidate of data.strokes) {
+    if (!candidate || typeof candidate !== 'object') return null;
+    const stroke = candidate as Record<string, unknown>;
+    if (!validColor(stroke.color) || !finite(stroke.width) || stroke.width < 0.1 || stroke.width > 64 || !Array.isArray(stroke.points) || !stroke.points.length) return null;
+    count += stroke.points.length;
+    if (count > MAX_POINTS) return null;
+    const points: SignaturePoint[] = [];
+    for (const candidate of stroke.points) {
+      if (!candidate || typeof candidate !== 'object') return null;
+      const point = candidate as Record<string, unknown>;
+      if (!finite(point.x) || !finite(point.y) || point.x < 0 || point.x > 1 || point.y < 0 || point.y > 1) return null;
+      points.push({ x: point.x, y: point.y });
+    }
+    strokes.push({ color: stroke.color, width: stroke.width, points });
+  }
+  return { version: 1, strokes };
+}
+
+const rounded = (value: number) => Number(value.toFixed(3));
+function strokePath(points: SignaturePoint[], width: number, height: number) {
+  const coordinates = points.map((point) => [rounded(point.x * width), rounded(point.y * height)] as const);
+  const first = coordinates[0]!;
+  let path = `M ${first[0]} ${first[1]}`;
+  if (coordinates.length === 1) return `${path} l 0.001 0`;
+  for (let i = 1; i < coordinates.length - 1; i++) {
+    const current = coordinates[i]!;
+    const next = coordinates[i + 1]!;
+    path += ` Q ${current[0]} ${current[1]} ${rounded((current[0] + next[0]) / 2)} ${rounded((current[1] + next[1]) / 2)}`;
+  }
+  const last = coordinates[coordinates.length - 1]!;
+  return `${path} L ${last[0]} ${last[1]}`;
+}
+
+function makePath(stroke: SignatureStroke, width: number, height: number) {
+  const path = document.createElementNS(SVG_NS, 'path');
+  path.setAttribute('d', strokePath(stroke.points, width, height));
+  path.setAttribute('fill', 'none');
+  path.setAttribute('stroke', stroke.color);
+  path.setAttribute('stroke-width', String(stroke.width));
+  path.setAttribute('stroke-linecap', 'round');
+  path.setAttribute('stroke-linejoin', 'round');
+  return path;
+}
+
+let nextId = 0;
+
+/** A responsive SVG drawing pad. Drawing is immediate; only toolbar feedback uses motion. */
+export function createSignaturePad(root: HTMLElement | null, options: SignaturePadOptions = {}): SignaturePadInstance {
+  if (!root) return inert<SignaturePadInstance>({
+    data: emptyData(), isEmpty: true, canUndo: false, canRedo: false,
+    undo() {}, redo() {}, clear() {}, importData: () => false, exportData: emptyData,
+    exportSVG: () => '', exportPNG: async () => null, setDisabled() {}, setReadOnly() {},
+  });
+  registerMotion();
+  const scope = createScope();
+  let strokes = validatedData(options.data)?.strokes ?? [];
+  const initialStrokes = cloneStrokes(strokes);
+  let disabled = Boolean(options.disabled);
+  let readOnly = Boolean(options.readOnly);
+  let undoStack: SignatureStroke[][] = [];
+  let redoStack: SignatureStroke[][] = [];
+  const historyLimit = finite(options.historyLimit) ? clamp(Math.floor(options.historyLimit), 1, 100) : 50;
+  const inkWidth = finite(options.width) ? clamp(options.width, 0.1, 64) : 2.4;
+  const exportData = (): SignatureData => ({ version: 1, strokes: cloneStrokes(strokes) });
+  const wrapper = document.createElement('div');
+  wrapper.dataset.mkSignatureBody = '';
+  const surface = document.createElement('div');
+  surface.dataset.mkSignatureSurface = '';
+  const svg = document.createElementNS(SVG_NS, 'svg');
+  svg.dataset.mkSignatureDrawing = '';
+  svg.setAttribute('role', 'img');
+  svg.setAttribute('aria-label', options.label ?? 'Área de firma');
+  svg.setAttribute('preserveAspectRatio', 'none');
+  const placeholder = document.createElement('span');
+  placeholder.dataset.mkSignaturePlaceholder = '';
+  placeholder.setAttribute('aria-hidden', 'true');
+  placeholder.textContent = options.placeholder ?? 'Firma aquí';
+  const pen = document.createElement('span');
+  pen.dataset.mkSignatureCursor = ''; pen.setAttribute('aria-hidden', 'true');
+  // Removed ink leaves through this overlay, so the drawing always holds the current value.
+  const ghost = document.createElementNS(SVG_NS, 'svg');
+  ghost.setAttribute('data-mk-signature-ghost', '');
+  ghost.setAttribute('aria-hidden', 'true');
+  ghost.setAttribute('preserveAspectRatio', 'none');
+  surface.append(svg, ghost, placeholder, pen);
+  const footer = document.createElement('div');
+  footer.dataset.mkSignatureFooter = '';
+  const toolbar = document.createElement('div');
+  toolbar.dataset.mkSignatureToolbar = '';
+  toolbar.setAttribute('role', 'group');
+  toolbar.setAttribute('aria-label', 'Herramientas de firma');
+  const makeButton = (action: string, text: string) => {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.dataset.mkSignatureAction = action;
+    const paths: Record<string, string> = { undo: 'M9 5 4 10l5 5M4 10h9a6 6 0 0 1 6 6', redo: 'm15 5 5 5-5 5m5-5h-9a6 6 0 0 0-6 6', clear: 'm9 5 1-2h4l1 2M4 6h16M7 6l1 15h8l1-15M10 10v7m4-7v7' };
+    button.innerHTML = `<svg viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><path d="${paths[action]}"/></svg>`;
+    const caption = document.createElement('span'); caption.textContent = text; button.append(caption);
+    toolbar.append(button);
+    return button;
+  };
+  const undoButton = makeButton('undo', 'Deshacer');
+  const redoButton = makeButton('redo', 'Rehacer');
+  const clearButton = makeButton('clear', 'Limpiar');
+  if (options.toolbar !== false) footer.append(toolbar);
+  const status = document.createElement('span');
+  status.dataset.mkSignatureStatus = '';
+  status.setAttribute('role', 'status');
+  status.setAttribute('aria-live', 'polite');
+  const heading = document.createElement('div'); heading.dataset.mkSignatureHeader = '';
+  const title = document.createElement('span'); title.textContent = options.label ?? 'Tu firma';
+  heading.append(title, status);
+  const hint = document.createElement('p');
+  hint.dataset.mkSignatureHint = '';
+  hint.id = `mk-signature-hint-${++nextId}`;
+  hint.textContent = options.hint ?? 'Dibuja con el ratón, el dedo o un lápiz. Puedes deshacer cada trazo.';
+  svg.setAttribute('aria-describedby', hint.id);
+  wrapper.append(heading, surface, footer, hint);
+  let hidden: HTMLInputElement | null = null;
+  if (options.name) {
+    hidden = document.createElement('input');
+    hidden.type = 'hidden';
+    hidden.name = options.name;
+    wrapper.append(hidden);
+  }
+  root.append(wrapper);
+  scope.add(() => wrapper.remove());
+  for (const name of ['data-mk-disabled', 'data-mk-readonly', 'data-mk-drawing', 'data-mk-empty', 'data-mk-pen-visible']) scope.attr(root, name, null);
+  scope.attr(root, 'data-mk-ready', '');
+  let dimensions = { width: 640, height: 240 };
+  let active: { pointerId: number; stroke: SignatureStroke; path: SVGPathElement } | null = null;
+  const effects = new Set<gsap.core.Animation>();
+  // Only the stroke count rolls; the status line is rewritten in full when the pad
+  // turns empty or signed, so repeated strokes never blur the whole label.
+  const statusCount = document.createElement('span');
+  const statusLabel = document.createElement('span');
+  let shown: { count: number; readOnly: boolean } | null = null;
+  const paintStatus = () => {
+    const count = strokes.length;
+    if (shown && shown.count === count && shown.readOnly === readOnly) return;
+    const before = shown;
+    shown = { count, readOnly };
+    const animate = before !== null && !reduced();
+    if (!count) {
+      status.textContent = 'Sin firma';
+      if (animate && before.count) keep(blurIn(status, { from: 'soft', duration: .25 }));
+      return;
+    }
+    statusLabel.replaceChildren(statusCount, ` ${count === 1 ? 'trazo' : 'trazos'} · ${readOnly ? 'Solo lectura' : 'Firma capturada'}`);
+    status.replaceChildren(statusLabel);
+    if (animate && before.count) keep(rollDigits(statusCount, String(count), count > before.count ? 1 : -1, .3));
+    else {
+      statusCount.textContent = String(count);
+      if (animate) keep(blurIn(status, { from: 'soft', duration: .25 }));
+    }
+  };
+  const keep = (effect: gsap.core.Animation | null) => {
+    for (const animation of effects) if (animation.totalProgress() === 1) effects.delete(animation);
+    if (effect) effects.add(effect);
+  };
+  const locked = () => disabled || readOnly;
+
+  const update = () => {
+    root.toggleAttribute('data-mk-empty', !strokes.length && !active);
+    root.toggleAttribute('data-mk-disabled', disabled);
+    root.toggleAttribute('data-mk-readonly', readOnly);
+    svg.setAttribute('aria-disabled', String(disabled));
+    placeholder.hidden = strokes.length > 0 || active !== null;
+    undoButton.disabled = locked() || !undoStack.length;
+    redoButton.disabled = locked() || !redoStack.length;
+    clearButton.disabled = locked() || !strokes.length;
+    paintStatus();
+    if (hidden) {
+      hidden.disabled = disabled;
+      hidden.value = JSON.stringify(exportData());
+    }
+  };
+  const render = () => {
+    const rect = surface.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0) dimensions = { width: rect.width, height: rect.height };
+    svg.setAttribute('viewBox', `0 0 ${dimensions.width} ${dimensions.height}`);
+    svg.replaceChildren(...strokes.map((stroke) => makePath(stroke, dimensions.width, dimensions.height)));
+    if (active) {
+      active.path = makePath(active.stroke, dimensions.width, dimensions.height);
+      svg.append(active.path);
+    }
+  };
+  const emit = (reason: SignaturePadChangeReason) => {
+    const detail: SignaturePadChangeDetail = { data: exportData(), reason, isEmpty: !strokes.length, canUndo: !!undoStack.length, canRedo: !!redoStack.length };
+    options.onChange?.(exportData(), { ...detail, data: exportData() });
+    if (scope.disposed) return;
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail }));
+  };
+  const release = (pointerId: number) => {
+    try { surface.releasePointerCapture?.(pointerId); } catch { /* The pointer may already be released. */ }
+  };
+  const cancel = () => {
+    if (!active) return;
+    const pointerId = active.pointerId;
+    active = null;
+    root.removeAttribute('data-mk-drawing');
+    release(pointerId);
+    render();
+    update();
+  };
+  const remember = () => {
+    undoStack.push(strokes);
+    if (undoStack.length > historyLimit) undoStack.shift();
+    redoStack = [];
+  };
+  const pulse = (button: HTMLButtonElement) => {
+    keep(press(button));
+    // Undo and redo rewind their arrow; clear tips the bin's lid.
+    const icon = button.querySelector('svg');
+    const turn = button === undoButton ? -50 : button === redoButton ? 50 : -14;
+    if (icon && !reduced()) keep(gsap.fromTo(icon, { rotate: turn }, { rotate: 0, duration: .5, ease: EASE.click, overwrite: 'auto', clearProps: 'transform' }));
+  };
+  // The value changes first. An undone stroke retracts along its path back to where
+  // it began, a clear sweeps the page like an eraser from left to right, and
+  // returning ink is written again at pen pace. The overlay never takes input.
+  const wipeId = `mk-signature-wipe-${++nextId}`;
+  let wipes = 0;
+  const animateInk = (before: SignatureStroke[], reason: 'undo' | 'redo' | 'clear') => {
+    if (reduced()) return;
+    const { width, height } = dimensions;
+    const byX = (a: SignatureStroke, b: SignatureStroke) => (a.points[0]?.x ?? 0) - (b.points[0]?.x ?? 0);
+    const removed = before.filter((stroke) => !strokes.includes(stroke)).sort(byX);
+    const added = strokes.filter((stroke) => !before.includes(stroke)).sort(byX);
+    ghost.setAttribute('viewBox', `0 0 ${width} ${height}`);
+    if (removed.length && reason === 'clear') {
+      const svgNode = <K extends keyof SVGElementTagNameMap>(tag: K, attributes: Record<string, string | number>) => {
+        const node = document.createElementNS(SVG_NS, tag);
+        for (const [name, value] of Object.entries(attributes)) node.setAttribute(name, String(value));
+        return node;
+      };
+      // The eraser only travels across the ink, so its time is spent on the signature.
+      const points = removed.flatMap((stroke) => stroke.points);
+      const pad = inkWidth * 2 + 8;
+      const left = Math.min(...points.map((point) => point.x)) * width - pad;
+      const right = Math.max(...points.map((point) => point.x)) * width + pad;
+      const top = Math.max(0, Math.min(...points.map((point) => point.y)) * height - pad);
+      const bottom = Math.min(height, Math.max(...points.map((point) => point.y)) * height + pad);
+      const id = `${wipeId}-${++wipes}`;
+      const clip = svgNode('clipPath', { id });
+      const reveal = svgNode('rect', { x: left, y: 0, width: width * 2, height });
+      clip.append(reveal);
+      const ink = svgNode('g', { 'clip-path': `url(#${id})` });
+      ink.append(...removed.map((stroke) => makePath(stroke, width, height)));
+      const edge = svgNode('rect', { x: left, y: top, width: 2, height: Math.max(24, bottom - top), rx: 1, fill: 'currentColor', opacity: 0 });
+      ghost.append(clip, ink, edge);
+      const done = () => { clip.remove(); ink.remove(); edge.remove(); };
+      const sweep = Math.min(.6, Math.max(.36, (right - left) / 900));
+      keep(gsap.timeline({ onComplete: done, onInterrupt: done })
+        .to([reveal, edge], { attr: { x: right }, duration: sweep, ease: 'power2.inOut' }, 0)
+        .to(edge, { opacity: .3, duration: .08 }, 0)
+        .to(edge, { opacity: 0, duration: .14 }, sweep - .12));
+    } else removed.forEach((stroke) => {
+      const path = makePath(stroke, width, height);
+      ghost.append(path);
+      const length = path.getTotalLength?.() ?? 0;
+      const done = () => path.remove();
+      if (!length) { keep(gsap.to(path, { opacity: 0, duration: .25, onComplete: done })); return; }
+      path.style.strokeDasharray = `${length} ${length}`;
+      keep(gsap.timeline({ onComplete: done, onInterrupt: done })
+        .fromTo(path, { strokeDashoffset: 0 }, { strokeDashoffset: length, duration: .5, ease: 'power2.inOut' }, 0)
+        .to(path, { opacity: 0, duration: .16 }, .36));
+    });
+    const rendered = [...svg.children] as SVGPathElement[];
+    added.forEach((stroke, index) => {
+      const path = rendered[strokes.indexOf(stroke)];
+      const length = path?.getTotalLength?.() ?? 0;
+      if (!path || !length) return;
+      path.style.strokeDasharray = `${length} ${length}`;
+      keep(gsap.fromTo(path, { strokeDashoffset: length }, { strokeDashoffset: 0, duration: .6, delay: Math.min(index * .08, .48), ease: EASE.wipe, clearProps: 'strokeDasharray,strokeDashoffset' }));
+    });
+  };
+  const undo = () => {
+    if (scope.disposed) return;
+    cancel();
+    if (!undoStack.length) return;
+    const before = strokes;
+    redoStack.push(strokes);
+    strokes = undoStack.pop()!;
+    render(); update(); emit('undo'); animateInk(before, 'undo');
+  };
+  const redo = () => {
+    if (scope.disposed) return;
+    cancel();
+    if (!redoStack.length) return;
+    const before = strokes;
+    undoStack.push(strokes);
+    strokes = redoStack.pop()!;
+    render(); update(); emit('redo'); animateInk(before, 'redo');
+  };
+  const clear = () => {
+    if (scope.disposed) return;
+    cancel();
+    if (!strokes.length) return;
+    const before = strokes;
+    remember(); strokes = [];
+    render(); update(); emit('clear'); animateInk(before, 'clear');
+  };
+  const form = hidden?.form;
+  if (form) scope.on(form, 'reset', (event) => {
+    // Native reset runs after dispatch. Waiting also observes preventDefault from later listeners.
+    scope.timeout(() => {
+      if (scope.disposed || event.defaultPrevented || hidden?.form !== form) return;
+      const changed = !sameStrokes(strokes, initialStrokes);
+      cancel(); strokes = cloneStrokes(initialStrokes); undoStack = []; redoStack = [];
+      render(); update();
+      if (changed) emit('reset');
+    }, 0);
+  });
+  const pointFrom = (event: PointerEvent): SignaturePoint | null => {
+    const rect = surface.getBoundingClientRect();
+    if (!rect.width || !rect.height || !finite(event.clientX) || !finite(event.clientY)) return null;
+    return { x: clamp((event.clientX - rect.left) / rect.width, 0, 1), y: clamp((event.clientY - rect.top) / rect.height, 0, 1) };
+  };
+  const addPoint = (event: PointerEvent) => {
+    if (!active) return;
+    const point = pointFrom(event);
+    if (!point || active.stroke.points.length >= MAX_POINTS - strokes.reduce((sum, stroke) => sum + stroke.points.length, 0)) return;
+    const last = active.stroke.points[active.stroke.points.length - 1]!;
+    if (point.x === last.x && point.y === last.y) return;
+    active.stroke.points.push(point);
+    active.path.setAttribute('d', strokePath(active.stroke.points, dimensions.width, dimensions.height));
+  };
+  scope.on(surface, 'pointerdown', (event) => {
+    const pointer = event as PointerEvent;
+    if (locked() || active || pointer.button !== 0 || pointer.isPrimary === false || strokes.length >= MAX_STROKES || strokes.reduce((sum, stroke) => sum + stroke.points.length, 0) >= MAX_POINTS) return;
+    const point = pointFrom(pointer);
+    if (!point) return;
+    pointer.preventDefault();
+    const themed = getComputedStyle(root).getPropertyValue('--mk-signature-ink').trim() || getComputedStyle(root).color;
+    const color = validColor(options.color) ? options.color : validColor(themed) ? themed : '#252735';
+    const stroke: SignatureStroke = { points: [point], color, width: inkWidth };
+    active = { pointerId: pointer.pointerId, stroke, path: makePath(stroke, dimensions.width, dimensions.height) };
+    render(); update();
+    root.setAttribute('data-mk-drawing', '');
+    try { surface.setPointerCapture?.(pointer.pointerId); } catch { /* Synthetic events have no active pointer. */ }
+  });
+  // Window listeners also finish safely when capture is unavailable in an embedded browser.
+  scope.on(window, 'pointermove', (event) => {
+    const pointer = event as PointerEvent;
+    if (!active || pointer.pointerId !== active.pointerId) return;
+    pointer.preventDefault();
+    const samples = typeof pointer.getCoalescedEvents === 'function' ? pointer.getCoalescedEvents() : [];
+    for (const sample of samples) addPoint(sample);
+    addPoint(pointer);
+  }, { passive: false });
+  scope.on(window, 'pointerup', (event) => {
+    const pointer = event as PointerEvent;
+    if (!active || pointer.pointerId !== active.pointerId) return;
+    addPoint(pointer);
+    const completed = active;
+    active = null;
+    root.removeAttribute('data-mk-drawing');
+    release(completed.pointerId);
+    remember(); strokes = [...strokes, completed.stroke];
+    update(); emit('draw');
+  });
+  for (const type of ['pointercancel', 'lostpointercapture']) scope.on(type === 'pointercancel' ? window : surface, type, (event) => {
+    if (active?.pointerId === (event as PointerEvent).pointerId) cancel();
+  });
+  scope.on(window, 'blur', cancel);
+  const movePen = (event: Event) => {
+    const pointer = event as PointerEvent;
+    const rect = surface.getBoundingClientRect();
+    root.toggleAttribute('data-mk-pen-visible', pointer.pointerType !== 'touch' && !locked());
+    pen.style.left = `${pointer.clientX - rect.left}px`; pen.style.top = `${pointer.clientY - rect.top}px`;
+  };
+  scope.on(surface, 'pointerenter', movePen);
+  scope.on(surface, 'pointermove', movePen);
+  scope.on(surface, 'pointerleave', () => root.removeAttribute('data-mk-pen-visible'));
+  scope.on(document, 'visibilitychange', () => { if (document.hidden) cancel(); });
+  for (const [button, action] of [[undoButton, undo], [redoButton, redo], [clearButton, clear]] as const) scope.on(button, 'click', () => {
+    if (locked() || button.disabled) return;
+    pulse(button); action();
+  });
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(render)).observe(surface);
+  scope.on(window, 'resize', render);
+  scope.add(() => { cancel(); for (const effect of effects) effect.kill(); });
+  render(); update();
+
+  const exportSVG = (settings: SignatureExportOptions = {}) => {
+    const width = finite(settings.width) ? clamp(settings.width, 1, 4096) : dimensions.width;
+    const height = finite(settings.height) ? clamp(settings.height, 1, 4096) : dimensions.height;
+    const output = document.createElementNS(SVG_NS, 'svg');
+    output.setAttribute('width', String(rounded(width)));
+    output.setAttribute('height', String(rounded(height)));
+    output.setAttribute('viewBox', `0 0 ${width} ${height}`);
+    if (validColor(settings.background)) {
+      const background = document.createElementNS(SVG_NS, 'rect');
+      background.setAttribute('width', '100%'); background.setAttribute('height', '100%'); background.setAttribute('fill', settings.background);
+      output.append(background);
+    }
+    output.append(...strokes.map((stroke) => makePath(stroke, width, height)));
+    return new XMLSerializer().serializeToString(output);
+  };
+  const pending = new Set<() => void>();
+  scope.add(() => { for (const cancelExport of pending) cancelExport(); pending.clear(); });
+  return {
+    get data() { return exportData(); },
+    get isEmpty() { return !strokes.length; },
+    get canUndo() { return !!undoStack.length; },
+    get canRedo() { return !!redoStack.length; },
+    undo, redo, clear, exportData,
+    importData(value, notify = true) {
+      if (scope.disposed) return false;
+      const next = validatedData(value);
+      if (!next) return false;
+      if (sameStrokes(next.strokes, strokes)) return true;
+      cancel(); strokes = next.strokes; undoStack = []; redoStack = [];
+      render(); update();
+      if (notify) emit('import');
+      return true;
+    },
+    exportSVG: (settings) => scope.disposed ? '' : exportSVG(settings),
+    exportPNG(settings = {}) {
+      if (scope.disposed) return Promise.resolve(null);
+      const canvas = document.createElement('canvas');
+      let context: CanvasRenderingContext2D | null;
+      try { context = canvas.getContext('2d'); }
+      catch { return Promise.resolve(null); }
+      if (!context || typeof canvas.toBlob !== 'function') return Promise.resolve(null);
+      const scale = finite(settings.scale) ? clamp(settings.scale, 1, 4) : 2;
+      canvas.width = Math.round((finite(settings.width) ? clamp(settings.width, 1, 4096) : dimensions.width) * scale);
+      canvas.height = Math.round((finite(settings.height) ? clamp(settings.height, 1, 4096) : dimensions.height) * scale);
+      return new Promise<Blob | null>((resolve) => {
+        const image = new Image();
+        let finished = false;
+        const done = (blob: Blob | null) => {
+          if (finished) return;
+          finished = true; image.onload = null; image.onerror = null;
+          pending.delete(cancelExport); clearTimeout(timer); resolve(scope.disposed ? null : blob);
+        };
+        const cancelExport = () => { done(null); image.src = ''; };
+        const timer = setTimeout(cancelExport, 10_000);
+        pending.add(cancelExport);
+        image.onerror = () => done(null);
+        image.onload = () => {
+          try {
+            context.drawImage(image, 0, 0, canvas.width, canvas.height);
+            canvas.toBlob(done, 'image/png');
+          } catch { done(null); }
+        };
+        image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(exportSVG(settings))}`;
+      });
+    },
+    setDisabled(value) { if (!scope.disposed) { cancel(); disabled = Boolean(value); update(); } },
+    setReadOnly(value) { if (!scope.disposed) { cancel(); readOnly = Boolean(value); update(); } },
+    destroy: () => scope.dispose(),
+  };
+}