@peripheries/renderer 0.22.0 → 0.23.1

package/dist/types/react/page-renderer.d.ts

@@ -9,45 +9,20 @@ import type { StackStoreApi } from '../core/store/create-store.js';
 import type { PageCell } from '../core/types.js';
 import { type FrameProps } from './cell-view.js';
 import type { LoadPage } from './use-paging.js';
-/** What differs between the host, the component repos' harness and the agency's preview (design/renderer.md §6). */
 export type RendererEnvironment = {
-    /** Default components: what a name resolves to when no bundle in scope exports it. */
     core: CoreRegistry;
     navigate: (to: string) => void;
-    /** The shared store the cells' selections, viewState and live read. */
     store: StackStoreApi;
-    /** A page configuration problem, for whoever is building the page. Default: a console warning. */
     onDiagnostic?: (d: Diagnostic) => void;
-    /**
-     * The actions a cell gets. The host has none until R2's write rule; the
-     * component repos' harness gives mocks (`projectCellActions` applies the PWA's
-     * lookup rule to a page-level map).
-     */
     actionsFor?: (cell: PageCell) => Record<string, CellAction> | undefined;
-    /**
-     * Runs a cell's declared action (design/data.md §9.2), resolved against the
-     * cell's data and the component's `@input`: the host's write path, as the
-     * viewer, or a harness's mock. Without it a declared action reports `FAILED`.
-     */
     runAction?: RunAction;
-    /**
-     * Loads a paged label's next page (QueryDescriptor.paging), as the viewer.
-     * Without it a paged label shows its first page, with `hasMore` false.
-     */
     loadPage?: LoadPage;
-    /** A component threw. Default: a console error; the cell shows an error notice either way. */
     onCellError?: (cellId: string, error: Error) => void;
-    /** A cell's prop reference resolved to nothing (a binding the page gets wrong). */
     onUnresolvedReference?: (cellId: string, ref: string) => void;
-    /**
-     * Each rendered cell's props, leaf by leaf, with where each value came from (INV-DOC-6): what
-     * the edit layer maps to a write function with `editTarget`. Called as each cell renders.
-     */
     onPropSources?: (cell: EditCell, sources: PropSourceEntry[]) => void;
-    /** Reads the page again: a cell whose data or bundle failed offers it as "Try again" (shell audit S1). */
     retry?: () => void;
-    /** Extra attributes and style for each cell's frame, e.g. a print policy the host doesn't apply yet. */
     frameProps?: (cell: PageCell, contract: ComponentContract | undefined) => FrameProps | undefined;
+    cellProps?: (cell: PageCell) => Record<string, unknown> | undefined;
 };
 export type PageRendererProps = {
     runtime: PageRuntime;
@@ -55,14 +30,7 @@ export type PageRendererProps = {
     params: Record<string, unknown>;
     baseProps: unknown;
     context: Record<string, unknown>;
-    /** The signed-in person, for `@viewer.*` in props (design/data.md §5). */
     viewer?: unknown;
     environment: RendererEnvironment;
 };
-/**
- * One page, one renderer (design/core.md §3, stages 4–5). It fetches nothing:
- * the page's data comes in `runtime` (loadPageData) and its bundles in
- * `bundles`. On the server the bundles haven't imported, so each cell renders
- * as a placeholder sized by its layout.
- */
 export declare function PageRenderer({ runtime, bundles, params, baseProps, context, viewer, environment }: PageRendererProps): import("react").JSX.Element;

package/dist/types/react/structure-view.d.ts

@@ -5,21 +5,9 @@ type Derived = {
     numbering: SectionNumbering;
     references: SectionReferences;
 };
-/**
- * Numbering and references for the whole page, derived once: a nested
- * renderer that re-derived them from its subtree would number the same
- * section differently. Clause citations read each cell's resolved `props.blocks`.
- */
 export declare function useStructureFacts(structure: LayoutNode[], cells: PageCell[], env: CellEnvironment, documents: Record<string, {
     label?: unknown;
 }> | undefined): Derived;
-/**
- * The document renderer (the PWA's StructureRenderer). A node naming a cell
- * renders it with the whole document's numbering, levels, titles, anchors and
- * references for the node's own document, and with the node's children as the
- * cell's child cells. A section node is a real `<section>` with a heading; a
- * container section with no cell renders its children itself.
- */
 export declare function StructureView({ nodes, env, facts, level, documentId, }: {
     nodes: Array<LayoutNode | string> | ResolvedLayoutNode[];
     env: CellEnvironment;

package/dist/types/react/use-cell-store.d.ts

@@ -1,11 +1,6 @@
 import type { StackStoreApi } from '../core/store/create-store.js';
 import { type ScopeContext } from '../core/store/scope-keys.js';
 import type { PageCell } from '../core/types.js';
-/**
- * A cell's `selections`, `viewState` and `live` props from the shared store.
- * The selector returns values only, compared shallowly, so a cell re-renders
- * only when one of its own channels changes; setters are attached after.
- */
 export declare function useCellStore(cell: PageCell, scope: ScopeContext, api: StackStoreApi): {
     selections: import("../core/index.js").ProjectedBundle | undefined;
     viewState: import("../core/index.js").ProjectedBundle | undefined;

package/dist/types/react/use-container-size.d.ts

@@ -3,9 +3,4 @@ export type Size = {
     width: number;
     height: number;
 };
-/**
- * The element's measured size, in whole pixels, updated at most once per
- * frame (design/core.md §4). Only for components that declare they need it:
- * CSS container queries cover the rest for free.
- */
 export declare function useContainerSize(ref: RefObject<HTMLElement | null>, enabled: boolean): Size | undefined;

package/dist/types/react/use-forms-runtime.d.ts

@@ -0,0 +1,147 @@
+import { type KeyboardEvent } from 'react';
+import { type DisplayMode, type FileToUpload, type FormLink, type FormModel, type FormQuestionDefinition, type FormsPort, type FormsRefusal, type Position, type StepKind, type SubmissionStatus } from '../forms/index.js';
+export declare const FORM_SAVE_DEBOUNCE_MS = 3000;
+export type FormSaveState = 'idle' | 'saving' | 'saved' | 'error';
+export type FormAnswer = {
+    key: string;
+    label: string;
+    question: FormQuestionDefinition | null;
+    value: unknown;
+    change(value: unknown): void;
+    readOnly: boolean;
+    required: boolean;
+    missing: boolean;
+    refusal: string | null;
+    inputId: string;
+    upload?(file: FileToUpload): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        refusal: string;
+    }>;
+    openFile?(): Promise<string | null>;
+};
+export declare const answerInputId: (key: string) => string;
+export type FormSlotProps = {
+    title: string;
+    chapter: {
+        id: string;
+        title: string;
+    } | null;
+    step: {
+        id: string;
+        title: string;
+        index: number;
+        count: number;
+        kind: StepKind;
+        label?: string;
+    };
+    sections: Array<{
+        id: string;
+        title: string;
+        chapter?: string;
+        kind: StepKind;
+        label?: string;
+        complete: boolean;
+        answered: number;
+        total: number;
+        current: boolean;
+    }>;
+    progress: {
+        answered: number;
+        required: number;
+        ratio: number;
+        total: {
+            answered: number;
+            count: number;
+        };
+    };
+    question: {
+        index: number;
+        count: number;
+        key: string;
+        next: {
+            label: string;
+        } | null;
+        answer?: FormAnswer;
+    } | null;
+    goToQuestion(key: string): void;
+    displayMode: DisplayMode;
+    setDisplayMode(mode: DisplayMode): void;
+    goToSection(stepId: string): void;
+    advance(): void;
+    back(): void;
+    canBack: boolean;
+    next: {
+        title: string;
+    } | null;
+    submit?: {
+        label: string;
+        run(): void;
+        blocked: boolean;
+    } | null;
+    reopen?: {
+        label: string;
+        run(): void;
+    } | null;
+    save: {
+        state: FormSaveState;
+        at?: string;
+        error?: string;
+    };
+    missing: Array<{
+        key: string;
+        label: string;
+    }>;
+    chapters?: Array<{
+        id: string;
+        title: string;
+    }>;
+    status?: SubmissionStatus | null;
+    readOnly?: boolean;
+    review?: {
+        status: SubmissionStatus;
+        note: string;
+        at: string;
+        by: string | null;
+    } | null;
+};
+export type FormsRuntimeOptions = {
+    model: FormModel;
+    port: FormsPort;
+    initial: Record<string, {
+        value: unknown;
+        stateId?: string | null;
+    }>;
+    status: SubmissionStatus | null;
+    visited?: string[];
+    link?: FormLink;
+    phone?: boolean;
+    onNavigate?(link: FormLink, how: {
+        replace: boolean;
+    }): void;
+    describe?(code: FormsRefusal): string;
+    notes?: Array<{
+        at: string;
+        text: string;
+        status?: SubmissionStatus;
+        by?: string | null;
+    }>;
+};
+export declare function useFormsRuntime(o: FormsRuntimeOptions): {
+    slots: FormSlotProps | null;
+    cellProps: (cell: {
+        id: string;
+    }) => Record<string, unknown> | undefined;
+    steps: import("../forms/index.js").FormStep[];
+    step: import("../forms/index.js").FormStep;
+    position: Position | null;
+    values: Record<string, unknown>;
+    change: (key: string, value: unknown) => void;
+    flush: () => Promise<void>;
+    readOnly: boolean;
+    status: SubmissionStatus | null;
+    headingRef: import("react").RefObject<HTMLElement | null>;
+    contentRef: import("react").RefObject<HTMLElement | null>;
+    onKeyDown: (e: KeyboardEvent) => void;
+};

package/dist/types/react/use-paging.d.ts

@@ -1,22 +1,13 @@
 import type { QueryPage } from '../core/load-page.js';
 import type { DataContext, DataEntry, PageCell } from '../core/types.js';
-/** Loads one more page of a paged label (RendererEnvironment.loadPage): the host's read, as the viewer. */
 export type LoadPage = (descriptor: NonNullable<DataEntry['page']>['descriptor'], variables: Record<string, unknown>) => Promise<QueryPage>;
-/** A paged label as a component sees it (apps.md §6). */
 export type LabelPaging = {
     hasMore: boolean;
     isLoadingMore: boolean;
     error: Error | null;
     loadMore: () => void;
 };
-/** The labels a cell reads: those it declares, and those its props reference. */
 export declare function cellLabels(cell: Pick<PageCell, 'props' | 'data'>): Set<string>;
-/**
- * A cell's paged labels (QueryDescriptor.paging): the pages it has loaded
- * beyond the first, appended to each label's data, and `loadMore` /
- * `hasMore` per label. A label whose first page reloads (a write, Realtime)
- * starts again from that page.
- */
 export declare function usePaging(cell: Pick<PageCell, 'props' | 'data'>, entries: DataContext, loadPage: LoadPage | undefined): {
     data: DataContext;
     paging: Record<string, LabelPaging> | undefined;

package/dist/types/runtime/boot.d.ts

@@ -1,18 +1,7 @@
 import { type SharedImport } from '@peripheries/runtime';
-/**
- * A classic inline script that must run before any module: it creates the
- * promise every shim awaits. `installRuntime` resolves it.
- */
 export declare const RUNTIME_BOOT_SCRIPT: string;
-/**
- * The import map for a page: the pinned runtimes plus the shared lineages'
- * live versions (design/core-and-tokens.md §4). One map per page, because
- * Firefox doesn't merge several and a merged map keeps the first rule.
- */
 export declare function importMapFor(shared?: readonly SharedImport[]): {
     imports: Record<string, string>;
 };
-/** `importMapFor`, serialised for `<script type="importmap">`. `<` is escaped so a URL can't close the script. */
 export declare function importMapJson(shared?: readonly SharedImport[]): string;
-/** The import map with no shared lineages, serialised for `<script type="importmap">`. */
 export declare const IMPORT_MAP_JSON: string;

package/dist/types/runtime/install.d.ts

@@ -1,5 +1,4 @@
 import { READY_GLOBAL, RESOLVE_GLOBAL, RUNTIME_GLOBAL, type RuntimeSpecifier } from '@peripheries/runtime';
-/** `@peripheries/ui` is lent by the host (`extra`), not installed by the renderer. */
 export type StackRuntime = Record<Exclude<RuntimeSpecifier, '@peripheries/ui'>, unknown> & Record<string, unknown>;
 type RuntimeGlobals = {
     [RUNTIME_GLOBAL]?: StackRuntime;
@@ -7,20 +6,6 @@ type RuntimeGlobals = {
     [RESOLVE_GLOBAL]?: () => void;
     require?: (specifier: string) => unknown;
 };
-/**
- * The host's module instances by specifier. `extra` is what the host lends beyond the
- * renderer's own (`@peripheries/ui`), so the published renderer depends on nothing it
- * doesn't install itself.
- */
 export declare function buildRuntime(extra?: Record<string, unknown>): StackRuntime;
-/**
- * Puts the host's module instances where the `/_shared/*.js` shims look for
- * them, and releases every shim waiting on the boot promise. Idempotent.
- *
- * Also installs a `globalThis.require` for Rolldown's CJS interop: bundles
- * built with Vite 8 call `require('react')` from transitive CJS dependencies
- * at module init, which throws in a browser without it. The runtime modules
- * are already loaded, so it answers synchronously.
- */
 export declare function installRuntime(g?: RuntimeGlobals, extra?: Record<string, unknown>): StackRuntime;
 export { runtimeReady } from '../core/bundles/load.js';

package/dist/types/runtime/shims.d.ts

@@ -1,11 +1,3 @@
 import { type RuntimeSpecifier } from '@peripheries/runtime';
-/** Output file name, taken from the URL the import map advertises, so the two can't disagree. */
 export declare function shimFileName(specifier: RuntimeSpecifier): string;
-/**
- * An ESM module that forwards `specifier` to the host's instance.
- *
- * It awaits the ready promise the boot script creates, so a bundle imported
- * before the host has installed its runtime waits instead of failing: the
- * "Failed to resolve module specifier" race cannot happen (channel-06 #10).
- */
 export declare function renderShim(specifier: RuntimeSpecifier, names: string[], hasDefault: boolean): string;

package/dist/types/runtime/store-export.d.ts

@@ -1,14 +1,7 @@
 import { type StackStoreApi } from '../core/store/create-store.js';
 import type { LiveEntry, ScopeId, StackStoreState } from '../core/store/types.js';
 export declare function getStackStore(): StackStoreApi;
-/**
- * Forget everything the shared store holds for the current viewer: its
- * selections, view state and live data, and every persisted scope. The host
- * calls it when the signed-in user changes or signs out, so nothing one
- * viewer selected or saw survives into the next viewer's session.
- */
 export declare function resetStackStore(): void;
-/** Subscribe a component to a slice of the shared store. */
 export declare function useStackStore<T>(selector: (state: StackStoreState) => T): T;
 export declare const selectors: {
     selection: (scope: ScopeId, channel: string) => (s: StackStoreState) => unknown;

package/dist/types/testing/base-props.d.ts

@@ -1,3 +1,2 @@
 import type { BaseProps } from '@peripheries/runtime';
-/** What every cell gets as `baseProps` on a golden page: a synthetic viewer of the example client org. */
 export declare const FIXTURE_BASE_PROPS: BaseProps;

package/dist/types/testing/components.d.ts

@@ -12,22 +12,15 @@ type SectionMaps = {
     }>;
 };
 export declare function Masthead({ title, subtitle }: Props): import("react").JSX.Element;
-/** Authored text arrives as `children` unless the cell has child cells. */
 export declare function Prose({ children }: Props): import("react").JSX.Element;
-/** A section body in the style of an org bundle's DocumentSection: it owns its section's anchor. */
 export declare function DocumentSection({ sectionId, title, body, blocks, children, sectionNumbers, sectionAnchors }: Props & SectionMaps): import("react").JSX.Element;
-/** A same-page citation: `§<number> <title>`, plus the clause's letter when it names one. */
 export declare function SectionReference({ to, sectionReferences }: Props & SectionMaps): import("react").JSX.Element;
 export declare function KpiCard({ label, value, data, status }: Props): import("react").JSX.Element;
-/** Writes a shared selection. */
 export declare function OptionList({ options, selections }: Props): import("react").JSX.Element;
-/** Reads the same selection. */
 export declare function SelectionEcho({ selections }: Props): import("react").JSX.Element;
 export declare function Boom(): never;
-/** Lists a walk's nodes with their plan and data states, as a backlog or flow cell would. */
 export declare function FlowList({ nodes, edges }: Props): import("react").JSX.Element;
 export declare function Badge({ text }: Props): import("react").JSX.Element;
-/** The example client org's main lineage. */
 export declare const clientKit: {
     Masthead: typeof Masthead;
     Prose: typeof Prose;
@@ -39,7 +32,6 @@ export declare const clientKit: {
     FlowList: typeof FlowList;
     Boom: typeof Boom;
 };
-/** The advisor org's main lineage: its own Prose (which the client's shadows) and a Badge only it has. */
 export declare const advisorKit: {
     Prose: ({ children }: Props) => import("react").JSX.Element;
     Badge: typeof Badge;

package/dist/types/testing/form-workbook.d.ts

@@ -0,0 +1,103 @@
+import { type FormItem, type FormModel } from '../forms/index.js';
+export declare const formWorkbookPage: {
+    id: string;
+    name: string;
+    org_id: string;
+    project_id: string;
+    process_id: null;
+    graph_node_id: null;
+    page_type: string;
+    status: string;
+    is_template: boolean;
+    metadata: null;
+    content: {
+        cells: ({
+            id: string;
+            component: string;
+            props: {
+                blocks: {
+                    text: string;
+                }[];
+                question?: undefined;
+            };
+            when?: undefined;
+        } | {
+            id: string;
+            component: string;
+            props: {
+                question: {
+                    key: string;
+                    label: string;
+                    type: string;
+                    required: boolean;
+                    options?: undefined;
+                };
+                blocks?: undefined;
+            };
+            when?: undefined;
+        } | {
+            id: string;
+            component: string;
+            props: {
+                question: {
+                    key: string;
+                    label: string;
+                    type: string;
+                    required: boolean;
+                    options: {
+                        value: string;
+                        label: string;
+                    }[];
+                };
+                blocks?: undefined;
+            };
+            when?: undefined;
+        } | {
+            id: string;
+            component: string;
+            props: {
+                question: {
+                    key: string;
+                    label: string;
+                    type: string;
+                    required: boolean;
+                    options?: undefined;
+                };
+                blocks?: undefined;
+            };
+            when: {
+                all: {
+                    q: string;
+                    op: string;
+                    value: string;
+                }[];
+            };
+        } | {
+            id: string;
+            component: string;
+            props: {
+                blocks?: undefined;
+                question?: undefined;
+            };
+            when?: undefined;
+        })[];
+    };
+    layout: {
+        type: string;
+        chapters: {
+            id: string;
+            title: string;
+        }[];
+        steps: {
+            id: string;
+            title: string;
+            chapter: string;
+            cell_ids: string[];
+        }[];
+        submit: {
+            required: string;
+        };
+    };
+};
+export declare function formWorkbookItem(cellId: string): FormItem | null;
+export declare const formWorkbookModel: () => FormModel;

package/dist/types/testing/golden.d.ts

@@ -8,49 +8,33 @@ export type GoldenBundle = {
 };
 export type GoldenPage = {
     name: string;
-    /** What it proves, in one line. */
     purpose: string;
     page: ProjectPage;
-    /** The process row: its id and its `<tier>_<role>_system_id` columns. */
     process?: {
         id: string;
     } & Record<string, string | null>;
-    /** walk_graph's answers, by start node (and depth, when two walks share a start); states keyed by system id. */
     walks?: Array<{
         start: string;
         maxDepth?: number;
         result: RawWalk;
     }>;
-    /** Newest `page_cell_config` per cell node (cell_config_latest). */
     configs?: Array<{
         system_id: string;
         graph_node_id: string;
         config: Record<string, unknown>;
     }>;
-    /** Newest state per node (node_state_latest). */
     states?: Array<{
         system_id: string;
         graph_node_id: string;
         data: unknown;
     }>;
-    /**
-     * Queries' answers by operation name: what the label holds, already shaped
-     * (design/data.md §6). A function of the variables answers per viewer or per id.
-     */
     queries?: Record<string, unknown | ((variables: Record<string, unknown>) => unknown)>;
-    /** Live bundles the viewer can see; the page's scope picks among them. */
     bundles: GoldenBundle[];
-    /** The org template's advisor org, whose main lineage is in scope after the page's own org. */
     advisorOrgId?: string;
 };
-/** An SCG document: a frame cell, then sections numbered through a transparent container, a clause citation and child cells. */
 export declare const documentPage: GoldenPage;
-/** A grid dashboard fed by declared producers, with conditions, a crash, a missing component and a shared selection. */
 export declare const dashboardPage: GoldenPage;
-/** A legacy page of thin refs: configs from the cells' DSNS, their declarations hoisted, one config missing. */
 export declare const thinRefPage: GoldenPage;
-/** Every cell form on one page: inline, refs (one with a config, one falling back), a legacy thin ref, form 4, and a cross-org bundle. */
 export declare const mixedPage: GoldenPage;
-/** Walks from the page node: @_traversal with two systems, walk labels scoped to their cell, declarations winning, walks skipped when not needed. */
 export declare const walkPage: GoldenPage;
 export declare const GOLDEN_PAGES: GoldenPage[];

package/dist/types/testing/ids.d.ts

@@ -1,7 +1,5 @@
-/** A synthetic UUID: `fixtureId(7)` → `00000000-0000-4000-8000-000000000007`. */
 export declare const fixtureId: (n: number) => string;
 export declare const FIXTURE_ID: RegExp;
-/** The only org slugs and email domain a fixture may use. */
 export declare const FIXTURE_ORG_SLUGS: readonly ["example-client", "example-advisor"];
 export declare const FIXTURE_EMAIL_DOMAIN = "example.test";
 export declare const CLIENT_ORG: {

package/dist/types/testing/index.d.ts

@@ -3,3 +3,4 @@ export * as fixtureComponents from './components.js';
 export { dashboardPage, documentPage, GOLDEN_PAGES, mixedPage, thinRefPage, walkPage, type GoldenBundle, type GoldenPage } from './golden.js';
 export { ADVISOR_ORG, CLIENT_ORG, FIXTURE_EMAIL_DOMAIN, FIXTURE_ID, FIXTURE_ORG_SLUGS, fixtureId } from './ids.js';
 export { goldenBundleRow, goldenBundles, goldenGraphSource, goldenScope, type SourceCall } from './sources.js';
+export { formWorkbookItem, formWorkbookModel, formWorkbookPage } from './form-workbook.js';

package/dist/types/testing/sources.d.ts

@@ -8,18 +8,11 @@ export type SourceCall = {
     method: keyof GraphSource;
     args: unknown[];
 };
-/** A GraphSource over a golden page's process, configs, states and walks. */
 export declare function goldenGraphSource(g: GoldenPage): GraphSource & {
     calls: SourceCall[];
 };
-/** A golden bundle's registry row: every export, under its own name. */
 export declare function goldenBundleRow(b: GoldenBundle): BundleRow;
-/** The page's bundle scope, nearest first: its own refs, then its org's main lineage, then the advisor org's. */
 export declare function goldenScope(g: GoldenPage): LineageRef[];
-/**
- * The page's bundles, "imported" from the golden modules. `loaded: false` gives
- * what the server renders with: the rows, and no bundle yet.
- */
 export declare function goldenBundles(g: GoldenPage, cells: PageCell[], { loaded }?: {
     loaded?: boolean | undefined;
 }): PageBundles;

package/dist/types/theme/check.d.ts

@@ -1,6 +1,4 @@
 import type { ThemeV2 } from '@peripheries/runtime';
 import type { ThemeDiagnostic } from './parse.js';
-/** [foreground, background, minimum ratio]: 4.5 for text, 3 for UI and large text. */
 export declare const CONTRAST_PAIRS: readonly (readonly [string, string, number])[];
-/** Contrast warnings for the theme's merged tier. Pairs whose values don't resolve to colours are skipped. */
 export declare function checkTheme(theme: ThemeV2, base?: Record<string, string>): ThemeDiagnostic[];

package/dist/types/theme/color.d.ts

@@ -1,29 +1,17 @@
-/** A gamma-encoded sRGB colour, every channel 0–1. */
 export type Rgb = {
     r: number;
     g: number;
     b: number;
     alpha: number;
 };
-/** OKLCH: lightness 0–1, chroma (0–~0.4), hue in degrees. */
 export type Oklch = {
     l: number;
     c: number;
     h: number;
 };
-/** Parse a CSS colour: hex (#rgb, #rgba, #rrggbb, #rrggbbaa), rgb()/rgba(), hsl()/hsla() or oklch(), legacy or modern syntax. */
 export declare function parseColor(value: string): Rgb | null;
-/** `#rrggbb`, or `#rrggbbaa` when the colour is translucent. */
 export declare function toHex(color: Rgb): string;
-/** sRGB → OKLCH (alpha is dropped). Achromatic colours get hue 0. */
 export declare function toOklch(color: Rgb): Oklch;
-/** OKLCH → sRGB, mapped into gamut by reducing chroma at the same lightness and hue. */
 export declare function fromOklch(color: Oklch): Rgb;
-/** WCAG 2.x relative luminance. */
 export declare function relativeLuminance(color: Rgb): number;
-/**
- * WCAG 2.x contrast ratio (1–21) of a foreground on a background. A
- * translucent foreground is composited over the background, a translucent
- * background over white. Null when either colour doesn't parse.
- */
 export declare function contrastRatio(foreground: Rgb | string, background: Rgb | string): number | null;

package/dist/types/theme/derive.d.ts

@@ -1,18 +1,6 @@
 import type { ThemeV2 } from '@peripheries/runtime';
 import { type Rgb } from './color.js';
-/** What the derivation and the check assume when neither the theme nor the base sets them. */
 export declare const FALLBACK_BASE: Readonly<Record<string, string>>;
-/** Follow `var(--x)` through a flat token map (keys without `--`) to a colour. */
 export declare function resolveColor(value: string | undefined, tokens: Record<string, string>, depth?: number): Rgb | null;
-/**
- * The semantic overrides a theme sets (names without `--`). `base` is core's
- * flat default map; it supplies the background and text the derivation
- * contrasts against when the theme doesn't set them. Explicit `tokens` win.
- */
 export declare function themeTokens(theme: ThemeV2, base?: Record<string, string>): Record<string, string>;
-/**
- * The overrides as the `theme` cascade layer, one declaration per line,
- * sorted; '' when the theme sets nothing. A value that could break out of
- * a declaration or the `<style>` element is dropped.
- */
 export declare function themeCss(theme: ThemeV2, base?: Record<string, string>): string;

package/dist/types/theme/parse.d.ts

@@ -5,18 +5,11 @@ export type ThemeDiagnostic = {
     message: string;
     severity: 'error' | 'warning';
 };
-/** A value that is safe to write into a declaration in a `<style>` element. */
 export declare const isSafeCssValue: (value: string) => boolean;
-/** `var(--name)` or `var(--name, fallback)`. */
 export declare const VAR_REF: RegExp;
 type Read = {
     theme: ThemeV2;
     diagnostics: ThemeDiagnostic[];
 };
-/**
- * A template's theme as version 2. `version: 2` is validated as written; no
- * version (or `version: 1`) is the legacy shape, mapped per
- * design/core-and-tokens.md §6.1. Bad values are dropped with a diagnostic.
- */
 export declare function parseTheme(raw: unknown): Read;
 export {};