@elaraai/east-ui 1.0.80 → 1.0.82

package/dist/src/contracts/source.d.ts

@@ -11,8 +11,9 @@
  * positional surface, a `Dict<String, Row>` for a keyed one (#568). east-ui
  * declares the shape; whoever can actually fetch windows produces a value of
  * it. `Data.bindPaged` in `@elaraai/e3-ui` is the production implementation
- * (dataset windows over an e3 workspace) and {@link Paged.of} is the in-memory
- * one; neither is named here, and **nothing in this file imports e3**.
+ * (dataset windows over an e3 workspace) and {@link Paged.of} /
+ * {@link Paged.pinned} are the in-memory ones; e3 is never named here, and
+ * **nothing in this file imports e3**.
  *
  * # Why a variant, not a narrow struct
  *
@@ -28,7 +29,7 @@
  *
  * @packageDocumentation
  */
-import { type EastType, type ExprType, type SubtypeExprOrValue, ArrayType, BooleanType, DictType, FunctionType, IntegerType, OptionType, StringType, StructType, VariantType } from "@elaraai/east";
+import { type EastType, type ExprType, type SubtypeExprOrValue, ArrayType, BooleanType, DictType, FunctionType, IntegerType, NullType, OptionType, StringType, StructType, VariantType } from "@elaraai/east";
 /**
  * Where a key query landed in a source's canonical row order.
  *
@@ -127,10 +128,10 @@ export type SeekQueryType = typeof SeekQueryType;
  *
  * Parameterised on the COLLECTION, not on the row: a window of an `Array<R>`
  * dataset is an `Array<R>`, a window of a `Dict<K, V>` dataset is a
- * `Dict<K, V>`, and the Plan's canvas windows are `Dict<String, PlanRow>`
- * (#568). That is what `Data.bindPaged` already produces — it returns
- * `Option<T>` at the dataset's own type — so the contract matches the producer
- * instead of narrowing it to arrays.
+ * `Dict<K, V>`, and the Plan's canvas windows are its blocks — one
+ * `Array<PlanRow>` stream per series (#823). That is what `Data.bindPaged`
+ * already produces — it returns `Option<T>` at the dataset's own type — so the
+ * contract matches the producer instead of narrowing it to arrays.
  *
  * `page` and `total` follow the in-flight-is-`none` convention: a window still
  * being fetched reads `none` and the call re-fires when it lands, so the reads
@@ -138,6 +139,28 @@ export type SeekQueryType = typeof SeekQueryType;
  * source is exhausted at that offset — a reader that walks offsets terminates
  * on an empty window, never on `none`.
  *
+ * A window may also hold FEWER than `limit` elements while the source still
+ * has more: a source that bounds its pages serves what fits. e3 trims every
+ * page of a dataset to a byte budget — the same number of elements on every
+ * page of one dataset — so wide elements come back in short windows (#829).
+ * Only an EMPTY window means exhausted. Components never see a short window:
+ * {@link buildRowSource}'s derived `page` re-requests whatever a trimmed page
+ * left out, so every window it serves is whole.
+ *
+ * A window that CANNOT be read — a failed fetch, a page that does not decode —
+ * makes `page` THROW its reason; it never reads `none`, which means in flight,
+ * and a reader waiting on it would wait forever (#811). A component shows the
+ * failure where that window's rows would be and asks again when the user
+ * retries. A source may rate-limit repeat attempts (e3 relaunches a failed
+ * window on a read at least two seconds later), and an authoring error — a
+ * dataset that cannot be paged — keeps throwing. `seek` follows the same rule.
+ *
+ * A paged source names no snapshot, so a component reads each of its windows
+ * once: the same `id` serves the same rows for as long as the component holds
+ * it. A source whose content moves under one id — a dataset the view follows,
+ * a source the view writes — is a {@link PinnedSourceType}, which names the
+ * snapshot its windows, total and searches belong to.
+ *
  * @typeParam C - The collection type one window carries.
  * @param c - The collection type value.
  * @returns The concrete `StructType` of a paged source over `c`.
@@ -148,11 +171,13 @@ export type SeekQueryType = typeof SeekQueryType;
  *   never re-renders when the source is swapped, and a window cache cannot key
  *   itself. Two sources with the same `id` must serve the same rows.
  * @property page - `(offset, limit)` → that window's elements as a value of the
- *   collection type; `none` while in flight, an EMPTY collection at exhaustion.
+ *   collection type; `none` while in flight, an EMPTY collection at exhaustion,
+ *   and possibly fewer than `limit` elements before it (see above). Throws when
+ *   the window cannot be read.
  * @property total - The source's total element count, once known; `none` until then.
  * @property seek - The source's key-search capability ({@link SeekType}) —
  *   `none` when the source is not key-ordered (an Array-backed source cannot
- *   seek; there is nothing to binary-search).
+ *   seek; there is nothing to binary-search). A search that fails throws.
  */
 export declare const PagedSourceType: <C extends EastType>(c: C) => StructType<{
     readonly id: StringType;
@@ -188,14 +213,83 @@ export declare const PagedSourceType: <C extends EastType>(c: C) => StructType<{
  * @typeParam C - The collection type one window carries.
  */
 export type PagedSource<C extends EastType> = ExprType<ReturnType<typeof PagedSourceType<C>>>;
+/**
+ * A {@link PagedSourceType} that names its SNAPSHOT — the contract a component
+ * follows through changes to the source's content, and the one it edits.
+ *
+ * @remarks
+ * Every window, the total and every search belong to one snapshot, the
+ * source's `revision`, so rows from two snapshots never sit side by side. When
+ * the revision moves — the data was written, `refresh` was asked for — a
+ * component reads its windows again at the new one, and the rows it had stand
+ * in until each lands: the view never empties between two snapshots of its
+ * data (#821). An edit is checked against the snapshot it was drafted on, and
+ * the drafts retire once the source reads back at the snapshot the write made
+ * (#880) — which is why the Sheet and the Plan edit a paged source only
+ * through this contract.
+ *
+ * `Data.bindPaged` in `@elaraai/e3-ui` returns one, its revision the dataset's
+ * content hash, and {@link Paged.pinned} is the in-memory one.
+ *
+ * @typeParam C - The collection type one window carries.
+ * @param c - The collection type value.
+ * @returns The concrete `StructType` of a pinned source over `c`.
+ *
+ * @property id - The logical source's identity, as {@link PagedSourceType}'s;
+ *   the rows it serves are its current revision's.
+ * @property page - As {@link PagedSourceType}'s, at the current revision.
+ * @property total - As {@link PagedSourceType}'s, at the current revision.
+ * @property seek - As {@link PagedSourceType}'s, at the current revision.
+ * @property revision - The snapshot the source serves; `none` while it is
+ *   being found. A reader re-fires when the source moves to another.
+ * @property refresh - Move the source: `some(hash)` to that snapshot — after a
+ *   write the view confirmed — or `none` to the one the source holds now.
+ */
+export declare const PinnedSourceType: <C extends EastType>(c: C) => StructType<{
+    readonly id: StringType;
+    readonly page: FunctionType<[IntegerType, IntegerType], OptionType<C>>;
+    readonly total: FunctionType<[], OptionType<IntegerType>>;
+    readonly seek: OptionType<FunctionType<[VariantType<{
+        readonly key: StringType;
+        readonly prefix: StringType;
+        readonly fields: StructType<{
+            readonly values: ArrayType<StringType>;
+            readonly prefix: OptionType<StringType>;
+        }>;
+        readonly range: StructType<{
+            readonly from: ArrayType<StringType>;
+            readonly to: ArrayType<StringType>;
+        }>;
+    }>], OptionType<StructType<{
+        readonly found: BooleanType;
+        readonly row: IntegerType;
+        readonly count: IntegerType;
+    }>>>>;
+    readonly revision: FunctionType<[], OptionType<StringType>>;
+    readonly refresh: FunctionType<[OptionType<StringType>], NullType>;
+}>;
+/**
+ * The TypeScript type of a {@link PinnedSourceType} over collection type `C` —
+ * the pinned sibling of {@link PagedSource}.
+ *
+ * @typeParam C - The collection type one window carries.
+ */
+export type PinnedSource<C extends EastType> = ExprType<ReturnType<typeof PinnedSourceType<C>>>;
 /**
  * How a component's rows arrive: inline, or from a windowed source.
  *
  * @remarks
- * Both arms speak the same COLLECTION type — inline is the whole of it, paged
- * is a window of it — so a component that keys its rows (the Plan's
- * `Dict<String, PlanRow>`) and one that positions them (`Array<Row>`) share one
- * vocabulary without either shape leaking into the arm names (#568).
+ * Every arm speaks the same COLLECTION type — inline is the whole of it, the
+ * windowed arms a window of it — so a keyed source (a Sheet's
+ * `Dict<String, Row>`), a positional one (a Table's `Array<Row>`) and a
+ * composite one (the Plan's blocks, one row stream per series) share one
+ * vocabulary without any shape leaking into the arm names (#568).
+ *
+ * The two windowed arms differ in one thing: whether the source names its
+ * snapshot. `paged` is the released arm — exported UIs carry it, so it never
+ * changes — and a component reads each of its windows once; `pinned` names the
+ * revision its windows belong to, which is what lets a component follow the
+ * source as its content changes, and edit it.
  *
  * @typeParam C - The collection type.
  * @param c - The collection type value.
@@ -203,31 +297,29 @@ export type PagedSource<C extends EastType> = ExprType<ReturnType<typeof PagedSo
  *
  * @property inline - The whole collection, already in hand.
  * @property paged - A {@link PagedSourceType} fetched a window at a time.
+ * @property pinned - A {@link PinnedSourceType} — windows at a named snapshot, followed from one to the next.
  */
-export declare const RowSourceType: <C extends EastType>(c: C) => VariantType<{
-    readonly inline: C;
-    readonly paged: StructType<{
-        readonly id: StringType;
-        readonly page: FunctionType<[IntegerType, IntegerType], OptionType<C>>;
-        readonly total: FunctionType<[], OptionType<IntegerType>>;
-        readonly seek: OptionType<FunctionType<[VariantType<{
-            readonly key: StringType;
-            readonly prefix: StringType;
-            readonly fields: StructType<{
-                readonly values: ArrayType<StringType>;
-                readonly prefix: OptionType<StringType>;
-            }>;
-            readonly range: StructType<{
-                readonly from: ArrayType<StringType>;
-                readonly to: ArrayType<StringType>;
-            }>;
-        }>], OptionType<StructType<{
-            readonly found: BooleanType;
-            readonly row: IntegerType;
-            readonly count: IntegerType;
-        }>>>>;
-    }>;
-}>;
+export declare const RowSourceType: <C extends EastType>(c: C) => RowSourceType<C>;
+/**
+ * The East type {@link RowSourceType} builds over collection type `C`, as a
+ * named interface.
+ *
+ * @remarks
+ * An interface is a symbol, so the declaration emitter names it wherever a
+ * component's type carries a row source, instead of writing the collection
+ * type out once per arm — which keeps `UIComponentType`'s declaration within
+ * the length TypeScript will serialize (TS7056; see `UIComponentNode`).
+ *
+ * @typeParam C - The collection type.
+ */
+export interface RowSourceType<C extends EastType> extends VariantType {
+    /** The arms, by name — {@link RowSourceType}'s three. */
+    readonly cases: {
+        readonly inline: C;
+        readonly paged: ReturnType<typeof PagedSourceType<C>>;
+        readonly pinned: ReturnType<typeof PinnedSourceType<C>>;
+    };
+}
 /**
  * The TypeScript type of a {@link RowSourceType} over collection type `C`.
  *
@@ -258,9 +350,14 @@ export type RowSourceInput<C extends EastType> = SubtypeExprOrValue<C> | PagedSo
  * element type recovered from it (an `Array`'s value, a `Set`'s key, a
  * `Dict`'s value), and its KEY type when it has one.
  *
- * `keyType` is what a keyed component checks: the Plan requires
- * `Dict<String, R>` because its canvas rows inherit the source's keys, so an
+ * `keyType` is what a keyed component checks: the Plan requires a `Dict`
+ * (any key type, #822) because a row's id starts with its entry's key, so an
  * unkeyed source is refused rather than silently re-keyed (#568).
+ *
+ * `pinned` says whether a windowed source names its snapshot — `revision` and
+ * `refresh`, as {@link PinnedSourceType} has them — and so builds the `pinned`
+ * arm: the one a component follows through changes to the source, and the
+ * only one the Sheet and the Plan edit.
  */
 export type ResolvedRowSource = {
     kind: "inline";
@@ -268,12 +365,14 @@ export type ResolvedRowSource = {
     collectionType: EastType;
     elementType: EastType;
     keyType: EastType | undefined;
+    live?: ExprType<StructType>;
 } | {
     kind: "paged";
     source: ExprType<StructType>;
     collectionType: EastType;
     elementType: EastType;
     keyType: EastType | undefined;
+    pinned: boolean;
 } | {
     kind: "ordered";
     source: ExprType<StructType>;
@@ -283,7 +382,13 @@ export type ResolvedRowSource = {
     keyType: EastType;
     /** The order key the window is sorted by, off the element's `ik`. */
     orderKeyType: EastType;
+    /** Whether the source names its snapshot — `revision` and `refresh`. */
+    pinned: boolean;
 };
+/** A resolved WINDOWED source — `paged`, or an `ordered` index window. */
+export type ResolvedWindowedSource = Extract<ResolvedRowSource, {
+    kind: "paged" | "ordered";
+}>;
 /**
  * Classify a component's rows prop at BUILD time — the one dispatch every
  * collection shares, so no component re-sniffs shapes of its own.
@@ -291,7 +396,9 @@ export type ResolvedRowSource = {
  * Accepted shapes, in order:
  * - a collection expression / value (`Array<R>`, `Dict<K, V>`, `Set<R>`) ⇒ `inline`;
  * - a struct carrying `page` + `total` ⇒ `paged` (a {@link PagedSourceType},
- *   or anything structurally matching it — `Data.bindPaged`'s handle);
+ *   or anything structurally matching it), marked `pinned` when it also
+ *   carries `revision` + `refresh` (a {@link PinnedSourceType} —
+ *   `Data.bindPaged`'s handle, `Paged.pinned`);
  * - a struct carrying `read` ⇒ a whole-value bind handle, which resolves by
  *   CALLING `read()` and recursing. The call becomes part of the surrounding
  *   East expression, so it is evaluated inside the component's reactive render
@@ -300,7 +407,7 @@ export type ResolvedRowSource = {
  *
  * @param data - The rows prop as the author passed it
  * @param label - Component name for the error message (`"Plan"`, `"Table"`)
- * @returns The resolved arm — see {@link ResolvedRowSource}
+ * @returns The resolved arm, retaining a live handle for invocation-time reads — see {@link ResolvedRowSource}
  * @throws Error when the expression is none of the accepted shapes
  */
 export declare function resolveRowSource(data: unknown, label: string): ResolvedRowSource;
@@ -320,26 +427,55 @@ export declare function resolveRowSource(data: unknown, label: string): Resolved
  * component's rows inherit the source's keys, and flattening at the boundary
  * would throw away exactly what makes a window's rows addressable (#568). A
  * positional component (Table) receives its `Array<Row>`; a keyed one (Plan) a
- * `Dict<String, R>`.
+ * `Dict<K, R>`.
  *
  * @typeParam Out - The component's own row COLLECTION type.
  * @param resolved - The output of {@link resolveRowSource}
  * @param outType - The component's row collection type
  * @param make - The source collection → the component's row collection
- * @param idSuffix - Appended to the paged source's `id` — see below
  * @returns The `RowSourceType(outType)` value to store in the IR
  *
  * @remarks
- * `idSuffix` exists because `make` is part of what the derived source SERVES.
- * {@link PagedSourceType} requires that two sources sharing an `id` serve the
- * same rows, and a component whose `make` changes — a Plan whose series list was
- * narrowed by a pick — now serves different rows from the same underlying
- * handle. Since a window cache keys on `id` alone and resident windows are never
- * re-read, an unsigned id leaves the previous rows on screen forever. A
- * component that can vary its `make` must pass a signature of what varied.
+ * The derived source keeps the handle's `id`: `make` is part of what it
+ * serves, and a component whose `make` changes (a Plan whose series list a
+ * pick narrowed) serves other rows from the same handle — which a renderer
+ * tells apart by comparing the derived source whole, closures included
+ * (`equivalentFor`, #809), not by its id (#822).
+ *
+ * The derived `page` serves WHOLE windows (#829). A handle may answer
+ * `(offset, limit)` with fewer than `limit` elements while it still has more —
+ * e3 trims every page to a byte budget — and every component addresses its
+ * windows at `w × size`, so a short window would silently drop its tail. The
+ * derived `page` therefore re-requests `(offset + served, limit − served)`
+ * until the window holds `limit` elements, the source is exhausted (an empty
+ * piece, or `offset + served` reaching a known `total()`), or a piece is still
+ * in flight — in which case the whole window reads `none` and re-fires when the
+ * piece lands. The pieces join in the collection's own order (arrays
+ * concatenate; dicts and sets union, their pieces being disjoint and ascending)
+ * and `make` runs once over the whole window. Each piece stays its own request,
+ * so a runtime caches them at the size the source chose to serve.
+ *
+ * A source that names its snapshot (`resolved.pinned`, a
+ * {@link PinnedSourceType}) builds the `pinned` arm, its `revision` and
+ * `refresh` carried through as they are; any other builds `paged`, which has
+ * neither. The derived `page` is the same either way.
  */
-export declare function buildRowSource<Out extends EastType>(resolved: ResolvedRowSource, outType: Out, make: (collection: ExprType<EastType>) => SubtypeExprOrValue<Out>, idSuffix?: SubtypeExprOrValue<StringType>): RowSource<Out>;
-/** Options for the ARRAY form of {@link Paged.of}. */
+export declare function buildRowSource<Out extends EastType>(resolved: ResolvedRowSource, outType: Out, make: (collection: ExprType<EastType>) => SubtypeExprOrValue<Out>): RowSource<Out>;
+/**
+ * The WHOLE window `(offset, limit)` of a paged source's own collection — the
+ * pieces a trimmed page left out asked for until the window holds `limit`
+ * elements, the source is exhausted, or a piece is in flight (the window then
+ * reads `none`, #829). What {@link buildRowSource}'s derived `page` maps its
+ * `make` over; a caller that must read the very windows a component reads —
+ * the Plan's editing reads its entries back (#880) — asks for them here, so
+ * each piece is the same request the component made.
+ *
+ * @param resolved - A resolved paged source ({@link resolveRowSource})
+ * @returns `(offset, limit)` → the window, `none` while a piece is in flight
+ */
+export declare function buildPagedWindow(resolved: ResolvedWindowedSource): ExprType<FunctionType<[IntegerType, IntegerType], OptionType<EastType>>>;
+/** Options for {@link Paged.of} — `key` applies to the ARRAY form only,
+ *  `pageLimit` to both. */
 export interface PagedOfOptions<R extends EastType> {
     /**
      * Key accessor. Supplying it declares the rows are SORTED by that key and
@@ -351,6 +487,17 @@ export interface PagedOfOptions<R extends EastType> {
      * are the row order and the search space.
      */
     key?: (row: ExprType<R>) => SubtypeExprOrValue<StringType>;
+    /**
+     * Serve at most this many elements per window, whatever `limit` asks — the
+     * in-memory twin of a source that bounds its pages (e3 trims every page to
+     * a byte budget, so wide elements come back in short windows, #829).
+     *
+     * A component never sees the trim: `buildRowSource` re-requests what a
+     * short window left out, so every window it serves is whole. Set it to
+     * exercise that path in examples and tests. Must be a positive integer;
+     * omit it and a window is exactly what `limit` asks (clamped at the end).
+     */
+    pageLimit?: number;
 }
 /**
  * Build an in-memory {@link PagedSourceType} over a collection already in hand
@@ -362,17 +509,26 @@ export interface PagedOfOptions<R extends EastType> {
  * whole paged path — windowing, exhaustion on `some([])`, totals, seek — with
  * no server, no platform function and no bind. `@elaraai/e3-ui`'s
  * `Data.bindPaged` is the same contract backed by real dataset windows.
+ * `pageLimit` adds the one thing a real server does that an in-memory source
+ * would not: short windows, as e3 serves wide elements under its byte budget.
  *
  * Windows follow the collection: an `Array` source serves array windows in
  * stream order, a `Dict` source serves DICT windows in canonical key order —
  * the same shape and the same order a keyed dataset's windows arrive in, which
  * is what a keyed component (the Plan) requires of its source (#568).
  *
+ * The source captures an immutable copy of the collection when it is created,
+ * so no window drifts with the input: changed content is a new source, under a
+ * new id. A view that edits its source, or follows it from one snapshot to the
+ * next, takes {@link Paged.pinned}.
+ *
  * @typeParam R - The row type (array form) / the value type (dict form).
  * @param id - Comparable identity for this source (see {@link PagedSourceType}).
  * @param collection - The whole collection — an `Array<R>` or a `Dict<String, R>`.
- * @param options - {@link PagedOfOptions} — array form only; supply `key` to enable `seek`.
+ * @param options - {@link PagedOfOptions} — `key` (array form only) enables `seek`;
+ *   `pageLimit` trims every window, as a server bounding its pages does.
  * @returns A `PagedSourceType` at the collection it was given.
+ * @throws {Error} When `pageLimit` is not a positive integer.
  *
  * @example
  * ```tsx
@@ -387,9 +543,40 @@ export interface PagedOfOptions<R extends EastType> {
  * ```
  */
 declare function createPagedOf<R extends EastType>(id: SubtypeExprOrValue<StringType>, rows: SubtypeExprOrValue<ArrayType<R>>, options?: PagedOfOptions<R>): PagedSource<ArrayType<R>>;
-declare function createPagedOf<V extends EastType>(id: SubtypeExprOrValue<StringType>, entries: SubtypeExprOrValue<DictType<StringType, V>>): PagedSource<DictType<StringType, V>>;
+declare function createPagedOf<V extends EastType>(id: SubtypeExprOrValue<StringType>, entries: SubtypeExprOrValue<DictType<StringType, V>>, options?: Pick<PagedOfOptions<V>, "pageLimit">): PagedSource<DictType<StringType, V>>;
+/**
+ * Build an in-memory {@link PinnedSourceType} — {@link Paged.of} naming its
+ * snapshot, for a fixture a view edits or follows.
+ *
+ * @remarks
+ * The snapshot is the id, for good: `revision()` reads `some(id)`, a `refresh`
+ * to `none` or to the id keeps it, and a refresh to any other snapshot throws —
+ * an in-memory source cannot move, so a write it is told about is one it never
+ * saw. Everything else is {@link Paged.of}'s: the captured copy, the windows,
+ * the total, `seek` and `pageLimit`.
+ *
+ * @typeParam R - The row type (array form) / the value type (dict form).
+ * @param id - The source's identity, and its one snapshot.
+ * @param collection - The whole collection — an `Array<R>` or a `Dict<String, R>`.
+ * @param options - {@link PagedOfOptions}, as {@link Paged.of} takes them.
+ * @returns A `PinnedSourceType` at the collection it was given.
+ * @throws {Error} When `pageLimit` is not a positive integer.
+ *
+ * @example
+ * ```tsx
+ * const rows = $.const([{ id: "r1", quantity: 2.0 }], ArrayType(OrderRow));
+ * const source = $.let(Paged.pinned("orders:fixture-1", rows));
+ * // A dataset handle's lifecycle, over one snapshot that never moves.
+ * $(source.refresh(none));
+ * $(source.refresh(some("orders:fixture-1")));
+ * return <Text>{East.str`Snapshot: ${source.revision().unwrap("some")}`}</Text>;
+ * ```
+ */
+declare function createPagedPinned<R extends EastType>(id: SubtypeExprOrValue<StringType>, rows: SubtypeExprOrValue<ArrayType<R>>, options?: PagedOfOptions<R>): PinnedSource<ArrayType<R>>;
+declare function createPagedPinned<V extends EastType>(id: SubtypeExprOrValue<StringType>, entries: SubtypeExprOrValue<DictType<StringType, V>>, options?: Pick<PagedOfOptions<V>, "pageLimit">): PinnedSource<DictType<StringType, V>>;
 /**
- * The `Paged` namespace — building a {@link PagedSourceType} without a server.
+ * The `Paged` namespace — building a {@link PagedSourceType} or a
+ * {@link PinnedSourceType} without a server.
  *
  * @remarks
  * The contract itself is what components consume; this namespace is the
@@ -399,6 +586,8 @@ declare function createPagedOf<V extends EastType>(id: SubtypeExprOrValue<String
 export declare const Paged: {
     /** Build an in-memory paged source over a collection already in hand. */
     readonly of: typeof createPagedOf;
+    /** Build an in-memory PINNED source — `of`, naming its one snapshot, for a fixture a view edits or follows. */
+    readonly pinned: typeof createPagedPinned;
     /** East types — the contract, for `$.const` / `$.let` annotations. */
     readonly Types: {
         /** A windowed row source over a collection type. */
@@ -423,6 +612,30 @@ export declare const Paged: {
                 readonly count: IntegerType;
             }>>>>;
         }>;
+        /** A windowed row source that names its snapshot, over a collection type. */
+        readonly PinnedSource: <C extends EastType>(c: C) => StructType<{
+            readonly id: StringType;
+            readonly page: FunctionType<[IntegerType, IntegerType], OptionType<C>>;
+            readonly total: FunctionType<[], OptionType<IntegerType>>;
+            readonly seek: OptionType<FunctionType<[VariantType<{
+                readonly key: StringType;
+                readonly prefix: StringType;
+                readonly fields: StructType<{
+                    readonly values: ArrayType<StringType>;
+                    readonly prefix: OptionType<StringType>;
+                }>;
+                readonly range: StructType<{
+                    readonly from: ArrayType<StringType>;
+                    readonly to: ArrayType<StringType>;
+                }>;
+            }>], OptionType<StructType<{
+                readonly found: BooleanType;
+                readonly row: IntegerType;
+                readonly count: IntegerType;
+            }>>>>;
+            readonly revision: FunctionType<[], OptionType<StringType>>;
+            readonly refresh: FunctionType<[OptionType<StringType>], NullType>;
+        }>;
         /** Where a key query landed in a source's row order. */
         readonly SeekRange: StructType<{
             readonly found: BooleanType;
@@ -442,31 +655,8 @@ export declare const Paged: {
                 readonly to: ArrayType<StringType>;
             }>;
         }>;
-        /** How a component's rows arrive (inline / paged), at a collection type. */
-        readonly RowSource: <C extends EastType>(c: C) => VariantType<{
-            readonly inline: C;
-            readonly paged: StructType<{
-                readonly id: StringType;
-                readonly page: FunctionType<[IntegerType, IntegerType], OptionType<C>>;
-                readonly total: FunctionType<[], OptionType<IntegerType>>;
-                readonly seek: OptionType<FunctionType<[VariantType<{
-                    readonly key: StringType;
-                    readonly prefix: StringType;
-                    readonly fields: StructType<{
-                        readonly values: ArrayType<StringType>;
-                        readonly prefix: OptionType<StringType>;
-                    }>;
-                    readonly range: StructType<{
-                        readonly from: ArrayType<StringType>;
-                        readonly to: ArrayType<StringType>;
-                    }>;
-                }>], OptionType<StructType<{
-                    readonly found: BooleanType;
-                    readonly row: IntegerType;
-                    readonly count: IntegerType;
-                }>>>>;
-            }>;
-        }>;
+        /** How a component's rows arrive (inline / paged / pinned), at a collection type. */
+        readonly RowSource: <C extends EastType>(c: C) => RowSourceType<C>;
     };
 };
 export {};

package/dist/src/contracts/source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/contracts/source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/contracts/source.ts"],"names":[],"mappings":"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"}