@uniflowed/story 0.0.0-alpha.18

package/collect.js

@@ -0,0 +1,279 @@
+// @flow
+//
+// `@uniflowed/story/collect`: which files are stories, and what is in them.
+//
+// A story file is `_uf.story.js`, beside the component it describes.
+//
+//   src/components/Button.js
+//   src/components/_uf.story.js
+//
+// # The name is the repository's own grammar, not a second one
+//
+// uf already reserves `_uf.<role>[.<variant>].js` for the files the framework
+// gives meaning to, and `crates/uf_router/src/reserved.rs` is its single
+// source of truth: `uf create` generates those names, the router looks for
+// them, and `uf lint`'s `router/reserved-files` rejects the ones that do not
+// fit. A story file is exactly such a file — a name uf assigns meaning to, in
+// a project's own source tree — so it is spelled `_uf.story.js` and not
+// `*.stories.js`.
+//
+// The variants are the same vocabulary for the same reason, and the rule
+// about them is the router's too: only the default variant is the thing the
+// runner renders. `_uf.story.native.js` is a companion for a React Native
+// build, the way `_uf.page.native.js` is, and [`findStoryFiles`] leaves it
+// alone until there is a renderer that could mount it.
+//
+// **`story` is not yet one of the roles the Rust grammar defines.** Adding it
+// is one arm in `ReservedRole` in `crates/uf_router/src/reserved.rs`, and
+// this package cannot make that change from JavaScript. Until it lands,
+// `uf lint` reports `router/reserved-files` on every `_uf.story.js` — the
+// name is right and the linter has not been told. `index.js` lists it under
+// **Readiness** rather than leaving it to be discovered by whoever writes the
+// first story file.
+//
+// # What makes a file a story file is the name, and what makes it valid is
+// the export
+//
+// Discovery is by name alone: a walk that had to read every file to find out
+// whether it declared stories would be a parse of the whole tree. Loading is
+// where a file is judged, and a `_uf.story.js` that exports no story set is
+// an error rather than an empty result — the name is a claim, and a file that
+// does not honour it is a mistake somebody made, not a fact about the
+// project.
+//
+// Every export is considered, not a conventional name and not the default
+// export. A file may hold the stories of two components, and naming them
+// after what they are is better than naming one of them `default`. uf's
+// `react/no-default-export-component` lint rule points the same way.
+//
+// # Why this walk is in JavaScript, and where it stops being acceptable
+//
+// uf's rule is that repository-wide file discovery belongs in Rust, and it is
+// the right rule: `uf test` and the router both discover natively, and both
+// are on the hot path of every keystroke in watch mode. This walk is not that
+// yet. It is bounded work a test or a script asks for once — one `readdir`
+// per directory, no file read, no parse — and it exists because there is no
+// `uf story` command to discover natively *for* it.
+//
+// When one lands, the walk belongs in `uf_router`-shaped Rust beside the
+// route discovery it mirrors, with this left as the loader the host calls
+// with the paths it was given. [`loadStoryFile`] and [`indexStories`] are
+// already separate from [`findStoryFiles`] for that reason: replacing the
+// walk does not touch them.
+
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { Story, StorySet } from "./story.js";
+import { isStorySet } from "./story.js";
+
+/** The role segment a story file carries. */
+export const STORY_ROLE: "story" = "story";
+
+/** The name of a story file with no variant: the one the runner renders. */
+export const STORY_FILE: "_uf.story.js" = "_uf.story.js";
+
+/**
+ * Which build a story file applies to.
+ *
+ * The router's vocabulary, exactly. `"default"` has no segment in the name.
+ */
+export type StoryVariant = "default" | "native" | "ios" | "android" | "web" | "test";
+
+/** The variants, in the order `uf_router::ReservedVariant` declares them. */
+const VARIANTS: $ReadOnlyArray<StoryVariant> = ["native", "ios", "android", "web", "test"];
+
+/** Directory names the walk never descends into. */
+const IGNORED: $ReadOnlyArray<string> = [
+  "node_modules",
+  ".git",
+  ".uf",
+  "dist",
+  "build",
+  "target",
+  "coverage",
+];
+
+/**
+ * The variant of `fileName` as a story file, or `null` if it is not one.
+ *
+ * Takes a file name, not a path, for the reason the Rust classifier does:
+ * a caller with a path can normalise it two ways and get two answers.
+ */
+export function classifyStoryFile(fileName: string): StoryVariant | null {
+  if (!fileName.startsWith("_uf.") || !fileName.endsWith(".js")) {
+    return null;
+  }
+  const segments = fileName.slice("_uf.".length, -".js".length).split(".");
+  if (segments[0] !== STORY_ROLE) {
+    return null;
+  }
+  if (segments.length === 1) {
+    return "default";
+  }
+  if (segments.length > 2) {
+    // `_uf.story.native.test.js`: one variant, not a stack of them.
+    return null;
+  }
+  const variant = VARIANTS.find((each) => each === segments[1]);
+  return variant ?? null;
+}
+
+/**
+ * Whether `fileName` is the story file a renderer mounts.
+ *
+ * The platform variants are companions to a story, never stories of their
+ * own — the same distinction `ReservedVariant::is_route_entry` draws.
+ */
+export function isStoryEntry(fileName: string): boolean {
+  return classifyStoryFile(fileName) === "default";
+}
+
+/** What to leave out of a walk. */
+export type FindOptions = {|
+  /** Directory names to skip, replacing the defaults. */
+  readonly ignore?: $ReadOnlyArray<string>,
+  /**
+   * How deep to descend below `root`. Defaults to 32.
+   *
+   * A bound rather than a promise not to recurse: a directory tree is
+   * untrusted input the moment a generated or vendored directory is in it,
+   * and an unbounded walk is an unbounded stack.
+   */
+  readonly maxDepth?: number,
+|};
+
+/**
+ * Every story file under `root`, as absolute paths, in a stable order.
+ *
+ * Sorted, so a catalogue, a report and a set of baselines come out in the
+ * same order on every machine.
+ *
+ * Symbolic links are not followed. That falls out of asking `readdir` for
+ * directory entries rather than stating it as a rule: an entry describes the
+ * link itself, so a link is neither `isDirectory()` nor `isFile()` and the
+ * walk passes it by. It has to be that way round — a link to a parent is a
+ * walk that does not terminate, and a link into `node_modules` is somebody
+ * else's story file.
+ */
+export async function findStoryFiles(root: string, options?: FindOptions): Promise<Array<string>> {
+  const ignore = new Set(options?.ignore ?? IGNORED);
+  const maxDepth = options?.maxDepth ?? 32;
+  const found: Array<string> = [];
+
+  const walk = async (directory: string, depth: number): Promise<void> => {
+    if (depth > maxDepth) {
+      return;
+    }
+    const entries = (await readdir(directory, { withFileTypes: true })).map((entry) => ({
+      entry,
+      // Flow's Node library definition types `Dirent.name` as `string |
+      // Buffer`, because `readdir` can be asked for buffers. This call does
+      // not ask; the conversion is what says so, rather than a cast that
+      // would be wrong the day somebody adds an encoding.
+      name: typeof entry.name === "string" ? entry.name : entry.name.toString("utf8"),
+    }));
+    entries.sort((left, right) => (left.name < right.name ? -1 : 1));
+
+    for (const { entry, name } of entries) {
+      if (entry.isDirectory()) {
+        if (!ignore.has(name)) {
+          await walk(path.join(directory, name), depth + 1);
+        }
+      } else if (entry.isFile() && isStoryEntry(name)) {
+        found.push(path.join(directory, name));
+      }
+    }
+  };
+
+  await walk(path.resolve(root), 0);
+  return found;
+}
+
+/**
+ * Import `file` and return every story set it exports.
+ *
+ * Throws when it exports none. See the module docs: the name is a claim.
+ *
+ * The import is by `file:` URL rather than by path, because a bare path is
+ * resolved against the *importer* on every host uf supports, and this module
+ * is not where the story file lives.
+ */
+export async function loadStoryFile(file: string): Promise<Array<StorySet>> {
+  const absolute = path.resolve(file);
+  const module = await import(pathToFileURL(absolute).href);
+  const sets: Array<StorySet> = [];
+  for (const name of Object.keys(module)) {
+    const value = module[name];
+    if (isStorySet(value)) {
+      sets.push(value);
+    }
+  }
+  if (sets.length === 0) {
+    throw new Error(`@uniflowed/story: ${absolute} exports no story set`);
+  }
+  return sets;
+}
+
+/** Every story a project declares, and how to reach one. */
+export type StoryIndex = {|
+  /** The files the sets came from, in walk order. */
+  readonly files: $ReadOnlyArray<string>,
+  /** Every set, in the order its file was found. */
+  readonly sets: $ReadOnlyArray<StorySet>,
+  /** Every story in every set, flattened, in declaration order. */
+  readonly stories: $ReadOnlyArray<Story>,
+  /** The story with this id, or `undefined`. */
+  readonly get: (id: string) => Story | void,
+|};
+
+/**
+ * Build an index from files that have already been found.
+ *
+ * Separate from [`collectStories`] so that a host which discovered the files
+ * some other way — natively, from a watcher, from a changed-files list — can
+ * still build the same index.
+ *
+ * Two stories with one id is an error, and it names both files. An id is what
+ * a failing job prints and what a visual baseline is filed under, so a
+ * collision does not produce a confusing result: it produces the *wrong* one,
+ * silently, for whichever of the two was written second.
+ */
+export async function indexStories(files: $ReadOnlyArray<string>): Promise<StoryIndex> {
+  const sets: Array<StorySet> = [];
+  const stories: Array<Story> = [];
+  const byId: Map<string, Story> = new Map();
+  const sources: Map<string, string> = new Map();
+
+  for (const file of files) {
+    for (const set of await loadStoryFile(file)) {
+      sets.push(set);
+      for (const story of set.stories) {
+        const clash = sources.get(story.id);
+        if (clash != null) {
+          throw new Error(
+            `@uniflowed/story: two stories share the id ${story.id}\n` +
+              `  ${clash}\n  ${file}\n` +
+              "Give one of them a different title or name.",
+          );
+        }
+        sources.set(story.id, file);
+        byId.set(story.id, story);
+        stories.push(story);
+      }
+    }
+  }
+
+  return {
+    files: [...files],
+    sets,
+    stories,
+    get: (id: string) => byId.get(id),
+  };
+}
+
+/** Find every story file under `root` and index what they declare. */
+export async function collectStories(root: string, options?: FindOptions): Promise<StoryIndex> {
+  return indexStories(await findStoryFiles(root, options));
+}

package/index.js

@@ -0,0 +1,160 @@
+// @flow
+//
+// `@uniflowed/story`: a named state of a component that a person and a test
+// can both reach.
+//
+// uf already has a test runner, a real DOM, queries a person would recognise,
+// and request mocking. So the question this package has to answer is what a
+// story is still worth once all of that exists — and the answer is not "a
+// nicer way to render a component in a test", because `render(<Button />)`
+// was already that.
+//
+// What a story adds is that the state has a **name outside the file that
+// produced it**. `button--pending` is a thing a CI job can print, a visual
+// baseline can be filed under, a URL can carry and a reviewer can ask for.
+// The props and the setup that state needs are declared once, beside the
+// name, instead of being rebuilt in every test that wants it — and because
+// they are declared as data, the same declaration serves the assertion and
+// the picture.
+//
+//   // src/components/_uf.story.js
+//   export const stories = defineStories({
+//     title: "Button",
+//     component: Button,
+//     props: { label: "Save", pending: false },
+//     stories: {
+//       Primary: {},
+//       Pending: { props: { pending: true } },
+//       Saved: {
+//         mocks: [http.post("/save", () => HttpResponse.json({ ok: true }))],
+//         play: async ({ canvas, user }) => {
+//           await user.click(canvas.getByRole("button", { name: "Save" }));
+//           if ((await canvas.findByRole("status")).textContent !== "Saved") {
+//             throw new Error("the button did not report success");
+//           }
+//         },
+//       },
+//     },
+//   });
+//
+// That file is three things at once: the catalogue entry a person browses,
+// the fixture a test mounts, and — for `Saved` — a test in its own right.
+//
+// # Why this is Flow now
+//
+// It used to be a declaration whose every function returned
+// `nativeRuntimeRequired(…)` behind an opaque `NativeHandle`, which is to say
+// it was a contract with nothing behind it. Nothing here needs to be native
+// and nothing here would be faster if it were: declaring a story builds a
+// closure, rendering one is React's work in a DOM, and playing one is the
+// same event dispatch `@uniflowed/react-testing` already does. The one part
+// of a story system that *is* a hot path — walking a repository to find every
+// story file — is discussed under `collect.js`, which says plainly that the
+// walk belongs in Rust when there is a `uf story` command to own it.
+//
+// So the handle is gone rather than preserved. A story is a value: it can be
+// built, passed, filtered and rendered by ordinary code, which is what makes
+// the same declaration reachable from a test, from a page and from a script.
+//
+// # How the package is laid out
+//
+// Five modules beside this one, split by what each decides:
+//
+// - `story.js` — **declaring**: `defineStories`, what a story inherits from
+//   its set, and where the `Props` type parameter is checked and why it is
+//   then erased. Pure data; declaring a story runs nothing.
+// - `collect.js` — **finding**: `_uf.story.js`, the repository's own reserved
+//   name grammar, the walk, and what makes a story file valid.
+// - `render.js` — **rendering one**: the mock lifetime, the decorators, the
+//   mount, and the markup. Everything here is about *time*.
+// - `play.js` — **driving one**: what a play function is handed, what a step
+//   means, and what a failure inside one says.
+// - `runner.js` — **`@uniflowed/test`**: one test per story. A separate entry
+//   point, so a consumer that does not want the test runner never resolves
+//   it. Not re-exported below, for the same reason.
+//
+// There is no `internal/`. Every module here is a reasonable thing to import
+// on purpose: a documentation build wants `collect.js` and `render.js` and
+// has no use for the runner, and a test wants the runner and never walks a
+// directory.
+//
+// # Readiness
+//
+// **Implemented and tested.** Declaring a component's stories with complete
+// props on the set and a partial override per story, with per-story and
+// per-set decorators, mocks and play functions; names defaulting to the
+// declaration key; stable `title--name` ids. Collecting them: the
+// `_uf.story.js` reserved name with the router's variant vocabulary, a
+// bounded walk that skips `node_modules` and symlinks, loading every story
+// set a file exports, and rejecting two stories that share an id. Rendering
+// one into `@uniflowed/react-testing`'s DOM, with the story's handlers
+// listening before the mount and `globalThis.fetch` put back on unmount, and
+// with the recorded requests exposed. Play functions with a scoped `canvas`,
+// `userEvent`, named steps, and a failure that carries the story id, the step
+// path and the original error. `renderStoryToHtml` for something that is not
+// a test. One `it` per story through `@uniflowed/story/runner`.
+//
+// **Experimental.** The `_uf.story.js` name itself. It follows uf's reserved
+// grammar — `_uf.<role>[.<variant>].js` — but `story` is not yet one of the
+// roles `crates/uf_router/src/reserved.rs` defines, and that file is the
+// grammar's single source of truth for `uf create`, the router and the
+// linter. Until a `story` role is added there, **`uf lint` reports
+// `router/reserved-files` on every `_uf.story.js`**: the name is right and
+// the linter has not been told. The alternative was to invent a second
+// convention (`*.stories.js`) that no uf tool knows about, which is worse.
+//
+// `describeStories` is experimental for a different reason, and it is a
+// property of `uf test` rather than of this package: discovery scans source
+// text for `it(` with a string-literal name, so a file whose only content is
+// a `describeStories` call is skipped — silently, reporting zero files and
+// exiting 0. `runner.js` documents the shape that works today and
+// `storyTest` is the escape hatch.
+//
+// **Not implemented.** There is no `uf story` command, no development server,
+// no browser canvas and no static story site: this package produces the index
+// and the markup those would need, and nothing renders them for a person yet
+// beyond a string. `withBrowser` is deliberately gone rather than carried
+// over — `@uniflowed/browser` is still a declaration whose every function
+// throws, so a story that claimed to drive a real browser would be claiming a
+// capability that does not exist. For the same reason nothing here talks to
+// `@uniflowed/vrt`; `storyId` is exported so that a baseline can be filed
+// under the same name when it does.
+//
+// Also absent, and each for a reason rather than by oversight: no Storybook
+// CSF compatibility, no `argTypes`, controls or knobs (a control panel needs
+// the canvas that does not exist), no MDX or autodocs, no addon protocol, no
+// global decorators or a project-level `preview.js` (a story's setup is
+// declared in the story's own file, where it can be read), no composition of
+// remote catalogues, and no story-level snapshot testing —
+// `@uniflowed/test`'s snapshots work on the string `renderStoryToHtml`
+// returns. Only the default variant of the reserved name is rendered:
+// `_uf.story.native.js` is recognised and skipped, because a React Native
+// renderer does not exist here either. Nothing renders a story through RSC or
+// server rendering; a story mounts on the client, which is what
+// `@uniflowed/react-testing` provides.
+
+export type {
+  Decorator,
+  Story,
+  StoryDeclaration,
+  StoryProps,
+  StorySet,
+  StorySetConfig,
+} from "./story.js";
+export type { FindOptions, StoryIndex, StoryVariant } from "./collect.js";
+export type { PlayContext, PlayFunction, PlayStage, Step } from "./play.js";
+export type { MountedStory } from "./render.js";
+
+export { STORY_SET, defineStories, findStory, isStorySet, storyId } from "./story.js";
+export {
+  STORY_FILE,
+  STORY_ROLE,
+  classifyStoryFile,
+  collectStories,
+  findStoryFiles,
+  indexStories,
+  isStoryEntry,
+  loadStoryFile,
+} from "./collect.js";
+export { StoryPlayError } from "./play.js";
+export { mountStory, renderStoryToHtml } from "./render.js";

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@uniflowed/story",
+  "version": "0.0.0-alpha.18",
+  "description": "Named, rendered states of a component that a person and a test can both reach, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/story"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./collect": "./collect.js",
+    "./play": "./play.js",
+    "./render": "./render.js",
+    "./runner": "./runner.js",
+    "./story": "./story.js"
+  },
+  "files": [
+    "*.js",
+    "!*.test.js"
+  ],
+  "dependencies": {
+    "@uniflowed/mock": "0.0.0-alpha.18",
+    "@uniflowed/react": "0.0.0-alpha.18",
+    "@uniflowed/react-testing": "0.0.0-alpha.18",
+    "@uniflowed/test": "0.0.0-alpha.18"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  }
+}

package/play.js

@@ -0,0 +1,173 @@
+// @flow
+//
+// `@uniflowed/story/play`: the half of a story that makes it a test.
+//
+// A story with props is a picture: it proves the component renders, and
+// nothing about what happens when somebody uses it. A play function is what
+// closes that gap — it is handed the story's own mounted markup and drives it
+// the way a person would, then asserts.
+//
+//   Submitted: {
+//     play: async ({ canvas, user, step }) => {
+//       await step("fills the form", async () => {
+//         await user.type(canvas.getByLabelText("Email"), "a@b.test");
+//       });
+//       await user.click(canvas.getByRole("button", { name: "Save" }));
+//       expect(await canvas.findByRole("status")).toBeTruthy();
+//     },
+//   }
+//
+// This module owns three things: what that function is handed, what a step
+// means, and what a failure inside one says.
+//
+// # The canvas is the story, not the document
+//
+// `canvas` queries the container this story was mounted into, not the whole
+// page. `screen` is still there for a portal — a dialog renders outside its
+// parent by design — but the default is scoped, because a story that finds
+// the *previous* story's button and passes is worse than one that fails.
+//
+// # Steps exist for the failure message
+//
+// A play function that does five things and fails on the fourth reports one
+// assertion error and no account of how it got there. `step` names a stretch
+// of it, so a failure reads `button--submitted > fills the form: unable to
+// find a label "Email"`. Nested steps join with the same separator.
+//
+// Nothing else about a step is special: it does not retry, it does not time
+// out on its own — the test runner already owns the timeout — and it does not
+// group output. It is a label, and a label is what was missing.
+//
+// # No assertion library here
+//
+// A play function asserts with whatever the file it lives in imports:
+// `expect` from `@uniflowed/test` in a test, or a bare `throw` in a story
+// file that must not depend on the runner. This module only reports what came
+// out, so nothing here decides how a project writes an assertion — and a
+// story file stays importable by a tool that has no test runner in it.
+
+import type { Queries } from "@uniflowed/react-testing";
+import { userEvent, within } from "@uniflowed/react-testing";
+
+/** How steps are joined into the label a failure carries. */
+const STEP_SEPARATOR = " > ";
+
+/** A named stretch of a play function. */
+export type Step = (name: string, body: () => mixed) => Promise<void>;
+
+/**
+ * What every play function is handed, minus the props.
+ *
+ * Split out from [`PlayContext`] because it is the part that does not depend
+ * on the story's type parameter — `render.js` builds one of these knowing
+ * only a DOM node, and `story.js` closes over the typed props to complete it.
+ */
+export type PlayStage = {|
+  /** The element this story was mounted into. */
+  readonly container: Element,
+  /** Queries scoped to `container`. */
+  readonly canvas: Queries,
+  /** What a person did: click, type, tab, hover. */
+  readonly user: typeof userEvent,
+  /** Name a stretch of the play, so a failure says where it was. */
+  readonly step: Step,
+|};
+
+/** What a play function declared on a typed story set is handed. */
+export type PlayContext<Props> = {|
+  ...PlayStage,
+  /** The props this story was rendered with. */
+  readonly props: Props,
+|};
+
+/**
+ * A play function with its story's props already inside it.
+ *
+ * This is the shape a resolved [`Story`](./story.js) holds: `story.js` wraps
+ * the caller's typed function so that everything downstream can call it with
+ * a stage and nothing else.
+ */
+export type PlayFunction = (stage: PlayStage) => mixed;
+
+/**
+ * A play function's failure, told where it happened.
+ *
+ * The original message is kept in full and the original error in `cause`,
+ * because the useful half of an assertion failure is the assertion's own
+ * account of what it expected. What this adds is the story id and the step
+ * path, which the assertion cannot know.
+ */
+export class StoryPlayError extends Error {
+  /** The story that was playing. */
+  readonly story: string;
+  /** The step path, or `null` when the failure was outside every step. */
+  readonly step: string | null;
+
+  constructor(story: string, step: string | null, cause: mixed) {
+    const where = step == null ? story : `${story}${STEP_SEPARATOR}${step}`;
+    super(`${where}: ${messageOf(cause)}`);
+    this.name = "StoryPlayError";
+    this.story = story;
+    this.step = step;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Build the stage for a story mounted into `container`.
+ *
+ * The `step` this returns writes into `path`, which [`runPlay`] reads when
+ * something throws. A step that fails leaves its name in place on purpose:
+ * the failure is reported from the innermost step that was running, not from
+ * wherever the stack happened to unwind to.
+ */
+export function createStage(container: Element): {|
+  readonly stage: PlayStage,
+  readonly stepPath: () => string | null,
+|} {
+  const path: Array<string> = [];
+
+  const step: Step = async (name, body) => {
+    path.push(name);
+    await Promise.resolve(body());
+    path.pop();
+  };
+
+  return {
+    stage: {
+      container,
+      canvas: within(container),
+      user: userEvent,
+      step,
+    },
+    stepPath: () => (path.length === 0 ? null : path.join(STEP_SEPARATOR)),
+  };
+}
+
+/**
+ * Run `play` for the story called `story`, on `stage`.
+ *
+ * Always awaits, even for a synchronous play function, so that a play that
+ * grows an `await` later does not change when its failure surfaces —
+ * a synchronous throw and a rejected promise both arrive here.
+ */
+export async function runPlay(
+  play: PlayFunction,
+  story: string,
+  stage: PlayStage,
+  stepPath: () => string | null,
+): Promise<void> {
+  try {
+    await Promise.resolve(play(stage));
+  } catch (error) {
+    throw new StoryPlayError(story, stepPath(), error);
+  }
+}
+
+/** What `error` says, whatever it is. */
+function messageOf(error: mixed): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

package/render.js

@@ -0,0 +1,211 @@
+// @flow
+//
+// `@uniflowed/story/render`: putting one story on screen, and taking it down.
+//
+// Everything about a story that involves *time* is here: when its handlers
+// start intercepting, when React mounts it, when its play function runs, and
+// what is put back afterwards. `story.js` is data and this is the lifetime.
+//
+//   const mounted = mountStory(findStory(buttonStories, "Pending"));
+//   try {
+//     expect(mounted.canvas.getByRole("button")).toBeDisabled();
+//     await mounted.play();
+//   } finally {
+//     mounted.unmount();
+//   }
+//
+// # One renderer, for the test and for the person
+//
+// A story that only a bespoke UI can render is a story nobody runs in CI, so
+// there is exactly one path here and both callers take it. `@uniflowed/test`
+// reaches it through [`mountStory`] and asserts on `canvas`;
+// [`renderStoryToHtml`] is the same mount, serialised, which is what a static
+// story page or a review artefact needs. Neither is a second implementation
+// of the first, so neither can drift from it.
+//
+// The DOM is `@uniflowed/react-testing`'s — a real document, installed on
+// first render, with React told it is under test so an unwrapped update is
+// still reported. A story therefore mounts the same way a component test
+// does, on Node.js, Bun or Deno, with nothing configured.
+//
+// # Mocks start before the mount, and stop after the unmount
+//
+// A component that fetches does it in an effect, and `render` flushes effects
+// before it returns — so a registry installed after the mount would miss the
+// first request every time. It is installed first, and closed by `unmount`,
+// which is also what puts the platform's `fetch` back.
+//
+// A story that declares no handlers installs **no** interception at all. It
+// is not given an empty registry that rejects everything: a story with no
+// mocks reaches the network exactly as the application would, which is the
+// honest default and the only one that leaves `passthrough` meaning
+// something. A story that *does* declare handlers gets
+// `@uniflowed/mock`'s own default, `onUnhandledRequest: "error"` — having
+// said what this story talks to, a request to anything else is a finding.
+//
+// # Decorators wrap outside-in
+//
+// The set's decorators are applied around the story's, and within each list
+// the first written is the outermost. `[withTheme, withRouter]` reads as
+// theme outside router, and that is what it does.
+
+import { mock } from "@uniflowed/mock";
+import type { MockRegistry, RecordedRequest } from "@uniflowed/mock";
+import type * as React from "@uniflowed/react";
+import type { Queries } from "@uniflowed/react-testing";
+import { render } from "@uniflowed/react-testing";
+
+import { createStage, runPlay } from "./play.js";
+import type { Decorator, Story } from "./story.js";
+
+/** A story on screen, and everything a caller can do with it. */
+export type MountedStory = {|
+  /** The story that was mounted. */
+  readonly story: Story,
+  /** The element it was mounted into. */
+  readonly container: Element,
+  /** Queries scoped to `container`. */
+  readonly canvas: Queries,
+  /**
+   * Requests this story made, in request order.
+   *
+   * The registry's live log, not a copy, so a caller that holds on to it
+   * across an interaction sees what the interaction asked for. Empty and
+   * permanently so when the story declares no handlers — nothing is watching.
+   */
+  readonly requests: $ReadOnlyArray<RecordedRequest>,
+  /**
+   * Run the story's play function, if it has one.
+   *
+   * Resolves immediately when it has none, so a caller never has to ask.
+   * Throws a [`StoryPlayError`](./play.js) naming the story and the step.
+   */
+  readonly play: () => Promise<void>,
+  /** The story's markup, as it stands. */
+  readonly html: () => string,
+  /** Take it down and stop intercepting. Safe to call twice. */
+  readonly unmount: () => void,
+|};
+
+/**
+ * Mount `story` and hand back what it produced.
+ *
+ * Synchronous, because mounting is: `render` wraps the work in React's `act`,
+ * which runs the render, the effects and the microtasks React queued before
+ * it returns. What a story's effects then *await* — a request, a timer — is
+ * not finished, which is what `findBy…` and [`MountedStory.play`] are for.
+ *
+ * Mounting a second story takes the first down: `@uniflowed/react-testing`
+ * cleans up before it renders, and a document holding two stories makes
+ * "there is one Save button" false for reasons that have nothing to do with
+ * the story being read.
+ */
+/**
+ * The registry the last mounted story installed, if it had one.
+ *
+ * `installFetch` refuses to nest, so a second story with mocks cannot listen
+ * while the first is still listening — and a test that mounts and asserts
+ * without unmounting is the ordinary shape, so "the caller will unmount" is
+ * not something this can rely on. Mounting closes whatever is still
+ * installed, exactly as `@uniflowed/react-testing` takes down the tree the
+ * story before it left.
+ */
+let active: MockRegistry | null = null;
+
+export function mountStory(story: Story): MountedStory {
+  active?.close();
+  active = null;
+
+  const registry = story.mocks.length > 0 ? mock(...story.mocks) : null;
+  if (registry != null) {
+    registry.listen();
+    active = registry;
+  }
+
+  let result;
+  try {
+    result = render(decorate(story.element(), story.decorators));
+  } catch (error) {
+    // The registry is listening and the story never mounted, so nothing will
+    // ever call `unmount`. Leaving it installed would hand the *next* story a
+    // `globalThis.fetch` belonging to a story that failed to render, and
+    // `listen()` refuses to nest — so the next mount would fail with an
+    // unrelated message.
+    registry?.close();
+    if (active === registry) {
+      active = null;
+    }
+    throw error;
+  }
+
+  const { stage, stepPath } = createStage(result.container);
+  let live = true;
+
+  return {
+    story,
+    container: result.container,
+    canvas: stage.canvas,
+    requests: registry?.requests ?? [],
+    play: async () => {
+      if (story.play != null) {
+        await runPlay(story.play, story.id, stage, stepPath);
+      }
+    },
+    html: () => result.asFragment(),
+    unmount: () => {
+      if (!live) {
+        return;
+      }
+      live = false;
+      result.unmount();
+      registry?.close();
+      // Only when it is still this story's: a late unmount must not take away
+      // the registry a story mounted afterwards is using.
+      if (active === registry) {
+        active = null;
+      }
+    },
+  };
+}
+
+/**
+ * The story's markup, for something that is not a test.
+ *
+ * A static story page, a review artefact, a diff in a pull request: all of
+ * them need the same string, and none of them should mount React themselves.
+ *
+ * `play` is off by default. The markup of a story *as declared* is what a
+ * catalogue shows; the markup after it has been driven is a different and
+ * equally useful picture, and the caller is the one who knows which they
+ * meant.
+ */
+export async function renderStoryToHtml(
+  story: Story,
+  options?: {| readonly play?: boolean |},
+): Promise<string> {
+  const mounted = mountStory(story);
+  try {
+    if (options?.play === true) {
+      await mounted.play();
+    }
+    return mounted.html();
+  } finally {
+    mounted.unmount();
+  }
+}
+
+/**
+ * Wrap `node` in `decorators`, first outermost.
+ *
+ * Applied back to front so that `decorators[0]` ends up furthest from the
+ * component. A `reduceRight` would say the same thing in one line and
+ * allocate an intermediate for each step; a story is rendered per assertion
+ * in a watch loop, so the loop stays.
+ */
+function decorate(node: React.Node, decorators: $ReadOnlyArray<Decorator>): React.Node {
+  let wrapped = node;
+  for (let index = decorators.length - 1; index >= 0; index -= 1) {
+    wrapped = decorators[index](wrapped);
+  }
+  return wrapped;
+}

package/runner.js

@@ -0,0 +1,93 @@
+// @flow
+//
+// `@uniflowed/story/runner`: stories as tests `uf test` runs.
+//
+// A story is already a rendered state with its setup declared beside it. This
+// module is the twenty lines that turn that into test results, so a project
+// does not write the same mount-play-unmount block once per story.
+//
+//   import { describe, it } from "@uniflowed/test";
+//   import { describeStories, storyTest } from "@uniflowed/story/runner";
+//   import { stories } from "./_uf.story.js";
+//
+//   it("renders every Button story", storyTest(findStory(stories, "Primary")));
+//   describe("Button", () => {
+//     describeStories(stories);
+//   });
+//
+// # Why this is a separate entry point
+//
+// It is the only module in the package that imports `@uniflowed/test`.
+// Everything else — declaring, collecting, rendering — works with no test
+// runner in the process, which is what lets a story file be imported by a
+// documentation build or a story page. Putting the bridge behind
+// `@uniflowed/story/runner` means a consumer that does not want the runner
+// never resolves it. `@uniflowed/form/validator` is the same arrangement for
+// the same reason.
+//
+// # A mount is already an assertion
+//
+// A story with no play function still fails when the component throws, when a
+// required prop is missing at runtime, when an effect rejects, or when it
+// requests something its handlers do not cover — `mountStory` installs the
+// story's mocks with `onUnhandledRequest: "error"`. That is a real test, and
+// it is the one Storybook calls a smoke test. A play function is what turns
+// it from "it rendered" into "it works".
+//
+// # What `uf test` can and cannot see here
+//
+// `uf test` discovers test declarations by scanning source text for `it(` and
+// `describe(` with a **string literal** first argument, and a file with no
+// such declaration is not run at all. [`describeStories`] registers its cases
+// from the set, so their names are not literals — which means a file whose
+// only content is a `describeStories` call is skipped silently, reported as
+// zero files and zero tests, and exits 0.
+//
+// So a story test file must contain at least one literal declaration, and the
+// shape above is the recommended one: a literal `describe` is not enough,
+// because discovery counts only `it` and `test`. Once the file is picked up,
+// every case [`describeStories`] registered runs and is reported normally —
+// the worker runs what the file registered, not what discovery predicted.
+//
+// [`storyTest`] exists for the other half of that: it returns the body, so a
+// project that wants one literally named test per story can write one and
+// keep `uf test -t` able to select it.
+
+import { describe, it } from "@uniflowed/test";
+
+import { mountStory } from "./render.js";
+import type { Story, StorySet } from "./story.js";
+
+/**
+ * The body of one story's test: mount it, play it, take it down.
+ *
+ * The unmount is in a `finally` because a failed assertion inside a play
+ * function would otherwise leave the story mounted and its handlers
+ * installed — and `@uniflowed/mock` refuses to nest, so the *next* story
+ * would fail with a message about interception rather than about itself.
+ */
+export function storyTest(story: Story): () => Promise<void> {
+  return async () => {
+    const mounted = mountStory(story);
+    try {
+      await mounted.play();
+    } finally {
+      mounted.unmount();
+    }
+  };
+}
+
+/**
+ * Register one test per story in `set`, under a suite named after it.
+ *
+ * Read the module docs before relying on this as a file's only content: the
+ * names come from the set rather than from source text, so `uf test` will not
+ * discover the file on its own.
+ */
+export function describeStories(set: StorySet): void {
+  describe(set.title, () => {
+    for (const story of set.stories) {
+      it(story.name, storyTest(story));
+    }
+  });
+}

package/story.js

@@ -0,0 +1,293 @@
+// @flow
+//
+// `@uniflowed/story/story`: declaring a component's states, as data.
+//
+// A story is a name, a component, and the props that put it in one state.
+// Declaring one runs nothing, mounts nothing and touches no global: this
+// module is entirely value-level, so importing a story file is cheap and a
+// story catalogue can be built by a tool that has no DOM.
+//
+//   export const stories = defineStories({
+//     title: "Button",
+//     component: Button,
+//     props: { label: "Save", pending: false },
+//     stories: {
+//       Primary: {},
+//       Pending: { props: { pending: true } },
+//     },
+//   });
+//
+// # A set carries complete props; a story is a delta
+//
+// [`StorySetConfig.props`] is `Props`, not `Partial<Props>`, and each story's
+// own `props` is the partial one. That is the whole of the inheritance rule,
+// and it is what makes "every story in this set renders" true by construction
+// rather than by hope: there is no way to declare a story whose props are
+// incomplete, because the set already supplied them.
+//
+// Storybook allows partial `args` at both levels and finds out at render time
+// which component ended up without a required one. uf has a type checker; a
+// missing prop is a type error at the declaration, in the file that made the
+// mistake.
+//
+// They are called `props` rather than `args` because that is what they are.
+// uf is a React toolchain, the value is spread onto a React component, and a
+// second word for props would only be a word to translate.
+//
+// # Where the type parameter earns its keep, and where it stops
+//
+// `defineStories` is generic in `Props`, and that is where every check
+// happens: `component` must accept them, the set's `props` must be complete
+// for it, each story's overrides must be a subset of the same shape, and a
+// `play` function is handed a context whose `props` field is `Props`.
+//
+// [`Story`] and [`StorySet`] are *not* generic. A catalogue holds the stories
+// of many components, and those have no common type parameter — a
+// `StorySet<Props>` is neither covariant nor contravariant in `Props`, because
+// `props` reads it and `component` and `play` consume it. Keeping the
+// parameter would mean an `any` at the point where the catalogue is built,
+// and this package does not use `any`. So the parameter is checked at the
+// declaration and erased into the catalogue: [`Story.props`] is
+// [`StoryProps`], and [`Story.element`] is a closure that already has the
+// typed props inside it, applied to the typed component. Nothing downstream
+// can get the pairing wrong, because nothing downstream can see the two
+// halves separately.
+//
+// # Identity
+//
+// A story's [`Story.id`] is `<title>--<name>`, slugified. It is the name a
+// failing CI job prints, the name a visual-regression baseline is filed
+// under, and the name a URL would carry — so it has to be stable under
+// re-ordering, safe in a path, and derived from what a person wrote rather
+// than from a counter. Two stories that slugify to one id are rejected by
+// `collect.js`, which is the only place that can see both.
+
+import type { MockHandler } from "@uniflowed/mock";
+import type * as React from "@uniflowed/react";
+
+import type { PlayContext, PlayFunction, PlayStage } from "./play.js";
+
+/**
+ * A story's props once the type parameter is gone.
+ *
+ * `mixed`, not `any`: a consumer showing a story's props in a panel has to
+ * narrow each one, which is correct — it genuinely does not know what they
+ * are.
+ */
+export type StoryProps = { readonly [string]: mixed };
+
+/**
+ * Something wrapped around a story before it is mounted.
+ *
+ * A theme provider, a router context, a fixed-width frame. It takes the node
+ * rather than a render function because there is nothing else useful to give
+ * it: React already defers the work, and a decorator that could choose *not*
+ * to call its child would be a decorator that can silently render nothing.
+ */
+export type Decorator = (children: React.Node) => React.Node;
+
+/** One named state, as the caller writes it. */
+export type StoryDeclaration<Props extends { ... }> = {|
+  /**
+   * What a person calls this state. Defaults to the key it was declared
+   * under, which is usually already the right words.
+   */
+  readonly name?: string,
+  /** What differs from the set's props. */
+  readonly props?: Partial<Props>,
+  /** Wrapped inside the set's decorators. */
+  readonly decorators?: $ReadOnlyArray<Decorator>,
+  /** Offered before the set's, so a story can override one of them. */
+  readonly mocks?: $ReadOnlyArray<MockHandler>,
+  /** Drives this state and asserts on it. Replaces the set's `play`. */
+  readonly play?: (context: PlayContext<Props>) => mixed,
+|};
+
+/** A component's stories, as the caller writes them. */
+export type StorySetConfig<Props extends { ... }> = {|
+  /** What the component is called. `"Forms/Button"` groups it. */
+  readonly title: string,
+  /**
+   * The component every story in the set renders.
+   *
+   * `component(...Props)` rather than `component(...Props) renders X`: a
+   * story renders whatever its component renders, and constraining that here
+   * would be this package having an opinion about a component it was handed.
+   */
+  readonly component: component(...Props),
+  /** Complete props, so every story below is renderable. */
+  readonly props: Props,
+  /** Wrapped around every story, outside the story's own decorators. */
+  readonly decorators?: $ReadOnlyArray<Decorator>,
+  /** In force for every story in the set, behind the story's own. */
+  readonly mocks?: $ReadOnlyArray<MockHandler>,
+  /** Run for every story that does not declare its own. */
+  readonly play?: (context: PlayContext<Props>) => mixed,
+  /**
+   * The states, in declaration order.
+   *
+   * An object rather than an array because the key is the story's identity —
+   * it is what a test names and what an id is built from — and an array of
+   * `{ name, … }` records makes that a field somebody can forget.
+   */
+  readonly stories: { readonly [key: string]: StoryDeclaration<Props> },
+|};
+
+/** One story, resolved: everything it needs to be rendered, and nothing else. */
+export type Story = {|
+  /** `"button--pending"`. Stable, path-safe, and derived from what was written. */
+  readonly id: string,
+  /** The key it was declared under. */
+  readonly key: string,
+  /** What a person calls it. */
+  readonly name: string,
+  /** The set's title, repeated here so a story is self-describing. */
+  readonly title: string,
+  /** The set's props with this story's overrides applied, erased to `mixed`. */
+  readonly props: StoryProps,
+  /** The set's decorators, then this story's. First is outermost. */
+  readonly decorators: $ReadOnlyArray<Decorator>,
+  /**
+   * This story's handlers, then the set's.
+   *
+   * That way round because `@uniflowed/mock` offers a request to handlers in
+   * order and the first that matches answers it: a story that declares
+   * `GET /users/:id` overrides the set's handler for the same route, which is
+   * what a story called `Missing` is for.
+   */
+  readonly mocks: $ReadOnlyArray<MockHandler>,
+  /** What drives it, or `null`. */
+  readonly play: PlayFunction | null,
+  /**
+   * The element, built on demand.
+   *
+   * A function rather than a node so that declaring a thousand stories costs
+   * a thousand closures rather than a thousand React elements, and so a story
+   * rendered twice gets two elements rather than one shared one.
+   */
+  readonly element: () => React.Node,
+|};
+
+/**
+ * The brand [`isStorySet`] looks for.
+ *
+ * A string rather than a class or a `Symbol()`, because the check has to hold
+ * across two copies of this package in one process — a linked workspace
+ * beside a nested install is the ordinary way that happens — and `instanceof`
+ * does not.
+ */
+export const STORY_SET: "uniflowed/story-set" = "uniflowed/story-set";
+
+/** A component's stories, resolved. */
+export type StorySet = {|
+  readonly kind: typeof STORY_SET,
+  readonly title: string,
+  readonly stories: $ReadOnlyArray<Story>,
+|};
+
+/**
+ * Resolve a component's stories.
+ *
+ * Everything is computed here: inheritance, names, ids and the element
+ * closures. A [`StorySet`] is therefore inert data — the reason a tool can
+ * import a story file to list what is in it without a DOM, a runner or a
+ * network.
+ *
+ * Throws when the set is empty. A story file that declares no stories is a
+ * file somebody meant to finish, and reporting it as zero stories hides that
+ * at exactly the moment it is cheap to notice.
+ */
+export function defineStories<Props extends { ... }>(config: StorySetConfig<Props>): StorySet {
+  const keys = Object.keys(config.stories);
+  if (keys.length === 0) {
+    throw new Error(`@uniflowed/story: ${config.title} declares no stories`);
+  }
+
+  const Component = config.component;
+  const stories = keys.map((key) => {
+    const declaration = config.stories[key];
+    const name = declaration.name ?? key;
+    // Spread rather than `Object.assign`: the result is a new object each
+    // time, so no story can reach another's props, and Flow reads the spread
+    // of a `Partial<Props>` over a `Props` as `Props` — which is what makes
+    // the element below check.
+    const props: Props = { ...config.props, ...declaration.props };
+    const declaredPlay = declaration.play ?? config.play;
+
+    return {
+      id: storyId(config.title, name),
+      key,
+      name,
+      props,
+      title: config.title,
+      decorators: [...(config.decorators ?? []), ...(declaration.decorators ?? [])],
+      mocks: [...(declaration.mocks ?? []), ...(config.mocks ?? [])],
+      // The one place the type parameter crosses into the erased world, and it
+      // crosses without a cast: `props` is still `Props` in this scope, so the
+      // context handed to the caller's function is a real `PlayContext<Props>`
+      // and the closure that remains is `PlayFunction`.
+      play: declaredPlay == null ? null : (stage: PlayStage) => declaredPlay({ ...stage, props }),
+      element: () => <Component {...props} />,
+    };
+  });
+
+  return { kind: STORY_SET, title: config.title, stories };
+}
+
+/**
+ * The id `title` and `name` produce.
+ *
+ * Exported because a visual-regression baseline, a URL and a report all have
+ * to agree on it, and each computing its own would agree until the day one of
+ * them handled a slash differently.
+ */
+export function storyId(title: string, name: string): string {
+  return `${slugify(title)}--${slugify(name)}`;
+}
+
+/**
+ * `"Forms/Text Field"` becomes `"forms-text-field"`.
+ *
+ * Lowercase, and every run of anything else becomes a single dash. That loses
+ * information — `"A/B"` and `"A B"` are one slug — which is why duplicate ids
+ * are an error where they can be seen rather than a silent overwrite.
+ */
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** Whether `value` is a [`StorySet`]. */
+export function isStorySet(value: mixed): boolean {
+  return (
+    typeof value === "object" &&
+    value != null &&
+    value.kind === STORY_SET &&
+    Array.isArray(value.stories)
+  );
+}
+
+/**
+ * The story in `set` under `key`, or named `name`.
+ *
+ * Throws rather than returning `undefined`, and says what the set does hold.
+ * The caller is a test naming a story it believes exists; handing it `void`
+ * turns a renamed story into a `TypeError` three lines later, in the runner
+ * rather than in the test.
+ */
+export function findStory(set: StorySet, key: string): Story {
+  // A key first, then a name. Both are looked up because a story's name is
+  // what a report prints and a key is what the file says — but a set where
+  // one story's *name* is another story's *key* would otherwise answer with
+  // whichever came first in the file, and mount the wrong component.
+  const found =
+    set.stories.find((story) => story.key === key) ??
+    set.stories.find((story) => story.name === key);
+  if (found == null) {
+    const known = set.stories.map((story) => story.key).join(", ");
+    throw new Error(`@uniflowed/story: ${set.title} has no story ${key}; it has ${known}`);
+  }
+  return found;
+}