@interop/byoe-react-template 0.1.0

package/test/browser-was/replication.spec.ts

@@ -0,0 +1,154 @@
+/**
+ * WAS replication suite: real end-to-end sync against a local
+ * was-teaching-server (booted + provisioned in globalSetup). Each browser
+ * context is an independent IndexedDB replica; they all share the SAME dev seed
+ * and grants, so they replicate through one WAS Space.
+ *
+ * The pull side is poll-based (no server-side live stream): a fresh context
+ * pulls on open, and an already-open context re-pulls on the app's periodic
+ * reSync (tuned low in this config), so the tests wait rather than force a
+ * reload. Expect timeouts are generous because each hop is a poll interval plus
+ * a round trip. Note texts are unique per run because the Space is shared and
+ * long-lived. Tests are serialized (one shared Space).
+ */
+import { test, expect, type Page, type BrowserContext } from '@playwright/test'
+
+/** The add-note input. MUI puts the aria-label on the field wrapper, so target
+ * the actual <input> by its placeholder. */
+function addInput(page: Page) {
+  return page.getByPlaceholder('A new note...')
+}
+
+/** The list row locator for a note by its exact text on `page`. */
+function noteRow(page: Page, text: string) {
+  return page.getByTestId('notes-list').getByText(text, { exact: true })
+}
+
+/** Opens a fresh profile (isolated IndexedDB) and waits for it to be ready. */
+async function openProfile(context: BrowserContext): Promise<Page> {
+  const page = await context.newPage()
+  await page.goto('/')
+  await expect(addInput(page)).toBeVisible({ timeout: 30_000 })
+  return page
+}
+
+/** Adds a note with the given text on `page` and waits for its row. */
+async function addNote(page: Page, text: string): Promise<void> {
+  await addInput(page).fill(text)
+  await page.getByRole('button', { name: 'Add' }).click()
+  await expect(noteRow(page, text)).toBeVisible()
+}
+
+/** Edits the note with `from` text to `to` via the row's inline editor. */
+async function editNote(page: Page, from: string, to: string): Promise<void> {
+  await page.getByRole('button', { name: `edit ${from}` }).click()
+  const field = page.getByLabel('edit note').locator('input')
+  await field.fill(to)
+  await page.getByRole('button', { name: 'Save' }).click()
+}
+
+/** Waits for the sync-status chip to settle on the synced state. */
+async function expectSynced(page: Page): Promise<void> {
+  await expect(page.getByTestId('sync-status-chip')).toHaveAttribute(
+    'data-sync-state',
+    'synced',
+    { timeout: 30_000 }
+  )
+}
+
+test('the app boots into dev-sync and reaches the synced state', async ({
+  browser
+}) => {
+  const context = await browser.newContext()
+  const page = await openProfile(context)
+
+  // Replication started against the WAS server and settled: proof the dev
+  // grants provisioned in globalSetup are accepted end to end.
+  await expectSynced(page)
+
+  await context.close()
+})
+
+test('a note replicates to a second fresh profile', async ({ browser }) => {
+  const text = `repl-${Date.now()}`
+  const ctxA = await browser.newContext()
+  const a = await openProfile(ctxA)
+
+  await addNote(a, text)
+  await expectSynced(a)
+
+  // A fresh profile with the same seed + grants pulls the envelope on open and
+  // hydrates the note, with no manual reload.
+  const ctxB = await browser.newContext()
+  const b = await openProfile(ctxB)
+  await expect(noteRow(b, text)).toBeVisible({ timeout: 30_000 })
+
+  await ctxA.close()
+  await ctxB.close()
+})
+
+test('a note added in one profile converges to an already-open profile', async ({
+  browser
+}) => {
+  const text = `live-${Date.now()}`
+  const ctxA = await browser.newContext()
+  const ctxB = await browser.newContext()
+  const a = await openProfile(ctxA)
+  const b = await openProfile(ctxB)
+
+  // B is already open (past its initial pull) when A creates the note, so B can
+  // only see it via the app's periodic reSync polling the changes feed.
+  await addNote(a, text)
+  await expectSynced(a)
+  await expect(noteRow(b, text)).toBeVisible({ timeout: 30_000 })
+
+  await ctxA.close()
+  await ctxB.close()
+})
+
+test('an edit replicates to a second fresh profile', async ({ browser }) => {
+  const original = `edit-${Date.now()}`
+  const edited = `${original}-v2`
+  const ctxA = await browser.newContext()
+  const a = await openProfile(ctxA)
+
+  await addNote(a, original)
+  await expectSynced(a)
+
+  // Edit in place. The push is a conditional overwrite of the same envelope;
+  // a version-skew 412 is resolved by the payload LWW (updatedAt, deviceId)
+  // and re-pushed, so the new text must land server-side.
+  await editNote(a, original, edited)
+  await expect(noteRow(a, edited)).toBeVisible()
+
+  const ctxB = await browser.newContext()
+  const b = await openProfile(ctxB)
+  await expect(noteRow(b, edited)).toBeVisible({ timeout: 30_000 })
+  await expect(noteRow(b, original)).toHaveCount(0)
+
+  await ctxA.close()
+  await ctxB.close()
+})
+
+test('a delete replicates to a second fresh profile', async ({
+  browser
+}) => {
+  const text = `del-${Date.now()}`
+  const ctxA = await browser.newContext()
+  const a = await openProfile(ctxA)
+
+  await addNote(a, text)
+  await expectSynced(a)
+
+  // Soft-delete tombstone, pushed as a conditional server-side delete.
+  await a.getByRole('button', { name: `delete ${text}` }).click()
+  await expect(noteRow(a, text)).toHaveCount(0)
+
+  const ctxB = await browser.newContext()
+  const b = await openProfile(ctxB)
+  await expectSynced(b)
+  await expect(noteRow(b, text)).toHaveCount(0)
+
+  await ctxA.close()
+  await ctxB.close()
+})

package/test/browser-was/serverLifecycle.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared lifecycle for the WAS-backed Playwright suite: boot a local
+ * was-teaching-server, provision the dev Space + collections + grants against
+ * it, and tear the server down afterwards. globalSetup and globalTeardown run
+ * in the same Playwright runner process, so the child handle is stashed on
+ * `globalThis`.
+ *
+ * The was-teaching-server checkout is READ-ONLY and run as-is
+ * (`tsx src/start.ts`); we only set its SERVER_URL / PORT env, which MUST match
+ * the URL the client builds from the granted zcaps' invocationTargets. The
+ * server directory defaults to the sibling checkout and is overridable via
+ * WAS_SERVER_DIR.
+ */
+import { spawn, execFile, type ChildProcess } from 'node:child_process'
+import { promisify } from 'node:util'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const execFileAsync = promisify(execFile)
+
+const here = dirname(fileURLToPath(import.meta.url))
+const repoRoot = join(here, '..', '..')
+
+export const WAS_PORT = Number(process.env.WAS_E2E_PORT ?? 3102)
+export const WAS_SERVER_URL = `http://localhost:${WAS_PORT}`
+export const WAS_SERVER_DIR =
+  process.env.WAS_SERVER_DIR ?? join(repoRoot, '..', 'was-teaching-server')
+
+const HANDLE_KEY = Symbol.for('byoe-react-template.was-e2e.server')
+
+interface Stash {
+  child?: ChildProcess
+}
+
+function stash(): Stash {
+  const g = globalThis as unknown as Record<symbol, Stash>
+  g[HANDLE_KEY] ??= {}
+  return g[HANDLE_KEY]
+}
+
+/** Polls the server root until it answers, or throws after `timeoutMs`. */
+async function waitForServer(timeoutMs = 20000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`${WAS_SERVER_URL}/`)
+      if (response.ok || response.status === 404) {
+        return
+      }
+    } catch {
+      /* not up yet */
+    }
+    await new Promise(resolve => setTimeout(resolve, 300))
+  }
+  throw new Error(`was-teaching-server did not come up at ${WAS_SERVER_URL}`)
+}
+
+/** Boots the server and runs the provisioning script. Called by globalSetup. */
+export async function startServerAndProvision(): Promise<void> {
+  const child = spawn('npx', ['tsx', 'src/start.ts'], {
+    cwd: WAS_SERVER_DIR,
+    env: {
+      ...process.env,
+      SERVER_URL: WAS_SERVER_URL,
+      PORT: String(WAS_PORT),
+      STORAGE_LIMIT_PER_SPACE: 'unlimited'
+    },
+    detached: true,
+    stdio: 'ignore'
+  })
+  child.unref()
+  stash().child = child
+
+  await waitForServer()
+
+  await execFileAsync('npx', ['tsx', 'scripts/provision-dev-grants.ts'], {
+    cwd: repoRoot,
+    env: { ...process.env, SERVER_URL: WAS_SERVER_URL }
+  })
+}
+
+/** Stops the server (its whole detached process group). Called by globalTeardown. */
+export async function stopServer(): Promise<void> {
+  const child = stash().child
+  if (child?.pid) {
+    try {
+      process.kill(-child.pid, 'SIGTERM')
+    } catch {
+      /* already gone */
+    }
+  }
+}

package/test/node/notesStore.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Round-trips the notes entity store through the encrypted local replica: opens
+ * the app's own LocalStore (its COLLECTIONS, the dev seed) on fake-indexeddb,
+ * installs it, then drives useNotes insert / update / remove and asserts the
+ * registry hydrate re-reads the persisted, decrypted rows. A fresh replaceAll([])
+ * before each hydrate proves the docs come back from the replica, not stale
+ * in-memory Map state.
+ *
+ * @vitest-environment node
+ */
+import 'fake-indexeddb/auto'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import {
+  clearLocalStore,
+  hasStore,
+  LocalStore,
+  setLocalStore
+} from '@interop/was-react'
+import { COLLECTIONS } from '../../src/app.config'
+import { DEV_SEED } from '../../src/dev/devSeed'
+import { registry, useNotes, type Note } from '../../src/stores/notes'
+
+let dbCounter = 0
+let store: LocalStore | null = null
+let dbName = ''
+
+const notesEntry = registry.notes
+if (!notesEntry) {
+  throw new Error('the notes registry entry is missing')
+}
+
+function makeNote(text: string): Note {
+  const now = new Date().toISOString()
+  return {
+    id: crypto.randomUUID(),
+    text,
+    createdAt: now,
+    updatedAt: now,
+    deviceId: 'test-device'
+  }
+}
+
+async function openStore(name: string): Promise<LocalStore> {
+  const opened = await LocalStore.init({
+    seed: DEV_SEED,
+    collections: COLLECTIONS,
+    dbName: name
+  })
+  setLocalStore(opened)
+  return opened
+}
+
+beforeEach(async () => {
+  dbName = `byoe-notes-test-${++dbCounter}`
+  store = await openStore(dbName)
+  useNotes.getState().replaceAll([])
+})
+
+afterEach(async () => {
+  if (store) {
+    await store.close()
+    store = null
+  }
+  if (hasStore()) {
+    clearLocalStore()
+  }
+})
+
+describe('notes store round-trip through the encrypted LocalStore', () => {
+  it('installs the store the entity actions reach for', () => {
+    expect(hasStore()).toBe(true)
+  })
+
+  it('inserts a note and hydrates it back from the replica', async () => {
+    const note = makeNote('Buy distinctive-oat-milk-token')
+    await useNotes.getState().insert(note)
+
+    // Drop the in-memory Map; hydrate must repopulate it from the replica.
+    useNotes.getState().replaceAll([])
+    expect(useNotes.getState().byId.size).toBe(0)
+
+    await notesEntry.hydrate()
+
+    const byId = useNotes.getState().byId
+    expect(byId.size).toBe(1)
+    expect(byId.get(note.id)).toEqual(note)
+  })
+
+  it('updates a note in place, reflected after a fresh hydrate', async () => {
+    const note = makeNote('First text')
+    await useNotes.getState().insert(note)
+
+    const updated: Note = {
+      ...note,
+      text: 'Second text',
+      updatedAt: new Date().toISOString()
+    }
+    await useNotes.getState().update(updated)
+
+    useNotes.getState().replaceAll([])
+    await notesEntry.hydrate()
+
+    const byId = useNotes.getState().byId
+    expect(byId.size).toBe(1)
+    expect(byId.get(note.id)).toEqual(updated)
+  })
+
+  it('removes a note, gone after a fresh hydrate', async () => {
+    const keep = makeNote('Keep me')
+    const drop = makeNote('Ephemeral')
+    await useNotes.getState().insert(keep)
+    await useNotes.getState().insert(drop)
+
+    await useNotes.getState().remove(drop.id)
+
+    useNotes.getState().replaceAll([])
+    await notesEntry.hydrate()
+
+    const byId = useNotes.getState().byId
+    expect(byId.size).toBe(1)
+    expect(byId.has(drop.id)).toBe(false)
+    expect(byId.get(keep.id)).toEqual(keep)
+  })
+
+  it('encrypts at rest: no note text in the stored envelope', async () => {
+    const note = makeNote('distinctive-oat-milk-token')
+    await useNotes.getState().insert(note)
+
+    const rows = await store!.rxCollection('notes').find().exec()
+    expect(rows).toHaveLength(1)
+    const raw = JSON.stringify(rows[0]!.toMutableJSON())
+    expect(raw).not.toContain('distinctive-oat-milk-token')
+  })
+
+  it('persists across a store reopen (survives a reload)', async () => {
+    const note = makeNote('Durable note')
+    await useNotes.getState().insert(note)
+
+    await store!.close()
+    clearLocalStore()
+
+    store = await openStore(dbName)
+
+    useNotes.getState().replaceAll([])
+    await notesEntry.hydrate()
+
+    expect(useNotes.getState().byId.get(note.id)).toEqual(note)
+  })
+})

package/tsconfig.dev.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": [
+    "src/**/*",
+    "test/**/*.ts",
+    "vite.config.ts",
+    "playwright.config.ts",
+    "playwright.was.config.ts",
+    "playwright.wallet.config.ts",
+    "scripts/**/*.ts"
+  ],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vite.config.ts

@@ -0,0 +1,18 @@
+/// <reference types="vitest/config" />
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+const srcDir = fileURLToPath(new URL('./src', import.meta.url))
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': srcDir
+    }
+  },
+  test: {
+    include: ['test/node/**/*.test.ts', 'src/**/*.test.ts']
+  }
+})