@estiva-app/ui 0.22.0 → 0.23.0

package/README.md

@@ -137,6 +137,27 @@ but this package. The frame is `AppShell` with a `Sidebar`, one theme
 (`--theme`, default `light`) set once in `index.html`. Its README says what is
 left to do by hand: register the app with Estiva ID, and protect `main`.
 
+### The catalogue — `estiva-ui`
+
+"Do we already have this?" has one answer: `estiva-ui find <what it does>`.
+
+```bash
+npx estiva-ui find a floating panel     # the package's parts, and this app's own
+npx estiva-ui check                     # every part says what it is for (CI's job gate)
+```
+
+- **The package's catalogue** is `registry.json`, generated from the code,
+  committed and shipped: one entry per export, with its purpose, every prop it
+  declares, what it owns and where its page is.
+- **An app's catalogue** is built from the app's own code each time it is read,
+  and never committed. Every part a `.tsx` file exports is listed with its
+  purpose (a one-line `/** … */` above it), where the app uses it, and its kind:
+  a pass-on of a package part, used in one place, used in several, a candidate to
+  move into the package, or used nowhere. `estiva-ui check` fails on a part with
+  no description. `--also [name=]<folder>` adds an app that sits beside this one.
+- `@estiva-app/ui/registry` exports the builders and the search for a tool that
+  reads them itself.
+
 ## The rules
 
 ### Forking is allowed

package/dist/Banner.d.ts

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 /**
  * The strip under the header where the app says something happened —
  * one line, gone when there is nothing to say (Ship's Banner,
@@ -9,6 +10,11 @@
  * An `error` announces itself (`role="alert"`); the other tones are
  * polite (`role="status"`).
  *
+ * `icon` and `action` put a 16px icon before the line and one small muted
+ * Button after it (Katerina, 2026-09-18, UIG-13: Peek's composer strip became
+ * a Banner in the `info` tone). With either, the banner is one line and the
+ * text truncates.
+ *
  * `onDismiss` adds an `✕` at the right-hand end (Katerina, D21,
  * 2026-09-07). Without it the strip is exactly what it was — a banner an
  * app removes by not rendering it. With it the row is 40px rather than
@@ -23,12 +29,24 @@
 export type BannerTone = 'ok' | 'error' | 'info' | 'warning';
 export interface BannerProps {
     tone: BannerTone;
-    children: string;
+    /** The one line. Text, or text with a name in `font-medium`. */
+    children: ReactNode;
+    /**
+     * A 16px icon before the line, in the tone's colour (Katerina, 2026-09-18:
+     * Peek's composer strip became a Banner). With an icon or an action the
+     * banner is one line, and the text truncates.
+     */
+    icon?: ReactNode;
+    /** The one thing to do: the package's Button, muted and small, at the end of the line. */
+    action?: {
+        label: string;
+        onClick?: () => void;
+    };
     /** Adds an `✕` at the right-hand end. Absent: the app removes the banner. */
     onDismiss?: () => void;
     /** The dismiss button's accessible name. Defaults to "Dismiss". */
     dismissLabel?: string;
     className?: string;
 }
-export declare function Banner({ tone, children, onDismiss, dismissLabel, className }: BannerProps): import("react").JSX.Element;
+export declare function Banner({ tone, children, icon, action, onDismiss, dismissLabel, className }: BannerProps): import("react").JSX.Element;
 //# sourceMappingURL=Banner.d.ts.map

package/dist/Banner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Banner.d.ts","sourceRoot":"","sources":["../src/Banner.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;AAE5D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AASD,wBAAgB,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAwB,EAAE,SAAS,EAAE,EAAE,WAAW,+BAqBrG"}
+{"version":3,"file":"Banner.d.ts","sourceRoot":"","sources":["../src/Banner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAMtC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;AAE5D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,CAAA;IAChB,gEAAgE;IAChE,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,0FAA0F;IAC1F,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;KAAE,CAAA;IAChD,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAA;IACtB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AASD,wBAAgB,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,YAAwB,EAAE,SAAS,EAAE,EAAE,WAAW,+BA8BnH"}

package/dist/ContainerHeader.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react';
+/**
+ * The bar across the top of a column — a list, a thread, a side panel: its
+ * title, and the buttons that act on the whole column at the right edge.
+ * Peek's ContainerHeader, moved into the package exactly as it looks
+ * (Katerina, 2026-09-18, UIG-13).
+ *
+ * 48px tall, a hairline under it. A string title is one line in
+ * `body-2-strong` and keeps its width; anything else — an EditableText, a
+ * title over a caption — takes the room that is left and is drawn as given.
+ *
+ * Not a SectionHeader: that is the 32px row one section of a column starts
+ * with. This is the column's own bar, one per column.
+ */
+export interface ContainerHeaderProps {
+    /** A string keeps the one-line treatment; a node is drawn as given. */
+    title: ReactNode;
+    /** A chevron after the title, for a title that opens something. */
+    chevron?: boolean;
+    /** The column's own buttons, at the right edge: IconButtons with tooltips, 4px apart. */
+    actions?: ReactNode;
+    className?: string;
+}
+export declare function ContainerHeader({ title, chevron, actions, className }: ContainerHeaderProps): import("react").JSX.Element;
+//# sourceMappingURL=ContainerHeader.d.ts.map

package/dist/ContainerHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContainerHeader.d.ts","sourceRoot":"","sources":["../src/ContainerHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,KAAK,EAAE,SAAS,CAAA;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yFAAyF;IACzF,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,eAAe,CAAC,EAAE,KAAK,EAAE,OAAe,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,oBAAoB,+BAiBnG"}

package/dist/EmptyState.d.ts

@@ -25,7 +25,16 @@ export interface EmptyStateProps {
     message: string;
     /** `page` when the whole page is empty; `section` when one part of it is. */
     scope?: 'page' | 'section';
+    /**
+     * The one thing to do about it — "New topic", "Try again" — drawn 16px under
+     * the line as the package's Button, outlined (Katerina, 2026-09-18). A `page`
+     * only: a section's empty line is one line among others, not a stage.
+     */
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
     className?: string;
 }
-export declare function EmptyState({ icon, message, scope, className }: EmptyStateProps): import("react").JSX.Element;
+export declare function EmptyState({ icon, message, scope, action, className }: EmptyStateProps): import("react").JSX.Element;
 //# sourceMappingURL=EmptyState.d.ts.map

package/dist/EmptyState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmptyState.d.ts","sourceRoot":"","sources":["../src/EmptyState.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAc,EAAE,SAAS,EAAE,EAAE,eAAe,+BAUvF"}
+{"version":3,"file":"EmptyState.d.ts","sourceRoot":"","sources":["../src/EmptyState.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAA;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wBAAgB,UAAU,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAc,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,eAAe,+BAgB/F"}

package/dist/gates/app-checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-checks.d.ts","sourceRoot":"","sources":["../../src/gates/app-checks.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAA0B,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE/E,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAA;IACZ,8GAA8G;IAC9G,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;IACvC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,wGAAwG;IACxG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoBpD,CAAA;AAaD,wBAAgB,SAAS,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,GAAS,EAAE,IAAI,EAAE,KAAsC,EAAE,YAA8D,EAAE,OAA8C,EAAE,EAAE,eAAe,GAAG,UAAU,EAAE,CA2JpP"}
+{"version":3,"file":"app-checks.d.ts","sourceRoot":"","sources":["../../src/gates/app-checks.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAA0B,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE/E,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAA;IACZ,8GAA8G;IAC9G,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;IACvC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,wGAAwG;IACxG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqBpD,CAAA;AAaD,wBAAgB,SAAS,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,GAAS,EAAE,IAAI,EAAE,KAAsC,EAAE,YAA8D,EAAE,OAA8C,EAAE,EAAE,eAAe,GAAG,UAAU,EAAE,CAgLpP"}

package/dist/gates/{chunk-ZGJ2J5NU.js → chunk-EA33NP5B.js}

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import { APP_RULE_IDS } from "../eslint/index.js";
 var here = dirname(fileURLToPath(import.meta.url));
 var packageRoot = resolve(here, "..", "..");
+var ASKED_OF_NPM = ["@estiva-app/identity", "@estiva-app/interop", "@estiva-app/platform", "@estiva-app/protocol", "eslint-plugin-react-hooks"];
 function themes() {
   const css = readFileSync(join(packageRoot, "tokens.css"), "utf8");
   return ["light", ...new Set([...css.matchAll(/data-theme='([\w-]+)'/g)].map((m) => m[1]))];
@@ -38,12 +39,18 @@ function appFiles({ name, title = name, theme = "light", ui, versions = {} }) {
       "lint:rules": "eslint --config eslint.gates.config.js .",
       "postlint:rules": `estiva-gates count --repo ${name}`,
       "gates:status": "estiva-gates status",
+      "ui:find": "estiva-ui find",
+      registry: "estiva-ui build",
+      "registry:check": "estiva-ui check",
       test: "vitest run",
       storybook: "storybook dev -p 6006",
       "build-storybook": "storybook build"
     },
     dependencies: {
       "@estiva-app/identity": own("@estiva-app/identity"),
+      "@estiva-app/interop": own("@estiva-app/interop"),
+      "@estiva-app/platform": own("@estiva-app/platform"),
+      "@estiva-app/protocol": own("@estiva-app/protocol"),
       "@estiva-app/ui": ui ?? `^${pkg.version}`,
       ...deps(["@tabler/icons-react", "react", "react-dom"])
     },
@@ -94,7 +101,9 @@ function appFiles({ name, title = name, theme = "light", ui, versions = {} }) {
 `;
   return {
     "package.json": json(packageJson),
-    ".gitignore": ["node_modules", "dist", "storybook-static", "*.local", "*.log", "*.tsbuildinfo", ".DS_Store", ""].join("\n"),
+    // registry.json: the app's catalogue, written only when `npm run registry` is asked
+    // to. It is built fresh from the code every time it is read, so it is never kept.
+    ".gitignore": ["node_modules", "dist", "storybook-static", "*.local", "*.log", "*.tsbuildinfo", ".DS_Store", "registry.json", ""].join("\n"),
     ".env.example": `# Estiva ID, for signing in. Copy this file to .env.local and fill both in.
 #
 # Left empty, the app offers no sign-in at all and runs anonymous: it never
@@ -106,6 +115,16 @@ function appFiles({ name, title = name, theme = "light", ui, versions = {} }) {
 # server; a local one (http://localhost:8787) in its database.
 VITE_ESTIVA_ID_ORIGIN=
 VITE_ESTIVA_ID_CLIENT_ID=${name}
+
+# The relay: the workspace this app reads and writes.
+#
+# Left empty, the app runs alone. It opens no connection, and its home page says
+# so. It also needs sign-in above: the relay refuses anything before sign-in, so
+# with a relay and no sign-in there is still no connection. And Estiva ID must
+# allow this app to sign in to that relay (the README says how).
+#
+# A relay running on this machine is http://localhost:3000.
+VITE_RELAY_URL=
 `,
     "index.html": `<!doctype html>
 <html lang="en"${themeAttr}>
@@ -312,6 +331,10 @@ jobs:
       - run: npm ci
       - name: Gate lint
         run: npm run lint:rules
+      # Every part of the app says in one line what it is for, so the catalogue
+      # (\`npm run ui:find\`) can offer it before someone builds it again.
+      - name: Every part is described
+        run: npm run registry:check
 `,
     "src/index.css": `@import '@estiva-app/ui/tokens.css';
 @import '@estiva-app/ui/base.css';
@@ -331,6 +354,7 @@ body,
 interface ImportMetaEnv {
   readonly VITE_ESTIVA_ID_ORIGIN?: string
   readonly VITE_ESTIVA_ID_CLIENT_ID?: string
+  readonly VITE_RELAY_URL?: string
 }
 `,
     "src/config.ts": `/** What the app is called on screen. */
@@ -345,6 +369,22 @@ export const ID_CONFIG: { base: string; clientId: string } | null =
   import.meta.env.VITE_ESTIVA_ID_ORIGIN && import.meta.env.VITE_ESTIVA_ID_CLIENT_ID
     ? { base: import.meta.env.VITE_ESTIVA_ID_ORIGIN.replace(/\\/+$/, ''), clientId: import.meta.env.VITE_ESTIVA_ID_CLIENT_ID }
     : null
+
+/**
+ * The relay, the workspace this app reads and writes, or \`null\` when this build
+ * has none. Empty is a real mode too: the app runs alone and opens no connection,
+ * and a local build can never reach the real relay by accident. See .env.example.
+ */
+export const RELAY_URL: string | null = import.meta.env.VITE_RELAY_URL?.trim().replace(/\\/+$/, '') || null
+
+/** The relay as a person would name it: host and port, no scheme. */
+export function relayLabel(url: string): string {
+  try {
+    return new URL(url).host
+  } catch {
+    return url
+  }
+}
 `,
     "src/auth/estivaId.ts": `import { createEstivaId, type ShellReason, type StoredToken } from '@estiva-app/identity'
 import { ID_CONFIG } from '../config'
@@ -529,6 +569,131 @@ export function AuthShell({ state, onContinue }: AuthShellProps) {
     </div>
   )
 }
+`,
+    "src/relay/client.ts": `import { signViaEstivaId } from '@estiva-app/identity'
+import { browserOnlineSource, createLiveClientHolder, type LiveClient } from '@estiva-app/platform'
+import { currentToken } from '../auth/estivaId'
+import { ID_CONFIG, RELAY_URL } from '../config'
+
+/**
+ * The event kinds this app reads. They are the app's own decision, and the one
+ * blank a new app fills in: Ship reads seven (projects, issues, changes,
+ * messages, comments, deletions and edits), Peek its own. Until there are kinds
+ * here the app is connected and reads nothing, which is a correct state.
+ */
+export const KINDS: number[] = []
+
+/**
+ * The tab's one relay client. \`@estiva-app/platform\` hands out a holder and
+ * keeps nothing, so this line is where "one connection per tab" lives. The relay
+ * signs a connection in once and caps subscriptions per connection, so a
+ * connection per component is wrong, not only wasteful; React's StrictMode,
+ * which mounts everything twice, is what would show it.
+ *
+ * Peek and Ship hold theirs the same way. Everything the client needs is handed
+ * in and nothing here reads the app's own data, so it could move into
+ * \`@estiva-app/platform\` as it is, if that is ever worth doing.
+ */
+const holder = createLiveClientHolder()
+
+/**
+ * The client, or \`null\` when this build cannot have one: no relay is set, or
+ * there is no sign-in. The relay refuses anything before sign-in, so a socket
+ * without it would only connect, be refused and retry.
+ */
+export function relayClient(): LiveClient | null {
+  const base = ID_CONFIG?.base
+  if (!RELAY_URL || !base) return null
+  return holder.get({
+    relayUrl: RELAY_URL,
+    // Read on every connect, never kept: a token kept from the first connect
+    // outlives a silent renewal as a dead one, and the next reconnect fails.
+    getCredential: () => {
+      const token = currentToken()
+      return token ? { accessToken: token.accessToken, pubkey: token.pubkey } : null
+    },
+    // \`expectedPubkey\` is a check, not a request. Estiva ID signs as the token's
+    // owner whatever it is handed, so a mismatch comes back as a valid event
+    // signed by somebody else. Always pass it.
+    sign: (unsigned, token, expectedPubkey) => signViaEstivaId(unsigned, { base, token, expectedPubkey }),
+    online: typeof window === 'undefined' ? undefined : browserOnlineSource(window),
+    // Names this app in the relay's own logs.
+    subscriptionPrefix: '${name}-',
+    log: (message, detail) => console.debug('[relay]', message, detail ?? ''),
+  })
+}
+`,
+    "src/relay/useRelayState.ts": `import type { RelayState } from '@estiva-app/protocol'
+import { useSyncExternalStore } from 'react'
+import { relayClient } from './client'
+
+const subscribe = (onChange: () => void): (() => void) => relayClient()?.onState(onChange) ?? (() => {})
+const snapshot = (): RelayState | 'off' => relayClient()?.state() ?? 'off'
+
+/** The connection's state, for a page to show: \`'off'\` when this build has no client. */
+export function useRelayState(): RelayState | 'off' {
+  return useSyncExternalStore(subscribe, snapshot, () => 'off')
+}
+`,
+    "src/relay/client.test.ts": `import { afterEach, describe, expect, it, vi } from 'vitest'
+
+/**
+ * The tab's one relay connection. A fake socket stands in for the relay, so this
+ * runs with no network, and counts the sockets opened.
+ */
+class FakeSocket {
+  static opened = 0
+  onopen: (() => void) | null = null
+  onmessage: ((event: { data: unknown }) => void) | null = null
+  onclose: (() => void) | null = null
+  onerror: (() => void) | null = null
+  constructor() {
+    FakeSocket.opened += 1
+  }
+  send() {}
+  close() {}
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+  vi.unstubAllGlobals()
+  vi.resetModules()
+  FakeSocket.opened = 0
+})
+
+describe('the relay client', () => {
+  it('opens no connection when no relay is set', async () => {
+    vi.stubEnv('VITE_RELAY_URL', '')
+    vi.stubEnv('VITE_ESTIVA_ID_ORIGIN', 'http://localhost:8787')
+    vi.stubEnv('VITE_ESTIVA_ID_CLIENT_ID', '${name}')
+    vi.stubGlobal('WebSocket', FakeSocket)
+    const { relayClient } = await import('./client')
+    expect(relayClient()).toBeNull()
+    expect(FakeSocket.opened).toBe(0)
+  })
+
+  it('opens no connection with a relay and no sign-in', async () => {
+    vi.stubEnv('VITE_RELAY_URL', 'http://localhost:3000')
+    vi.stubEnv('VITE_ESTIVA_ID_ORIGIN', '')
+    vi.stubGlobal('WebSocket', FakeSocket)
+    const { relayClient } = await import('./client')
+    expect(relayClient()).toBeNull()
+    expect(FakeSocket.opened).toBe(0)
+  })
+
+  it('holds one connection per tab, however often it is asked', async () => {
+    vi.stubEnv('VITE_RELAY_URL', 'http://localhost:3000')
+    vi.stubEnv('VITE_ESTIVA_ID_ORIGIN', 'http://localhost:8787')
+    vi.stubEnv('VITE_ESTIVA_ID_CLIENT_ID', '${name}')
+    vi.stubGlobal('WebSocket', FakeSocket)
+    const { relayClient } = await import('./client')
+    const first = relayClient()
+    expect(first).not.toBeNull()
+    expect(relayClient()).toBe(first)
+    expect(FakeSocket.opened).toBe(1)
+    first?.close()
+  })
+})
 `,
     "src/main.tsx": `import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
@@ -562,13 +727,15 @@ void (async () => {
 import { IconHome } from '@tabler/icons-react'
 import { useEffect, useState } from 'react'
 import { beginSignOut, currentToken, whoAmI } from './auth/estivaId'
-import { APP_TITLE, ID_CONFIG } from './config'
+import { APP_TITLE, ID_CONFIG, RELAY_URL } from './config'
 import { HomePage } from './pages/HomePage'
+import { useRelayState } from './relay/useRelayState'
 
 /** The frame: the package's AppShell with a sidebar, and the one page. */
 export function App() {
   const signedIn = currentToken() !== null
   const [me, setMe] = useState<Identity>({})
+  const relayState = useRelayState()
 
   useEffect(() => {
     if (!signedIn) return
@@ -591,19 +758,53 @@ export function App() {
         </Sidebar>
       }
     >
-      <HomePage />
+      <HomePage relay={RELAY_URL} state={relayState} name={me.name} />
     </AppShell>
   )
 }
 `,
-    "src/pages/HomePage.tsx": `import { EmptyState } from '@estiva-app/ui'
+    "src/pages/HomePage.tsx": `import type { RelayState } from '@estiva-app/protocol'
+import { EmptyState } from '@estiva-app/ui'
+import { relayLabel } from '../config'
+
+export interface HomePageProps {
+  /** The relay this build is set to, or \`null\` when the app runs alone. */
+  relay: string | null
+  /** The connection's state: \`'off'\` when this build has no client. */
+  state: RelayState | 'off'
+  /** The signed-in person's name, once Estiva ID has said it. */
+  name?: string
+}
+
+const SAYS: Record<RelayState, (host: string, name?: string) => string> = {
+  connecting: (host) => \`Connecting to \${host}\u2026\`,
+  authenticating: (host) => \`Signing in to \${host}\u2026\`,
+  live: (host, name) => (name ? \`Connected to \${host} as \${name}.\` : \`Connected to \${host}.\`),
+  reconnecting: (host) => \`Reconnecting to \${host}\u2026\`,
+  failed: (host) => \`Could not connect to \${host}.\`,
+}
 
-/** The first page. What it becomes is this app's own work. */
-export function HomePage() {
+/**
+ * The first page. What it becomes is this app's own work; until then it says
+ * whether the app is connected to the relay, and as whom.
+ *
+ * The empty state goes straight into the frame's \`main\`, with no box around it:
+ * \`main\` is a flex column, so the empty state takes the room left and centres
+ * in it both ways, as its own page says. A box around it would place it
+ * instead, and no gate reads a box. The connection is a quiet caption after it,
+ * at the foot of the page.
+ */
+export function HomePage({ relay, state, name }: HomePageProps) {
+  const line = !relay
+    ? 'Running alone: no relay is set. Set VITE_RELAY_URL in .env.local to connect.'
+    : state === 'off'
+      ? \`Not connected: \${relayLabel(relay)} needs sign-in, and this build has none.\`
+      : SAYS[state](relayLabel(relay), name)
   return (
-    <div className="flex justify-center px-6 py-16">
+    <>
       <EmptyState message="Nothing here yet." />
-    </div>
+      <p className="px-6 pb-6 text-center text-caption text-text-muted">{line}</p>
+    </>
   )
 }
 `,
@@ -614,12 +815,28 @@ const meta = {
   title: 'Pages/Home',
   component: HomePage,
   parameters: { layout: 'fullscreen' },
+  // Stands in for the frame's main: a flex column the height of the screen,
+  // which is what the page is drawn into in the app.
+  decorators: [
+    (Story) => (
+      <div className="flex h-screen flex-col">
+        <Story />
+      </div>
+    ),
+  ],
 } satisfies Meta<typeof HomePage>
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const Empty: Story = {}
+/** No relay set: the app runs alone, the way it starts. */
+export const RunningAlone: Story = { args: { relay: null, state: 'off' } }
+
+/** A relay set, before it has signed the connection in. */
+export const Connecting: Story = { args: { relay: 'http://localhost:3000', state: 'connecting' } }
+
+/** Connected, as the person who signed in. */
+export const Connected: Story = { args: { relay: 'http://localhost:3000', state: 'live', name: 'Alex Kim' } }
 `,
     "src/App.test.tsx": `import { render, screen } from '@testing-library/react'
 import { describe, expect, it } from 'vitest'
@@ -631,6 +848,7 @@ describe('${title}', () => {
     render(<App />)
     expect(screen.getAllByText(APP_TITLE).length).toBeGreaterThan(0)
     expect(screen.getByText('Nothing here yet.')).toBeTruthy()
+    expect(screen.getByText(/^Running alone/)).toBeTruthy()
     expect(screen.getByRole('link', { name: 'Home' })).toBeTruthy()
   })
 })
@@ -674,6 +892,40 @@ With no settings it runs **anonymous**: no sign-in is offered, and nothing reach
 the real Estiva ID. To sign in, copy \`.env.example\` to \`.env.local\` and fill it in.
 The app must first be registered with that Estiva ID as its own app.
 
+## The relay
+
+${title} is connected to the relay, the workspace, from its first commit, as
+whoever signed in. \`src/relay/client.ts\` holds the tab's one connection: ask it
+for \`relayClient()\`, and never open a socket of your own. The home page shows the
+connection's state.
+
+With \`VITE_RELAY_URL\` empty it runs alone and opens no connection. The relay
+also needs sign-in, so with a relay and no sign-in there is no connection either.
+
+Three packages come with it: \`@estiva-app/protocol\` (the wire: events, ids,
+signing, the relay clients), \`@estiva-app/platform\` (the one connection a tab
+holds) and \`@estiva-app/interop\` (showing another app's objects, from the
+manifest that app publishes).
+
+## What you fill in
+
+1. \`.env.local\`: Estiva ID and the relay (see \`.env.example\`).
+2. \`KINDS\` in \`src/relay/client.ts\`: the event kinds ${title} reads. Until then
+   it is connected and reads nothing.
+3. The product: its pages, and the fold that turns what arrives on the
+   connection into the app's state.
+
+Before ${title} can sign in on the real Estiva ID it has to be registered there
+as its own app, with:
+
+- its exact redirect address
+- every event kind it will sign, **including 22242**, the relay's sign-in handshake
+- the relay's address, allowed for that handshake. Estiva ID signs a handshake
+  only for a relay both the app and the deployment allow.
+
+Anything left out fails at the very last step: every screen looks right, and
+nothing arrives.
+
 ## The checks
 
 | command | what |
@@ -684,6 +936,8 @@ The app must first be registered with that Estiva ID as its own app.
 | \`npm test\` | the tests |
 | \`npm run build\` | the build |
 | \`npm run gates:status\` | which gates are on, read from the code |
+| \`npm run ui:find <words>\` | what the package and this app already have for it |
+| \`npm run registry:check\` | every part says what it is for \u2014 CI's job \`gate\` |
 | \`npm run storybook\` | the stories |
 
 The gates are the package's, imported rather than copied, so a rule written later
@@ -712,6 +966,16 @@ only with its reason on the line above, \`// @estiva-escape: <reason>\`, never w
 
 **Tokens only.** Colours, type, corners and shadows come from the package's preset.
 
+**One relay connection per tab.** \`relayClient()\` in \`src/relay/client.ts\` is the
+connection. Never open a socket and never make a second holder: the relay signs a
+connection in once, and caps subscriptions per connection.
+
+**Look before you build.** \`npm run ui:find <what it does>\` searches the package's
+parts and this app's own. Use what it finds.
+
+**Every part says what it is for.** A new part gets a one-line \`/** \u2026 */\` comment
+directly above it. \`npm run registry:check\` and CI's job \`gate\` refuse a part without one.
+
 **The count starts at zero and stays there** (\`.gates-count.json\`, \`docs/GATES-DEBT.md\`).
 
 What each gate is and how it is wired: the package's README,
@@ -734,7 +998,7 @@ function createApp(options) {
   const dir = resolve(options.parent ?? process.cwd(), options.name);
   if (existsSync(dir)) throw new Error(`${dir} already exists: create-estiva-app never writes into a folder that is there`);
   const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-  const missing = ["@estiva-app/identity", "eslint-plugin-react-hooks"].filter((n) => !pkg.devDependencies[n] && !options.versions?.[n]);
+  const missing = ASKED_OF_NPM.filter((n) => !pkg.devDependencies[n] && !options.versions?.[n]);
   const versions = { ...missing.length ? askNpm(missing) : {}, ...options.versions };
   const files = appFiles({ ...options, versions });
   for (const [rel, text] of Object.entries(files)) {
@@ -751,4 +1015,4 @@ export {
   askNpm,
   createApp
 };
-//# sourceMappingURL=chunk-ZGJ2J5NU.js.map
+//# sourceMappingURL=chunk-EA33NP5B.js.map