@foir/sdk 0.5.0 → 0.8.0

package/dist/codegen/index.d.ts

@@ -1,65 +1,16 @@
-import { CodegenConfig } from '@graphql-codegen/cli';
-export { B as BlockPluginConfig } from '../shared-DkWlEd2Z.js';
-
 /**
- * `@foir/sdk/codegen` — the Foir graphql-codegen preset.
+ * `@foir/sdk/codegen` — Foir graphql-codegen preset + item-registry plugin.
  *
- * `foirCodegen()` returns a complete `@graphql-codegen/client-preset` config so
- * a consumer's `codegen.ts` is ~3 lines instead of the ~109 every storefront
- * hand-copies. It standardizes the Foir conventions (custom scalars,
- * `enumValues: 'keep'`, the `X-Foir-Schema-Channel: draft` introspection header)
- * AND wires the block-registry plugin so the exhaustive `BlockRegistry` type is
- * regenerated alongside the typed documents.
+ * Build-time only. `@graphql-codegen/cli` + `@graphql-codegen/client-preset`
+ * are optional peer dependencies (the consumer's devDeps). The item-registry
+ * and item-scaffold plugins are wired by the preset and also available at
+ * `@foir/sdk/codegen/item-registry` / `@foir/sdk/codegen/item-scaffold`.
  *
- * `foirScaffold()` is the separate one-shot that writes the ContentRenderer
- * shell (run once; the dev owns the output).
+ * The pre-TTS-1391 paths `@foir/sdk/codegen/block-registry` and
+ * `/block-scaffold` still resolve, re-exporting those modules unchanged.
  */
-
-interface FoirCodegenOptions {
-    /** Foir public API GraphQL endpoint. */
-    apiUrl: string;
-    /**
-     * Public (`pk_`) API key. Reads the published schema. Used as the fallback
-     * when no preview key is set.
-     */
-    apiKey?: string;
-    /**
-     * Preview (`sk_`) key with `drafts:read`. Reads the DRAFT schema channel so
-     * freshly pushed (un-promoted) model changes are visible to codegen.
-     * Strongly preferred — a `pk_` key only sees the published schema.
-     */
-    previewKey?: string;
-    /** Output directory for the generated client types. Default `./app/gql/foir/`. */
-    outputDir?: string;
-    /** Operation document glob(s). Default `app/graphql/foir/**\/*.graphql`. */
-    documents?: string | string[];
-    /** Block union name(s) for the registry. Default `['Block']`. */
-    blockUnions?: string[];
-    /** Generated registry file path. Default `<outputDir>block-registry.ts`. */
-    registryFile?: string;
-    /** Extra/override custom scalars merged onto the Foir defaults. */
-    scalars?: Record<string, unknown>;
-}
-/**
- * Build the continuous Foir codegen config: typed documents + the exhaustive
- * block registry. Drop it into `codegen.ts` and run `graphql-codegen`.
- */
-declare function foirCodegen(options: FoirCodegenOptions): CodegenConfig;
-interface FoirScaffoldOptions extends FoirCodegenOptions {
-    /** Output path for the scaffold. Default `<outputDir>ContentRenderer.tsx`. */
-    scaffoldFile?: string;
-    /** Render-context type threaded to every block component. Default `unknown`. */
-    ctxType?: string;
-    /** Optional ctx-type import line, e.g. `import type { Ctx } from '~/ctx'`. */
-    ctxImport?: string;
-    /** Import path for the generated registry type. Default `./block-registry`. */
-    registryImport?: string;
-}
-/**
- * Build the one-shot scaffold config — writes a ContentRenderer shell with a
- * typed stub per block type. Run once (`graphql-codegen --config scaffold.ts`),
- * then own and implement the output.
- */
-declare function foirScaffold(options: FoirScaffoldOptions): CodegenConfig;
-
-export { type FoirCodegenOptions, type FoirScaffoldOptions, foirCodegen, foirScaffold };
+export { foirCodegen, foirScaffold } from './preset';
+export type { FoirCodegenOptions, FoirScaffoldOptions } from './preset';
+export type { ItemPluginConfig } from './shared';
+/** @deprecated Renamed to `ItemPluginConfig`. */
+export type { BlockPluginConfig } from './shared';

package/dist/codegen/index.js

@@ -1,7 +1,3 @@
-import {
-  DEFAULT_UNIONS
-} from "../chunk-ADO5FJNM.js";
-
 // src/codegen/preset.ts
 var DEFAULT_OUTPUT_DIR = "./app/gql/foir/";
 var DEFAULT_DOCUMENTS = "app/graphql/foir/**/*.graphql";
@@ -30,8 +26,8 @@ function foirCodegen(options) {
   const previewKey = options.previewKey ?? options.apiKey;
   const outputDir = normalizeDir(options.outputDir ?? DEFAULT_OUTPUT_DIR);
   const documents = options.documents ?? DEFAULT_DOCUMENTS;
-  const blockUnions = options.blockUnions ?? DEFAULT_UNIONS;
-  const registryFile = options.registryFile ?? `${outputDir}block-registry.ts`;
+  const unions = options.itemUnions ?? options.blockUnions;
+  const registryFile = options.registryFile ?? `${outputDir}item-registry.ts`;
   return {
     schema: schemaEntry(options.apiUrl, previewKey),
     documents,
@@ -47,8 +43,8 @@ function foirCodegen(options) {
         }
       },
       [registryFile]: {
-        plugins: ["@foir/sdk/codegen/block-registry"],
-        config: { unions: blockUnions }
+        plugins: ["@foir/sdk/codegen/item-registry"],
+        config: { unions }
       }
     }
   };
@@ -57,15 +53,15 @@ function foirScaffold(options) {
   const previewKey = options.previewKey ?? options.apiKey;
   const outputDir = normalizeDir(options.outputDir ?? DEFAULT_OUTPUT_DIR);
   const scaffoldFile = options.scaffoldFile ?? `${outputDir}ContentRenderer.tsx`;
-  const blockUnions = options.blockUnions ?? DEFAULT_UNIONS;
+  const unions = options.itemUnions ?? options.blockUnions;
   return {
     schema: schemaEntry(options.apiUrl, previewKey),
     ignoreNoDocuments: true,
     generates: {
       [scaffoldFile]: {
-        plugins: ["@foir/sdk/codegen/block-scaffold"],
+        plugins: ["@foir/sdk/codegen/item-scaffold"],
         config: {
-          unions: blockUnions,
+          unions,
           ctxType: options.ctxType,
           ctxImport: options.ctxImport,
           registryImport: options.registryImport

package/dist/codegen/item-registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@foir/sdk/codegen/item-registry` — a graphql-codegen plugin.
+ *
+ * Introspects the project's public schema, collects every member of the
+ * flexible union(s), and emits an EXHAUSTIVE `ItemRegistry` type — one key per
+ * item `__typename`, each typed `ItemComponent<ThatItem, Ctx>`. Because the
+ * type requires every key, a project that adds an inline model (→ a new item
+ * `__typename`) breaks the consumer's build until the new component is wired:
+ * exhaustiveness by construction, replacing the hand-synced switch a storefront
+ * would otherwise carry.
+ *
+ * Wired automatically by `foirCodegen()`. The generated file imports the item
+ * types from the codegen output (`./graphql`) and `ItemComponent` from
+ * `@foir/sdk/content`, so it pairs directly with `createContentRenderer`.
+ *
+ * Reachable at the pre-TTS-1391 path `@foir/sdk/codegen/block-registry` too,
+ * which re-exports this module unchanged.
+ */
+import type { GraphQLSchema } from 'graphql';
+import { type ItemPluginConfig } from './shared';
+export interface ItemRegistryConfig extends ItemPluginConfig {
+    /** Name of the generated registry type. Default `ItemRegistry`. */
+    registryName?: string;
+}
+/** @deprecated Renamed to {@link ItemRegistryConfig}. */
+export type BlockRegistryConfig = ItemRegistryConfig;
+/** graphql-codegen plugin entrypoint. */
+export declare const plugin: (schema: GraphQLSchema, _documents: unknown, config?: ItemRegistryConfig) => string;

package/dist/codegen/item-registry.js

@@ -0,0 +1,7 @@
+import {
+  plugin
+} from "../chunk-IGNLWT3H.js";
+import "../chunk-TAL5H6VA.js";
+export {
+  plugin
+};

package/dist/codegen/item-scaffold.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `@foir/sdk/codegen/item-scaffold` — a one-shot graphql-codegen plugin.
+ *
+ * Emits a ContentRenderer shell: a stub component per item `__typename`, an
+ * `itemRegistry` of the (exhaustive) `ItemRegistry` type, and a
+ * `createContentRenderer` wiring. Unlike the item-registry plugin (which
+ * regenerates every run), this is a STARTING POINT the dev then owns — run it
+ * once via `foirScaffold()`, then implement each stub. It compiles out of the
+ * box (each stub is a typed no-op) so the build stays green while you fill them
+ * in. Adding a new item type later surfaces as a compile error on
+ * `itemRegistry` (via the regenerated `ItemRegistry` type), not here.
+ *
+ * Reachable at the pre-TTS-1391 path `@foir/sdk/codegen/block-scaffold` too,
+ * which re-exports this module unchanged.
+ */
+import type { GraphQLSchema } from 'graphql';
+import { type ItemPluginConfig } from './shared';
+export interface ItemScaffoldConfig extends ItemPluginConfig {
+    /** Import path for the generated registry type. Default `./item-registry`. */
+    registryImport?: string;
+    /** Render-context type name threaded to every component. Default `unknown`. */
+    ctxType?: string;
+    /** Optional import line for the ctx type, e.g. `import type { Ctx } from '~/ctx'`. */
+    ctxImport?: string;
+}
+/** @deprecated Renamed to {@link ItemScaffoldConfig}. */
+export type BlockScaffoldConfig = ItemScaffoldConfig;
+/** graphql-codegen plugin entrypoint. */
+export declare const plugin: (schema: GraphQLSchema, _documents: unknown, config?: ItemScaffoldConfig) => string;

package/dist/codegen/item-scaffold.js

@@ -0,0 +1,7 @@
+import {
+  plugin
+} from "../chunk-OHYVKTGB.js";
+import "../chunk-TAL5H6VA.js";
+export {
+  plugin
+};

package/dist/codegen/preset.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `@foir/sdk/codegen` — the Foir graphql-codegen preset.
+ *
+ * `foirCodegen()` returns a complete `@graphql-codegen/client-preset` config so
+ * a consumer's `codegen.ts` is ~3 lines instead of the ~109 every storefront
+ * hand-copies. It standardizes the Foir conventions (custom scalars,
+ * `enumValues: 'keep'`, the `X-Foir-Schema-Channel: draft` introspection header)
+ * AND wires the item-registry plugin so the exhaustive `ItemRegistry` type is
+ * regenerated alongside the typed documents.
+ *
+ * `foirScaffold()` is the separate one-shot that writes the ContentRenderer
+ * shell (run once; the dev owns the output).
+ */
+import type { CodegenConfig } from '@graphql-codegen/cli';
+export interface FoirCodegenOptions {
+    /** Foir public API GraphQL endpoint. */
+    apiUrl: string;
+    /**
+     * Public (`pk_`) API key. Reads the published schema. Used as the fallback
+     * when no preview key is set.
+     */
+    apiKey?: string;
+    /**
+     * Preview (`sk_`) key with `drafts:read`. Reads the DRAFT schema channel so
+     * freshly pushed (un-promoted) model changes are visible to codegen.
+     * Strongly preferred — a `pk_` key only sees the published schema.
+     */
+    previewKey?: string;
+    /** Output directory for the generated client types. Default `./app/gql/foir/`. */
+    outputDir?: string;
+    /** Operation document glob(s). Default `app/graphql/foir/**\/*.graphql`. */
+    documents?: string | string[];
+    /**
+     * Entries union name(s) for the registry. When unset, every prose
+     * entries union in the schema (the unions carrying `Passage`) is
+     * discovered at introspection time. Set explicitly to narrow the
+     * registry to specific fields' unions.
+     */
+    itemUnions?: string[];
+    /** @deprecated Renamed to `itemUnions`. Honoured when `itemUnions` is unset. */
+    blockUnions?: string[];
+    /** Generated registry file path. Default `<outputDir>item-registry.ts`. */
+    registryFile?: string;
+    /** Extra/override custom scalars merged onto the Foir defaults. */
+    scalars?: Record<string, unknown>;
+}
+/**
+ * Build the continuous Foir codegen config: typed documents + the exhaustive
+ * item registry. Drop it into `codegen.ts` and run `graphql-codegen`.
+ */
+export declare function foirCodegen(options: FoirCodegenOptions): CodegenConfig;
+export interface FoirScaffoldOptions extends FoirCodegenOptions {
+    /** Output path for the scaffold. Default `<outputDir>ContentRenderer.tsx`. */
+    scaffoldFile?: string;
+    /** Render-context type threaded to every item component. Default `unknown`. */
+    ctxType?: string;
+    /** Optional ctx-type import line, e.g. `import type { Ctx } from '~/ctx'`. */
+    ctxImport?: string;
+    /** Import path for the generated registry type. Default `./item-registry`. */
+    registryImport?: string;
+}
+/**
+ * Build the one-shot scaffold config — writes a ContentRenderer shell with a
+ * typed stub per item type. Run once (`graphql-codegen --config scaffold.ts`),
+ * then own and implement the output.
+ */
+export declare function foirScaffold(options: FoirScaffoldOptions): CodegenConfig;

package/dist/codegen/shared.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared introspection helpers for the Foir codegen plugins.
+ */
+import { type GraphQLSchema } from 'graphql';
+export interface ItemPluginConfig {
+    /**
+     * Union type name(s) to collect item members from. When unset, the
+     * plugins DISCOVER the project's prose entries unions: every union whose
+     * member set includes `Passage` (each prose field's entries union is
+     * named by its materialised member set, so there is no single fixed
+     * name to configure). Set explicitly to narrow the registry to specific
+     * fields' unions.
+     */
+    unions?: string[];
+    /** Import path for the codegen-generated types. Default `./graphql`. */
+    graphqlImport?: string;
+    /** Import path for the SDK content primitives. Default `@foir/sdk/content`. */
+    sdkImport?: string;
+}
+/** @deprecated Renamed to {@link ItemPluginConfig}. */
+export type BlockPluginConfig = ItemPluginConfig;
+export declare const DEFAULT_GRAPHQL_IMPORT = "./graphql";
+export declare const DEFAULT_SDK_IMPORT = "@foir/sdk/content";
+/**
+ * Collect the deduped, sorted set of object-type member names across the
+ * named union(s) — or, when no names are given, across every prose entries
+ * union in the schema (the unions whose members include `Passage`).
+ * `Passage` itself is excluded: the content renderer owns passage
+ * rendering, so no registry component exists for it.
+ *
+ * Throws when nothing resolves — that almost always means a misconfigured
+ * union name, or a schema with no prose fields that place models.
+ */
+export declare function collectItemMembers(schema: GraphQLSchema, unionNames?: string[]): string[];
+/** @deprecated Renamed to {@link collectItemMembers}. */
+export declare const collectBlockMembers: typeof collectItemMembers;

package/dist/components/EditorProvider.d.ts

@@ -0,0 +1,36 @@
+/**
+ * EditorProvider - React context provider for Foir editor iframes.
+ *
+ * Wraps your editor root to handle postMessage lifecycle, theme sync,
+ * and provide the platform client via context.
+ */
+import { type ReactNode } from 'react';
+import type { EditorInit, EditorContextValue, LocaleContext } from '../types';
+export declare const EditorContext: import("react").Context<EditorContextValue | null>;
+export interface EditorProviderProps {
+    children: ReactNode;
+    /**
+     * Parent window origin for postMessage validation.
+     * Must be an explicit origin (e.g., 'https://admin.example.com').
+     * Falls back to VITE_PARENT_ORIGIN or NEXT_PUBLIC_PARENT_ORIGIN env var.
+     */
+    parentOrigin?: string;
+    /**
+     * Platform API URL for GraphQL requests.
+     * Falls back to VITE_API_URL or NEXT_PUBLIC_API_URL env var.
+     */
+    apiUrl?: string;
+    onInit?: (init: EditorInit) => void;
+    onValuesChanged?: (values: Record<string, unknown>) => void;
+    onVariantChanged?: (variantKey: string, values: Record<string, unknown>) => void;
+    onSaveResult?: (success: boolean, error?: string, versionId?: string) => void;
+    onPublishResult?: (success: boolean, error?: string) => void;
+    onThemeChanged?: (theme: 'light' | 'dark') => void;
+    onSelectionChanged?: (keys: string[], fields: Array<{
+        key: string;
+        label: string;
+        type: string;
+    }>) => void;
+    onLocaleChanged?: (locale: LocaleContext) => void;
+}
+export declare function EditorProvider({ children, parentOrigin: parentOriginProp, apiUrl: apiUrlProp, onInit, onValuesChanged, onVariantChanged, onSaveResult, onPublishResult, onThemeChanged, onSelectionChanged, onLocaleChanged, }: EditorProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/content/content-renderer.d.ts

@@ -0,0 +1,113 @@
+/**
+ * createContentRenderer — the generic content-dispatch primitive.
+ *
+ * It does NOT know any concrete item types. Given a registry that maps each
+ * entry `__typename` to a component, it renders a prose flow's entries (or a
+ * plain item array): looks each entry up by `__typename`, renders unknown
+ * types as null, keys by the entry `_key`/`_id` where one is present, assigns
+ * LCP `priority` to the first entry that actually renders, and threads a
+ * consumer-defined `Ctx` to every component.
+ *
+ * Passage entries — the flow's text — are not registry-dispatched: a run of
+ * consecutive passages renders as ONE unit through `options.passageRun` (or
+ * the SDK's `PassageList` with provider tokens when none is supplied), so
+ * prose reads as a single body with shared list structure.
+ *
+ * The "switch" is a typed object lookup. Exhaustiveness is enforced where the
+ * registry is BUILT — against the exhaustive `ItemRegistry` type the codegen
+ * plugin (EID-92) generates per project, so omitting an item type is a compile
+ * error there, not a runtime surprise here. The consumer can supply different
+ * registries per surface (e.g. web vs email).
+ *
+ * # On the word
+ *
+ * A prose field holds ENTRIES. A modeller may name the field `blocks`,
+ * `sections`, `modules` or anything else, and this renderer must not care:
+ * dispatch is on `__typename` and never on a field name. The `Block*` spellings
+ * below are deprecated aliases kept so existing consumers compile — see
+ * TTS-1391.
+ */
+import { type ReactNode } from 'react';
+import { type PassageLike } from './richtext';
+/** Minimal shape every entry in a prose flow carries. */
+export interface ItemLike {
+    __typename: string;
+    _id?: string | null;
+    _key?: string | null;
+}
+/** Props an item component receives from the content renderer. */
+export interface ItemComponentProps<TItem, TCtx = unknown> {
+    item: TItem;
+    /**
+     * The same value as `item`.
+     *
+     * @deprecated Use `item`. Kept so components scaffolded before TTS-1391
+     * keep compiling; it is passed on every render and will be removed in a
+     * future major.
+     */
+    block: TItem;
+    /** Consumer-defined render context (host product, locale, etc.). */
+    ctx: TCtx;
+    /** True only for the first item that renders — the LCP candidate. */
+    priority: boolean;
+}
+/** A component that renders one item type. */
+export type ItemComponent<TItem, TCtx = unknown> = (props: ItemComponentProps<TItem, TCtx>) => ReactNode;
+/**
+ * A registry mapping `__typename` → item component. In practice this is the
+ * exhaustive `ItemRegistry` type the codegen plugin emits for the project;
+ * here it's the structural lower bound the renderer needs.
+ */
+export type ItemRegistry<TCtx = unknown> = Record<string, ItemComponent<any, TCtx>>;
+/** A prose flow's projection wrapper: the field value carrying `entries`. */
+export interface EntriesLike {
+    entries?: readonly (ItemLike | null | undefined)[] | null;
+}
+/**
+ * The prose field's entries — the projection wrapper (`{ entries }`), or a
+ * plain array — plus the context threaded to every component.
+ *
+ * `items` is canonical. `blocks` is the pre-TTS-1391 spelling and still
+ * accepted; passing both is a type error rather than a silent precedence rule,
+ * because a caller who set both cannot be told which one this honoured.
+ */
+export type ContentRendererProps<TCtx> = {
+    /** Consumer-defined context passed to every item component. */
+    ctx: TCtx;
+} & ({
+    items: readonly (ItemLike | null | undefined)[] | EntriesLike | null | undefined;
+    blocks?: never;
+} | {
+    /** @deprecated Use `items`. */
+    blocks: readonly (ItemLike | null | undefined)[] | EntriesLike | null | undefined;
+    items?: never;
+});
+/** Props the passage-run component receives. */
+export interface PassageRunProps<TCtx = unknown> {
+    /** The consecutive passage entries of this run, in document order. */
+    passages: PassageLike[];
+    /** Consumer-defined render context. */
+    ctx: TCtx;
+    /** True only when the run is the flow's first rendered unit. */
+    priority: boolean;
+}
+export interface ContentRendererOptions<TCtx = unknown> {
+    /**
+     * Renders a run of consecutive passage entries. Defaults to the SDK's
+     * `PassageList` (typography tokens via `RichTextTypographyProvider`).
+     */
+    passageRun?: (props: PassageRunProps<TCtx>) => ReactNode;
+}
+/**
+ * Build a `<ContentRenderer>` bound to an item registry. Returns a component
+ * that takes the prose field's value (or a plain entry array) plus a `ctx`.
+ */
+export declare function createContentRenderer<TCtx = unknown>(registry: ItemRegistry<TCtx>, options?: ContentRendererOptions<TCtx>): (props: ContentRendererProps<TCtx>) => ReactNode;
+/** @deprecated Renamed to {@link ItemLike}. */
+export type BlockLike = ItemLike;
+/** @deprecated Renamed to {@link ItemComponentProps}. */
+export type BlockComponentProps<TBlock, TCtx = unknown> = ItemComponentProps<TBlock, TCtx>;
+/** @deprecated Renamed to {@link ItemComponent}. */
+export type BlockComponent<TBlock, TCtx = unknown> = ItemComponent<TBlock, TCtx>;
+/** @deprecated Renamed to {@link ItemRegistry}. */
+export type BlockRegistry<TCtx = unknown> = ItemRegistry<TCtx>;

package/dist/content/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@foir/sdk/content` — generic content-rendering primitives.
+ *
+ * Ships ONLY the framework-agnostic primitives: the entry-dispatch renderer
+ * and a prose renderer (passages with spans, marks and markDefs) with
+ * injected typography tokens. Concrete item components, host/Shopify
+ * context, and layout systems stay app-side. `react` is a peer dependency.
+ */
+export { createContentRenderer } from './content-renderer';
+export type { ItemLike, EntriesLike, ItemComponent, ItemComponentProps, ItemRegistry, ContentRendererProps, ContentRendererOptions, PassageRunProps, } from './content-renderer';
+/**
+ * Pre-TTS-1391 spellings. `Block` was one project's name for a flexible field,
+ * never a platform concept; these are kept so existing consumers compile and
+ * will be removed in a future major.
+ */
+export type { BlockLike, BlockComponent, BlockComponentProps, BlockRegistry, } from './content-renderer';
+export { RichTextRenderer, RichTextTypographyProvider, useRichTextTypography, PassageList, passagesOf, isPassageEntry, safeHref, } from './richtext';
+export type { RichTextRendererProps, PassageListProps, TypographyToken, ProseValueLike, PassageLike, ProseSpanLike, } from './richtext';

package/dist/content/richtext.d.ts

@@ -0,0 +1,118 @@
+/**
+ * RichTextRenderer — render a Foir prose value (a flow of passages) with
+ * per-passage typography tokens applied as inline styles.
+ *
+ * The design-token dependency is INJECTED, not imported from an app: pass the
+ * resolved `typography` token array as a prop, or provide it once via
+ * `<RichTextTypographyProvider>`. With no tokens the structure still renders
+ * (fallback tag, no inline typography), and a value without a typed `entries`
+ * projection falls back to its stored flow (`json`) and then its `html`
+ * projection. No `@foir`-app imports.
+ *
+ * Passage semantics:
+ *   - `kind` (paragraph / h1–h6 / quote / code) picks the HTML element.
+ *   - `token` names a typography token; its resolved CSS is inlined and the
+ *     token's `tag` wins over the kind's element when both are present.
+ *   - `align` maps to text-align on the rendered element.
+ *   - `list` + `level` flatten list membership onto the passage; consecutive
+ *     list passages regroup into <ul>/<ol> with nesting rebuilt from `level`.
+ *   - Span marks are the eight decorations (bold, italic, underline,
+ *     strikethrough, code, subscript, superscript, highlight) or the `_key`
+ *     of a markDef on the same passage (links, scheme-checked through
+ *     `safeHref`).
+ *   - A soft line break is `"\n"` inside a span's text.
+ */
+import { type ReactNode, type JSX } from 'react';
+/**
+ * safeHref allow-lists link schemes so stored prose can't smuggle a
+ * `javascript:` (or `data:`/`vbscript:`) URL that executes on click (EID-207).
+ * Relative URLs, anchors, and the http(s)/mailto/tel schemes pass; anything
+ * else collapses to '#'. Editors are not fully trusted, so this runs on the
+ * structured render path, not only the html fallback.
+ */
+export declare function safeHref(url: string | undefined): string;
+/** A resolved typography token from the project's design tokens. */
+export interface TypographyToken {
+    /** Token key referenced by a passage's `token`. */
+    name: string;
+    /** Rendered HTML element (paragraph / h1–h6 / blockquote). */
+    tag?: string;
+    value: {
+        fontFamily: string[];
+        fontSize: string | number;
+        fontWeight: string | number;
+        lineHeight: string | number;
+        letterSpacing: string | number;
+        textTransform?: string;
+    };
+}
+/**
+ * Provide the project's resolved typography tokens to every nested
+ * `<RichTextRenderer>` / `<PassageList>` so callers don't thread them through
+ * each usage. A `tokens` prop on the renderer still takes precedence.
+ */
+export declare function RichTextTypographyProvider({ tokens, children, }: {
+    tokens: TypographyToken[];
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Read the injected typography tokens (null when no provider is mounted). */
+export declare function useRichTextTypography(): TypographyToken[] | null;
+export interface ProseSpanLike {
+    text?: string | null;
+    marks?: ReadonlyArray<string | null> | null;
+}
+export interface PassageLike {
+    __typename?: string;
+    _type?: string;
+    _key?: string | null;
+    kind?: string | null;
+    token?: string | null;
+    align?: string | null;
+    list?: string | null;
+    level?: number | null;
+    language?: string | null;
+    markDefs?: unknown;
+    spans?: ReadonlyArray<ProseSpanLike | null> | null;
+}
+export interface ProseValueLike {
+    html?: string | null;
+    json?: unknown;
+    entries?: ReadonlyArray<PassageLike | null> | null;
+}
+/** True for a passage entry from either the typed projection
+ * (`__typename: "Passage"`) or the stored flow (`_type: "passage"`). */
+export declare function isPassageEntry(entry: unknown): entry is PassageLike;
+/**
+ * Extract the renderable passages from a prose value. Prefers the typed
+ * `entries` projection; falls back to walking the stored flow (`json`).
+ * Embed entries are skipped — a prose *value* position renders text; embeds
+ * in list positions render through the consumer's content renderer instead.
+ */
+export declare function passagesOf(value: ProseValueLike | null | undefined): PassageLike[];
+export interface RichTextRendererProps {
+    value: ProseValueLike | null | undefined;
+    className?: string;
+    /**
+     * Resolved typography tokens. Overrides any provided via
+     * `<RichTextTypographyProvider>`. When neither is set, paragraphs render
+     * with `fallbackTag` and no inline typography.
+     */
+    tokens?: TypographyToken[];
+    /** Tag used for a paragraph passage with no token tag. */
+    fallbackTag?: keyof JSX.IntrinsicElements;
+}
+export declare function RichTextRenderer({ value, className, tokens, fallbackTag, }: RichTextRendererProps): import("react/jsx-runtime").JSX.Element | null;
+export interface PassageListProps {
+    passages: ReadonlyArray<PassageLike>;
+    /** Resolved typography tokens; falls back to the provider's. */
+    tokens?: TypographyToken[];
+    /** Tag used for a paragraph passage with no token tag. */
+    fallbackTag?: keyof JSX.IntrinsicElements;
+}
+/**
+ * Render a run of passages: consecutive list passages regroup into (nested)
+ * <ul>/<ol>, everything else renders as its own element. Used by
+ * `RichTextRenderer` for prose field values and by `createContentRenderer`
+ * for passage runs inside a flow's entries.
+ */
+export declare function PassageList({ passages, tokens, fallbackTag, }: PassageListProps): import("react/jsx-runtime").JSX.Element;