gesso-framework 0.6.30 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # gesso-framework
 
+## 0.7.0
+
+### Minor Changes
+
+- fe71a86: An application can offer an agent tools of its own, beside its channels' and its screen's: `renderRoot(App).useAgentTools([...])`, and `useAgentTools` on the app builder. A tool is a name, a description, an input schema and a `run` that may answer with text, data and pictures (`agentText`, `agentImages`, `agentError` from `gesso-framework/agent`); its arguments are checked against the schema first. In `gesso-vite-plugin`, `agentInstructions` adds an application's own words to what an agent is told when it connects, and `catalog.exclude` leaves folders of generated code out of the component catalog, so they are not counted as uses.
+- 2034818: A tree drawn under transforms no longer costs a walk of all of it on every frame. A transformed node's subtree bounds are now its box and its children's carried out through its transform, where they were left unbounded and made every ancestor unbounded too; the hit tester passes such a subtree over when the point is outside it, and the accessibility mirror passes over what a panned, zoomed parent draws off screen (`LayoutEngine.screenBounds`). `InspectionService.box(node)` gives a node's box without building the rest of its report, for an editor that measures many nodes as its view moves. On a design tool's board of a thousand frames under one camera, a pan went from about one frame in three seconds to frames of about 25 milliseconds.
+- c053bc3: A length that is not one (`width: '100%'`) is refused where it is written, naming the element, instead of throwing in layout: that throw abandoned every frame, so one element's mistake stopped the whole application drawing. One that arrives bound, from an Observable, is reported once and laid out as if unset. `renderRoot(...).onError(listener)` hears every error the render worker reports to the shell, for an application that shows its errors itself with the plugin's `overlay: false`.
+- 6a7c397: `InspectionService.preview(node, property, value)` draws a node as though it declared a value, over its own and over its modifiers, until `endPreview` or the node leaves the tree: what a design editor shows while a colour is hovered or a padding dragged, before writing it to the source.
+- 0307034: An inspector report's owners say what each component's parent supplied for its inputs, as `inputs`: a word, a number or a flag as it is, an element (a slot the parent filled) as `{ element: true }`, and handlers or data left out. A design tool can then write a component's use back as code, `<TextField label="Email" />`, and an inspector can show a component's props. `ComponentHost.suppliedInputs()` is what it reads.
+- b85d643: `rasterize` keeps what a subtree paints as pixels and copies them while only what is above it moves or scales: a design tool's frames under a zooming camera are one `drawImage` each, not every photograph and path drawn again. Canvas2D draws a kept subtree again when anything in it changes, and once a zoom settles at another scale, sharp; while the zoom moves it stretches what it has, redrawing only what fits the frame. `UiRenderer.nextRepaint` asks the runtime for that settling frame. Culling also goes through a transform that only moves and scales, so a zoomed-in camera draws only what is on screen; a node moved by its own transform is culled where it is drawn, not where its box is.
+- 5b66cbf: SVG files draw. An `Image` whose source ends in `.svg` or is a `data:image/svg+xml` URL reads the file in the worker and draws it as vectors through `PaintSurface`, on either renderer, at whatever size the node is laid out at, rather than failing because `createImageBitmap` refuses SVG. `objectFit` places it, the file's own size sizes the node when nothing else does, and `currentColor` is the theme's text colour. Drawn: paths and basic shapes, groups, `<use>`, nested `<svg>`, transforms, fills and strokes with opacities, dashes, linear and radial gradients, clip paths and simple `<style>` rules; text, images, masks, filters, patterns and markers are skipped with a console note. New in `gesso-core`: `parseSvg`, `drawSvg`, `svgPaint`, `DefaultSvgResolver`, `isSvgSource`, and `imageSource`'s `vectors` argument; in `gesso-framework`, `MediaService.vectors`, `setSvgResolver` and the `media.vectors` option. `Image` is now built on a paint node rather than a box.
+- 9c411b1: An application's agent tool can say it waits on purpose, for a person or for its next task, with `waitsUpToMs`: it is listed under MCP's `_meta` as `gesso/waitsUpToMs` (`WAITS_UP_TO`), and the bridges between the agent and the thread, the dev server's and the render worker's, give a call of it that long, where they gave up on every call after two minutes.
+- 803a189: Touch, apart from the screen's size. What the person points with is now in the environment (`UiEnvironmentKeys.pointer`, `fine` or `coarse`): the runtime reads it from the device (CSS's `pointer` feature), keeps it on `ShellService.pointer`, and provides it at the root, and a `pointer` prop says it for a subtree, as a design tool's phone frame does. A theme provided under a coarse pointer is turned for it (`withPointer`): its `touch` values (larger type, more room, token groups of its own) are laid over it, and a token group it does not carry resolves to the group's own `coarse` values (`defineThemeExtension({ coarse })`). The controls use that: on touch a medium `Button` and a `TextInput` are at least 44 high (`TOUCH_TARGET`), a small button 36 and a large one 52. With a mouse nothing moves.
+
+### Patch Changes
+
+- 0e73baa: The dev server's agent endpoint now offers the project's own components, so an AI agent designing a screen uses what is there instead of drawing it again from boxes. `library_overview` lists every component in one line each, `library_search` finds the ones a few words describe, and `library_get` gives one in full: each input's type, default and meaning, examples, and the files that already use it. They are read from the files the project's tsconfig includes, a component saved in a new file is in the next answer, and they are answered on the dev server, so an agent can read them before a page is open. A library's components join only when named: `gesso({ catalog: { libraries: ['gesso-components'] } })`, and `catalog: false` leaves the tools out.
+
+  `tokens_view` joins the screen tools: the colours, type styles, corner radii, spacing scale and shadows of the theme in force, by name and value, at a control or at the application's outermost content. An agent told the names writes `backgroundColor="surface"` rather than a colour that will not follow the theme into dark mode. `GessoRuntime.themeAt(id)` gives the same theme to anything else that asks.
+
+- cf57c23: `tokens_view` and `render_frame` default to the themes an application designs in, when it names them with `renderThemesWith`: a design editor's project's theme rather than the editor's own, which is what an agent designing that project needs to read and draw in. Both take `theme: 'app' | 'light' | 'dark'`, `app` being the running application's own. `formatThemeTokens`'s second argument is now the sentence that names the theme ("The theme in force at …"), not only the place.
+- 407cefe: A desktop app's agents get `tokens_view` and `render_frame` from its windows, as a dev server's do. The relay from a window to the main process let through only tools named `ui_*`, so the two newer screen tools never crossed; it now lets through the screen's tools by name (`SCREEN_TOOL_NAMES`). `createScreenAgent({ windowChannels: true })` lets the window's channels through as well, for an application whose state lives in its window, and takes a `confirm` for their `@confirm` commands.
+
+  `renderRoot(App).loadModulesWith(load)` says how `render_frame` loads the module an agent names, for an application whose modules are served from somewhere other than its own root, such as an editor serving the project it designs from another folder.
+
+- 17711c4: `InspectionService` gives a component the inspector's answers about what is on the screen: `nodesAt(x, y)` is every node under a point, topmost first, in the coordinates a pointer event carries, and `inspect(node)` is the inspector's report on one, with the line that wrote it and where each component around it was used. It is for tools built in Gesso that point at Gesso, such as a design editor whose canvas holds live frames and where a click picks what is under it instead of pressing it. Injected like any service: `ctx.inject(InspectionService)`.
+- 4e0b6b7: Under `vite dev`, an element written in JSX remembers the file, line and column it was written on, and a component remembers where it was used. The inspector's report says so: a node's `source` is the line that made it, and each owner's `usedAt` is the line that used the component around it, so `formatNodeReport` now reads `written at src/Settings.tsx:12:7` and `rendered by Card (used at src/Settings.tsx:30:9)`. `UiGraphBuilder.sourceOf(node)` gives the same answer for any node. A canvas has no DOM for the browser's own inspector to point at, and this is the way back from a box on screen to the code. A production build compiles to `jsx`, which is given no location, so it costs nothing there.
+- 4956e76: `renderFrame` waits for a picture still being fetched or decoded before it draws, rather than taking the tree's quiet for finished: a large image could arrive after the frame was drawn, leaving it out. `mediaLoadsInFlight()` says how many pictures the media modifiers in this thread are still loading.
+- bf6cf01: `render_frame` joins the screen tools an agent gets: it draws a module of the project to a PNG, at the width asked for, and answers with it as an MCP image. It draws the module's default export, its only component, or the export named, with the inputs given, in the running application's theme unless `light` or `dark` is asked for. Without a height a frame is as tall as its content; given one, a screen fills it. The answer says when nothing was drawn, and what was thrown while it was drawn. A frame shares the application's channels and services, so a screen shows its real data.
+
+  `renderFrame(root, { width })` is the same drawing for any other use: a tree drawn once by a runtime of its own on an `OffscreenCanvas`, run until it stops asking for frames, sized to its content and read back as PNG bytes.
+
+  An error a frame causes is reported to the agent rather than over the person's screen. The render worker and the devtools overlay leave alone an error a frame has claimed (`claimErrors` in the framework, under a `Symbol.for` key the overlay reads).
+
+  `ServiceRegistry` takes a parent, which `get` falls back to and `has` does not consult, so an offscreen runtime finds the application's services and still registers its own.
+
+  A tool result's `content` can now hold an image (`AgentContent`), so code that read `content[0].text` without checking the part's type needs `resultText(result)`, which joins a result's text.
+
+- cdca567: `renderRoot(App).renderThemesWith(() => ({ light, dark }))` says what `render_frame`'s `light` and `dark` draw in, asked on each call: an application's own themes rather than Gesso's, such as the design system of a project a design editor is designing, so an agent sees a mock in the product's colours and type.
+- c35209d: A theme carries `units`, what an inch and a rem are worth in pixels: `{ pixelsPerInch: 96, rootFontSize: 16 }` on the stock themes, as in CSS. `lengths(theme.units)` gives `rem`, `inch`, `pt` and `mm` conversions to pixels, resolved where a value is written, so a theme can write its scales from the units it carries and a screen can write a print margin in millimetres or type in points. `themesEqual` compares the units. `UiTheme.units` is required, so a theme written without spreading a stock one has to add it. `tokens_view` reports the units, and tells an agent how to write a length in them.
+- 688eaa2: A trackpad pinch in WebKit (Safari, and the macOS web view an Electrobun app runs in) reaches the application as the ctrl-wheel Chromium and Firefox send for one, `deltaY` being -100·ln of each step's scale. Before, WebKit's gesture events went unheard, so a canvas that zooms on a ctrl-wheel could not be pinched there and a web view that magnifies zoomed the whole page instead. The gesture is kept from the page by the same rule as a wheel: when the chain under the pointer would take it, which `overscrollBehavior="contain"` says of every wheel.
+- Updated dependencies [2034818]
+- Updated dependencies [c053bc3]
+- Updated dependencies [85d58ae]
+- Updated dependencies [ae6af9a]
+- Updated dependencies [4e0b6b7]
+- Updated dependencies [2c55872]
+- Updated dependencies [6a7c397]
+- Updated dependencies [3ababdf]
+- Updated dependencies [b85d643]
+- Updated dependencies [4956e76]
+- Updated dependencies [6a7d6d4]
+- Updated dependencies [29e3863]
+- Updated dependencies [cf99e93]
+- Updated dependencies [5b66cbf]
+- Updated dependencies [c35209d]
+- Updated dependencies [639be4a]
+- Updated dependencies [9c8c730]
+- Updated dependencies [803a189]
+  - gesso-core@0.7.0
+
 ## 0.6.30
 
 ### Patch Changes

package/dist/{FunctionComponent-CHtojpp7.d.ts → FunctionComponent-Czkex8fp.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
+//#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
@@ -504,5 +748,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-Czkex8fp.d.ts.map