@shivaedev/work-board 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.13.0 - 2026-10-13
+
+### Added
+
+- Native `workContract` projection queries: `board` and `work` take `{ url }`; `overview` and `inbox` take no payload. Their typed results carry source data, validated membership and explicit unavailable states, without page HTML.
+- Portable `BoardProjection`, `WorkProjection`, `OverviewProjection` and `InboxProjection` schemas and types in `browser/views/schema.ts`, with shared `State`, `stateOf`, `viewUrl` and `fieldFilter` exports in `browser/views/state.ts`. The existing server URL-state exports remain compatible.
+- `DocumentView` accepts optional `board` section counts to render source Markdown as a heading board with the shared reading plugins.
+
+### Changed
+
+- Draw `mermaid` diagrams with Mermaid 12. Flowchart, state, class, entity-relationship and requirement diagrams that set no `layout` now lay out with ELK in Mermaid's `neo` look, so existing diagrams can change shape and gain shadows.
+- Drawing diagrams now needs an ES2024 browser, such as Safari 17.4 or later.
+- Navigation chrome, search, reading preferences, favorites, recents and reading history run in the React client with the shared native query registry.
+- Changes, Diagnostics, Start, Respond, Handoff and Result render typed Board queries in React. Their URLs load the React shell and require JavaScript; live updates and contextual forms retain their shared native client.
+- Board RPC adds `start`, `diagnostics`, `respond`, `handoff` and `result` queries. History responses add a typed `comparison` with source changes and identity limitations.
+- The configured home board, Work board/table with filters and selected detail, Overview and Inbox render in React from projection queries. Existing URLs, saved local views, inline answers and live updates use the shared query registry. Home reads retain targeted invalidation and change highlighting; visual previews refresh and diagram drawings return with Back navigation.
+
+### Fixed
+
+- Response drafts use effect-form persistence and retain input across reloads and source revisions. Questionnaire recovery keeps one snapshot per prior context, so repeated remounts retain answers without growing the draft. Response and handoff drafts now expire after seven days with a 256 KiB limit per draft; Clear draft restores only the current form.
+- Retain response and handoff draft text, source-change notices and caret selection through query refresh and reload in React-owned forms.
+- Back navigation and reload report a missing saved passage after restoring reading state, without changing the restored scroll or focus.
+- Search retains its query across dismissal and reopening, and keyboard dismissal restores the original control's focus and text selection.
+- Search passages that share a heading URL remain distinct when refreshed results remove or reorder entries.
+- Search keeps a valid keyboard selection when refreshed results shrink, so Enter opens the remaining selected result.
+- Editing a search query immediately clears previous options, so Enter before the debounce completes cannot open an old result or command.
+- A successful document refresh clears the previous navigation failure without resetting the current reading position or focus.
+- Opening the current projection URL uses its typed query, including when retrying a failed view. Overview and Inbox keep their payload-free calls.
+
+### Breaking
+
+- Requires stable Effect 4.0.4 in place of 4.0.0-rc.112. Effect 4.0.4 moves the former `effect/unstable/*` modules to `effect/*` and renames constructors such as `Config.string` to `Config.String`. Install `@effect/platform-node` and `@effect/platform-node-shared` 4.0.4 alongside it.
+- Removed `listenOn` from `@shivaedev/work-board/serve.ts` and the `server` and `ServerOptions` exports from `@shivaedev/work-board/rpc/server.ts`. Use `serveBoard` from `@shivaedev/work-board/serve.ts` to run the loopback Board HTTP and RPC server through Platform's `appHost`; the port, routes and CLI flags stay the same.
+- Remove the legacy string-script browser runtime and its HTTP asset routes. Remove these package exports and their modules: `diagnostics/script.ts`, `history/script.ts`, `page/sidebarScript.ts`, `page/searchResultsScript.ts`, `page/swap.ts`, `page/visualViewport.ts`, `page/stateScript.ts`, `page/searchScript.ts`, `page/visualScript.ts`, `page/itemContextScript.ts`, `page/libraryScript.ts`, `page/ageScript.ts`, `page/navigationScript.ts`, `page/readingStateScript.ts`, `page/formReadingScript.ts`, `page/diagrams.ts`, `page/client.ts`, `views/savedScript.ts`. Use the Board React client and native browser client instead.
+- Remove the Board HTML `page` RPC and the superseded server renderers for these views. Read documents with `document` and returned-result data with `result`.
+
 ## 0.12.0 - 2026-10-12
 
 ### Added

package/README.md

@@ -163,7 +163,7 @@ Back restores selected text and expanded details. Recent documents opens a bound
 
 **Diagnostics** in the sidebar reads Codex usage windows labelled by duration, GitHub REST and GraphQL rate limits, and Fleet health through the Fleet daemon's `daemon.diagnostics` HTTP RPC query at `127.0.0.1:3457`. Set `--fleet-port <port>` or `BoardOptions.fleetPort` to select another daemon port. A stopped daemon leaves Diagnostics available with an explicit unavailable state and a start command; the next refresh retries. Board does not start provider commands or read Fleet's database or health file. The daemon reads Codex and GitHub with its existing CLI authentication, caches rate-limit observations for one minute across Board clients and reports each source's missing configuration or error independently.
 
-The view refreshes through the native page query every 15 seconds while visible. Pause updates holds the displayed state; resume and returning to a visible tab refresh it. The shared `DiagnosticsContract` and `DiagnosticsSnapshot` schemas live in `@shivaedev/work-board/diagnostics/daemonContract.ts`; the version 2 `FleetHealth` schema lives in `@shivaedev/work-board/diagnostics/health.ts`. The page shows the publisher's observation time, freshness, running and queued counts and waiting counts for maintainer, orchestrator and automation, concurrency cap, last scheduler pass and last observed provider capacity rejection. Stale snapshots show a Stale badge and dimmed counts. Reset times show relative time and the browser’s local clock; without JavaScript they use the server’s local clock. Communication failures and API-key accounts explain why their data is unavailable. A publisher clock ahead of Board is disclosed; absent scheduler/rejection observations remain unknown or unobserved.
+The view refreshes through `client.api.diagnostics.query()` every 15 seconds while visible. Pause updates holds the displayed state; resume and returning to a visible tab refresh it. The shared `DiagnosticsContract` and `DiagnosticsSnapshot` schemas live in `@shivaedev/work-board/diagnostics/daemonContract.ts`; the version 2 `FleetHealth` schema lives in `@shivaedev/work-board/diagnostics/health.ts`. The page shows the publisher's observation time, freshness, running and queued counts and waiting counts for maintainer, orchestrator and automation, concurrency cap, last scheduler pass and last observed provider capacity rejection. Stale snapshots show a Stale badge and dimmed counts. Reset times show relative time and the browser’s local clock; the Diagnostics view requires JavaScript. Communication failures and API-key accounts explain why their data is unavailable. A publisher clock ahead of Board is disclosed; absent scheduler/rejection observations remain unknown or unobserved.
 
 **Changes** starts remembering only through **Start remembering changes**. After review, **Mark current workspace seen** replaces the baseline; **Clear remembered history** turns it off. Opening a view and receiving live updates never mark it seen. Compare additions, removals, fields and source text against that one browser-local baseline. Unique IDs match moved items; plain-file renames are removed/added paths. The baseline is bounded to 2 MiB and 30 days, with expiry, corruption, incomplete reads and oversized workspaces disclosed. It holds Markdown, not image bytes.
 
@@ -212,7 +212,7 @@ Registration captures one question generation in `responses/`; submission create
 
 An execution integration may mark a generated `kind: decision` request with `attention[].managed: true`. A separate immutable `kind: result` document records `request_receipt` with the registered question ID, its `reviewedRevision`, `recordedAt` and disposition `applied` or `superseded`. An applied receipt names the unique current `answer`; clarification and deferral cannot acknowledge it. Supersession retires the request without inventing an answer. Only an unambiguous receipt matching the exact current source path and bytes removes the managed request from the overview and response surface. `currentResponses(responses)` from `@shivaedev/work-board/responses/current.ts` selects the latest response per author, ordered by recorded time and then response ID, and removes explicitly superseded responses. Managed acknowledgements use this selection; different authors remain competing, and superseding an author’s latest response does not revive an earlier answer. `src/responses/current.test.ts` and Fleet’s PostgreSQL question tests cover this rule. The source remains unchanged and readable. Ordinary authored requests remain source-driven; receipts grant no execution, acceptance or delivery authority.
 
-Browser drafts have their own 2 MiB workspace bound and expire 30 days after their last edit. Navigation, reload and source refresh retain them; text edited while an earlier save completes remains an unsaved draft with a fresh identity. Corruption, expiry and storage failures are disclosed. Clearing drafts does not clear saved records or the seen baseline.
+Browser drafts use effect-form’s persisted drafts, keyed by workspace, item and request, with a 256 KiB limit per draft and a seven-day lifetime after the last edit. Navigation, reload and source refresh retain them; text edited while an earlier save completes remains an unsaved draft with a fresh identity. Malformed or expired drafts are discarded; unavailable storage leaves the form usable. **Clear draft** restores the current form’s initial values without changing saved records or the seen baseline.
 
 #### Wait for an attributable reply
 
@@ -268,15 +268,15 @@ Open a uniquely identified project item and choose **Prepare an agent handoff**.
 
 The agent edits `handoff.state` to `acknowledged`, `rejected` or `unavailable` and can add `handoff.by` and `handoff.note`. These are explicit local receipt facts, independent of task status, execution and human acceptance. An absent receipt stays unconfirmed; damaged or ambiguous history stays unavailable.
 
-Same-ID retries preserve receipt and extra metadata, including after source deletion. Restarted servers read the recorded receipt. Different direction and moved or duplicate identities are conflicts; a changed source before initial preparation requires another review. Saved context remains inspectable when its source disappears. Native navigation and Back retain owned draft text; source changes require a fresh preview. Drafts share the existing workspace store and its 30-day/2-MiB bounds. Clearing that store clears response and handoff drafts together.
+Same-ID retries preserve receipt and extra metadata, including after source deletion. Restarted servers read the recorded receipt. Different direction and moved or duplicate identities are conflicts; a changed source before initial preparation requires another review. Saved context remains inspectable when its source disappears. Native navigation and Back retain owned draft text; source changes require a fresh preview. Handoff drafts use effect-form with a separate key per workspace and item, under the same seven-day/256-KiB limits. **Clear draft** clears only the current form.
 
-The static handoff, response and question forms use `@shivaedev/effect-form` for Schema decoding, field messages and captured submissions. Board owns preview, reviewed-context checks and durable draft storage. Input typed during a response save remains available under a fresh draft identity; each form releases its registry on navigation or pagehide and rebinds on pageshow.
+Response and handoff forms are React components on `effect-react`’s `useCreate` and `effect-form`’s Schema decoding, field messages and persisted drafts. Board owns preview and reviewed-context checks. Draft text, source-change notices and caret selection survive query refresh and reload. Input typed during a response or handoff save remains an unsaved draft; a fresh preview assigns its next identity. The forms use the shell’s shared native registry.
 
 The [handoff source reference](docs/delivery/handoff-examples.md) shows a complete record, ordinary receipt edits and the boundary with optional execution integrations.
 
 #### Review the returned result
 
-A file with `kind: result` and a unique ID offers **Review returned result** at `/_board/result?item=<id>`. The page separates the report's authored status from linked work status, lists its criterion-level claims and missing provenance, and keeps the report, limitations and human feedback together. Reading through normal GET or the native page query leaves project files unchanged.
+A file with `kind: result` and a unique ID offers **Review returned result** at `/_board/result?item=<id>`. The page separates the report's authored status from linked work status, lists its criterion-level claims and missing provenance, and keeps the report, limitations and human feedback together. Reading through normal GET or the typed query leaves project files unchanged.
 
 The agent declares an explicit open `attention` request of kind `review` on the report. That request links into the existing response surface. A Markdown question packet can offer request revision or accept this exact report, with room for human rationale. These options are authored text, rather than reserved acceptance states. Preview and submit the response against the exact source you reviewed.
 
@@ -291,7 +291,7 @@ Import the module that defines a name. The package has no root entry; its manife
 | Module | Names and purpose |
 | --- | --- |
 | `board.ts` | `BoardOptions`, `boardLayer(options)`: Effect HTTP router Layer for the workspace |
-| `serve.ts` | `ServeOptions`, `HOST`, `listenOn(port)`, `serveBoard(options)`: Node loopback serving Layers |
+| `serve.ts` | `ServeOptions`, `HOST`, `serveBoard(options)`: loopback Board serving through Platform’s `appHost` |
 | `responses/agent.ts` | `AgentOptions`, `agentRequest(action, options, diagnostic?)`: Effect client for `question`, `response` or `wait` |
 | `browser/client.ts` | `Reader`, `BrowserClient`, `browserClient(url, options?)`: native reading, response and handoff bindings, registry and live updates |
 | `rpc/contract.ts` | `workContract`, `Subscribe`, `workRpcs`: reading queries and combined native RPC group |
@@ -312,7 +312,7 @@ Other defining modules are also exposed by the wildcard. Their [source directory
 import { NodeServices } from "@effect/platform-node";
 import { boardLayer } from "@shivaedev/work-board/board.ts";
 import { Layer } from "effect";
-import { HttpRouter } from "effect/unstable/http";
+import { HttpRouter } from "effect/http";
 
 const board = HttpRouter.toWebHandler(
   Layer.provide(boardLayer({ root: "./project-notes", home: "plan.md" }), NodeServices.layer),
@@ -377,7 +377,7 @@ export async function registerReviewedQuestion(url: string, revision: string) {
   const client = browserClient(url);
   try {
     const page = await client.read(
-      client.api.page.query({ url: "/_board/item/work.search/" }),
+      client.api.document.query({ url: "/_board/item/work.search/" }),
     );
     const question = await client.mutate(
       client.responses.registerQuestion.run({
@@ -436,7 +436,7 @@ export async function prepareReviewedHandoff(
 
 Pass `preview.source` and `preview.reviewedRevision` only after reviewing the preview's context. `saved.prompt` is the short instruction to copy into the agent session, and `history` contains records plus paths whose history is unknown. Keep the same ID for a retry of identical direction; choose a new ID for new direction.
 
-Result reading uses the same page query as other workspace views:
+Result reading returns the report, linked criteria and revision-pinned feedback from its typed query:
 
 ```ts
 import { browserClient } from "@shivaedev/work-board/browser/client.ts";
@@ -445,7 +445,7 @@ export async function readReturnedResult(url: string, item: string) {
   const client = browserClient(url);
   try {
     return await client.read(
-      client.api.page.query({
+      client.api.result.query({
         url: `/_board/result?item=${encodeURIComponent(item)}`,
       }),
     );
@@ -463,7 +463,7 @@ RPC rejections use Platform taxonomy classes: `Forbidden` for disabled writes, `
 
 Read `client.api.document.run({ url: "/notes.md" })` to get Markdown body source, metadata and diagnostics, resolved links and references, file information, resolved question actions and request previews with response history. Identity URLs and `/` use the same document query. Missing and duplicate identities reject with `NotFound` and `Conflict`; incomplete history stays explicitly unavailable. The query sends no rendered HTML or syntax tree.
 
-Pass that data as the `document` prop of `DocumentView` from `@shivaedev/work-board/browser/document/View.ts`. The view uses the Board's GFM, directive, heading and footnote plugins with raw HTML, browser-side Shiki and a Mermaid code override. `idPrefix` scopes footnotes when a host displays several documents. The Board shell is a React app with TanStack Router. Its route loaders read document and page contract queries through `effect-react` in the shell's native registry; preloading and navigation share those reads. Document and item pages mount `DocumentView` from the typed document query; the configured home board and workspace views remain in `LegacyMain`. The optional `reading` data supplies source context, backlinks, criterion claims and managed receipts; request `prompts` supply answer controls. Hosts can mount `DocumentView` directly from source-query data, or pass `context` and `introduction` React nodes for its document layout.
+Pass that data as the `document` prop of `DocumentView` from `@shivaedev/work-board/browser/document/View.ts`. The view uses the Board's GFM, directive, heading and footnote plugins with raw HTML, browser-side Shiki and a Mermaid code override. `idPrefix` scopes footnotes when a host displays several documents. The Board shell is a React app with TanStack Router. Its route loaders read document and projection contract queries through `effect-react` in the shell's native registry; preloading and navigation share those reads. Document and item pages mount `DocumentView` from the typed document query; the configured home board, Work board/table and selected detail, Overview and Inbox render typed projection queries in React. Changes, Diagnostics, Start, Respond, Handoff and Result also render typed query data in React. Their direct URLs load the shell and require JavaScript. The HTML page RPC is removed. The optional `reading` data supplies source context, backlinks, criterion claims and managed receipts; request `prompts` supply answer controls. Hosts can mount `DocumentView` directly from source-query data, or pass `context` and `introduction` React nodes for its document layout.
 
 #### Headless addon API