gesso-framework 0.6.30 → 0.8.0

package/dist/{FunctionComponent-CHtojpp7.d.ts → FunctionComponent-BDVrANP0.d.ts}

@@ -1,93 +1,249 @@
-import { f as ChannelToken, o as Patch, r as ChannelPort } from "./ChannelProtocol-ByNoHujM.js";
 import { BehaviorSubject, Observable, Subject, Subscription } from "rxjs";
-import { LayoutBox, Reactive, UiChild, UiModifier } from "gesso-core";
-//#region src/Component.d.ts
+import { LayoutBox, Reactive, UiChild, UiEnvironmentKey, UiModifier } from "gesso-core";
+//#region src/channel/ChannelToken.d.ts
 /**
- * Base class for all Gesso framework components.
- *
- * Components are class-based. They declare reactive state with
- * an `internalState()` cell, inputs with `@Input()`, and return a UiElement tree
- * from `render()`. The framework calls `render()` once per mount;
- * after that, observable emissions in the returned tree drive updates.
+ * The barrier between the application and the view, declared once.
+ *
+ * A token is a name, a shape and an initial value — and no
+ * implementation at all. Both threads import it, which is the point:
+ * the module holding it has nothing in it to bundle, so an app's api
+ * client and domain logic never reach the render worker the way a
+ * shared `Store` class dragged them there.
+ *
+ * What the framework knows about a channel ends here. It diffs plain
+ * data and ships patches; where the observables came from — a single
+ * subject, or an api → repository → domain → view-model stack — is the
+ * application's business and the framework cannot tell the difference.
+ *
+ *   export interface CatalogView {
+ *     products: ProductRow[];
+ *     status: 'loading' | 'ready' | 'error';
+ *   }
+ *   export interface CatalogCommands {
+ *     addToCart(id: string): void;
+ *   }
+ *   export const Catalog = channel<CatalogView, CatalogCommands>('catalog', {
+ *     products: [],
+ *     status: 'loading'
+ *   });
  */
-declare abstract class Component {
+/**
+ * A command a component can send back across the barrier.
+ *
+ * The arguments are what cross: each is structured-cloned onto the
+ * owning thread, so they must be plain data. There may be as many as
+ * the command needs, which is why `move(from, to)` is written the way
+ * anyone would write it rather than as `move({ from, to })`; a command
+ * used to carry one payload and the second argument was dropped on the
+ * floor with a warning.
+ *
+ * Commands return nothing: the effect comes back as a patch, never as
+ * a return value, since there is no synchronous answer to be had
+ * across a thread.
+ */
+type Command = (...args: never[]) => void;
+/**
+ * The internal view of a command set: a bag of callables by name.
+ *
+ * Public signatures constrain to `object`, not to this. An application
+ * declares its commands as an ordinary interface —
+ * `interface CatalogCommands { addToCart(id: string): void }` — and an
+ * interface has no index signature, so it does not satisfy a
+ * `Record<string, …>` constraint however well it fits in spirit.
+ * Constraining to `object` accepts what people actually write; this
+ * alias is what the implementation casts to when it looks a command up
+ * by name.
+ */
+type CommandMap = Record<string, Command>;
+/** The declared barrier for one area of an application. */
+interface ChannelToken<View extends object, Commands extends object = Record<string, never>> {
+  readonly name: string;
   /**
-   * Called once after the component's UiNode subtree has been created
-   * and all observable bindings are connected.
+   * What every view key holds before the first patch arrives.
+   *
+   * Required rather than optional, so the render thread never observes
+   * `undefined` for a declared key. A channel that is genuinely still
+   * loading says so in its own shape — a `status` field — rather than
+   * leaving the view to infer it from an absence.
    */
-  onMount?(): void;
+  readonly initial: View;
+  /** Phantom, carrying the command types to `send`. Never read. */
+  readonly commands?: Commands;
+}
+/**
+ * Declares a channel.
+ *
+ * The name identifies it across the thread boundary and must be
+ * stable; unlike a class name it survives minification, which is why
+ * it is written out rather than derived.
+ */
+declare function channel<View extends object, Commands extends object = Record<string, never>>(name: string, initial: View): ChannelToken<View, Commands>;
+/** A channel written as one object: the view with its values, and the commands. */
+interface ChannelSpec<View extends object, Commands extends object> {
   /**
-   * Called once when the component is being removed from the graph.
+   * Every view key with the value it holds before the first patch.
+   *
+   * The type of the channel's view is the type of this object, so the
+   * keys and their initial values are written once instead of in an
+   * interface and again in a literal that has to agree with it.
    */
-  onUnmount?(): void;
+  readonly view: View;
   /**
-   * Returns the component's UI definition.
+   * The commands, as a type rather than as implementations.
    *
-   * Called exactly once per component instance. Dynamic content is
-   * expressed through Observable props and children, never by
-   * re-invoking render().
-   *
-   * Returning an Observable is allowed for structural changes that
-   * cannot be expressed as observable children (routing, for example).
-   * The framework reconciles the component's root on each emission.
+   * Written `{} as { addToCart(id: string, quantity: number): void }`:
+   * the handlers live on the thread that owns the data and are passed
+   * to `provide`, so what belongs in the token is only their shape.
    */
-  abstract render(): UiChild;
+  readonly commands?: Commands;
 }
-//#endregion
-//#region src/InternalState.d.ts
 /**
- * A component's own state: originated here, and never crossing the
- * barrier.
- *
- * The writable counterpart to `InputCell`. The two are the same
- * `BehaviorSubject` and differ by one accessor — this one has a
- * `.value` setter — and that difference is the whole semantics:
- *
- *     internalState()   never crosses    I write it
- *     input()           crosses inward   someone else writes it
+ * Declares a channel from one object.
+ *
+ *   export const Catalog = defineChannel('catalog', {
+ *     view: {
+ *       products: [] as readonly ProductRow[],
+ *       status: 'loading' as ShelfStatus
+ *     },
+ *     commands: {} as {
+ *       addToCart(id: string, quantity: number): void;
+ *       move(from: number, to: number): void;
+ *     }
+ *   });
+ *
+ *   export type CatalogView = ViewOf<typeof Catalog>;
+ *
+ * The same token `channel()` returns, declared once instead of three
+ * times. `channel<View, Commands>(name, initial)` wrote the view as an
+ * interface, then as an initial literal that had to agree with it, and
+ * a key added to one and forgotten in the other was a type error in a
+ * third file. Here the object is the type.
+ *
+ * A field whose initial value is narrower than the type it holds is
+ * given the type it holds: `[]` is `never[]` and `'loading'` is
+ * `string` unless it is said, which is what the `as` clauses above are
+ * for. `ViewOf` and `CommandsOf` name the resulting types wherever the
+ * application used to name its own interface.
+ *
+ * `channel()` is not deprecated and keeps working exactly as it did.
+ * An application with interfaces it wants to keep, because they are
+ * shared with something else or because the initial values are built
+ * elsewhere, has nothing to migrate.
+ */
+declare function defineChannel<View extends object, Commands extends object = Record<string, never>>(name: string, spec: ChannelSpec<View, Commands>): ChannelToken<View, Commands>;
+/** The view type of a channel token, for an application that wants to name it. */
+type ViewOf<T> = T extends ChannelToken<infer View, object> ? View : never;
+/** The command type of a channel token. */
+type CommandsOf<T> = T extends ChannelToken<object, infer Commands> ? Commands : never;
+/**
+ * The keys a channel publishes.
  *
- * Named on that axis deliberately. It used to be `state()`, which
- * described *what* a thing was while `input()` described *where it
- * came from*; two names on two axes made neither of them tell you
- * anything about the other. `internalState(products)` reads as a
- * mistake at the call site in a way `state(products)` never did.
+ * Structural in its parameter rather than generic over the token, so
+ * it does not have to agree with any particular command type to read
+ * what is only ever the initial value's shape.
+ */
+declare function viewKeys(token: {
+  initial: object;
+}): string[];
+//#endregion
+//#region src/channel/StorePatch.d.ts
+type PatchPath = readonly (string | number)[];
+/**
+ * A change to one projection, as sent from a data worker to a replica.
  *
- * For values that originate on this thread and die with the component:
- * a tooltip's open flag, a caret, a scroll offset, the active tab.
- * Anything that survives a reload, or that another screen cares about,
- * is application state and belongs on a channel. Anything derived from
- * other cells is a `computed`.
+ * Paths are relative to the projection's root value, so a patch is
+ * self-contained: the replica never needs the previous value to apply
+ * one, only the value it already holds.
+ */
+type Patch = {
+  op: 'set';
+  projection: string;
+  path: PatchPath;
+  value: unknown;
+} | {
+  op: 'delete';
+  projection: string;
+  path: PatchPath;
+} | {
+  op: 'splice';
+  projection: string;
+  path: PatchPath;
+  index: number;
+  deleteCount: number;
+  items: readonly unknown[];
+};
+/**
+ * Describes how to turn `previous` into `current` for one projection.
  *
- * It is not only for components. The thread that owns a channel's data
- * writes cells too, and wrote them as a `BehaviorSubject` mirrored
- * into an `asObservable()` because this was reachable only through the
- * framework's main entry. `gesso-framework/worker` is the same cell
- * with none of the renderer behind it, so an application worker holds
- * one cell rather than a subject and a copy of it, and reads it with
- * `.value` in a `computed` rather than listing it in a
- * `combineLatest`. "Internal" still means what it says there: written
- * here, and crossing the barrier only as the plain data a view key
- * publishes.
+ * Returns an empty list when nothing changed, which is the common case
+ * and the reason this exists: the point of a projection is that most
+ * state changes do not alter it, and the ones that do usually alter a
+ * small part.
  */
-declare class InternalState<T> extends BehaviorSubject<T> {
-  /** What to call this cell in a warning or the inspector; optional. */
-  label: string | undefined;
-  constructor(initialValue: T);
-  get value(): T;
-  set value(next: T);
+declare function diffProjection(projection: string, previous: unknown, current: unknown): Patch[];
+/**
+ * Applies patches to a projection value, sharing structure with the
+ * original everywhere the patch did not reach.
+ *
+ * Nothing handed in is mutated: bindings hold onto emitted values, so a
+ * replica that edited in place would change data a component already
+ * rendered.
+ *
+ * **Each container on a patched path is copied once per batch, not once
+ * per patch.** A batch of N patches into one K-key object used to cost
+ * N × K: every patch spread the whole object again to change one key.
+ * A snapshot keyed by id is exactly that shape — gessologic published
+ * `Record<netId, 0 | 1>` for ten thousand nets, about nine hundred
+ * patches a publish, and the render worker's patch phase fell minutes
+ * behind a 60 Hz stream it could never catch. So the batch remembers
+ * the containers it has copied, and writes into those in place: they
+ * are its own, made during this call and seen by nobody yet. Values
+ * that arrived inside a patch are never written into, because they are
+ * the patch's — a devtools log replays the same patch objects again.
+ */
+declare function applyPatches(root: unknown, patches: readonly Patch[]): unknown;
+declare function applyPatch(root: unknown, patch: Patch): unknown;
+//#endregion
+//#region src/channel/ChannelProtocol.d.ts
+/**
+ * A two-way channel endpoint. `MessagePort` satisfies it, as does a
+ * test double, so nothing in the channel layer depends on Worker.
+ */
+interface ChannelPort {
+  postMessage(message: unknown): void;
+  onmessage: ((event: {
+    data: unknown;
+  }) => void) | null;
 }
 /**
- * Creates a reactive state cell.
- *
- * Usage inside a component:
- *
- *   private readonly count = state(0);
- *
- *   increment() {
- *     this.count.value++;
- *   }
+ * Render thread → the thread that owns the channel.
+ *
+ * A command's first argument stayed `payload` when commands learned to
+ * take more than one, and the rest travel beside it. That is not
+ * tidiness: an older view talking to a newer application worker sends
+ * no `rest`, which reads as the one-argument call it is, and an older
+ * application worker ignores the field, which is exactly what it did
+ * before the field existed.
  */
-declare function internalState<T>(initialValue: T, label?: string): InternalState<T>;
+type ChannelClientMessage = {
+  type: 'channel:sync';
+} | {
+  type: 'channel:command';
+  command: string;
+  payload: unknown;
+  rest?: unknown[];
+};
+/** The owning thread → render thread. */
+type ChannelHostMessage = {
+  type: 'channel:patch';
+  patches: Patch[];
+} | {
+  type: 'channel:error';
+  message: string;
+  stack?: string;
+};
+declare function isChannelClientMessage(value: unknown): value is ChannelClientMessage;
+declare function isChannelHostMessage(value: unknown): value is ChannelHostMessage;
 //#endregion
 //#region src/Input.d.ts
 /**
@@ -220,48 +376,6 @@ declare function into<V>(target: {
 }): OutputTarget<V>;
 declare function isOutputTarget(value: unknown): value is OutputTarget<unknown>;
 //#endregion
-//#region src/bounds.d.ts
-/**
- * A node's box, as a cell.
- *
- * `ctx.bounds()` hands one out and the modifier on it fills it, so the
- * arithmetic a pointer position needs starts from a value rather than
- * from `new BehaviorSubject<LayoutBox>({ x: 0, y: 0, width: 0, height: 0 })`
- * and a `measure(subject)` beside it. It is an ordinary cell: read it
- * with `.value` in a handler, bind it, or derive from it.
- *
- *   const track = ctx.bounds();
- *   <box modifiers={[track.modifier]} onPointerMove={e => at(e.x - track.value.x)} />
- *
- * **It reports a move, and only a move.** `measure` is built on
- * `LayoutNotifier`, which fires for every layout fact a node's listeners
- * could care about, and one of those is a scroll offset that changed
- * while the box stayed exactly where it was. A
- * cell that emitted for those would wake everything derived from it on
- * every frame of every scroll, for a box that did not move, which is
- * the defect this exists to avoid. So an equal box is dropped here,
- * where the comparison is four numbers, rather than by a
- * `distinctUntilChanged` at each of the places that read it.
- *
- * There is no `ctx.bounds(ref)`. A box is reported by a modifier, which
- * is how a node is reached from outside the layout engine everywhere
- * else in this framework, and a ref would be a second way of naming the
- * same node with nothing else built on it.
- */
-declare class BoundsCell extends InternalState<LayoutBox> {
-  /** Put this on the element whose box the cell should hold. */
-  readonly modifier: UiModifier<Subject<LayoutBox>>;
-  constructor();
-  /** Writes a box, unless it is the one already held. */
-  next(box: LayoutBox): void;
-}
-/**
- * A bounds cell outside a component, for a class component or a test.
- * Inside a function component `ctx.bounds()` is the same thing, and it
- * completes with the component.
- */
-declare function bounds(label?: string): BoundsCell;
-//#endregion
 //#region src/channel/ChannelReplica.d.ts
 /**
  * The render thread's end of a channel.
@@ -326,6 +440,136 @@ declare class ChannelReplica<View extends object, Commands extends object> {
   dispose(): void;
 }
 //#endregion
+//#region src/InternalState.d.ts
+/**
+ * A component's own state: originated here, and never crossing the
+ * barrier.
+ *
+ * The writable counterpart to `InputCell`. The two are the same
+ * `BehaviorSubject` and differ by one accessor — this one has a
+ * `.value` setter — and that difference is the whole semantics:
+ *
+ *     internalState()   never crosses    I write it
+ *     input()           crosses inward   someone else writes it
+ *
+ * Named on that axis deliberately. It used to be `state()`, which
+ * described *what* a thing was while `input()` described *where it
+ * came from*; two names on two axes made neither of them tell you
+ * anything about the other. `internalState(products)` reads as a
+ * mistake at the call site in a way `state(products)` never did.
+ *
+ * For values that originate on this thread and die with the component:
+ * a tooltip's open flag, a caret, a scroll offset, the active tab.
+ * Anything that survives a reload, or that another screen cares about,
+ * is application state and belongs on a channel. Anything derived from
+ * other cells is a `computed`.
+ *
+ * It is not only for components. The thread that owns a channel's data
+ * writes cells too, and wrote them as a `BehaviorSubject` mirrored
+ * into an `asObservable()` because this was reachable only through the
+ * framework's main entry. `gesso-framework/worker` is the same cell
+ * with none of the renderer behind it, so an application worker holds
+ * one cell rather than a subject and a copy of it, and reads it with
+ * `.value` in a `computed` rather than listing it in a
+ * `combineLatest`. "Internal" still means what it says there: written
+ * here, and crossing the barrier only as the plain data a view key
+ * publishes.
+ */
+declare class InternalState<T> extends BehaviorSubject<T> {
+  /** What to call this cell in a warning or the inspector; optional. */
+  label: string | undefined;
+  constructor(initialValue: T);
+  get value(): T;
+  set value(next: T);
+}
+/**
+ * Creates a reactive state cell.
+ *
+ * Usage inside a component:
+ *
+ *   private readonly count = state(0);
+ *
+ *   increment() {
+ *     this.count.value++;
+ *   }
+ */
+declare function internalState<T>(initialValue: T, label?: string): InternalState<T>;
+//#endregion
+//#region src/bounds.d.ts
+/**
+ * A node's box, as a cell.
+ *
+ * `ctx.bounds()` hands one out and the modifier on it fills it, so the
+ * arithmetic a pointer position needs starts from a value rather than
+ * from `new BehaviorSubject<LayoutBox>({ x: 0, y: 0, width: 0, height: 0 })`
+ * and a `measure(subject)` beside it. It is an ordinary cell: read it
+ * with `.value` in a handler, bind it, or derive from it.
+ *
+ *   const track = ctx.bounds();
+ *   <box modifiers={[track.modifier]} onPointerMove={e => at(e.x - track.value.x)} />
+ *
+ * **It reports a move, and only a move.** `measure` is built on
+ * `LayoutNotifier`, which fires for every layout fact a node's listeners
+ * could care about, and one of those is a scroll offset that changed
+ * while the box stayed exactly where it was. A
+ * cell that emitted for those would wake everything derived from it on
+ * every frame of every scroll, for a box that did not move, which is
+ * the defect this exists to avoid. So an equal box is dropped here,
+ * where the comparison is four numbers, rather than by a
+ * `distinctUntilChanged` at each of the places that read it.
+ *
+ * There is no `ctx.bounds(ref)`. A box is reported by a modifier, which
+ * is how a node is reached from outside the layout engine everywhere
+ * else in this framework, and a ref would be a second way of naming the
+ * same node with nothing else built on it.
+ */
+declare class BoundsCell extends InternalState<LayoutBox> {
+  /** Put this on the element whose box the cell should hold. */
+  readonly modifier: UiModifier<Subject<LayoutBox>>;
+  constructor();
+  /** Writes a box, unless it is the one already held. */
+  next(box: LayoutBox): void;
+}
+/**
+ * A bounds cell outside a component, for a class component or a test.
+ * Inside a function component `ctx.bounds()` is the same thing, and it
+ * completes with the component.
+ */
+declare function bounds(label?: string): BoundsCell;
+//#endregion
+//#region src/Component.d.ts
+/**
+ * Base class for all Gesso framework components.
+ *
+ * Components are class-based. They declare reactive state with
+ * an `internalState()` cell, inputs with `@Input()`, and return a UiElement tree
+ * from `render()`. The framework calls `render()` once per mount;
+ * after that, observable emissions in the returned tree drive updates.
+ */
+declare abstract class Component {
+  /**
+   * Called once after the component's UiNode subtree has been created
+   * and all observable bindings are connected.
+   */
+  onMount?(): void;
+  /**
+   * Called once when the component is being removed from the graph.
+   */
+  onUnmount?(): void;
+  /**
+   * Returns the component's UI definition.
+   *
+   * Called exactly once per component instance. Dynamic content is
+   * expressed through Observable props and children, never by
+   * re-invoking render().
+   *
+   * Returning an Observable is allowed for structural changes that
+   * cannot be expressed as observable children (routing, for example).
+   * The framework reconciles the component's root on each emission.
+   */
+  abstract render(): UiChild;
+}
+//#endregion
 //#region src/FunctionComponent.d.ts
 /**
  * What a functional component can ask of the framework while its body
@@ -392,6 +636,18 @@ interface ComponentContext {
    *   <box modifiers={[track.modifier]} onPointerDown={e => seek(e.x - track.value.x)} />
    */
   bounds(label?: string): BoundsCell;
+  /**
+   * What the component is placed under for `key`: the nearest value a
+   * node above it provides (`provide={[provided(key, value)]}`), else
+   * the key's default.
+   *
+   * Read as the body runs, from where the component is placed, so it
+   * is a value rather than a stream: a component that has to follow a
+   * change is given a source to follow (a cell) rather than each value.
+   * A design tool tells the screen it plays from the same screen drawn
+   * on its board this way.
+   */
+  environment<T>(key: UiEnvironmentKey<T>): T;
 }
 /**
  * The inputs a functional component receives: one host-owned cell per
@@ -504,5 +760,5 @@ type ComponentArgs<C> = RequiredKeys<ComponentProps<C>> extends never ? [inputs?
  */
 declare function isClassComponent(component: ComponentType): component is ClassComponent;
 //#endregion
-export { InternalState as C, output as S, Component as T, OutputTarget as _, ComponentType as a, into as b, Inputs as c, BoundsCell as d, bounds as f, OutputCell as g, InputCell as h, ComponentProps as i, isClassComponent as l, EmitValue as m, ComponentArgs as n, FunctionComponent as o, EmitArgs as p, ComponentContext as r, InputValue as s, ClassComponent as t, ChannelReplica as u, ReadableCell as v, internalState as w, isOutputTarget as x, input as y };
-//# sourceMappingURL=FunctionComponent-CHtojpp7.d.ts.map
+export { isChannelHostMessage as A, CommandsOf as B, into as C, ChannelHostMessage as D, ChannelClientMessage as E, diffProjection as F, channel as H, ChannelSpec as I, ChannelToken as L, PatchPath as M, applyPatch as N, ChannelPort as O, applyPatches as P, Command as R, input as S, output as T, defineChannel as U, ViewOf as V, viewKeys as W, EmitValue as _, ComponentType as a, OutputTarget as b, Inputs as c, BoundsCell as d, bounds as f, EmitArgs as g, ChannelReplica as h, ComponentProps as i, Patch as j, isChannelClientMessage as k, isClassComponent as l, internalState as m, ComponentArgs as n, FunctionComponent as o, InternalState as p, ComponentContext as r, InputValue as s, ClassComponent as t, Component as u, InputCell as v, isOutputTarget as w, ReadableCell as x, OutputCell as y, CommandMap as z };
+//# sourceMappingURL=FunctionComponent-BDVrANP0.d.ts.map