@swiftbrowser/web 0.1.0 → 0.3.0

package/src/main.ts

@@ -1,6 +1,7 @@
 /// <reference path="./vite-env.d.ts" />
 import { easingFor, springEasing, timingFor } from './animation';
 import type { BuildEndPayload, BuildErrorPayload, BuildStartPayload } from './devEvents';
+import { ChromeColor } from './chromeColor';
 import { applyPageMode, decidePageMode, readViewportInsets, watchViewport, type PageMode } from './deviceMode';
 import { EMPTY_CATALOG, catalogPath, isAssetCatalog, type AssetCatalog } from './assets';
 import { createMockApp } from './mock';
@@ -14,9 +15,16 @@ import {
   type ScenePhase,
 } from './protocol';
 import { Renderer, RendererError } from './renderer';
+import { withBlockedHosts } from './blockedHosts';
+import { withCORSProxy } from './corsProxy';
+import { browserEnvironment } from './hostRequests';
+import { callbackPageURL } from './webAuth';
+import { bitmapStore } from './bitmaps';
 import { DEFAULT_TYPE_SIZE, applyTypeSizeVariables } from './typography';
 import { JobScheduler, loadApp, type AppHandle, type JobTimers } from './wasm';
 import { chooseLocale, currentTimeZone } from './locale';
+import { indexedDBPersistence, launchValue, type SwiftDataPersistence, type SwiftDataStores } from './swiftData';
+import { applyHomeChanges, diffHome, homeDirectory, homeEntries, indexedDBFiles, type FilesPersistence, type HomeEntries } from './appFiles';
 import type { BundleManifest } from '../plugins/bundle-resources';
 
 const THEME_KEY = 'sb-theme';
@@ -70,7 +78,7 @@ function dispatch(event: RendererEvent): void {
     return;
   }
   try {
-    if (event.type === 'tap') {
+    if (event.type === 'tap' && event.x === undefined) {
       app.sendEvent(event.id);
     } else if (event.type === 'batch' && !app.supportsBatchEvents) {
       // The mock apps handle events one at a time.
@@ -87,6 +95,11 @@ function dispatch(event: RendererEvent): void {
 
 const renderer = new Renderer(screen, dispatch);
 
+// On a phone the browser's status bar strip and safe areas take the color the
+// app draws at its top edge (chromeColor.ts).
+const chromeColor = deviceMode ? new ChromeColor(device, screen) : null;
+if (chromeColor) renderer.afterLayout = () => chromeColor.schedule();
+
 // Phase 12: `.preferredColorScheme` from the app overrides the viewer's theme
 // for this page (not persisted); `null` goes back to the toggle / OS setting.
 screen.addEventListener('sb:color-scheme', (event) => {
@@ -122,6 +135,7 @@ function applyTheme(theme: Theme, persist: boolean): void {
   themeToggle.setAttribute('aria-pressed', String(theme === 'dark'));
   themeToggle.textContent = theme === 'dark' ? 'Light mode' : 'Dark mode';
   renderer.setEnvironment({ colorScheme: theme });
+  chromeColor?.schedule();
   if (persist) {
     try {
       localStorage.setItem(THEME_KEY, theme);
@@ -210,8 +224,8 @@ function currentSizeClass(): HorizontalSizeClass {
 let sentSizeClass: HorizontalSizeClass | null = null;
 
 if (deviceMode) {
-  // `#screen` fills the viewport (styles.css); the engine reads its size on
-  // every pass. The safe areas come from env(safe-area-inset-*): non-zero
+  // `#screen` fills the viewport (styles.css); the renderer re-reads its size
+  // when it resizes. The safe areas come from env(safe-area-inset-*): non-zero
   // only in standalone (home screen) mode or landscape, which is what the
   // real app would get.
   renderer.setSafeArea(readViewportInsets());
@@ -357,9 +371,78 @@ function launchEnvironment(): string[] {
   if (zone) env.push(`TZ=${zone}`);
   const defaults = readStoredDefaults();
   if (defaults !== null) env.push(`SB_DEFAULTS=${defaults}`);
+  // Signing in: the app's URL schemes (its Info.plist's CFBundleURLTypes) and
+  // the callback page its OAuth redirects become (webAuth.ts).
+  const schemes = registeredApp()?.urlSchemes;
+  if (schemes?.length) env.push(`SB_URL_SCHEMES=${schemes.join(',')}`);
+  env.push(`SB_WEB_AUTH_CALLBACK=${callbackPageURL(new URL(import.meta.env.BASE_URL, location.href).href)}`);
   return env;
 }
 
+// ---------------------------------------------------------------------------
+// Phase 18: SwiftData's stores, kept in IndexedDB
+// ---------------------------------------------------------------------------
+
+/** The app's database, or null where the browser has no IndexedDB (or forbids it). */
+const swiftData: SwiftDataPersistence | null = (() => {
+  try {
+    return typeof indexedDB === 'undefined' ? null : indexedDBPersistence(requestedApp);
+  } catch {
+    return null;
+  }
+})();
+
+/**
+ * Every SwiftData store the app saved, for `SB_SWIFTDATA`. `?swiftdata=reset`
+ * deletes them first (a model changed in a way the saved records cannot
+ * follow). A database that cannot be read starts the app empty.
+ */
+async function loadSwiftData(): Promise<SwiftDataStores> {
+  if (!swiftData) return {};
+  try {
+    if (params.get('swiftdata') === 'reset') await swiftData.clear();
+    return await swiftData.load();
+  } catch (error) {
+    console.warn('[sb] could not read the SwiftData stores; starting empty', error);
+    return {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Phase 19: the app's home directory, kept in IndexedDB
+// ---------------------------------------------------------------------------
+
+const files: FilesPersistence | null = (() => {
+  try {
+    return typeof indexedDB === 'undefined' ? null : indexedDBFiles(requestedApp);
+  } catch {
+    return null;
+  }
+})();
+
+/** The home as last written to IndexedDB, to diff the live tree against. */
+let savedHome: HomeEntries = new Map();
+
+/** The saved home (`?files=reset` deletes it first); empty when it cannot be read. */
+async function loadHome(): Promise<HomeEntries> {
+  if (!files) return new Map();
+  try {
+    if (params.get('files') === 'reset') await files.clear();
+    return await files.load();
+  } catch (error) {
+    console.warn('[sb] could not read the app\'s files; starting empty', error);
+    return new Map();
+  }
+}
+
+/** Writes what the app changed in its home since the last write. */
+function saveHome(home: ReturnType<typeof homeDirectory>): void {
+  const changes = diffHome(savedHome, homeEntries(home));
+  if (changes.put.length === 0 && changes.remove.length === 0) return;
+  savedHome = applyHomeChanges(savedHome, changes);
+  files?.apply(changes).catch((error: unknown) => console.warn('[sb] could not save the app\'s files to IndexedDB', error));
+}
+
 /** The app's resources (`/bundle/<App>.json` and its files), for the WASI `/bundle` mount; empty without a manifest. */
 async function loadBundle(app: string): Promise<Map<string, Uint8Array>> {
   const files = new Map<string, Uint8Array>();
@@ -489,7 +572,38 @@ async function boot(): Promise<void> {
     console.info(`[sb] restoring state for ${requestedApp}: ${restored}`);
   }
   const bundle = await loadBundle(requestedApp);
-  app = await loadApp(url, onOps, { args: [requestedApp], env, bundle, onDefaults: storeDefaults });
+  const stores = launchValue(await loadSwiftData());
+  if (stores !== null) env.push(`SB_SWIFTDATA=${stores}`);
+  savedHome = await loadHome();
+  const home = homeDirectory(savedHome);
+  // The standard directories a new home gets are saved with its first write.
+  const corsProxy = registeredApp()?.corsProxy;
+  app = await loadApp(url, onOps, {
+    // `?arg=` (repeatable) adds launch arguments after the app's name, as
+    // `simctl launch <app> <args>` does: CI's iOS fidelity workflow opens a
+    // screen of Examples/Fidelity with `?arg=-screen&arg=<name>`.
+    args: [requestedApp, ...params.getAll('arg')],
+    env,
+    bundle,
+    home,
+    onFilesWritten: () => saveHome(home),
+    onDefaults: storeDefaults,
+    // `ShareLink` shares asset-catalog images as their files. An app built
+    // with a CORS proxy retries a refused cross-origin read through it
+    // (corsProxy.ts); one built with blocked hosts never reaches them (blockedHosts.ts).
+    requests: {
+      ...browserEnvironment,
+      fetch: withBlockedHosts(
+        corsProxy ? withCORSProxy(browserEnvironment.fetch, corsProxy, location.origin) : browserEnvironment.fetch,
+        registeredApp()?.blockedHosts ?? [],
+      ),
+      assetURL: (name) => assets.images[name]?.src,
+      bitmapFile: (recipe) => bitmapStore.png(recipe),
+    },
+    onSwiftData: (op) => {
+      swiftData?.apply(op).catch((error: unknown) => console.warn('[sb] could not save to IndexedDB', error));
+    },
+  });
   setLoaded(requestedApp);
   sendEnvironment();
   flushQueuedEvents();
@@ -527,6 +641,10 @@ declare global {
        * module (or mock) has no executor.
        */
       runJobs: () => number | null;
+      /** Phase 19: the app's home as IndexedDB holds it now: path → text of each file (`null` for a directory). */
+      files: () => Promise<Record<string, string | null>>;
+      /** Phase 18: the app's SwiftData stores as IndexedDB holds them now (all saves written). */
+      swiftData: () => Promise<SwiftDataStores>;
       /** The executor driver class, so tests can run it against a stub. */
       JobScheduler: new (
         run: (nowMs: number) => number,
@@ -550,5 +668,10 @@ window.__sb = {
   assets: () => assets,
   animation: { easingFor, timingFor, springEasing },
   runJobs: () => app?.runJobs() ?? null,
+  swiftData: async () => (swiftData ? swiftData.load() : {}),
+  files: async () => {
+    const entries = files ? await files.load() : new Map<string, Uint8Array | null>();
+    return Object.fromEntries([...entries].map(([path, data]) => [path, data === null ? null : new TextDecoder().decode(data)]));
+  },
   JobScheduler,
 };

package/src/media.ts

@@ -0,0 +1,132 @@
+/**
+ * `media` host requests (docs/ops-protocol.md, "Video and audio"):
+ * AVFoundation's files and metadata probes, and QuickLook's previews.
+ *
+ * - `file` (`name`, `type`, `data` base64): a blob of the bytes; answers
+ *   `{ url }`, an object URL a `video` element can play.
+ * - `probe` (`url`): reads the media's metadata in a detached `<video>`;
+ *   answers `{ duration, width, height }` (`duration` null for a stream),
+ *   fails (`network: …`) when the browser cannot load or decode it.
+ * - `release` (`url`): revokes an object URL `file` made.
+ * - `open` (`url`, or `name` / `type` / `data`): opens the URL, or the file
+ *   as a blob, in a new tab; when the browser blocks the tab (no tap just
+ *   before), a file is downloaded instead. Answers `{ opened }`.
+ */
+
+import type { MediaRequestParams } from './protocol';
+
+/** Standard base64 to bytes (hostRequests.ts imports this module, so not from there). */
+function decode(text: string): Uint8Array {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+export interface MediaInfo {
+  duration: number | null;
+  width: number;
+  height: number;
+}
+
+/** What the page does for `media` requests; tests pass their own. */
+export interface MediaHost {
+  objectURL(blob: Blob): string;
+  revoke(url: string): void;
+  probe(url: string): Promise<MediaInfo>;
+  /** Opens `url` in a new tab; false when the browser blocked it. */
+  open(url: string): boolean;
+  download?(blob: Blob, filename: string): void;
+}
+
+export async function performMedia(params: MediaRequestParams, host: MediaHost | undefined): Promise<Record<string, unknown>> {
+  if (!host) throw new Error('unsupported: this page has no media host');
+  switch (params.action) {
+    case 'file': {
+      const blob = new Blob([decode(params.data ?? '') as BlobPart], { type: params.type ?? '' });
+      return { url: host.objectURL(blob) };
+    }
+    case 'probe': {
+      if (!params.url) throw new Error('malformed request: probe needs a url');
+      const info = await host.probe(params.url);
+      return { ...info };
+    }
+    case 'release':
+      if (params.url?.startsWith('blob:')) host.revoke(params.url);
+      return {};
+    case 'open': {
+      if (params.url !== undefined) {
+        if (!/^(https?|blob|data):/i.test(params.url)) throw new Error(`unsupported: cannot open ${params.url}`);
+        return { opened: host.open(params.url) };
+      }
+      const blob = new Blob([decode(params.data ?? '') as BlobPart], { type: params.type ?? '' });
+      const url = host.objectURL(blob);
+      if (host.open(url)) {
+        // The tab has loaded it long before then.
+        setTimeout(() => host.revoke(url), 60_000);
+        return { opened: true };
+      }
+      host.revoke(url);
+      host.download?.(blob, params.name || 'Preview');
+      return { opened: false };
+    }
+    default:
+      throw new Error(`unsupported: media action ${String((params as { action: unknown }).action)}`);
+  }
+}
+
+/** Reads metadata in a detached `<video>` (no sound, no frames beyond the first). */
+function probe(url: string): Promise<MediaInfo> {
+  return new Promise((resolve, reject) => {
+    const video = document.createElement('video');
+    video.preload = 'metadata';
+    video.muted = true;
+    const finish = (): void => {
+      video.removeAttribute('src');
+      video.load();
+    };
+    video.addEventListener(
+      'loadedmetadata',
+      () => {
+        const info = {
+          duration: Number.isFinite(video.duration) ? video.duration : null,
+          width: video.videoWidth,
+          height: video.videoHeight,
+        };
+        finish();
+        resolve(info);
+      },
+      { once: true },
+    );
+    video.addEventListener(
+      'error',
+      () => {
+        const message = video.error?.message || `could not load ${url}`;
+        finish();
+        reject(new Error(`network: ${message}`));
+      },
+      { once: true },
+    );
+    video.src = url;
+  });
+}
+
+export function browserMediaHost(download?: (blob: Blob, filename: string) => void): MediaHost | undefined {
+  if (typeof document === 'undefined' || typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') return undefined;
+  return {
+    objectURL: (blob) => URL.createObjectURL(blob),
+    revoke: (url) => URL.revokeObjectURL(url),
+    probe,
+    open: (url) => {
+      const tab = window.open(url, '_blank');
+      if (!tab) return false;
+      try {
+        tab.opener = null;
+      } catch {
+        // Another origin's window: nothing to cut.
+      }
+      return true;
+    },
+    ...(download ? { download } : {}),
+  };
+}

package/src/mock.ts

@@ -122,7 +122,8 @@ export function createCounterMock(onOps: OpsSink): MockAppHandle {
     received,
     sendEvent,
     sendEventJson(event) {
-      if (event.type === 'tap') sendEvent(event.id);
+      // A tap with a point (a `tapgesture` with `location`) is kept as sent.
+      if (event.type === 'tap' && event.x === undefined) sendEvent(event.id);
       else received.push(event);
       return true;
     },
@@ -380,8 +381,8 @@ export function galleryTextStyleIds(style: TextStyle): { styled: number; text: n
   return { styled: GALLERY_IDS.firstTextStyle + 2 * i, text: GALLERY_IDS.firstTextStyle + 2 * i + 1 };
 }
 
-const BLUE = { r: 0, g: 0.478, b: 1, a: 1 };
-const RED = { r: 1, g: 0.231, b: 0.188, a: 1 };
+const BLUE = { r: 0, g: 0.533, b: 1, a: 1 };
+const RED = { r: 1, g: 0.22, b: 0.235, a: 1 };
 const GREEN = { r: 0.204, g: 0.78, b: 0.349, a: 1 };
 
 /** The animated box: `styled{frame}` > `shape`; expanded doubles the width and swaps the fill. */

package/src/notifications.ts

@@ -0,0 +1,109 @@
+/**
+ * UserNotifications' page side (docs/ops-protocol.md, "Notifications"). The
+ * app schedules its own timers and sends a `notification` request when one
+ * comes due; the page only answers for the permission and shows what it is
+ * told to, with the browser's Notification API. Nothing is scheduled here, so
+ * nothing fires once the page is closed.
+ */
+
+import type { NotificationRequestParams } from './protocol';
+
+/** `NotificationPermission`, or no Notification API at all. */
+export type NotificationPermissionState = NotificationPermission | 'unsupported';
+
+export interface NotificationResult {
+  /** `status` and `request`. */
+  permission?: NotificationPermissionState;
+  /** `show`: whether a notification appeared. */
+  shown?: boolean;
+}
+
+/** The browser's notification facilities; tests substitute them. */
+export interface NotificationHost {
+  permission(): NotificationPermissionState;
+  requestPermission(): Promise<NotificationPermission>;
+  /** Shows a notification; resolves with whether the browser showed it. */
+  show(title: string, options: NotificationOptions): Promise<boolean>;
+  /** Closes the shown notifications with these tags. */
+  close(tags: readonly string[]): void;
+  /** `navigator.setAppBadge` (0 clears), where the browser has it. */
+  setBadge?(count: number): Promise<void>;
+}
+
+export async function performNotification(params: NotificationRequestParams, host: NotificationHost | undefined): Promise<NotificationResult> {
+  const permission = host?.permission() ?? 'unsupported';
+  switch (params.action) {
+    case 'status':
+      return { permission };
+    case 'request':
+      // The browser asks only once; after that the answer stands until the
+      // viewer changes it in the site settings.
+      if (!host || permission !== 'default') return { permission };
+      return { permission: await host.requestPermission() };
+    case 'show': {
+      if (params.badge !== undefined) await host?.setBadge?.(params.badge).catch(() => undefined);
+      if (params.title === undefined || !host || permission !== 'granted') return { shown: false };
+      const options: NotificationOptions = { silent: params.silent ?? false };
+      const body = [params.subtitle, params.body].filter((line) => line).join('\n');
+      if (body) options.body = body;
+      if (params.id) options.tag = params.id;
+      return { shown: await host.show(params.title, options) };
+    }
+    case 'close':
+      host?.close(params.ids ?? []);
+      return {};
+    case 'badge':
+      await host?.setBadge?.(params.badge ?? 0).catch(() => undefined);
+      return {};
+    default:
+      throw new Error(`unsupported: notification action ${String((params as { action: unknown }).action)}`);
+  }
+}
+
+/** The Notification API, or nothing where the browser has none (an iPhone tab not on the Home Screen). */
+export function browserNotificationHost(): NotificationHost | undefined {
+  if (typeof window === 'undefined' || typeof Notification === 'undefined') return undefined;
+  const open = new Map<string, Notification>();
+  const badgeNavigator = navigator as Navigator & { setAppBadge?: (n?: number) => Promise<void>; clearAppBadge?: () => Promise<void> };
+  return {
+    permission: () => Notification.permission,
+    requestPermission: () =>
+      new Promise((resolve) => {
+        // Older Safari takes a callback and returns nothing.
+        const result = Notification.requestPermission((answer) => resolve(answer));
+        if (result) result.then(resolve, () => resolve(Notification.permission));
+      }),
+    show: async (title, options) => {
+      try {
+        const notification = new Notification(title, options);
+        if (options.tag) open.set(options.tag, notification);
+        notification.onclick = () => {
+          window.focus();
+          notification.close();
+        };
+        notification.onclose = () => {
+          if (options.tag && open.get(options.tag) === notification) open.delete(options.tag);
+        };
+        return true;
+      } catch {
+        // Chrome on Android shows notifications only through a service worker.
+        const registration = await navigator.serviceWorker?.getRegistration().catch(() => undefined);
+        if (!registration) return false;
+        await registration.showNotification(title, options);
+        return true;
+      }
+    },
+    close: (tags) => {
+      for (const tag of tags) {
+        open.get(tag)?.close();
+        open.delete(tag);
+      }
+    },
+    ...(typeof badgeNavigator.setAppBadge === 'function'
+      ? {
+          setBadge: (count: number) =>
+            count > 0 ? badgeNavigator.setAppBadge!(count) : (badgeNavigator.clearAppBadge?.() ?? Promise.resolve()),
+        }
+      : {}),
+  };
+}

package/src/pathShape.ts

@@ -0,0 +1,156 @@
+/**
+ * Custom shapes (`shape: "path"`): a SwiftUI `Shape` drawn from its
+ * `path(in:)`. The Swift side sends the path as SVG path data for the size the
+ * element reported (`reportsSize`), so the element holds an `<svg>` whose
+ * view box is that size, stretched to the element's box until the path for a
+ * new size arrives (docs/ops-protocol.md, "Custom shapes").
+ *
+ * An update whose shape's `animatableData` changed carries `frames`: the
+ * paths at fractions of the change. When the commit animates the element,
+ * the Animator calls `playPathFrames`, which draws the frame for the
+ * animation's eased progress on each animation frame and ends on the final
+ * path; otherwise the final path is drawn at once.
+ */
+
+import type { Animation, ShapeProps } from './protocol';
+import { paintFor, type IdSource } from './chartDom';
+import { easedProgress } from './animation';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** The paths along an animated change (`index[i]` is the path at `progress[i]`). */
+export interface PathFrames {
+  progress: number[];
+  index: number[];
+  paths: string[];
+}
+
+interface PathState {
+  svg: SVGSVGElement;
+  path: SVGPathElement;
+  final: string;
+  frames: PathFrames | null;
+  /** The running playback's frame request. */
+  request: number | null;
+}
+
+const STATE = new WeakMap<HTMLElement, PathState>();
+let gradientIds = 0;
+
+/** Draws `props` (a `"path"` shape) into `el`. */
+export function applyPathShape(el: HTMLElement, props: ShapeProps): void {
+  const doc = el.ownerDocument;
+  let state = STATE.get(el);
+  if (!state || state.svg.parentElement !== el) {
+    const svg = doc.createElementNS(SVG_NS, 'svg');
+    svg.classList.add('sb-path');
+    svg.setAttribute('aria-hidden', 'true');
+    const path = doc.createElementNS(SVG_NS, 'path');
+    svg.append(doc.createElementNS(SVG_NS, 'defs'), path);
+    el.replaceChildren(svg);
+    state = { svg, path, final: '', frames: null, request: null };
+    STATE.set(el, state);
+  }
+  stop(state);
+  const { svg, path } = state;
+  const width = Number(props.size?.width) || 0;
+  const height = Number(props.size?.height) || 0;
+  if (width > 0 && height > 0) svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
+  else svg.removeAttribute('viewBox');
+  svg.setAttribute('preserveAspectRatio', 'none');
+
+  const defs = svg.querySelector('defs')!;
+  defs.replaceChildren();
+  const ids: IdSource = { next: 0, prefix: `sb-path${gradientIds++}` };
+  const bbox = { x: 0, y: 0, width, height };
+  const stroke = props.stroke;
+  const fill = props.fill ? paintFor(doc, defs, props.fill, bbox, ids) : stroke ? 'none' : 'currentColor';
+  path.style.fill = fill;
+  path.style.fillRule = props.fillRule === 'evenodd' ? 'evenodd' : 'nonzero';
+  if (stroke) {
+    path.style.stroke = stroke.color ? paintFor(doc, defs, stroke.color, bbox, ids) : 'currentColor';
+    path.style.strokeWidth = String(Number.isFinite(stroke.lineWidth) ? Math.max(0, stroke.lineWidth) : 1);
+    path.style.strokeLinecap = stroke.lineCap ?? 'butt';
+    path.style.strokeLinejoin = stroke.lineJoin ?? 'miter';
+    path.style.strokeMiterlimit = String(stroke.miterLimit ?? 10);
+    path.style.strokeDasharray = stroke.dash?.length ? stroke.dash.join(' ') : '';
+    path.style.strokeDashoffset = stroke.dashPhase ? String(stroke.dashPhase) : '';
+  } else {
+    path.style.stroke = 'none';
+  }
+  // The stroke is not scaled with a stretched view box.
+  path.setAttribute('vector-effect', 'non-scaling-stroke');
+
+  state.final = typeof props.path === 'string' ? props.path : '';
+  state.frames = validFrames(props.frames);
+  path.setAttribute('d', state.final);
+}
+
+/** Whether `el` is a path shape whose last update carried frames. */
+export function hasPathFrames(el: HTMLElement): boolean {
+  return STATE.get(el)?.frames != null;
+}
+
+/**
+ * Plays `el`'s frames in `animation`'s timing: the Animator calls it for an
+ * element whose update the commit animates. Returns whether there were frames.
+ */
+export function playPathFrames(el: HTMLElement, animation: Animation | undefined): boolean {
+  const state = STATE.get(el);
+  const frames = state?.frames;
+  if (!state || !frames) return false;
+  stop(state);
+  const view = el.ownerDocument.defaultView;
+  const now = () => view?.performance.now() ?? 0;
+  const start = now();
+  const draw = (): boolean => {
+    const elapsed = now() - start;
+    const done = isFinished(animation, elapsed);
+    state.path.setAttribute('d', done ? state.final : frameAt(frames, easedProgress(animation, elapsed)));
+    return done;
+  };
+  draw();
+  const tick = () => {
+    if (!el.isConnected || draw()) {
+      state.request = null;
+      state.path.setAttribute('d', state.final);
+      return;
+    }
+    state.request = view?.requestAnimationFrame(tick) ?? null;
+  };
+  state.request = view?.requestAnimationFrame(tick) ?? null;
+  return true;
+}
+
+/** The frame whose progress is nearest `progress`. */
+export function frameAt(frames: PathFrames, progress: number): string {
+  let best = 0;
+  let distance = Infinity;
+  for (let i = 0; i < frames.progress.length; i++) {
+    const d = Math.abs(frames.progress[i]! - progress);
+    if (d < distance) {
+      distance = d;
+      best = i;
+    }
+  }
+  return frames.paths[frames.index[best] ?? 0] ?? '';
+}
+
+function isFinished(animation: Animation | undefined, elapsed: number): boolean {
+  const delay = Math.max(0, (animation?.delay ?? 0) * 1000);
+  const duration = Math.max(0, (animation?.duration ?? 0.35) * 1000);
+  return elapsed >= delay + duration;
+}
+
+function stop(state: PathState): void {
+  if (state.request != null) {
+    state.svg.ownerDocument.defaultView?.cancelAnimationFrame(state.request);
+    state.request = null;
+  }
+}
+
+function validFrames(frames: ShapeProps['frames']): PathFrames | null {
+  if (!frames || !Array.isArray(frames.progress) || !Array.isArray(frames.index) || !Array.isArray(frames.paths)) return null;
+  if (frames.progress.length === 0 || frames.progress.length !== frames.index.length) return null;
+  return frames;
+}