@unpunnyfuns/swatchbook-blocks 1.1.1 → 2.0.0

package/dist/index.d.mts

@@ -1,162 +1,10 @@
-import { COLOR_FORMATS, ColorFormat } from "@unpunnyfuns/swatchbook-core/color-formats";
-import { FormatColorResult, NormalizedColor, formatColor } from "@unpunnyfuns/swatchbook-core/format-color";
-import * as _$react from "react";
+import { C as useOptionalSwatchbookData, D as NormalizedColor, E as FormatColorResult, O as formatColor, S as useColorFormat, T as ColorFormat, _ as VirtualTokenGraph, a as usePresenter, b as useActiveAxes, c as PresenterRegistry, d as ProjectSnapshot, f as SwatchbookContext, g as VirtualPresetShape, h as VirtualDiagnosticShape, l as AxesContext, m as VirtualAxisShape, n as PresenterContext, o as PresenterComponent, p as ThemeContext, r as mergePresenters, s as PresenterProps, t as DEFAULT_PRESENTERS, u as ColorFormatContext, v as VirtualTokenListing, w as COLOR_FORMATS, x as useActiveTheme, y as VirtualTokenShape } from "./registry-Dm25Go94.mjs";
 import { ReactElement, ReactNode } from "react";
-import { TokenGraph } from "@unpunnyfuns/swatchbook-core/graph";
-import { Axis, Diagnostic, Preset } from "@unpunnyfuns/swatchbook-core";
-import { SlimListedToken } from "@unpunnyfuns/swatchbook-core/snapshot-for-wire";
+import { formatTokenValue } from "@unpunnyfuns/swatchbook-core/token-value-css";
+import { Axis } from "@unpunnyfuns/swatchbook-core";
+import { SnapshotForWire } from "@unpunnyfuns/swatchbook-core/snapshot-for-wire";
+import { RealisedToken, RealisedToken as RealisedToken$1, TokenType } from "@unpunnyfuns/swatchbook-core/token-value-types";
 
-//#region src/contexts.d.ts
-/**
- * Typed shape of the addon's `virtual:swatchbook/tokens` module.
- *
- * The axis / permutation / diagnostic / preset entries are deliberate
- * type-aliases of core's authoritative shapes — the virtual module
- * publishes those shapes verbatim, so single-sourcing the types prevents
- * silent drift the moment core grows a field the plugin doesn't
- * serialise.
- *
- * Token / listing shapes stay as narrowed interfaces because blocks
- * only read a subset of Terrazzo's full token / listing structure; the
- * narrower shape documents what's actually relied on.
- *
- * The ambient `declare module 'virtual:swatchbook/tokens'` declarations
- * in `packages/addon/src/virtual.d.ts` describe the same payload.
- */
-type VirtualAxisShape = Axis;
-type VirtualDiagnosticShape = Diagnostic;
-interface VirtualTokenShape {
-  $type?: string | undefined;
-  $value?: unknown;
-  $description?: string | undefined;
-  /**
-   * DTCG `$deprecated` — `true` or a message string. Mirrors core's
-   * `SwatchbookToken.$deprecated`; reaches blocks via the resolved token
-   * map reconstructed from the wire `tokenGraph`.
-   */
-  $deprecated?: string | boolean | undefined;
-  aliasOf?: string | undefined;
-  aliasChain?: readonly string[] | undefined;
-  aliasedBy?: readonly string[] | undefined;
-  /**
-   * Per-sub-field alias map for composite tokens whose value blends
-   * primitives with aliased fragments — Terrazzo populates this when
-   * one or more component fields of a composite ($type: 'border',
-   * 'shadow', 'typography', 'gradient', 'transition') resolve through
-   * an alias. The `CompositeBreakdown` block reads it to render the
-   * source path beside each component value. Typed as `unknown` because
-   * the shape varies per composite type (color carries a
-   * `{components: (string | undefined)[]}` sub-shape; typography/border
-   * carry a flat `Record<string, string | undefined>`); the block
-   * narrows it at the consumer.
-   */
-  partialAliasOf?: unknown;
-}
-/**
- * Subset of `@terrazzo/plugin-token-listing`'s `ListedToken` that the
- * snapshot carries. Blocks read `names.css` for the authoritative CSS
- * variable name and `previewValue` for the display-ready CSS string.
- * `source.loc` enables "jump to authoring source" affordances.
- *
- * Aliases `SlimListedToken` from core's `/snapshot-for-wire` subpath —
- * the single canonical wire shape; both the addon's plugin (server-side
- * emit) and blocks (consumer-side read) reference the same definition.
- */
-type VirtualTokenListing = SlimListedToken;
-type VirtualPresetShape = Preset;
-/**
- * Wire shape of the token graph — aliased from core's authoritative
- * `TokenGraph` so both the virtual module declaration and the React
- * context stay aligned with the same definition.
- */
-type VirtualTokenGraph = TokenGraph;
-/**
- * Full project data read by blocks. Populated by the addon's preview
- * decorator (from the virtual module) or constructed by hand in
- * non-Storybook consumers.
- */
-interface ProjectSnapshot {
-  axes: readonly VirtualAxisShape[];
-  activeTheme: string;
-  activeAxes: Readonly<Record<string, string>>;
-  cssVarPrefix: string;
-  /**
-   * Project-wide baseline for the row-indicator strip from
-   * `config.indicators`. Sits between the hard-coded indicator defaults
-   * and a block's `indicators` prop. Optional — hand-built snapshots
-   * (tests, MDX) omit it and blocks fall back to the bare defaults.
-   */
-  indicators?: Readonly<Record<string, boolean>>;
-  diagnostics: readonly VirtualDiagnosticShape[];
-  /**
-   * Raw stylesheet text for the active theme. Optional — nothing on the
-   * `SwatchbookProvider` read path consumes it (`useProject()` never reads
-   * `snapshot.css`); the addon populates it incidentally when constructing
-   * its snapshot but injects CSS through its own independent mechanism.
-   */
-  css?: string;
-  /**
-   * Path-indexed Token Listing data produced by
-   * `@terrazzo/plugin-token-listing`. Blocks prefer reading authoritative
-   * CSS var names and preview values from here; empty for non-resolver
-   * projects. Treat as enrichment — fall back gracefully when a path is
-   * absent.
-   */
-  listing?: Readonly<Record<string, VirtualTokenListing>>;
-  /**
-   * Pre-built token graph for the project. JSON-serializable; nodes
-   * carry per-axis writes plus alias edges. The blocks hook backs
-   * `resolveAt` and variance from this graph.
-   */
-  tokenGraph?: VirtualTokenGraph;
-  /** The default tuple — `{ axis: axis.default }` for every axis. */
-  defaultTuple: Record<string, string>;
-  /**
-   * Pre-built `resolveAt(tuple)` accessor. The addon's preview decorator
-   * instantiates this once per iframe lifetime. When present, use-project
-   * prefers it over building its own from `tokenGraph`, so it MUST preserve
-   * alias provenance — back it with `resolveAllWithProvenanceAt`, not the raw
-   * leaf `resolveAllAt`, or axis-varying aliases silently lose their chain /
-   * reverse refs / description at non-default tuples. Hand-built snapshots
-   * (tests, MDX) can omit this; blocks then fall back to a provenance-aware
-   * graph-backed resolver built from `tokenGraph`.
-   */
-  resolveAt?: (tuple: Record<string, string>) => Record<string, VirtualTokenShape>;
-}
-declare function useOptionalSwatchbookData(): ProjectSnapshot | null;
-/**
- * Active swatchbook theme for the current story/docs render. Populated by
- * the addon's preview decorator and consumed by `useToken` + any future
- * consumer hooks.
- *
- * This runs through plain React context rather than Storybook's
- * `useGlobals` so the same hook works in autodocs / MDX renders where the
- * preview-hooks context isn't available.
- */
-declare const ThemeContext: _$react.Context<string>;
-declare function useActiveTheme(): string;
-/**
- * Active axis tuple for the current story/docs render — `Record<axisName,
- * contextName>`. Derived from the same input as {@link ThemeContext}; split
- * out so consumers needing per-axis info (toolbar, panel, tuple-aware
- * blocks) don't have to reparse the composed theme name.
- */
-declare const AxesContext: _$react.Context<Readonly<Record<string, string>>>;
-declare function useActiveAxes(): Readonly<Record<string, string>>;
-/**
- * Active color-display format for the current story/docs render. Populated
- * by the addon's preview decorator from the `swatchbookColorFormat` global
- * (per-story `globals` or toolbar dropdown) and consumed by blocks that
- * render color-token values. Emitted CSS is unaffected.
- *
- * Runs through plain React context rather than Storybook's `useGlobals` so
- * per-story seeded globals flow through on first render and the same hook
- * is safe to call from MDX doc blocks (where the preview-hooks context
- * isn't available).
- */
-declare const ColorFormatContext: _$react.Context<ColorFormat | null>;
-declare function useColorFormat(): ColorFormat;
-//#endregion
 //#region src/internal/sort-tokens.d.ts
 type SortBy = 'path' | 'value' | 'none';
 type SortDir = 'asc' | 'desc';
@@ -178,21 +26,28 @@ interface BorderPreviewProps {
   sortBy?: SortBy;
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
+  /**
+   * Highest-precedence color format for this preview's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function BorderPreview({
   filter,
   caption,
   sortBy,
-  sortDir
+  sortDir,
+  colorFormat
 }: BorderPreviewProps): ReactElement;
 //#endregion
 //#region src/border-preview/BorderSample.d.ts
-interface BorderSampleProps {
-  /** Full dot-path of the border token to preview. */
-  path: string;
-}
+/** Props for the connected {@link BorderSample} block. */
+type BorderSampleProps = PresenterProps<'border'>;
 declare function BorderSample({
-  path
+  token,
+  cssVar,
+  colorFormat
 }: BorderSampleProps): ReactElement;
 //#endregion
 //#region src/ColorPalette.d.ts
@@ -227,15 +82,45 @@ interface ColorPaletteProps {
   sortBy?: SortBy;
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
+  /**
+   * Highest-precedence color format for this palette's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function ColorPalette({
   filter,
   groupBy,
   caption,
   sortBy,
-  sortDir
+  sortDir,
+  colorFormat
 }: ColorPaletteProps): ReactElement;
 //#endregion
+//#region src/presenters/ColorSwatch.d.ts
+/** Props for the {@link ColorSwatch} presenter. */
+type ColorSwatchProps = PresenterProps<'color'>;
+/**
+ * Presenter for `$type: color` tokens: a color chip, leaf label, and
+ * formatted value with an out-of-gamut marker. The chip's background is
+ * `cssVar` when supplied (R3); otherwise it is computed straight from
+ * `token.$value`, with `raw` guarded to `hex` (`cssColorFormat`) so the chip
+ * always paints a real color even when the display format is a JSON debug
+ * string. The value text below the chip uses the actual `colorFormat`,
+ * `raw` included. `options.label` lets a grouped consumer (e.g.
+ * `ColorPalette`) supply a group-relative label instead of the bare leaf
+ * segment, so context lost to grouping (`blue` in `color.palette.blue.50`)
+ * still reads on the swatch; standalone usage falls back to `leafOf(path)`.
+ */
+declare function ColorSwatch({
+  path,
+  token,
+  cssVar,
+  colorFormat,
+  options
+}: ColorSwatchProps): ReactElement;
+//#endregion
 //#region src/indicators/resolve.d.ts
 /** The individually-toggleable indicators in the row strip. `alias` covers the whole alias unit (forward chain + reverse count). */
 type IndicatorName = 'alias' | 'variance' | 'gamut' | 'deprecation' | 'description' | 'composes';
@@ -303,6 +188,12 @@ interface ColorTableProps {
   id?: string;
   /** Configure the per-row indicator strip. See `IndicatorsProp`. Gamut stays in the Value cell, so it is not part of this strip. */
   indicators?: IndicatorsProp;
+  /**
+   * Highest-precedence color format for this table's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 /**
  * A grouped, searchable table of `$type: color` tokens. Suffix-matched
@@ -319,7 +210,8 @@ declare function ColorTable({
   onSelect,
   variants,
   id,
-  indicators
+  indicators,
+  colorFormat
 }: ColorTableProps): ReactElement;
 //#endregion
 //#region src/Diagnostics.d.ts
@@ -344,22 +236,14 @@ declare function Diagnostics({
 //#region src/dimension-scale/DimensionSample.d.ts
 /** The visual treatment for a dimension sample: a length bar, a radius square, or a sized square. */
 type DimensionVisual = 'length' | 'radius' | 'size';
-/** Props for the connected {@link DimensionSample} block. */
-interface DimensionSampleProps {
-  /** Full dot-path of the dimension token to preview. */
-  path: string;
-  /**
-   * Visualization kind:
-   * - `'length'` (default): horizontal bar whose width equals the token's dimension.
-   * - `'radius'`: 56×56 square with the token applied as `border-radius`.
-   * - `'size'`: a square sized to the token's dimension.
-   */
-  visual?: DimensionVisual;
-}
-/** Connected block: resolves `path` against the active project and renders its dimension sample. */
+/** Props for the connected {@link DimensionSample} block. `options.visual` selects the visualization kind (see {@link DimensionVisual}); defaults to `'length'`. */
+type DimensionSampleProps = PresenterProps<'dimension'>;
+/** Connected block: renders a realised dimension token's sample, capped for oversized values. */
 declare function DimensionSample({
-  path,
-  visual
+  token,
+  cssVar,
+  colorFormat,
+  options
 }: DimensionSampleProps): ReactElement;
 //#endregion
 //#region src/DimensionScale.d.ts
@@ -425,6 +309,20 @@ declare function FontFamilyPreview({
   sortDir
 }: FontFamilyPreviewProps): ReactElement;
 //#endregion
+//#region src/presenters/FontFamilySpecimen.d.ts
+/** Props for the {@link FontFamilySpecimen} presenter. `options.sample` overrides the rendered sample text; defaults to a pangram. */
+type FontFamilySpecimenProps = PresenterProps<'fontFamily'>;
+/**
+ * Presenter for `$type: fontFamily` tokens: path, resolved stack, a sample
+ * line styled per R3, and the css var in use.
+ */
+declare function FontFamilySpecimen({
+  path,
+  token,
+  cssVar,
+  options
+}: FontFamilySpecimenProps): ReactElement;
+//#endregion
 //#region src/FontWeightScale.d.ts
 interface FontWeightScaleProps {
   /**
@@ -454,6 +352,20 @@ declare function FontWeightScale({
   sortDir
 }: FontWeightScaleProps): ReactElement;
 //#endregion
+//#region src/presenters/FontWeightSpecimen.d.ts
+/** Props for the {@link FontWeightSpecimen} presenter. `options.sample` overrides the rendered sample text; defaults to `'Aa'`. */
+type FontWeightSpecimenProps = PresenterProps<'fontWeight'>;
+/**
+ * Presenter for `$type: fontWeight` tokens: path, the raw weight value, a
+ * sample glyph styled per R3, and the css var in use.
+ */
+declare function FontWeightSpecimen({
+  path,
+  token,
+  cssVar,
+  options
+}: FontWeightSpecimenProps): ReactElement;
+//#endregion
 //#region src/GradientPalette.d.ts
 interface GradientPaletteProps {
   /**
@@ -471,32 +383,63 @@ interface GradientPaletteProps {
   sortBy?: SortBy;
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
+  /**
+   * Highest-precedence color format for this palette's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function GradientPalette({
   filter,
   caption,
   sortBy,
-  sortDir
+  sortDir,
+  colorFormat
 }: GradientPaletteProps): ReactElement;
 //#endregion
+//#region src/presenters/GradientSwatch.d.ts
+/** Props for the {@link GradientSwatch} presenter. */
+type GradientSwatchProps = PresenterProps<'gradient'>;
+/**
+ * Presenter for `$type: gradient` tokens: a gradient chip. Unlike the
+ * other composite presenters, a gradient's css var (per Terrazzo's
+ * `transformGradient`) resolves to a bare `<color> <pct>, ...` stop list,
+ * not a complete property value: DTCG gradients carry no direction, so
+ * both branches need one supplied at render time. `90deg` (`to right`)
+ * matches the direction the standalone block previously hard-coded.
+ */
+declare function GradientSwatch({
+  token,
+  cssVar,
+  colorFormat
+}: GradientSwatchProps): ReactElement;
+//#endregion
 //#region src/motion-preview/MotionSample.d.ts
 type MotionSpeed = 0.25 | 0.5 | 1 | 2;
-interface MotionSampleProps {
-  /** Full dot-path of the motion token (`transition`, `duration`, or `cubicBezier`). */
-  path: string;
-  /** Playback speed multiplier. Defaults to `1`. */
-  speed?: MotionSpeed;
-  /**
-   * Change this value to force the animation to restart. Useful when an
-   * outer block exposes a "replay" button that should re-trigger every
-   * sample at once.
-   */
-  runKey?: number;
-}
+/**
+ * Props for the connected {@link MotionSample} block. `token` accepts any
+ * of the three motion `$type`s (`transition`, `duration`, `cubicBezier`) —
+ * looser than a single-type `PresenterProps<'transition'>` because
+ * `resolveMotionSpec` dispatches on the realised `$type` at runtime and
+ * TokenNavigator/MotionPreview feed it all three from one call site.
+ * `options.speed` is the playback speed multiplier (defaults to `1`);
+ * `options.runKey` forces the animation to restart when changed, e.g. from
+ * an outer block's "replay" button re-triggering every sample at once.
+ */
+type MotionSampleProps = PresenterProps;
+/**
+ * Connected block: renders a realised motion token's animated sample. Both
+ * `durationMs` and `easing` come from the realised `$value`; the ball's
+ * setInterval loop needs a JS-readable duration, and (see the comment below)
+ * `cssVar` cannot stand in for `easing` here. `cssVar` is still accepted, per
+ * the uniform `PresenterProps` contract every presenter shares, but this
+ * View has nowhere safe to apply it.
+ */
 declare function MotionSample({
-  path,
-  speed,
-  runKey
+  token,
+  cssVar: _cssVar,
+  options
 }: MotionSampleProps): ReactElement;
 //#endregion
 //#region src/MotionPreview.d.ts
@@ -569,81 +512,71 @@ declare function OpacityScale({
   sortDir
 }: OpacityScaleProps): ReactElement;
 //#endregion
-//#region src/internal/channel-globals.d.ts
-/**
- * Shared subscription to Storybook's globals channel, lifted out of React
- * component state so the values survive docs-mode remounts.
- *
- * On MDX docs pages, Storybook force-rerenders the docs container on every
- * `updateGlobals` (see `preview/runtime.js` → `onUpdateGlobals`), which
- * unmounts and remounts any embedded blocks. A `useState(null)` initializer
- * inside the block would reset to null on each remount — the symptom is a
- * one-frame flicker to the correct value, then revert to the defaults.
- * Module-level state persists; React reads it through `useSyncExternalStore`
- * and stays concurrent-safe.
- */
-interface ChannelGlobals {
-  axes: Record<string, string> | null;
-  format: ColorFormat | null;
-}
-declare function useChannelGlobals(): ChannelGlobals;
-//#endregion
-//#region src/internal/channel.d.ts
-/**
- * Host adapter API — a distinct tier from the components/hooks/
- * `SwatchbookProvider` surface that MDX/story authors use. This is how a
- * host (Storybook's addon, or an alternative embedding) injects live data
- * into blocks without blocks depending on that host. Most consumers never
- * touch this; it exists for whoever builds the next integration.
- *
- * Minimal event-source contract blocks need from their host. Storybook's
- * preview Channel satisfies it structurally; a plain emitter or a test double
- * does too. Blocks never import `storybook/preview-api` — the addon, which
- * owns the Storybook relationship, injects the channel at preview init via
- * {@link registerChannel}, mirroring how `registerTokenSource` injects the
- * initial token snapshot.
- */
-interface BlockChannel {
-  on<T>(event: string, listener: (payload: T) => void): void;
-}
+//#region src/presenters/OpacitySwatch.d.ts
 /**
- * Host adapter API. The single most load-bearing function in the host
- * contract — the addon calls it once at preview init.
- *
- * Inject the host channel. Runs any subscribers that queued before the
- * channel existed, then clears the queue. The host contract does NOT dedupe:
- * on HMR a subscriber's module re-runs {@link onChannel}, which re-attaches
- * immediately once the channel is set, so each subscriber MUST guard its own
- * attach to stay single-wired.
+ * Props for the {@link OpacitySwatch} presenter. `options.sampleColorVar`
+ * sets the chip's fill color (a resolved css var or literal); defaults to
+ * the swatchbook accent surface.
  */
-declare function registerChannel(next: BlockChannel): void;
+type OpacitySwatchProps = PresenterProps<'number'>;
 /**
- * Host adapter API — see {@link registerChannel}.
- *
- * Attach a subscriber to the host channel now if one is registered, else queue
- * it to run the moment {@link registerChannel} fires. Blocks call this at
- * module load; the queue absorbs the gap until the addon injects the channel.
+ * Presenter for `$type: number` opacity tokens: a colored chip over a
+ * checkerboard backdrop, with the chip's `opacity` set from the token per
+ * R3. The number alone (`0.4`) doesn't convey what the token looks like
+ * applied to a surface; the chip does.
  */
-declare function onChannel(attach: (channel: BlockChannel) => void): void;
+declare function OpacitySwatch({
+  token,
+  cssVar,
+  options
+}: OpacitySwatchProps): ReactElement;
 //#endregion
 //#region src/provider.d.ts
 interface SwatchbookProviderProps {
-  value: ProjectSnapshot;
+  snapshot: SnapshotForWire;
+  /** Controlled active tuple. Mutually exclusive with `defaultAxes`. */
+  axes?: Record<string, string> | undefined;
+  /** Uncontrolled initial tuple; the provider owns state and `useSetAxes` flips it. */
+  defaultAxes?: Record<string, string> | undefined;
+  /** Overrides merged over {@link DEFAULT_PRESENTERS} for this subtree. */
+  presenters?: PresenterRegistry | undefined;
+  /**
+   * Mount the snapshot's emitted CSS into `document.head` through the shared
+   * managed style element (default `true`). Pass `false` when the host places
+   * the stylesheet itself: SSR frameworks, shadow roots, the Storybook addon
+   * (which injects its own combined stylesheet). The element is shared by ID,
+   * so a page hosting providers with different snapshots should opt out and
+   * manage stylesheets itself; same-snapshot providers are idempotent.
+   */
+  mountCss?: boolean | undefined;
   children: ReactNode;
 }
 /**
- * Wraps a tree of blocks with the token data they need to render.
+ * Wraps a tree of blocks with the token data they need to render, assembled
+ * from core's wire snapshot plus an active axis tuple.
  *
- * The Storybook addon's preview decorator mounts this automatically, so
- * story/MDX authors typically never see it. Outside Storybook — unit
- * tests, custom React apps, non-Storybook doc sites — consumers construct
- * a {@link ProjectSnapshot} (often imported from a JSON file) and wrap
- * their blocks in this provider.
+ * The Storybook addon's preview decorator mounts this automatically
+ * (`axes` controlled by the toolbar), so story/MDX authors typically never
+ * see it. Outside Storybook: unit tests, custom React apps, non-Storybook
+ * doc sites. Consumers pass a {@link SnapshotForWire} (often imported from
+ * a JSON file) and either drive `axes` themselves or let the provider own
+ * the tuple via `defaultAxes` + {@link useSetAxes}.
  */
 declare function SwatchbookProvider({
-  value,
+  snapshot,
+  axes,
+  defaultAxes,
+  presenters,
+  mountCss,
   children
 }: SwatchbookProviderProps): ReactElement;
+/**
+ * Flip the active tuple on an uncontrolled {@link SwatchbookProvider}
+ * (mounted with `defaultAxes`, not `axes`). Throws when the nearest
+ * provider is controlled (the host owns `axes`) or absent, since there's
+ * no internal state to flip in either case.
+ */
+declare function useSetAxes(): (tuple: Record<string, string>) => void;
 /**
  * Read the current {@link ProjectSnapshot}. Throws if called outside a
  * {@link SwatchbookProvider}; blocks that need to fall back to the
@@ -651,66 +584,6 @@ declare function SwatchbookProvider({
  */
 declare function useSwatchbookData(): ProjectSnapshot;
 //#endregion
-//#region src/internal/channel-tokens.d.ts
-/**
- * Host adapter API — same integration tier as {@link BlockChannel} /
- * {@link registerChannel} / {@link onChannel}, distinct from the
- * components/hooks/`SwatchbookProvider` surface MDX/story authors use.
- * Most consumers never touch this; it exists for whoever builds the next
- * host integration.
- *
- * Live token snapshot backed by the addon's preview dev-time HMR event.
- *
- * The initial snapshot is *injected* by the addon preview via
- * {@link registerTokenSource} rather than imported from the addon's
- * `virtual:swatchbook/tokens` build artifact — so blocks carries no
- * dependency on that module and imports cleanly standalone (outside
- * Storybook, in unit tests, in the docs site). Until something registers
- * a source, blocks render from empty defaults.
- *
- * For dev-time updates this module subscribes to `TOKENS_UPDATED_EVENT`
- * on Storybook's channel (which the addon preview re-broadcasts from its
- * own HMR listener) and exposes the latest snapshot via
- * `useSyncExternalStore`, so hooks re-render in place on each token save.
- */
-declare const TOKENS_UPDATED_EVENT = "swatchbook/tokens-updated";
-/** Host adapter API — see {@link registerTokenSource}. */
-interface TokenSnapshot {
-  readonly axes: readonly VirtualAxisShape[];
-  readonly presets: readonly {
-    name: string;
-    axes: Partial<Record<string, string>>;
-    description?: string;
-  }[];
-  readonly diagnostics: readonly VirtualDiagnosticShape[];
-  readonly css: string;
-  readonly cssVarPrefix: string;
-  /** Project-wide baseline for the row-indicator strip from `config.indicators`. */
-  readonly indicators: Readonly<Record<string, boolean>>;
-  readonly listing: Readonly<Record<string, VirtualTokenListing>>;
-  readonly tokenGraph: VirtualTokenGraph;
-  readonly defaultTuple: Record<string, string>;
-  /** Monotonic counter, bumped on each update. Useful as a React key. */
-  readonly version: number;
-}
-/**
- * Host adapter API — same integration tier as {@link registerChannel}.
- *
- * Seed the initial token snapshot. The addon preview calls this once at
- * init with the build-time `virtual:swatchbook/tokens` data. Keeping the
- * virtual-module read on the addon side (the package that owns it) lets
- * blocks import cleanly without it. No-op fields fall back to the current
- * snapshot, so a partial source is safe.
- */
-declare function registerTokenSource(source: Partial<TokenSnapshot>): void;
-/**
- * Host adapter API — same integration tier as {@link registerChannel}. Most
- * consumers read project data through `useSwatchbookData()` /
- * `SwatchbookProvider` instead; this is the internal subscription
- * `useProject()`'s fallback path uses to read the live channel-fed snapshot.
- */
-declare function useTokenSnapshot(): TokenSnapshot;
-//#endregion
 //#region src/ShadowPreview.d.ts
 interface ShadowPreviewProps {
   /**
@@ -728,23 +601,43 @@ interface ShadowPreviewProps {
   sortBy?: SortBy;
   /** `'asc'` (default) or `'desc'`. */
   sortDir?: SortDir;
+  /**
+   * Highest-precedence color format for this preview's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function ShadowPreview({
   filter,
   caption,
   sortBy,
-  sortDir
+  sortDir,
+  colorFormat
 }: ShadowPreviewProps): ReactElement;
 //#endregion
 //#region src/shadow-preview/ShadowSample.d.ts
-interface ShadowSampleProps {
-  /** Full dot-path of the shadow token to preview. */
-  path: string;
-}
+/** Props for the connected {@link ShadowSample} block. */
+type ShadowSampleProps = PresenterProps<'shadow'>;
 declare function ShadowSample({
-  path
+  token,
+  cssVar,
+  colorFormat
 }: ShadowSampleProps): ReactElement;
 //#endregion
+//#region src/presenters/StrokeSample.d.ts
+/** Props for the {@link StrokeSample} presenter. */
+type StrokeSampleProps = PresenterProps<'strokeStyle'>;
+/**
+ * Presenter for `$type: strokeStyle` tokens: a line styled with the
+ * token's `border-top-style` per R3, or the object-form fallback message
+ * when `$value` is a dash pattern with no pure CSS equivalent.
+ */
+declare function StrokeSample({
+  token,
+  cssVar
+}: StrokeSampleProps): ReactElement;
+//#endregion
 //#region src/StrokeStylePreview.d.ts
 interface StrokeStylePreviewProps {
   /**
@@ -776,10 +669,18 @@ interface TokenDetailProps {
   path: string;
   /** Override the heading. Defaults to the path. */
   heading?: string;
+  /**
+   * Highest-precedence color format for this block's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   * Also governs the composed `CompositeBreakdown` / `AxisVariance` sub-parts.
+   */
+  colorFormat?: ColorFormat;
 }
 declare function TokenDetail({
   path,
-  heading
+  heading,
+  colorFormat
 }: TokenDetailProps): ReactElement;
 //#endregion
 //#region src/token-detail/AliasChain.d.ts
@@ -804,18 +705,32 @@ declare function AliasedBy({
 interface AxisVarianceProps {
   /** Full dot-path of the token. */
   path: string;
+  /**
+   * Highest-precedence color format for this block's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function AxisVariance({
-  path
+  path,
+  colorFormat
 }: AxisVarianceProps): ReactElement;
 //#endregion
 //#region src/token-detail/CompositeBreakdown.d.ts
 interface CompositeBreakdownProps {
   /** Full dot-path of the token. */
   path: string;
+  /**
+   * Highest-precedence color format for this block's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   */
+  colorFormat?: ColorFormat;
 }
 declare function CompositeBreakdown({
-  path
+  path,
+  colorFormat
 }: CompositeBreakdownProps): ReactElement | null;
 //#endregion
 //#region src/token-detail/CompositePreview.d.ts
@@ -909,6 +824,13 @@ interface TokenNavigatorProps {
   id?: string;
   /** Configure the per-row indicator strip. See `IndicatorsProp`. */
   indicators?: IndicatorsProp;
+  /**
+   * Highest-precedence color format for this tree's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   * Also governs the composed row-detail `TokenDetail` slide-over.
+   */
+  colorFormat?: ColorFormat;
 }
 /**
  * A collapsible, searchable tree of tokens with roving-tabindex keyboard
@@ -922,7 +844,8 @@ declare function TokenNavigator({
   searchable,
   onSelect,
   id,
-  indicators
+  indicators,
+  colorFormat
 }: TokenNavigatorProps): ReactElement;
 //#endregion
 //#region src/TokenTable.d.ts
@@ -967,6 +890,13 @@ interface TokenTableProps {
   id?: string;
   /** Configure the per-row indicator strip. See `IndicatorsProp`. */
   indicators?: IndicatorsProp;
+  /**
+   * Highest-precedence color format for this table's values, overriding
+   * an outer `ColorFormatContext` and the project's `defaultColorFormat`.
+   * Omit to inherit the existing precedence chain (see `useColorFormat`).
+   * Also governs the composed row-detail `TokenDetail` slide-over.
+   */
+  colorFormat?: ColorFormat;
 }
 /**
  * A sortable, searchable table of tokens. Click a row to inspect it in a
@@ -982,9 +912,24 @@ declare function TokenTable({
   searchable,
   onSelect,
   id,
-  indicators
+  indicators,
+  colorFormat
 }: TokenTableProps): ReactElement;
 //#endregion
+//#region src/presenters/TypeSpecimen.d.ts
+/** Props for the connected {@link TypeSpecimen} block. `options.sample` overrides the rendered sample text; defaults to a pangram. */
+type TypeSpecimenProps = PresenterProps<'typography'>;
+/**
+ * Presenter for `$type: typography` tokens: a spec summary and a sample line
+ * styled per R3. Token identity (the path) is the consuming block's
+ * responsibility, not this presenter's; see `TypographyScale`.
+ */
+declare function TypeSpecimen({
+  token,
+  cssVar: _cssVar,
+  options
+}: TypeSpecimenProps): ReactElement;
+//#endregion
 //#region src/TypographyScale.d.ts
 interface TypographyScaleProps {
   /**
@@ -1013,5 +958,5 @@ declare function TypographyScale({
   sortDir
 }: TypographyScaleProps): ReactElement;
 //#endregion
-export { AliasChain, type AliasChainProps, AliasedBy, type AliasedByProps, AxesContext, AxisVariance, type AxisVarianceProps, type BlockChannel, BorderPreview, type BorderPreviewProps, BorderSample, type BorderSampleProps, COLOR_FORMATS, type ChannelGlobals, type ColorFormat, ColorFormatContext, ColorPalette, type ColorPaletteProps, ColorTable, type ColorTableProps, CompositeBreakdown, type CompositeBreakdownProps, CompositePreview, type CompositePreviewProps, ConsumerOutput, type ConsumerOutputProps, Diagnostics, type DiagnosticsProps, DimensionSample, type DimensionSampleProps, DimensionScale, type DimensionScaleProps, type DimensionVisual, FontFamilyPreview, type FontFamilyPreviewProps, FontWeightScale, type FontWeightScaleProps, type FormatColorResult, GradientPalette, type GradientPaletteProps, type IndicatorName, type IndicatorsProp, MotionPreview, type MotionPreviewProps, MotionSample, type MotionSampleProps, type MotionSpeed, type NormalizedColor, OpacityScale, type OpacityScaleProps, type ProjectSnapshot, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, type SortBy, type SortDir, StrokeStylePreview, type StrokeStylePreviewProps, SwatchbookProvider, type SwatchbookProviderProps, TOKENS_UPDATED_EVENT, ThemeContext, TokenDetail, type TokenDetailProps, TokenHeader, type TokenHeaderProps, TokenNavigator, type TokenNavigatorProps, type TokenSnapshot, TokenTable, type TokenTableProps, TokenUsageSnippet, type TokenUsageSnippetProps, TypographyScale, type TypographyScaleProps, type VirtualAxisShape as VirtualAxis, type VirtualDiagnosticShape as VirtualDiagnostic, type VirtualPresetShape as VirtualPreset, type VirtualTokenShape as VirtualToken, type VirtualTokenGraph, type VirtualTokenListing, formatColor, onChannel, registerChannel, registerTokenSource, useActiveAxes, useActiveTheme, useChannelGlobals, useColorFormat, useOptionalSwatchbookData, useSwatchbookData, useTokenSnapshot };
+export { AliasChain, type AliasChainProps, AliasedBy, type AliasedByProps, AxesContext, AxisVariance, type AxisVarianceProps, BorderPreview, type BorderPreviewProps, BorderSample, type BorderSampleProps, COLOR_FORMATS, type ColorFormat, ColorFormatContext, ColorPalette, type ColorPaletteProps, ColorSwatch, type ColorSwatchProps, ColorTable, type ColorTableProps, CompositeBreakdown, type CompositeBreakdownProps, CompositePreview, type CompositePreviewProps, ConsumerOutput, type ConsumerOutputProps, DEFAULT_PRESENTERS, Diagnostics, type DiagnosticsProps, DimensionSample, type DimensionSampleProps, DimensionScale, type DimensionScaleProps, type DimensionVisual, FontFamilyPreview, type FontFamilyPreviewProps, FontFamilySpecimen, type FontFamilySpecimenProps, FontWeightScale, type FontWeightScaleProps, FontWeightSpecimen, type FontWeightSpecimenProps, type FormatColorResult, GradientPalette, type GradientPaletteProps, GradientSwatch, type GradientSwatchProps, type IndicatorName, type IndicatorsProp, MotionPreview, type MotionPreviewProps, MotionSample, type MotionSampleProps, type MotionSpeed, type NormalizedColor, OpacityScale, type OpacityScaleProps, OpacitySwatch, type OpacitySwatchProps, type PresenterComponent, PresenterContext, type PresenterProps, type PresenterRegistry, type ProjectSnapshot, type RealisedToken, ShadowPreview, type ShadowPreviewProps, ShadowSample, type ShadowSampleProps, type SortBy, type SortDir, StrokeSample, type StrokeSampleProps, StrokeStylePreview, type StrokeStylePreviewProps, SwatchbookContext, SwatchbookProvider, type SwatchbookProviderProps, ThemeContext, TokenDetail, type TokenDetailProps, TokenHeader, type TokenHeaderProps, TokenNavigator, type TokenNavigatorProps, TokenTable, type TokenTableProps, type TokenType, TokenUsageSnippet, type TokenUsageSnippetProps, TypeSpecimen, type TypeSpecimenProps, TypographyScale, type TypographyScaleProps, type VirtualAxisShape as VirtualAxis, type VirtualDiagnosticShape as VirtualDiagnostic, type VirtualPresetShape as VirtualPreset, type VirtualTokenShape as VirtualToken, type VirtualTokenGraph, type VirtualTokenListing, formatColor, formatTokenValue, mergePresenters, useActiveAxes, useActiveTheme, useColorFormat, useOptionalSwatchbookData, usePresenter, useSetAxes, useSwatchbookData };
 //# sourceMappingURL=index.d.mts.map