@appsolutely-io/waypoint 0.0.0-stage → 0.1.1-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appsolutely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,261 @@
-# Temporary Holding Version
+# waypoint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MIT-licensed package for conversations that propose, confirm and run requests. The core is framework-free; React and antd are optional peers. No request runs merely because a flow or model proposed it.
+
+## Using the package
+
+```sh
+npm install @appsolutely-io/waypoint@next
+```
+
+Only pre-releases are published so far, under the `next` dist-tag. Pin the exact version: a pre-release may change shape before the next one.
+
+```ts
+import {
+  createWaypointClient,
+  createSseTransport,
+} from "@appsolutely-io/waypoint";
+
+const client = createWaypointClient({
+  accountId: "example-account",
+  conversationId: "example-conversation",
+  platform, // Inject clock, online, visibility and ids from your application.
+  transport: createSseTransport(request, stream),
+  storage, // Optional StoragePort; synchronous and asynchronous ports work.
+});
+await client.ready;
+await client.setDraft("Rename the item");
+await client.send();
+```
+
+`request` and `stream` are application adapters. They retain the application's authentication, CSRF and API error handling. The core itself reads no browser global. Dispose each client when its owning screen ends. A storage key includes the account and conversation; pass a separate port when clients must also have separate persistence.
+
+Startup negotiation and the first conversation read each have a 10-second budget, and reading the optional storage (at most 1 second) runs alongside negotiation, so `ready` settles within 20 seconds. A failed start reports `sign-in` for an authentication refusal (an HTTP 401), `update-required` only for an incompatible protocol, and `unavailable` for anything else. One retry owner per client then retries an `unavailable` start after 1, 2, 4, 8 and 16 seconds and every 30 seconds after that, skipping attempts while `online()` or `visibility()` is false. It also retries at once when the optional `subscribeOnline` or `subscribeVisibility` callback reports that the application is back online or visible, and when the application calls `client.refresh()`. A `sign-in` start waits for one of those signals; an `update-required` start retries only on `client.refresh()`. A transient first read is retried the same way; a 404 or 410 read is final. Retrying never resends a message or reply and never confirms or runs a plan. Storage that answers after its budget adds its saved rows without replacing a draft or pending row the user already has.
+
+```tsx
+import { WaypointChat } from "@appsolutely-io/waypoint/react";
+import { antdSkin } from "@appsolutely-io/waypoint/skin-antd";
+import "@appsolutely-io/waypoint/styles.css";
+
+<WaypointChat
+  client={client}
+  {...antdSkin}
+  layout="panel"
+  colorScheme="dark"
+/>;
+```
+
+Omit the skin for neutral controls. `@appsolutely-io/waypoint/skin-default` exports the neutral token values. Importing core requires no UI peer. `/testing` additionally needs React, React DOM and Testing Library; install those only when using that helper.
+
+## Preview locally
+
+In a checkout of this repository:
+
+```sh
+npm ci
+npm run playground
+```
+
+Open http://127.0.0.1:43300/. The local server prints the URL and does not open a browser. The toolbar switches between neutral and Ant Design controls, light/dark/system colour schemes, layouts, direction, and the shipped languages. Choose a conversation, AI form fill, saved requests, or a long transcript with its message outline. The right-to-left option mirrors the layout using the selected language’s text. The mock server streams an answer to every message. The reply state choice (`?state=`) opens a fresh conversation that reaches one state on load: `streaming`, `done`, `stopped`, `versions`, `tools`, `sources`, `overdue`, `reply-failed`, `reply-unavailable`, a refused send for each problem code (`error-retryable`, `error-rate-limited` and so on), `plan` and `form`. Settings stay in the URL for sharing and reloading. All demo data uses the local mock server; the playground is excluded from the published package.
+
+Set `PLAYGROUND_PORT` to an integer from 1024 to 65535 to use another local port (for example, `PLAYGROUND_PORT=43301 npm run playground`).
+
+## Extending waypoint
+
+Every client owns its state, listeners, streams and send failures. Providers change rendering without replacing that state. These extension points are public:
+
+| Extension point        | Example                                                                                                                                                                                                                             |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createWaypointClient` | `createWaypointClient({ accountId, conversationId, platform, transport })`                                                                                                                                                          |
+| `PlatformPorts`        | `platform: { clock, online: () => true, visibility: () => true, ids }`; optional `subscribeOnline` / `subscribeVisibility`                                                                                                          |
+| `MessageVersionPort`   | `versions: { edit, regenerate, select }`; message actions refetch the authoritative sibling after the host operation; the host draws the controls ([docs/message-versions.md](docs/message-versions.md))                            |
+| `StoragePort`          | `storage: { get, set, remove }`; each operation may return a promise                                                                                                                                                                |
+| `transport`            | `createSseTransport(request, stream)`, `createFetchStreamTransport(request, stream)` or `createSignalTransport(request, stream)`                                                                                                    |
+| State subscriptions    | `const unsubscribe = client.subscribe(() => draw(client.getSnapshot()))`                                                                                                                                                            |
+| Typed events           | `client.on(event => recordId(event.type, event))`; events contain ids, never field values                                                                                                                                           |
+| `beforeSend`           | `beforeSend: async reply => permitted ? { ...reply, content: rewritten } : false`                                                                                                                                                   |
+| `ComposerContribution` | `contributions: [{ id: 'example', evaluate: () => ({ hold, hint, payload }) }]`                                                                                                                                                     |
+| Plan execution         | `plans: { read, request, heartbeat, intent?, stepUp? }`; `stepUp` returns one ephemeral code or cancellation                                                                                                                        |
+| Plan recovery          | `plans: { ...runnerPorts, intent }`; protected controls use stored intent results; optional legacy `resume` / `retryUndo` remain adapter-driven                                                                                     |
+| `FlowSource`           | `flowSource: { list, setFavourite, run }`, `tabs: ['presets', 'favourites']`                                                                                                                                                        |
+| Parsed flow documents  | Add `flowSource.load: id => fetchDocument(id)` and `flowOperations: ['items.update']`; `run(id, values, document)` receives validated JSON without loading YAML                                                                     |
+| Headless React         | `useConversation`, `useComposer`, `usePlan`, `useFlows` inside `WaypointProvider`, or pass a client directly to each hook                                                                                                           |
+| Renderer-neutral hooks | `usePlanView(client)` and `useBlockReply(client)` from `/hooks` (also from `/react`): the plan's presses and the one-answer-per-card lock, as message keys, with React only and no DOM; see [A UI of your own](#a-ui-of-your-own)   |
+| Plan step names        | `planLabels={{ resource: key => names[key], field: (resource, key) => fields[resource]?.[key] }}`; steps are numbered ("Task 1", "Task 2"), an unnamed step shows "Change 1" and an unnamed field "Value 1", never its internal key |
+| Theme tokens           | `theme: { accent: '#245ad1' }`; `themeProperties(theme)` derives CSS custom properties from the same typed source                                                                                                                   |
+| Direction and scheme   | `locale="zh-CN" dir="rtl" colorScheme="dark"`; `colorScheme` is host-driven and preserves state                                                                                                                                     |
+| Layout                 | `layout="panel"`, `"page"`, `"floating"` or `"sheet"`; container queries respond to the instance's available width                                                                                                                  |
+| Slots                  | `slots={{ composer: props => <MyComposer {...props} /> }}`; `messageActions`, `extraPanels` and `stepUpPrompt` are also regions                                                                                                     |
+| Provider replacement   | `parts={{ bubble: MyBubble }}` replaces that part everywhere                                                                                                                                                                        |
+| Control replacement    | `primitives={{ button: MyButton, textarea: MyTextarea }}`; input, checkbox, datePicker and drawer are replaceable too                                                                                                               |
+| Widget registry        | `widgets={[{ type: 'example/status', render: StatusWidget }]}`; standard entries use the explicit `standardWidgets` array                                                                                                           |
+| Markdown               | `renderers={{ markdown: MyMarkdown }}` (`renderers.markdown`); the default renderer is lazy, disables raw HTML and allows only approved link schemes                                                                                |
+| Problem presentation   | `problemText={problem => ({ text: explain(problem.code), action: recovery })}` over the closed problem union                                                                                                                        |
+| Messages               | `format={(key, values) => catalogue.format(key, values)}`; typed keys, ICU plurals, English and Simplified Chinese defaults                                                                                                         |
+| Feature selection      | `features={['widgets', 'flows']}` intersects the negotiated capabilities; unknown capabilities are off                                                                                                                              |
+| Shortcuts              | `shortcuts={{ focusComposer: '/', send: false }}`; each shortcut can be disabled and focus stays within the chat                                                                                                                    |
+| Skin wrapper           | `wrapper={MyThemeProvider}` receives the scheme and resolved tokens; the antd wrapper maps dark mode to its dark algorithm                                                                                                          |
+| Skin testing           | `renderWithWaypoint(element, { client, skin })`, `defineSkinContract`, `defineOverrideContract`, `defineAccessibilityContract` from `/testing`                                                                                      |
+
+A slot or replacement receives presentation props and callbacks. The client remains the behavior owner. Answering a card answers the whole card and disables it in place while the answer is in flight. Whether a card is answered is the host's to say (see **Card answers** below): after every answer, accepted, refused or lost, the client reads the conversation and shows the card as the host reports it, answered or open, and focus goes back to the pressed answer when the card is open, or to the composer when it is answered. A card the host accepted an answer for stays answered even if that read fails; the failed read shows its Retry. An answered card says "Answered: Accept" when the host names an action of the card in its `answer`, and "Answered" otherwise. An answer refused because the card was already answered, in another tab or an earlier page, says "This question was already answered." instead of the generic refusal. Widget types unknown to the client show their fallback with update guidance and cannot submit a reply. Tokens are scoped to the instance root, never the document root.
+
+### A UI of your own
+
+A host that draws its own UI, React Native included, uses the hooks from `/hooks` and formats the keys they return with `/messages` and the language it needs; nothing else of the web chat is loaded:
+
+```tsx
+import { usePlanView } from "@appsolutely-io/waypoint/hooks";
+import { createFormatter } from "@appsolutely-io/waypoint/messages";
+import en from "@appsolutely-io/waypoint/messages/en";
+
+const t = createFormatter("en", en);
+
+function PlanActions({ client }) {
+  const { view, press } = usePlanView(client);
+  return view?.actions.map((entry) => (
+    <Button
+      key={entry.id}
+      disabled={!entry.available}
+      onPress={() => press(entry.id)}
+    >
+      {entry.countedLabelKey && entry.labelValues
+        ? t(entry.countedLabelKey, entry.labelValues)
+        : t(entry.labelKey)}
+    </Button>
+  ));
+}
+```
+
+Each language is its own entry (`/messages/en`, `/messages/zh-Hans`), so a host ships only the text it shows; a host with its own wording passes its own catalogue. A key the catalogue lacks throws in development and shows the key itself in production. `stepName(t, planLabels, step)` names a plan step the way the web chat does. `problemView(problem)` gives a problem's words (`key`), its one action (`retry` or `refresh`, worded `chat.retry` and `chat.problem.refresh`) and the `code` and `id` the chat shows behind "Details"; `replyRowView(snapshot.replyState, { canStop: client.canStopReply(), canRetry: client.canRetryReply() })` gives the reply row's words and its buttons (Stop, Keep waiting, Retry), each wired to the client method of the same name (`retry` is `retryReply()`).
+
+### Part data
+
+Each part receives a copy of its own data as `data`, typed by its name (`PartData`, `PartDataMap`; `PartProps<"stepRow">` for one part). Parts not listed receive none.
+
+| Part                 | `data`                                                                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `bubble`             | `{ message }` (`id`, `role`, `content`, `status`, `versionIndex`, `versionCount`, `blocks`) or `{ pending }` for a message being sent |
+| `messageActions`     | `{ message }` (`id`, `role`, `status`, `versionIndex`, `versionCount`)                                                                |
+| `widgetFrame`        | `{ block }` (`id`, `type`, `answered`)                                                                                                |
+| `failedSendControls` | `{ pending }` (`id`, `content`, `failure`: `{ code }` or `null`)                                                                      |
+| `composer`           | `{ sending }`                                                                                                                         |
+| `confirmBar`         | `{ view, actions }`: the plan view and the actions the bar shows                                                                      |
+| `confirmation`       | `{ confirmation }`: the host's confirmation record                                                                                    |
+| `planNode`           | `{ view }`                                                                                                                            |
+| `stepRow`            | `{ step }` (`id`, `operation`, `resource`, `view`, `tier`, `undo`, `stepUp`)                                                          |
+| `stepUpPrompt`       | `{ stepUpCount }`                                                                                                                     |
+| `recoveryPanel`      | `{ view }`                                                                                                                            |
+| `stepStatusRow`      | `{ step }` (`stepId`, `index`, `resource`, `truth`, `textKey`): name it with `stepName(format, planLabels, step)`                     |
+| `recoveryActions`    | `{ actions }`                                                                                                                         |
+
+`FlowSource` defaults to favourites, most-used, recent, presets, in that order, and initially chooses the first nonempty tab. An explicit selection survives subsequent reads. The source owns favourite status and usage; the client does not infer them. `load` optionally returns a parsed `Flow` matching `schema.json`. Both YAML and JSON paths use `validateFlowDocument`; `bindFlow` binds parameters, and `run` asks the host for a proposal. This path never bypasses confirmation or executes arbitrary flow requests directly.
+
+The runner sends the confirmed canonical method, path and body unchanged, adds `Waypoint-Step`, and retains `If-Match`. A transient `stepUpCode` is supplied separately to the application's request adapter; add it only to the outgoing write's verification field, never to the stored canonical request or logs. Outcomes and undo requests come from the server. Stop inhibits local dispatch and reads the recorded outcomes; protected plans additionally submit a fenced terminal intent. Neither Stop nor interruption automatically requests Undo. A heartbeat or browser loss needs authoritative readback; forward writes are never automatically retried. Scheduled plans are handed to the application's scheduling adapter and never run browser writes.
+
+Integrations not included in this release:
+
+- Form-popup images use the injected `PrivateAttachmentPort` upload/remove adapter. General composer attachments remain an unimplemented seam through the protocol `AttachmentPort` and `ComposerContribution`.
+- The command/mention registry: **seam exists, not implemented**. Contributions supply hints, hold decisions and payloads; no registry implementation ships.
+- The `/element` custom-element wrapper: **seam exists, not implemented**. The framework-free `subscribe` / `getSnapshot` contract can drive a future wrapper; there is no `/element` export.
+- A React Native UI: **seam exists, not implemented**. The core's injected platform/storage/transport ports require no DOM, and the `/hooks` entry gives a native UI the plan presses and the card answer lock; native rendering is outside this package.
+- **Not implemented yet:** continuing a plan's remaining steps, selected undo and continuing a confirmed undo, decision time limits, per-account plan capacity and its account screen, account deletion handling, background recovery checks and operator diagnostics, scheduled-work recovery, execution identity across windows, custom step kinds and the conformance scenarios for these.
+
+## Versions and distribution
+
+The protocol version is independent of the package version. `SUPPORTED_PROTOCOLS` currently contains `1.1` and `1.0`; negotiation selects a supported version and capability list. Additive optional fields belong to protocol minor versions. An incompatible version returns the typed update problem. A package release can change UI or tooling without changing the protocol.
+
+For the package, a **0.x minor = breaking** release; patch releases preserve its public API. Public changes carry a Changeset and an updated API Extractor report. Deprecated APIs retain `@deprecated` for at least one minor release and issue a development-mode warning before removal. `RunnerPorts.stop` is deprecated and no longer called by the runner; guard any direct call because the port is now optional.
+
+The package is published to npm with prebuilt `dist`. There are no install/prepare lifecycle builds. `npm run release-build` generates and verifies the artifact, and `prepublishOnly` runs it before every publish; it does not commit, tag, push or publish by itself. Local consumer verification uses an equivalent packed prebuilt artifact, with both npm and pnpm, and verifies installed file hashes and all explicit exports.
+
+The **initial core** has its own budget, set in `.size-limit.cjs` and checked by `npm run size`. Lazy recovery code has separate caps and an additional deduplicated aggregate regression guard allowing 3% above the measured size, rounded down. The **parser chunk** keeps its separate 15 kB cap; parsing a server-supplied JSON flow avoids YAML entirely. React, the renderer-neutral hooks, CSS, skins, testing and the schema retain their approved limits in `.size-limit.cjs`. Run `npm run size` for current measurements. See [the measurement method and package checks](docs/plan-protocol.md#packaging-acceptance).
+
+### Upgrading
+
+For the full list of breaking changes and host duties, see [CHANGELOG Upgrading](CHANGELOG.md#upgrading).
+
+**Shortcut scope.** Remove `shortcuts.global`; it is deprecated and ignored. The composer focus shortcut acts only while focus is inside the chat and outside an editable field.
+
+The [plan protocol guide](docs/plan-protocol.md) describes the implemented host contract, delivery uncertainty, packaging checks and quality backlog. The following adapter changes are additive unless identified as replacements:
+
+| Before                                                                                       | Now                                                         | Consumer action                                                                                                                                                 |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RunnerPorts.stop(id): Promise<PlanRecord>`                                                  | `stop?(id): Promise<PlanRecord>` (deprecated)               | Guard direct calls with `ports.stop?.(id)`; the runner never calls it or automatically requests Undo.                                                           |
+| `heartbeat(id)`                                                                              | `heartbeat(id, acceptance?)`                                | Forward the optional protected execution identity to the host's renewal check.                                                                                  |
+| `PlanRunner.run(id, confirmedDigest)`                                                        | `run(id, confirmedDigest, acceptance?)`                     | Protected runs require the first accepted confirmation's private `ExecutionAcceptance`; legacy calls remain valid.                                              |
+| `TransportPort.send(...): Promise<{ id: string }>`                                           | `Promise<ReplyDelivery>` (`{ id, acceptance? }`)            | Preserve private acceptance in the adapter response; `client.reply()` still returns `Promise<boolean>`.                                                         |
+| `negotiate(supported)`                                                                       | `negotiate(supported, offer?)`                              | Forward the offer; host helper `negotiate(supported, capabilities)` becomes `negotiate(supported, capabilities, offer)` for binding.                            |
+| `read(conversationId)`, `send(reply, conversationId)`, `subscribe(conversationId, listener)` | Same calls with optional final `ReaderRequestContext`       | Forward the per-client agreement without storing shared mutable context.                                                                                        |
+| `RunnerPorts.read(id)`                                                                       | `read(id, context?)`                                        | Forward its optional reader agreement context too.                                                                                                              |
+| No protected terminal-intent adapter                                                         | `intent?(request: IntentRequest): Promise<PlanIntentReply>` | Add the authenticated safety-control route and durable host state described below; old adapters remain assignable and protected plans are read-only without it. |
+| `runFlow(id, values): Promise<void>`                                                         | `Promise<string \| void>`                                   | Use the loaded conversation id when returned; a refused or superseded navigation returns no id, and a rejected operation may throw.                             |
+
+`stopPlan`, `resumePlan` and `retryUndo` retain their public names. Optional legacy `plans.resume(id)` and `plans.retryUndo(id)` signatures remain supported and adapter-driven; they are not protected continuation APIs. This release's delivery types are `ReplyDelivery` and `PlanIntentReply`; it does not export `ControlDeliveryReply`. `IntentOverlay` exposes pending delivery, not authority. Custom snapshots carry intent overlays/notices/alerts and `planReadOnly`; consumers that implement their own client follow the current API report rather than assuming an older snapshot shape.
+
+**Host adoption.** Persist generations, reviews, execution/fence state, intent slots, rounds, evidence and final receipts atomically and durably. Validate ownership and scope from stored records, enforce streaming body limits, fence old admissions/commits, preserve exact confirmation replay, and refuse legacy stop for protected plans. Forward negotiation offers and contexts. Keep conformance controls isolated and audit production routing independently. Custom reads use trusted host manifests/templates and project only declared low-tier fields; a stream cannot select its own trusted template. Account quota, principal deletion, custom step registries, scheduled-work recovery and their lifecycle controls are not included in this release. The guide records the identity non-reuse duty and the released-before-deletion receipt limitation without claiming those missing controls ship.
+
+**Guarded field parts.** A custom `fieldAdornment` part previously received `{ disabled, onPress }`; it now also receives `{ "aria-disabled", describedBy }` on `PartProps`. Forward those as `aria-disabled` and `aria-describedby` while reserving native `disabled` for the existing disabled state; a guarded action must remain focusable, and its `onPress` is absent while guarded.
+
+**Form catalogues.** `MessageKey` now includes `keyof FormCatalogue` (also exported as `FormMessageKey`). Consumers with exhaustive `Record<MessageKey, string>` dictionaries or formatters add these form keys or a fallback; `FormCatalogue` contains the lazy form extras' messages.
+
+**Form sessions load on first use.** `createFormSession(config)` is replaced by `await loadFormSession(config)`, which loads the session code as its own chunk. If the chunk cannot be loaded it rejects with the fixed problem `FORM_SESSION_UNAVAILABLE` (`retryable`, id `form-session-load`), keeps nothing, and a later call tries again.
+
+**Queued messages are withdraw-only.** `client.edit(id)` and `useComposer().edit` are replaced by `client.withdraw(id)` and `useComposer().withdraw`, and the `chat.edit` message key by `chat.withdraw`, with `chat.restored`, `chat.restoredEdit` and `chat.restoredDiscard` for restored items. Withdrawing moves a queued message's content into its own restored item (`snapshot.restored`, each with its own id, kept in the same stored record) and removes the row in the same commit. Withdrawn content never enters the draft by itself: `client.editRestored(id)` appends it to the draft only when the user asks, as an ordinary draft change, and `client.discardRestored(id)` deletes the item, the only way an item is removed; draft changes never touch restored items. Nothing changes before the withdrawal's commit lands (the row id is listed in `snapshot.withdrawing` meanwhile, and the stock UI disables its control), and a withdrawal whose commit fails changes nothing. The stock UI lists restored items next to the composer with Edit and Discard. It is refused, reported as `refused` with id `sending`, while a send is in flight or its outcome is unknown, because that message may already be delivered. Outbox rows never change: each row is one logical message whose id is sent as `clientMessageId` and is the server's dedupe key, so a message with an unknown outcome is only ever resent with the same id and content. An attempt is settled only by an acknowledgement (a successful send, or a conversation read that holds the id) or by a definite failure of that same attempt; a refused retry, a reload, a new runtime or a read that does not hold the id settles nothing. A send dispatches only after its claim is committed to storage and sends the row as committed; if the claim cannot be committed nothing is sent and the row is marked `unavailable`.
+
+**Storage writes.** A client saves operations, not snapshots: set the draft, add an outbox row, claim or finish a send attempt, withdraw a row, remove a row once it is acknowledged or dismissed. Each is applied to the stored record when the commit lands, through the optional atomic `StoragePort.compareAndSet(key, expected, value)` (implemented by `createMemoryStorage`), otherwise under a Web Lock on the key (`navigator.locks`, shared by tabs and workers of one origin) where the platform has it, otherwise by writing, reading back and retrying. An operation whose condition no longer holds is dropped and the client shows the stored record instead. The draft is ordered by commit through a per-key revision persisted in the record, never by a clock: the later commit wins. A disposed client's draft edit lands only if nobody changed the draft since the revision it last saw. Loading a record only replaces what the client shows and never writes. Stores shared by several runtimes without Web Locks should implement `compareAndSet`: the read-back fallback cannot stop a write one runtime started from landing late.
+
+**Protected plans and terminal intents.** A plan record may carry `recovery` (profile `plan-recovery-v1`): its stored phase, generation, round, revision, conversation, current review and execution, intent slot versions, winner and per-step truth (`done`, `not-done`, `unknown`). Every such record passes one monotone gate, which keeps each protected plan's history for the client's lifetime: a lower revision is ignored, an equal revision must be the same record, and a record for another conversation or generation, one whose `conversationId`, `generation` or `revision` is missing or ill typed, or a protected plan arriving without its recovery view is reported as `invalid-plan` and the stored record kept. A plan under a profile or phase this client does not know, or without the negotiated `plan-recovery` capability, is adopted **read-only** under the same rules: it is shown with its recorded state and the `chat.recovery.updateToControl` explanation, every control refuses it locally and sends nothing, a run whose plan turns read-only gets no further record, and an acceptance that lands meanwhile starts nothing; controls return only from a fresh read at a known profile and phase. The runner consumes and the client publishes (`onRecord`) only records the gate adopted; a refused record ends a run as an interruption with cause `plan-changed`. A client offers the `plan-recovery` capability only when `plans.intent(request)` is supplied; it delivers terminal intents (`IntentRequest` → `PlanIntentReply`) through the host's `/plans/:id/safety-control` route, which needs authentication and CSRF but no agreement. `stopPlan()` on a protected plan inhibits the local run at once and submits a Stop for the exact execution, or the generation before any acceptance; `declinePlan()` submits an initial Cancel (never a normal reply); `leavePlan()` submits a Leave when the `plan-leave` capability is agreed (it holds only together with `plan-recovery`), acknowledging the adopted record's `decisionKey`, `versions`, `evidenceDigest` and `unknownCount` (against a running execution the host fences it and saves no decision, `leaveSafetyNeedsReview`; from readback an informed Leave opens the next decision round and closes the decision as `left-known` or `left-unconfirmed`, and a second window's identical Leave joins that round and gets the same stored result); `keepChangesReview()` / `canKeepChanges()` read synchronously, from the adopted record, what Keep would confirm (`forward-only` when planned work remains, `end-retention` otherwise) or why it is disabled (`capabilityMissing`, `keepNoDecision`, `sealed`, `keepBlockedActive`, `keepBlockedUnknown`), and `keepChanges(review)` sends exactly that Keep under the `plan-keep` capability (it holds only together with `plan-recovery`); a successful Keep closes the decision or ends own retention, records a permanent receipt and seals the plan, after which every later intent is answered from the final history (`finalHistory`) without changing it; while an intent is pending, `snapshot.intentOverlays[planId]` shows it (at most one per plan: its request, delivery `sending` / `uncertain` / `not-sent` and a problem key), `snapshot.intentNotice` the last resolved reply's facts, and `snapshot.intentAlert` the one action to focus after a new failure; `checkIntentStatus()` (also `checkSavedChoice()`, `checkKeepStatus()`, `retryIntent()`) redelivers the same request, a 401 is retried once after a successful authenticated call, 403 / 429 / offline wait for the user, and new confirmation is refused while pending; the intent port should reject with a numeric HTTP `status` (and `retryAfter` for 429) for host answers, any other rejection being an unknown outcome; the intent client loads when a protected plan is first adopted, so `keepChangesReview()` answers `{ disabled: "loading" }` until then and `{ disabled: "intentUnavailable" }` after a failed load (retried by a later review); an interrupted run (failed step or step-up, missing attribution, refused renewal, changed plan) submits an automatic Stop with that cause; each then reads the plan again. The intent client loads on first use; if it cannot load, the action reports `retryable`/`intent-load` and only the local Stop stays. A first accepting confirmation of a protected plan returns a private `acceptance` (`ReplyDelivery`), which only the runner receives; `reply()` stays boolean, a run starts only under it, and `runPlan()`/`resumePlan()` or the runner itself refuse a protected plan without it. A failed plan read during a run also submits the automatic Stop (cause `connection-lost`), for the interrupted plan whichever plan is displayed. A capability is enabled only when this client offered it, whatever the host echoes. **Behaviour change for every plan:** a stopped or failed run never asks the host to stop or undo anymore: it stops dispatching and reads its facts; `RunnerPorts.stop` is deprecated and never called, and `RunnerPorts.heartbeat(id, acceptance?)` receives the accepted execution. Hosts: the reference resolver (`src/host/plan-intents.ts`, not part of the client bundle) is a pure per-plan transition to run inside the host's own per-plan transaction, with `parseIntentRequest` to validate an intent body (exact fields, token and integer bounds, a 4096-byte NFC-normalized UTF-8 payload) and `parseConfirm` a confirmation, both before any comparison; the separate 8192-byte body limit `MAX_INTENT_BODY_BYTES` must be enforced while the body streams in (a declared or streamed length over it is refused at once, before parsing). A commit needs the `Admission` that only the admission of that exact operation returns. `parseIntentRequest` and `Admission` are repository reference code, not package exports. A host selects the plan and execution only from its own records (the route, and the execution it issued), requires the caller's scoped permission and the plan's own conversation, accepts an effect only as the exact accepted operation at its step, and answers an exact confirmation replay (every field equal) with the original acknowledgment and no new authority, refusing any changed or malformed one; the reference fixture keeps that safety state in memory, while a real host must keep it durable and atomic, and refuse the legacy `/stop` for protected plans.
+
+**Stream recovery for bound subscriptions.** When a subscription opened under an agreement reports `reconnecting` or `unavailable` (including a frame the transport cannot parse), the client closes it at once, before the adapter's own reconnect can retry the old URL, and owns recovery: after 250, 500, 1000, 2000 and 4000 ms it probes an authenticated conversation read and, when that succeeds, opens a new subscription under the current agreement. A probe refused with `agreement-expired` hands over to the agreement renegotiation, which reconnects under the new agreement; a probe refused for sign-in or an incompatible version stops with that cause (problem id `stream`); a missing conversation stops as for any read. A probe that succeeds does not reset the count; only an open that stays healthy for 10 s does, or regaining connectivity. While offline an attempt waits for connectivity (the `subscribeOnline` notification, or a 4 s recheck of `online()`) instead of being spent. After five attempts the snapshot reports `streamUnavailable: true` and the problem `unavailable`/`stream`; `client.refresh()` or coming back online retries, and the next healthy open clears that problem. The count, the give-up state and the episode belong to the stream under its current agreement: renegotiation, Retry, switching conversation or disposal retires them, so `streamUnavailable` never carries over to a new agreement. Hints coalesce with any read already running for the conversation. Because the client owns this reconnect, an adapter's native resume (for example an EventSource `Last-Event-ID`) is not used: each recovery refetches the full conversation. Subscriptions opened without an agreement keep their adapter's reconnect as before.
+
+**Signal transport hints.** `createSignalTransport` now turns each stream line into a `{ type: "invalidate" }` transport event instead of parsing it as a frame; a hint is never applied as content. The client coalesces hints per conversation with whatever conversation read is already running: at most one more read follows it. Code that switches over `TransportEvent` should handle the new member.
+
+**Conformance runners load on first use.** `runConformance`, `runPlanConformance` and `runFormFillConformance` keep their signatures but load their code as a separate chunk; if it cannot be loaded they reject with `CONFORMANCE_UNAVAILABLE` (`retryable`, id `conformance-load`) and a later call loads again.
+
+**Agreement binding.** `TransportPort.negotiate(supported, offer?)` now receives the client's `NegotiationOffer` (the capabilities it implements) and may return an `agreementId`. `read`, `send` and `subscribe` take an optional last `ReaderRequestContext` argument, `{ agreementId }`, and `RunnerPorts.read(id, context?)` an optional second one. Existing adapters with the old signatures stay assignable and keep working without a binding. A transport must store no binding itself: each client owns its answer, even when several clients share one transport. The built-in HTTP transport sends the offer in the `/negotiate` body and never an old agreement; once a client has an agreement, it sends it as a `Waypoint-Agreement` header and, for the stream, as a `?waypointAgreement=` query parameter, because an EventSource cannot set headers. The id is not a secret and grants nothing.
+
+Hosts that pass the offer to `negotiate(supported, capabilities, offer)` return only capabilities both sides support and should issue an `agreementId`; a host that keeps the two-argument call stays a legacy host and issues none. On a reader or message route, after normal authentication, an agreement the host does not know (expired, revoked or reset) must answer 409 with `{ "code": "agreement-expired" }` before admitting anything, and a malformed id must answer 400. `waypoint-conformance` checks this when the host issues agreements.
+
+On `agreement-expired` for its current agreement, the client closes the stream, renegotiates once and reads again; concurrent refusals share that renegotiation, and a refusal of an older agreement counts as one ordinary failure. If the replacement is refused before anything succeeds under it, the client stops with `unavailable` (id `agreement`) until `client.refresh()`. A renegotiation that changes the protocol reports `update-required`. A refused message stays in the outbox with the same id and is sent again only by an explicit retry; a refused reply or plan confirmation is never resent. A refusal of the current agreement also retires an active plan run on this client locally, with no remote stop or undo; plan reads take part in the same binding, and a refusal from a conversation the client has left is ignored.
+
+**Card answers.** A host holds one answer per card, a block of a message with the blocks nested in it. The first answer it applies marks that block `answered: true` in every later read: the message's block (the card), not a block nested in it that the answer names. A replay of that request (the same `clientReplyId` and body) gets its first response; any other answer to the card, whatever its `clientReplyId`, is refused with 409 `{ "code": "refused" }` and changes nothing. The same `clientReplyId` with another body is refused too, with 409 `refused` or, as the [Idempotency-Key draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) answers a changed body, 422. The rule departs from that draft in one way: another answer under a new `clientReplyId` is refused because the card already holds one, which the draft does not cover. While the first request with a `clientReplyId` is still being processed, a host either waits for it and answers with its response or, as the draft does, answers 409; the client then reads and shows the card as the host holds it. A host may also name the answer it holds in the card's optional `answer`: the applied `ReplyAction` or `ReplyForm` without its `protocol` (`CardAnswer`), only with `answered: true`. The chat shows it as the chosen answer when it names an action of the card, and ignores it otherwise or without `answered: true`; a host that leaves it out stays valid. Every reader of the conversation sees `answer`, so a host leaves out a form's `values` when they are not for everyone to read. The client keeps no answer of its own: `useBlockReply` locks a card while its answer is in flight, and after the host accepted it, builds the `clientReplyId` from the conversation, message, card and answer (`cardReplyId`, the same whatever the order of the answer's keys), so the same answer after a reload or in another tab is the same request, and frees a refused or lost answer's card once it has read the conversation after the answer. `reply()` resolves with the `ReplyOutcome`. When an answer is refused and the read after it shows the card answered, another answer was held first (another tab, an earlier page): the chat then says `chat.problem.answered` instead of the generic refusal, and says nothing about the refusal until that read settles. A host's `problemText` gets the same fact as its second argument, `{ answeredElsewhere: true }`. A headless UI decides this from the outcome and the conversation the same way. That read follows every reply, accepted or not, and has the startup read's budget: one that never answers ends as the failed read, with its Retry. `createScriptedTransport` from `/testing` behaves this way and names the applied answer, and `waypoint-conformance` checks it (`one answer per card`, an answer to a block nested in a card; it accepts 422 for the changed body, and checks `answer` only when a host sends it, field by field, in any key order and with any other fields the schema allows).
+
+**Plans from newer hosts.** `RecoveryView.profile` is now `'plan-recovery-v1' | (string & {})` (was `'plan-recovery-v1'`) and `RecoveryView.phase` is `RecoveryPhase | (string & {})` (was `RecoveryPhase`); the schema marks both with the `x-open-enum` extension and accepts other strings, while `RecoveryPhase` itself stays closed for intent replies. The extension value is either an array of known string literals (for example `["plan-recovery-v1"]`) or the name of the enum definition containing them (`"RecoveryPhase"`); the generator emits those known values unioned with `(string & {})`. A validator in strict mode refuses unknown keywords and formats: register `x-open-enum` as an annotation (Ajv: `ajv.addKeyword("x-open-enum")`) and the `date-time` format the schema uses (Ajv: `ajv-formats`), or validate in non-strict mode. Code that switches exhaustively on `recovery.profile` or `recovery.phase` must handle other values and render them read-only, and code that assigns `recovery.phase` to a `RecoveryPhase` must narrow it first. A client without `plans.intent`, or facing a profile or phase it does not know, now shows such a plan read-only instead of reporting `invalid-plan`; a record whose `conversationId`, `generation` or `revision` is missing or ill typed is refused for every profile.
+
+**Modal drawer root.** A skin whose drawer renders a mask or focus sentinels beside its dialog element marks the drawer's own root with the attribute `data-wp-modal-root`: the chat then makes everything outside that root inert, so the mask still takes clicks. It makes its focus sentinels inert itself, as the antd skin does.
+
+**Form fill.** The popup's Message and Reference links are drawn by the `textarea` primitive (paste is caught on a wrapper, so a custom one still gets images), and a boolean field by the new optional `checkbox` primitive (`CheckboxProps`: `checked`, `onChange(checked)`, `label`, `disabled`, `invalid`, `describedBy`; the native checkbox if absent). Generation, suggestions, fill reverts, the popup's status and attachments load as a lazy chunk with the first form: until it loads, or after it failed, Generate is unavailable with its reason and the fields keep working. A suggestion's buttons are "Replace" and "Keep mine" (the `/testing` form contract now presses "Replace"). Number fields edit as numbers; other non-text values are shown read-only and need `renderField` to be edited. `FormDraft` gains `localInvalid` and `localText`, `FormSnapshot` gains `fills`, and `FormSession` gains `markEdited`, `revert` and `failRequest`: a custom session implementation adds them. `FieldAdornmentProps.wrapper` reports the field's wrapper element.
+
+**Flows.** A row press opens a parameter drawer when the source can `load` documents (`client.canPrepareFlow()`); `client.prepareFlow(id)` loads and validates the document and keeps it for the next `runFlow` of that flow, which no longer loads it again (`prepareFlow()` forgets it). A custom `WaypointClient` adds both methods. A custom `button` primitive forwards `aria-pressed` and `id` (new on `ButtonProps`): the favourite toggle and the tabs use them.
+
+**Messages.** The `messageActions` part receives `data.message` (`id`, `role`, `status`, `versionIndex`, `versionCount`). Without a host part it shows the default actions, loaded with the first message: Copy on every message; with a `versions` port, Regenerate on a reply and Edit (an inline editor whose Send calls `client.editMessage`) on the user's own message; with a `feedback` port (`FeedbackPort`, called through `client.sendFeedback`), Good response and Bad response on a reply. A message with several versions shows "‹ 2/3 ›" in place (Previous version, Next version, through `client.selectVersion`); the walk's ends stay focusable and do nothing. A reply still being written shows none. A reply the host ended as failed or unavailable has nothing to copy or rate, and its Retry, in the reply row, asks for it again when there is a `versions` port, so it shows only the version walk, when it has versions. `client.canChangeVersions()` and `client.canSendFeedback()` say which ports are there. A host part replaces the defaults; see [docs/message-versions.md](docs/message-versions.md). In a narrow chat, the part of the reply that presents the plan (the last message, holding the plan's `plan` block) is rendered after the plan, outside that reply's article. A stream's `message.start` marks an assistant message `writing` and replaces any text shown under its id; `message.end` sets its status. A reply that streams in is announced once, when it ends.
+
+**Lazy code.** `handleToolRead` and `handlePlanningRead` keep their signatures but load their code on first use and reject with `STREAM_READS_UNAVAILABLE` (`retryable`, id `stream-reads-load`) if it cannot be loaded; `loadReadHandlers()` loads it ahead. `decodeFrames` loads its decoder on first use. A failed load of the storage commit code is reported as the existing `storage-write` problem.
+
+**Local problem identifiers.** Read-only `confirmPlan`, `runPlan`, `stopPlan`, `resumePlan` and `retryUndo` report `refused` with the target plan id. Read-only `declinePlan`, `leavePlan`, `keepChanges` and `checkIntentStatus` (and its aliases `checkSavedChoice`, `checkKeepStatus` and `retryIntent`) report `refused` / `intentPending`, as do a confirmation and a new terminal choice made while a terminal choice for the same plan is still pending. A missing read adapter reports `invalid-read` / `read-unavailable`, and other read handling failures use `invalid-read` / `read-failed`. Form mode refuses sensitive tool frames with `refused` / `form-tools` and composer sends without a session with `refused` / `form-session`. A client-actions chunk failure reports `retryable` / `on-demand-load`. These are local problem ids, distinct from host-issued identifiers.
+
+## Verification
+
+`npm run lint`, `npm run typecheck`, `npm test -- tests/protocol tests/conformance tests/core tests/react tests/skin-antd tests/package`, `npm run build`, `npm run api:check`, `npm run size` and `npm run test:consumer` are local/CI gates. `npm run test:native` checks the local build; CI's consumer check invokes `scripts/native-smoke.mjs` against the installed packed core for both npm and pnpm. Focused tests use at most two workers; `npm run test:browser` uses one. `npm run api:update` intentionally regenerates reports after a reviewed API change; check mode never blesses an uncommitted change. CI exercises lowest and latest optional peers.
+
+`waypoint-conformance <test-base-url> [--app-host]` runs HTTP scenarios against an isolated scripted service. The fixture's session and script endpoints answer 404 outside explicit test mode. No production database or model credential is needed. Profile-specific service behavior remains the application's responsibility.
+
+The protocol documents (this README and `docs/`) state requirements in plain English ("must", "never", "only"), binding as written. [The reply protocol](docs/reply-protocol.md), which covers stopping a reply and the other reply features a host can offer, uses the capitalised key words; the others do not use the capitalised key words of [BCP 14](https://www.rfc-editor.org/info/bcp14) ([RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)). The schema uses [JSON Schema 2020-12](https://json-schema.org/draft/2020-12). YAML parsing uses [js-yaml's JSON schema](https://github.com/nodeca/js-yaml), rejecting duplicate keys, aliases and executable tags. API snapshots use [API Extractor reports](https://api-extractor.com/pages/setup/configure_api_report/). The antd skin follows its [token and algorithm APIs](https://ant.design/docs/react/customize-theme/).
+
+Markdown images are links by default and initiate no image download. Opt in explicitly with `markdownImages={{ origin: "https://example.test", allow: url => allowedImages.has(url) }}`: origin permits same-origin images and allow permits a host-defined image list.
+
+All built-in Markdown, route and plan-view links share `isSafeUrl`. Add host-owned protocols with `extraUrlSchemes={["example"]}`; executable schemes and slash/backslash authority tricks remain refused.
+
+Read frames are answered by the client when `reads` is configured. For example, `reads: { manifest, request: call => apiRead(call), planning: { template: (planId, stepId) => trustedTemplate(planId, stepId), request: template => planningRead(template) } }`. The template comes from the host's trusted plan source, independently of the stream. Manifest reads project declared low-tier fields into `tool-result`; exact-template planning reads send their projected values only as `plan.values`. Refused reads never dispatch a request.
+
+`DEFAULT_FLOW_TABS` is the shared ordered built-in list. Add host tabs with `tabs: [{ id: "team", labelKey: "host.team" }]` and resolve their labels with `flowTabLabel={key => hostMessages(key)}`. Built-in tab names retain their typed catalogue keys.
+
+Direct runner integrations call `runner.run(planId, confirmedDigest)` with the digest the user confirmed. `client.confirmPlan()` captures that digest and deduplicates simultaneous confirmations of the same digest. `client.stopPlan(planId)` records stop intent even before execution begins; a stopped identifier cannot restart forward writes.
+
+Relative links (`docs/page`, `?q=1`) are refused. For application navigation, only absolute same-origin paths (beginning with `/`, excluding `//` and `/\`) are allowed; fragments and the explicitly allowed URL schemes remain supported.
+
+Confirmation retry keys are scoped to each plan id and digest: retrying a refused confirmation reuses its key, while a revised digest gets a new key. Confirmed digests are held in memory, scoped to conversation and plan, and cleared when the plan ends or is stopped, on conversation switches, and on disposal. A resume after a page reload always asks for confirmation again; confirmations are never persisted. Resume runs only when the returned final plan still matches the confirmed id and digest; otherwise it reports `plan-changed` ("The plan changed; confirm again.") and offers fresh confirmation. Running a permanently stopped id reports `stopped`. Both use the normal typed problem channel. `client.reply` accepts a reply without `protocol` and sets the negotiated version after readiness.
+
+For the legacy resume adapter, a resume that returns the same timed plan waiting to be scheduled restores that record without reporting a problem or running browser writes. An unfinished immediate proposal reports `invalid-plan` and retains its returned state. Returned plan identity is checked before either kind is handled.
+
+Form-bound conversations negotiate `form-fill` on protocol 1.1. Use `await loadFormSession({ fields, ids })` (its code loads on first use, outside the core bundle), the optional client `formSession`, `FormFillPopup`, `FormFillFields` and the shared `FieldAdornment` slot. Draft reception never saves records. The rail accepts subject and parent metadata or a `ConversationSource`. See [the form protocol and integration guide](docs/form-fill-protocol.md) for wire examples, replacement rules and host responsibilities.

package/dist/block-reply-DN4RiLL0.d.cts

@@ -0,0 +1,169 @@
+import { W as WaypointClient, b as ClientSnapshot, x as KeepChangesReviewResult, L as ReplyOutcome } from './form-fill-C32AHxSr.cjs';
+import { d as IntentOverlay, c as IntentNotice, I as IntentAlert } from './intent-BQPPows1.cjs';
+import { ad as PlanState, Z as IntentKind, ac as PlanRecord, ag as Reply, B as Block } from './generated-C9tbjwK0.cjs';
+import { M as MessageKey } from './i18n-DPNfYTMG.cjs';
+
+declare function useWaypointSnapshot(client?: WaypointClient): ClientSnapshot;
+
+interface ViewMessage {
+    key: MessageKey;
+    values?: Record<string, number>;
+}
+type Tone = "neutral" | "progress" | "warning" | "success";
+interface StepStatus {
+    stepId: string;
+    /** Its place in the plan, from 1; with `resource`, what `stepName` names it by. */
+    index: number;
+    resource?: string;
+    truth: "done" | "not-done" | "unknown";
+    textKey: MessageKey;
+    lateReport?: "contradicted";
+}
+type ActionId = "confirm" | "stop" | "decline" | "leave" | "keep" | "status" | "undoSelected" | "continue";
+interface ActionEntry {
+    id: ActionId;
+    /** The label; it takes no values. */
+    labelKey: MessageKey;
+    /**
+     * A label that also says how many changes there are ("Apply 2 changes"),
+     * formatted with `labelValues`; Confirm has one. Without it, or without
+     * the values, `labelKey` alone names the action ("Apply these changes").
+     */
+    countedLabelKey?: MessageKey;
+    /** The values `countedLabelKey` takes: the number of changes. */
+    labelValues?: Record<string, number>;
+    available: boolean;
+    reasonKey?: MessageKey;
+    reasonValues?: Record<string, number>;
+    busy?: boolean;
+    schedule?: boolean;
+}
+interface PlanViewStatus {
+    dataStatus: string;
+    wireState: PlanState;
+    label: ViewMessage;
+    tone: Tone;
+    attention: boolean;
+    result?: "kept";
+}
+interface PlanViewAlert {
+    serial: number;
+    action?: "checkStatus" | "retry" | "signIn" | "hostGuidance" | "wait";
+    restoreFocus?: true;
+    message?: ViewMessage;
+    retryAvailable: boolean;
+    retryReasonKey?: MessageKey;
+    retryValues?: Record<string, number>;
+}
+interface PlanView {
+    planId: string;
+    /** Null for a plan without the recovery profile (legacy). */
+    status: PlanViewStatus | null;
+    intent: {
+        kind: IntentKind;
+        status: IntentOverlay["delivery"];
+    } | null;
+    steps: StepStatus[];
+    lines: ViewMessage[];
+    notice: ViewMessage[];
+    alert: PlanViewAlert | null;
+    actions: ActionEntry[];
+    pending: readonly IntentKind[];
+    conversationUnavailable: boolean;
+    /** A protected plan this client cannot control: shown, never acted on. */
+    readOnly?: true;
+}
+interface PlanViewInput {
+    plan: PlanRecord | null;
+    capabilities: readonly string[];
+    conversationUnavailable: boolean;
+    overlay: IntentOverlay | undefined;
+    notice: IntentNotice | null;
+    alert: IntentAlert | null;
+    keepReview: KeepChangesReviewResult;
+    pending: readonly IntentKind[];
+    now: number;
+    conversationId: string;
+    readOnly?: boolean;
+}
+/** The notice's messages, built only from what the host reported. */
+declare function noticeMessages(notice: IntentNotice): ViewMessage[];
+/** The view of the current plan, or null without one. */
+declare function planView(input: PlanViewInput): PlanView | null;
+interface KeepSheetView {
+    messages: ViewMessage[];
+    proceed: {
+        available: boolean;
+        reasonKey?: MessageKey;
+    };
+}
+/** What the Keep confirmation states for the review captured at opening. */
+declare function keepSheet(review: {
+    review: "forward-only" | "end-retention";
+    remaining: number;
+}, view: PlanView): KeepSheetView;
+/** A message block as part data: its identity only, never its body. */
+interface BlockSummary {
+    id: string;
+    type: string;
+    answered: boolean;
+}
+
+interface KeepSheet {
+    messages: ViewMessage[];
+    proceed: {
+        available: boolean;
+        reasonKey?: ViewMessage["key"];
+    };
+    onProceed(): void;
+    onCancel(): void;
+}
+/**
+ * The plan view of the current plan and its presses, for every renderer.
+ * Presses go through the client; this hook only tracks a press that has no
+ * overlay yet, so the view can show it as pending.
+ */
+declare function usePlanView(client?: WaypointClient): {
+    view: PlanView | null;
+    press: (id: ActionId | "retry") => void;
+    sheet: KeepSheet | null;
+};
+
+/** An answer to a card, without the ids the hook fills in. */
+type BlockAnswer = Pick<Reply, "kind"> & Record<string, unknown>;
+interface BlockReply {
+    /**
+     * Ids of this conversation's cards with an answer in flight or accepted
+     * here, by card id alone; `isAnswered` with a message id tells cards of
+     * different messages apart.
+     */
+    answered: ReadonlySet<string>;
+    /**
+     * Whether a card takes no answer: the host marks it answered, or one is
+     * in flight or was accepted here. Pass the card's message id when card
+     * ids repeat.
+     */
+    isAnswered(block: Pick<Block, "id" | "answered">, messageId?: string): boolean;
+    /**
+     * Sends one answer to the card of `messageId` (when given), with a reply
+     * id built from the card and the answer (see `cardReplyId`). A press on a
+     * card that takes no answer here does nothing and resolves with nothing.
+     * Otherwise resolves with the outcome once the client has read the
+     * conversation after the answer; a card whose answer was refused or lost
+     * is then shown as the host reports it, and one whose answer was
+     * accepted stays answered.
+     */
+    reply(block: Pick<Block, "id">, answer: BlockAnswer, messageId?: string): Promise<ReplyOutcome | void>;
+}
+/**
+ * A card's reply id: the same for the same answer to the same card, in any
+ * page or tab, so a host deduplicates a resend, and another for another
+ * answer, which a host that already holds one refuses. It is opaque: its
+ * parts and a digest of the answer (whatever the order of its keys),
+ * escaped by code unit, and a digest of all of it past 128 characters.
+ */
+declare function cardReplyId(conversationId: string, messageId: string, blockId: string, answer: BlockAnswer): string;
+/** The card answer lock every renderer uses. */
+declare function useBlockReply(client?: WaypointClient): BlockReply;
+
+export { type ActionEntry as A, type BlockAnswer as B, type KeepSheet as K, type PlanView as P, type StepStatus as S, type Tone as T, type ViewMessage as V, type ActionId as a, type BlockReply as b, type KeepSheetView as c, type PlanViewAlert as d, type PlanViewInput as e, type PlanViewStatus as f, cardReplyId as g, usePlanView as h, useWaypointSnapshot as i, type BlockSummary as j, keepSheet as k, noticeMessages as n, planView as p, useBlockReply as u };