@supersuit/suggest-a-change 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-10-12)
+
+First release. The report contract and flow map: kinds, roles, ceilings, statuses, who acts at each step, and report validation.
+
+The client core, exported as `./client`: IndexedDB store, op ids, the outbox (`Op.kind` is a string the host names; the module adds `report` and `reportPart`), the take recorder with crash recovery, drafts keyed `sac:<app>:<account>`, and the report sender over a `StoreAdapter`. Built to `dist/` with type declarations.
+
+The screens, exported from `./client` (React 19 as an optional peer): the entry, the sheet, the receipt, My suggestions and the detail view, a default voice field, and optional styles in `./styles.css`.
+
+The screen check, exported as `./check` and installed as the `suggest-a-change-check` command: it fails an app whose screens below home lack the Suggest a change entry (nested layouts and imported shell components are followed; an exempt screen needs a reason) or whose adapters file does not export all four of `identity`, `store`, `words` and `limits`. `checkEntryOnRoutes` does the same for an app with one shell. `suggest-a-change init` wires a new Next.js app: the dependency, adapter stubs under `tailor/`, the entry in the root layout and the check in the app's check script. The stubs carry a `suggest-a-change: STUB` line: the check warns about it, and `suggest-a-change-check --strict` fails on it, so an app cannot ship the stubs as done.
+
+The server half, exported as `./server`: `createReportHandlers` (submit, upload-url, finalize, mine, one, append, and the agent routes list, file, settle, claim-approval, status), the `HostedStore` an app's storage implements, `runStoreConformance` (the suite every adapter must pass), and `sniffType`. Web-standard APIs only, no runtime dependency. Reports are isolated by member (another member's report answers exactly like a missing one), the stored role is decided by the server, attachments go straight to storage on links with size and type fixed and are verified by their bytes at finalize, the day's limit is twenty at most, a claim lasts ten minutes, and the approval is first-wins and held by the Mac that took it (a week, releasable). The store contract is create-only and narrow (`put`, `setFile`, `addFollowUp`, `setStatus` with a precondition, `reopen`), so a stale write cannot erase a status or a claim, and a follow-up or file that arrives after a Mac collected a report offers it again. Settle carries the revision the Mac was shown, so something added between list and settle is never lost; follow-up caps are enforced inside the atomic write; a verified file entry cannot be replaced; only the owner adds to a report, and not once it has ended; a voice file's link size follows its declared length. The phone refuses a picture or video format the app cannot take, in words, and takes a HEIC with no type by its extension. The conformance suite is proved against deliberately unsafe adapters.
+
+The check is strict about what counts as rendering the entry: an imported component only covers a layout that uses it (as an element, a prop value or a rendered alias), and the imported name (for a namespace import, the member rendered) is carried through barrel files, strings and comments never count, JSX text is not read as code, and an app directory with no pages is a usage error rather than a pass.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SupersuitUp
+
+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,219 @@
-# Temporary Holding Version
+# @supersuit/suggest-a-change
 
-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.
+The report format and flow behind a Suggest a change button: what a report is, who acts at each step, the screens, and the check every app runs. The contract (the package root) has zero dependencies.
+
+## 30 seconds
+
+```bash
+npm install @supersuit/suggest-a-change
+```
+
+```js
+import { KINDS, STATUSES, FLOW, CEILINGS } from "@supersuit/suggest-a-change";
+
+console.log(KINDS);            // ["change", "broken", "feedback"]
+console.log(FLOW["with-freeda"]); // { actor: "mac", next: ["planned"] }
+```
+
+The package root is the report contract: the kinds, roles, ceilings, the status list and the flow map (who performs each step and which moves are allowed), plus the functions that validate a report against them. It has no imports, so it can also be copied whole into a place that has no install step. If you copy it, keep a hash of the copy and fail a test when the bytes change; fix the contract here and copy it again.
+
+The client core is TypeScript, built to `dist/` with declarations. `"./client"` is one entry point that includes the screens, so it needs React 19 installed in the app (the contract at the package root and `"./check"` do not):
+
+```ts
+import { openStore, makeOutbox, makeReportSender, queueReport, draftKey, saveDraft, startTake, recoverTakes } from "@supersuit/suggest-a-change/client";
+```
+
+A draft is keyed `sac:<app>:<account>`, so switching people never shows another person's draft, and it carries the report id made when it started. A report goes into the outbox as one `report` write and one `reportPart` per attachment, and the draft is cleared only when the last of them has landed. `StoreAdapter` is the interface an app implements for the receiving side.
+
+### The screens (React 19, optional peer)
+
+`"./client"` also carries the screens: `SuggestEntry`, `SuggestSheet`, `Receipt`, `MySuggestions`, `SuggestionDetail`, `ReportProblem`, `DefaultField`, `Toasts`, and `receiptWords`. An app supplies `Adapters`:
+
+```tsx
+import { SuggestEntry, SuggestSheet, type Adapters } from "@supersuit/suggest-a-change/client";
+import "@supersuit/suggest-a-change/styles.css"; // optional
+
+const adapters: Adapters = {
+  identity: async () => (user ? { account: user.memberKey, role: "member" } : null),
+  store,                                  // a StoreAdapter: submit, uploadPart, mine, one, append (dedupe by id)
+  words: { app: "notes", owner: "Alex" },    // the owner's name is passed in, never written in the module
+  limits: { images: 3 },                  // may lower the ceilings, never raise them
+  Field: GoldenVoiceField,                // optional: a host's own voice field; the module ships DefaultField
+  snapshot: async () => screenshotBlob(), // optional: one tap to attach a picture of this screen
+  about: { app: "notes", version: "1.2.3" }, // stamped into every report
+  lands: "app",                           // "mac" on a Helm that posts straight to the owner's Mac
+};
+// On every screen below home:  <SuggestEntry adapters={adapters} onOpen={() => setOpen(true)} />
+// then:                        {open && <SuggestSheet adapters={adapters} where={{ screen: "Photos", route: location.pathname }} onClose={() => setOpen(false)} />}
+```
+
+The entry carries `data-suggest-entry` (the attribute the screen check looks for; see "The check" below). Signed out, it opens nothing and says why. The receipt says "Got it" only after the adapter has answered `done` for the report and every attachment; until then it says the report is on the phone. Every text field the module renders sits in a `[data-voice-field]` container with a `[data-voice-control]`; a host's `Field` slot must keep that shape (it receives `FieldProps`, which is the Helm's voice field props). A voice note alone is a whole report: the recording is kept and uploaded as a part, and the receiving Mac writes the transcript.
+
+Styling: structure only, class names prefixed `sac-`. `@supersuit/suggest-a-change/styles.css` is optional defaults (16px inputs so iOS does not zoom, 44px touch targets, safe-area padding on the sheet). Re-skin it with these custom properties:
+
+| Property | Default | Used for |
+| --- | --- | --- |
+| `--sac-font` | `inherit` | all text |
+| `--sac-fg` | `#1a1a1a` | text |
+| `--sac-bg` | `#ffffff` | sheet and control backgrounds |
+| `--sac-muted` | `#5f6368` | secondary text |
+| `--sac-border` | `#cfd2d6` | outlines |
+| `--sac-accent` | `#1a56db` | the primary button, the current step |
+| `--sac-accent-fg` | `#ffffff` | text on the accent |
+| `--sac-danger` | `#b3261e` | errors and the record dot |
+| `--sac-radius` | `12px` | corners |
+| `--sac-gap` | `12px` | spacing |
+| `--sac-z` | `1000` | stacking of the sheet (toasts sit one above) |
+| `--sac-backdrop` | `rgba(0, 0, 0, 0.45)` | the dim behind the sheet |
+| `--sac-focus` | `#1a56db` | focus rings |
+
+The four diagnostics are the app's version, the time, the screen size and the phone type; the app's version and the phone type are on by default and the time and screen size are off (the report's id and the app's own received time already say when it was sent), and the screen's name and address are always sent and shown as such.
+
+**Identity.** Every screen asks `adapters.identity()` when it mounts, whenever it is handed a different `adapters` object, and whenever the host calls `refreshIdentity()` (exported from `"./client"`; call it after a sign-in, sign-out or account switch). When the account differs, the old account's rows leave the screen and its waiting reports stay on the phone, to be sent only while that account is signed in; every send re-confirms the account first. Keep `adapters` stable where you can; a parent that rebuilds it every render is safe, only slower (one `identity()` call per render).
+
+**Follow-ups.** Words and voice notes added to a report afterwards are queued in the outbox like the report (a `followUp` write, then one part per voice note), keep the app's refusal with a Try again, and delete their local copy only once they have landed. `StoreAdapter.append` must therefore dedupe by report id and `more.followId`.
+
+## The check: every screen carries the button
+
+`suggest-a-change-check` fails an app whose screens lack the Suggest a change entry, or whose adapters are not all supplied. Each app calls it from its own check script. Run it from the app's folder:
+
+```bash
+npx suggest-a-change-check
+npx suggest-a-change-check --help
+```
+
+Exit 0 is clean, 1 is problems (each printed with the file and the fix), 2 is a usage error or nothing to check. `--json` prints `{ ok, problems, checked, exempted }`. The flags are `--repo`, `--config`, `--app-dir`, `--adapters` and `--strict`. An app directory with no pages is a usage error (exit 2: nothing was checked), as is an app directory outside the repo.
+
+**Put `suggest-a-change-check --strict` in the app's check script** once the adapters are real. `init` writes stubs that sign nobody in and refuse every report, and marks the file with a `suggest-a-change: STUB` line. Without `--strict` that line is a `warning:` (also in the `--json` `warnings`) and the exit stays 0; with `--strict` it is a problem and the exit is 1. Delete the line when the four adapters are real.
+
+For a Next.js app (app router) it reads source, not a running app:
+
+- It takes the same screen list the home-screen check takes (see "The screen list" below): every page under the app directory (`appDir` in `home-screen.json`, else `src/app`, else `app`), minus the routes listed under `home` (default `/`).
+- A screen passes when its page, or any layout or template from the app directory down to the page's own folder (nested layouts and route groups included), renders `<SuggestEntry` or carries `data-suggest-entry` as a JSX element or attribute. The entry may come through a component the file imports, but only if the file actually uses that import: it appears as an element (`<Shell>`), is passed as a value inside JSX (`<Providers Layout={Shell}>`), or is assigned to a const that is rendered (`const W = Shell; <W />`). Importing it is not enough, and calling a function with it (`String(Shell)`) is not using it. The imported NAME is carried through barrel files: a barrel that re-exports both Shell and Button covers a layout that renders Shell, never one that renders only Button. `export { A as B } from`, `export { default as X } from`, `export * from`, `export * as ns from`, and `import { X } from ...; export { X }` / `export default X` all pass the name along. For a namespace import (`import * as ui`) only the members rendered count: `<ui.Button />` is covered only if Button's export reaches the entry, while `<ui.Shell />` is covered if Shell's does; a namespace handed on whole (`parts={ui}`) counts every member. Relative, `@/` and `~/` imports are followed three levels deep, each re-export hop counting as one. A match inside a string literal, a comment or a template string does not count; JSX text is text, so an apostrophe in it starts nothing.
+- A screen that should not have the button is listed in the same config file, with a reason:
+
+  ```json
+  { "home": ["/"], "suggest-a-change": { "exempt": { "/share/[token]": "opened by someone who is not a member" } } }
+  ```
+
+  An exemption with an empty reason, or for a route that no longer exists, is a problem.
+- The adapters file (`tailor/suggest-a-change.ts`, or the path under `"suggest-a-change": { "adapters": "..." }`) must export all four of `identity`, `store`, `words` and `limits`, directly or through `export *` and `export { x as y }` from a local file.
+
+What it cannot see: an entry rendered only under a condition, which component inside an imported file renders the entry (it checks the file: when one file defines both the entry-bearing component and other components, rendering any of that file's exports counts as covered), a component reached through more than three levels of imports, an import through a path alias other than `@/` and `~/`, an entry that code builds from a string, and a regular expression literal containing a quote, which can confuse its reading of the rest of that file. It reads text, so it will say a screen is covered when the entry exists in the source and never shows at runtime. Keep the entry unconditional (a signed-out visitor is told why by the entry itself).
+
+### The screen list
+
+The check copies the route rules of a template's `living/home-screen-contract.mjs`, so both sides name the same screens. These are the rules, pinned by the `routes` fixture in `test/fixtures/` and the test `the screen list follows the rules the home-screen check follows`; change one side and the other must change with it:
+
+- A screen is a file named `page.tsx`, `page.ts`, `page.jsx`, `page.js` or `page.mdx`. `page.test.tsx`, `page.dev.tsx` and `route.ts` are not screens.
+- Any file under a folder whose name starts with `_` is skipped.
+- Route groups, folders named `(name)`, are dropped from the route: `(marketing)/about/page.tsx` is `/about`.
+- Parallel-route slots, folders named `@name`, are dropped: `@sidebar/stats/page.tsx` is `/stats`.
+- Dynamic segments stay as written: `[id]`, `[...slug]`, `[[...path]]`.
+- Intercepting folders `(.)x`, `(..)x` and `(...)x` are NOT dropped (only a folder name that both starts with `(` and ends with `)` is a group), so `photos/(.)view/[id]/page.tsx` is `/photos/(.)view/[id]`.
+- A route is exempt from the check if it is a `home` route, or listed under `suggest-a-change.exempt` with a reason.
+
+An app with one shell and no per-screen pages (a single-page app) checks its route list instead:
+
+```js
+import { checkEntryOnRoutes } from "@supersuit/suggest-a-change/check";
+
+const problems = checkEntryOnRoutes({
+  routes: ["/", "/inbox", { route: "/print", exempt: "a printed page" }],
+  render: (route) => renderToString(<App route={route} />), // returns the route's HTML
+});
+// [] when every route's HTML has an element carrying data-suggest-entry. checkEntryOnRoutesAsync takes an async render.
+```
+
+`checkSuggestEverywhere({ repo, appDir, config, adaptersFile })` is the same check as the command, as a function that returns the problems (it throws `UsageError` when there is no app directory to check).
+
+### Wiring a new app
+
+```bash
+npx suggest-a-change init
+```
+
+Run it in the app's folder. It adds the dependency to `package.json`, writes `tailor/suggest-a-change.ts` with the four adapters stubbed (kept as it is if it exists), adds `suggest-a-change-check` to the app's check script (`living:check` if the app has one, else `check`), writes `src/components/suggest-a-change.tsx`, and renders it in the root layout (before the last JSX `{children}`, never a destructured parameter). It keeps `package.json`'s indent and the order of the other dependencies, and refuses an app directory outside the repo. The adapters it writes are stubs and `init` says so. Running it again changes nothing. Then install your dependencies and fill in the four adapters. `--repo`, `--app` (the id in `words.app`) and `--owner` (the first name the receipt says) are optional; `suggest-a-change check` is the same command as `suggest-a-change-check`.
+
+Check this package (typecheck, client tests, build, node tests, the commands):
+
+```bash
+npm ci
+npm run check
+```
+
+Development needs Node 22 or newer (vitest and jsdom); the built package runs on Node 20 and up.
+
+## The server half (`./server`)
+
+Web-standard only (`Request`, `Response`, `crypto.subtle`), no runtime dependency, nothing from react or the client. A hosted app mounts the handlers and supplies a storage adapter.
+
+```ts
+import { createReportHandlers } from "@supersuit/suggest-a-change/server";
+
+const h = createReportHandlers({
+  store,                                  // your HostedStore (see runStoreConformance)
+  identity: async (req) => member,        // { account } or null
+  maintainers: ["mo"],                    // member keys with maintainer permission; ordinary membership never is
+  agent: async (req) => maintainerKey,    // which maintainer's Mac is calling, or null
+  limits: { perPersonPerDay: 10 },        // may lower a limit, never raise it (also voiceNotes, followUpVoiceNotes, followUps, agentPage)
+  app: { name: "Notes" },                 // stamped into every report from here; an app in the body is ignored
+  maintainersSince: { mo: "2026-10-01" }, // optional: reports from before this are not offered to that maintainer's Mac
+  tell: (e) => notify(e),                 // ids only, never words; a failure never fails the request
+});
+```
+
+| Route | Handler | Answers |
+| --- | --- | --- |
+| `POST /api/reports` | `submit` | 200 (a repeat of the same id is 200 too), 400, 401, 413, 422, 429 |
+| `POST /api/reports/upload-url` | `uploadUrl` | 200 `{ url, headers }` (or `{ done }`), 400, 401, 404, 413 |
+| `POST /api/reports/:id/finalize` | `finalize` | 200, 401, 404, 409 (not arrived yet), 422 (contents are not the declared type) |
+| `GET /api/reports/mine` | `mine` | 200, 401 |
+| `GET /api/reports/:id` | `one(req, id)` | 200, 401, 404 (missing and not yours look the same) |
+| `POST /api/reports/:id/append` | `append(req, id)` | 200, 400, 401, 404 (not the owner's: same as missing), 409 (the suggestion has ended) |
+| `GET /api/agent/reports` | `agentList` | 200 `{ reports }`: one page (20, oldest first) of what is open for this Mac, each claimed for ten minutes; a report whose files are still arriving waits up to an hour |
+| `GET /api/agent/reports/:id/files/:file` | `agentFile(req, id, file)` | 200 `{ url, expiresAt, type, bytes, sha256 }` (the link lives five minutes), 404 |
+| `POST /api/agent/reports/:id/settle` | `agentSettle` | body `{ revision }` (the one the list gave this report): 200, 400 (no revision), 409 (not claimed, or `stale`: something was added since the list, so the report is offered again) |
+| `POST /api/agent/reports/:id/claim-approval` | `agentClaimApproval` | 200, or 409 `{ claimedBy }` |
+| `POST /api/agent/reports/:id/status` | `agentStatus` | 200, 400, 409 |
+
+A client adapter's `uploadPart` asks `upload-url`, PUTs the bytes straight to storage, then calls `finalize`. Nothing is uploaded through the app's server and no handler reads a body over about 400 KB (sized from the field limits at four bytes a character; far under 4 MB).
+
+The role stored on a report comes from the signed-in member and the `maintainers` list. A `who` sent by the phone is ignored; a report carrying `timeline`, `status`, `plan` or `decision` is refused. `sniffType(firstBytes)` names a file by its bytes (jpeg, png, webp, heic/heif, gif, mp4/mov, webm, m4a/aac, mp3, wav, ogg/opus; anything else is `null`) and `finalize` refuses a file whose bytes are not the type it was declared as.
+
+**Settle carries a revision.** `agentList` gives each report a `revision`; the Mac sends it back with `settle`, and the store settles only if the report still has exactly that content. A follow-up or file that arrived in between answers 409 `stale`, drops the claim, and the next list offers the report with the addition. Adapters compute the same value with `reportRevision`.
+
+**The collector MUST verify.** `agentFile` answers the verified `bytes` and `sha256`; a Mac that downloads the link must check both before it trusts the file.
+
+**The approval.** Moves before the owner is asked (`with-freeda`, `planned`, `waiting-on-owner`) need no claim. Leaving `waiting-on-owner`, starting `being-made` and any end status need the Mac that holds the approval (taken atomically if nobody holds it, otherwise 409 with who does). The holder can release it, and it lapses after seven days.
+
+**What a storage adapter implements** (`HostedStore`). Every method that changes a report is narrow and atomic: `put` is create-only (`created`, `exists`, or `limit` when the member's day is full, counted in the same transaction), and `setFile` (never replaces a verified entry; an older pending never replaces a newer one), `addFollowUp` (the caps, a reused file name and an ended report are checked inside the write), `setStatus(expectFrom)`, `claimApproval`, `claim`, `settle` and `reopen` each change one thing. A real adapter implements these with a transaction or a precondition, never "read the report, change a copy, write it back": that rolls back a status or a claim written in between. Upload links must be create-only and one-time with the size and type fixed in their conditions (a Firebase or S3 signed PUT with `if-generation-match: 0` or `If-None-Match: *`), `discard` must delete a refused object, and `readUrl` links must expire after `ttlMs`.
+
+**Every adapter must pass the conformance suite**, against the adapter and its real storage:
+
+```ts
+import { runStoreConformance } from "@supersuit/suggest-a-change/server";
+await runStoreConformance(() => ({ store, now, advance, putViaLink, getViaLink, objectKeys }), { test }); // the runner's own `test`
+// putViaLink / getViaLink do what your storage service does with a PUT on an upload link and a GET on a read link.
+```
+
+## What is here, and what is coming
+
+| Export | State |
+| --- | --- |
+| `"."` the report contract | here |
+| `"./client"` ids, drafts, the report outbox and the recorder | here |
+| `"./client"` the toast, entry, sheet, receipt, My suggestions and detail (React 19, optional peer) | here |
+| `"./styles.css"` optional defaults | here |
+| `"./check"` and the `suggest-a-change-check` and `suggest-a-change init` commands | here |
+| `"./server"` the receiving side: handlers, store conformance suite, byte sniffing | here |
+
+Each export is added to `package.json` in the same change as its code, so nothing here points at a file that does not exist.
+
+## Status
+
+Version 0.1.0 is the first release and is published once by its owner (the first publish of a new package name cannot be a tag push). Every release after that is a pushed `v<version>` tag (GitHub Actions, npm trusted publishing). Below 1.0, additions are patch versions, so apps on `^0.1.0` take them without a change.
+
+## License
+
+MIT

package/bin/check.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// suggest-a-change-check: exit 0 clean, 1 problems, 2 usage.
+import { runCheck } from '../src/check/cli.mjs'
+process.exit(runCheck(process.argv.slice(2)))

package/bin/init.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// suggest-a-change init: exit 0 done, 2 usage.
+import { runInit } from '../src/check/init.mjs'
+process.exit(runInit(process.argv.slice(2)))

package/bin/suggest-a-change.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// suggest-a-change: the module's command line. Exit codes: 0 ok, 1 problems, 2 usage.
+//   suggest-a-change init [...]    wire an app to Suggest a change
+//   suggest-a-change check [...]   the screen check (also installed as suggest-a-change-check)
+import { runCheck } from '../src/check/cli.mjs'
+import { runInit } from '../src/check/init.mjs'
+
+const USAGE = `suggest-a-change: the report format and flow behind a Suggest a change button.
+
+Usage:
+  suggest-a-change init  [--repo <path>] [--app <id>] [--owner <name>] [--json]
+  suggest-a-change check [--repo <path>] [--config <file>] [--app-dir <dir>] [--adapters <file>] [--json]
+  suggest-a-change --help
+
+"check" is the same command as suggest-a-change-check. Run either with --help for its flags.
+The report contract is a library: import it from "@supersuit/suggest-a-change".`
+
+const [cmd, ...rest] = process.argv.slice(2)
+if (cmd === '--help' || cmd === '-h') { console.log(USAGE); process.exit(0) }
+if (cmd === 'init') process.exit(runInit(rest))
+if (cmd === 'check') process.exit(runCheck(rest))
+console.error(cmd ? `unknown command ${cmd}\n\n${USAGE}` : USAGE)
+process.exit(2)

package/dist/client/adapters.d.ts

@@ -0,0 +1,101 @@
+import type { ComponentType } from 'react';
+import type { CEILINGS } from '../contract.mjs';
+import type { Store } from './idb.ts';
+import type { StoreAdapter } from './reports.ts';
+import type { startTake } from './recorder.ts';
+import type { Words } from './words.ts';
+export type Role = 'operator' | 'member' | 'maintainer';
+export type Kind = 'change' | 'broken' | 'feedback';
+export type Identity = {
+    account: string;
+    role: Role;
+};
+export type HeardUpload = (key: string, blob: Blob, ms: number) => Promise<{
+    audio: string;
+    text: string;
+} | {
+    refused: string;
+}>;
+/** What a field needs of the host's runtime: the phone's database. A host's richer runtime fits. */
+export interface FieldRuntime {
+    store: Store;
+}
+/** The props every text field the module renders receives. Named and shaped after the Helm's golden
+ *  voice field (VoiceFieldProps), so the Helm passes that component into the `Field` slot as it is. */
+export interface FieldProps {
+    rt: FieldRuntime;
+    id: string;
+    label: string;
+    value: string;
+    onChange(v: string): void;
+    placeholder?: string;
+    multiline?: boolean;
+    type?: 'text' | 'search';
+    /** Gets each finished take. The sheet keeps the recording; transcription is the receiving Mac's job. */
+    upload?: HeardUpload;
+    onHeard?(h: {
+        audio: string;
+        text: string;
+    }): void;
+    onKept?(t: {
+        key: string;
+        ms: number;
+    }): void;
+    onHearing?(hearing: boolean): void;
+    disabled?: boolean;
+    persist?: boolean;
+    startTake?: typeof startTake;
+    /** A take stops by itself here and is kept at this length (the module's default field only). */
+    maxMs?: number;
+    /** Scopes this field's recorded takes (the sheet passes the draft key: app and account), so an interrupted take can only rejoin its own account. */
+    scope?: string;
+    /** The default field's own words, from the app's `words.text`. */
+    labels?: {
+        holdToTalk: string;
+        stopTalking: string;
+        micDenied: string;
+        voiceUnavailable: string;
+        voiceTotalLimit: string;
+    };
+}
+export interface Adapters {
+    /** Who is signed in; null when no one is. */
+    identity(): Promise<Identity | null>;
+    /** Where reports are kept. Must dedupe by report id (see StoreAdapter). */
+    store: StoreAdapter;
+    words: Words;
+    /** Lowers the ceilings; never raises them. */
+    limits?: Partial<typeof CEILINGS>;
+    Field?: ComponentType<FieldProps>;
+    /** One tap to attach a picture of the current screen. Without it the control is not shown. */
+    snapshot?(): Promise<Blob>;
+    /** Which app and version this is, stamped into every report. */
+    about?: {
+        app?: string;
+        template?: string;
+        templateVersion?: string;
+        copy?: string;
+        version?: string;
+    };
+    /** Where a received report lands: `'mac'` on a Helm that posts straight to the owner's Mac. */
+    lands?: 'app' | 'mac';
+    /** The phone's own database and reachability, for hosts that already hold them (and for tests). */
+    phone?: {
+        store?: Store;
+        reach?: {
+            check(force?: boolean): Promise<boolean>;
+            mark(up: boolean): void;
+        };
+        now?: () => number;
+        /** Reads a video's length in ms; undefined when it cannot be read. Defaults to the browser's own player. */
+        videoLength?(file: Blob): Promise<number | undefined>;
+        /** How long the default reader waits for the video's length before giving up. Default 3000. */
+        probeMs?: number;
+    };
+    /** Phone type for the device diagnostic. Defaults to a short name ("iPhone", "Android phone"). */
+    device?(): string;
+    /** The recorder the default field uses. Defaults to the module's own. */
+    startTake?: typeof startTake;
+    /** False when the receiving side cannot take a voice note added to a report afterwards (the detail view then says so). */
+    appendVoice?: boolean;
+}

package/dist/client/adapters.js

@@ -0,0 +1 @@
+export {};

package/dist/client/default-field.d.ts

@@ -0,0 +1,2 @@
+import type { FieldProps } from './adapters.ts';
+export declare function DefaultField(props: FieldProps): import("react").JSX.Element;

package/dist/client/default-field.js

@@ -0,0 +1,99 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// THE MODULE'S OWN VOICE FIELD, for hosted apps that have no golden one. A text area with a hold-to-talk
+// button beside it, in one [data-voice-field] container with nothing else typeable in it. A take is
+// recorded with the module's recorder (written to the phone's database as it is made). Transcription is
+// not done here: the take goes to `upload`, and the receiving Mac writes the transcript. A voice note
+// alone is a whole report, so a field with no words and one take is a complete answer.
+//
+// Holding the button records; letting go (or leaving it) stops. For anyone who cannot hold, Space or
+// Enter on the focused button starts a take and again stops it.
+import { useEffect, useRef, useState } from 'react';
+import { startTake as defaultStartTake } from './recorder.js';
+import { toast } from './toast.js';
+import { DEFAULT_STRINGS } from './words.js';
+export function DefaultField(props) {
+    const { rt, id, label, value, onChange, placeholder, multiline = false, type = 'text', upload, onHeard, onKept, onHearing, disabled, startTake = defaultStartTake, maxMs, labels, scope } = props;
+    const L = labels ?? DEFAULT_STRINGS;
+    // With nowhere to send a take, recording would lose it silently: the control stays, switched off, and says why.
+    const canRecord = Boolean(upload || onKept);
+    const [recording, setRecording] = useState(false);
+    const take = useRef(null);
+    const wanted = useRef(false);
+    const timer = useRef(null);
+    const latest = useRef(value);
+    latest.current = value;
+    const cb = useRef({ onChange, upload, onHeard, onKept, onHearing });
+    cb.current = { onChange, upload, onHeard, onKept, onHearing };
+    async function begin() {
+        if (take.current || wanted.current || disabled)
+            return;
+        // No time left: say so before recording instead of recording a note that will be refused.
+        if (maxMs !== undefined && maxMs <= 0) {
+            toast({ id: 'sac-limit', text: L.voiceTotalLimit, tone: 'warn' });
+            return;
+        }
+        wanted.current = true;
+        try {
+            const t = await startTake(rt.store, `take:${id}:${Date.now()}`, scope ? `${scope}|field:${id}` : `field:${id}`);
+            if (!wanted.current) {
+                await t.cancel();
+                return;
+            }
+            take.current = t;
+            setRecording(true);
+            if (maxMs)
+                timer.current = setTimeout(() => void end(), maxMs);
+        }
+        catch {
+            wanted.current = false;
+            toast({ id: 'sac-mic', text: L.micDenied, tone: 'warn' });
+        }
+    }
+    async function end() {
+        wanted.current = false;
+        if (timer.current) {
+            clearTimeout(timer.current);
+            timer.current = null;
+        }
+        const t = take.current;
+        if (!t)
+            return;
+        take.current = null;
+        setRecording(false);
+        const r0 = await t.stop();
+        // A take the timer ended is kept at the limit: the recorder reports a little longer than the timer ran.
+        const r = maxMs ? { ...r0, ms: Math.min(r0.ms, maxMs) } : r0;
+        cb.current.onHearing?.(true);
+        try {
+            if (!cb.current.upload) {
+                cb.current.onKept?.({ key: r.key, ms: r.ms });
+                return;
+            }
+            const h = await cb.current.upload(r.key, r.blob, r.ms);
+            if ('refused' in h) {
+                toast({ id: 'sac-refused', text: h.refused, tone: 'warn' });
+                return;
+            }
+            cb.current.onHeard?.(h);
+            if (h.text)
+                cb.current.onChange([latest.current.trim(), h.text].filter(Boolean).join(' '));
+        }
+        finally {
+            cb.current.onHearing?.(false);
+        }
+    }
+    useEffect(() => () => { wanted.current = false; if (timer.current)
+        clearTimeout(timer.current); void take.current?.cancel(); }, []);
+    const control = (_jsx("button", { type: "button", "data-voice-control": "", className: "sac-record", "aria-pressed": recording, "aria-label": canRecord ? `${recording ? L.stopTalking : L.holdToTalk}: ${label}` : `${L.voiceUnavailable}: ${label}`, disabled: disabled || !canRecord, onPointerDown: (e) => { e.preventDefault(); void begin(); }, onPointerUp: () => void end(), onPointerLeave: () => { if (wanted.current)
+            void end(); }, onPointerCancel: () => void end(), onContextMenu: (e) => e.preventDefault(), onKeyDown: (e) => {
+            if (e.key !== ' ' && e.key !== 'Enter')
+                return;
+            e.preventDefault();
+            if (e.repeat)
+                return;
+            void (take.current || wanted.current ? end() : begin());
+        }, children: _jsx("span", { "aria-hidden": "true", className: "sac-record-dot" }) }));
+    const shared = { id: `sac-field-${id}`, value, placeholder, disabled, className: 'sac-input', onChange: (e) => onChange(e.target.value) };
+    return (_jsxs("div", { "data-voice-field": "", className: "sac-voice", "data-recording": recording ? '' : undefined, children: [control, _jsx("label", { htmlFor: `sac-field-${id}`, className: "sac-sr", children: label }), multiline ? _jsx("textarea", { rows: 3, ...shared }) : _jsx("input", { type: type, ...shared })] }));
+}

package/dist/client/detail.d.ts

@@ -0,0 +1,17 @@
+import type { Adapters } from './adapters.ts';
+export declare function statusOf(r: Record<string, unknown>): string;
+/** The step shown under "Being made". The timeline entry is the truth (that is where the receiving side puts it); a top-level `step` is read only when there is no timeline. */
+export declare function stepOf(r: Record<string, unknown>): string | undefined;
+/** The strip is made from the contract's own statuses, one step per distinct word ("planned" reads as "With Freeda"),
+ *  and a step is marked from the report's timeline: reached, skipped (the report went past it), or still ahead. */
+export declare function StatusStrip({ status, owner, step, timeline, label }: {
+    status: string;
+    owner: string;
+    step?: string;
+    timeline?: string[]; /** The list's accessible name; the screens pass the app's own (words.text.stepLabel). */
+    label?: string;
+}): import("react").JSX.Element;
+export declare function SuggestionDetail({ adapters, id }: {
+    adapters: Adapters;
+    id: string;
+}): import("react").JSX.Element;