@peripheries/renderer 0.23.0 → 0.23.1

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/model.d.ts

@@ -1,27 +1,13 @@
 import { type Condition } from './conditions.js';
-/**
- * A form as the forms runtime reads it (forms-as-pages.md §4.2–§4.3): steps, an overlay on the
- * page's flat cells, each holding items (cells) and the questions they ask. Where it comes from
- * is an adapter's business: a page's `layout.steps` (`fromPageSteps`) or, until forms are pages
- * (SCH M3b), the legacy definition (the host's adapter). Pure: no React, no network.
- */
 export type FormQuestion = {
-    /** The answer's key: what conditions, progress and the port name. */
     key: string;
     label: string;
     required: boolean;
-    /** Enter may move on from it (forms-as-pages.md §4.3): a one-line question. */
     singleLine: boolean;
     when?: Condition | null;
-    /** The question node an answer is saved against (answer_save's p_question_node), when the form is a page. */
     node?: string;
-    /** How to ask it, from the question node's state: what a cell renders its control from. */
     definition?: FormQuestionDefinition;
 };
-/**
- * A question's definition as its node's state holds it (forms-as-pages.md §4.2): the control's
- * type, its options, validation and help. The runtime passes it through to the cell untouched.
- */
 export type FormQuestionDefinition = {
     type: string;
     options?: unknown[];
@@ -30,14 +16,12 @@ export type FormQuestionDefinition = {
     helpText?: string;
 };
 export type FormItemKind = 'question' | 'content' | 'document' | 'review' | 'upload' | 'other';
-/** One cell of a step: its questions, if any. */
 export type FormItem = {
     id: string;
     kind: FormItemKind;
     questions: FormQuestion[];
     when?: Condition | null;
 };
-/** `label`: an authored word for the step shown in place of its derived kind's (advisor review, status); the kind stays derived. */
 export type FormStep = {
     id: string;
     title: string;
@@ -54,50 +38,32 @@ export type FormModel = {
     title: string;
     chapters: FormChapter[];
     steps: FormStep[];
-    /** On submit: `warn` lists what's missing and submits; `block` refuses until it's answered (owner, Q-F7; default warn). */
     submitRequired: 'warn' | 'block';
-    /** Back is offered (the template's `allow_back`, default true). */
     allowBack: boolean;
-    /** The form takes a submission (false for a legacy form, which has none); default true. */
     submittable?: boolean;
 };
-/** A step's kind, derived from its cells (§4.2): for labels and progress. */
 export type StepKind = 'answer' | 'read' | 'review' | 'upload' | 'submit';
-/** Where a submission stands (the `submission` layer's status, schema-g2.md §2.7). */
 export type SubmissionStatus = 'in_progress' | 'submitted' | 'changes_requested' | 'completed';
 export type DisplayMode = 'step' | 'question';
-/** Steps, cells and questions whose conditions hold for these answers; a step left with nothing visible is skipped. */
 export declare function visibleSteps(model: FormModel, values: Record<string, unknown>): FormStep[];
 export declare const questionsOf: (step: FormStep) => FormQuestion[];
 export declare function stepKind(step: FormStep, isLast: boolean): StepKind;
-/** Where a person is: a step, and in question mode one of its questions. */
 export type Position = {
     step: string;
     question?: string;
 };
-/** The places Next and Back move through: a step each, or in question mode each question (a step with none counts once). */
 export declare function positionsOf(steps: FormStep[], mode: DisplayMode): Position[];
-/** A position in these steps: the same, else its step's first, else the first. */
 export declare function settle(steps: FormStep[], mode: DisplayMode, at: Position | null): Position | null;
-/** One move on, or back; null at either end. A move across a step boundary is a step change (it pushes history). */
 export declare function move(steps: FormStep[], mode: DisplayMode, at: Position, by: 1 | -1): Position | null;
-/** The contents click (§4.3): that step, in question mode at its first unanswered question, else its first. */
 export declare function goTo(steps: FormStep[], mode: DisplayMode, stepId: string, values: Record<string, unknown>): Position | null;
-/** A question's place (§4.3 question mode, `?question=`): its step, settled for the mode. Null when no visible step has it. */
 export declare function goToQuestion(steps: FormStep[], mode: DisplayMode, key: string): Position | null;
-/** Enter moves on (§4.3): a step with exactly one visible one-line question, or a one-line question in question mode. */
 export declare function enterAdvances(step: FormStep, mode: DisplayMode, question?: string): boolean;
-/** Required questions not yet answered, in order: in one step, or (no step) in the whole form. */
 export declare function missing(steps: FormStep[], values: Record<string, unknown>, stepId?: string): FormQuestion[];
 export type StepProgress = {
     answered: number;
     total: number;
     complete: boolean;
 };
-/**
- * Progress (§4.3): overall, required answered of required visible; per step, answered of visible
- * questions, complete when all its required ones are answered. A read step counts once visited.
- */
 export declare function progress(steps: FormStep[], values: Record<string, unknown>, visited: ReadonlySet<string>): {
     answered: number;
     required: number;
@@ -108,27 +74,17 @@ export declare function progress(steps: FormStep[], values: Record<string, unkno
     };
     perStep: Record<string, StepProgress>;
 };
-/** Answers can't change: submitted or completed (Edit answers reopens a submitted form). */
 export declare const isReadOnlyStatus: (status: SubmissionStatus | null | undefined) => status is "submitted" | "completed";
-/** Step mode on desktop, one question at a time on a phone (§4.3). */
 export declare const defaultMode: (phone: boolean) => DisplayMode;
-/**
- * Steps from a page's overlay (§4.2): `layout.steps: [{ id, title, chapter?, cell_ids, when? }]`
- * and `layout.chapters`, each cell's questions from `questionsOfCell` (the page knows its
- * question cells' bindings). Cells the overlay doesn't name aren't in the form.
- */
 export declare function fromPageSteps(page: {
     name?: string | null;
     layout?: Record<string, unknown> | null;
 }, itemOf: (cellId: string) => FormItem | null): FormModel;
-/** A deep link (§4.3, the URL contract `?mode=&page=&section=&question=`): `section` a step id, `page` a chapter id, `question` a question key. */
 export type FormLink = {
     mode?: 'question';
     page?: string;
     section?: string;
     question?: string;
 };
-/** Where a link lands: the step it names (and question), else its chapter's first step, else the first. */
 export declare function positionFromLink(steps: FormStep[], mode: DisplayMode, link: FormLink): Position | null;
-/** The link to a position, as an assistant reply carries it. */
 export declare function linkTo(steps: FormStep[], mode: DisplayMode, at: Position): FormLink;

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

@@ -1,11 +1,4 @@
-/**
- * How the forms runtime saves (joint-releases.md §2.4): an injected port, so the runtime never
- * names a table or a function. The legacy adapter (the host's, over form_answer_save) implements
- * it in G2; answer_save, form_submit, form_visit and form_reopen (SCH M3b; schema-g2.md §2.7) in
- * G3, with no renderer release. A refusal is a code, never a throw, so it's said in words like an edit's.
- */
 import type { FileAnswer } from '@peripheries/runtime';
-/** The codes a port answers with (schema-g2.md §2.7), and NETWORK when the call didn't arrive. */
 export type FormsRefusal = 'CONFLICT' | 'ANSWER_TYPE' | 'ANSWER_OPTION' | 'ANSWER_REQUIRED' | 'ANSWER_FILE_PATH' | 'ANSWER_VALIDATION' | 'FORM_INCOMPLETE' | 'FORM_NOT_OPEN' | 'FORM_COMPLETED' | 'FORM_STEP_UNKNOWN' | 'NO_CAPABILITY' | 'NETWORK' | (string & {});
 export type FormsResult<T extends object = object> = ({
     ok: true;
@@ -15,11 +8,9 @@ export type FormsResult<T extends object = object> = ({
     message?: string;
     detail?: unknown;
 };
-/** A file to upload for an answer: any Blob with a name (a File in the browser). */
 export type FileToUpload = Blob & {
     readonly name: string;
 };
-/** One answer to save: its key, the question node when the form is a page, and the state it replaces. */
 export type AnswerToSave = {
     key: string;
     node?: string;
@@ -27,31 +18,19 @@ export type AnswerToSave = {
     expectedStateId?: string | null;
 };
 export interface FormsPort {
-    /** Save one answer; the state it wrote is what the next save of that key expects (CONFLICT otherwise). */
     save(answer: AnswerToSave): Promise<FormsResult<{
         stateId?: string | null;
     }>>;
-    /** Submit: `missing` is what the runtime found unanswered (recorded under `warn`; `block` refuses FORM_INCOMPLETE). */
     submit(input: {
         missing: string[];
     }): Promise<FormsResult<{
         status: 'submitted';
         missing: string[];
     }>>;
-    /**
-     * Edit answers (forms-as-pages.md §4.3): a submitted form back to `in_progress`, recorded in the
-     * submission. Refused once staff have completed it (FORM_COMPLETED).
-     */
     reopen(): Promise<FormsResult<{
         status: 'in_progress';
     }>>;
-    /** A step was seen (`submission.visited_steps`): read steps count once visited. A repeat is a no-op. */
     visit(stepId: string): Promise<FormsResult>;
-    /**
-     * Upload a file for a file question, as the viewer: the adapter stores it where answer_save
-     * accepts it and returns the answer to save (`{ v: 1, file }`); saving it is `save`'s. Absent
-     * where the host takes no files.
-     */
     upload?(input: {
         key: string;
         node?: string;
@@ -62,7 +41,6 @@ export interface FormsPort {
             file: FileAnswer;
         };
     }>>;
-    /** A short-lived URL to open a saved file answer, as the viewer (storage decides who may). */
     openFile?(file: FileAnswer): Promise<FormsResult<{
         url: string;
     }>>;