@kitn.ai/ui 0.25.2 → 0.27.0

package/src/agent-tooling/recipes/index.ts

@@ -0,0 +1,22 @@
+import type { CodeRecipe } from './types';
+import { composedThread } from './composed-thread';
+
+export type { CodeRecipe, CodeRecipeFile } from './types';
+
+/**
+ * The code-recipe registry.
+ *
+ * Registered here → served by `component_reference({ name: "<id>" })` AND
+ * compiled by `verify:scaffold` (which loads this list through the registry
+ * bundle, so adding an entry moves that gate's printed cell count by itself —
+ * the same derive-don't-list contract as the integration and surface axes).
+ */
+export const codeRecipes: CodeRecipe[] = [composedThread];
+
+export function listCodeRecipes(): CodeRecipe[] {
+  return codeRecipes;
+}
+
+export function getCodeRecipe(id: string): CodeRecipe | undefined {
+  return codeRecipes.find((r) => r.id === id);
+}

package/src/agent-tooling/recipes/types.ts

@@ -0,0 +1,32 @@
+/**
+ * A CODE recipe: a complete, compiling composition the MCP serves as files.
+ *
+ * Distinct from a `TSurfaceRecipe` (../catalog/catalog-types.ts) on purpose:
+ * the catalog record is DATA — ingredients, wiring edges, invariants, each
+ * resolved and executed by its own guards — while a code recipe is the full
+ * host module a builder pastes. The two meet on `id`: a code recipe whose id
+ * also names a surface recipe is that record's body.
+ *
+ * `verify:scaffold` compiles every `lang: 'ts'` file of every registered code
+ * recipe with a stock consumer tsconfig, resolving `@kitn.ai/ui` through the
+ * shipped exports map — the same gate the scaffolder's emitted string literals
+ * go through, because this code is string literals with the same failure mode.
+ */
+export interface CodeRecipeFile {
+  /** Path inside the consumer's app, e.g. `src/main.ts`. */
+  path: string;
+  lang: 'ts' | 'html' | 'css';
+  code: string;
+}
+
+export interface CodeRecipe {
+  /** Kebab-case id, e.g. `composed-thread`. Also the component_reference topic name. */
+  id: string;
+  title: string;
+  intent: string;
+  /** The kai-* tags the composition places. */
+  ingredients: string[];
+  /** The teaching notes served above the files — the WHY a prop table cannot carry. */
+  notes: string[];
+  files: CodeRecipeFile[];
+}

package/src/agent-tooling/registry.ts

@@ -23,6 +23,11 @@ export {
   type SurfaceProbe,
 } from './archetypes';
 
+// The code-recipe axis, same contract as the two above: the gate loads it from
+// this registry bundle, so registering a recipe adds its compile cells without
+// touching the verify script.
+export { listCodeRecipes, getCodeRecipe, type CodeRecipe, type CodeRecipeFile } from './recipes';
+
 // Order is the order a scaffolding agent reads them in. `openai` and `anthropic`
 // lead because they are the two keys a developer is most likely to already hold.
 export const integrations: Integration[] = [
@@ -72,10 +77,18 @@ export interface GatewayGroup {
  *
  * THE ORDER OF THE TESTS IS THE DESIGN, not an implementation detail:
  *
- *   1. No route at all -> **No backend**. Exactly `mock` today, and derived from
- *      the absence rather than from `id === 'mock'` or `category === 'mock'`: a
- *      second no-backend entry (a canned transcript player, say) should land in
- *      this group without editing this function.
+ *   1. `keyExposure === 'frontend-safe' && outOfBand === 'none'` -> **No
+ *      backend**. Exactly `mock` today, and still derived from declared facts
+ *      rather than from `id === 'mock'` or `category === 'mock'`: a second
+ *      no-backend entry (a canned transcript player, say) lands here by
+ *      declaring the same two. This USED to be "has no route at all", and the
+ *      G-04 fix broke that derivation on purpose: mock now ships an OPTIONAL
+ *      route (the same responder frames over HTTP), and a route the app runs
+ *      fine without must not move its heading. What "no backend" really claims
+ *      is that the browser can do the whole job — nothing secret or server-only
+ *      (frontend-safe) and nothing to install or start out of band ('none') —
+ *      so that pair is the derivation. `ollama` is the near-miss that keeps it
+ *      honest: frontend-safe, but 'local-server' — something must be listening.
  *   2. `outOfBand !== 'none'` -> **Bring a server or runtime**, and this is
  *      checked BEFORE the key test on purpose. `pydantic-ai` needs both a python
  *      runtime and OPENAI_API_KEY; the groups are not disjoint in reality, so
@@ -92,8 +105,12 @@ export interface GatewayGroup {
  * wrong about that one entry; this is the derivation, so this is the answer.
  */
 export function listGatewayGroups(): GatewayGroup[] {
-  const hasRoute = (i: Integration) =>
-    i.webRoute !== undefined || Object.keys(i.routeTemplates).length > 0;
+  // The browser can do the whole job: nothing secret or server-only, nothing to
+  // install or start. NOT "has no route" — mock's G-04 route is optional, and a
+  // route the app runs fine without must not move its heading (see the comment
+  // above).
+  const selfContained = (i: Integration) =>
+    i.keyExposure === 'frontend-safe' && i.outOfBand === 'none';
 
   const groups: GatewayGroup[] = [
     { id: 'no-backend', title: 'No backend', integrations: [] },
@@ -103,7 +120,7 @@ export function listGatewayGroups(): GatewayGroup[] {
   const into = (id: GatewayGroup['id']) => groups.find((g) => g.id === id)!;
 
   for (const integration of integrations) {
-    if (!hasRoute(integration)) into('no-backend').integrations.push(integration);
+    if (selfContained(integration)) into('no-backend').integrations.push(integration);
     else if (integration.outOfBand !== 'none') into('bring-a-server').integrations.push(integration);
     else into('bring-a-key').integrations.push(integration);
   }

package/src/agent-tooling/route-emit.ts

@@ -135,9 +135,33 @@ const CHAT_REQUEST_BODY_DECL = [
   `  tools?: unknown[];`,
   `};`,
   ``,
-  `/** Narrow the JSON body once, at the edge. */`,
+  `class ChatRequestError extends Error {`,
+  `  constructor(readonly status: number, message: string) { super(message); }`,
+  `}`,
+  ``,
+  `/** Narrow the JSON body once, at the edge. A bare GET, a malformed body, or a`,
+  ` *  missing messages array is a ChatRequestError with a status — NEVER an`,
+  ` *  unhandled SyntaxError: one killed a Vite dev server (findings F-10). */`,
   `async function readChatRequest(request: Request): Promise<ChatRequestBody> {`,
-  `  return (await request.json()) as ChatRequestBody;`,
+  `  if (request.method !== 'POST') {`,
+  `    throw new ChatRequestError(405, \`Method \${request.method} not allowed — POST /api/chat.\`);`,
+  `  }`,
+  `  let parsed: unknown;`,
+  `  try { parsed = await request.json(); } catch {`,
+  `    throw new ChatRequestError(400, 'Request body is not valid JSON.');`,
+  `  }`,
+  `  const body = parsed as ChatRequestBody;`,
+  `  if (!Array.isArray(body?.messages)) {`,
+  `    throw new ChatRequestError(400, 'Request body must carry a messages array.');`,
+  `  }`,
+  `  return body;`,
+  `}`,
+  ``,
+  `/** Map a guard rejection to the Response its status demands; rethrow anything`,
+  ` *  else — an unexpected error should be loud, not laundered into a 400. */`,
+  `function toChatErrorResponse(error: unknown): Response {`,
+  `  if (error instanceof ChatRequestError) return Response.json({ error: error.message }, { status: error.status });`,
+  `  throw error;`,
   `}`,
 ];
 

package/src/components/attachment-types.ts

@@ -5,9 +5,62 @@ export interface AttachmentData {
   type: 'file' | 'source-document';
   filename?: string;
   mediaType?: string;
+  /** A `data:` URI or an https URL — this is the field the wire encodes, so it
+   *  is what reaches the model. NEVER `URL.createObjectURL`: an object URL
+   *  resolves only inside the tab that minted it, so a `blob:` URL renders a
+   *  flawless preview and is meaningless to any provider —
+   *  `toOpenAIMessages`/`toAnthropicMessages` refuse it rather than send an
+   *  address the model cannot fetch. Read picked files with
+   *  `FileReader.readAsDataURL` instead (see `elements/default-input.tsx`). */
   url?: string;
   title?: string;
 }
 
-export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
+/**
+ * How an attachment is DRAWN, derived from what the wire can do with it.
+ *
+ * ★ THIS IS NOT A LIST OF MEDIA TYPES, and that is the whole point. It used to
+ * be one in disguise (`image | video | audio | document`, decided by a prefix
+ * switch in `attachments.tsx`), and it disagreed with `wire/media-types.ts` in
+ * both directions: SVG and MP4 drew a convincing preview that then threw at
+ * encode time, while PDF and text — the formats the wire handles best — drew
+ * the same anonymous icon as a `.zip`. `getMediaCategory` now asks the media
+ * policy and returns what it says, so there is one declaration and this is a
+ * projection of it.
+ *
+ * `image` / `document` / `text` ARE `EncodableKind` from `wire/media-types.ts`.
+ * They are spelled out rather than imported because this module is deliberately
+ * JSX-free and dependency-free for the framework-neutral consumers; the runtime
+ * agreement is pinned by `attachment-media-policy.test.tsx`, whose drift guard
+ * derives both sides from the policy.
+ *
+ * `video` and `audio` are GONE on purpose. No wire this kit ships can carry
+ * either, so they were categories whose only job was to make an unsendable file
+ * look sendable; both now land in `unsendable`.
+ */
+export type AttachmentMediaCategory =
+  /** A raster image in one of the four formats both APIs document. */
+  | 'image'
+  /** A PDF. Named for the Anthropic `document` block it becomes. */
+  | 'document'
+  /** Text content — `text/*`, JSON, XML, YAML. Rides as text on both wires. */
+  | 'text'
+  /** A RAG citation chip, not something the user staged. Never encoded. */
+  | 'source'
+  /**
+   * No wire format this kit ships can carry this type — SVG, BMP, video, audio,
+   * archives. That is a fact about the kit's encoders, knowable at render time
+   * and true of every provider, which is why it is safe to show the user.
+   *
+   * It is NOT "this will fail to send": the renderer does not know which
+   * provider a thread is bound for, and must not pretend to.
+   */
+  | 'unsendable'
+  /**
+   * Nobody named this file, so nothing is known yet. Its bytes decide it (see
+   * `classifyAttachment`), and they have not been read at render time. Marking
+   * it `unsendable` would be a guess wearing a fact's clothes.
+   */
+  | 'unknown';
+
 export type AttachmentVariant = 'grid' | 'inline' | 'list';

package/src/components/attachments.tsx

@@ -3,14 +3,15 @@ import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
 import { HoverCardRoot, HoverCardTrigger, HoverCardContent } from '../ui/hover-card';
 import {
+  FileCode,
   FileText,
+  FileX,
   Globe,
   Image as ImageIcon,
-  Music2,
   Paperclip,
-  Video,
   X,
 } from 'lucide-solid';
+import { DEFAULT_MEDIA_POLICY } from '../wire/media-types';
 import type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
 export type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
 
@@ -18,32 +19,86 @@ export type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from
 // Types
 // ============================================================================
 
+/** One icon per category, and the categories are the wire's own kinds — so the
+ *  set is exhaustive by construction and a kind added to `EncodableKind` is a
+ *  compile error HERE rather than an `undefined` icon at runtime.
+ *
+ *  PDF and text get different glyphs deliberately. They are the two formats the
+ *  wire handles best and they used to share the anonymous fallback icon with a
+ *  `.zip`, which is the inversion this whole change is about. */
 const mediaCategoryIcons: Record<AttachmentMediaCategory, typeof ImageIcon> = {
-  audio: Music2,
   document: FileText,
   image: ImageIcon,
   source: Globe,
+  text: FileCode,
   unknown: Paperclip,
-  video: Video,
+  unsendable: FileX,
 };
 
 // ============================================================================
 // Utility Functions
 // ============================================================================
 
+/**
+ * What to DRAW for this attachment, asked of the one module that knows.
+ *
+ * ★ NO MEDIA TYPES APPEAR BELOW, and that is the fix. This function used to be
+ * a prefix switch — `image/` → image, `video/` → video, `application/` or
+ * `text/` → document — a second list of media types in a repo whose media-type
+ * declaration says, at its own definition, "if you find yourself writing a
+ * second list of media types anywhere in this repo, delete it and read this".
+ * It had drifted in both directions: `image/svg+xml` came back `image` and drew
+ * a real thumbnail for a format the encoder refuses outright, while
+ * `application/json` came back `document` when the wire carries it as text.
+ *
+ * `DEFAULT_MEDIA_POLICY` and not a narrowed one, on purpose. A developer's
+ * `accept` filter says what a user may STAGE; it says nothing about what an
+ * already-staged attachment IS, and narrowing here would redraw a message
+ * retroactively when a host changed a prop. The default policy is the kit's
+ * full capability set, so `unsupported` against it means exactly "no wire
+ * format this kit ships can carry this" — which is the only claim about
+ * sendability the renderer can honestly make without knowing the provider.
+ */
 export const getMediaCategory = (data: AttachmentData): AttachmentMediaCategory => {
+  // A citation chip is not an upload and never reaches an encoder — see the
+  // `kit-side` classification in `wire/files.ts`. Asking the policy about it
+  // would be asking the wrong question.
   if (data.type === 'source-document') {
     return 'source';
   }
 
-  const mediaType = data.mediaType ?? '';
-
-  if (mediaType.startsWith('image/')) return 'image';
-  if (mediaType.startsWith('video/')) return 'video';
-  if (mediaType.startsWith('audio/')) return 'audio';
-  if (mediaType.startsWith('application/') || mediaType.startsWith('text/')) return 'document';
+  const decision = DEFAULT_MEDIA_POLICY.decide(data.mediaType);
+  switch (decision.status) {
+    // The wire's kind IS the rendering category. Not mapped, not translated.
+    case 'allowed':
+      return decision.kind;
+    case 'unsupported':
+      return 'unsendable';
+    // Nobody named the file, so its bytes decide it and they have not been read
+    // here. `filtered` cannot occur against the unnarrowed default policy, but
+    // it means "the kit could have sent this" — also not unsendable. Both are
+    // honestly `unknown`, and no `default:` branch exists so a new
+    // `MediaDecision` variant is a compile error rather than a silent guess.
+    case 'undetermined':
+    case 'filtered':
+      return 'unknown';
+  }
+};
 
-  return 'unknown';
+/**
+ * The fact, written out, for the one category where the kit knows something the
+ * user needs to know.
+ *
+ * A FACT ABOUT THE FORMATS, NOT A PREDICTION ABOUT THIS REQUEST. At render time
+ * the kit does not know which provider the thread is bound for, so "this will
+ * fail" is not its to say. What it does know is that no wire format it ships
+ * has any representation for the type at all, which is true of every provider
+ * and is what this sentence claims.
+ */
+export const getUnsendableNote = (data: AttachmentData): string | undefined => {
+  if (getMediaCategory(data) !== 'unsendable') return undefined;
+  const type = data.mediaType?.trim() || 'This file type';
+  return `${type} is not one of the attachment formats a model request can carry.`;
 };
 
 export const getAttachmentLabel = (data: AttachmentData): string => {
@@ -133,6 +188,7 @@ function Attachment(props: AttachmentProps) {
   // once and the item never re-lays-out when the container variant changes.
   const ctx = useAttachmentsContext();
   const mediaCategory = () => getMediaCategory(local.data);
+  const unsendable = () => getUnsendableNote(local.data);
 
   return (
     <AttachmentContext.Provider
@@ -159,8 +215,35 @@ function Attachment(props: AttachmentProps) {
           ],
           local.class,
         )}
+        // ★ A STABLE HANDLE ON "THIS IS AN ATTACHMENT", published the way this
+        // kit publishes them (`part="row"`, `part="bubble content"`,
+        // `part="citations"`). Consumers get a `::part(attachment)` styling seam
+        // — and, just as importantly, anything asserting on the rendering gets
+        // something to key on that is not a class name or a position.
+        //
+        // That is not a hypothetical convenience. The conformance harness pinned
+        // this component by `span.truncate` and broke the day the thread moved
+        // from the inline chip to the grid tile; the obvious repair — "the
+        // innermost div holding both the media icon and the filename" — was
+        // measured to be WORSE, because when the filename is missing `.last()`
+        // slides silently up to the assistant's message row, which contains the
+        // tool panel echoing the same filename in its JSON. The assertion then
+        // passes while the user sees an anonymous grey box. A position that
+        // still resolves, to the wrong node, is the failure that stays green.
+        part="attachment"
+        // The mark lives on the ITEM rather than on `<AttachmentPreview>`,
+        // because the sub-parts are optional in composition — a consumer who
+        // renders only an `<AttachmentInfo>` still has to be told. `title` is
+        // the mouse affordance; the `sr-only` line inside is what actually
+        // carries the fact to assistive tech and to a test. `rest` is spread
+        // after both, so a consumer's own `title` still wins.
+        data-unsendable={unsendable() === undefined ? undefined : ''}
+        title={unsendable()}
         {...rest}
       >
+        <Show when={unsendable()}>
+          {(note) => <span class="sr-only">{note()}</span>}
+        </Show>
         {local.children}
       </div>
     </AttachmentContext.Provider>
@@ -182,10 +265,24 @@ function AttachmentPreview(props: AttachmentPreviewProps) {
   const iconSize = () => ctx.variant === 'inline' ? 'size-3' : 'size-4';
 
   const renderIcon = (Icon: typeof ImageIcon) => (
-    <Icon class={cn(iconSize(), 'text-muted-foreground')} />
+    <Icon
+      class={cn(
+        iconSize(),
+        // The one visible half of the mark. `warning` is an existing theme
+        // token, not a new colour for this state.
+        ctx.mediaCategory === 'unsendable' ? 'text-warning' : 'text-muted-foreground',
+      )}
+    />
   );
 
   const renderContent = () => {
+    // ★ ONLY `image` GETS A REAL PREVIEW, and `image` now means "a raster format
+    // some wire can actually carry" because the category comes from the media
+    // policy. There used to be a `video` branch here that mounted a real
+    // <video> for a file no encoder in this kit can represent: a preview that
+    // looks like it worked, in front of a send that throws. An SVG reached the
+    // <img> branch for the same reason. Both are `unsendable` now and fall
+    // through to the marked icon below.
     if (ctx.mediaCategory === 'image' && ctx.data.type === 'file' && ctx.data.url) {
       return ctx.variant === 'grid' ? (
         <img
@@ -206,10 +303,6 @@ function AttachmentPreview(props: AttachmentPreviewProps) {
       );
     }
 
-    if (ctx.mediaCategory === 'video' && ctx.data.type === 'file' && ctx.data.url) {
-      return <video class="size-full object-cover" muted src={ctx.data.url} />;
-    }
-
     const Icon = mediaCategoryIcons[ctx.mediaCategory];
     return local.fallbackIcon ?? renderIcon(Icon);
   };
@@ -244,14 +337,68 @@ function AttachmentInfo(props: AttachmentInfoProps) {
   const label = () => getAttachmentLabel(ctx.data);
 
   return (
-    <Show when={ctx.variant !== 'grid'}>
-      <div class={cn('min-w-0 flex-1', local.class)} {...rest}>
+    <Show
+      when={ctx.variant !== 'grid'}
+      fallback={
+        /*
+         * ★ A GRID TILE IS SELF-DESCRIBING ONLY WHEN IT IS AN IMAGE.
+         *
+         * A tile used to render no label at all, on the theory that it is "a
+         * self-contained visual". True of a photo; false of a PDF, a zip or a
+         * text file, which draw a 16px glyph on a grey square and are otherwise
+         * anonymous. The name was reachable by hover (pointer only) and by an
+         * `sr-only` line (assistive tech only), which between them serve
+         * everyone EXCEPT a sighted keyboard user and a sighted touch user —
+         * measured in a real browser as `visibleText: ""` on every non-image
+         * tile, with no focusable element inside any of them.
+         *
+         * So a non-image tile carries a visible, truncated caption and needs no
+         * interaction of any kind. An image tile still carries none: the image
+         * is the content, and stamping a filename over it is noise. That is
+         * also why the `sr-only` label was REMOVED from `<AttachmentPreview>`
+         * rather than kept alongside this — an image has `alt`, everything else
+         * now has this, and keeping both would announce the name twice.
+         */
+        <Show when={ctx.mediaCategory !== 'image'}>
+          {/* A `div`, not a `span` — `AttachmentInfoProps` extends
+              `JSX.HTMLAttributes<HTMLDivElement>`, so `rest` carries a
+              div-typed `ref` and the other branch below is a div too. */}
+          <div
+            class={cn(
+              'absolute inset-x-0 bottom-0 truncate px-1.5 py-1 text-caption',
+              'bg-background/85 backdrop-blur-sm',
+              ctx.mediaCategory === 'unsendable' ? 'text-warning' : 'text-foreground',
+              local.class,
+            )}
+            part="attachment-name"
+            {...rest}
+          >
+            {label()}
+          </div>
+        </Show>
+      }
+    >
+      {/* Same `part` in both branches: an assertion (or a consumer's CSS) that
+          asks for the attachment's name must not have to know which variant is
+          rendering. That is the whole point of publishing it. */}
+      <div class={cn('min-w-0 flex-1', local.class)} part="attachment-name" {...rest}>
         <span class="block truncate">{label()}</span>
         {/* The media-type subtitle is a two-line affordance — only the `list`
-            variant has room for it; `inline` chips are a fixed single-line height. */}
-        <Show when={local.showMediaType && ctx.variant === 'list' && ctx.data.mediaType}>
-          <span class="text-muted-foreground text-caption block truncate">
-            {ctx.data.mediaType}
+            variant has room for it; `inline` chips are a fixed single-line height.
+            The unsendable line rides in the same slot and WINS it, because "no
+            wire can carry this" is the more useful half of the same sentence. */}
+        <Show
+          when={ctx.mediaCategory === 'unsendable' && ctx.variant === 'list'}
+          fallback={
+            <Show when={local.showMediaType && ctx.variant === 'list' && ctx.data.mediaType}>
+              <span class="text-muted-foreground text-caption block truncate">
+                {ctx.data.mediaType}
+              </span>
+            </Show>
+          }
+        >
+          <span class="text-warning text-caption block truncate">
+            {ctx.data.mediaType ? `${ctx.data.mediaType} · ` : ''}unsupported attachment format
           </span>
         </Show>
       </div>

package/src/components/audio-visualizer/fit-scale.ts

@@ -0,0 +1,112 @@
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+
+/**
+ * Fit-to-container scaling: the size tiers are fixed
+ * px by design (`sizes.ts`), so a container narrower than a tier's natural
+ * footprint used to CLIP the picture at its edges. The dispatcher now scales
+ * the WHOLE visualization down proportionally to fit, and renders byte-equal
+ * to the designed px metrics whenever the container is at least natural size.
+ *
+ * Why a transform-scale wrapper rather than relative units or reflow:
+ * - The px tiers ARE the design (LiveKit parity); switching the geometry to
+ *   relative units would change rendering at every container size, not just
+ *   the overflowing ones.
+ * - Reflowing (fewer bars, smaller gaps) changes what the animation MEANS;
+ *   proportional scale keeps the exact picture, just smaller.
+ * - A transform also covers the shader variants for free: their canvases size
+ *   their backing store from layout size (`clientWidth`), which a transform
+ *   does not change, so the bitmap stays at full natural resolution and only
+ *   the composited output shrinks. No variant needs an exception.
+ *
+ * Both sizes are MEASURED (one ResizeObserver watching both wrappers), never
+ * restated from `sizes.ts`: the natural footprint depends on variant, size
+ * tier, barCount/count/radius and the consumer's own part styling, and a
+ * hand-derived width table would rot the day any of those moved.
+ *
+ * Where ResizeObserver does not exist (SSR, jsdom) this is inert: scale stays
+ * 1 and nothing is written, which is exactly the pre-fix rendering.
+ */
+export function computeFitScale(
+  available: number | undefined,
+  natural: number | undefined,
+): number {
+  if (
+    available === undefined || natural === undefined ||
+    !Number.isFinite(available) || !Number.isFinite(natural) ||
+    available <= 0 || natural <= 0
+  ) {
+    return 1;
+  }
+  return Math.min(1, available / natural);
+}
+
+export interface FitScale {
+  /** Ref for the outer wrapper (the host box, clamped by `max-width: 100%`). */
+  observeOuter: (el: HTMLElement) => void;
+  /** Ref for the inner wrapper (the natural-size content that gets scaled). */
+  observeInner: (el: HTMLElement) => void;
+  /** 1 when the content fits; the proportional shrink factor when it does not. */
+  scale: Accessor<number>;
+  /** The scaled content height in px while shrunk, else undefined: the outer
+   *  wrapper adopts it so the page never reserves the unscaled height. */
+  scaledHeight: Accessor<number | undefined>;
+}
+
+/**
+ * One ResizeObserver over both wrappers. ResizeObserver reports layout
+ * (border-box/content-box) sizes, which CSS transforms do not affect, so the
+ * inner wrapper keeps reporting its NATURAL size even while scaled, and the
+ * outer wrapper (whose `max-width: 100%` is what lets a narrow parent
+ * actually constrain it) reports the width the container is offering. The
+ * ratio of the two is the scale, with `computeFitScale` guarding the
+ * unmeasured/degenerate cases to 1 so a bad reading can never blank the
+ * element.
+ */
+export function createFitScale(): FitScale {
+  const [availableWidth, setAvailableWidth] = createSignal<number>();
+  const [naturalWidth, setNaturalWidth] = createSignal<number>();
+  const [naturalHeight, setNaturalHeight] = createSignal<number>();
+
+  let outerEl: HTMLElement | undefined;
+  let innerEl: HTMLElement | undefined;
+  let observer: ResizeObserver | undefined;
+
+  const ensureObserver = (): ResizeObserver | undefined => {
+    if (observer) return observer;
+    if (typeof ResizeObserver === 'undefined') return undefined;
+    observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        // contentRect, not borderBoxSize: identical for these padding-less
+        // wrappers and present everywhere this runs.
+        if (entry.target === outerEl) setAvailableWidth(entry.contentRect.width);
+        if (entry.target === innerEl) {
+          setNaturalWidth(entry.contentRect.width);
+          setNaturalHeight(entry.contentRect.height);
+        }
+      }
+    });
+    return observer;
+  };
+
+  onCleanup(() => observer?.disconnect());
+
+  const scale = () => computeFitScale(availableWidth(), naturalWidth());
+  const scaledHeight = () => {
+    const k = scale();
+    const h = naturalHeight();
+    return k < 1 && h !== undefined && h > 0 ? h * k : undefined;
+  };
+
+  return {
+    observeOuter: (el) => {
+      outerEl = el;
+      ensureObserver()?.observe(el);
+    },
+    observeInner: (el) => {
+      innerEl = el;
+      ensureObserver()?.observe(el);
+    },
+    scale,
+    scaledHeight,
+  };
+}