@ahoo-wang/wow-view-engine 9.2.0-rc.0

package/dist/model/issue.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A validation finding. Every kernel reports problems this way.
+ *
+ * Wording lives in the UI layer: `code` is the branching key and `params`
+ * carries the values a message needs, so the model stays free of copy.
+ */
+export interface Issue {
+    /** Stable machine-readable key, e.g. `record.sort.field-not-sortable`. */
+    code: string;
+    severity: IssueSeverity;
+    /** Location inside the config, e.g. `['sort', 0, 'field']`. */
+    path: IssuePath;
+    params?: Record<string, string | number>;
+}
+/**
+ * `error` blocks apply and save; `warning` is reported without blocking —
+ * something is wrong, or the answer could be misread; `note` is something
+ * true about the answer a reader should know, and nothing is wrong: the
+ * groups a view's own limit left out, when every row shown is whole.
+ */
+export type IssueSeverity = 'error' | 'warning' | 'note';
+export type IssuePath = (string | number)[];
+/** What separates the items of a list parameter (`listParam`). */
+export declare const LIST_PARAM_SEPARATOR = "\u001E";
+/**
+ * A parameter that is a list — the titles of the boards that keep a view
+ * shared — as one string the model can carry. Joining it is wording: the
+ * catalogue's formatter joins the items as the surface's language joins a
+ * list (`Intl.ListFormat`, a conjunction: 「A、B和C」, "A, B, and C"), after
+ * which a title written as a key is said where it is shown (D2).
+ */
+export declare function listParam(items: readonly string[]): string;
+//# sourceMappingURL=issue.d.ts.map

package/dist/model/issue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../src/model/issue.ts"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;IACxB,+DAA+D;IAC/D,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAE5C,kEAAkE;AAClE,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE1D"}

package/dist/model/json.d.ts

@@ -0,0 +1,34 @@
+/** Any value a saved configuration may hold: configs are plain JSON. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Replaces enum members with their string values and leaves everything else
+ * untouched, so a Wow protocol type can be reused in a configuration without
+ * dragging its enums into stored data.
+ */
+export type LiteralEnums<T> = T extends string ? `${T}` : T extends object ? {
+    [K in keyof T]: LiteralEnums<T[K]>;
+} : T;
+/**
+ * The object without one optional member: what "unset" writes. A config
+ * stays plain JSON, so a setting taken back leaves no `undefined` behind for
+ * a comparison to trip over.
+ */
+export declare function without<T extends object, K extends keyof T>(value: T, key: K): Omit<T, K>;
+/**
+ * The object with `patch` laid over it, where a member the patch gives as
+ * `undefined` is taken out rather than set to it — for the same reason as
+ * `without`: a member that is not there and one that is `undefined` are the
+ * same JSON but not the same object, and a comparison against what was
+ * saved would call the two different.
+ */
+export declare function overlaid<T extends object>(value: T, patch: Partial<T>): T;
+/**
+ * Whether two plain JSON values say the same, whatever order their object
+ * keys came in — a member that is `undefined` reads as one not there, as
+ * JSON reads it. What a board's filters hold, one filter's value, a panel's
+ * look against its view's.
+ */
+export declare function sameJson(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=json.d.ts.map

package/dist/model/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/model/json.ts"],"names":[],"mappings":"AAaA,wEAAwE;AACxE,MAAM,MAAM,SAAS,GACnB,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GAC1C,GAAG,CAAC,EAAE,GACN,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACtC,CAAC,CAAC;AAER;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EACzD,KAAK,EAAE,CAAC,EACR,GAAG,EAAE,CAAC,GACL,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAIZ;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAKzE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAExD"}

package/dist/model/limits.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Admission and scheduling budgets. Configs arrive from a store, so the
+ * validators apply these before anything reaches a compiler or a timer.
+ */
+export interface RuntimeLimits {
+    /** Data queries running at once across every runtime of one engine. */
+    maxConcurrentQueries: number;
+    /**
+     * Queued data queries; beyond this a request is rejected, not buffered.
+     * An open board holds room of its own on top of it, sized by its panels,
+     * so a board larger than this still opens whole (host-integration.md 4).
+     */
+    maxQueuedQueries: number;
+    /** Upper bound of `RecordViewConfig.pageSize`. */
+    maxPageSize: number;
+    /**
+     * The most rows a paged query may reach, page × size, whatever the
+     * definition says: a definition's `RecordCapability.maxWindow` may only
+     * lower it. The pager stops at the last page inside it and an export
+     * stops there too (`pageWindow`).
+     */
+    maxPageWindow: number;
+    /**
+     * The most rows any analysis query asks for: the upper bound of
+     * `AnalysisViewConfig.limit`, and of what the engine asks beside it — the
+     * probe row that tells a cut result from a whole one, and the split's
+     * whole a 「其他」 is measured against. A definition's `maxLimit` may
+     * only lower it (`limitBounds`).
+     */
+    maxAnalysisRows: number;
+    /**
+     * Rows one export may carry away, however many the conditions match.
+     *
+     * An export pages the source under the applied conditions with no regard
+     * for the page on screen, so it is the one command here whose cost is the
+     * size of the *result* rather than of a page. The ceiling is what keeps a
+     * mis-aimed export from asking a backend for a million rows and building a
+     * string of them in a browser tab; over it, the count is put to the user
+     * before anything is fetched.
+     */
+    exportMax: number;
+    /** Shortest auto-refresh interval, in seconds. */
+    minRefreshInterval: number;
+    /** Longest auto-refresh interval, in seconds; keeps the timer in range. */
+    maxRefreshInterval: number;
+    /** Nesting depth of a filter tree, checked iteratively before recursion. */
+    maxFilterDepth: number;
+    /**
+     * Total nodes of a filter tree as a config holds it, groups included; and
+     * of an expression or 「只保留」 tree. The engine's own guard on a tree
+     * that arrives from a store, walked before anything recurses into it —
+     * not what a source admits, which `maxQueryFilterNodes` says.
+     */
+    maxFilterNodes: number;
+    /**
+     * The most filter nodes one query may send, counted as a Wow service's
+     * query guard counts them (`max-filter-nodes`): on the compiled query,
+     * its own filter, each element's and each metric's, and its 「只保留」
+     * together — a date range is one condition and three nodes. A source's
+     * descriptor says it (`limits.maxFilterNodes`); the host only lowers it.
+     */
+    maxQueryFilterNodes: number;
+    /**
+     * The most values one filter node may carry — an `IN` list, `IDS`, a
+     * 「只保留」 `IN` — as the guard counts them (`max-filter-values`). A
+     * source's descriptor says it (`limits.maxFilterValues`).
+     */
+    maxFilterValues: number;
+    /** Panels of one dashboard, checked before any child runtime is created. */
+    maxDashboardPanels: number;
+    /**
+     * The page sizes a control offers from, before `maxPageSize` cuts them and
+     * the size a view is saved at is folded in.
+     */
+    pageSizes: readonly number[];
+    /**
+     * The page sizes the card layout offers from, cut and folded the same way.
+     *
+     * A page of cards is read in rows, and a page that is not a whole number
+     * of rows ends on a row with a gap in it — 50 cards three to a row is
+     * sixteen rows and a stray two (the user's 2026-09-23 review). The ladder
+     * is multiples of 12 because 12 is a whole number of rows at every width a
+     * grid can be: one to four cards per row, and the fewer columns a narrow
+     * screen falls back to. Switching the layout moves the page size to the
+     * nearest rung of the other ladder (`nearestPageSize`), so 20 rows of a
+     * table come back as 24 cards and go back as 20 rows.
+     */
+    cardPageSizes: readonly number[];
+    /**
+     * The auto-refresh cadences a control offers from, in seconds, before the
+     * two interval bounds cut them and the interval in force is folded in.
+     *
+     * Three rungs by default, and deliberately few. Half a minute is the
+     * shortest cadence a person reads as "live" without the screen redrawing
+     * under their hands, five minutes the longest before "keeps itself up to
+     * date" stops being the reason anyone opened this view; a quarter of an
+     * hour and an hour were rungs nobody picked and everybody had to read
+     * past. Every rung divides into whole seconds or minutes, so each has a
+     * label nobody has to decode — and a view already saved at some other
+     * number keeps its own rung, so shortening the ladder strands nobody.
+     */
+    refreshIntervals: readonly number[];
+    /** The page size a new record view starts at, unless its definition says. */
+    defaultPageSize: number;
+    /** Columns a new record view shows; more is noise in a first view. */
+    defaultColumns: number;
+    /** Fields on a new record view's cards, the title aside. */
+    defaultCardFields: number;
+    /**
+     * Whether every file the default UI exports — a record view's rows and an
+     * analysis's groups — is written with its formulas neutralized: a cell a
+     * spreadsheet could evaluate gets a leading apostrophe
+     * (`CsvOptions.neutralizeFormulas`, OWASP CSV Injection). On by default,
+     * and on wherever it is left out; `false` is the host's explicit opt-out,
+     * for files that never reach a spreadsheet.
+     */
+    exportNeutralizeFormulas: boolean;
+}
+export declare const DEFAULT_RUNTIME_LIMITS: Readonly<RuntimeLimits>;
+/**
+ * Longest timer delay a 32-bit millisecond counter holds. `maxRefreshInterval`
+ * stays well below it, so a long interval never collapses into a tight loop.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * The rung of a ladder nearest a page size, for a layout switch that moves
+ * a view from one ladder to the other (`RuntimeLimits.cardPageSizes`). A
+ * tie goes to the larger rung, so a switch never takes rows away where it
+ * could give one more; a size already on the ladder, or an empty ladder,
+ * leaves the size as it is.
+ */
+export declare function nearestPageSize(ladder: readonly number[], size: number): number;
+//# sourceMappingURL=limits.d.ts.map

package/dist/model/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/model/limits.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;;;OASG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,kBAAkB,EAAE,MAAM,CAAC;IAU3B;;;OAGG;IACH,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6EAA6E;IAC7E,eAAe,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,wBAAwB,EAAE,OAAO,CAAC;CACnC;AAED,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,aAAa,CAgCzD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,aAAgB,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,MAAM,GACX,MAAM,CAOR"}

package/dist/model/record.d.ts

@@ -0,0 +1,114 @@
+import { SummaryFunction } from './field.js';
+import { DataViewConfigBase } from './config.js';
+/** One row as returned by the business query source. */
+export type RecordData = Record<string, unknown>;
+/** The value of a row's `rowKey` field. */
+export type RecordKey = string | number;
+/** Sort direction as stored in a config: Wow's `SortDirection` values. */
+export type SortDirection = 'ASC' | 'DESC';
+export type RecordLayout = 'table' | 'card';
+/** Which paging protocol the source offers; declared by the definition. */
+export type PagingMode = 'paged' | 'cursor';
+/**
+ * Where to read from. The definition's paging mode decides which member is
+ * available, and a cursor of `null` asks for the first page.
+ */
+export type RecordPageTarget<P extends PagingMode = PagingMode> = P extends 'paged' ? {
+    index: number;
+} : {
+    cursor: string | null;
+};
+export interface RecordSort {
+    field: string;
+    direction: SortDirection;
+}
+/**
+ * Whether a stored column is held against the table's left edge. Anything
+ * but `true` lets it scroll with the rest.
+ *
+ * A pinning has one value and not a side (D19): the left is the only end a
+ * user pins to, and the right one is the action column's, which is the
+ * host's slot rather than anything a config can name. Configs arrive from a
+ * store, so `pinned` may be `'left'`, `'top'` or a number — read through
+ * here every one of them reads as "not pinned", and `validateRecord`
+ * reports the value separately so it is fixable rather than silent.
+ */
+export declare function columnPinned(value: unknown): boolean;
+/**
+ * Whether a stored column is switched off. Anything but `true` shows it —
+ * the same reading {@link columnPinned} gives the other flag.
+ *
+ * `hidden` is the newer member, so most configs do not carry it at all and
+ * a config from a store may carry anything under that name. Read through
+ * here, a config written before the member existed reads as all visible,
+ * which is what it always was.
+ */
+export declare function columnHidden(value: unknown): boolean;
+/**
+ * One column of the table layout.
+ *
+ * A column the user switched off keeps its entry — `hidden: true` — rather
+ * than leaving the list: the entry *is* its place in the order, so a column
+ * put back comes back where it was instead of at the end, and it can be
+ * dragged while it is off. `projectRecord` skips it, so it is not drawn, not
+ * exported, and not the column the table draws last (D13).
+ */
+export interface RecordColumn {
+    field: string;
+    width?: number;
+    /**
+     * Present, and only ever `true`, on a column held against the table's left
+     * edge (D19). Unpinning deletes the member rather than writing `false`,
+     * the way `hidden` does, so a column back where it started is the same
+     * JSON it started as — and the type says so, rather than admitting a
+     * `false` no writer here writes (B8). A stored one still reads as "not
+     * pinned" (`columnPinned`), because a config is untrusted data.
+     */
+    pinned?: true;
+    /** Present, and only ever `true`, on a column the table does not draw. */
+    hidden?: true;
+}
+export interface RecordSummary {
+    field: string;
+    fn: SummaryFunction;
+}
+export interface RecordTableSpec {
+    columns: RecordColumn[];
+}
+export interface RecordCardSpec {
+    /** Field shown as the card title. */
+    title: string;
+    /** Fields shown in the card body. */
+    fields: string[];
+    image?: string;
+    /**
+     * How many cards stand in one row. `perRow`, not `columns`: everywhere
+     * else in this package a column is a column of the table, and one word
+     * that meant two things was the review's B9 (2026-09-22).
+     */
+    perRow?: 1 | 2 | 3 | 4;
+}
+/**
+ * Both layouts are stored together, so switching between table and card keeps
+ * the other one's settings; `layout` only records the current choice.
+ */
+export interface RecordViewConfig extends DataViewConfigBase {
+    kind: 'record';
+    sort: RecordSort[];
+    pageSize: number;
+    summaries?: RecordSummary[];
+    layout: RecordLayout;
+    table: RecordTableSpec;
+    card: RecordCardSpec;
+}
+/**
+ * The record members that only draw the result, on top of the base's
+ * (`PRESENTATION_MEMBERS` in `config.ts` joins the two).
+ *
+ * Table or cards is one of them: both layouts draw the very same rows from
+ * the very same query, and both are stored side by side, so switching is
+ * complete the moment it is done. An analysis layout is *not* one — the
+ * kernel shapes a chart only for the layout that ran.
+ */
+export declare const RECORD_PRESENTATION_MEMBERS: readonly ["layout"];
+//# sourceMappingURL=record.d.ts.map

package/dist/model/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/model/record.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,2CAA2C;AAC3C,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC;AAE3C,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAE5C,2EAA2E;AAC3E,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAC5D,CAAC,SAAS,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,0EAA0E;IAC1E,MAAM,CAAC,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,eAAe,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,cAAc,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,qBAEgB,CAAC"}

package/dist/model/storeError.d.ts

@@ -0,0 +1,105 @@
+import { ViewInstance, ViewPreferences } from './instance.js';
+export type ViewStoreErrorCode = 
+/** The expected revision no longer matches. */
+'CONFLICT' | 'NOT_FOUND' | 'FORBIDDEN'
+/** Reached but refused; the payload is wrong. */
+ | 'INVALID'
+/**
+ * Not reached, or reached with an unknown outcome. `reachable` tells the
+ * two apart: the server answered with an error of its own.
+ */
+ | 'UNAVAILABLE'
+/**
+ * The backend has no view store at all — a server released before it —
+ * so no view can be read or written there, and none is "gone".
+ */
+ | 'UNSUPPORTED';
+export declare const VIEW_STORE_ERROR_CODES: readonly ViewStoreErrorCode[];
+/**
+ * The single failure type of the persistence port. A backend adapter maps its
+ * transport errors, HTTP status codes included, onto these six codes, and
+ * keeps what it mapped from: the error it caught as `cause`, the backend's
+ * own error code as `detail`.
+ *
+ * It lives in `model` rather than next to the port because both sides of the
+ * port speak it: a store raises it, and the runtime classifies a write outcome
+ * by it without depending on any store implementation.
+ */
+export declare class ViewStoreError extends Error {
+    readonly code: ViewStoreErrorCode;
+    /** The instance the server holds, when an instance write conflicted. */
+    readonly instance?: ViewInstance;
+    /** The preferences it holds, when a preference write conflicted. */
+    readonly preferences?: ViewPreferences;
+    /**
+     * With `UNAVAILABLE`: the browser's own storage would not keep the write
+     * (full, or turned off), so it never left the device and nothing was
+     * written. The outcome is known, not lost on the way, and the reader is
+     * told what to free rather than that the result never came back.
+     */
+    readonly storage?: true;
+    /**
+     * With `INVALID` from `changeAudience`: the shared dashboards that show
+     * the view and so keep it shared, by **title** as stored — a title
+     * written as a key stays one, said where it is shown (D2). The engine
+     * says the refusal in its own words around them
+     * (`view.changeAudience.invalid.shared-boards`); `message` stays the
+     * store's own, for logs.
+     */
+    readonly boards?: readonly string[];
+    /**
+     * With `UNAVAILABLE`: the server answered, with an error of its own (a
+     * 5xx, a timeout or a refusal it reported) — not the network. The reader
+     * is told the server could not handle it, with its reason, rather than
+     * that it could not be reached, and an operator looks at the server's log.
+     */
+    readonly reachable?: true;
+    /**
+     * The backend's own word for the failure, where it gave one — a Wow
+     * server's `errorCode` (`ViewAppRequired`, `ViewInvalid`, …) — so a host
+     * can tell apart what the port's code folds together. Diagnostics only:
+     * the engine decides by `code`.
+     */
+    readonly detail?: {
+        readonly code: string;
+    };
+    constructor(code: ViewStoreErrorCode, message: string, held?: ConflictingState & {
+        storage?: true;
+        boards?: readonly string[];
+        reachable?: true;
+        detail?: {
+            readonly code: string;
+        };
+        /** What the store caught, kept as the standard `Error.cause`. */
+        cause?: unknown;
+    });
+}
+/**
+ * What the server holds, said by which of the two it is.
+ *
+ * One member carrying either used to be enough to compile, and so the two
+ * were told apart by casting at each point of use: a preference conflict
+ * that arrived carrying an instance was read as preferences all the way to
+ * the screen. A store fills in the one its own write was about, and nothing
+ * downstream has to guess.
+ */
+export interface ConflictingState {
+    instance?: ViewInstance;
+    preferences?: ViewPreferences;
+}
+/**
+ * Structural, so an error raised by a second copy of this package, or by a
+ * store that builds the shape itself, is still recognised: an `Error` named
+ * `ViewStoreError` with one of the port's codes. The name is what keeps a
+ * stray `{ code: 'NOT_FOUND' }` from an HTTP library out. Every guard of
+ * the engine's errors reads them so (`isViewWriteError`,
+ * `isViewCommandError`, `isExportCancelledError`).
+ */
+export declare function isViewStoreError(error: unknown): error is ViewStoreError;
+/**
+ * Whether `error` is an error of this `name` — the rule every guard of the
+ * engine's errors keeps, rather than `instanceof`, which a second install of
+ * the package (or a bundle that inlined one) fails.
+ */
+export declare function isNamedError(error: unknown, name: string): boolean;
+//# sourceMappingURL=storeError.d.ts.map

package/dist/model/storeError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storeError.d.ts","sourceRoot":"","sources":["../../src/model/storeError.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEnE,MAAM,MAAM,kBAAkB;AAC5B,+CAA+C;AAC7C,UAAU,GACV,WAAW,GACX,WAAW;AACb,iDAAiD;GAC/C,SAAS;AACX;;;GAGG;GACD,aAAa;AACf;;;GAGG;GACD,aAAa,CAAC;AAElB,eAAO,MAAM,sBAAsB,EAAE,SAAS,kBAAkB,EAO/D,CAAC;AAEF;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,oEAAoE;IACpE,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;gBAG1C,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,gBAAgB,GAAG;QACvB,OAAO,CAAC,EAAE,IAAI,CAAC;QACf,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3B,SAAS,CAAC,EAAE,IAAI,CAAC;QACjB,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QACnC,iEAAiE;QACjE,KAAK,CAAC,EAAE,OAAO,CAAC;KACZ;CAeT;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAOxE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAMlE"}

package/dist/model/text.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Words written as keys (host-integration.md 3.1): a definition says
+ * `text('executionFailed.title')` where a language would say 「失败执行」, so
+ * one definition serves every language and a host's catalogue says them.
+ *
+ * A key travels as a string — every label slot of a definition, a system
+ * view and a board is a `string`, and stays one — between two characters no
+ * wording uses (U+E000 and U+E001, private use). The closing one lets a key
+ * be read where code has put it inside a longer string — a condition's
+ * summary, 「{field} · {element}」 — so it is said there too. A literal
+ * string is still a label, for a host of one language.
+ *
+ * A key is said at the leaf (D2, user 2026-09-28): the definitions, the
+ * stored configs, every runtime's state and snapshot, and what an editor
+ * takes and gives back keep their keys; only where text is shown or leaves
+ * the engine — a rendered label, a chart's option, an export, an accessible
+ * name, a title — is it said (`say`, and `useSay` in `/ui`), in the words
+ * of the Provider in force, else the ones the engine was built with
+ * (`ViewEngineOptions.text`). So one engine serves every language, and a
+ * change of language only redraws.
+ */
+/** A key standing where a label goes; a string, so it goes anywhere one does. */
+export type Text = string & {
+    readonly __text: unique symbol;
+};
+/** How a host says a key in the language in force; `undefined` for none. */
+export type TextResolver = (key: string) => string | undefined;
+/** The words keys are said in: a resolver, or a catalogue by key. */
+export type TextWords = TextResolver | Readonly<Record<string, string | undefined>>;
+/** The key `key`, to stand where a label goes. */
+export declare function text(key: string): Text;
+/** The key a label stands for, or `null` for a label that is words already. */
+export declare function textKeyOf(value: string): string | null;
+/**
+ * `value` with every key in it said by `resolve` — the whole string, or
+ * keys code has put inside a longer one. A key `resolve` has no words for
+ * is said as the key itself, and reported to `missing`. With `known`, only
+ * the keys it knows are keys: anything else between the marks is left as
+ * it came (a reader's title, a row's cell).
+ */
+export declare function sayKeys(value: string, resolve: TextResolver, missing?: (key: string) => void, known?: (key: string) => boolean): string;
+/**
+ * `value` with every key in it said in `words` (D2): what a label reads as
+ * where it is shown or leaves the engine. A key `words` lack reads as the
+ * key itself — visible, never a marker. The same string where it holds no
+ * key.
+ */
+export declare function say(value: string, words: TextWords): string;
+/** Every key written anywhere in `value`: what a definition says in words. */
+export declare function textKeysIn(value: unknown): Set<string>;
+/**
+ * `value` with every key in it said by `resolve`, and the same object where
+ * it holds none. A key `resolve` has no words for is said as the key itself
+ * — visible, rather than blank — and reported to `missing` with where it
+ * sits, so admission can say so.
+ */
+export declare function withText<T>(value: T, resolve: TextResolver, missing?: (key: string, path: readonly (string | number)[]) => void): T;
+//# sourceMappingURL=text.d.ts.map

package/dist/model/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/model/text.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,iFAAiF;AACjF,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,MAAM,CAAA;CAAE,CAAC;AAE/D,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAE/D,qEAAqE;AACrE,MAAM,MAAM,SAAS,GACnB,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAU9D,kDAAkD;AAClD,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEtC;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKtD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAe,EACzC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAC/B,MAAM,CASR;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAY3D;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAOtD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,IAAe,GAC5E,CAAC,CA6BH"}