@ripplo/testing 0.7.9 → 0.7.11

package/DSL.md

@@ -1,13 +1,13 @@
 # Ripplo DSL reference
 
-The complete primitive catalog for `@ripplo/testing`. The `/ripplo:create` skill covers the workflow and the model; this is the exhaustive "what exists" — every action, locator, predicate, field axis, and assertion with a signature and a one-line example.
+The complete primitive catalog for `@ripplo/testing`. The `/ripplo:create` skill covers the authoring flow and the model; this is the exhaustive "what exists" — every action, locator, assertion, and field axis with a signature and a one-line example.
 
 A project has four layers:
 
 - **Entities** (`.ripplo/entities/`) — the state model. Each entity gets a `seed`/`read` impl in the app's engine funnel.
-- **Singletons** (`.ripplo/singletons/`) — client/global state (e.g. localStorage flags).
+- **Singletons** (`.ripplo/singletons/`) — single app-wide values. Like entities, each has a `source` ("backend" or "client").
 - **Worlds** (`.ripplo/worlds/`) — pure builder functions returning a flat record of entity handles (the starting state).
-- **Tests** (`.ripplo/tests/`) — `test("Intent", () => ({ given, steps }))`.
+- **Workflows** (`.ripplo/workflows/`) — `workflow("Intent", () => ({ given, steps }))`. The compiler enumerates concrete tests from each workflow.
 
 Everything is imported from `@ripplo/testing`.
 
@@ -27,7 +27,7 @@ export const Task = entity("task", {
     note: field({ optional: true, value: v.word() }), // nullable
   },
   identity: { id: id() },
-  source: "backend", // "backend" (DB) or "client" (browser state)
+  source: "backend", // "backend" (server-side) or "client" (browser-side)
 });
 ```
 
@@ -38,7 +38,7 @@ export const Task = entity("task", {
 Pick by where the state is persisted, not where it's displayed:
 
 - `source: "backend"` — the default for anything long-lived: database rows, server-side session state, anything that survives a page reload because the server has it. Seeded/read by the **server engine** (`createEngine` in your app's `test/engine.ts`).
-- `source: "client"` — state that lives only in the browser: localStorage, IndexedDB, in-memory stores that the app treats as state but never persists server-side. Seeded/read by the **client engine** (`mountClientEngine`, below). Reach for it when a flow's behavior depends on browser-local state you need to arrange or assert.
+- `source: "client"` — state that lives only in the browser: localStorage, IndexedDB, in-memory stores that the app treats as state but never persists server-side. Seeded/read by the **client engine** (`mountClientEngine`, below). Reach for it when a flow's behavior depends on browser-local state you need to seed or assert.
 
 If you're unsure, it's backend. A value that's cached in the browser but owned by the server is backend — model the server's row, not the cache.
 
@@ -47,16 +47,16 @@ If you're unsure, it's backend. A value that's cached in the browser but owned b
 ### `field(options)`
 
 ```ts
-field({ value: v.email() }); // required, stable, oracle holds observed == model
+field({ value: v.email() }); // required, stable — Ripplo checks the app's value matches what the test expected
 field({ value: v.word(), optional: true }); // nullable; `null` is a valid set/assert value
 field({ value: v.number({ min: 0, max: 100 }), stable: false }); // adopt-only, drift not checked
 ```
 
-| option     | meaning                                                                                                     |
-| ---------- | ----------------------------------------------------------------------------------------------------------- |
-| `value`    | the value-space (`v.*`) — required                                                                          |
-| `optional` | `true` ⇒ the field is nullable (`null` allowed in `of`/`updated`/assertions); oracle treats `null ≡ absent` |
-| `stable`   | default `true` (oracle holds `observed == model value`). `false` = adopt-only, drift unchecked              |
+| option     | meaning                                                                                                              |
+| ---------- | -------------------------------------------------------------------------------------------------------------------- |
+| `value`    | the value-space (`v.*`) — required                                                                                   |
+| `optional` | `true` ⇒ the field is nullable (`null` allowed in `of`/`updated`/assertions); Ripplo treats `null ≡ absent`          |
+| `stable`   | default `true` (Ripplo checks the app's value matches what the test expected). `false` = adopt-only, drift unchecked |
 
 ### Identity: `id()` and `key(options)`
 
@@ -85,7 +85,7 @@ identity: {
 | `v.oneOf([...])`                           | any     | enum — one of the listed values                             |
 | `v.datetime({ offsetDays: { min, max } })` | string  | ISO-8601 timestamp, offset days relative to the run's start |
 
-String spaces take optional constraints: `v.word({ minLength, maxLength, pattern })`. `v.number` requires `{ min, max }`. `v.oneOf` types narrowly with `as const`-style tuples: `v.oneOf(["PENDING", "ACCEPTED"])`. `v.datetime` values are generated relative to the run's start timestamp (e.g. `{ min: -30, max: 1 }` = up to 30 days past, 1 day future); the oracle compares datetimes by UTC instant, so driver formatting/timezone rendering differences never diverge.
+String spaces take optional constraints: `v.word({ minLength, maxLength, pattern })`. `v.number` requires `{ min, max }`. `v.oneOf` types narrowly with `as const`-style tuples: `v.oneOf(["PENDING", "ACCEPTED"])`. `v.datetime` values are generated relative to the run's start timestamp (e.g. `{ min: -30, max: 1 }` = up to 30 days past, 1 day future); Ripplo compares datetimes by UTC instant, so driver formatting/timezone rendering differences never cause a mismatch.
 
 ---
 
@@ -116,7 +116,7 @@ export const projectWithTask = () => {
 | --------------------- | --------------------------------------------------------------------------------------- |
 | `Entity.of(props)`    | a row that is **guaranteed** present                                                    |
 | `Entity.only(props)`  | exactly one such row (singleton in the world)                                           |
-| `Entity.maybe(props)` | optionally present (fuzz covers both branches)                                          |
+| `Entity.maybe(props)` | optionally present — a compile-time degree of freedom the compiler solves per test      |
 | `Entity.none(where)`  | asserts **absence** — no row matches (returns an absence handle; include it in `given`) |
 
 - `arbitrary(Entity.field.x)` — draws a fresh value for field `x`. A fresh param each call.
@@ -126,17 +126,17 @@ export const projectWithTask = () => {
 
 ---
 
-## Tests
+## Workflows
 
 ```ts
-import { button, click, fill, goto, test, textbox, visible } from "@ripplo/testing";
+import { button, click, fill, goto, textbox, visible, workflow } from "@ripplo/testing";
 import { Task } from "../entities/index.js";
 import { ownedProject } from "../worlds/index.js";
 
-export const createTask = test("Create a task", () => {
+export const createTask = workflow("Create a task", () => {
   const { me, project } = ownedProject();
   return {
-    given: [me, project], // arrange: all the handles this test needs
+    given: [me, project], // setup: all the handles this workflow needs
     steps: [
       // act + assert
       goto`/projects/${project.id}/tasks`.expect(visible(button("New"))),
@@ -147,18 +147,23 @@ export const createTask = test("Create a task", () => {
   };
 });
 
-export const renameTask = test("Rename a task"); // STUB — no body; gated until implemented
+export const renameTask = workflow("Rename a task"); // STUB — no body; gated until implemented
 ```
 
-- `test(intent)` (no body) → a **stub**; `test(intent, () => body)` → an implemented test.
-- The test body returns `{ given, steps }`. The arrange/act boundary is `given:` vs `steps:`.
+- `workflow(intent)` (no body) → a **stub**; `workflow(intent, () => body)` → an implemented workflow.
+- The workflow body returns `{ given, steps }`. The setup/act boundary is `given:` vs `steps:`.
 - Everything a step references must trace to a handle in `given`.
+- Register workflows in `.ripplo/workflows/index.ts` (exports `workflows`); the funnel is `createRipplo({ entities, singletons, workflows })`.
+
+### Workflows compile to tests
+
+The compiler enumerates one concrete test per `when` branch at `ripplo compile`/`lint` time — a covering set across all when blocks. Each test gets a solved seed: the compiler picks which `maybe(...)` entities to seed and pins `arbitrary()` singleton values so the branch's condition holds after the steps' declared effects. A workflow with no when blocks compiles to a single test named "main". A branch no seed can reach is a compile error ("branch X is unreachable") — fix the condition or widen the world with maybe entities. The solver caps candidate seeds at 4096 (maybe subsets × singleton pin combinations) — past that it errors with "too many optional entities and singleton values to solve", so split the workflow or convert `maybe(...)` entities to `of(...)`. Runs are per test. `maybe()` entities are compile-time degrees of freedom, never randomly chosen at run time.
 
 ---
 
 ## Actions
 
-Each returns a step; chain `.expect(...predicates)` to assert after it runs.
+Each returns a step; chain `.expect(...assertions)` to assert after it runs.
 
 | action     | signature                      | example                                  |
 | ---------- | ------------------------------ | ---------------------------------------- |
@@ -217,11 +222,11 @@ click(inside(main(), button("New"))); // disambiguate from a header CTA
 
 ---
 
-## Predicates (UI assertions)
+## UI assertions
 
 Used inside a step's `.expect(...)`.
 
-| predicate  | signature                         | asserts                                   |
+| assertion  | signature                         | asserts                                   |
 | ---------- | --------------------------------- | ----------------------------------------- |
 | `visible`  | `visible(locator)`                | element is visible                        |
 | `disabled` | `disabled(locator)`               | element is disabled                       |
@@ -229,11 +234,38 @@ Used inside a step's `.expect(...)`.
 | `focused`  | `focused(locator)`                | element has focus                         |
 | `value`    | `value(locator, string\|binding)` | input's value equals                      |
 | `text`     | `text(locator, string\|binding)`  | element's text equals                     |
-| `not`      | `not(predicate)`                  | negation — `not(visible(role("dialog")))` |
+| `not`      | `not(assertion)`                  | negation — `not(visible(role("dialog")))` |
 | `and`      | `and(...conditions)`              | conjunction                               |
-| `when`     | `when(...clauses)`                | conditional assertion                     |
+| `when`     | `when(...branches)`               | named conditional branches (below)        |
 | `count`    | `count(Entity).is(n)`             | n rows of the entity exist                |
 
+### `when` — named branches
+
+`when` takes `branch(...)` builders. Each branch names a scenario, optionally guards it with `.if(condition)`, and asserts with `.expect(...assertions)`:
+
+```ts
+when(
+  branch("deleting the last project")
+    .if(count(Project).is(0))
+    .expect(url.is`/connect`),
+  branch("deleting the first project, onboarding pending")
+    .if(and(count(Project).is(1), onboardingDismissed.is(false)))
+    .expect(url.is`/onboarding?projectId=${other.id}`),
+  branch("deleting one of several projects").expect(url.is`/projects`),
+);
+```
+
+Rules:
+
+- Every branch is named.
+- At most one unconditional branch, and it must be last.
+- Names are unique within a workflow.
+- No nested whens — a `when` inside a branch's `.expect(...)` is an error ("whens are one level deep"). A scenario that wants a second level is its own workflow.
+
+The name labels the test, not the condition — describe the scenario from the user's point of view, including the state that drives the different outcome. Two failure modes to avoid: post-state names ("no projects left" describes the result, not the scenario) and seed-mechanics names ("first project, onboarding pending" describes how the world was built). Test: it should read as a sentence under the workflow name, and someone seeing the name as a failed-test label should know which situation broke. "Delete project → deleting the last project" works. "Delete project → deleting a project when the remaining project still needs onboarding" works. "Delete project → no projects left" and "Delete project → first project, onboarding pending" do not.
+
+The compiler enumerates one test per branch (see "Workflows compile to tests" above).
+
 ### Browser singletons
 
 ```ts
@@ -243,9 +275,9 @@ goto`/projects/${p.id}`.expect(url.is`/projects/${p.id}`); // url/title/viewport
 
 ---
 
-## Backend assertions (the oracle)
+## Backend assertions — Ripplo verifies backend state
 
-Put these in a step's `.expect(...)` alongside UI predicates. The oracle does a 3-way compare (model-before / predicted-after / observed) and flags divergence — you never poll.
+Put these in a step's `.expect(...)` alongside UI assertions. After each step Ripplo compares your app's state against what the test declared and flags any mismatch — you never poll.
 
 ```ts
 import { changed, within } from "@ripplo/testing";
@@ -259,7 +291,7 @@ Task.deleted({ id: task.id }); // the keyed row is gone
 - `Entity.created(props)` — assert a creation.
 - `Entity.updated(key, changes)` — assert an update on the row matching `key`. Use `changed()` as a value when the new value is server-chosen (assert it _differs_ without pinning it).
 - `Entity.deleted(key)` — assert deletion.
-- Consistency timing is automatic: a field declared `consistency: "eventual"` (or a `changed()` baseline) tolerates propagation lag; default `strict` fails fast on a wrong intermediate value.
+- Consistency timing is automatic: `strict` (the default) means the field must match immediately and fails fast on a wrong intermediate value, `consistency: "eventual"` (or a `changed()` baseline) means it may lag briefly and Ripplo waits for it.
 
 ### Relational selection (`where` / `within`)
 
@@ -275,7 +307,9 @@ Task.deleted({ projectId: within(Project.where({ ownerId: me.id }), "id") }); //
 
 ---
 
-## Singletons (client/global state)
+## Singletons (single app-wide values)
+
+A singleton is one app-wide value, where an entity has rows. Like entities, it has a `source` — `"backend"` (seeded/read by the server engine) or `"client"` (seeded/read by the client engine).
 
 ```ts
 import { singleton, v } from "@ripplo/testing";
@@ -290,7 +324,7 @@ export const onboardingDismissed = singleton("onboardingDismissed", {
 export const singletons = [onboardingDismissed];
 ```
 
-Set in a test's body (`singletons:`) and assert via predicates; the client engine seeds/reads them in the browser.
+Set in a workflow's body (`singletons:`) and assert via UI assertions. The engine matching the singleton's source seeds and reads it.
 
 ### The client engine
 
@@ -353,5 +387,5 @@ export const engine = createEngine(ripplo, { entities: impls, singletons: {} },
 ```
 
 - **`seed`** creates one row from `fields`, returns `{ row, session }` (`session` = an auth session for identity entities like `user`/`session`, else `undefined`).
-- **`read`** returns this run's rows of the entity. Scope every query by the run so the oracle only sees this run's data.
-- Isolation lives here, not in the test: run-scoped ids in `seed`, run-scoped queries in `read`. Never `update`/`delete` rows your run didn't create.
+- **`read`** returns this run's rows of the entity. Scope every query by the run so Ripplo only sees this run's data.
+- Isolation lives here, not in the workflow: run-scoped ids in `seed`, run-scoped queries in `read`. Never `update`/`delete` rows your run didn't create.

package/dist/{engine-BfvzXgLg.d.ts → engine-Dv3trweR.d.ts}

@@ -237,6 +237,11 @@ interface Within {
     readonly selection: Selection$1;
 }
 type WhereValue = SetValue | Within;
+interface WhenBranch {
+    readonly condition: Condition | undefined;
+    readonly consequence: Predicate;
+    readonly name: string;
+}
 type Predicate = {
     readonly kind: "visible";
     readonly locator: Locator;
@@ -290,10 +295,8 @@ type Predicate = {
     readonly kind: "count";
     readonly value: number;
 } | {
-    readonly condition: Predicate;
-    readonly consequence: Predicate;
+    readonly branches: ReadonlyArray<WhenBranch>;
     readonly kind: "when";
-    readonly otherwise: Predicate | undefined;
 };
 type Condition = Extract<Predicate, {
     kind: "singleton" | "count";
@@ -367,7 +370,7 @@ declare const stepSchema: z.ZodObject<{
     expect: z.ZodDefault<z.ZodArray<z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>>>;
 }, z.core.$strip>;
 type Step = z.infer<typeof stepSchema>;
-declare const testSchema: z.ZodObject<{
+declare const workflowSchema: z.ZodObject<{
     absent: z.ZodDefault<z.ZodArray<z.ZodObject<{
         entity: z.ZodString;
         where: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
@@ -393,7 +396,6 @@ declare const testSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     name: z.ZodString;
     params: z.ZodRecord<z.ZodString, z.ZodObject<{
-        example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
         valueSpace: z.ZodString;
     }, z.core.$strip>>;
     singletons: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
@@ -464,6 +466,103 @@ declare const testSchema: z.ZodObject<{
         expect: z.ZodDefault<z.ZodArray<z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>>>;
     }, z.core.$strip>>>;
     stub: z.ZodDefault<z.ZodBoolean>;
+    tests: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        absent: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            entity: z.ZodString;
+            where: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                ref: z.ZodString;
+            }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    ref: z.ZodString;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>, z.ZodNull]>>;
+        }, z.core.$strip>>>;
+        exclusive: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        intent: z.ZodString;
+        name: z.ZodString;
+        params: z.ZodRecord<z.ZodString, z.ZodObject<{
+            valueSpace: z.ZodString;
+        }, z.core.$strip>>;
+        singletons: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            ref: z.ZodString;
+        }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+            template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                ref: z.ZodString;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>, z.ZodNull]>>>;
+        slug: z.ZodString;
+        steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"goto">;
+                url: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    ref: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        ref: z.ZodString;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>]>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"fill">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                value: z.ZodUnion<readonly [z.ZodObject<{
+                    ref: z.ZodString;
+                }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                    template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        ref: z.ZodString;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>, z.ZodNull]>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"clear">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"click">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"dblclick">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"select">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                value: z.ZodUnion<readonly [z.ZodObject<{
+                    ref: z.ZodString;
+                }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                    template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        ref: z.ZodString;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>, z.ZodNull]>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"check">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"uncheck">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"hover">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+            }, z.core.$strip>, z.ZodObject<{
+                files: z.ZodArray<z.ZodString>;
+                kind: z.ZodLiteral<"upload">;
+                locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+            }, z.core.$strip>, z.ZodObject<{
+                key: z.ZodString;
+                kind: z.ZodLiteral<"press">;
+                locator: z.ZodOptional<z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>>;
+            }, z.core.$strip>], "kind">;
+            expect: z.ZodDefault<z.ZodArray<z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>>>;
+        }, z.core.$strip>>>;
+        workflow: z.ZodString;
+        world: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            as: z.ZodString;
+            entity: z.ZodString;
+            set: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                ref: z.ZodString;
+            }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    ref: z.ZodString;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>, z.ZodNull]>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
     world: z.ZodDefault<z.ZodArray<z.ZodObject<{
         as: z.ZodString;
         entity: z.ZodString;
@@ -476,7 +575,7 @@ declare const testSchema: z.ZodObject<{
         }, z.core.$strip>, z.ZodNull]>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
-type Test = z.infer<typeof testSchema>;
+type Workflow = z.infer<typeof workflowSchema>;
 declare const lockfileSchema: z.ZodObject<{
     entities: z.ZodArray<z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
@@ -528,7 +627,39 @@ declare const lockfileSchema: z.ZodObject<{
         }>;
         valueSpace: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
-    tests: z.ZodArray<z.ZodObject<{
+    valueSpaces: z.ZodArray<z.ZodObject<{
+        constraints: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"string">;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            minLength: z.ZodOptional<z.ZodNumber>;
+            pattern: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"number">;
+            max: z.ZodOptional<z.ZodNumber>;
+            min: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"datetime">;
+            maxOffsetDays: z.ZodNumber;
+            minOffsetDays: z.ZodNumber;
+        }, z.core.$strip>], "kind">>;
+        generator: z.ZodEnum<{
+            "company.name": "company.name";
+            "date.iso": "date.iso";
+            "internet.email": "internet.email";
+            "internet.url": "internet.url";
+            "person.fullName": "person.fullName";
+            "lorem.slug": "lorem.slug";
+            "lorem.word": "lorem.word";
+        }>;
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+        }>;
+        values: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    }, z.core.$strip>>;
+    workflows: z.ZodArray<z.ZodObject<{
         absent: z.ZodDefault<z.ZodArray<z.ZodObject<{
             entity: z.ZodString;
             where: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
@@ -554,7 +685,6 @@ declare const lockfileSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         name: z.ZodString;
         params: z.ZodRecord<z.ZodString, z.ZodObject<{
-            example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
             valueSpace: z.ZodString;
         }, z.core.$strip>>;
         singletons: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
@@ -625,6 +755,103 @@ declare const lockfileSchema: z.ZodObject<{
             expect: z.ZodDefault<z.ZodArray<z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>>>;
         }, z.core.$strip>>>;
         stub: z.ZodDefault<z.ZodBoolean>;
+        tests: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            absent: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                entity: z.ZodString;
+                where: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                    ref: z.ZodString;
+                }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                    template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        ref: z.ZodString;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>, z.ZodNull]>>;
+            }, z.core.$strip>>>;
+            exclusive: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            intent: z.ZodString;
+            name: z.ZodString;
+            params: z.ZodRecord<z.ZodString, z.ZodObject<{
+                valueSpace: z.ZodString;
+            }, z.core.$strip>>;
+            singletons: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                ref: z.ZodString;
+            }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    ref: z.ZodString;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>, z.ZodNull]>>>;
+            slug: z.ZodString;
+            steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"goto">;
+                    url: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        ref: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                            ref: z.ZodString;
+                        }, z.core.$strip>]>>;
+                    }, z.core.$strip>]>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"fill">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                    value: z.ZodUnion<readonly [z.ZodObject<{
+                        ref: z.ZodString;
+                    }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                        template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                            ref: z.ZodString;
+                        }, z.core.$strip>]>>;
+                    }, z.core.$strip>, z.ZodNull]>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"clear">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"click">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"dblclick">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"select">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                    value: z.ZodUnion<readonly [z.ZodObject<{
+                        ref: z.ZodString;
+                    }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                        template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                            ref: z.ZodString;
+                        }, z.core.$strip>]>>;
+                    }, z.core.$strip>, z.ZodNull]>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"check">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"uncheck">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"hover">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    files: z.ZodArray<z.ZodString>;
+                    kind: z.ZodLiteral<"upload">;
+                    locator: z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    key: z.ZodString;
+                    kind: z.ZodLiteral<"press">;
+                    locator: z.ZodOptional<z.ZodType<Locator, unknown, z.core.$ZodTypeInternals<Locator, unknown>>>;
+                }, z.core.$strip>], "kind">;
+                expect: z.ZodDefault<z.ZodArray<z.ZodType<Predicate, unknown, z.core.$ZodTypeInternals<Predicate, unknown>>>>;
+            }, z.core.$strip>>>;
+            workflow: z.ZodString;
+            world: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                as: z.ZodString;
+                entity: z.ZodString;
+                set: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                    ref: z.ZodString;
+                }, z.core.$strip>, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodObject<{
+                    template: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        ref: z.ZodString;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>, z.ZodNull]>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
         world: z.ZodDefault<z.ZodArray<z.ZodObject<{
             as: z.ZodString;
             entity: z.ZodString;
@@ -637,38 +864,6 @@ declare const lockfileSchema: z.ZodObject<{
             }, z.core.$strip>, z.ZodNull]>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
-    valueSpaces: z.ZodArray<z.ZodObject<{
-        constraints: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
-            kind: z.ZodLiteral<"string">;
-            maxLength: z.ZodOptional<z.ZodNumber>;
-            minLength: z.ZodOptional<z.ZodNumber>;
-            pattern: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
-            kind: z.ZodLiteral<"number">;
-            max: z.ZodOptional<z.ZodNumber>;
-            min: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strip>, z.ZodObject<{
-            kind: z.ZodLiteral<"datetime">;
-            maxOffsetDays: z.ZodNumber;
-            minOffsetDays: z.ZodNumber;
-        }, z.core.$strip>], "kind">>;
-        generator: z.ZodEnum<{
-            "company.name": "company.name";
-            "date.iso": "date.iso";
-            "internet.email": "internet.email";
-            "internet.url": "internet.url";
-            "person.fullName": "person.fullName";
-            "lorem.slug": "lorem.slug";
-            "lorem.word": "lorem.word";
-        }>;
-        name: z.ZodString;
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-        }>;
-        values: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-    }, z.core.$strip>>;
 }, z.core.$strip>;
 type Lockfile = z.infer<typeof lockfileSchema>;
 declare const sessionSchema: z.ZodObject<{
@@ -745,7 +940,6 @@ type Primitive = string | number | boolean;
 type Fields = Record<string, Primitive>;
 interface ParamToken {
     readonly base: string;
-    readonly example: Primitive | undefined;
     readonly valueSpace: string;
 }
 type EntityKind = "of" | "only" | "maybe";
@@ -830,9 +1024,19 @@ interface CountCondition {
     readonly is: (count: number) => ConditionPredicate;
 }
 declare function count(entity: Countable): CountCondition;
-type WhenClause = readonly [ConditionInput, PredicateInput];
-declare function when(...clauses: readonly WhenClause[]): LeafPredicate;
-declare function when(...clausesThenFallback: readonly [...WhenClause[], PredicateInput]): LeafPredicate;
+interface BranchInput {
+    readonly __branch: true;
+    readonly branch: WhenBranch;
+}
+interface NamedBranch {
+    readonly expect: (consequence: PredicateInput) => BranchInput;
+    readonly if: (condition: ConditionInput) => ConditionedBranch;
+}
+interface ConditionedBranch {
+    readonly expect: (consequence: PredicateInput) => BranchInput;
+}
+declare function branch(name: string): NamedBranch;
+declare function when(...branches: ReadonlyArray<BranchInput>): LeafPredicate;
 
 interface ValueSpacePartial<T extends Primitive> {
     readonly __t: T | undefined;
@@ -1088,4 +1292,4 @@ interface Engine {
 }
 declare function createEngine<R extends DeclSource>(ripplo: R, impls: EngineImpls<R, "backend">, teardown: Teardown): Engine;
 
-export { key as $, type AnyBinding as A, type Binding as B, type Capture as C, type DeclSource as D, type Engine as E, type FieldHandle as F, type GivenItem as G, type Handle as H, type SingletonValue as I, type WithinMatcher as J, and as K, type Locator as L, changed as M, count as N, createEngine as O, type PredicateInput as P, disabled as Q, type Row as R, type Step as S, type Test as T, type UniqueNames as U, enabled as V, type WhenClause as W, entity as X, field as Y, focused as Z, id as _, type EntityList as a, not as a0, singleton as a1, text as a2, v as a3, value as a4, visible as a5, when as a6, within as a7, type SingletonList as b, type Lockfile as c, type BrowserSingleton as d, type LeafPredicate as e, type Primitive as f, type Primitive$1 as g, type SingletonDef as h, type AbsenceHandle as i, CLIENT_MOUNT_KEY as j, CLIENT_SEED_KEY as k, type ConditionInput as l, type ConditionPredicate as m, type CountCondition as n, type DuplicateEntityName as o, type EngineError as p, type EngineImpls as q, type EngineRead as r, type EntityDef as s, type EntityHandle as t, type EntityImpl as u, type FieldOptions as v, type Fields as w, type Selection as x, type SingletonConfig as y, type SingletonImpl as z };
+export { field as $, type AnyBinding as A, type Binding as B, type Capture as C, type DeclSource as D, type Engine as E, type FieldHandle as F, type GivenItem as G, type Handle as H, type SingletonConfig as I, type SingletonImpl as J, type SingletonValue as K, type Locator as L, type WithinMatcher as M, type NamedBranch as N, and as O, type PredicateInput as P, branch as Q, type Row as R, type Step as S, changed as T, type UniqueNames as U, count as V, type Workflow as W, createEngine as X, disabled as Y, enabled as Z, entity as _, type EntityList as a, focused as a0, id as a1, key as a2, not as a3, singleton as a4, text as a5, v as a6, value as a7, visible as a8, when as a9, within as aa, type SingletonList as b, type Lockfile as c, type BrowserSingleton as d, type LeafPredicate as e, type Primitive as f, type Primitive$1 as g, type SingletonDef as h, type AbsenceHandle as i, type BranchInput as j, CLIENT_MOUNT_KEY as k, CLIENT_SEED_KEY as l, type ConditionInput as m, type ConditionPredicate as n, type ConditionedBranch as o, type CountCondition as p, type DuplicateEntityName as q, type EngineError as r, type EngineImpls as s, type EngineRead as t, type EntityDef as u, type EntityHandle as v, type EntityImpl as w, type FieldOptions as x, type Fields as y, type Selection as z };

package/dist/express.d.ts

@@ -1,5 +1,5 @@
 import { Router } from 'express';
-import { E as Engine } from './engine-BfvzXgLg.js';
+import { E as Engine } from './engine-Dv3trweR.js';
 import 'neverthrow';
 import 'zod';