@interop/byoe-react-template 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+
+      # Provision pnpm via Corepack (bundled with Node) from the
+      # `packageManager` pin in package.json, avoiding the flaky
+      # pnpm/action-setup self-installer.
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm run lint
+
+      - name: Typecheck
+        run: pnpm run typecheck
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Test (Node)
+        run: pnpm run test:node
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Test (Browser)
+        run: pnpm run test:browser

package/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write        # required for npm provenance
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      # Provision pnpm via Corepack (bundled with Node) from the
+      # `packageManager` pin in package.json, avoiding the flaky
+      # pnpm/action-setup self-installer.
+      - name: Enable Corepack
+        run: corepack enable
+
+      # Node 24's bundled npm is already >= 11.5.1, as trusted publishing
+      # requires. Do not `npm install -g npm@latest` here: npm overwriting
+      # itself in the runner toolcache leaves it unable to resolve `sigstore`.
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Publish to npm
+        run: npm publish

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0 - TBD
+
+### Changed
+
+- Scoped the package name to `@interop/byoe-react-template` (the unscoped
+  `byoe-react-template` npm package is deprecated).
+
+### Added
+
+- Initial BYOE app template: a Vite + React + TypeScript SPA built on
+  `@interop/was-react`.
+- CHAPI wallet login (DID Auth) with a protected route and offline dev mode.
+- An example WAS-backed "notes" collection with local-first encrypted storage
+  and background sync.
+- MUI app shell with sync status and reconnect UI.
+- Three-tier test setup (offline/mocked, real WAS server, full wallet login)
+  plus a Node unit tier.
+- A dev provisioning script for syncing without a wallet.

package/CLAUDE.md

@@ -0,0 +1,55 @@
+# byoe-react-template (BYOE Notes)
+
+A minimal, working "Bring Your Own Everything" (BYOE) app template: a Vite +
+React + TypeScript SPA with DID-Auth login via a CHAPI wallet, local-first
+encrypted storage, and background sync to a WAS server, built on
+`@interop/was-react`. It ships one example "notes" collection. The library owns
+the reusable plumbing (identity, login, session, encrypted replica, sync, hooks,
+MUI components); this repo is the thin app-specific shell around it.
+
+## Source layout
+
+- `src/app.config.ts` -- env-var exports and the one `WasAppConfig` the library
+  consumes (app name, credential type/vocab, `COLLECTIONS` map). First stop when
+  renaming the template.
+- `src/stores/notes.ts` -- the example entity store (`createEntityStore`) plus
+  the `StoreRegistry` the rehydrate mechanism drives.
+- `src/dev/` -- dev-mode bootstrap (`bootstrap.ts` opens the local store from
+  `devSeed.ts` and hydrates) and `devSync.ts` (CHAPI-bypassed replication from a
+  provisioned grants file).
+- `src/components/` -- `AppShell` (top bar, `SyncStatusChip`, `ReconnectBanner`,
+  logout) and `DevGate` (dev-mode router gate; wallet mode uses the library's
+  `ProtectedRoute`).
+- `src/pages/` -- `LoginPage` (CHAPI login) and `NotesPage` (list/add/edit/
+  delete).
+- `scripts/provision-dev-grants.ts` -- provisions a dev Space, collections, and
+  delegated zcaps against a running was-teaching-server.
+- `playwright.config.ts` (offline/mocked, CI), `playwright.was.config.ts` (real
+  WAS server), `playwright.wallet.config.ts` (full wallet login), and `test/`
+  tiers, plus Node unit tests via Vitest.
+
+## Commands
+
+```
+pnpm dev                     # wallet mode; VITE_AUTH_MODE=dev for offline mode
+pnpm run build               # typecheck + Vite build
+pnpm run typecheck
+pnpm run lint
+pnpm run fix                 # eslint --fix + prettier
+pnpm run test:node           # Vitest + fake-indexeddb
+pnpm run test:browser        # Playwright, offline/mocked (CI)
+pnpm run test:browser:was    # Playwright against a real local WAS server
+pnpm run test:browser:wallet # Playwright full wallet login (local/manual)
+pnpm run provision:dev       # provision dev grants (SERVER_URL, default :3002)
+```
+
+## Conventions
+
+- pnpm; Node >= 24; ESM only.
+- Prettier: no semicolons, single quotes, no trailing commas,
+  `arrowParens: avoid`.
+- Never use the right-arrow character (write `to`), em-dash character (write
+  `--`), or ellipsis character (write `...`).
+- Inline single-use option/argument types at the function signature instead of
+  declaring a named type.
+- Keep app-agnostic logic in `@interop/was-react` rather than growing it here.

package/LICENSE.md

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Interop Alliance
+
+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

@@ -0,0 +1,217 @@
+# BYOE Notes _(@interop/byoe-react-template)_
+
+[![Node.js CI](https://github.com/interop-alliance/byoe-react-template/workflows/CI/badge.svg)](https://github.com/interop-alliance/byoe-react-template/actions?query=workflow%3A%22CI%22)
+[![NPM Version](https://img.shields.io/npm/v/@interop/byoe-react-template.svg)](https://npm.im/@interop/byoe-react-template)
+
+> A template for building "Bring Your Own Everything" (BYOE) apps on Wallet
+> Attached Storage: a Vite + React + TypeScript SPA with DID-Auth login via a
+> CHAPI wallet, local-first encrypted storage, and background sync, built on
+> [`@interop/was-react`](https://npm.im/@interop/was-react).
+
+## Table of Contents
+
+- [Background](#background)
+- [What is in this template](#what-is-in-this-template)
+- [Install](#install)
+- [Usage](#usage)
+- [Renaming this template into a new app](#renaming-this-template-into-a-new-app)
+- [Testing](#testing)
+- [Contribute](#contribute)
+- [License](#license)
+
+## Background
+
+"Bring Your Own Everything" (BYOE) is a way to build web apps with no backend
+that the app owns. The user brings their own identity (a wallet) and their own
+storage (Wallet Attached Storage, WAS), and the app stores everything encrypted
+in that user-owned space. The app is a Relying Party: it authenticates via
+"Login With Wallet" (CHAPI) and reads and writes the user's WAS space using
+wallet-delegated authorization capabilities (zcaps). It never owns the space,
+never holds the wallet's root key, and invokes only the zcaps the wallet grants
+it.
+
+"Bring Your Own Storage" (BYOS) is the storage half of that model. Every
+collection is encrypted client-side as an Encrypted Data Vault (EDV): the WAS
+server only ever sees opaque JWE envelopes and can neither read nor search the
+plaintext. Data is local-first -- a local RxDB (IndexedDB) database holds the
+encrypted envelopes and replicates them to WAS in the background. The app works
+fully offline; sync resumes on reconnect.
+
+This template is a minimal, working BYOE app that wires all of that up through
+`@interop/was-react`, which owns the reusable plumbing (identity derivation, the
+CHAPI login flow, the session lifecycle, the encrypted local replica, WAS
+replication, and the React hooks and MUI components). For the depth on those
+pieces -- the login flow, session lifecycle, and sync architecture -- see the
+[`@interop/was-react` README](https://npm.im/@interop/was-react). This document
+covers what the template ships and how to make it your own.
+
+## What is in this template
+
+- A **login page** (`src/pages/LoginPage.tsx`) driving DID-Auth login through
+  CHAPI: one "Login with wallet" button, a per-phase progress line, and an error
+  alert.
+- A **protected route**: in wallet mode the library's `ProtectedRoute` (from
+  `@interop/was-react/mui`) gates the app; in offline dev mode a local `DevGate`
+  plays the same role.
+- One example **WAS-backed "notes" collection** (`src/pages/NotesPage.tsx` +
+  `src/stores/notes.ts`): list, add, edit, and delete notes, read from an
+  in-memory store hydrated from the encrypted local replica and replicated to
+  WAS in the background.
+- An **MUI app shell** (`src/components/AppShell.tsx`): a top bar with the app
+  name, the library's `SyncStatusChip` (offline / syncing / synced / error), a
+  logout button, and the `ReconnectBanner` shown when granted access nears
+  expiry.
+- A **dev provisioning script** (`scripts/provision-dev-grants.ts`) for syncing
+  against a local WAS server without a wallet in the loop, and a **three-tier
+  test setup** (see [Testing](#testing)).
+
+## Install
+
+### Prerequisites
+
+- **Node.js >= 24** and **pnpm** (the repo pins `pnpm@11.9.0`).
+- For real background sync, a **WAS server** --
+  [`was-teaching-server`](https://github.com/interop-alliance/) run locally.
+- For wallet login, a **CHAPI wallet** -- for example
+  [`freewallet`](https://github.com/interop-alliance/), or any CHAPI wallet
+  reachable through the [authn.io](https://authn.io) mediator.
+
+### Setup
+
+```
+pnpm install
+```
+
+## Usage
+
+### Auth modes
+
+The app runs in one of two auth modes, selected by `VITE_AUTH_MODE`:
+
+- **Wallet mode (default).** `pnpm dev` serves the login page and gates the app
+  behind Login With Wallet. This needs a CHAPI wallet and a WAS server to
+  complete a login and sync.
+
+  ```
+  pnpm dev
+  ```
+
+- **Offline dev mode.** `VITE_AUTH_MODE=dev pnpm dev` skips login entirely and
+  boots straight into a local encrypted store keyed by a fixed public dev seed.
+  No wallet, no server, no sync -- just the UI against the local replica. Good
+  for developing screens.
+
+  ```
+  VITE_AUTH_MODE=dev pnpm dev
+  ```
+
+- **Dev mode with sync.** Dev mode plus `VITE_WAS_DEV_SYNC=true` replicates to a
+  running WAS server without a wallet, using a locally provisioned grants file.
+  First, with a `was-teaching-server` running, provision the grants:
+
+  ```
+  pnpm run provision:dev
+  ```
+
+  This creates a dev Space and the app's collections on the server (default
+  `http://localhost:3002`, override with `SERVER_URL`) and writes the delegated
+  zcaps to the git-ignored `public/dev-grants.local.json`. Then run:
+
+  ```
+  VITE_AUTH_MODE=dev VITE_WAS_DEV_SYNC=true pnpm dev
+  ```
+
+> The fixed dev seed is public. Never use dev mode (or that seed) for anything
+> real: anything encrypted under it is readable by anyone.
+
+### Environment variables
+
+All are optional; see `src/app.config.ts` for the defaults.
+
+| Variable                  | Default                  | Purpose                                                                |
+| ------------------------- | ------------------------ | ---------------------------------------------------------------------- |
+| `VITE_AUTH_MODE`          | `wallet`                 | `wallet` (CHAPI login gate) or `dev` (local dev-seed store, no login). |
+| `VITE_APP_ORIGIN`         | `http://localhost:5173`  | This app's origin; the CHAPI anti-phishing binding on the app key.     |
+| `VITE_WAS_SERVER_URL`     | `http://localhost:3002`  | Remote WAS server; the expected host of every granted zcap.            |
+| `VITE_WAS_DEV_SYNC`       | `false`                  | Dev mode only: replicate to WAS using a provisioned grants file.       |
+| `VITE_WAS_DEV_GRANTS_URL` | `/dev-grants.local.json` | Where the app fetches the dev grants JSON from.                        |
+| `VITE_WAS_SYNC_RETRY_MS`  | (library default)        | Replication retry backoff, in ms.                                      |
+| `VITE_WAS_SYNC_POLL_MS`   | (library default)        | Periodic re-sync interval, in ms.                                      |
+
+### Other scripts
+
+```
+pnpm run build       # typecheck, then Vite production build
+pnpm run typecheck   # tsc --noEmit
+pnpm run lint        # eslint over src, test, scripts
+pnpm run fix         # eslint --fix, then prettier --write
+```
+
+## Renaming this template into a new app
+
+To turn "BYOE Notes" into your own app:
+
+1. **`package.json`** -- change `name` and `description`.
+2. **`src/app.config.ts`** -- set `appConfig.appName`, the
+   `credential.credentialType` and `credential.vocabBase` (a unique credential
+   type and vocab URI for your app's seed credential), and the `COLLECTIONS`
+   list (see step 5).
+3. **`index.html`** -- change the `<title>`.
+4. **UI strings** -- replace the "BYOE Notes" text in
+   `src/components/AppShell.tsx` and `src/pages/LoginPage.tsx`.
+5. **Replace the notes collection with your own.** Each collection needs three
+   things:
+   - a `{ key, id }` entry in `COLLECTIONS` in `src/app.config.ts` (the app-side
+     `key` maps to the WAS collection `id`, a deliberately unprefixed, generic
+     name shared across interoperable apps);
+   - an **entity store** created with `createEntityStore<T>(key)` (see
+     `src/stores/notes.ts`);
+   - a **registry entry** wiring that store's `hydrate` / `patch` / `drop` /
+     `replaceAll` handlers into the exported `StoreRegistry`.
+
+   Then build a page against your store's `insert` / `update` / `remove` verbs,
+   modeled on `src/pages/NotesPage.tsx`, and route to it in `src/App.tsx`.
+
+   Every entity payload MUST carry `updatedAt` (ISO timestamp) and `deviceId`
+   (from the library's `getDeviceId()`), stamped on every insert and update:
+   remote conflicts are resolved last-writer-wins on that pair, and a payload
+   without them loses every conflict to the server copy.
+
+## Testing
+
+The template has three browser test tiers plus a Node unit tier. The offline
+tier is the CI-suitable default; the WAS and wallet tiers need sibling checkouts
+of the supporting servers.
+
+```
+pnpm run test:node          # Vitest + fake-indexeddb, Node (no browser)
+pnpm run test:browser       # Playwright, offline/mocked dev mode; CI-suitable
+pnpm run test:browser:was   # Playwright against a real local WAS server
+pnpm run test:browser:wallet # Playwright full wallet login flow; local/manual
+```
+
+- **`test:node`** runs the Vitest suite against `fake-indexeddb`. No browser or
+  server needed.
+- **`test:browser`** (the default `playwright.config.ts`) serves the app in
+  offline dev mode and drives the UI against the local encrypted replica only.
+  No sibling checkouts or servers required.
+- **`test:browser:was`** (`playwright.was.config.ts`) boots a local
+  `was-teaching-server` from a sibling `../was-teaching-server` checkout
+  (override with `WAS_SERVER_DIR`), provisions dev grants, and exercises real
+  replication in dev-sync mode.
+- **`test:browser:wallet`** (`playwright.wallet.config.ts`) boots the WAS server
+  plus a `freewallet` dev server (sibling `../freewallet`, override with
+  `FREEWALLET_DIR`) and runs the full Login With Wallet flow. This is a
+  local/manual tier, not for CI.
+
+The combined `pnpm test` runs `lint` then `test:node`.
+
+## Contribute
+
+PRs accepted. If editing this README, please conform to the
+[standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+Keep app-agnostic logic in `@interop/was-react` rather than growing it here.
+
+## License
+
+[MIT License](LICENSE.md) (c) 2026 Interop Alliance.

package/_spec/phase2-handoff.md

@@ -0,0 +1,143 @@
+# Phase 2 handoff: build `byoe-react-template`
+
+Phase 1 is DONE: `@interop/was-react` is fully extracted, tested, documented
+(local checkout at `~/code/Interop/was-react`, for reading source/API), and
+published to npm as `@interop/was-react@0.1.2`. This file gives a fresh
+session everything needed to build
+the template app in THIS repo (`~/code/Interop/byoe-react-template`, currently
+an empty clone).
+
+## Goal (from the original prompt)
+
+A minimal but complete Vite + React + TypeScript SPA, `private: true`, no
+packaging machinery, demonstrating the BYOE pattern end to end by consuming
+`@interop/was-react`. Keep the template thin: anything app-agnostic belongs in
+the library.
+
+Required app content:
+- Login page with DID Auth via CHAPI (wallet polyfill wired up)
+- One protected route behind `ProtectedRoute` (from `@interop/was-react/mui`)
+- One example WAS-backed collection ("notes"): list/add/edit/delete,
+  local-first with sync, `SyncStatusChip` in the app shell
+- MUI app shell with `ReconnectBanner`
+
+Tooling modeled on `~/code/Dima/life-advisor/package.json`: scripts `dev`,
+`build` (typecheck + `vite build`), `fix`, `format`, `lint`, `typecheck`,
+`test`, `test:node`, `test:browser`, `test:browser:was`,
+`test:browser:wallet`, `provision:dev`; pnpm; `engines.node >= 24`; MIT;
+author "Interop Alliance" (https://github.com/interop-alliance/); eslint flat
+config + prettier + tsconfig conventions as in life-advisor /
+isomorphic-lib-template.
+
+Testing: vitest + fake-indexeddb for unit tests; THREE Playwright configs
+(mocked / real WAS server / real wallet) mirroring life-advisor's
+`playwright.config.ts`, `playwright.was.config.ts`,
+`playwright.wallet.config.ts`; plus the dev-grants provisioning script
+(`provision:dev` calls the library's `@interop/was-react/dev`).
+
+README: what BYOE/BYOS is (brief), prerequisites (WAS server, wallet), how to
+rename the template into a new app, how to run each test tier. Also a short
+CLAUDE.md describing structure and conventions.
+
+Constraints: do NOT modify life-advisor, freewallet, or was-react (except:
+publishing reminder below). Check in with the user when the template is done.
+
+## Consuming @interop/was-react
+
+Published: use `"@interop/was-react": "^0.1.2"` from the npm registry (do NOT
+use link:/file: references). was-react peers the template must install:
+`react >= 19`, `react-dom`, `zustand ^5`, `rxdb ^17`, and for the mui entry:
+`@mui/material ^9`, `@mui/icons-material ^9`, `@emotion/react`,
+`@emotion/styled`, `react-router ^8`. Node-only dev entry needs `tsx` to run
+the provision script (or use the installed `was-provision-dev-grants` bin).
+
+## was-react API facts (verified)
+
+- Wrap app above the router:
+  `<WasSessionProvider config={appConfig} registry={storeRegistry}>`.
+- `WasAppConfig`: `{ appName, appOrigin, collections: [{ key, id }],
+  credential: { credentialType, vocabBase }, wasServerUrl?, mediatorBase?,
+  dbName?, storageKeyPrefix?, sync?, expiry? }`. The library builds the
+  documentLoader/LoginConfig internally from this.
+- `StoreRegistry = Record<collectionKey, { hydrate(): Promise<void>;
+  upsert(doc: {id}): void; drop(uuid): void; clear(): void }>` -- one entry
+  per `collections[].key`.
+- `createEntityStore` (zustand factory) exposes
+  `hydrate/insert/update/remove/replaceAll/patch/drop` -- NO `upsert`/`clear`;
+  registry wiring needs small adapters: `upsert -> patch` (with a cast),
+  `clear -> replaceAll([])`. The was-react README quick start shows exactly
+  this for a "notes" store -- FOLLOW IT. (Optional improvement noted with the
+  user: a `toRegistryEntry(store)` helper in was-react could remove this
+  boilerplate; fine to add to was-react during Phase 2 if it proves annoying,
+  it was offered and not rejected.)
+- Hooks: `useLogin()` -> `{ login, status, phase, error }` (phases:
+  `probing`/`storing-key`/`requesting-grants`/`verifying`), `useSession`,
+  `useLogout`, `useReconnect`, `useSyncStatus` (rollup:
+  offline / error > syncing > synced), `useAppReady`.
+- `@interop/was-react/mui`: `ProtectedRoute` (props incl.
+  `loginPath`, default `/login`; calls `restore()` on mount, redirects
+  unauthenticated), `ReconnectBanner`, `SyncStatusChip`. Wallet-mode only (no
+  dev-mode branch; life-advisor's dev `initApp`/`AUTH_MODE` pattern stays
+  app-side -- the template does NOT need a dev mode unless the WAS e2e tier
+  requires dev-sync, see below).
+- Dev sync (no wallet): app-side wiring like life-advisor's `devSync.ts` --
+  fetch a grants JSON, `parseGrants`, `deriveIdentity({ seed })`,
+  `startWasSync({ parsed, zcapClient, localStore,
+  syncController: createSyncController({ collections, sync }),
+  onRemoteChange: (key, event) => patchFromChange(registry, key, event) })`.
+  Library exports all of these from the root entry.
+- `@interop/was-react/dev`: `provisionDevGrants({ serverUrl, seed,
+  collections: string[], spaceName?, outFile?, probe? })`; CLI
+  `was-provision-dev-grants --server-url --seed (hex|base64url)
+  --collections a,b --space-name --out --probe`.
+- CHAPI E2E test bridge globals (for Playwright without a real mediator):
+  `__WAS_REACT_E2E_CHAPI__` (activation flag),
+  `__WAS_REACT_E2E_CHAPI_REQUESTS__`, `__WAS_REACT_E2E_CHAPI_RESPONSES__`;
+  active when `import.meta.env.MODE !== 'production'`.
+- Read `~/code/Interop/was-react/README.md` -- its Quick start section is the
+  authoritative wiring example (all symbols verified against source).
+
+## Playwright tier facts (from life-advisor + freewallet)
+
+- Default config: offline/mocked suite, vite dev server, single chromium.
+- WAS config: serialized, single worker; boots the app AND a real WAS server
+  from a sibling checkout `../was-teaching-server` (env override
+  `WAS_SERVER_DIR`), server started with `pnpm run dev` and env
+  `PORT`/`SERVER_URL`; the server's `SERVER_URL` must EXACTLY equal the
+  client's `VITE_WAS_SERVER_URL` (zcap invocation-target host match).
+  life-advisor's version uses globalSetup/globalTeardown to provision grants.
+- Wallet config: boots 3 servers -- was-teaching-server, freewallet
+  (`../freewallet`, env `FREEWALLET_DIR`), and the app. life-advisor's
+  playwright.wallet.config.ts hardcodes `/Users/dmitriz/...` defaults --
+  use env-overridable relative defaults (`../was-teaching-server`,
+  `../freewallet`) instead.
+- freewallet CI note: only the mocked tier runs in CI; WAS/wallet tiers are
+  local/manual (need sibling checkouts).
+
+## Repo conventions (user's rules)
+
+- pnpm, Node >= 24, MIT, author Interop Alliance. Do not commit or bump
+  versions; user handles that. CHANGELOG dates are `TBD`.
+- Never use the characters `→` (use `to`), mdash (use `--`), `…` (use `...`).
+- Never mention `_spec` dirs, roadmap phases/tracks, or bedrock libraries in
+  CHANGELOG/code comments.
+- TS style: single-use options types inlined at signatures; single-field
+  interfaces inlined at usage.
+- pnpm build-script approvals: if scripts fail with ERR_PNPM_IGNORED_BUILDS,
+  set `allowBuilds: esbuild: true` in pnpm-workspace.yaml (was done in
+  was-react). Lockfile/minimumReleaseAge issues: stop and ask the user.
+- Delegate to Opus 4.8 sub-agents whenever appropriate.
+- Prettier in these repos: no semicolons, single quotes, no trailing commas,
+  arrowParens avoid, proseWrap always.
+
+## Suggested plan
+
+1. Scaffold: Vite React-TS app modeled on life-advisor's tooling (copy its
+   eslint/prettier/tsconfig conventions; `private: true`, no exports/files/
+   publishConfig). `@interop/was-react@^0.1.2` + peers.
+2. App: config + notes entity store + registry + provider + router (login
+   page, protected `/notes` route, MUI shell with ReconnectBanner +
+   SyncStatusChip). Deliberately minimal, every piece demonstrating one part.
+3. Tests: vitest unit (notes store round-trip w/ fake-indexeddb), 3 Playwright
+   tiers, provision:dev script.
+4. README + CLAUDE.md. Check in with user when done.

package/eslint.config.js

@@ -0,0 +1,40 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+import prettierConfig from 'eslint-config-prettier'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist', '**/*.min.js']),
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      prettierConfig // must be last in extends
+    ],
+    languageOptions: {
+      ecmaVersion: 2022,
+      globals: { ...globals.browser, ...globals.node },
+      parserOptions: {
+        project: ['./tsconfig.dev.json']
+      }
+    },
+    rules: {
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+          destructuredArrayIgnorePattern: '^_'
+        }
+      ],
+      '@typescript-eslint/no-explicit-any': 'off',
+      curly: ['error', 'all'],
+      'no-var': 'error',
+      'prefer-const': 'error'
+    }
+  }
+])

package/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>BYOE Notes</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@interop/byoe-react-template",
+  "description": "Template for building 'Bring Your Own Everything' (BYOE) apps on Wallet Attached Storage: a Vite + React + TypeScript SPA with DID Auth login via a CHAPI wallet, local-first encrypted storage, and background sync, built on @interop/was-react.",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit -p tsconfig.dev.json && vite build",
+    "typecheck": "tsc --noEmit -p tsconfig.dev.json",
+    "fix": "eslint --fix src test && pnpm run format",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\" \"test/**/*.ts\" \"scripts/**/*.ts\" \"*.md\"",
+    "lint": "eslint src test scripts",
+    "test": "pnpm run lint && pnpm run test:node",
+    "test:browser": "playwright test",
+    "test:browser:was": "playwright test -c playwright.was.config.ts",
+    "test:browser:wallet": "playwright test -c playwright.wallet.config.ts",
+    "test:node": "vitest run",
+    "provision:dev": "tsx scripts/provision-dev-grants.ts"
+  },
+  "dependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@interop/was-react": "^0.1.3",
+    "@mui/icons-material": "^9.0.0",
+    "@mui/material": "^9.0.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router": "^8.1.0",
+    "rxdb": "^17.0.0",
+    "uuidv7": "^1.2.1",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.60.0",
+    "@types/node": "^26.0.1",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.0",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "fake-indexeddb": "^6.0.0",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.3",
+    "tsx": "^4.20.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.4",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"
+  },
+  "packageManager": "pnpm@11.9.0",
+  "engines": {
+    "node": ">=24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Interop Alliance (https://github.com/interop-alliance/)",
+  "license": "MIT"
+}