@sincpro/web-framework 0.0.0-stage → 0.1.0

package/dist/core/present.d.ts

@@ -0,0 +1,48 @@
+import { type FieldMeta, type Meta } from "@sincpro/criteria";
+/**
+ * How a field is SHOWN, decided once from the model and nowhere else.
+ *
+ * Context: this is the part of "render from the metadata" that is the same in every
+ * piece. A table column, a fact of a record and a search chip all need the word for the field, whether it is a
+ * number, whether it orders, and the text a value reads as («Pagada», «12/03/2026», «sí»,
+ * «3 elementos»). What they draw it WITH is theirs; what it SAYS is decided here, so they
+ * cannot disagree.
+ */
+export type FieldView = {
+    name: string;
+    label: string;
+    help: string | undefined;
+    type: FieldMeta["type"];
+    kind: FieldMeta["kind"];
+    /** Right-aligned, tabular: integer and number. */
+    numeric: boolean;
+    /** The server can order by it — never a nullable column. */
+    sortable: boolean;
+    required: boolean;
+    readonly: boolean;
+};
+export declare function viewOf(meta: Meta | null | undefined, name: string, locale?: string): FieldView;
+/**
+ * The fields a screen shows when it names none: every scalar the model holds, in the order it
+ * declares them. Relations and value objects are left out — they are not a column, they are a
+ * page of their own (`RecordLines`) or a section.
+ */
+export declare function defaultFields(meta: Meta | null | undefined): string[];
+/** The bookkeeping every framework entity carries; shown on demand, never by default. */
+export declare const BOOKKEEPING: ReadonlySet<string>;
+/**
+ * The text a value reads as. `null` when there is nothing to read — the caller draws its own
+ * «empty» (a dash in a fact, nothing in a cell).
+ *
+ *     textOf(meta, "state", "paid", "es")            -> "Pagada"     (choice_labels)
+ *     textOf(meta, "active", true, "es")              -> "sí"
+ *     textOf(meta, "due", "2026-03-12", "es")         -> "12 mar 2026"
+ *     textOf(meta, "total", "1150.5", "es")           -> "1150,5"     (exact: digits kept)
+ *     textOf(meta, "lines", {items, count: {value: 30}}) -> "30 elementos"
+ */
+export declare function textOf(meta: Meta | null | undefined, name: string, value: unknown, locale?: string): string | null;
+/**
+ * The value a column orders and groups on: the raw scalar, never the text. ISO dates order
+ * as text; a decimal that travels as text orders as a number.
+ */
+export declare function sortKeyOf(meta: Meta | null | undefined, name: string, value: unknown): string | number | boolean | null;

package/dist/core/present.js

@@ -0,0 +1,165 @@
+import { choiceLabelOf, labelOf, } from "@sincpro/criteria";
+import { frameworkCopy } from "./copy.js";
+import { relatedOf } from "./related.js";
+/** Present when a field is named that the model does not declare: drawn plain, never thrown. */
+const UNKNOWN = {
+    type: "unknown",
+    kind: "scalar",
+    nullable: true,
+    sortable: false,
+    ops: [],
+};
+function fieldOf(meta, name) {
+    return meta?.fields[name] ?? UNKNOWN;
+}
+function helpOf(field, locale) {
+    const help = field.help;
+    if (help === undefined)
+        return undefined;
+    return (locale ? help[locale] : undefined) ?? help["default"];
+}
+export function viewOf(meta, name, locale) {
+    const field = fieldOf(meta, name);
+    return {
+        name,
+        label: labelOf(meta, name, locale),
+        help: helpOf(field, locale),
+        type: field.type,
+        kind: field.kind,
+        numeric: field.type === "integer" || field.type === "number",
+        sortable: field.sortable,
+        required: field.required ?? false,
+        readonly: field.readonly ?? false,
+    };
+}
+/**
+ * The fields a screen shows when it names none: every scalar the model holds, in the order it
+ * declares them. Relations and value objects are left out — they are not a column, they are a
+ * page of their own (`RecordLines`) or a section.
+ */
+export function defaultFields(meta) {
+    if (!meta)
+        return [];
+    return Object.entries(meta.fields)
+        .filter(([, field]) => field.kind === "scalar")
+        .map(([name]) => name);
+}
+/** The bookkeeping every framework entity carries; shown on demand, never by default. */
+export const BOOKKEEPING = new Set(["version", "updated_at"]);
+/** `"2026-03-12"` as a LOCAL date: `new Date("2026-03-12")` is UTC midnight, the day before
+ *  anywhere west of Greenwich. */
+function localDate(text) {
+    const [year, month, day] = text.split("-").map(Number);
+    return new Date(year ?? 0, (month ?? 1) - 1, day ?? 1);
+}
+function decimals(text) {
+    const dot = text.indexOf(".");
+    return dot < 0 ? 0 : text.length - dot - 1;
+}
+/**
+ * One formatter per locale and shape, kept. Building an `Intl` formatter costs far more than
+ * using one: built per cell, 2 000 rows × 8 fields took ~150 ms — a list that stutters on
+ * every page. The set of shapes is tiny (three date/number styles × decimals × locales).
+ */
+const formatters = new Map();
+function dateFormat(locale, withTime) {
+    const key = `d|${locale ?? ""}|${withTime}`;
+    let format = formatters.get(key);
+    if (format === undefined) {
+        format = new Intl.DateTimeFormat(locale, withTime ? { dateStyle: "medium", timeStyle: "short" } : { dateStyle: "medium" });
+        formatters.set(key, format);
+    }
+    return format;
+}
+function numberFormat(locale, kept) {
+    const key = `n|${locale ?? ""}|${kept ?? ""}`;
+    let format = formatters.get(key);
+    if (format === undefined) {
+        format = new Intl.NumberFormat(locale, kept === undefined ? {} : { minimumFractionDigits: kept, maximumFractionDigits: kept });
+        formatters.set(key, format);
+    }
+    return format;
+}
+/** The record a many2one points at, read by the display its definition names. */
+function displayOf(field, value) {
+    const definition = field.definition;
+    const display = definition?.display || undefined;
+    const key = display ?? definition?.identity ?? "id";
+    const shown = value[key] ?? value["display_name"] ?? value["name"] ?? value["id"];
+    return shown === undefined || shown === null ? "" : String(shown);
+}
+/**
+ * The text a value reads as. `null` when there is nothing to read — the caller draws its own
+ * «empty» (a dash in a fact, nothing in a cell).
+ *
+ *     textOf(meta, "state", "paid", "es")            -> "Pagada"     (choice_labels)
+ *     textOf(meta, "active", true, "es")              -> "sí"
+ *     textOf(meta, "due", "2026-03-12", "es")         -> "12 mar 2026"
+ *     textOf(meta, "total", "1150.5", "es")           -> "1150,5"     (exact: digits kept)
+ *     textOf(meta, "lines", {items, count: {value: 30}}) -> "30 elementos"
+ */
+export function textOf(meta, name, value, locale) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    const field = fieldOf(meta, name);
+    const copy = frameworkCopy();
+    if (field.choices && field.choices.length > 0)
+        return choiceLabelOf(meta, name, value, locale);
+    switch (field.type) {
+        case "boolean":
+            return value ? copy.value.yes : copy.value.no;
+        case "date":
+            return typeof value === "string"
+                ? dateFormat(locale, false).format(localDate(value))
+                : String(value);
+        case "datetime": {
+            const date = new Date(String(value));
+            return Number.isNaN(date.getTime())
+                ? String(value)
+                : dateFormat(locale, true).format(date);
+        }
+        case "integer":
+        case "number": {
+            const number = Number(value);
+            if (Number.isNaN(number))
+                return String(value);
+            const kept = typeof value === "string" ? decimals(value) : undefined;
+            return numberFormat(locale, kept).format(number);
+        }
+        case "text[]":
+            return Array.isArray(value)
+                ? value.length === 0
+                    ? null
+                    : value.join(", ")
+                : String(value);
+        case "one2many":
+        case "many2many": {
+            const related = relatedOf(value);
+            return copy.value.items(related.count.value, related.count.exact);
+        }
+        case "many2one":
+            return typeof value === "object" ? displayOf(field, value) : String(value);
+        case "embedded":
+            return null;
+        default:
+            return typeof value === "object" ? JSON.stringify(value) : String(value);
+    }
+}
+/**
+ * The value a column orders and groups on: the raw scalar, never the text. ISO dates order
+ * as text; a decimal that travels as text orders as a number.
+ */
+export function sortKeyOf(meta, name, value) {
+    if (value === null || value === undefined)
+        return null;
+    const field = fieldOf(meta, name);
+    if (field.type === "number" || field.type === "integer") {
+        const number = Number(value);
+        return Number.isNaN(number) ? null : number;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (field.type === "one2many" || field.type === "many2many")
+        return relatedOf(value).count.value;
+    return textOf(meta, name, value);
+}

package/dist/core/related.d.ts

@@ -0,0 +1,22 @@
+import type { Count } from "@sincpro/criteria";
+/**
+ * The records a relation holds inside its parent, however the server sent them.
+ *
+ * Context: sincpro_framework answers a one2many of a record as a PAGE of its own —
+ * `{items, count, cursor}` — so a tenant with a thousand members does not answer all of them;
+ * an older answer, or a domain declared by hand, sends a bare array. A screen that reads only
+ * `items` and counts them shows the first page and calls it the total (forge's console did:
+ * `count={repositories.length}`). This reads both shapes and keeps the real count.
+ *
+ *     relatedOf({ items: [a, b], count: { value: 1000, exact: true }, cursor: "x" })
+ *       -> { items: [a, b], count: { value: 1000, exact: true }, cursor: "x", partial: true }
+ *     relatedOf([a, b])  -> { items: [a, b], count: { value: 2, exact: true }, cursor: null, partial: false }
+ */
+export type Related<T> = {
+    items: T[];
+    count: Count;
+    cursor: string | null;
+    /** There are more than `items` holds: the record brought one page of them. */
+    partial: boolean;
+};
+export declare function relatedOf<T>(value: unknown): Related<T>;

package/dist/core/related.js

@@ -0,0 +1,21 @@
+export function relatedOf(value) {
+    if (Array.isArray(value))
+        return {
+            items: value,
+            count: { value: value.length, exact: true },
+            cursor: null,
+            partial: false,
+        };
+    if (typeof value === "object" && value !== null && "items" in value) {
+        const page = value;
+        const items = page.items ?? [];
+        const count = page.count ?? { value: items.length, exact: page.cursor == null };
+        return {
+            items,
+            count,
+            cursor: page.cursor ?? null,
+            partial: count.value > items.length || !count.exact || page.cursor != null,
+        };
+    }
+    return { items: [], count: { value: 0, exact: true }, cursor: null, partial: false };
+}

package/dist/core/rest.d.ts

@@ -0,0 +1,30 @@
+import { type Criteria } from "@sincpro/criteria";
+import { type Transport } from "./transport.js";
+/**
+ * The REST wire of sincpro_framework (`FastApiGateway`).
+ *
+ * Context: two things `restSource` from `@sincpro/criteria` 0.3 gets wrong against
+ * sincpro_framework 3.27, both found by forge's console, which had to write its own client:
+ *
+ * - it appends `?criteria=` to the route as it is, which breaks a route that already carries
+ *   its own query (`/projects?tenant_id=acme`) — here the criteria joins that query;
+ * - it sends `pack()` (base64url), and the REST entrypoint reads the parameter as plain JSON
+ *   and refuses anything else («criteria is not JSON») — here it travels as JSON.
+ *
+ * Once criteria fixes both, this keeps only what it adds: `one()`.
+ *
+ *     const transport = restTransport({
+ *       base: "/v1",
+ *       headers: () => ({ Authorization: `Bearer ${session.secret}` }),
+ *     });
+ */
+export type RestOptions = {
+    /** Prepended to every route: `"/v1"`, `"https://forge.sincpro.com.bo/v1"`. */
+    base?: string;
+    /** Sent with every request. A function is called fresh each time — a token that rotates. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Defaults to the global `fetch`. Inject one for tests. */
+    fetch?: typeof fetch;
+};
+export declare function urlOf<T>(base: string, route: string, criteria?: Criteria<T>): string;
+export declare function restTransport(options?: RestOptions): Transport;

package/dist/core/rest.js

@@ -0,0 +1,50 @@
+import { pageFrom, plain, readProblem, } from "@sincpro/criteria";
+import { TransportError, } from "./transport.js";
+/** The keys of an answer that are not the record: what is left is the record's own field. */
+const ENVELOPE = new Set(["cursor", "count", "entity_meta_data", "dropped", "draft"]);
+export function urlOf(base, route, criteria) {
+    const url = `${base}${route}`;
+    if (criteria === undefined)
+        return url;
+    const joiner = url.includes("?") ? "&" : "?";
+    return `${url}${joiner}criteria=${encodeURIComponent(JSON.stringify(criteria))}`;
+}
+export function restTransport(options = {}) {
+    const base = options.base ?? "";
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    async function get(route, url, signal, write) {
+        const own = typeof options.headers === "function" ? options.headers() : (options.headers ?? {});
+        const headers = write ? { ...own, "Content-Type": "application/json" } : own;
+        const response = await doFetch(url, {
+            headers,
+            ...(write ? { method: write.method, body: JSON.stringify(write.body) } : {}),
+            ...(signal ? { signal } : {}),
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw new TransportError(route, response.status, readProblem(text), undefined);
+        return text ? JSON.parse(text) : null;
+    }
+    return {
+        async list(route, criteria, signal) {
+            const answer = await get(route, urlOf(base, route, plain(criteria)), signal);
+            return pageFrom(answer);
+        },
+        async one(route, signal) {
+            const answer = (await get(route, urlOf(base, route), signal));
+            const own = Object.keys(answer).filter((key) => !ENVELOPE.has(key));
+            const [key] = own;
+            if (own.length !== 1 || key === undefined)
+                throw new TransportError(route, 200, null, `${route} answered ${own.length} fields of its own (${own.join(", ")}); a record answers one`);
+            return {
+                record: answer[key],
+                meta: answer["entity_meta_data"] ?? null,
+                dropped: answer["dropped"] ?? [],
+                draft: answer["draft"] ?? null,
+            };
+        },
+        async send(method, route, body, signal) {
+            return (await get(route, urlOf(base, route), signal, { method, body }));
+        },
+    };
+}

package/dist/core/schema.d.ts

@@ -0,0 +1,46 @@
+import type { Meta } from "@sincpro/criteria";
+/**
+ * A model definition read from a JSON Schema — what an OpenAPI document holds.
+ *
+ * Context: what sincpro_framework's OpenAPI 3.1 describes and what it does not, checked
+ * against a running forge:
+ *
+ *   - the records a READ answers are invisible: the framework serialises them with its own
+ *     envelope, so `GET /projects` and `GET /projects/{id}` answer schema `{}` and no
+ *     `Project` schema exists. A list's definition comes from `entity_meta_data`, at runtime
+ *     or preloaded (`FrameworkProvider metas`) — not from here;
+ *   - the COMMANDS and the value objects are described well, and better than the meta in one
+ *     place: inside a value object `entity_meta_data` sends a `Literal` and a `list[str]` as
+ *     `unknown`, where the schema says `enum: ["es", "en"]` and `array<string>`.
+ *
+ * So this reads a component schema into a `Meta` — the form of a Command, a value object — and
+ * `completeMeta` fills, from it, what the server's meta left `unknown`.
+ *
+ *     const spec = metaFromSchema("ProjectSpecification", doc.components.schemas);
+ *     const fixed = completeMeta(project.fields.specification.definition, spec);
+ */
+export type JsonSchema = {
+    type?: string | string[];
+    format?: string;
+    enum?: readonly unknown[];
+    items?: JsonSchema;
+    $ref?: string;
+    anyOf?: readonly JsonSchema[];
+    oneOf?: readonly JsonSchema[];
+    properties?: Readonly<Record<string, JsonSchema>>;
+    required?: readonly string[];
+    title?: string;
+    description?: string;
+    default?: unknown;
+};
+export type SchemaComponents = Readonly<Record<string, JsonSchema>>;
+/** The definition a component schema describes. `identity` empty: a value object has none. */
+export declare function metaFromSchema(name: string, components: SchemaComponents, options?: {
+    identity?: string;
+}): Meta;
+/**
+ * The server's definition, with what it left `unknown` taken from the schema — recursively
+ * into value objects. What the server DID say always wins: its labels, its operators, its
+ * hints. A field the schema does not know is left as the server sent it.
+ */
+export declare function completeMeta(meta: Meta, schema: Meta): Meta;

package/dist/core/schema.js

@@ -0,0 +1,128 @@
+import { field } from "./meta.js";
+const UNKNOWN = {
+    type: "unknown",
+    kind: "scalar",
+    nullable: true,
+    sortable: false,
+    ops: [],
+};
+function nameOfRef(ref) {
+    return ref.slice(ref.lastIndexOf("/") + 1);
+}
+/** `anyOf: [X, {type: "null"}]` is `X`, nullable — how pydantic writes `X | None`. */
+function unwrap(schema) {
+    const options = schema.anyOf ?? schema.oneOf;
+    if (options === undefined)
+        return { schema, nullable: false };
+    const real = options.filter((one) => one.type !== "null");
+    const [only] = real;
+    return real.length === 1 && only !== undefined
+        ? { schema: { ...only, ...pick(schema) }, nullable: real.length < options.length }
+        : { schema, nullable: real.length < options.length };
+}
+/** The words of the outer schema win over the ones of what it wraps. */
+function pick(schema) {
+    return {
+        ...(schema.title === undefined ? {} : { title: schema.title }),
+        ...(schema.description === undefined ? {} : { description: schema.description }),
+        ...(schema.default === undefined ? {} : { default: schema.default }),
+    };
+}
+function fieldFrom(raw, required, components, seen) {
+    const { schema: unwrapped, nullable } = unwrap(raw);
+    const target = unwrapped.$ref !== undefined
+        ? { ...components[nameOfRef(unwrapped.$ref)], ...pick(unwrapped) }
+        : unwrapped;
+    const options = {
+        ...(target.title === undefined ? {} : { label: target.title }),
+        ...(target.description === undefined ? {} : { help: target.description }),
+        ...(target.default === undefined ? {} : { default: target.default }),
+        ...(nullable ? { nullable } : {}),
+        required: required && target.default === undefined && !nullable,
+    };
+    if (unwrapped.$ref !== undefined) {
+        const name = nameOfRef(unwrapped.$ref);
+        if (components[name] === undefined || seen.has(name))
+            return UNKNOWN;
+        if (target.properties === undefined)
+            return target.enum ? field.choice(target.enum.map(String), options) : UNKNOWN;
+        return field.embedded(metaOf(name, target, components, new Set([...seen, name])), options);
+    }
+    if (target.enum)
+        return field.choice(target.enum.map(String), options);
+    const type = Array.isArray(target.type)
+        ? target.type.find((t) => t !== "null")
+        : target.type;
+    switch (type) {
+        case "string":
+            if (target.format === "date")
+                return field.date(options);
+            if (target.format === "date-time")
+                return field.datetime(options);
+            return field.text(options);
+        case "integer":
+            return field.integer(options);
+        case "number":
+            return field.number(options);
+        case "boolean":
+            return field.boolean(options);
+        case "array": {
+            const item = target.items === undefined ? undefined : unwrap(target.items).schema;
+            if (item?.$ref !== undefined) {
+                const inner = fieldFrom(item, false, components, seen);
+                return inner.kind === "embedded" && inner.definition
+                    ? field.embedded(inner.definition, { ...options, many: true })
+                    : field.tags(options);
+            }
+            return item?.type === "string" || item?.enum ? field.tags(options) : UNKNOWN;
+        }
+        default:
+            return UNKNOWN;
+    }
+}
+function metaOf(name, schema, components, seen) {
+    const required = new Set(schema.required ?? []);
+    const fields = Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, property]) => [
+        key,
+        fieldFrom(property, required.has(key), components, seen),
+    ]));
+    return {
+        aggregate: name,
+        identity: "",
+        default_order: "",
+        fields,
+        ...(schema.title === undefined ? {} : { name: { default: schema.title } }),
+    };
+}
+/** The definition a component schema describes. `identity` empty: a value object has none. */
+export function metaFromSchema(name, components, options = {}) {
+    const schema = components[name];
+    if (schema === undefined)
+        throw new Error(`no schema named ${name}`);
+    const meta = metaOf(name, schema, components, new Set([name]));
+    return options.identity
+        ? { ...meta, identity: options.identity, get_id: options.identity }
+        : meta;
+}
+/**
+ * The server's definition, with what it left `unknown` taken from the schema — recursively
+ * into value objects. What the server DID say always wins: its labels, its operators, its
+ * hints. A field the schema does not know is left as the server sent it.
+ */
+export function completeMeta(meta, schema) {
+    const fields = Object.fromEntries(Object.entries(meta.fields).map(([name, own]) => {
+        const known = schema.fields[name];
+        if (known === undefined)
+            return [name, own];
+        if (own.type === "unknown")
+            return [name, { ...known, ...labelsOf(own) }];
+        if (own.kind === "embedded" && own.definition && known.definition)
+            return [name, { ...own, definition: completeMeta(own.definition, known.definition) }];
+        return [name, own];
+    }));
+    return { ...meta, fields };
+}
+/** A label the server declared is kept over the schema's generated title. */
+function labelsOf(own) {
+    return own.label && Object.keys(own.label).length > 0 ? { label: own.label } : {};
+}

package/dist/core/transport.d.ts

@@ -0,0 +1,59 @@
+import type { Criteria, Dropped, Meta, Page, Problem } from "@sincpro/criteria";
+/**
+ * The one seam between this package and a server.
+ *
+ * Context: a list and a record are the same two questions whatever the wire is — «a page of
+ * these, under this criteria» and «this one». REST today; JSON-RPC and gRPC are the other
+ * wires sincpro_framework serves. Each of those is
+ * one adapter implementing this, and nothing above it changes. A route is a string the adapter
+ * understands: a path for REST, a method for RPC.
+ *
+ * Every adapter throws `TransportError` for a refusal, so a screen explains a failure once
+ * whichever wire it came over.
+ */
+export interface Transport {
+    /** A page of records under the criteria. */
+    list<T>(route: string, criteria: Criteria<T>, signal?: AbortSignal): Promise<Page<T>>;
+    /** One record, with the definition of its model. */
+    one<T>(route: string, signal?: AbortSignal): Promise<One<T>>;
+    /** A Command — a write, an action, a preview: `method` and a JSON body, its answer back. */
+    send<T>(method: Method, route: string, body: unknown, signal?: AbortSignal): Promise<T>;
+}
+export type Method = "POST" | "PUT" | "PATCH" | "DELETE";
+/** One record as sincpro_framework answers it (`ResponseRecord`): the record, its model. */
+export type One<T> = {
+    record: T;
+    meta: Meta | null;
+    dropped: Dropped[];
+    /** What this caller kept of an edit between requests (sincpro_framework `Drafts`). */
+    draft: Draft | null;
+};
+/** A kept edit: the values typed, the version of the draft, the record version it started on. */
+export type Draft = {
+    values: Record<string, unknown>;
+    version: number;
+    origin_version?: number;
+};
+/**
+ * A refusal, from any wire. `problem` is what the server said about it (RFC 9457 plus the
+ * engine's `kind`, `next_step`, `guidance`) or `null` when it said nothing readable — a proxy's
+ * HTML page. `status` is `null` when the request never got an answer.
+ */
+export declare class TransportError extends Error {
+    readonly route: string;
+    readonly status: number | null;
+    readonly problem: Problem | null;
+    constructor(route: string, status: number | null, problem: Problem | null, message?: string);
+}
+/**
+ * What a person reads about a failure: a heading, and a sentence with what happened and what
+ * to do. The server's own words first; the copy table's when it sent none.
+ *
+ *     explain(new TransportError("/x", 403, { kind: "permission_denied", guidance: "Pedí acceso.", … }))
+ *       -> { heading: "No tenés acceso", sentence: "Pedí acceso.", retryable: false }
+ */
+export declare function explain(error: unknown): {
+    heading: string;
+    sentence: string;
+    retryable: boolean;
+};

package/dist/core/transport.js

@@ -0,0 +1,43 @@
+import { frameworkCopy } from "./copy.js";
+/**
+ * A refusal, from any wire. `problem` is what the server said about it (RFC 9457 plus the
+ * engine's `kind`, `next_step`, `guidance`) or `null` when it said nothing readable — a proxy's
+ * HTML page. `status` is `null` when the request never got an answer.
+ */
+export class TransportError extends Error {
+    route;
+    status;
+    problem;
+    constructor(route, status, problem, message) {
+        super(message ?? problem?.detail ?? problem?.title ?? `${status ?? "no answer"} at ${route}`);
+        this.route = route;
+        this.status = status;
+        this.problem = problem;
+        this.name = "TransportError";
+    }
+}
+/**
+ * What a person reads about a failure: a heading, and a sentence with what happened and what
+ * to do. The server's own words first; the copy table's when it sent none.
+ *
+ *     explain(new TransportError("/x", 403, { kind: "permission_denied", guidance: "Pedí acceso.", … }))
+ *       -> { heading: "No tenés acceso", sentence: "Pedí acceso.", retryable: false }
+ */
+export function explain(error) {
+    const copy = frameworkCopy().failure;
+    if (error instanceof TransportError && error.problem !== null) {
+        const { kind, title, detail, guidance, retryable } = error.problem;
+        return {
+            heading: title ?? copy.kind[kind] ?? copy.status(error.status ?? 0),
+            sentence: [detail, guidance].filter(Boolean).join(" "),
+            retryable,
+        };
+    }
+    if (error instanceof TransportError && error.status !== null)
+        return { heading: copy.status(error.status), sentence: error.message, retryable: true };
+    return {
+        heading: copy.unreachable,
+        sentence: error instanceof Error ? error.message : String(error),
+        retryable: true,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public entry of @sincpro/web-framework — the web client of sincpro_framework, married to
+ * `@sincpro/web-ui` (how it looks) and `@sincpro/web-composer` (where it opens).
+ *
+ * Inside, three folders with one direction: `core/` is plain logic with no React (tested in
+ * Node), `react/` holds state and draws nothing, `web/` draws. `make doctor` keeps the arrows.
+ */
+export * from "./core/index.js";
+export * from "./react/index.js";
+export * from "./web/index.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public entry of @sincpro/web-framework — the web client of sincpro_framework, married to
+ * `@sincpro/web-ui` (how it looks) and `@sincpro/web-composer` (where it opens).
+ *
+ * Inside, three folders with one direction: `core/` is plain logic with no React (tested in
+ * Node), `react/` holds state and draws nothing, `web/` draws. `make doctor` keeps the arrows.
+ */
+export * from "./core/index.js";
+export * from "./react/index.js";
+export * from "./web/index.js";

package/dist/react/context.d.ts

@@ -0,0 +1,27 @@
+import type { Meta } from "@sincpro/criteria";
+import { type MetaStore } from "../core/metas.js";
+import type { Transport } from "../core/transport.js";
+import { type ReactNode } from "react";
+/**
+ * Who answers, in which language a screen reads, and which model definitions are already
+ * known — for everything under it.
+ *
+ * Context: a view receives its record reference and nothing else — the composer hands it no
+ * client on purpose — so the transport reaches it through context, set once where the
+ * application starts.
+ */
+type FrameworkContextValue = {
+    transport: Transport;
+    locale: string | undefined;
+    metas: MetaStore;
+};
+export declare function FrameworkProvider({ transport, locale, metas: seed, children, }: {
+    transport: Transport;
+    /** The language labels and values are read in (`"es"`); the model's `default` without it. */
+    locale?: string;
+    /** Definitions known before any request, by entity key: the preload. */
+    metas?: Readonly<Record<string, Meta>>;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useFramework(): FrameworkContextValue;
+export {};