@solidjs/web 2.0.0-beta.21 → 2.0.0-beta.23

package/types/jsx.d.ts

@@ -1120,7 +1120,7 @@ export namespace JSX {
 
   interface AnchorHTMLAttributes<T> extends HTMLAttributes<T> {
     download?: string | EnumeratedAcceptsEmpty | RemoveAttribute;
-    href?: string | RemoveAttribute;
+    href?: string | SerializableAttributeValue | RemoveAttribute;
     hreflang?: string | RemoveAttribute;
     ping?: string | RemoveAttribute;
     referrerpolicy?: HTMLReferrerPolicy | RemoveAttribute;
@@ -1128,6 +1128,21 @@ export namespace JSX {
     target?: "_self" | "_blank" | "_parent" | "_top" | (string & {}) | RemoveAttribute;
     type?: string | RemoveAttribute;
 
+    // Client-side navigation contract. These attributes are inert markup on
+    // their own — a routing integration that delegates anchor clicks (e.g.
+    // @solidjs/router) reads them off the element at event time. Typed here
+    // so plain `<a>` elements participate without per-router augmentation.
+    /** Marks the anchor as a client-navigation link when the integration requires explicit opt-in. */
+    link?: BooleanAttribute | RemoveAttribute;
+    /** Serialized (JSON) history state pushed alongside the navigation. */
+    state?: string | RemoveAttribute;
+    /** Suppress scroll restoration/reset after the navigation. */
+    noScroll?: BooleanAttribute | RemoveAttribute;
+    /** Replace the current history entry instead of pushing a new one. */
+    replace?: BooleanAttribute | RemoveAttribute;
+    /** Route preload intent; `"false"` disables the integration's default eager preload. */
+    preload?: boolean | "false" | RemoveAttribute;
+
     /** @experimental */
     attributionsrc?: string | RemoveAttribute;
 
@@ -1147,7 +1162,7 @@ export namespace JSX {
     alt?: string | RemoveAttribute;
     coords?: string | RemoveAttribute;
     download?: string | EnumeratedAcceptsEmpty | RemoveAttribute;
-    href?: string | RemoveAttribute;
+    href?: string | SerializableAttributeValue | RemoveAttribute;
     ping?: string | RemoveAttribute;
     referrerpolicy?: HTMLReferrerPolicy | RemoveAttribute;
     rel?: string | RemoveAttribute;

package/types/response.d.ts

@@ -23,6 +23,32 @@ export class ResponseEnvelope<T = unknown> {
  */
 export function isResponseEnvelope(value: unknown): value is ResponseEnvelope;
 
+/**
+ * Registered-symbol brand (`Symbol.for("solid.Href")`) marking URL-bearing
+ * values. Declared `unique symbol` type-side; the runtime value is the
+ * registered symbol, so separately bundled copies agree on identity.
+ */
+export declare const HREF: unique symbol;
+
+/**
+ * A URL-bearing value: coerces to its URL via `toString()` and carries the
+ * `HREF` registered-symbol brand. Integrations mint these (e.g. a router's
+ * typed path objects answer the brand from their proxy) and URL-accepting
+ * APIs like `redirect()` accept them alongside plain strings. The brand is
+ * what makes the type meaningful — every object has `toString()`.
+ */
+export interface Href {
+  [HREF]: true;
+  toString(): string;
+}
+
+/**
+ * Whether `value` is an `Href`-branded URL-bearing value. Registered-symbol
+ * check, so it stays correct across duplicated module instances — same
+ * rationale as `isResponseEnvelope`.
+ */
+export function isHref(value: unknown): value is Href;
+
 /** `ResponseInit` accepted by the response helpers, plus `revalidate`. */
 export interface ResponseHelperInit extends ResponseInit {
   /**
@@ -51,7 +77,7 @@ export interface ResponseHelperInit extends ResponseInit {
  * }
  * ```
  */
-export function redirect(url: string, init?: number | ResponseHelperInit): Response;
+export function redirect(url: string | Href, init?: number | ResponseHelperInit): Response;
 
 /**
  * Empty response requesting revalidation of the named cache keys — all of

package/types/serializer.d.ts

@@ -137,3 +137,15 @@ export function serializeJSON(value: unknown, options: JSONSerializeOptions): ()
  * settles the async values referenced inside it.
  */
 export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
+
+/**
+ * A resident, response-scoped decode table over the keyed JSON codec: apply
+ * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
+ * `resolve`. The frames client host wires one per response
+ * (`applyData: c => table.apply(c)`).
+ */
+export interface JSONDataTable {
+  apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;
+  resolve<T = unknown>(ref: { $ref: string }): T;
+}
+export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;

package/types/server-functions/client.d.ts

@@ -2,10 +2,13 @@ import { JSONCodecOptions } from "../serializer.js";
 import { ServerFunction, ServerFunctionMetadata } from "./shared.js";
 
 export {
+  ERROR_HEADER,
   FUNCTION_HEADER,
   INSTANCE_HEADER,
   SINGLE_FLIGHT_HEADER,
+  decodeErrorHeaderValue,
   decodeResponse,
+  encodeErrorHeaderValue,
   getServerFunctionMetadata,
   isServerFunction,
   subscribeFlightData,
@@ -78,6 +81,30 @@ export interface ServerFunctionsClientConfig {
    * ```
    */
   prepareRequest?: PrepareRequestHook;
+  /**
+   * Response-side integration seam — the client mirror of the handler's
+   * `transformResult`. `handle(response, ctx)` sees every response before
+   * the transport decodes it; returning anything but undefined resolves the
+   * call with that value. `capture(info)` runs synchronously at the call
+   * site (before any await) and its return arrives as `ctx.context`, so
+   * ambient per-call state (e.g. a reactive owner) survives to response
+   * time. See `createServerComponentHandler` in frame-transport for the
+   * canonical implementation.
+   */
+  responseHandler?: {
+    capture?(info: { id: string; meta: unknown }): unknown;
+    handle(
+      response: Response,
+      ctx: { id: string; meta: unknown; args: unknown[]; context: unknown }
+    ): unknown;
+  };
+  /**
+   * Encoder for argument lists JSON can't carry faithfully. JSON-safe args
+   * always go as plain JSON (no codec in the bundle); anything else throws
+   * unless this is set. Installed by `enableRichArguments()` from the
+   * rich-args entry — set directly only for custom wire encodings.
+   */
+  serializeArgs?(args: unknown[]): string | Promise<string>;
 }
 
 /**
@@ -97,10 +124,11 @@ export function configureServerFunctionsClient(config?: ServerFunctionsClientCon
  *
  * The declaration rides the metadata channel
  * (`getServerFunctionMetadata(fn)?.method === "GET"`) for routers and
- * integrations to detect, and the server enforces it: GET-declared
- * functions accept GET requests (and only GET), everything else answers
- * 405. Server-side the wrapper is identity-flavored — SSR calls stay
- * in-process.
+ * integrations to detect, and the server honors it: GET-declared functions
+ * accept GET requests in addition to the default POST transport (declaring
+ * GET grants, it does not revoke); functions that never declared GET answer
+ * GET requests with 405. Server-side the wrapper is identity-flavored — SSR
+ * calls stay in-process.
  *
  * Wrap the reference at its declaration; the compiler round-trips the call
  * in both builds:
@@ -123,9 +151,16 @@ export function GET<A extends readonly any[], R>(
  * source name as the trailing argument (dev-only metadata seeded on the
  * metadata channel; never emitted in production). Not meant for
  * hand-written code.
+ *
+ * The optional `base` targets calls at that url verbatim instead of the
+ * configured endpoint — for integrations reconstructing a callable from a
+ * server-rendered action url (e.g. a router intercepting a form submit whose
+ * `action="/_server?id=...&args=..."` came off the wire): bound arguments
+ * stay in the query string, where the server reads them for natural-encoding
+ * bodies (FormData, urlencoded).
  * @internal
  */
-export function createServerReference(id: string, name?: string): ServerFunction;
+export function createServerReference(id: string, name?: string, base?: string): ServerFunction;
 
 /**
  * Compiler ABI — only ever referenced by server-mode compiler output;

package/types/server-functions/server.d.ts

@@ -3,10 +3,13 @@ import { JSONCodecOptions } from "../serializer.js";
 import { RequestEvent } from "../server.js";
 
 export {
+  ERROR_HEADER,
   FUNCTION_HEADER,
   INSTANCE_HEADER,
   SINGLE_FLIGHT_HEADER,
+  decodeErrorHeaderValue,
   decodeResponse,
+  encodeErrorHeaderValue,
   getServerFunctionMetadata,
   isServerFunction,
   subscribeFlightData,
@@ -194,8 +197,9 @@ export function createServerReference<T extends any[], R>(
  * declaration on the reference's metadata channel
  * (`getServerFunctionMetadata(fn)?.method === "GET"`) and records the
  * declared method for the function's id so `handleServerFunctionRequest`
- * enforces it: GET-declared functions accept GET requests (and only GET),
- * everything else answers 405.
+ * honors it: GET-declared functions accept GET requests in addition to the
+ * default POST transport (declaring GET grants, it does not revoke);
+ * functions that never declared GET answer GET requests with 405.
  *
  * Wrap the reference at its declaration; the compiler round-trips the call
  * in both builds:
@@ -282,9 +286,9 @@ export interface HandleServerFunctionOptions {
 
 /**
  * Web-standard HTTP handler for server function calls: resolves the
- * function id from the request, enforces the declared method (405 when the
- * request method contradicts a `GET` declaration — or uses GET without
- * one), decodes arguments, runs the function under a request-event scope,
+ * function id from the request, gates GET dispatch on the declaration (405
+ * for a GET request to a function that never declared `GET`; POST is always
+ * accepted), decodes arguments, runs the function under a request-event scope,
  * and encodes the result (forwarding redirect/revalidation metadata
  * through headers). Mount it on the endpoint the client transport targets
  * (default `/_server`); platform adapters (h3, express, ...) convert their

package/types/server-functions/shared.d.ts

@@ -38,6 +38,35 @@ export const FUNCTION_HEADER: string;
  */
 export const INSTANCE_HEADER: string;
 
+/**
+ * Response header marking a thrown server-function error
+ * (`"X-Server-Function-Error"`). The client transport rejects with the
+ * decoded body when it is present (unless redirect/revalidation metadata
+ * marks the response as control flow). The value carries the error's
+ * message — `"true"` for thrown control-flow responses and non-Error
+ * values — encoded with `encodeErrorHeaderValue`, so integrations reading
+ * it must pass it through `decodeErrorHeaderValue`.
+ */
+export const ERROR_HEADER: string;
+
+/**
+ * Encodes an error message for the `ERROR_HEADER` value. HTTP header values
+ * are latin1 ByteStrings — `Headers.set` throws on code points above U+00FF
+ * — so plain printable-latin1 messages ride verbatim (ASCII stays
+ * byte-identical on the wire) and everything else (CJK, emoji, controls)
+ * travels percent-encoded behind a marker. `decodeErrorHeaderValue`
+ * round-trips the message exactly, astral-plane characters included (lone
+ * surrogates are replaced with U+FFFD — they cannot survive UTF-8 anyway).
+ */
+export function encodeErrorHeaderValue(value: string): string;
+
+/**
+ * Decodes an `ERROR_HEADER` value produced by `encodeErrorHeaderValue`:
+ * marked values are percent-decoded, everything else (including values from
+ * peers that never encode) passes through untouched.
+ */
+export function decodeErrorHeaderValue(value: string): string;
+
 /**
  * Header driving the single-flight protocol on both legs
  * (`"X-Single-Flight"`). On the request it opts the call into data

package/types/server.d.ts

@@ -205,6 +205,16 @@ export function setAttribute(node: Element, name: string, value: string): void;
 /** @deprecated not supported on the server side */
 export function setAttributeNS(node: Element, namespace: string, name: string, value: string): void;
 
+/**
+ * Server no-op: element claims are a client-only concern, but consumers may
+ * register isomorphically. Returns a no-op unregister function.
+ */
+export function registerElementClaim(handler: (element: Element) => void): () => void;
+/** Server no-op: returns `node` unchanged. Claims never fire during SSR. */
+export function claimElement<T extends Element>(node: T): T;
+/** Server no-op: returns `root` unchanged. Claims never fire during SSR. */
+export function claimElementTree<T extends Node>(root: T): T;
+
 /** @deprecated not supported on the server side */
 export function addEvent(node: Element, name: string, handler: () => void, delegate: boolean): void;
 

package/types-cjs/client.d.cts

@@ -66,6 +66,32 @@ export function assign(
 ): void;
 export function setAttribute(node: Element, name: string, value: string): void;
 export function setAttributeNS(node: Element, namespace: string, name: string, value: string): void;
+/**
+ * Register a consumer for compiler-emitted element claims. Compiled DOM
+ * output claims navigation-relevant elements (`a[href]`, `form[action]`) at
+ * creation, and compiler-owned writes to `href`/`action` re-invoke the same
+ * handlers — so handlers must be idempotent and must check the element's
+ * relevance themselves (rechecks can fire for any element whose
+ * `href`/`action` is written, e.g. `<link href>`). Handlers run under the
+ * reactive owner current at element creation; scope per-element state and
+ * cleanup through your own reactive system. Dormant until registered —
+ * without a handler the emitted claims are null checks. Returns an
+ * unregister function.
+ */
+export function registerElementClaim(handler: (element: Element) => void): () => void;
+/**
+ * Claim `node` for registered consumers (see `registerElementClaim`).
+ * Emitted by the compiler at element creation; idempotent by contract.
+ */
+export function claimElement<T extends Element>(node: T): T;
+/**
+ * Sweep-claim every navigation-relevant element (`a[href]`, `form[action]`)
+ * in `root` — the subtree equivalent of the per-element `claimElement`
+ * compiled output emits, for content that becomes live DOM without compiled
+ * creation code (frame streams, adopted SSR ranges). Dormant without a
+ * registered consumer.
+ */
+export function claimElementTree<T extends Node>(root: T): T;
 export function className(node: Element, value: JSX.ClassValue, prev?: JSX.ClassValue): void;
 export function setProperty(node: Element, name: string, value: any): void;
 export function setStyleProperty(node: Element, name: string, value: any): void;

package/types-cjs/core.d.cts

@@ -1,3 +1,4 @@
-export { getOwner, runWithOwner, createComponent, createRoot as root, sharedConfig, untrack, merge as mergeProps, flatten, ssrHandleError, ssrScope } from "solid-js";
+export { getOwner, runWithOwner, createComponent, createRoot as root, sharedConfig, untrack, merge as mergeProps, flatten, ssrHandleError, ssrScope, NoHydration, Hydration } from "solid-js";
 export declare const effect: (fn: any, effectFn: any, options: any) => void;
 export declare const memo: (fn: any) => import("solid-js").SourceAccessor<any>;
+export declare const runWithHydrationScope: (id: any, fn: any) => unknown;

package/types-cjs/frames/client.d.cts

@@ -0,0 +1,53 @@
+/**
+ * @solidjs/web/frames — client half. Consume frame streams into live DOM
+ * boundaries. There is deliberately no server-component API here beyond
+ * `installServerComponents()`: `dynamic` + server functions IS the client
+ * surface — a server-function call whose response is a frame stream
+ * resolves with a stable per-call-site component.
+ *
+ * Copied next to the runtime's frame d.ts files at publish (see
+ * types:copy-frames), so the relative imports below resolve in-place.
+ */
+export {
+  createFrame,
+  createFrameHost,
+  createFrameInsertable,
+  FRAME_APPLIED_EVENT
+} from "./frame-client.cjs";
+export type {
+  Frame,
+  FrameChunk,
+  FrameHost,
+  FrameHostOptions,
+  FrameOptions,
+  FrameWrite,
+  Slot,
+  SlotContext
+} from "./frame-client.cjs";
+export {
+  FRAME_STREAM_HEADER,
+  applyFrameResponse,
+  isFrameStreamResponse,
+  createServerComponentHandler
+} from "./frame-transport.cjs";
+export { createJSONDataTable } from "./serializer.cjs";
+export type { JSONDataTable } from "./serializer.cjs";
+
+import type { FrameHost } from "./frame-client.cjs";
+
+/**
+ * The app-wide frame host (created on first use): one chunk router, with
+ * codec data tables rotated per response — deserializer cross-reference
+ * space is stream-scoped by contract.
+ */
+export function getFrameHost(): FrameHost;
+
+/**
+ * Installs the server-component transport policy on the server-function
+ * client: boundary identity derives from the reactive owner captured at the
+ * call site, frame-stream responses resolve to stable per-call-site
+ * components, and document-SSR boundaries adopt their server-rendered
+ * ranges. Call once in the client entry (the package is sideEffects:false —
+ * a bare import would be tree-shaken); call again to rebind a custom host.
+ */
+export function installServerComponents(host?: FrameHost): void;

package/types-cjs/frames/frame-client.d.cts

@@ -0,0 +1,205 @@
+/**
+ * Client frame runtime — the consumer side of a frame stream. A frame
+ * renders server-owned content into a DOM boundary from a resident keyed
+ * record store: chunks are writes, not events, so application is
+ * prerequisite-driven and order-independent. Client-owned slot ranges
+ * inside the boundary are preserved across server updates — the
+ * version is a stale-guard only ("policy A"): newer content morphs in
+ * place, and teardown is `dispose()`, never a version bump.
+ */
+
+/** One transport chunk of a frame stream, addressed by frame `id`. */
+export type FrameChunk =
+  | { type: "start"; id: string; version: number }
+  | { type: "html"; id: string; version: number; html: string }
+  | { type: "fragment"; id: string; version: number; key: string; html: string }
+  | {
+      type: "reveal";
+      id: string;
+      version: number;
+      keys: string[];
+      waitForStyles?: boolean;
+      fallback?: boolean;
+    }
+  | {
+      type: "data";
+      id: string;
+      version: number;
+      key?: string;
+      node?: unknown;
+      initial?: boolean;
+      /** Eval-style hydration script — only when produced with the hydration serializer. */
+      payload?: string;
+    }
+  | {
+      type: "assets";
+      id: string;
+      version: number;
+      key: string;
+      modules?: string[];
+      styles?: string[];
+      inlineStyles?: { id: string; content?: string; attrs?: Record<string, string> }[];
+    }
+  | { type: "slot"; id: string; version: number; key: string; args: Record<string, unknown> }
+  | { type: "template"; id: string; version: number; key: string; html: string; fields: string[] }
+  | {
+      type: "block";
+      id: string;
+      version: number;
+      key: string;
+      template: string;
+      values: unknown[];
+    }
+  | { type: "complete"; id: string; version: number }
+  | { type: "error"; id: string; version: number; key?: string; error: unknown };
+
+/**
+ * Maps a wire chunk onto resident-store record writes. `data` chunks map to
+ * no records — they are response-scoped and the host applies them through
+ * its data hook.
+ */
+export function chunkToRecords(chunk: FrameChunk): Record<string, unknown>;
+
+/**
+ * One store write applied to a frame: `r` maps record keys to values
+ * (`chunkToRecords` produces these from wire chunks) and `version` is the
+ * stream stamp — an older version than the frame's current one is ignored.
+ */
+export interface FrameWrite {
+  version: number;
+  r: Record<string, unknown>;
+}
+
+/** Context passed to a slot callback. */
+export interface SlotContext {
+  /**
+   * Register cleanup for when this occurrence's range is removed from the
+   * server content, or the owning frame is disposed.
+   */
+  onCleanup(fn: () => void): void;
+  /**
+   * The range's current interior — server-rendered client content on an
+   * adopted document-SSR boot, or the previous output on a re-call. A
+   * framework binding hydrates onto it and returns `undefined` to claim it
+   * in place (zero DOM mutation).
+   */
+  existing: ChildNode[];
+}
+
+/**
+ * Client content for a server-declared slot. Direct-insert occurrences
+ * call it with empty props; render-prop occurrences pass the occurrence's
+ * resolved args (primitives literal, `{$ref}` data resolved through the
+ * host, `{$frame}` regions as marker-range fragments). Return nodes to fill
+ * the range, or `undefined` to claim `ctx.existing` untouched.
+ */
+export type Slot = (props: Record<string, unknown>, ctx: SlotContext) => Node | Node[] | undefined;
+
+export interface Frame {
+  /** Merge a write into the store and flush (morph/reveal/slot sync). */
+  apply(write: FrameWrite): void;
+  /** The active version, or undefined before the first apply. */
+  readonly version: number | undefined;
+  /** Read-only view of the resident record store. */
+  readonly store: Readonly<Record<string, unknown>>;
+  /** The stream's error record, if an `error` chunk arrived. */
+  readonly error: unknown;
+  /** Whether the named fragment has been revealed into the boundary. */
+  isRevealed(segment: string): boolean;
+  /** Tear down: slot cleanups cascade, later chunks are ignored. Idempotent. */
+  dispose(): void;
+}
+
+/**
+ * Routes a flat stream of addressed chunks to frames by id, buffering chunks
+ * for frames that have not registered yet (only the newest version's chunks
+ * are kept). `data` chunks are response-scoped and go to `applyData`.
+ *
+ * An id may have several frames (the same server component mounted more
+ * than once): chunks fan out to all of them, and a frame registering after
+ * delivery is seeded from a sibling's store.
+ */
+export interface FrameHost {
+  register(id: string, frame: Frame): void;
+  /** Remove one frame (or all frames of the id when `frame` is omitted). */
+  unregister(id: string, frame?: Frame): void;
+  apply(chunk: FrameChunk): void;
+  /** The first registered frame under the id, if any. */
+  get(id: string): Frame | undefined;
+  serialize(value: unknown): { $ref: string };
+  /** `frameId` is the resolving frame's id — route to its stream's table. */
+  resolve(ref: { $ref: string }, frameId?: string): unknown;
+}
+
+/**
+ * The bubbling DOM event (`"frame:applied"`) a frame dispatches from its
+ * parent element whenever server content lands in the document — root
+ * materialize/morph, segment reveal, fallback materialization — with
+ * `detail: { id, version, reason }`. One document-level listener sees every
+ * boundary (nested region frames dispatch too); use it to re-apply
+ * client-owned decorations on server-owned markup (router affordance
+ * reflection, e.g. `aria-current`) without a MutationObserver.
+ */
+export const FRAME_APPLIED_EVENT: "frame:applied";
+
+/** Options for `createFrameHost`. */
+export interface FrameHostOptions {
+  /**
+   * Backs `{$ref}` slot args (typically a codec data table's `resolve`).
+   * `frameId` identifies the resolving frame — data tables are
+   * response-scoped, so multi-stream hosts route by it (nested region ids
+   * prefix-match their root).
+   */
+  resolve?(ref: { $ref: string }, frameId?: string): unknown;
+  /** Test/host-side counterpart of `resolve`. */
+  serialize?(value: unknown): { $ref: string };
+  /**
+   * Receives each `data` chunk whole. Wire a codec table:
+   * `applyData: c => table.apply(c)` (see `createJSONDataTable`).
+   */
+  applyData?(chunk: Extract<FrameChunk, { type: "data" }>): void;
+}
+
+export function createFrameHost(options?: FrameHostOptions): FrameHost;
+
+/** Options for `createFrame` / `createFrameInsertable`. */
+export interface FrameOptions {
+  /** Register with this host under `id`, receiving routed/buffered chunks. */
+  host?: FrameHost;
+  id?: string;
+  /** Client content keyed by prop name (occurrences resolve by prop). */
+  slots?: Record<string, Slot>;
+  /**
+   * Adopt existing server-rendered DOM: the first apply morphs against it,
+   * and slots sync immediately (hydration attach) — a document-SSR boot
+   * needs no chunk.
+   */
+  adopt?: boolean;
+  /** Called after each apply flush (tests/telemetry). */
+  onApply?(info: { version: number; reason: "materialize" | "morph" | "reveal" }): void;
+  /**
+   * Wraps element-claim sweeps (`a[href]`/`form[action]` in materialized
+   * server content — and only those) so claim consumers register their
+   * per-element cleanup against the boundary's reactive owner, e.g.
+   * `fn => runWithOwner(owner, fn)`. Nested region frames inherit it.
+   * Without it, sweeps run under whatever owner is current (none, for
+   * streamed chunks).
+   */
+  ownerScope?<T>(fn: () => T): T;
+}
+
+/** A frame rendering into an element boundary. */
+export function createFrame(boundary: Element, options?: FrameOptions): Frame;
+
+/**
+ * A branded frame-insertable value: the client runtime's `insert` recognizes
+ * it (registered `$$FRAME` symbol) and calls the mount handler the value
+ * carries — a comment range is established at the insertion point and a
+ * host-registered frame binds to it. One static mount per value; lifecycle
+ * belongs to the creator via `dispose()` (register it with your owner's
+ * cleanup).
+ */
+export function createFrameInsertable(options: FrameOptions): {
+  readonly frame: Frame | null;
+  dispose(): void;
+};