@trypattern/sdk 0.1.38 → 0.1.39

package/docs/look.md

@@ -0,0 +1,147 @@
+# The look: primitives, theme, tokens and icons
+
+The look is Pattern's, and everything on screen is drawn by its primitives from
+`@trypattern/sdk/react`. An app changes the look through its theme, never by restyling a primitive.
+
+## Frame
+
+- `AppFrame`: the sidebar, phone drawer and page panel, for a signed-in area, from `links` and the
+  layout model's commands (it adds Log out). A link's `count` shows beside it, and
+  `countTone: 'attention'` makes it a solid blue badge for something waiting, whatever the brand
+  colour. Following a sidebar link closes the phone drawer by itself.
+  - `look="plain"`: a white sidebar with the app's name, its links and the signed-in person at the
+    bottom, whose menu is `accountMenu`.
+  - `look="shell"` (the default): a grey frame with the page inset, a top bar and a `workspaceMenu`
+    at the top.
+- `Screen` follows the frame's look; in the plain look it is a heading with `title`, an optional
+  `eyebrow` line above it or a `parent` link, `actions` beside it, and the page below in a column
+  `width` `xs` to `lg` or `full` (`md` by default). On a phone it shows the button that opens the
+  drawer.
+- Also `SignInScreen` (a ready-made sign-in page), `CommandPalette` and `Toaster`.
+
+## Layout
+
+- `Content` (the centred page column, `width` `xs` to `lg` or `full`), `Stack` (a column) and `Row`
+  (side by side), each with `gap` and `padding` named from `space` (`gap="md"`).
+- `Card`: with `to` the whole card is a link, and then `hover="zoom"` gently zooms its photo,
+  `hover="outline"` darkens its edge and `isPressable` presses it in, all still for people who turn
+  motion off; `surface="none"` for one with no background, like a photo tile.
+- `Divider` (with `label="or"` for a labelled one), `SettingsRow` (a title and description beside a
+  control, stacked on phones), `PropertyRow` (a label and its value, side by side on every screen).
+- `ListRow`: a row that opens a page with `to`, another site with `href`, or runs `onClick`;
+  `leading`, `trailing`, `size` `sm` (a list beside the page, which shades on hover), `md` or `lg`
+  (rows in a card, which stay still), and `isCurrent` on the one showing.
+- `TableRow`: a row of a table that opens something: `label`, `isCurrent` on the open one, `onClick`,
+  and `size="lg"` for two-line rows.
+- `EmptyState` (a message and an action, centred), `LoadingRows` (`count` placeholder rows while a
+  list loads) and `Form` (hands `onSubmit` the fields' values).
+- `Header` wraps a site's top bar so it stays at the top of the page, clear at the top and frosted
+  with a hairline once scrolled, above the page and below menus and dialogs.
+
+## Words
+
+- `Text` with a `variant`:
+  - for a website: `hero` (the home page's big line), `display` (a page's title), `section` (a
+    section's heading), `intro` (the line under the hero) and `lead` (the site's 15px body text);
+  - everywhere: `heading`, `subheading`, `title`, `label`, `body` (small print), `caption` and
+    `code`.
+
+  Also a `tone` (`primary`, `secondary`, `tertiary`, `brand`, `danger`, `positive`, `warning`, or
+  `inherit`), `weight` (`normal`, `medium`, `semibold`, `bold`, `heavy`) for emphasis, `as` (`p`,
+  `h1`, `h2`, `h3`) for screen readers, `align`, `isTruncated` and `isSelectable`.
+
+- `Link` is words that go somewhere: `to="/flowers"` for a page here, `href="https://…"` for
+  another site (it opens in a new tab), and `Button` takes either too. `Link` and `Badge` take
+  `tone="positive"` for something live or done.
+- `Appear` wraps something that shows up after the page opens (a button once there is something to
+  act on): it fades in without moving what is already there.
+
+## Controls
+
+- `Button` (with `to` it opens a page). A full-width `Button` (`isFullWidth`) centres its label;
+  `align="start"` puts it at the start.
+- `ContinueWithGoogle` (the Google sign-in button, with Google's logo), `AppearancePicker` (Light,
+  Dark or System; apps start light).
+- `IconButton` (`variant="primary"` for a brand-coloured one, `shape="round"`).
+- `Calendar`: a month of `open`, `closed` and `full` (crossed-out) days; `weekStart="sunday"` starts
+  its weeks on Sunday. It fills the width it is given.
+- `TextField`, `Select` (its `label` is read aloud only; `isLabelHidden={false}` shows it above,
+  like a `TextField`'s), `Switch`.
+- `Checkbox` (a round tick, or `shape="square"`; its `label` is for screen readers).
+- `SegmentedControl` (an option's `count` shows beside its label).
+- `RadioGroup`: a card of choices, each with a `label`, optional `description` (a second line),
+  `badge`, `content` and `trailing`, and `isDisabled`; `size="lg"` for a roomier one, like an item's
+  sizes.
+- `ChoiceGroup`: a row of `Choice`s, words with a `title` and `subline`, or photos, like an item's
+  thumbnails.
+- `CopyButton` (copies `text` and says Copied).
+- `Menu` and `ContextMenu`: entries run `onSelect` or open a page with `to`, with an `icon` or a
+  `mark` (the first letter of a name in a small brand tile, as for switching between businesses).
+- `Dialog`: `placement="sheet"` is a bottom sheet on phones, with a grab handle to drag it closed,
+  and a centred dialog on a computer; keep a close button in it. Its content scrolls by itself when
+  taller than the screen; to keep a header and footer in place, put the middle in a `ScrollArea`
+  between them.
+- `Tooltip` and `Kbd`.
+- `Image` (a photo from the `media` table; `origin` shows one from another site).
+- `Gallery`: several photos one at a time, swipe on phones, arrows on hover on a computer, dots and
+  an "N of M" count. `value`/`onChange` take the shown photo's id, and on phones it runs edge to edge
+  when given negative `marginInline` equal to the page gutter.
+- `Avatar`, `Badge`, `Icon` (with a `tone`, and `weight="light"` for a thinner line), `Spinner`,
+  `ScrollArea`.
+- `Skeleton`: `text="heading"`, `"lead"`, `"label"` or another `Text` variant takes exactly one line
+  of that text, so a page that is loading has the same layout as once it has loaded. Draw loading in
+  the final layout, never a separate loader first.
+- `FilePicker`: a drop zone with a button that picks a file (`title`, `hint`, `buttonLabel`,
+  `accept`, the file types); `onPick` hands a command the file as plain data, `{ id, name, type, size }`,
+  so the model checks its type and size and a server call sends it. `FilePreview` shows a picked
+  photo straight away, before it uploads (`file`, `alt`). `ProgressBar` (`label` and `value` from 0
+  to 1) shows an upload.
+
+## Rules for controls and styles
+
+- Controls take closed choices: `variant` (`primary`, `secondary`, `tertiary`, `transparent`),
+  `tone` (`neutral`, `brand`, `danger`) and `size` (`xs` to `xl`). A `primary` button is the brand
+  colour unless it says `tone="neutral"`, so a brand colour shows everywhere at once; the same `size`
+  is the same height for a button, a field and a select, so a row lines up.
+- A primitive's `style` prop takes placement only (`alignSelf`, `flexGrow`, margins, `minWidth`, and
+  `display: 'none'` to hide it at a breakpoint). Its colors, sizes, states and motion are not the
+  app's to change.
+- A screen has no styles, no tokens and no plain elements: it arranges primitives and the app's
+  pieces.
+- A piece in `src/components/<Name>/` may draw a shape no primitive gives (a booking calendar, a
+  photo grid) with `stylex.create`, where every value is a token from
+  `@trypattern/sdk/tokens.stylex`: `space.*` for paddings, gaps and margins, and `controls.*`,
+  `iconSizes.*` or `widths.*` for sizes. Words are `<Text>`, anything clickable is a primitive, and
+  nothing changes on hover (hover effects are the primitives' own, like `Card`'s `hover`). Such a
+  piece is listed as the app's own in its design system.
+- Never write `<button>`, `<input>`, `<p>`, `<h1>`, words loose in a `<div>`, or `onClick` on a
+  `<div>`: use the primitive, and if none fits, the gap is in Pattern.
+- There is one breakpoint, `breakpoints.compact` (phone width), and no hand cursor: both are
+  Pattern's choice.
+
+## Theme
+
+An app changes the look in two files, and `src/main.tsx` hands both to
+`startApp(App, { theme, icons })`.
+
+- `src/theme/theme.ts` re-values tokens with `stylex.createTheme`:
+  - `colors`, each as `light-dark(light, dark)`. This is the only file where raw colors are allowed.
+  - `radii`, and `corners`: `buttonMd`, `fieldMd` and the other sizes are buttons' and fields'
+    corners, which follow `radii` until set, so pill buttons can sit beside squarer fields;
+    `checkbox` is a square `Checkbox`'s corner, 4px whatever `radii` says.
+  - `fonts`: `sans` for words, `heading` for the hero, display, section, heading and subheading
+    variants, `mono` for code. Load a font by adding its `@fontsource` package and importing it in
+    `src/index.css`.
+  - `fontWeights` (`heading` is the headings' weight) and `trackings` (letter spacing).
+  - `shadows`, and the size scales `space`, `fontSizes`, `lineHeights`, `controls`, `iconSizes`,
+    `borders` and `widths` to make the whole app roomier or tighter; every `Text` variant and
+    control moves with them. `fontSizes.bodyCompact` and `lineHeights.bodyCompact` are the body and
+    label size on phones; set them to the desktop size to keep text from growing there.
+  - Sizes are whole pixels, and `app check` refuses a theme where text would clip or a scale
+    shrinks.
+- The business's own named colours go in `src/theme/colors.stylex.ts`,
+  `export const brand = stylex.defineVars({ sage: 'light-dark(#e3ebe0, #1f2a1d)' })`, and a piece
+  uses `brand.sage`; keep `colors.*` for what they mean (`warning` stays a warning).
+- `src/theme/icons.ts` adds the app's icons with `defineIcons({ name: 'M5 12h14' })`: a path is
+  drawn as a 2px line, and `{ fill: '...' }` is filled. Several paths are drawn as one shape, so
+  lines don't darken where they meet.

package/docs/requests.md

@@ -0,0 +1,115 @@
+# Requests: forms, bookings and owner emails
+
+Requests are what people send for the owner to answer: bookings, forms (orders, quotes, contact messages, early-access requests) and anything your own server code takes in, like a custom checkout. Each kind is a request source. For every one, Pattern saves the request, emails the owner straight away (with the visitor as reply-to and a link to it), keeps trying until that email goes through, and lists it on onpattern.app under Requests. There the owner accepts or declines a booking, replies, marks it done or runs one of your source's own actions. Your part is to declare the source and build the visitor's side. Never build an admin page for requests, and never write an "email the owner" step.
+
+## Forms: `inquiry()`
+
+- A form's rows live in the app's own table, whose `create` access is `'server'` and which has no status column: whether it's answered is Pattern's.
+- Declare it in `schema.ts`: `export const orders = inquiry(tables.requests, { source: 'orders', title: 'Flower order', form: 'Order form', name: 'name', email: 'email', fields: { date: 'Wanted by', budget: 'Budget' }, summary: 'budget', message: 'message', when: { field: 'date', detail: 'Delivery, any time' } })`.
+  - `title` names one request and `form` the form it came from.
+  - `fields` are the columns the owner sees, with their labels, and `summary` the one shown in the list.
+  - `when` is the date column, if there is one.
+- Serve it with `inquiries([orders])` in `server/worker.ts`'s `blocks`, and send it from a model with `await this.stores.inquiries.send('orders', { name, email, … })`, which returns `'saved'` or another outcome to show a toast for.
+- A second form is a second table and a second `inquiry()`, listed in the same `inquiries([...])`.
+- A site with forms and no bookings adds `...requestTables` from `@trypattern/sdk/schema` to `tables` (bookings already include them); `app migration` then creates them.
+- Flows fake sending: `world.inquiries.sent` lists what was sent, and `stores.inquiries.sent` is the last one.
+
+## Bookings
+
+The bookings block is a request source of its own: each booking request reaches the owner like any other request, with Accept and Decline.
+
+- Wire it in three places: `blocks: [bookings]` in `src/App.ts`, `bookings({ timezone })` in `server/worker.ts` and `...bookingTables` in `schema.ts`.
+- The block decides what is available; the app's components decide what it looks like. `this.stores.bookings` has `loadDays(month)`, `loadWindows(date)` and `request(fields)`, and `state.days` and `state.windows` hold the answers. Show them with the `Calendar` primitive, a list of days or a single date field, but never work out availability yourself.
+- Opening hours are the `bookingRules` row. Flows fake the block with `world.bookings`.
+
+## Drafts from Claude
+
+`app requests` lists the live site's requests, and `app requests draft <source/id> --text '…' --asked '<their words>'` writes a reply for the owner, who reads it on onpattern.app and presses Send. Nothing reaches the visitor until they do. Deciding, marking done and running actions are the owner's, on onpattern.app.
+
+## Your own server code
+
+When your own server code takes something in that the owner should answer (a custom checkout, a quote calculator), declare it as a request source and record each request in the same batch as its row.
+
+### 1. Declare the source
+
+In `schema.ts`, next to the table that holds the rows:
+
+```ts
+import { requestSource } from '@trypattern/sdk/server'
+
+export const rentals = requestSource(tables.rentals, {
+  source: 'rentals',
+  kind: 'booking',
+  title: 'Rental booking',
+  form: 'Checkout',
+  name: 'name',
+  email: 'email',
+  fields: { chairs: 'Chairs', eventDate: 'Event day' },
+  summary: 'chairs',
+  when: { field: 'eventDate', detail: 'Pickup the day before' },
+  actions: {
+    markFulfilled: {
+      label: 'Mark fulfilled',
+      resolves: true,
+      can: (row) => row['stage'] === 'paid',
+      run: ({ d1, id }) => [
+        d1
+          .prepare(
+            "UPDATE rentals SET stage = 'fulfilled' WHERE id = ?1 AND stage = 'paid'"
+          )
+          .bind(id)
+      ]
+    }
+  }
+})
+```
+
+- `source` is a stable camelCase id. Never rename it once the site is live.
+- The table's `create` access is `'server'`: only your server code adds rows, so every row is also a request.
+- `title`, `form`, `name`, `email`, `fields`, `summary`, `message` and `when` say how the request reads in the list and the side sheet, as for `inquiry()`.
+- Every request can always be answered with **Reply** (an email from the dashboard) and **Mark done**. Don't declare those.
+- `actions` adds the decisions only your business has:
+  - `accept` and `decline` keep their usual buttons. Pattern emails the customer that the owner confirmed or declined.
+  - Any other camelCase name is a custom action: `label` is the words on its button, and `resolves` says whether it finishes the request (`true`) or leaves it open (`false`). Custom actions send no email.
+  - `can(row)` says whether the button shows for this row right now. Pattern asks again just before running it.
+  - `run({ d1, id, row })` returns the D1 statements that make the change. Each statement must change at least one row, or the whole action is undone and the owner sees "That can't be done to this request now". Write the business check into the statement itself (`WHERE stage = 'paid'`), so a change that happened in between stops it.
+
+### 2. Serve it
+
+In `server/worker.ts`, add the block, and add `...requestTables` to `tables` in `schema.ts` if it isn't there yet (then run `app migration`):
+
+```ts
+import { createServer, requestSources } from '@trypattern/sdk/server'
+import { rentals } from '../schema.ts'
+
+export default createServer({
+  tables,
+  admins,
+  blocks: [requestSources([rentals])]
+})
+```
+
+### 3. Record each request in the same batch as its row
+
+```ts
+import { deliverRequestNotices, recordRequest } from '@trypattern/sdk/server'
+
+const id = `rental-${checkoutKey}`
+const row = { id, name, email, chairs, eventDate, stage: 'paid' }
+await c.env.DB.batch([
+  c.env.DB.prepare(
+    'INSERT INTO rentals (id, name, email, chairs, event_date, stage) VALUES (?1, ?2, ?3, ?4, ?5, ?6)'
+  ).bind(id, name, email, chairs, eventDate, 'paid'),
+  ...recordRequest(c, rentals, row)
+])
+await deliverRequestNotices(c)
+```
+
+- The row, the request, its history and the owner's email are saved together: if the batch fails, none of them exist.
+- The row's `id` is the idempotency key. Derive it from something stable, like the checkout's own key, so a retried checkout records one request and sends one email.
+- `deliverRequestNotices(c)` sends the owner's email after the response. If it can't be sent, Pattern keeps trying on its own, without waiting for another visit, and the dashboard shows the failure.
+
+### What Claude may and may not do
+
+- Claude reads requests and drafts replies with `app requests`. Only the owner, signed in on onpattern.app, can send a reply or run an action.
+- An action with an effect outside the database, like refunding a Stripe payment, needs a durable job with its own pending, succeeded and failed states. It can't happen inside `run`, because a database batch can't include Stripe. Don't present a refund as `decline`. Payment state comes only from verified Stripe events.

package/docs/state.md

@@ -0,0 +1,142 @@
+# State: stores, models, actions, screens and flows
+
+A Pattern app is a React + TypeScript single-page app (Vite, React Router in data mode, StyleX and
+the components from `@trypattern/sdk/react`). State flows through four layers, and each reads only
+the one below it:
+
+```
+network → service → STORE → MODEL → SCREEN
+          (Pattern)  data,   state,   reads one model
+                     cached  answers,
+                             commands
+                                ↑
+                             ACTIONS   menu entries and shortcuts that send commands
+flows, ⌘K, shortcuts and `app send` change things only through commands on models
+```
+
+## Code conventions
+
+- Import project files by their path from the project root: `@/src/models/Item.ts`,
+  `@/schema.ts`. Only a file in the same folder may be `./File.ts`. Export only what another file
+  imports, and import things from where they are defined, never through a file that re-exports
+  them.
+- Let TypeScript infer return types. Write one only on functions exported from `src/lib/`, which
+  several files rely on, and where TypeScript asks for it (a function that calls itself).
+
+## Stores
+
+`src/stores/<Name>.ts`, listed in `src/stores/index.ts`: state several models share.
+
+- Pattern gives every table in `schema.ts` a store of the same name (`items`: `items`, `status`,
+  `pending`; `load()`, `create()`, `update()`, `remove()`, cached in the browser per person), and a
+  read-only `public<Table>` store for a table with `public` columns.
+- Built-in stores: `session` (the signed-in user), `actions` (everything the command menu and
+  keyboard shortcuts can do right now, worked out by the files in `src/actions/`), `toasts` (messages
+  on screen: `this.stores.toasts.show({ tone: 'error', title: 'Couldn’t save' })`, with `neutral`,
+  `success` or `error`), `page` (the open page and its address values) and `device`
+  (`state.today`, today's date as `'2026-10-18'`, kept current past midnight, and
+  `state.isCompact`, whether the screen is phone width).
+- Your own are `class X extends Store({ state, persist })` with plain methods. A store calls the
+  app's own server calls through `this.services`, typed for this app.
+
+## Models
+
+`src/models/<Name>.ts`, listed in `src/models/index.ts` under its page's route id.
+
+- `class X extends Model({ state, persist })`, or `Model()` with neither. `state` fields are zod
+  schemas with `.default()`; `persist` lists fields kept in this browser across reloads (never on the
+  server). Every store is there as `this.stores.<name>`.
+- A model shows three kinds of public member: getters are its answers, worked out from its state and
+  stores (`public get hasNext()`); `command()` fields are what it can do
+  (`public openNext = command(() => ...)`, or `command({ input: { ... } }, (input) => ...)`); and
+  `onPageOpen(params)` runs when its page opens, which can happen twice for one visit (signed out,
+  then again after sign-in), so it only ever loads and never assumes it ran once.
+- `this.params` holds the open page's address values (`this.params['itemId']` on
+  `/flowers/:itemId`), so a detail page answers `get itemId()` from it rather than copying it into
+  state. A model behind sign-in reads `this.stores.session.state.user` rather than assuming someone
+  is signed in.
+- Everything else is `private`, and a helper is a private method, never a getter.
+- A getter is pure: it works its answer out from `this.state` and `this.stores.<name>.state` only,
+  returns plain JSON, and never changes anything, waits, or reads the clock, randomness or a private
+  field. Pattern caches each getter until something it read changes, so an answer several getters
+  need is its own getter (`public get neighbours()`). Today's date and phone width come from the
+  `device` store, so getters can use both.
+- Every model can call `this.app.navigate(path)`. Models never call or read other models: share
+  state through a store, and share work through a function in `src/lib/`. A model knows nothing
+  about menus or which page is open.
+
+## Actions
+
+`src/actions/<thing>.ts`, listed in `src/actions/index.ts`. If a person can see it in a menu or
+press a key for it, it is an action; what it does is a command.
+
+- One file per thing the actions act on (`navigation.ts`), each
+  `export const navigationActions = defineActions(({ page, models }) => [...])` returning entries
+  built with `action()` from `@trypattern/sdk`: an id, a label, a group, an icon, optional keys and
+  the commands it sends.
+- `page` is the open page's route id and `models.<name>` is that model's state and answers, so an
+  entry shows only when it applies (`models.item.hasNext && action(...)`). Actions that belong to
+  one page say so, `defineActions({ page: 'item' }, ({ models }) => [...])`, and Pattern offers them
+  only while that page is open.
+- An actions file is pure like a getter, and Pattern reruns it only when something it read changes.
+  The ⌘K menu orders entries by the `actionGroups` list in `src/actions/index.ts`, and a group not in
+  that list is a type error.
+- Pattern listens for the keys itself: an action's `keys` are a single key (`['c']`), a sequence
+  (`['g', 'i']`) or a combo with ⌘ on a Mac and Ctrl elsewhere (`['mod+k']`), and `isHidden: true`
+  keeps a shortcut-only action out of the menu.
+
+## Screens and layouts
+
+- A screen (`src/screens/<Name>Screen.tsx`) reads one model, `const item = useModel('item')` from
+  `@trypattern/sdk/react`, shows `item.sizes` and calls `item.chooseSize()`. It never reads a store;
+  if it needs something, add a getter to the model. A screen arranges primitives and has no styles
+  of its own (see [the look](look.md)).
+- Pieces only one screen uses go in `src/components/<Name>/` and take props; only screens and layouts
+  call `useModel`. Pass a model's commands straight to list rows (`onDelete={list.deleteItem}`), not
+  a new arrow function, so rows only redraw when their own data changes.
+- Layouts (`src/layouts/<Name>Layout.tsx`) are the frames pages render inside, and they are the
+  app's own: any layout it likes, built from primitives. Every route sits under `AppLayout`; an area
+  that needs its own frame or sign-in is a nested layout route (a `Component` with `children` and no
+  `path`). `AppLayout` renders `<Toaster />` once, which `app check` requires.
+- `src/App.ts` lists the `tables`, `stores`, `models`, `routes`, `actions` and `actionGroups`; a
+  route's `id` names the page (`page: 'item'` in the snapshot) and opens the model with the same
+  name.
+- Pattern reads the app's types from `src/models/index.ts`, `schema.ts`, `src/stores/index.ts`,
+  `src/routes.tsx`, `src/actions/index.ts` (the action groups) and `src/theme/icons.ts` (the icon
+  names), so `Model`, `defineActions`, `action`, `AppStores`, `AppSnapshot`, `AppPath` (every path
+  the routes allow), `IconName` and `useModel` are typed for this app with nothing to declare.
+- A new page: add `src/screens/<Name>Screen.tsx`, a route with an `id` in `src/routes.tsx`, and
+  `src/models/<Name>.ts` registered under that `id` in `src/models/index.ts`.
+
+## Built in
+
+Every app gets four models and the stores above without listing them, and may not reuse their
+names:
+
+- `account` (`user`, `appearance`; `setAppearance`, `signOut`);
+- `appSettings` (`title`, `canRename`, `isRenaming`; `rename`);
+- `palette`, the ⌘K command menu (`isOpen`, `query`, `results`; `open`, `toggle`, `setQuery`, `run`);
+- `signIn`, the sign-in steps (`continueWithGoogle`, the email code steps and the dev-only
+  `signInAsDevUser`).
+
+Pattern applies `account.appearance` to the page and offers the appearance switches, Log out and ⌘K
+as actions in the `Preferences` and `Account` groups. The app's name is data, not code: `title` in
+the `settings` table of the app's own database, served at `/api/app` and shown by the sidebar, the
+sign-in screen and the browser tab. Admins rename the app in Settings, which needs no publish.
+
+## Flows
+
+- Behaviour is tested with flows, not a browser: `flows/<Name>.flow.ts` sends commands (as
+  `{ type: 'item.chooseSize', id: 'bouquets-large' }`, or the built-in
+  `{ type: 'app.navigate', to: '/flowers' }`) and checks the app snapshot:
+  `{ page, path, models: { <model>: state and getters }, stores: { ... } }`.
+- `app test` runs them in about a second. A new feature gets a command and a flow. `flows/flow.ts`
+  hands the flow runner the app; it fakes the server from `schema.ts` and `seed.ts`.
+- Flows sign in as ada@acme.test by default (`{ signedInAs: null }` for a signed-out flow), and the
+  emailed sign-in code is always 123456.
+- `{ hold: '<service call>' }` and `{ release: '…' }` pause a server call, so a flow can check the
+  loading state; `world` fakes what the server knows.
+- Flows check what actions are offered with `expect: { stores: { actions: { items: ... } } }`, and
+  press a key with `{ send: { type: 'app.pressKey', key: 'j' } }`.
+- Never expect the app's own name in a flow: every site has its own title, so a flow that renames
+  it checks the new name instead.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@trypattern/sdk",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "type": "module",
   "files": [
     "dist",
+    "docs",
     "presets"
   ],
   "bin": {
@@ -95,11 +96,11 @@
     "trailingComma": "none"
   },
   "scripts": {
-    "check": "tsc -p . && oxlint -c oxlint.sdk.json src/components src/hooks src/theme && node tests/check-types.ts && vitest run --root tests/server && prettier --check src tests presets *.json",
+    "check": "tsc -p . && oxlint -c oxlint.sdk.json src/components src/hooks src/theme && node tests/check-types.ts && vitest run --root tests/server && prettier --check src tests presets docs *.json",
     "typecheck": "tsc -p .",
     "test:types": "node tests/check-types.ts",
     "test:server": "vitest run --root tests/server",
-    "format": "prettier --write src tests presets *.json",
+    "format": "prettier --write src tests presets docs *.json",
     "lint": "oxlint -c oxlint.sdk.json src/components src/hooks src/theme",
     "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/theme/reset.css dist/theme/reset.css"
   }