@kestack/kabuki 0.0.0 → 0.0.2

package/README.md

@@ -11,7 +11,8 @@ changes, and its State decides which Children it Invokes, which Capabilities
 it Provides to them and which Workers run. Leaving a State stops all of it.
 Any fact in the Model can own a Worker too: an upload runs for as long as its
 row says Uploading.
-Keyed Children follow the Model: a list of items can be a list of Actors.
+Children are written the way Workers are: always, `while` a test holds, or
+one per key `each` names, so a list of items can be a list of Actors.
 It is declarative, as React is: a parent says what should be, never what to
 do. It controls its Children only by whether they exist and by their Props,
 and what it must control it owns, as React lifts state up.
@@ -35,6 +36,26 @@ move its Head, and start again, and new Messages grow a new Branch. A History
 is also what an app is saved as and drawn from before it runs: on a server,
 at build time, and across a hot reload.
 
+Routing is a layer on top, in `@kestack/kabuki/routing`, that core never
+imports: a page is an Actor with a place in the URL. The router is read down
+from the pages' definitions, so any build can import it and name a Route by
+type. One Router Actor above the pages holds the history and the data of
+every page on screen, and hands each page its own as Props, so a page move
+is one Message and a page is a Child coming and going. It routes in memory
+by default; the browser's history and TanStack Router's are Adapters, each
+its own subpath. How it fits together is in
+[docs/routing.md](./docs/routing.md).
+
+Start, in `@kestack/kabuki/start` and its Vite plugin, serves a routed app
+from a Cloudflare Worker: for a URL it runs the Loaders of the places it
+names at once, starts every page from what its Loader gave, and sends the HTML with the
+Snapshot beside it, which the browser hydrates and carries on from. It never
+runs a Runtime on the server. An app writes three files: its pages, its app
+with its Document and what it needs in the browser, and its Loaders with what
+they need on the server, in three tiers; the plugin writes every entry. Each
+platform is an adapter of its own subpath, Cloudflare Workers for now. How it works is in
+[docs/start.md](./docs/start.md).
+
 Read the language in [CONTEXT.md](./CONTEXT.md), the decisions in
 [docs/adr/](./docs/adr/), and how the History works in
 [docs/history.md](./docs/history.md). A live demo, Opening an app, is at `/demos/opening-an-app` in the docs app: every concept in one story, drawn as the tree.
@@ -49,6 +70,8 @@ pnpm add @kestack/kabuki effect react
   one is checked against its Schema as it is made; Workers, Commands and
   Capabilities are Effect values and Layers.
 - `react`: `@kestack/kabuki/react` draws the tree with React components.
+- `react-dom`, optional: Start draws pages with `react-dom/server` and hydrates them with `react-dom/client`.
+- `vite`, optional: `@kestack/kabuki/start/vite` is a Vite plugin.
 
 ## Exports
 
@@ -56,13 +79,14 @@ pnpm add @kestack/kabuki effect react
 
 | Export             | What it does                                                                                                         |
 | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `Actor.make`       | Defines an Actor from its Requires and Schemas. `.build` adds how it behaves, at the top and in one block per State. |
-| `Actor.many`       | Declares a keyed Child slot: one Instance of an Actor per key the parent Invokes.                                    |
+| `Actor.define`     | Says what an Actor is: its name, Requires and Schemas, which fix every type. It runs nothing.                        |
+| `Actor.build`      | Says how a defined Actor behaves, at the top and in one block per State: the build is what runs and is drawn.        |
 | `Command.make`     | Defines a Command from its name, the Schema of its args and the Effect it runs; an Update calls it with the args.    |
 | `Runtime.start`    | Runs an Actor, or carries a History on, inside a Scope, with the app's Layer; gives back `send`, `start` and `stop`. |
 | `History.make`     | A new, empty History for an Actor, with the root's Input.                                                            |
 | `History.load`     | A History carrying on from one saved before, read with the Actor's code as it is now.                                |
 | `History.restored` | The lightest History an app can be saved as: one Restore of a Snapshot at a Time, right after init.                  |
+| `history.keep`     | Sets the History's Window, how many entries it keeps; older ones Compact into a Restore. Works while it runs.        |
 | `Replay.make`      | Plays Branches of one app from init, remembering Snapshots so playing again starts from the nearest one.             |
 | `Replay.fold`      | The Snapshot right after a Branch, played now from init with the root's Input, with no yielding.                     |
 | `restore`          | The Restore Message: given to the root, it replaces the whole Snapshot with a saved one, checked against the Actors. |
@@ -72,16 +96,111 @@ pnpm add @kestack/kabuki effect react
 | `handle`           | Applies one Envelope to a Snapshot and gives the next one, purely.                                                   |
 | `outcomeOf`        | Works out what came of one Envelope on a Snapshot: handled, ignored or dropped. The History never keeps it.          |
 | `instanceAt`       | Finds the Instance with an ID in a Snapshot.                                                                         |
-| `isMany`           | Tells a keyed Child slot from a fixed one in an Instance's Children.                                                 |
+| `isMany`           | Tells the list of an `each` Child from one Instance in an Instance's Children.                                       |
 
 ### `@kestack/kabuki/react`
 
-| Export        | What it does                                                                                                                                                                                                                                                               |
-| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `View.make`   | Defines how one Actor is drawn, one function for every State, as a React component that takes the Instance, and a `ref` and `style`, from its parent.                                                                                                                      |
-| `toReact`     | Turns a root Actor, its View and a Layer into one React component that runs the whole app, one Runtime for every mount; `useRuntime` reads its History, shows any Step, and stops and starts it. Drawn before it runs, on a server too, from a saved History if given one. |
-| `useChild`    | Reads one fixed Child's Model, State and Props from its parent's View, to draw, or only what an optional selector picks; an escape hatch that can never Send.                                                                                                              |
-| `useChildren` | Reads a slot of keyed Children the same way, in order; only the component that calls it re-renders, as they change or as what the selector picks does.                                                                                                                     |
+| Export         | What it does                                                                                                                                                                                                                                                               |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `View.make`    | Defines how one built Actor is drawn, one function for every State, as a React component that takes the Instance, and a `ref` and `style`, from its parent; the View carries its Actor as `.actor`.                                                                        |
+| `toReact`      | Turns a root Actor, its View and a Layer into one React component that runs the whole app, one Runtime for every mount; `useRuntime` reads its History, shows any Step, and stops and starts it. Drawn before it runs, on a server too, from a saved History if given one. |
+| `View.lazy`    | A View of the Actor it is given first, whose code is loaded the first time it is drawn, or on `preload()`; a server waits for it before it sends, and tells the App's `onLazyView`.                                                                                        |
+| `View.preload` | Loads the lazy Views made with these ids, so a browser hydrating a page a server drew never waits on their code.                                                                                                                                                           |
+| `useChild`     | Reads one Child's Model, State and Props from its parent's View, to draw, or only what an optional selector picks; an escape hatch that can never Send.                                                                                                                    |
+| `useChildren`  | Reads the Instances of an `each` Child the same way, in order; only the component that calls it re-renders, as they change or as what the selector picks does.                                                                                                             |
+| `lazyOf`       | Finds the lazy View made for an Actor, if one was, to load its code before it is drawn.                                                                                                                                                                                    |
+| `useLive`      | Says whether the app is drawn as it is now, not at a past Step, so an effect that touches the page around it can stay still under Time Travel.                                                                                                                             |
+
+### `@kestack/kabuki/routing`
+
+| Export                        | What it does                                                                                                                                                                                                                                        |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Page.define`                 | Says what a page is: an Actor definition with a place in the URL, its params, query, data, Render Mode, Metadata and the definitions of the pages under it.                                                                                         |
+| `Page.build`                  | Says how a page behaves, as `Actor.build` takes it, with the build of each page under it in `pages`; a page is drawn with `View.make`.                                                                                                              |
+| `Page.notFound`               | What a Loader fails with when its place is not found.                                                                                                                                                                                               |
+| `Page.redirect`               | What a Loader fails with to send the app to another of its Routes, or to a whole URL outside it; `{ permanent: true }` makes a server answer `308` rather than `302`.                                                                               |
+| `Page.NotFound`               | The Schema of a Loader's not-found failure, to carry it over the wire.                                                                                                                                                                              |
+| `Page.Redirect`               | The Schema of a Loader's Redirect, to carry it over the wire.                                                                                                                                                                                       |
+| `Router.define`               | Reads the app's router down from the root page's definition: a constructor per place, the URL both ways, each place's Metadata and Render Mode, every path, the typing of the Loaders, and how the Router behaves in the browser.                   |
+| `Router.app`                  | Puts the Router above the root page's View: it holds the history, every move and every page's data; gives the Actor, its View, `startAt` and `href`. With `scrollRestoration: true` on the router it restores scroll as TanStack Router does.       |
+| `Router.Link`                 | Draws a plain `<a href>` to a Route, preloading it on hover, once in view, or never, going to an element on the page with `hash`, and leaving every scroll as it is with `resetScroll={false}`; the Router catches a plain click and moves the app. |
+| `Router.Retry`                | A button that loads every page on screen again, for a page whose Loader broke.                                                                                                                                                                      |
+| `Router.memory`               | A `Loading` that runs the Loaders in place, for tests, stories and the server.                                                                                                                                                                      |
+| `Router.cached`               | Puts the Data cache in front of a `Loading`: the last data of each place, shown at once on Back, a link or a preload.                                                                                                                               |
+| `Router.push`                 | A Command that moves the app to a Route, as a new entry.                                                                                                                                                                                            |
+| `Router.replace`              | A Command that puts a Route in place of the current entry, so Back skips it.                                                                                                                                                                        |
+| `Router.back`                 | A Command that goes Back.                                                                                                                                                                                                                           |
+| `Router.forward`              | A Command that goes Forward.                                                                                                                                                                                                                        |
+| `Router.backTo`               | A Command that goes Back when the app came from a Route, and replaces the entry with it otherwise: closing a dialog with a Route of its own.                                                                                                        |
+| `Router.reload`               | A Command that loads every page on screen again, as after a save; the pages and their Models stay.                                                                                                                                                  |
+| `Router.preload`              | A Command that warms the Data cache, and the code of the lazy Views, for a Route.                                                                                                                                                                   |
+| `Navigation`                  | The Capability the Router Provides to every page, which an Actor under a page that moves the app lists in its Requires.                                                                                                                             |
+| `Loading`                     | The Capability the Router uses, if the Layer has it, to load the data of places.                                                                                                                                                                    |
+| `useRouter`                   | Reads the Router from a component drawn inside the app: the current Route and URL, the history, the move it holds while it loads as `pending`, the title, Back, Forward, reload and preload; `useRouter<Route>()` types its Routes as the app's.    |
+| `useElementScrollRestoration` | Reads where an element, or the window, was scrolled on the entry drawn, as scroll restoration kept it: for a virtual list that puts itself back.                                                                                                    |
+
+### `@kestack/kabuki/routing/adapter`
+
+| Export    | What it does                                                                                               |
+| --------- | ---------------------------------------------------------------------------------------------------------- |
+| `Adapter` | The service where an app's address lives, which each adapter below gives: write one for any other history. |
+| `KEY`     | The key the Router keeps in a history entry's state, so Back and Forward land on an entry it knows.        |
+| `keyIn`   | Reads that key from a history entry's state, if the Router wrote one.                                      |
+
+### `@kestack/kabuki/routing/adapter/browser`
+
+| Export    | What it does                                                                                                                        |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `browser` | A Layer that puts the app's address in the browser's own history, for an app that owns the whole site or everything under its base. |
+
+### `@kestack/kabuki/routing/adapter/tanstack`
+
+| Export     | What it does                                                                                                                                                     |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tanstack` | A Layer that puts the app's address in TanStack Router's history, for an app on a TanStack Start catch-all route; TanStack gets back every URL outside the base. |
+
+### `@kestack/kabuki/start`
+
+| Export             | What it does                                                                                                                                                     |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Start.app`        | Gives the app's router and its root page's View their Document and what the Actors Require in the browser, checked against them: what `src/app` default-exports. |
+| `Start.Document`   | The plainest Document, Start's parts in an English page: what an app that gives none is drawn in.                                                                |
+| `Start.Head`       | Draws, in the Document's `<head>`, the charset and viewport, the Metadata, and the styles and chunks the page needs.                                             |
+| `Start.Scripts`    | Draws, at the end of the Document's `<body>`, the saved History as JSON and the script that hydrates the page.                                                   |
+| `Start.useDrawn`   | Reads when and by which build the server drew the page, and whether the component asking was in that drawing or drawn later by the browser.                      |
+| `Start.useRuntime` | Reads the running app from the Document, for devtools drawn around it; `null` on the server.                                                                     |
+
+### `@kestack/kabuki/start/platform`
+
+The port each platform's adapter fills, in types only: no runtime value.
+
+### `@kestack/kabuki/start/platform/cloudflare`
+
+| Export       | What it does                                                                                                                      |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `cloudflare` | Cloudflare Workers, for `start({ platform: cloudflare() })`: the server built as one module in its edge form.                     |
+| `serve`      | Start's handler as a Worker's `fetch`, handed the Worker's env and the Cloudflare Cache: what the server's entry default-exports. |
+
+### `@kestack/kabuki/start/vite`
+
+| Export  | What it does                                                                                                                                                                                                                                                     |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start` | The Vite plugin: builds for the platform its adapter names, finds the app's two files by name, writes Start's handler, the server's and the browser's entries, names every lazy View by its module, and serves SSR in dev; works under Alchemy's `Website.Vite`. |
+
+### `@kestack/kabuki/start/server`
+
+| Export                  | What it does                                                                                                                                                                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server`                | Makes Start's handler, which knows no platform, from what the app's two files export: what the plugin's handler module runs; an app never calls it.                                                                                   |
+| `Start.layers`          | Gives the Loaders what they Require on the server, in three tiers, a call each (`instance`, `request`, `visitor`), each checked against the tiers before it, and the Loaders checked last: what `src/loaders.server` default-exports. |
+| `Start.ResponseHeaders` | The service a dynamic or client Loader, or the visitor tier, adds headers to its response with, as a refreshed session's `set-cookie`.                                                                                                |
+
+### `@kestack/kabuki/start/client`
+
+| Export    | What it does                                                                                                                                                      |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client`  | Hydrates a page the Worker drew, from the History it saved in it: what the plugin's browser entry runs; an app never calls it.                                    |
+| `loading` | The `Loading` that asks the server for the data of places at `POST /_kabuki/load`, each answered as it comes: what `client` hydrates with, behind the Data cache. |
 
 ## Usage
 
@@ -91,7 +210,7 @@ This root signs a user in. While `Anonymous` it Provides `SignIn` and Invokes
 `login`; while `Authenticated` it Provides `Session` and Invokes `todos`.
 
 ```ts
-export const Auth = Actor.make('Auth', {
+export const Auth = Actor.define('Auth', {
   requires: [Server],
   state: Schema.TaggedUnion({
     Checking: {},
@@ -103,7 +222,9 @@ export const Auth = Actor.make('Auth', {
     LoggedIn: { user: Schema.String },
     LoggedOut: {},
   }),
-}).build({
+});
+
+export const AuthLive = Actor.build(Auth, {
   init: () => ({ state: { _tag: 'Checking' } }),
   state: {
     Checking: {
@@ -123,7 +244,7 @@ export const Auth = Actor.make('Auth', {
       },
     },
     Anonymous: {
-      children: { login: Login },
+      children: { login: { actor: LoginLive } },
       provides: (self) =>
         Layer.succeed(SignIn, {
           complete: (user) => self.send({ _tag: 'LoggedIn', user }),
@@ -133,7 +254,7 @@ export const Auth = Actor.make('Auth', {
       },
     },
     Authenticated: {
-      children: { todos: Todos },
+      children: { todos: { actor: TodosLive } },
       provides: (self) =>
         Layer.succeed(Session, {
           user: self.get.pipe(Effect.map(({ state }) => state.user)),
@@ -145,8 +266,8 @@ export const Auth = Actor.make('Auth', {
 });
 ```
 
-- `make` takes only the Requires and the Schemas, which fix every type. `build` is checked against them: an Update that returns a State the Schema does not have, or a `state.user` read where there is none, does not compile.
-- `build` has two Levels. What is written at the top holds for as long as the Instance lives; what is written in a State's block holds while that State lasts. Each Level can hold `provides`, `children`, `invoke`, `on` and `workers`.
+- `Actor.define` takes only the name, the Requires and the Schemas, which fix every type, and imports nothing but other definitions. `Actor.build` is checked against them: an Update that returns a State the Schema does not have, or a `state.user` read where there is none, does not compile. The definition is `Auth`, the build `AuthLive`, side by side in one file.
+- A build has two Levels. What is written at the top holds for as long as the Instance lives; what is written in a State's block holds while that State lasts. Each Level can hold `provides`, `children`, `on` and `workers`.
 - An Update that returns a different `_tag` is a Transition: the old State's Children, Workers and Capabilities stop, the new State's start. A Child written at the top lasts through it.
 - A Worker is a named, scoped Effect given `self`: `send` to its own Instance, `get` and `changes` for its current data, and `now` for the app's Time. Written in the `Checking` block, `check` runs while that State lasts.
 - Provides is one Layer per Level, built each time its Level starts. A Capability that reads the Model reads it through `self`, so it never goes stale. It cancels out what the Children below it need; a need nothing cancels bubbles up to the app's Layer.
@@ -161,7 +282,7 @@ const save = Command.make('save', {
     Effect.sleep('1 second').pipe(Effect.as({ _tag: 'Saved' as const })),
 });
 
-const List = Actor.make('List', {
+const List = Actor.define('List', {
   model: Schema.Struct({
     ids: Schema.Array(Schema.String),
     uploading: Schema.Array(Schema.String),
@@ -173,16 +294,18 @@ const List = Actor.make('List', {
     Saved: {},
     Uploaded: { id: Schema.String },
   }),
-}).build({
+});
+
+const ListLive = Actor.build(List, {
   init: () => ({ model: { ids: [], uploading: [], next: 0 } }),
-  children: { rows: Actor.many(Row) },
-  invoke: ({ model }) => ({
-    rows: model.ids.map((id) => ({
-      key: id,
-      input: { text: `#${id}` },
-      props: { uploading: model.uploading.includes(id) },
-    })),
-  }),
+  children: {
+    rows: {
+      actor: RowLive,
+      each: ({ model }) => model.ids,
+      input: (_, id) => ({ text: `#${id}` }),
+      props: ({ model }, id) => ({ uploading: model.uploading.includes(id) }),
+    },
+  },
   on: {
     Added: (_, { model }) => {
       const id = `${model.next}`;
@@ -219,7 +342,7 @@ const List = Actor.make('List', {
 });
 ```
 
-- `invoke` sits beside the `children` it feeds, and says which keys exist, the Input each new Child starts from, and the Props each is handed. After every Update, a new key Invokes a Row, a key gone stops it, and a key kept keeps its Instance. From then on the Row owns its data.
+- A Child is written as a Worker is: its `actor`, then always, `while` a test is true, or `each` key a function names, one Instance per key. Its `input` and `props` are worked out from the parent's data and the Child's key, `''` unless it is one of `each`. After every Update, a new key Invokes a Row, a key gone stops it, and a key kept keeps its Instance. From then on the Row owns its data. A Child written with `while` stops when its test turns false and comes back as a fresh Instance.
 - Props are what the parent says now, worked out again after each of its Updates: the Row declares them with `props` beside `input`, and its Update, its Workers' Conditions and its View read them. It never writes them, and a change runs none of its rules. Props equal to the last ones keep the Instance; new ones are not in the History, since Replay works them out again from the parent.
 - Instance IDs are deterministic: `List/rows[0]#1` is the first `rows` keyed `0`. A key Invoked again gets `#2`, so a Message meant for the old Instance is dropped.
 - A Command is an errand, made once with `Command.make`: a name, the Schema of its args and the Effect it runs from them, ending with at most one Message. The Update asks for it with its args, `save({ id })`, which is plain data a test can compare; the args are checked when it runs. Nothing stops it but its Instance stopping, and there is no cancel. An Update may return a list of Commands; they run concurrently.
@@ -229,7 +352,7 @@ const List = Actor.make('List', {
 ### Drawing it with React
 
 ```tsx
-export const AuthView = View.make(Auth, ({ _tag, state, children }) => {
+export const AuthView = View.make(AuthLive, ({ _tag, state, children }) => {
   switch (_tag) {
     case 'Checking':
       return <Spinner />;
@@ -245,17 +368,17 @@ export const AuthView = View.make(Auth, ({ _tag, state, children }) => {
   }
 });
 
-const RowView = View.make(Row, ({ model, props, root }) => (
+const RowView = View.make(RowLive, ({ model, props, root }) => (
   <li {...root} data-uploading={props.uploading}>
     {model.text}
   </li>
 ));
 const MotionRow = motion.create(RowView);
 
-const DemoApp = toReact(Auth, AuthView, ServerLive);
+const DemoApp = toReact(AuthLive, AuthView, ServerLive);
 ```
 
-- One function draws every State. It gets `_tag`, `model`, `state`, `props`, `children` (Handles; arrays for keyed Children, each with its `key`), `send` and `root`; a `switch` on `_tag` narrows `state` and `children`. The DOM stays across a Transition. It never sees Capabilities, so it draws a Replay exactly like the live app.
+- One function draws every State. It gets `_tag`, `model`, `state`, `props`, `children` (Handles: one for a Child that is always there, one or `undefined` for a `while` Child, a list for an `each` Child, each with its `key`), `send` and `root`; a `switch` on `_tag` narrows `state` and `children`. The DOM stays across a Transition. It never sees Capabilities, so it draws a Replay exactly like the live app.
 - A Child is placed with `<RowView instance={handle} />`. A parent View hands it only where to draw; data from the parent is the Row's Props, which the parent Actor hands it, so its Update and Workers see the same.
 - Spreading `root` on the View's own element hands it the parent's `ref` and `style`, so `motion.create(RowView)` animates it, with no wrapper element, and it stays memoized. A View whose Instance has stopped keeps drawing its last data, so `AnimatePresence` can play its exit.
 - A View re-renders only when its own Instance's Model, State, Props or set of Children changes, or its `ref` or `style` does. Many Messages handled in a row make one render.
@@ -267,9 +390,9 @@ const DemoApp = toReact(Auth, AuthView, ServerLive);
 ### Drawing it before it runs
 
 ```tsx
-const DemoApp = toReact(Auth, AuthView, ServerLive, { saved });
+const DemoApp = toReact(AuthLive, AuthView, ServerLive, { saved });
 ```
 
 - The app is drawn before any Runtime exists: with no History, right after init; with a saved one, at its Head, replayed through Suspense. A server or a static build gets the same HTML the client hydrates, and `useRuntime` reads the saved History from the start, so a Timeline is drawn there too. Until the Runtime starts, a Send is dropped.
-- `saved` is what `history.save()` gives: its entries and its Head, each Message, and each Instance of a Restore's Snapshot, written through its Actor's Schemas and read back through them on load. So the encoded side of every Schema must be JSON-safe, and then it is plain JSON: a `Date` as `Schema.DateFromString`, an `Option` as `Schema.OptionFromNullOr`. A saved History never changes, and one whose Head is not one of its entries fails to load. The Runtime carries on live at the Head, with Time going on from the Head's. `History.restored(Auth, snapshot, at).save()` makes the lightest one, a History of one Restore right after init, for an app that saves only its Snapshot; init stays the first Step. Where the History is kept is the app's business.
+- `saved` is what `history.save()` gives: its entries and its Head, each Message, and each Instance of a Restore's Snapshot, written through its Actor's Schemas and read back through them on load. So the encoded side of every Schema must be JSON-safe, and then it is plain JSON: a `Date` as `Schema.DateFromString`, an `Option` as `Schema.OptionFromNullOr`. A saved History never changes, and one whose Head is not one of its entries fails to load. The Runtime carries on live at the Head, with Time going on from the Head's. `History.restored(AuthLive, snapshot, at).save()` makes the lightest one, a History of one Restore right after init, for an app that saves only its Snapshot; init stays the first Step. Where the History is kept is the app's business. Give `window` to keep only that many entries on the Head's Branch: the oldest kept becomes a Restore of the Snapshot right after it, and Time Travel reaches nothing before it. `history.keep(n)` changes it at any time, `history.keep(null)` stops Compacting. An app made with `toReact` remembers a Window changed that way in `localStorage` under its name, and starts from it after a reload, over the `window` it was given.
 - When the last mount closes, the History is left under the app's name, the root Actor's by default, and the next mount of an app with that name carries on from it: the same component mounted again, or a new one after a hot reload, whose code replays the old Messages. A Message the new code handles differently warns and goes on. Give `name` when two apps share a root Actor and must not share a History; two apps of one name mounted at once is a console error.

package/dist/core/actor/actor.d.ts

@@ -1,13 +1,20 @@
-import type { Actor as ActorOf, AnyActor, Behavior, KidsByState, Many, OpenOfBehavior, Requires, Single, Tagged } from './types.ts';
+import type { Actor as ActorOf, Behavior, KidsByState, OpenOfBehavior, Requires, Single, Tagged } from './types.ts';
 import { Schema } from 'effect';
-/** An Actor's Schemas, waiting for the behavior that runs it. */
+/**
+ * What an Actor is, as `Actor.define` gives it: its name, and the Schemas
+ * and Requires every type is fixed by. It runs nothing: `Actor.build` adds
+ * how it behaves.
+ */
 export interface Defined<Name extends string, Input, Props, Model, State extends Tagged, Msg extends Tagged, R extends Requires> {
-    readonly build: <const B extends Behavior<Input, Props, Model, State, Msg, R, B>>(behavior: B) => ActorOf<Name, Input, Props, Model, State, Msg, KidsByState<State, B>, OpenOfBehavior<R, B>>;
+    readonly name: Name;
+    readonly shape: Shape<Input, Props, Model, State, Msg, R>;
 }
+/** Any Actor's definition, loosely. */
+export type AnyDefined = Defined<string, any, any, any, any, any, any>;
 /** A Schema Kabuki can read and write without Capabilities and at once. */
 type Codec<T> = Schema.Codec<T, unknown, never, never>;
 /**
- * What `make` takes: every type the behavior is checked against, as codecs,
+ * What `define` takes: every type the behavior is checked against, as codecs,
  * and the Capabilities the Actor's own code may use. Every value is checked
  * against them too, as it is made: each Input and Props, each Model and
  * State from init or an Update, and each Message as it is Sent. A saved
@@ -25,18 +32,22 @@ export interface Shape<Input, Props, Model, State, Msg, R extends Requires> {
     readonly message?: Codec<Msg>;
     readonly state?: Codec<State>;
 }
-declare function make<const Name extends string, State extends Tagged = Single, Model = {}, Msg extends Tagged = never, const R extends Requires = readonly [], Input = void, Props = void>(name: Name, shape: Shape<Input, Props, Model, State, Msg, R>): Defined<Name, Input, Props, Model, State, Msg, R>;
-/** A keyed Child slot: the parent Invokes one Instance of `actor` per key. */
-declare const many: <A extends AnyActor>(actor: A) => Many<A>;
+declare function define<const Name extends string, State extends Tagged = Single, Model = {}, Msg extends Tagged = never, const R extends Requires = readonly [], Input = void, Props = void>(name: Name, shape: Shape<Input, Props, Model, State, Msg, R>): Defined<Name, Input, Props, Model, State, Msg, R>;
+/** How the Actor `D` defines may be built, as written in `B`. */
+export type BehaviorOf<D, B> = D extends Defined<any, infer Input, infer Props, infer Model, infer State, infer Msg, infer R> ? Behavior<Input, Props, Model, State, Msg, R, B> : never;
+/** The Actor `D` defines, built with `B`. */
+export type BuiltOf<D, B> = D extends Defined<infer Name, infer Input, infer Props, infer Model, infer State, infer Msg, infer R> ? ActorOf<Name, Input, Props, Model, State, Msg, KidsByState<State, B>, OpenOfBehavior<R, B>> : never;
+declare function build<D extends AnyDefined, const B extends BehaviorOf<D, B>>(definition: D, behavior: B): BuiltOf<D, B>;
 /**
- * An Actor, in two steps. `make` takes its Schemas and Requires, which fixes
- * every type. `build` takes how it behaves, at the top for as long as the
- * Instance lives and in one block per State for as long as that State lasts:
- * its Provides, Children, Invocation, Updates under `on`, and Workers.
+ * An Actor, in two steps. `define` takes what it is: its Schemas and
+ * Requires, which fix every type. `build` takes a definition and how it
+ * behaves, at the top for as long as the Instance lives and in one block per
+ * State for as long as that State lasts: its Provides, Children, Updates
+ * under `on`, and Workers.
  */
 export declare const Actor: {
-    make: typeof make;
-    many: typeof many;
+    define: typeof define;
+    build: typeof build;
 };
 export {};
 //# sourceMappingURL=actor.d.ts.map

package/dist/core/actor/actor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../../src/core/actor/actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,IAAI,OAAO,EAChB,QAAQ,EACR,QAAQ,EAKR,WAAW,EACX,IAAI,EACJ,cAAc,EACd,QAAQ,EACR,MAAM,EAGN,MAAM,EAEP,MAAM,YAAY,CAAC;AACpB,OAAO,EAAU,MAAM,EAAa,MAAM,QAAQ,CAAC;AAEnD,iEAAiE;AACjE,MAAM,WAAW,OAAO,CACtB,IAAI,SAAS,MAAM,EACnB,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,SAAS,MAAM,EACpB,GAAG,SAAS,MAAM,EAClB,CAAC,SAAS,QAAQ;IAElB,QAAQ,CAAC,KAAK,EAAE,CACd,KAAK,CAAC,CAAC,SAAS,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAE/D,QAAQ,EAAE,CAAC,KACR,OAAO,CACV,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,GAAG,EACH,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,EACrB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CACrB,CAAC;CACH;AAED,2EAA2E;AAC3E,KAAK,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,QAAQ;IACxE,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,mHAAmH;IACnH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;CAC/B;AAED,iBAAS,IAAI,CACX,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,KAAK,GAAG,EAAE,EACV,GAAG,SAAS,MAAM,GAAG,KAAK,EAC1B,KAAK,CAAC,CAAC,SAAS,QAAQ,GAAG,SAAS,EAAE,EACtC,KAAK,GAAG,IAAI,EACZ,KAAK,GAAG,IAAI,EAEZ,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,GAC/C,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AAmNrD,8EAA8E;AAC9E,QAAA,MAAM,IAAI,GAAI,CAAC,SAAS,QAAQ,SAAS,CAAC,KAAG,IAAI,CAAC,CAAC,CAGjD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;CAAiB,CAAC"}
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../../src/core/actor/actor.ts"],"names":[],"mappings":"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"}

package/dist/core/actor/actor.js

@@ -1,10 +1,11 @@
 import { Effect, Schema, SchemaAST } from 'effect';
-function make(name, shape) {
+function define(name, shape) {
+    return { name, shape };
+}
+function build(definition, behavior) {
     return {
-        build: (behavior) => ({
-            name,
-            definition: definitionOf(name, shape, behavior),
-        }),
+        name: definition.name,
+        definition: definitionOf(definition.name, definition.shape, behavior),
     };
 }
 /** The plain definition the engine works from, out of the Schemas and the levels. */
@@ -14,7 +15,6 @@ const definitionOf = (name, shape, behavior) => {
     const top = slots(behavior.children);
     const lasting = Object.keys(top);
     const children = {};
-    const invoke = {};
     const update = {};
     const stateProvides = {};
     const workers = {};
@@ -35,7 +35,6 @@ const definitionOf = (name, shape, behavior) => {
             if (slot in top)
                 throw new Error(`[@kestack/kabuki] ${name}: Child "${slot}" is written at the top and in ${tag}`);
         children[tag] = { ...top, ...own };
-        invoke[tag] = merged(behavior.invoke, block.invoke);
         if (block.on)
             update[tag] = block.on;
         stateProvides[tag] = block.provides;
@@ -70,17 +69,36 @@ const definitionOf = (name, shape, behavior) => {
         stateProvides,
         children,
         lasting,
-        invoke,
     };
 };
 const slots = (children) => Object.fromEntries(Object.entries(children ?? {}).map(([slot, child]) => [
     slot,
-    isMany(child)
-        ? { definition: child.actor.definition, many: true }
-        : { definition: child.definition, many: false },
+    slotOf(child),
 ]));
-/** The top-level Invocation and a State's own, as one. */
-const merged = (top, own) => !top ? own : !own ? top : (data) => ({ ...top(data), ...own(data) });
+const ONE = [''];
+const NONE = [];
+const NOTHING = () => undefined;
+/**
+ * A Child as the keys its Condition names, the way a Worker is: one, `''`,
+ * for every kind but `each`, or its `key` if it names one.
+ */
+const slotOf = (child) => {
+    const exists = child.while;
+    const key = child.key;
+    const one = key ? (data) => [key(data)] : () => ONE;
+    return {
+        definition: child.actor.definition,
+        kind: child.each ? 'each' : exists ? 'while' : 'always',
+        keyed: key !== undefined,
+        keys: child.each
+            ? child.each
+            : exists
+                ? (data) => (exists(data) ? one(data) : NONE)
+                : one,
+        input: (child.input ?? NOTHING),
+        props: (child.props ?? NOTHING),
+    };
+};
 /**
  * The State tags: a tagged union's cases, else every State a block is
  * written for. An Actor without States has the one, `Single`.
@@ -124,8 +142,6 @@ const tagsOf = (schema) => {
             : [])
         : []);
 };
-const ONE = [''];
-const NONE = [];
 /**
  * A Worker's Condition as the keys it names: one, `''`, for every kind but
  * `each`. Written in a State's block, it names none outside that State.
@@ -153,16 +169,11 @@ const workerOf = (worker, state) => {
         run,
     };
 };
-const isMany = (slot) => '_tag' in slot && slot._tag === 'Many';
-/** A keyed Child slot: the parent Invokes one Instance of `actor` per key. */
-const many = (actor) => ({
-    _tag: 'Many',
-    actor,
-});
 /**
- * An Actor, in two steps. `make` takes its Schemas and Requires, which fixes
- * every type. `build` takes how it behaves, at the top for as long as the
- * Instance lives and in one block per State for as long as that State lasts:
- * its Provides, Children, Invocation, Updates under `on`, and Workers.
+ * An Actor, in two steps. `define` takes what it is: its Schemas and
+ * Requires, which fix every type. `build` takes a definition and how it
+ * behaves, at the top for as long as the Instance lives and in one block per
+ * State for as long as that State lasts: its Provides, Children, Updates
+ * under `on`, and Workers.
  */
-export const Actor = { make, many };
+export const Actor = { define, build };

package/dist/core/actor/index.d.ts

@@ -1,6 +1,6 @@
 export { Actor } from './actor.ts';
 export { Command } from './command.ts';
 export { RUN } from './types.ts';
-export type { Defined } from './actor.ts';
-export type { ActorOf, AnyActor, Data, ActorDefinition, Encoding, Many, Only, Self, SlotDefinition, Tagged, Types, Worker, WorkerDefinition, Workers, } from './types.ts';
+export type { AnyDefined, Defined } from './actor.ts';
+export type { ActorOf, ActorType, AnyActor, Behavior, Child, Data, ActorDefinition, Encoding, KidsByState, Only, OpenOfBehavior, Requires, Self, SlotDefinition, Tagged, Types, Worker, WorkerDefinition, Workers, } from './types.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/actor/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/actor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACjC,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,eAAe,EACf,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,cAAc,EACd,MAAM,EACN,KAAK,EACL,MAAM,EACN,gBAAgB,EAChB,OAAO,GACR,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/actor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACjC,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EACV,OAAO,EACP,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,IAAI,EACJ,eAAe,EACf,QAAQ,EACR,WAAW,EACX,IAAI,EACJ,cAAc,EACd,QAAQ,EACR,IAAI,EACJ,cAAc,EACd,MAAM,EACN,KAAK,EACL,MAAM,EACN,gBAAgB,EAChB,OAAO,GACR,MAAM,YAAY,CAAC"}