@peripheries/renderer 0.23.0 → 0.24.0

package/dist/types/core/query.d.ts

@@ -1,59 +1,23 @@
 import { type QueryDescriptor, type QueryOrderBy } from '@peripheries/runtime';
 import type { Diagnostic } from './graph.js';
 import { type ResolutionContext } from './references.js';
-/**
- * Functions a render-time document may read, with the tables each reads (for
- * invalidation). pg_graphql reflects every stable function the role can run
- * as a Query field, and many are SECURITY DEFINER, so a function is allowed
- * only by name, once a database test has pinned it as stable, SECURITY
- * INVOKER, closed to anon and with a fixed search_path
- * (tests/integration/graph-reads.test.ts).
- */
 export declare const RENDER_FUNCTIONS: Readonly<Record<string, readonly string[]>>;
-/**
- * Render functions declared before the schema milestone that brings them, by milestone: a
- * document may name one now, and it reads nothing until the function exists. The database test
- * checks each like the rest once it exists, and fails if its milestone is in and it still isn't.
- */
 export declare const RENDER_FUNCTIONS_AHEAD: Readonly<Record<string, string>>;
 export type PreparedDocument = {
     text: string;
     operationName: string | undefined;
-    /** Root entity names, e.g. `project_page` for `project_pageCollection`; `*` for `node`; a render function's tables. */
     entities: readonly string[];
-    /** Stable short hash of the prepared text; part of query keys. */
     hash: string;
 };
 export declare class UnsafeDocumentError extends Error {
     name: string;
-    /** The diagnostic a descriptor's check reports; DESCRIPTOR_DOCUMENT_INVALID when unset. */
     readonly code?: 'DESCRIPTOR_VERSION_FILTER' | 'DESCRIPTOR_STATE_UNSCOPED';
     constructor(message: string, options?: {
         code: 'DESCRIPTOR_VERSION_FILTER' | 'DESCRIPTOR_STATE_UNSCOPED';
     });
 }
-/**
- * The collections a render-time document reads main rows of only (versions.md §4.6, graph-model
- * G1 · DF M0): prepareDocument adds `version: { is: NULL }` to each one's filter, at any depth.
- * A branch is read through a version context, never a hand-written filter, so a document that
- * filters on `version` itself is refused.
- */
 export declare const MAIN_ONLY_COLLECTIONS: ReadonlySet<string>;
-/**
- * A GraphQL document checked against the render-time rule (design/renderer.md
- * §4.5) and ready to send: exactly one `query` operation whose root fields are
- * table or view collections, `ByPk` reads, `node`, or a render function.
- * `__typename` is added to every nested selection, so a host can find JSON
- * columns in the result. Throws UnsafeDocumentError.
- */
 export declare function prepareDocument(source: string): PreparedDocument;
-/**
- * The shape of a query's result, from its selection alone (design/data.md
- * §2.1): a field without a selection set is a `leaf` (a scalar, a JSON column
- * or an array column, so any path below it may exist); `edges { node }` is a
- * list. With `flatten_connections`, a connection that selects edges is the
- * list of its nodes, as the host shapes it.
- */
 export type SelectionShape = {
     kind: 'leaf';
 } | {
@@ -63,53 +27,25 @@ export type SelectionShape = {
     kind: 'list';
     of: SelectionShape;
 };
-/** The shape a document's selection yields, before `result.path`. */
 export declare function selectionShape(document: string, flatten?: boolean): SelectionShape;
-/**
- * The shape at a dot path, or null when the selection doesn't select it. A
- * numeric segment indexes a list; anything below a leaf is accepted.
- */
 export declare function shapeAt(shape: SelectionShape, path: readonly string[]): SelectionShape | null;
-/** What a descriptor's label holds: its selection, flattened, at `result.path`. Null when the path isn't selected. */
 export declare function descriptorShape(descriptor: QueryDescriptor): SelectionShape | null;
-/** Namespaces a variable may read, besides labels (design/data.md §5). */
 export declare const VARIABLE_NAMESPACES: readonly ["params", "baseProps", "viewer", "context"];
-/** Every whole-string reference in a descriptor's variables, by the label or namespace it reads. */
 export declare function variableReferences(variables: unknown): Array<{
     ref: string;
     label: string;
 }>;
-/** The labels (not namespaces) a descriptor's variables read: what decides its round (design/data.md §5, §6). */
 export declare const variableLabels: (descriptor: Pick<QueryDescriptor, "variables">) => string[];
-/**
- * A descriptor's static checks (design/data.md §4): the version-1 shape, one
- * query operation under the render-time rule, every required variable given
- * (`$orderBy` by `order_by`), references well formed, and `result.path`
- * selected. It doesn't run anything; a dry run under a real viewer checks the
- * rest against the database. `path` prefixes each diagnostic's path.
- */
 export declare function validateDescriptor(descriptor: unknown, path?: string): Diagnostic[];
-/** `order_by` as pg_graphql's `orderBy` argument: `[{ updated_at: DescNullsLast }]`. */
 export declare const orderByVariable: (orderBy: readonly QueryOrderBy[]) => {
     [x: string]: string;
 }[];
 export type ResolvedVariables = {
     variables: Record<string, unknown>;
-    /** References that resolved to nothing (null or undefined): the query doesn't run (QUERY_UNRESOLVED). */
     unresolved: string[];
-    /** References whose data is still loading: the query waits. */
     pending: string[];
 };
-/**
- * A descriptor's variables, resolved with the one reference grammar (the same
- * resolver as props), plus `$orderBy` from `order_by` when the document
- * declares it. A whole-string reference that resolves to null or nothing is
- * unresolved; interpolation (`${x}`) works as in props.
- */
 export declare function resolveDescriptorVariables(descriptor: QueryDescriptor, ctx: ResolutionContext): ResolvedVariables;
-/** The variables a paged descriptor's document declares and the renderer sets. */
 export declare const PAGING_VARIABLES: ReadonlySet<string>;
-/** A paged descriptor's variables for one page: `$first` its size, `$after` the cursor (null for the first page). */
 export declare const pageVariables: (descriptor: QueryDescriptor, variables: Record<string, unknown>, after?: string | null) => Record<string, unknown>;
-/** One query per distinct question: the document and the resolved variables, and the result's shape. */
 export declare const queryKey: (descriptor: QueryDescriptor, variables: Record<string, unknown>) => string;

package/dist/types/core/references.d.ts

@@ -3,16 +3,11 @@ import type { DataContext } from './types.js';
 export type ResolutionContext = {
     data: DataContext;
     params: Record<string, unknown>;
-    /** Told of each whole-string `@ref` that resolves to nothing (a missing label, path or leaf), except while its data loads. */
     onUnresolved?: (ref: string) => void;
-    /** Told of each whole-string `@ref` whose data is still loading. */
     onLoading?: (ref: string) => void;
-    /** Told of each resolved leaf, by its prop path, with where its value came from (INV-DOC-6; sources.ts). */
     onSource?: OnSource;
 };
-/** The key that marks a projection: `{ "@each": "@label.path", "as": "item", "map": … }`. */
 export declare const EACH = "@each";
-/** The element's label inside `map` when `as` is not given. */
 export declare const EACH_DEFAULT_AS = "item";
 export type Each = {
     [EACH]: string;
@@ -20,17 +15,12 @@ export type Each = {
     map: unknown;
 };
 export declare const isEach: (value: unknown) => value is Each;
-/**
- * Resolve every string in a value, recursively through arrays and plain objects. Keys aren't
- * resolved. `at` is the value's path among the props, for `onSource`.
- */
 export declare function resolveReferences<T = unknown>(value: T, ctx: ResolutionContext, at?: string[]): T;
 export declare const settled: (data: unknown) => {
     data: unknown;
     isLoading: boolean;
     error: null;
 };
-/** What a cell brings to its own resolution (loadPageData's CellData), and the labels the page declares. */
 export type CellScope = {
     static?: DataContext;
     declared?: DataContext;
@@ -43,14 +33,6 @@ export type CellScope = {
     };
     pageDeclared?: ReadonlySet<string>;
 };
-/**
- * The context one cell resolves against (design/renderer.md §5.2), lowest
- * first: the page's static values, the cell's own static values, the labels
- * the cell's walk found, the page's declarations, the cell's own
- * declarations; then the reserved
- * `_traversal`, `params`, `baseProps`, `viewer` and `context`, which nothing
- * can shadow. Explicit beats discovered: no walk label replaces a declared one.
- */
 export declare function cellResolutionContext(_cell: {
     data?: {
         queries?: Record<string, unknown>;
@@ -59,7 +41,6 @@ export declare function cellResolutionContext(_cell: {
     viewer?: unknown;
     context?: unknown;
 }): ResolutionContext;
-/** The location context every cell on a page shares (core.md §8): the host's, with the page's own ids. */
 export declare const pageContext: (context: Record<string, unknown> | undefined, page: {
     id: string;
     project_id: string | null;
@@ -69,14 +50,12 @@ export declare const pageContext: (context: Record<string, unknown> | undefined,
     projectId: string | null;
     processId: string | null;
 };
-/** One cell's location context: the page's, with the cell's own node. */
 export declare const cellContext: (context: Record<string, unknown>, cell: {
     graph_node_id?: string;
     metadata?: Record<string, unknown>;
 }) => {
     nodeId: string | undefined;
 };
-/** showIf / hideIf: values (usually strict refs) tested for truthiness. An empty string skips the check. */
 export declare function passesConditions(conditions: {
     showIf?: unknown;
     hideIf?: unknown;

package/dist/types/core/release.d.ts

@@ -1,21 +1,11 @@
 import type { ReleaseProblem } from '@peripheries/runtime';
 import type { ProjectPage } from './types.js';
 import { type Catalog } from './validate.js';
-/** One page the release records: the node it lives on (the anchor, or its artifact) and its document. */
 export type ManifestPage = {
     graphNodeId: string;
     page: Pick<ProjectPage, 'content' | 'layout'> & {
         is_template?: boolean | null;
     };
 };
-/** The pages' errors as VERSION_INVALID's problems: a release that has any isn't cut. Warnings don't stop one. */
 export declare function validateManifest(pages: ManifestPage[], catalog?: Catalog): ReleaseProblem[];
-/**
- * A page artifact's data state as a ManifestPage (pages.md §2): the artifact's `data` is the page
- * document itself (`cells`, `data`, page configuration such as `layout.editing`), each cell
- * carrying the `layout_entry` the publish splits into the row's `layout.structure`. So the
- * document is the content, and a `layout` key, when the artifact has one, the layout. The
- * structure isn't rebuilt from the entries (the publish's split), so STRUCTURE_INVALID is judged
- * at publish, not here.
- */
 export declare function manifestPageFrom(graphNodeId: string, data: unknown): ManifestPage;

package/dist/types/core/rules.d.ts

@@ -1,3 +1,2 @@
-/** The page layout types `pageContainerStyle` and the structure renderer handle. */
 export declare const LAYOUT_TYPES: readonly ["stack", "grid", "flex", "document"];
 export declare const PAGE_RULES: string;

package/dist/types/core/selected.d.ts

@@ -1,9 +1,4 @@
 import type { QueryDescriptor } from '@peripheries/runtime';
 import type { Diagnostic } from './graph.js';
 import type { PageCell } from './types.js';
-/**
- * The paths one cell's props and conditions read from the given query labels
- * that the queries don't select. Inside an `@each` over a query's list, the
- * element's paths are checked against the list's element. `at` prefixes paths.
- */
 export declare function selectionIssues(cell: Pick<PageCell, 'id' | 'props' | 'conditions'>, queries: Record<string, QueryDescriptor>, at: string): Diagnostic[];

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

@@ -2,47 +2,29 @@ import { type VersionContext } from '@peripheries/runtime';
 import type { CellSource, ResolvedCell } from './cells.js';
 import type { PageRuntime } from './load-page.js';
 import type { StateOrigin } from './types.js';
-/** Where one prop's value came from. `path` is where the value sits in its source. */
-export type PropSource = 
-/** A node's state (a declared binding, or an element of an `@each` over one): `path` is inside the state's data. */
-{
+export type PropSource = {
     kind: 'state';
     graphNodeId: string;
     reads: StateOrigin[];
     path: string[];
-}
-/** A literal in the cell's props, at its prop path. */
- | {
+} | {
     kind: 'literal';
     path: string[];
-}
-/** A literal in the page's or the cell's static data (`data.static`): `path` starts with its label. */
- | {
+} | {
     kind: 'static';
     scope: 'page' | 'cell';
     path: string[];
-}
-/** Computed, queried, walked or the host's own: not editable. */
- | {
+} | {
     kind: 'derived';
     why: 'query' | 'walk' | 'record' | 'param' | 'reserved';
 };
-/** A prop path (`['items', '0', 'title']`) and its source. */
 export type PropSourceEntry = {
     prop: string[];
     source: PropSource;
 };
-/** Told of each leaf of a cell's resolved props, with its source. */
 export type OnSource = (prop: string[], source: PropSource) => void;
-/** Keys under a state that only the agency's tools write (data.md §9.5). */
 export declare const TOOL_OWNED_KEYS: readonly ["content_index", "ref_index"];
-/** A section's fields a person edits on the structure itself (data.md §9.5, `doc_edit_structure`). */
 export declare const STRUCTURE_FIELDS: readonly ["title", "applicable", "startsPage", "directed", "status"];
-/**
- * Where an edit of a value goes: the write function and the arguments that come from the source.
- * The new value (and, for a page edit, the version seen) is the caller's. `fn: null` says why the
- * value can't be edited here; the write functions still decide everything that can.
- */
 export type EditTarget = ({
     fn: 'doc_edit_content';
     graphNodeId: string;
@@ -61,59 +43,18 @@ export type EditTarget = ({
     fn: 'page_edit_data';
     path: string[];
 }) & {
-    /** The branch the edit writes (`p_version_id`, versions.md §4.3); absent on main. */
     versionId?: string;
 } | {
     fn: null;
     reason: EditRefusal;
 };
-export type EditRefusal = 
-/** Computed, queried or walked: nothing holds it to edit. */
-'DERIVED'
-/** The cell's content is its node's `page_cell_config`, not the page's. */
- | 'NODE_CONFIG'
-/** A `data.static` literal of a cell whose content is its node's (NODE_CONFIG's case for static data). */
- | 'STATIC'
-/** The read didn't say which state it saw, so no version check is possible. */
- | 'NO_STATE_ID'
-/** The value merges more than one system's state, so which one to write is ambiguous. */
- | 'MERGED_READS'
-/** Not a data state (`<tier>_data`): the document write functions write data states only. */
- | 'NOT_DATA_STATE'
-/** A tool-owned index (`content_index`, `ref_index`). */
- | 'TOOL_OWNED'
-/**
- * An element of a list the write functions refused: a path whose index names no element
- * (`jsonb_set_path`). The host no longer refuses list paths itself: the functions write at a
- * path into a list (DF-SCH-9), and their dry run says whether the element exists.
- */
- | 'LIST_ELEMENT'
-/** Read at a release or a channel (or another scope's published version): releases are read-only (versions.md §5.3). */
- | 'VERSION_IS_RELEASE';
-/** The cell a value is in, and how its content was resolved (ResolvedCell.source). */
+export type EditRefusal = 'DERIVED' | 'NODE_CONFIG' | 'STATIC' | 'NO_STATE_ID' | 'MERGED_READS' | 'NOT_DATA_STATE' | 'TOOL_OWNED' | 'LIST_ELEMENT' | 'VERSION_IS_RELEASE';
 export type EditCell = {
     id: string;
     source?: CellSource;
 };
-/**
- * The write function an edit of this value goes to (design/data.md §9.5):
- * - a node's data state: a section's structure field or `order` to `doc_edit_structure`,
- *   anything else to `doc_edit_content`, with the state id the viewer saw;
- * - a literal in an inline cell, or its own `data.static`, to `page_edit_cell`'s path write, which
- *   writes the page artifact and the row together;
- * - the page's `data.static` to `page_edit_data`'s path write;
- * - everything else nowhere, with the reason.
- * Paths may run through list indices: the functions write at a path into a list (DF-SCH-9).
- */
 export declare function editTarget(source: PropSource, cell: EditCell, version?: VersionContext): EditTarget;
-/** A value at a path, as the nested object a patch is (`['props', 'caption']` → `{ props: { caption } }`). */
 export declare function patchAt(path: readonly string[], value: unknown): unknown;
-/**
- * One cell's props as the renderer resolves them (CellView), with each leaf's source and value,
- * without rendering: what an assistant reads to plan an edit (docs-forms M3). Null when the cell's
- * conditions hide it. The same resolution context CellView builds, from the same runtime; paged
- * labels' later pages aren't loaded, so a paged list reads its first page.
- */
 export declare function cellPropSources(runtime: Pick<PageRuntime, 'page' | 'data' | 'declared' | 'cellData'>, cell: ResolvedCell, env?: {
     params?: Record<string, unknown>;
     baseProps?: unknown;

package/dist/types/core/store/create-store.d.ts

@@ -1,11 +1,6 @@
 import { Store } from '@tanstack/store';
 import type { LiveEntry, ScopeId, SelectionsScope, StackStoreData, StackStoreState, ViewStateScope } from './types.js';
 export type StackStoreApi = ReturnType<typeof createStackStore>;
-/**
- * The shared store, on TanStack Store (design/bundles.md §5). One instance per
- * page tree. `getState()` returns the data with the actions, the shape the
- * PWA's zustand store exposed to the escape-hatch API.
- */
 export declare function createStackStore(initial?: Partial<StackStoreData>): {
     getState: () => StackStoreState;
     subscribe: (listener: (state: StackStoreState) => void) => import("@tanstack/store").Subscription;
@@ -22,6 +17,5 @@ export declare function createStackStore(initial?: Partial<StackStoreData>): {
     };
     _clearScope: (scope: ScopeId) => void;
     _reset: () => void;
-    /** The underlying TanStack store, for `useSelector`. */
     store: Store<StackStoreData, never>;
 };

package/dist/types/core/store/persistence.d.ts

@@ -7,5 +7,4 @@ export interface PersistedScope {
 export declare function loadScope(scope: ScopeId, mode: StorageMode): PersistedScope | null;
 export declare function saveScope(scope: ScopeId, slice: PersistedScope, mode: StorageMode): void;
 export declare function clearScope(scope: ScopeId, mode: StorageMode): void;
-/** Removes every persisted scope from session and local storage: a different viewer starts clean. */
 export declare function clearAllScopes(): void;

package/dist/types/core/store/projection.d.ts

@@ -2,14 +2,9 @@ import type { StackStoreApi } from './create-store.js';
 import { type ScopeContext } from './scope-keys.js';
 import type { LiveDeclarations, ProjectedBundle, ScopeId, SelectionDeclarations, StackStoreData, ViewStateDeclarations } from './types.js';
 export declare function projectSelections(decls: SelectionDeclarations | undefined, state: StackStoreData, ctx: ScopeContext): ProjectedBundle | undefined;
-/** Selections are read-only unless `writable`. */
 export declare function attachSelectionSetters(values: ProjectedBundle, decls: SelectionDeclarations, store: StackStoreApi, ctx: ScopeContext): ProjectedBundle;
 export declare function projectViewState(decls: ViewStateDeclarations | undefined, state: StackStoreData, ctx: ScopeContext): ProjectedBundle | undefined;
-/** viewState is writable unless `writable: false`. */
 export declare function attachViewStateSetters(values: ProjectedBundle, decls: ViewStateDeclarations, store: StackStoreApi, ctx: ScopeContext): ProjectedBundle;
-/** `live.<name>` is the data; `live.<name>Status` the envelope. */
 export declare function projectLive(decls: LiveDeclarations | undefined, state: StackStoreData): ProjectedBundle | undefined;
-/** Equality for a selector: re-render only when a projected channel changes. */
 export declare function shallowEqualBundle(a: ProjectedBundle | undefined, b: ProjectedBundle | undefined): boolean;
-/** Every scope a cell's declarations touch (for hydration and persistence). */
 export declare function collectScopeIds(ctx: ScopeContext, selections?: SelectionDeclarations, viewState?: ViewStateDeclarations): ScopeId[];

package/dist/types/core/store/scope-keys.d.ts

@@ -6,5 +6,4 @@ export interface ScopeContext {
     pageId?: string | null;
     projectId?: string | null;
 }
-/** `null` when the context lacks the id: no scope, so no value and no setter. */
 export declare function resolveScopeId(kind: ScopeKind, ctx: ScopeContext): ScopeId | null;

package/dist/types/core/store/types.d.ts

@@ -11,14 +11,11 @@ export interface LiveEntry<T = unknown> {
 export interface StackStoreData {
     selections: Record<ScopeId, SelectionsScope>;
     viewState: Record<ScopeId, ViewStateScope>;
-    /** Global, not scoped: a channel is one source. */
     live: Record<string, LiveEntry>;
 }
 export interface StackStoreActions {
-    /** Cell-facing, through projected setter props. */
     setSelection: (scope: ScopeId, channel: string, value: unknown) => void;
     setViewState: (scope: ScopeId, key: string, value: unknown) => void;
-    /** Host-internal. */
     _setLive: (channel: string, entry: LiveEntry) => void;
     _hydrateScope: (scope: ScopeId, slice: {
         selections?: SelectionsScope;
@@ -29,11 +26,8 @@ export interface StackStoreActions {
         viewState: ViewStateScope;
     };
     _clearScope: (scope: ScopeId) => void;
-    /** Empties selections, view state and live data: a different viewer starts clean. */
     _reset: () => void;
 }
-/** What a selector sees: the data plus the actions, as the PWA's zustand store exposed. */
 export type StackStoreState = StackStoreData & StackStoreActions;
 export type { LiveDecl, LiveDeclarations, SelectionDecl, SelectionDeclarations, ViewStateDecl, ViewStateDeclarations, } from '@peripheries/runtime';
-/** Spread onto a cell's `selections` / `viewState` / `live` props. */
 export type ProjectedBundle = Record<string, unknown>;

package/dist/types/core/structure.d.ts

@@ -5,28 +5,17 @@ export type { LayoutNode, SectionKind, SectionReference };
 export type ResolvedLayoutNode = Omit<LayoutNode, 'children'> & {
     children?: ResolvedLayoutNode[];
 };
-/** The page's own document, which almost every page is. */
 export declare const PAGE_DOCUMENT = "__page__";
-/** A string child is sugar for `{ cellId }`. */
 export declare function normalizeStructure(nodes: ReadonlyArray<LayoutNode | string> | null | undefined): ResolvedLayoutNode[];
-/** Siblings by `order` (default 0), stable. */
 export declare const sortByOrder: <T extends {
     order?: number;
 }>(nodes: readonly T[]) => T[];
 export declare const isSectionNode: (n: ResolvedLayoutNode) => boolean;
 export declare const isSectionKind: (v: unknown) => v is SectionKind;
-/** A section's anchor: its cell, else its section id (the same value `DocumentSection` and the contents use). */
 export declare const sectionAnchor: (n: Pick<ResolvedLayoutNode, "cellId" | "sectionId">) => string;
-/**
- * Hierarchical rendering when the structure wants it: `type: 'document'`, or
- * any top-level node naming a section or carrying children. A flat list of
- * `{ cellId }` is only an ordering hint for print, and renders flat.
- */
 export declare function usesStructureLayout(layout: Record<string, unknown> | null | undefined): boolean;
 export type DocumentNumbering = {
-    /** Only `kind: 'article'` sections are numbered, per document, prefixed by the parent trail. */
     numbers: Record<string, number[]>;
-    /** Structural depth of each section. */
     levels: Record<string, number>;
     authoredLevels: Record<string, number>;
     titles: Record<string, string>;
@@ -42,35 +31,19 @@ export type SectionNumbering = {
 };
 export declare const numberingFor: (numbering: SectionNumbering | undefined, documentId: string | undefined) => DocumentNumbering;
 export declare function deriveSectionNumbering(structure: ReadonlyArray<LayoutNode | string> | null | undefined): SectionNumbering;
-/** Per document: every target a cell in it may cite, by role (`residue`), `label:role`, or `role#clause`. */
 export type SectionReferences = Record<string, Record<string, SectionReference>>;
 type Documents = Record<string, {
     label?: unknown;
 }> | null | undefined;
-/** Same-page section references: a document's own roles, plus `label:role` for every uniquely labelled document. */
 export declare function deriveSectionReferences(numbering: SectionNumbering, documents: Documents): SectionReferences;
-/**
- * Clause citations (`role#clauseId`): each section's cells' resolved
- * `props.blocks`, where a `clause` block's items carry ids. The item's index
- * and the clause shape let a Reference render the clause's number.
- */
 export declare function deriveElementReferences(structure: ReadonlyArray<LayoutNode | string> | null | undefined, blocksByCellId: Readonly<Record<string, unknown>>, documents: Documents): SectionReferences;
-/** Same-page references win over data-derived ones (clauses; cross-page arrive in R5). */
 export declare function mergeSectionReferences(samePage: SectionReferences, other: SectionReferences | undefined): SectionReferences;
 export declare const referencesFor: (refs: SectionReferences | undefined, documentId: string | undefined) => Record<string, SectionReference>;
-/** What stops a structure rendering: a node naming a missing cell, or an unknown section kind (a refusal, by design). */
 export declare function structureIssues(structure: ReadonlyArray<LayoutNode | string> | null | undefined, cells: PageCell[]): string[];
-/**
- * A node's extrinsic pagination: a page break before, keep-with-previous
- * (break-before: avoid), or avoid breaking inside. `breakInside: 'auto'` is
- * dropped, so a node can't relax what a component declares; a break before
- * wins over keep-with-previous. The component's own @printPolicy joins in R5.
- */
 export declare function nodePrintStyle(node: Pick<LayoutNode, 'print'>): {
     breakBefore?: 'page' | 'avoid';
     breakInside?: 'avoid';
 } | undefined;
-/** One entry in a document's table of contents. */
 export type ContentsEntry = {
     sectionId: string;
     anchor: string;
@@ -79,10 +52,4 @@ export type ContentsEntry = {
     level: number;
     children: ContentsEntry[];
 };
-/**
- * A document's table of contents (INV-DOC-1): its sections in order, nested, with the numbers
- * articles get and the anchors the page renders (`sectionAnchor`). A section's title is its
- * structure node's, else its cell's `title` prop, else its id. `tocHidden` sections are left out,
- * their children kept in their place. Only the page's own document.
- */
 export declare function tableOfContents(structure: ReadonlyArray<LayoutNode | string> | null | undefined, cells?: ReadonlyArray<PageCell>): ContentsEntry[];

package/dist/types/core/types.d.ts

@@ -1,16 +1,10 @@
 import type { DeclaredBinding, PageCell, QueryDescriptor } from '@peripheries/runtime';
-/** One source in a DataContext: the value and its state. */
-/** A paged label's position (QueryDescriptor.paging): what loading its next page needs. */
 export type DataPage = {
     hasMore: boolean;
     endCursor: string | null;
     descriptor: QueryDescriptor;
     variables: Record<string, unknown>;
 };
-/**
- * A label's read. `unresolved` names the references that resolved to nothing, so the query never
- * ran (QUERY_UNRESOLVED): there is nothing to show yet, which is not a failed read.
- */
 export type DataEntry = {
     data: unknown;
     isLoading: boolean;
@@ -19,7 +13,6 @@ export type DataEntry = {
     unresolved?: string[];
     origin?: DataOrigin;
 };
-/** A system a label's value was read from, and the newest state seen there (null: none, or the source doesn't say). */
 export type StateOrigin = {
     systemId: string;
     name?: string;
@@ -27,12 +20,6 @@ export type StateOrigin = {
     versionId?: string | null;
     outOfScope?: boolean;
 };
-/**
- * Where a label's value came from (INV-DOC-6), so an edit can go back to it (design/data.md §9.5).
- * `at` is the path inside the source to the label's value: inside the state's data (a binding's
- * `field`, an `@each` element's index), or the label and its path in the page's or cell's static data.
- * A label without an origin was read some other way (a query): it isn't editable.
- */
 export type DataOrigin = {
     kind: 'state';
     graphNodeId: string;

package/dist/types/core/validate.d.ts

@@ -1,7 +1,6 @@
 import { type Diagnostic } from './graph.js';
 import { type Each } from './references.js';
 import type { PageCell, ProjectPage } from './types.js';
-/** What validation knows about the components in scope. Stream 3 fills it from the catalog. */
 export type Catalog = {
     components: Record<string, {
         props_schema?: {
@@ -11,34 +10,23 @@ export type Catalog = {
         } | null;
     } | undefined>;
 };
-/**
- * The names nearest a name that isn't in scope, nearest first: a near spelling
- * (`Prse`), or each of its words starting a word of the name (`DocSection` →
- * `DocumentSection`). Full-text search can't find either.
- */
 export declare function nearestNames(name: string, names: Iterable<string>, limit?: number): string[];
 export declare const RESPONSIVE_BUCKETS: readonly ["narrow", "compact", "wide"];
 export declare const STORE_SCOPES: readonly ["page", "project"];
 export declare const WALK_DIRECTIONS: readonly ["incoming", "outgoing", "both"];
-/** Options: `template` for a page template, whose node bindings are filled when it is instantiated. */
 export type ValidateOptions = {
     template?: boolean;
 };
-/** What is wrong with a projection's form, if anything: the one judgement EACH_INVALID and validatePageProps share. */
 export declare function eachFormProblems(value: Each): string[];
-/** One cell's configuration. `ids` are the page's cell ids, for `children`. */
 export declare function validateCell(cell: PageCell, catalog?: Catalog, path?: string, ids?: ReadonlySet<string>, options?: ValidateOptions): Diagnostic[];
-/** A whole page: every cell, the page's own declarations, unique cell ids, and its document structure. */
 export declare function validatePage(page: Pick<ProjectPage, 'content' | 'layout'> & {
     is_template?: boolean | null;
 }, catalog?: Catalog): Diagnostic[];
-/** A slot a component declares in its props schema: `properties.<name>["x-slot"]` (ui-consistency.md §2.8). */
 export type SlotDeclaration = {
     name: string;
     accepts?: readonly string[];
     max?: number;
 };
-/** The slots a catalog entry declares, by name. */
 export declare function declaredSlots(schema: {
     properties?: Record<string, unknown>;
 } | null | undefined): Map<string, SlotDeclaration>;

package/dist/types/core/values.d.ts

@@ -1,12 +1,6 @@
 import type { Traversal } from '@peripheries/runtime';
 import type { PageRuntime } from './load-page.js';
 import type { ProjectPage } from './types.js';
-/**
- * `values` are labels and their resolved values, on top of the page's static
- * data. `traversal` is `@_traversal` for every walking cell: one subgraph for
- * all of them, or one per cell id; a walking cell it doesn't cover gets an
- * empty one, as the host gives a walk that found nothing.
- */
 export declare function pageRuntimeFromValues(page: ProjectPage, { values, traversal }?: {
     values?: Record<string, unknown>;
     traversal?: Traversal | Record<string, Traversal>;

package/dist/types/forms/conditions.d.ts

@@ -1,26 +1,7 @@
-/**
- * Conditions on pages, sections, questions and content blocks (design/forms.md §3.1).
- *
- * One shape: `{ all: [{ q: '<question key>', op, value }], not?: boolean }`, operators
- * in lower case only. Ported from the PWA's `lib/forms/evaluate-conditional.ts` and
- * `lib/forms/normalize-conditional-logic.ts`; the semantics are theirs:
- *
- * - every clause must hold (AND); `not: true` negates the result;
- * - absent or empty conditions show the target;
- * - an unknown operator, or an error while evaluating, SHOWS the target. Hiding would
- *   silently remove a question from a workbook; an extra one is visible and correctable.
- *
- * The PWA had two stored shapes and mixed operator casing (`equals`, `not_equals`,
- * `notEquals`, `is_not_empty`, `greaterThan` …). `normalizeCondition` maps all of them
- * to this shape once, at migration and validation time, so the evaluator reads only
- * the canonical operators.
- */
 export declare const CONDITION_OPS: readonly ["eq", "ne", "in", "not_in", "gt", "lt", "gte", "lte", "contains", "not_contains", "empty", "not_empty"];
 export type ConditionOp = (typeof CONDITION_OPS)[number];
 export interface ConditionClause {
-    /** The question key the clause reads from the answers. */
     q: string;
-    /** A `ConditionOp`; anything else shows the target and is reported. */
     op: ConditionOp | (string & {});
     value?: unknown;
 }
@@ -29,26 +10,8 @@ export interface Condition {
     not?: boolean;
 }
 export declare function isConditionOp(op: unknown): op is ConditionOp;
-/**
- * True when the condition passes and the target should render.
- *
- * @param answers Answers keyed by question key, unwrapped (`unwrapAnswerValue`).
- * @param onProblem Called for an unknown operator or an evaluation error; the target
- *   is shown in both cases.
- */
 export declare function evaluateCondition(condition: Condition | null | undefined, answers: Record<string, unknown>, onProblem?: (problem: string) => void): boolean;
-/** The canonical operator for a legacy spelling, or null when it is not one we know. */
 export declare function normalizeOperator(op: unknown): ConditionOp | null;
-/**
- * Map a stored condition to the one shape.
- *
- * Accepts the new shape, the PWA's current `{ conditions: [{ questionId, operator, value }],
- * not? }`, its legacy `[{ when, operator, is }]`, and any of them as a JSON string (the
- * column is jsonb and some seeding wrote it stringified).
- *
- * `condition: null` means UNGATED, i.e. the target shows: the safe direction for input
- * that is absent or unusable. Unusable input and dropped clauses are listed in `problems`.
- */
 export declare function normalizeCondition(legacy: unknown): {
     condition: Condition | null;
     problems: string[];

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

@@ -1,3 +1,4 @@
 export { CONDITION_OPS, evaluateCondition, isConditionOp, normalizeCondition, normalizeOperator, type Condition, type ConditionClause, type ConditionOp } from './conditions.js';
 export { defaultMode, enterAdvances, fromPageSteps, goTo, goToQuestion, isReadOnlyStatus, linkTo, missing, move, positionFromLink, positionsOf, progress, questionsOf, settle, stepKind, visibleSteps, type DisplayMode, type FormChapter, type FormItem, type FormItemKind, type FormLink, type FormModel, type FormQuestion, type FormQuestionDefinition, type FormStep, type Position, type StepKind, type StepProgress, type SubmissionStatus, } from './model.js';
 export type { AnswerToSave, FileToUpload, FormsPort, FormsRefusal, FormsResult } from './port.js';
+export type { FormContentBlock, FormSection } from './section.js';