@astrale-os/adapter-cloudflare 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/adapter-cloudflare",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Deploy an Astrale domain as a standalone Cloudflare Worker",
   "keywords": [
     "adapter",

package/template/.agents/skills/astrale-cli/SKILL.md

@@ -91,7 +91,7 @@ Examples:
 
 ```bash
 astrale call /:blog.acme.com:class.Author:list
-astrale call /:blog.acme.com:interface.NoteOps:createNote title=Hello
+astrale call /:blog.acme.com:interface.MonitorOps:watch url=https://astrale.ai
 astrale call /blog.acme.com/alice::deactivate
 astrale call @f00d...::deactivate
 ```

package/template/.agents/skills/astrale-domain/SKILL.md

@@ -42,8 +42,8 @@ domain.ts           # THE manifest — wires it ALL: defineDomain({ schema, meth
                     #   a renamed module is a compile error here, not a missing route.
 astrale.config.ts   # binds the domain to its deploy adapter (deploy(domain, …)) — node-only
 schema/             # classes/interfaces/edges — the contract (zod props, fn signatures)
-                    #   + compiled.ts (D = compileDomain) — the public compiled entry
-core/               # pure, transport-agnostic logic + keys.ts (compiled accessors)
+                    #   + index.ts exports D = compileDomain(schema) (resolved paths/keys)
+core/<context>/     # pure, transport-agnostic logic per bounded context (e.g. core/monitor: keys/health/node)
 integrations/       # external-API ports + adapters + a lazy registry (see §4) — what deps is built from
 runtime/index.ts    # composition root: the methods map; each execute resolves deps → calls core logic
 functions/          # standalone remote functions (webhook-shaped endpoints)
@@ -123,7 +123,7 @@ Handler context: `kernel` (callback client bound to the composed credential —
 caller's delegated authority ∪ this function's own), `self` (instance methods),
 `params` (zod-validated), `deps` (your typed `Deps` from `deps.ts`; raw `Env` if
 you omit the mapper), `auth` (principal, verified claims). Resolve ports from
-`deps` per request (`deps.summarizer()` — the registry builds + caches them per
+`deps` per request (`deps.prober()` — the registry builds + caches them per
 isolate) — NEVER construct external clients at module load (workers must be
 import-side-effect-free).
 
@@ -167,7 +167,7 @@ example — Scaleway/WorkOS/KV):
 
 1. **Port** — a narrow interface in `integrations/<feature>/port.ts` declaring
    only what the logic needs (`WeatherClient { forecast(city) }`, the scaffold's
-   `Summarizer { summarize(body) }`). `core/` logic depends on the port, never
+   `Prober { probe(url) }`). `core/` logic depends on the port, never
    on fetch/SDKs/env.
 2. **Adapter(s) + registry** — `createXClient(config)` in
    `integrations/<feature>/` (one per backend), plus a `registry.ts` that reads
@@ -177,7 +177,7 @@ example — Scaleway/WorkOS/KV):
    upstream detail in `cause`. The registry builds the chosen adapter LAZILY +
    caches it per isolate (a worker never validates an unused backend's env).
 3. **Wiring** — `deps.ts` mounts the registry (`defineDomain({ deps })`); the
-   `execute` hook resolves the PORT from `deps` (`deps.summarizer()`) per
+   `execute` hook resolves the PORT from `deps` (`deps.prober()`) per
    request and passes it to the `core/` logic.
 
 Secrets & config:

package/template/.env.example

@@ -5,10 +5,8 @@
 #
 # EXAMPLE_API_KEY=sk-...
 #
-# ── Summarizer (the example external-API integration) ──────────────────────
-# The scaffold summarizes notes with a no-network heuristic by default. To use a
-# real OpenAI-compatible model instead, set NOTE_SUMMARIZER=http and provide:
-# NOTE_SUMMARIZER=http
-# SUMMARIZER_API_KEY=sk-...
-# SUMMARIZER_BASE_URL=https://api.openai.com/v1
-# SUMMARIZER_MODEL=gpt-4o-mini
+# ── Prober (the example external-API integration) ──────────────────────────
+# The scaffold probes monitor targets with a real, KEYLESS HTTP request by
+# default (no secret needed). These knobs are optional config, not secrets:
+# PROBER=http                # `http` (default) | `mock` (offline/deterministic)
+# PROBE_TIMEOUT_MS=10000

package/template/README.md

@@ -27,7 +27,7 @@ pnpm prod                         # deploy prod → prints a URL
 
 ```
 schema/        classes + interfaces (the data model) + compiled accessors
-core/          pure, transport-agnostic logic + keys.ts (never hand-write keys)
+core/<context>/ pure, transport-agnostic logic per bounded context (e.g. core/monitor)
 integrations/  external-API ports + adapters + a lazy registry (built into deps)
 runtime/       the execute() handlers — the composition root (the methods map)
 views/         iframe-mountable UIs
@@ -89,7 +89,7 @@ adapter-owned keys `name`, `main`, `assets`, `routes` are rejected (use
 
 - **Edit a handler** (`core/` logic or `runtime/` wiring) → hot-reloads at the same URL. Nothing to reinstall.
 - **Edit the schema** (`schema/`) → rebuilds the graph; reinstall with `astrale domain install <url> --direct`.
-- **`postInstall`** (the static `Note.seed` method) runs once after install, as
+- **`postInstall`** (the static `Monitor.seed` method) runs once after install, as
   the system identity, so the domain can seed itself and set its own grants. It
   must be a class-hosted static addressed by a typed colon-path
   (`/:origin:class.X:seed`) — the kernel refuses tree paths here.

package/template/client/README.md

@@ -1,38 +1,64 @@
 # astrale-domain-client — SPA for domain views
 
-A small React + Vite SPA that renders the domain's `ui-note` View. It is loaded
-inside an iframe mounted by the Astrale shell, runs the shell handshake to learn
-its target node id and a delegation token, fetches that Note from the kernel,
-and renders its title/body. Built into `../.dist/` and served by the
-generated worker (`.astrale/`) under `/ui/*` via its `ASSETS` binding.
-
-## Self-contained on purpose
-
-This client depends only on `react`, `react-dom`, `vite`, and
-`@vitejs/plugin-react` — all on public npm. It does **not** import
-`@astrale-os/shell`, `@astrale-os/kernel-client`, or `@astrale-os/ui-components`,
-so the template builds with no registry auth and no workspace `link:`s. Two
-small subsets are reimplemented inline:
-
-- the shell child-handshake (`src/lib/shell.ts`), and
-- a minimal JSON kernel client (`src/lib/kernel.ts`).
+A small React + Vite SPA that renders the domain's Views. It is loaded inside an
+iframe mounted by the Astrale shell, runs the shell handshake (via the real
+`@astrale-os/shell`) to learn its target node id and a kernel session, fetches
+that node from the kernel, and renders it. The bundled `ui-monitor` view loads a
+Monitor and renders its status/url/latency, with a "Check now" button that calls
+the Monitor's `check` instance method and reloads the node. Built into `../.dist/`
+and served by the generated worker (`.astrale/`) under `/ui/*` via its `ASSETS`
+binding.
+
+## Built on the real shell SDK
+
+This client consumes `@astrale-os/shell` for the child handshake AND the kernel
+client: `src/shell/use-shell.ts` boots `createShell({ mode: 'sandboxed' })`, and
+feature hooks call kernel methods through `shell.kernel` (token refresh, codec
+negotiation, redirect following, and delegation are all handled by the SDK — no
+inline wire code). `@` is aliased to `src/` (mirrors `tsconfig` paths), so feature
+code imports `@/shell`, `@/ui`, `@/monitor`.
 
 ## Layout
 
+Feature-first: each feature owns its types/api/mappers/hooks/components. The
+`shell/` and `ui/` folders are the generic, domain-neutral seams every feature
+builds on.
+
 ```
 src/
   main.tsx              # entry → createRoot(App)
-  app.tsx               # the ui-note view (renders the loaded Note)
-  lib/
-    shell.ts            # inline shell child handshake (postMessage + MessagePort)
-    use-shell.ts        # React hook over the handshake (status + live session)
-    kernel.ts           # inline kernel JSON client (kernelCall + prop readers)
-    use-node.ts         # React hook: fetch a node via @<id>::get
-  styles.css            # self-contained styles (no Tailwind)
+  app.tsx               # path router: ROUTES { '/ui/monitor': MonitorView }
+  styles.css            # self-contained styles (no Tailwind), design tokens
+  shell/                # GENERIC kernel/shell adapter on @astrale-os/shell
+    client.ts           #   prop readers (PROP, readProp, readPropBySuffix) + errors
+    invoke.ts           #   callMethod / invokeNode (@<id>::<method>) / nodeAddr
+    use-shell.ts        #   useShell() → createShell({ mode: 'sandboxed' })
+    use-node.ts         #   useNode(session, id) → @<id>::get (+ reload)
+    use-async.ts        #   generic reloadable async resource
+    use-capability.ts   #   write lifecycle (idle → running → done/failed)
+    transformers.ts     #   qualified-prop / link / node-array shaping
+    view-router.tsx     #   resolveView(routes) + ViewFrame (handshake gate)
+    index.ts            #   barrel → @/shell
+  ui/                   # PURE presentation — no kernel, no hooks
+    surface.tsx         #   Panel / ErrorBanner / EmptyState / Spinner
+    badge.tsx           #   StatusBadge (up | down | unknown)
+    value.tsx           #   KV / Mono / ExternalLink
+    format.ts           #   relativeTime
+    index.ts            #   barrel → @/ui
+  monitor/              # THE Monitor feature (template example)
+    monitor.types.ts    #   MonitorRecord
+    monitor.api.ts      #   check(session, id) → @<id>::check
+    monitor.mappers.ts  #   monitorFromNode (node → record)
+    hooks/              #   useMonitor.query / useCheck.mutation
+    components/         #   MonitorCard (container: hooks + @/ui)
+    index.ts            #   barrel → @/monitor
+  views/
+    monitor.tsx         #   MonitorView = <ViewFrame>…<MonitorCard/></ViewFrame>
 __tests__/
-  harness.ts            # fake shell parent + fake kernel (fetch stub)
-  app.test.tsx          # handshake → render → setTarget → tokenRefresh
-  kernel.test.ts        # kernelCall wire shape + prop readers
+  harness.ts            # fake shell parent (real protocol) + fake kernel (fetch stub)
+  app.test.tsx          # handshake → render → check now → setTarget → fallback
+  seam.test.tsx         # pure @/ui + @/monitor hooks in isolation (no handshake)
+  kernel.test.ts        # pure helpers: prop readers, mapper, relativeTime
 ```
 
 ## Dev loops
@@ -40,7 +66,7 @@ __tests__/
 ```bash
 pnpm dev       # vite build --watch → ../.dist/ (worker auto-reloads, no HMR)
 pnpm dev:hmr   # vite dev on http://127.0.0.1:5173/ (React fast-refresh)
-pnpm test      # vitest run (happy-dom; fake parent + fake kernel, JSON-only)
+pnpm test      # vitest run (happy-dom; fake parent speaks the real shell protocol)
 ```
 
 For HMR, set `VIEW_DEV_URL=http://127.0.0.1:5173` in the worker's `.dev.vars`;
@@ -48,38 +74,29 @@ the generated worker forwards `/ui/*` to vite.
 
 ## How it connects
 
-1. The domain declares the View in `../views/note.ts` with `mount: '/ui/note'`.
-   The SDK points the View node's iframe at `<serving url>/ui/note`.
-2. The shell mounts that iframe and completes the handshake: it transfers a
-   `MessagePort` and sends a `ctrl:handshake` carrying `kernelUrl`, a
-   `delegationToken` (+ `tokenExpiresAt`), and the `targetNodeId`. `useShell()`
-   surfaces a live session and tracks `setTarget` hot-swaps.
-3. `useNode(session, nodeId)` POSTs `@<id>::get` to `kernelUrl` with the
-   delegation token as `authorization` and renders the Note's `title`/`body`
-   (props are read by key suffix, since the domain origin is unknown at build
-   time). The iframe authenticates with the handshake token ONLY — the parent
-   minted it for this kernel, so the audience already matches (no cookie, no
-   whoami, no client-side minting).
-
-### Token refresh
-
-The parent pushes a fresh credential over the port as `ctrl:tokenRefresh`
-before the current one expires. `shell.ts` swaps it into a mutable `currentToken`
-so the next `kernelCall` (e.g. on the next `setTarget` or remount) uses it —
-`getToken()` always returns the live token, never the one captured at handshake.
-
-## Deferred — kept minimal on purpose
-
-The inline kernel client is **JSON-only** and read-only for this template:
-
-- no msgpack codec (the `application/vnd.astrale.kernel+msgpack` body),
-- no streaming (`output: 'stream'`) or binary (`output: 'binary'`) responses,
-- no redirect following — a `{ redirect }` envelope (remote-domain Functions)
-  throws rather than re-minting against the target worker,
-- no client-side credential minting / `whoami` (the handshake token is used
-  as-is), and
-- no writes — only `@<id>::get`.
-
-These all live in `@astrale-os/kernel-client` / `@astrale-os/shell`. To grow
-past the template, pull those in (and `link:` them in dev) instead of extending
-the inline subset.
+1. The domain declares each View in `../views/` with `mount: '/ui/<path>'`. The
+   SDK points the View node's iframe at `<serving url>/ui/<path>`.
+2. The shell mounts that iframe and completes the handshake (a transferred
+   `MessagePort` + a `ctrl:handshake` carrying `kernelUrl`, the delegation token,
+   and the `targetNodeId`). `useShell()` boots `@astrale-os/shell`, surfaces the
+   kernel session, and tracks `setTarget` hot-swaps.
+3. A feature loads its node through the session: `useNode(session, nodeId)` calls
+   `@<id>::get` over `shell.kernel`, and a mapper (`monitorFromNode`) projects it
+   to a typed record. Domain props are read by key SUFFIX (`.property.url`, …)
+   because the domain origin is unknown at build time; the name uses the kernel
+   `Named.name` key.
+4. Writes go through `useCapability`: "Check now" runs `@<id>::check`, then calls
+   `useMonitor`'s `reload()` so the fresh status/latency re-render. The shell's
+   kernel client owns the credential and refreshes it before expiry — features
+   never touch the token.
+
+## Adding a view
+
+1. Write a `ViewComponent` (usually wrapping `ViewFrame`) under `src/views/`.
+2. Add a `ROUTES` entry keyed by its mount path in `src/app.tsx`.
+3. Register a matching `defineView({ mount: '/ui/<path>' })` in the domain's
+   `views/` so the shell mounts an iframe there.
+
+For a NEW feature, mirror `src/monitor/`: a `*.types.ts`, `*.api.ts`,
+`*.mappers.ts`, a `hooks/` folder of `.query`/`.mutation` hooks, and a
+`components/` folder of containers that compose `@/ui`.

package/template/client/__tests__/app.test.tsx

@@ -1,21 +1,32 @@
-import { act, cleanup, render, screen } from '@testing-library/react'
-import { afterEach, describe, expect, it } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
-import { App } from '../src/app'
-import { type CapturedRequest, installFakeKernel, installFakeParent, noteNode, ok } from './harness'
+import { App } from '@/app'
+import { installFakeKernel, installFakeParent, monitorNode, ok } from './harness'
 
 const KERNEL_URL = 'https://k.example.test/api'
-const KERNEL_TYPE = 'application/vnd.astrale.kernel+json'
+
+/**
+ * The router picks a view from `window.location.pathname`, so every test mounts
+ * at a known path. `replaceState` rewrites the happy-dom location without a
+ * reload. Default to the Monitor detail path; the fallback test overrides.
+ */
+function mountAt(path: string) {
+  window.history.replaceState({}, '', path)
+}
+
+beforeEach(() => {
+  mountAt('/ui/monitor')
+})
 
 afterEach(() => {
   cleanup()
 })
 
 /**
- * Let the handshake + any kernel fetch settle, flushing the resulting React
+ * Let the handshake + any kernel fetches settle, flushing the resulting React
  * state updates inside `act`. The handshake completes over a real MessagePort
- * (async hops), so a microtask isn't enough — a short timer pump is. Wrapping
- * it in `act` keeps the updates warning-free and committed before we assert.
+ * (async hops), so a microtask isn't enough — a short timer pump is.
  */
 async function flush(ms = 20) {
   await act(async () => {
@@ -23,35 +34,36 @@ async function flush(ms = 20) {
   })
 }
 
-/** Common assertions on a captured kernel request for `@<id>::get`. */
-function expectGetCall(req: CapturedRequest, nodeId: string, token: string) {
-  // POST to the kernel URL with a trailing slash added.
-  expect(req.method).toBe('POST')
-  expect(req.url).toBe(`${KERNEL_URL}/`)
-  // Bare delegation token (no "Bearer ").
-  expect(req.headers['authorization']).toBe(token)
-  // Kernel JSON envelope content type on both content-type and accept.
-  expect(req.headers['content-type']).toBe(KERNEL_TYPE)
-  expect(req.headers['accept']).toBe(KERNEL_TYPE)
-  // Envelope body shape.
-  expect(req.body.method).toBe(`@${nodeId}::get`)
-  expect(req.body.params).toEqual({})
-  expect(req.body.id).toBeTruthy()
+function handshake(targetNodeId?: string) {
+  return installFakeParent({
+    windowId: 'win-1',
+    kernelUrl: KERNEL_URL,
+    functionId: 'ui-monitor',
+    delegationToken: 'tok-A',
+    tokenExpiresAt: Date.now() + 3_600_000,
+    targetNodeId,
+  })
 }
 
-describe('ui-note view — handshake + real node render', () => {
-  it('completes the handshake, calls @<id>::get, and renders the Note', async () => {
-    const parent = installFakeParent({
-      windowId: 'win-1',
-      kernelUrl: KERNEL_URL,
-      functionId: 'ui-note',
-      delegationToken: 'tok-A',
-      tokenExpiresAt: Date.now() + 3_600_000,
-      targetNodeId: 'note-1',
+describe('monitor view (/ui/monitor)', () => {
+  it('loads the target node and renders name, url, status and latency', async () => {
+    const parent = handshake('mon-1')
+    const kernel = installFakeKernel((body) => {
+      if (body.method === '@mon-1::get') {
+        return ok(
+          monitorNode({
+            id: 'mon-1',
+            name: 'API health',
+            url: 'https://api.example.test/health',
+            status: 'up',
+            statusCode: '200',
+            latencyMs: '42',
+            lastCheckedAt: '2026-06-14T10:00:00Z',
+          }),
+        )
+      }
+      return { error: { code: 3002, message: `unexpected: ${body.method}` } }
     })
-    const kernel = installFakeKernel(() =>
-      ok(noteNode({ id: 'note-1', name: 'My first note', body: 'Hello from the kernel.' })),
-    )
 
     try {
       render(<App />)
@@ -60,113 +72,176 @@ describe('ui-note view — handshake + real node render', () => {
       // Parent observed the child's handshakeAck.
       await expect(parent.ack).resolves.toBeUndefined()
 
-      // The Note renders its title (Named.name) and body.
-      expect(screen.getByText('My first note')).toBeTruthy()
-      expect(screen.getByText('Hello from the kernel.')).toBeTruthy()
+      expect(screen.getByText('API health')).toBeTruthy()
+      // ExternalLink strips the scheme.
+      expect(screen.getByText('api.example.test/health')).toBeTruthy()
+      const badge = screen.getByText('UP')
+      expect(badge.className).toContain('status-up')
+      expect(screen.getByText('42ms')).toBeTruthy()
+      expect(screen.getByText('200')).toBeTruthy()
 
-      // Exactly one kernel call, with the verified wire shape.
+      // Exactly one kernel call, for the node load.
       expect(kernel.calls).toHaveLength(1)
-      expectGetCall(kernel.calls[0]!, 'note-1', 'tok-A')
+      expect(kernel.calls[0]!.body.method).toBe('@mon-1::get')
     } finally {
       kernel.restore()
       parent.restore()
     }
   })
 
-  it('renders the kernel error envelope on the error path', async () => {
-    const parent = installFakeParent({
-      windowId: 'win-2',
-      kernelUrl: KERNEL_URL,
-      functionId: 'ui-note',
-      delegationToken: 'tok-A',
-      tokenExpiresAt: Date.now() + 3_600_000,
-      targetNodeId: 'missing-1',
-    })
-    const kernel = installFakeKernel(() => ({
-      error: { code: 3002, message: 'Path not found' },
-    }))
+  it('renders a DOWN badge when the monitor status is down', async () => {
+    const parent = handshake('mon-d')
+    const kernel = installFakeKernel(() =>
+      ok(monitorNode({ id: 'mon-d', name: 'Down site', url: 'https://x.test', status: 'down' })),
+    )
 
     try {
       render(<App />)
       await flush()
 
-      expect(screen.getByText(/Failed to load the Note/)).toBeTruthy()
-      // The "<code>: <message>" surfaces from kernelCall.
-      expect(screen.getByText(/3002: Path not found/)).toBeTruthy()
-      expect(kernel.calls).toHaveLength(1)
+      const badge = screen.getByText('DOWN')
+      expect(badge).toBeTruthy()
+      expect(badge.className).toContain('status-down')
     } finally {
       kernel.restore()
       parent.restore()
     }
   })
 
-  it('re-fetches on a setTarget hot-swap', async () => {
-    const parent = installFakeParent({
-      windowId: 'win-3',
-      kernelUrl: KERNEL_URL,
-      functionId: 'ui-note',
-      delegationToken: 'tok-A',
-      tokenExpiresAt: Date.now() + 3_600_000,
-      targetNodeId: 'note-1',
+  it('clicks "Check now", issues @<id>::check, and reflects the refreshed status', async () => {
+    const parent = handshake('mon-1')
+    // First ::get is down; ::check mutates server-side; the post-check ::get is up.
+    let checked = false
+    const kernel = installFakeKernel((body) => {
+      if (body.method === '@mon-1::check') {
+        checked = true
+        return ok(null)
+      }
+      // @mon-1::get — reflect the pre/post-check status.
+      return ok(
+        monitorNode({
+          id: 'mon-1',
+          name: 'API health',
+          url: 'https://api.example.test/health',
+          status: checked ? 'up' : 'down',
+          statusCode: checked ? '200' : '503',
+        }),
+      )
     })
-    const kernel = installFakeKernel((body) =>
-      // Respond per-target so the swap is observable.
-      body.method === '@note-2::get'
-        ? ok(noteNode({ id: 'note-2', name: 'Second note', body: 'Swapped in.' }))
-        : ok(noteNode({ id: 'note-1', name: 'First note', body: 'Original.' })),
-    )
 
     try {
       render(<App />)
       await flush()
-      expect(screen.getByText('First note')).toBeTruthy()
+
+      // Initial load: DOWN.
+      expect(screen.getByText('DOWN')).toBeTruthy()
       expect(kernel.calls).toHaveLength(1)
+      expect(kernel.calls[0]!.body.method).toBe('@mon-1::get')
 
-      // Parent pushes a new target node.
-      parent.setTarget('note-2')
+      // Click "Check now".
+      await act(async () => {
+        fireEvent.click(screen.getByText('Check now'))
+      })
       await flush()
 
-      expect(screen.getByText('Second note')).toBeTruthy()
-      expect(screen.getByText('Swapped in.')).toBeTruthy()
+      // A ::check call was issued, then the node was re-fetched.
+      expect(kernel.calls.map((c) => c.body.method)).toEqual([
+        '@mon-1::get',
+        '@mon-1::check',
+        '@mon-1::get',
+      ])
 
-      // A second kernel call for the new node.
-      expect(kernel.calls).toHaveLength(2)
-      expectGetCall(kernel.calls[1]!, 'note-2', 'tok-A')
+      // The refreshed status renders.
+      expect(screen.getByText('UP')).toBeTruthy()
+      expect(screen.getByText('200')).toBeTruthy()
     } finally {
       kernel.restore()
       parent.restore()
     }
   })
 
-  it('uses the refreshed token for calls after ctrl:tokenRefresh', async () => {
-    const parent = installFakeParent({
-      windowId: 'win-4',
-      kernelUrl: KERNEL_URL,
-      functionId: 'ui-note',
-      delegationToken: 'tok-A',
-      tokenExpiresAt: Date.now() + 1_000,
-      targetNodeId: 'note-1',
+  it('surfaces a check failure without losing the loaded record', async () => {
+    const parent = handshake('mon-1')
+    const kernel = installFakeKernel((body) => {
+      if (body.method === '@mon-1::check') {
+        return { error: { code: 2004, message: 'Permission denied' } }
+      }
+      return ok(monitorNode({ id: 'mon-1', name: 'API health', url: 'https://x.test', status: 'up' }))
     })
+
+    try {
+      render(<App />)
+      await flush()
+
+      await act(async () => {
+        fireEvent.click(screen.getByText('Check now'))
+      })
+      await flush()
+
+      // The proper client maps the error code to a typed error, so the operator
+      // sees the clean server message (no `<code>:` prefix).
+      expect(screen.getByText(/Check failed:/)).toBeTruthy()
+      expect(screen.getByText(/Permission denied/)).toBeTruthy()
+      // The record is still shown.
+      expect(screen.getByText('API health')).toBeTruthy()
+    } finally {
+      kernel.restore()
+      parent.restore()
+    }
+  })
+
+  it('renders the kernel error on the node-load error path', async () => {
+    const parent = handshake('missing-1')
+    const kernel = installFakeKernel(() => ({ error: { code: 3002, message: 'Path not found' } }))
+
+    try {
+      render(<App />)
+      await flush()
+
+      expect(screen.getByText(/Failed to load the Monitor/)).toBeTruthy()
+      // The proper client maps NOT_FOUND (3002) to a typed error → clean message.
+      expect(screen.getByText(/Path not found/)).toBeTruthy()
+    } finally {
+      kernel.restore()
+      parent.restore()
+    }
+  })
+
+  it('re-fetches on a setTarget hot-swap', async () => {
+    const parent = handshake('mon-1')
     const kernel = installFakeKernel((body) =>
-      ok(noteNode({ id: body.method.slice(1, -5), name: 'Note', body: 'b' })),
+      body.method === '@mon-2::get'
+        ? ok(monitorNode({ id: 'mon-2', name: 'Second monitor', url: 'https://b.test', status: 'down' }))
+        : ok(monitorNode({ id: 'mon-1', name: 'First monitor', url: 'https://a.test', status: 'up' })),
     )
 
     try {
       render(<App />)
       await flush()
-      expect(kernel.calls).toHaveLength(1)
-      // First call used the handshake token.
-      expect(kernel.calls[0]!.headers['authorization']).toBe('tok-A')
+      expect(screen.getByText('First monitor')).toBeTruthy()
+      expect(screen.getByText('UP')).toBeTruthy()
+
+      // Parent pushes a new target node.
+      parent.setTarget('mon-2')
+      await flush()
+
+      expect(screen.getByText('Second monitor')).toBeTruthy()
+      expect(screen.getByText('DOWN')).toBeTruthy()
+    } finally {
+      kernel.restore()
+      parent.restore()
+    }
+  })
 
-      // Parent pushes a fresh token, then triggers a new fetch via setTarget.
-      parent.tokenRefresh('tok-B', Date.now() + 3_600_000)
-      parent.setTarget('note-9')
+  it('explains a missing target instead of a blank screen', async () => {
+    const parent = handshake(undefined)
+    const kernel = installFakeKernel(() => ok(null))
+    try {
+      render(<App />)
       await flush()
 
-      // The post-refresh call carries the NEW token.
-      expect(kernel.calls).toHaveLength(2)
-      expect(kernel.calls[1]!.body.method).toBe('@note-9::get')
-      expect(kernel.calls[1]!.headers['authorization']).toBe('tok-B')
+      expect(screen.getByText(/No target Monitor/)).toBeTruthy()
+      expect(kernel.calls).toHaveLength(0)
     } finally {
       kernel.restore()
       parent.restore()
@@ -174,15 +249,29 @@ describe('ui-note view — handshake + real node render', () => {
   })
 
   it('falls back to a standalone preview with no parent', async () => {
-    // No fake parent installed → connectShell rejects fast because
-    // window.parent === window in this realm.
+    // No fake parent → the shell sees window.parent === window and stands alone.
     const kernel = installFakeKernel(() => ok(null))
     try {
       render(<App />)
       await flush()
 
       expect(screen.getByText(/No parent shell/)).toBeTruthy()
-      // Never hit the kernel in standalone mode.
+      expect(kernel.calls).toHaveLength(0)
+    } finally {
+      kernel.restore()
+    }
+  })
+})
+
+describe('router fallback', () => {
+  it('renders "No view registered" for an unregistered path', async () => {
+    mountAt('/ui/nope')
+    const kernel = installFakeKernel(() => ok(null))
+    try {
+      render(<App />)
+      await flush()
+
+      expect(screen.getByText(/No view registered for \/ui\/nope/)).toBeTruthy()
       expect(kernel.calls).toHaveLength(0)
     } finally {
       kernel.restore()