@magicvr/schema-ui-shell 0.1.0

package/renderer/render.d.ts

@@ -0,0 +1,194 @@
+import { type ComponentType, type ReactNode } from "react";
+import { type UploadableFile } from "@/protocol/conformance/upload-orchestration";
+import { type FormControlField } from "@/renderer/form-controls.types";
+import { type ResourceList, type ResourceQuery } from "@/renderer/resource";
+import { type RenderActionButtonNode, type RenderChartNode, type RenderFormNode, type RenderPageDocument, type RenderStatCardNode, type RenderTableNode } from "@/renderer/render.types";
+/**
+ * R5 D-COMP minimal Renderer (resolve R4 F-002) + S4 Schema CRUD (GOAL-007).
+ *
+ * Dispatch layer: parses a page document, applies the frozen $context
+ * reaction engine to form field state, and renders whitelisted node types
+ * through the components in this directory. Unknown node types fail closed.
+ *
+ * S4 one-time completion (I-007-003 v0.2.2 §9): a SchemaCrudProvider owns the
+ * cross-node state a Schema-driven CRUD page needs — selected row (feeds
+ * recordView + edit-form prefill), per-table query (search form-to-query
+ * binding), a reload token, the active modal, the pending delete confirm, and
+ * a generic action executor that gates through the frozen `executeAction`
+ * engine and constructs requests with the pinned conformance constructor
+ * (`request-construction.ts`). Every page-level behaviour stays fixture-driven;
+ * after this completion page behavior remains schema-owned; core fixtures and
+ * module-owned schema packages can add pages without Renderer changes.
+ *
+ * Scope: the frozen §5 node whitelist — layout (grid/section/tabs),
+ * data/action (text/table/recordView/actionButton) and form. The form control
+ * whitelist itself is enforced by D-FORM (isWhitelistedFormControl /
+ * checkFormCapabilities) via gateRenderFormFields. The default app path wires
+ * a schema-driven table surface (SchemaTable, GOAL-004) as `tableRenderer`;
+ * a table node dispatched without one fails closed with an observable note.
+ *
+ * A-002 F-002-002 (GOAL-009 S1): form submission is blocked while any
+ * gate/reaction error is present — the submit button is disabled and
+ * handleSubmit re-rejects before any request can be constructed.
+ */
+export interface RendererComponentProps {
+    document: RenderPageDocument;
+    context: Record<string, unknown>;
+    /** Renders a table node; provided by the example page that owns data. */
+    tableRenderer?: (node: RenderTableNode) => ReactNode;
+    /** Renders statCard/chart nodes (supportsData display, registry); defaults to built-ins. */
+    dataRenderer?: (node: RenderStatCardNode | RenderChartNode) => ReactNode;
+    /** Invoked when an actionButton node is activated. */
+    onAction?: (node: RenderActionButtonNode) => void;
+    /**
+     * Session-internal navigation hook (ADR-0021 navigate actions; GOAL-015
+     * F-001): the host pushes the target onto its own history/visit stack so
+     * breadcrumbs survive. Falls back to window.location.assign when absent.
+     */
+    onNavigate?: (url: string) => void;
+    /** Overrides the default FormControls component (keeps field wiring local). */
+    formComponent?: ComponentType<{
+        fields: FormControlField[];
+        values: Record<string, unknown>;
+        onChange: (id: string, value: unknown) => void;
+        fieldDisabled?: (id: string) => boolean;
+        onUpload?: (field: FormControlField, files: UploadableFile[]) => Promise<unknown>;
+        /** W11 · U-01/U-02: auth-aware transport for dynamic option sources. */
+        fetcher?: typeof fetch;
+    }>;
+}
+export interface SchemaCrudFeedback {
+    kind: "success" | "error";
+    message: string;
+    code?: string;
+    /** VP-007 S4: catalog key for the frontend localization floor. */
+    messageKey?: string;
+    /** VP-007 S4: interpolation params for messageKey. */
+    params?: Record<string, unknown>;
+}
+export interface SchemaCrudConfirm {
+    actionRef: string;
+    actionKey: string;
+    row: Record<string, unknown>;
+    requestMapping?: Record<string, unknown>;
+    message: string;
+    /** Batch trigger confirm (ADR-0022 D4/D5): carries the selection snapshot. */
+    batch?: {
+        tableId: string;
+        selection: TableSelection;
+    };
+    /** Toolbar item batchMapping carried through confirm. */
+    batchMapping?: Record<string, unknown>;
+}
+/** Selection snapshot (ADR-0022 D3): ordered keys + count. */
+export interface TableSelection {
+    keys: unknown[];
+    count: number;
+}
+export type ActionResult = {
+    ok: true;
+    fieldErrors?: Array<{
+        field: string;
+        reason: string;
+        rowNumber?: number;
+    }>;
+    message?: string;
+    messageKey?: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    messageKey?: string;
+    params?: Record<string, unknown>;
+    /** GOAL-014 D-002 §2: server field-level validation failures. */
+    fieldErrors?: Array<{
+        field: string;
+        reason: string;
+        rowNumber?: number;
+    }>;
+};
+export interface SchemaCrudValue {
+    selectedRow: Record<string, unknown> | null;
+    selectRow: (row: Record<string, unknown> | null) => void;
+    tableQuery: (id: string) => ResourceQuery | undefined;
+    setTableQuery: (id: string, query: ResourceQuery) => void;
+    reloadToken: number;
+    reloadList: () => void;
+    /**
+     * Fetches a resource list through the page-level in-flight coalescer:
+     * simultaneous consumers of the same URL share ONE network request (three
+     * statCards + the wallet-ensure probe on one "我的钱包" visit merge into a
+     * single GET /me). Requests are otherwise never memoized — every query,
+     * reset or reload refetches — and reloadList drops the in-flight map so a
+     * reload issued during a slow fetch starts its own fresh request.
+     * `transport` is the caller's own transport (a directly injected fixture or
+     * the auth fetcher); defaults to the provider's registered fetcher.
+     */
+    fetchList: (dataSource: string, query: ResourceQuery, extraQuery?: string, transport?: typeof fetch) => Promise<ResourceList>;
+    /**
+     * Targeted display-data refresh (W25): bumps the per-URL refresh token for
+     * the standard display query of `dataSource` (statCard/chart consume it),
+     * so a consumer can refetch ONE surface without a full-page reload wave.
+     * Only applies to display nodes without route-param bindings (the standard
+     * DISPLAY_LIST_QUERY shape); tables/misc surfaces keep their data until a
+     * manual reload.
+     */
+    refreshList: (dataSource: string) => void;
+    /** Current refresh token for a display dataSource (0 when untouched). */
+    listRefreshToken: (dataSource: string) => number;
+    activeModal: {
+        actionRef: string;
+        row: Record<string, unknown> | null;
+        title: string;
+    } | null;
+    modalRow: Record<string, unknown> | null;
+    openModal: (actionRef: string, row: Record<string, unknown> | null, title: string) => void;
+    closeModal: () => void;
+    pendingConfirm: SchemaCrudConfirm | null;
+    requestConfirm: (confirm: SchemaCrudConfirm) => void;
+    resolveConfirm: (confirmed: boolean) => Promise<void>;
+    feedback: SchemaCrudFeedback | null;
+    registerFetcher: (fetcher: typeof fetch) => void;
+    /** The currently registered transport (globalThis.fetch until injected). */
+    fetcher: typeof fetch;
+    /** Runs a request action end-to-end (gate → construct → fetch → feedback/reload). */
+    runRowAction: (actionRef: string, opts: RunRequestOptions) => Promise<ActionResult>;
+    /** Dispatches a toolbar/row action entry: modal open, confirm, or request. */
+    invokeAction: (item: Record<string, unknown>, row: Record<string, unknown> | null) => void;
+    /** Dispatches a batch toolbar trigger (ADR-0022): gate → confirm → request. */
+    invokeBatchAction: (item: Record<string, unknown>, tableId: string) => void;
+    /** Upload control transport (ADR-0012): resolves action/actionRef → validates → uploads. */
+    uploadFiles: (field: FormControlField, files: UploadableFile[]) => Promise<unknown>;
+    /** Per-table selection state (keys + count; normalized by the table). */
+    selection: (tableId: string) => TableSelection | undefined;
+    setSelection: (tableId: string, keys: unknown[]) => void;
+    clearSelection: (tableId: string) => void;
+    /** Submits a default-mode form against its `submitAction`. */
+    submitForm: (form: RenderFormNode, values: Record<string, unknown>) => Promise<ActionResult>;
+    /** Binds a search-mode form's fields to its target table query. */
+    searchFormSubmit: (form: RenderFormNode, values: Record<string, unknown>) => void;
+    effectivePermission: (targetId: string) => boolean;
+    /**
+     * Current route snapshot (from the render context; App injects
+     * route: {params, query}). Used for ADR-0039 dataSource bindings and
+     * create-modal readOnly seeding instead of reading window.location.
+     */
+    route: {
+        query: Record<string, string>;
+        params: Record<string, string>;
+    };
+}
+export interface RunRequestOptions {
+    row?: Record<string, unknown> | null;
+    formValues?: Record<string, unknown>;
+    requestMapping?: Record<string, unknown>;
+    gateTargetId?: string;
+    confirmed?: boolean;
+}
+/** Page CRUD context consumed by custom components (rendered nodes). */
+export declare const SchemaCrudContext: import("react").Context<SchemaCrudValue | null>;
+/** Reads the page-level Schema CRUD provider (null when rendered bare). */
+export declare function useSchemaCrud(): SchemaCrudValue | null;
+export declare function RenderPage({ document, context, tableRenderer, dataFetcher, onAction, onNavigate, formComponent, }: RendererComponentProps & {
+    dataFetcher?: typeof fetch;
+}): import("react").JSX.Element;

package/renderer/render.types.d.ts

@@ -0,0 +1,289 @@
+import { type FormControlField, type FormControlGateError } from "@/renderer/form-controls.types";
+import { type FormControlStateMap, type ReactionError } from "@/renderer/reactions";
+/**
+ * D-COMP page renderer (frozen §5 whitelist + I-PROTO-FULL-001 full registry
+ * surface; resolve R4 F-002).
+ *
+ * The renderer walks a page document's node tree and dispatches whitelisted
+ * node types to the components in this directory. It is deliberately minimal:
+ * only the node types surfaced by the example pages are handled, and any
+ * other type fails closed instead of rendering a silent fallback.
+ *
+ * A page document looks like the example pages' `PAGE_DOCUMENT`:
+ *   { meta: { protocolVersion, requiredCapabilities }, body: Node }
+ *
+ * Node types supported (registry surface):
+ *   - layout:  grid / section / tabs
+ *   - data/action: text / table / recordView / actionButton / statCard / chart
+ *   - form:    form → FormControls (with reactions applied to field state)
+ * The form control whitelist itself is enforced by D-FORM
+ * (isWhitelistedFormControl / checkFormCapabilities).
+ */
+export type RenderNodeType = "form" | "section" | "table" | "grid" | "tabs" | "text" | "recordView" | "actionButton" | "statCard" | "chart" | "custom";
+export interface RenderMeta {
+    protocolVersion: string;
+    requiredCapabilities: string[];
+}
+export interface ReactionState {
+    /** fieldId → control state after reactions. */
+    state: FormControlStateMap;
+    errors: ReactionError[];
+}
+export interface RenderFormNode {
+    type: "form";
+    id?: string;
+    props: {
+        fields: Array<Record<string, unknown>>;
+        reactions?: unknown;
+        submitLabel?: string;
+        /** S2 (VP-007): i18n key resolved before `submitLabel` (local doc convention). */
+        submitLabelKey?: string;
+        /** Default-mode submit: the top-level action id to run on submit (S4). */
+        submitAction?: string;
+        /** Search-mode form: binds its fields to the target table's query (S4). */
+        mode?: "default" | "search";
+        targetTable?: string;
+        /** Section heading rendered above the fields (registry form `title`/`titleKey`). */
+        title?: string;
+        /** i18n key resolved before `title`. */
+        titleKey?: string;
+        /**
+         * ADR-0021 edit-form record GET prefill (registry since 2.1): loads current
+         * values from a detail GET and initializes the fields via `responseMapping`
+         * (field id → dot-path in the response). Requires capability
+         * `form.record.load`; search-mode forms forbid it.
+         */
+        recordSource?: Record<string, unknown>;
+        /** GOAL-014 D-002 §4: responsive form column count (>1 enables the grid). */
+        columns?: number;
+    };
+    children?: RenderNode[];
+}
+export interface RenderSectionNode {
+    type: "section";
+    id?: string;
+    props?: Record<string, unknown>;
+    children: RenderNode[];
+}
+export interface RenderGridNode {
+    type: "grid";
+    id?: string;
+    props?: Record<string, unknown>;
+    children?: RenderNode[];
+}
+export interface RenderTabsNode {
+    type: "tabs";
+    id?: string;
+    props?: Record<string, unknown>;
+    children?: RenderNode[];
+}
+export interface RenderTextNode {
+    type: "text";
+    id?: string;
+    props?: {
+        text?: string;
+        /** i18n key resolved before `text` (F-01 · GOAL-003 A-003 F-001). */
+        textKey?: string;
+    };
+    children?: RenderNode[];
+}
+/**
+ * v2.9 DataRef subset consumed by data nodes (ADR-0039): source:api url +
+ * params (literal scalars or whole $context.route.query.* / params.* bindings).
+ */
+export interface RenderDataRef {
+    url: string;
+    params?: Record<string, unknown>;
+}
+export interface RenderTableNode {
+    type: "table";
+    id?: string;
+    /** v2.9 node-level DataRef (source:api). Preferred over props.dataSource. */
+    data?: RenderDataRef;
+    props: {
+        columns?: Array<Record<string, unknown>>;
+        actions?: Array<Record<string, unknown>>;
+        toolbar?: Array<Record<string, unknown>>;
+        dataSource?: string;
+        /** Table heading (literal fallback for titleKey). */
+        title?: string;
+        /** i18n key resolved before title. */
+        titleKey?: string;
+        /** Direct field name of each row's unique key (F-002 · I-010-001 v0.2.0 §3; default "id"). */
+        rowKey?: string;
+        /** ADR-0022 multi-select model (registry; mode: multiple only). */
+        selection?: {
+            mode?: string;
+        };
+        /** Schema-driven filters (select-only; see schemaTableFilters). */
+        filters?: Array<Record<string, unknown>>;
+    };
+    children?: RenderNode[];
+}
+/** Read-only field row on a recordView (registry `fields[]` since 2.4). */
+export interface RenderRecordViewField {
+    key: string;
+    label?: string;
+    labelKey?: string;
+}
+export interface RenderRecordViewNode {
+    type: "recordView";
+    id?: string;
+    props?: {
+        record?: Record<string, unknown>;
+        /** Detail panel heading (registry `title` since 2.4). */
+        title?: string;
+        /** i18n key resolved before `title`. */
+        titleKey?: string;
+        /** Declared display fields; when set, only these rows render. */
+        fields?: RenderRecordViewField[];
+    };
+    children?: RenderNode[];
+}
+export interface RenderActionButtonNode {
+    type: "actionButton";
+    id?: string;
+    props?: {
+        label?: string;
+        /** i18n key resolved before `label` (S3). */
+        labelKey?: string;
+        actionId?: string;
+        visibleWhen?: unknown;
+        disabledWhen?: unknown;
+        /** Permission-intent key (ADR-0023 D4b mount); gates the button target. */
+        permissionIntent?: string;
+        /** Target id for the permission target / action gate (falls back to node id). */
+        key?: string;
+        /** Confirm message (shown before executing the referenced action). */
+        confirm?: string;
+        /** i18n key resolved before `confirm`. */
+        confirmKey?: string;
+    };
+    children?: RenderNode[];
+}
+export interface RenderStatCardNode {
+    type: "statCard";
+    id?: string;
+    /** v2.9 node-level DataRef (source:api). Preferred over props.dataSource. */
+    data?: RenderDataRef;
+    props?: {
+        label?: string;
+        /** i18n key resolved before `label` (F-01 · GOAL-003 A-003 F-001). */
+        labelKey?: string;
+        unit?: string;
+        /** plain | currency | percent (registry enum). */
+        format?: string;
+        /** Field of the dataSource rows to display (registry, required since 0.2). */
+        valueField?: string;
+        /** Single-slash same-origin data path (same invariant as table.dataSource). */
+        dataSource?: string;
+    };
+    children?: RenderNode[];
+}
+export interface RenderChartNode {
+    type: "chart";
+    id?: string;
+    /** v2.9 node-level DataRef (source:api). Preferred over props.dataSource. */
+    data?: RenderDataRef;
+    props?: {
+        /** line | bar | pie (registry enum, required). */
+        chartType?: string;
+        xField?: string;
+        yField?: string;
+        /** Single-slash same-origin data path (same invariant as table.dataSource). */
+        dataSource?: string;
+    };
+    children?: RenderNode[];
+}
+export interface RenderCustomNode {
+    type: "custom";
+    id?: string;
+    /** Registered component key (GOAL-018: renderer custom-component registry). */
+    component: string;
+    props?: Record<string, unknown>;
+    children?: RenderNode[];
+}
+export type RenderNode = RenderFormNode | RenderSectionNode | RenderGridNode | RenderTabsNode | RenderTextNode | RenderTableNode | RenderRecordViewNode | RenderActionButtonNode | RenderStatCardNode | RenderChartNode | RenderCustomNode;
+/** Page-level action table entry (registry: modal | request | navigate). */
+export interface RenderPageAction {
+    type: string;
+    /** Modal content; required when type=modal. */
+    content?: RenderNode;
+    /** Request/navigate target URL. */
+    url?: string;
+    /** HTTP method for request-shaped actions. */
+    method?: string;
+    /** Permission intent name, gated against page-level permissionCascade. */
+    permissionIntent?: string;
+}
+export interface RenderPageDocument {
+    meta: RenderMeta;
+    body: RenderNode;
+    /** Page-level action table referenced by actionRef / actionId. */
+    actions?: Record<string, RenderPageAction>;
+}
+export type RenderErrorCode = "RENDER_UNKNOWN_NODE_TYPE" | "RENDER_INVALID_BODY" | "RENDER_META_INVALID" | "RENDER_FORM_FIELD_INVALID";
+export interface RenderError {
+    code: RenderErrorCode;
+    path: string;
+    message: string;
+}
+export type ActionGateErrorCode = "ACTION_GATE_EXPRESSION_INVALID";
+export interface ActionGateError {
+    code: ActionGateErrorCode;
+    path: string;
+    message: string;
+}
+export type ActionGateResult = {
+    kind: "ok";
+    value: boolean;
+} | {
+    kind: "error";
+    error: ActionGateError;
+};
+export interface RenderFormFieldGate {
+    /** Fields that passed the type whitelist and the version/capability gate. */
+    fields: FormControlField[];
+    /** Deterministic errors for rejected fields and gate failures. */
+    errors: FormControlGateError[];
+}
+/** Keeps only well-formed recordView field rows (key required). */
+export declare function parseRecordViewFields(raw: unknown): RenderRecordViewField[];
+export declare function isWhitelistedNodeType(type: string): type is RenderNodeType;
+/**
+ * Resolves a dot-path on a record for `form.recordSource.responseMapping`
+ * (e.g. `"customer.name"` → record.customer.name). Missing segments or a
+ * non-object intermediate return `undefined` (field keeps its default/empty).
+ */
+export declare function resolveResponsePath(record: unknown, path: string): unknown;
+/** Normalizes an unknown body value into a typed RenderNode, fail-closed. */
+export declare function parseRenderNode(value: unknown, path: string): RenderNode | RenderError;
+/** Collects all form fieldIds from a page document (for reaction resolution). */
+export declare function collectFieldIds(node: RenderNode, into?: string[]): string[];
+/** Resolves the reaction state for a form node's fields. */
+export declare function resolveFormReactions(form: RenderFormNode, context: Record<string, unknown>): ReactionState;
+/**
+ * Resolves a table action gate expression.
+ *
+ * Distinguishes an absent property (→ `absentDefault`) from an explicit but
+ * invalid expression (→ fail-closed `error`, no silent default). Valid $context
+ * expressions are evaluated against the frozen engine; booleans pass through.
+ */
+export declare function resolveActionGate(expression: unknown, context: Record<string, unknown>, absentDefault: boolean, path: string): ActionGateResult;
+/**
+ * Evaluates a whitelisted table action's visibility/disabled gate.
+ * Explicit invalid expressions fail closed (hidden / disabled) and are reported.
+ */
+export declare function tableActionGate(action: Record<string, unknown>, context: Record<string, unknown>): {
+    visible: boolean;
+    disabled: boolean;
+    errors: ActionGateError[];
+};
+/**
+ * Parses and gates a form node's raw fields against the D-FORM §5 whitelist
+ * and the page meta version/capability rules (F-002 / F-003).
+ *
+ * Returns only the fields that pass every gate; rejected fields produce
+ * deterministic errors instead of being silently rendered (or silently dropped).
+ */
+export declare function gateRenderFormFields(metaValue: unknown, rawFields: unknown, path: string): RenderFormFieldGate;

package/renderer/resource.d.ts

@@ -0,0 +1,114 @@
+import type { SortOrder } from "@/components/data-table";
+export declare const DEFAULT_PAGE_SIZE = 10;
+/**
+ * Frozen list-endpoint rule (I-010-001 v0.2.0 · A-001 F-001): `table.props.dataSource`
+ * must be a single-slash same-origin absolute path — starts with one `/`, no `//`
+ * (no protocol-relative host), no scheme, no whitespace, backslash, `?` or `#`.
+ * Query strings are appended by `buildResourceQuery`, never authored in dataSource;
+ * fragments are never allowed. Validated before any (auth) fetch is attempted.
+ * Mirrors `DataRef.url`'s `^/(?!/)[^\s\\]*$` but additionally rejects `?`/`#`.
+ */
+export declare const DATASOURCE_URL_PATTERN: RegExp;
+/** A schema-driven resource row: any plain JSON object (no field whitelist). */
+export interface ResourceItem {
+    [key: string]: unknown;
+}
+/** Unified list envelope frozen across resources: `{items,total,page,pageSize}`. */
+export interface ResourceList {
+    items: ResourceItem[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/** A generic resource list query. */
+export interface ResourceQuery {
+    q?: string;
+    sort?: string;
+    order?: SortOrder;
+    page?: number;
+    pageSize?: number;
+    /** Schema-driven table filters (table node props.filters): field to value. */
+    filters?: Record<string, string>;
+}
+/**
+ * Shared query for display components (statCard/chart) that read the first
+ * item + envelope of a list endpoint. The pageSize keeps the historical RPC
+ * shape (one generous bucket); wallet-ensure uses the exact same query so its
+ * existence probe coalesces with the statCards' request (per-page fetch cache).
+ */
+export declare const DISPLAY_LIST_QUERY: ResourceQuery;
+/** One field-level validation failure (GOAL-014 D-002 §2.1). */
+export interface FieldError {
+    field: string;
+    reason: string;
+}
+/** A resource API failure carrying the frozen envelope `{error, message}`. */
+export declare class ResourceApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    /** VP-007 S4: stable catalog key when the server cataloged this error. */
+    readonly messageKey?: string;
+    /** VP-007 S4: interpolation params for messageKey. */
+    readonly params?: Record<string, unknown>;
+    /** GOAL-014: field-level validation failures, when the server attached them. */
+    readonly fieldErrors: FieldError[];
+    /** R1 correlation identifier for support/operator lookup. */
+    readonly correlationId?: string;
+    constructor(status: number, code: string, message: string, messageKey?: string, params?: Record<string, unknown>, fieldErrors?: FieldError[], correlationId?: string);
+}
+/** W19: missing self-wallet is an empty surface, not a hard page error. */
+export declare function isWalletNotFoundError(err: unknown): boolean;
+export declare const EMPTY_RESOURCE_LIST: ResourceList;
+export type ResourceCreateBody = ResourceItem;
+export type ResourcePatch = Partial<ResourceItem>;
+/** F-001: single executable rule for a table list endpoint (fail-closed on any violation). */
+export declare function isValidDataSource(url: string): boolean;
+/** Reads the frozen error envelope from a non-OK response. */
+export declare function readResourceApiError(response: Response, label: string): Promise<ResourceApiError>;
+/** Serializes a ResourceQuery into a URL query string (query-serialization). */
+/**
+ * v2.9 dataSource params resolution (ADR-0039, capability data.route-binding).
+ * Literal scalars pass through; whole `$context.route.query.*` /
+ * `$context.route.params.*` bindings are resolved from the route snapshot;
+ * a missing key (or absent route) is a tombstone — the parameter is dropped
+ * (ADR-0010 semantics, same as null values). Returns the merged query string
+ * (empty when nothing resolves).
+ */
+export declare function resolveDataParamsQuery(params: Record<string, unknown> | undefined, route: {
+    query?: Record<string, string>;
+    params?: Record<string, string>;
+}): string;
+export declare function buildResourceQuery(query: ResourceQuery): string;
+/**
+ * Maps an unknown list payload to the unified ResourceList envelope, fail-closed
+ * on shape drift. Items are arbitrary JSON objects (F-002 rowKey is enforced at
+ * the table surface, not here).
+ */
+export declare function parseResourceList(value: unknown): ResourceList;
+/**
+ * Builds the query-string portion of a resource list request — the exact
+ * construction `fetchResourceList` sends on the wire. `extraQuery` carries
+ * v2.9 ADR-0039 dataSource params that already resolved to literal key=value
+ * pairs and is merged over the standard q/sort/order/page/pageSize query.
+ */
+export declare function resourceListQueryString(query: ResourceQuery, extraQuery?: string): string;
+/**
+ * The final URL for a resource list request (F-001-validated baseURL + query
+ * string). Shared by `fetchResourceList` and the renderer's per-page fetch
+ * cache so the cache key and the wire request can never drift apart.
+ */
+export declare function resourceListURL(baseURL: string, query: ResourceQuery, extraQuery?: string): string;
+/**
+ * Fetches a page of a schema-driven resource list (request-construction).
+ *
+ * `extraQuery` carries v2.9 ADR-0039 dataSource params that already resolved
+ * to literal key=value pairs (e.g. `dictKey=order_status` from a
+ * `$context.route.query.*` binding). It is merged with the standard
+ * q/sort/order/page/pageSize query; baseURL itself must stay a bare
+ * single-slash same-origin path (F-001).
+ */
+export declare function fetchResourceList(fetcher: typeof fetch, baseURL: string, query: ResourceQuery, extraQuery?: string): Promise<ResourceList>;
+/** Creates a resource row via POST; returns the 201 row. */
+export declare function createResource(fetcher: typeof fetch, baseURL: string, body: ResourceCreateBody): Promise<ResourceItem>;
+export declare function updateResource(fetcher: typeof fetch, baseURL: string, id: string, patch: ResourcePatch): Promise<ResourceItem>;
+export declare function deleteResource(fetcher: typeof fetch, baseURL: string, id: string): Promise<void>;