@ekanos/harness 0.1.0

package/README.md

@@ -0,0 +1,879 @@
+# @ekanos/harness
+
+The Ekanos integration dev harness: every surface of an integration rendered in
+real Fusion chrome — the actual dashboard grid, the actual `Widget.*` compound
+components, the actual design tokens — from fixtures, with no Supabase, no auth
+and no network.
+
+**New here? Start with the `@ekanos/sdk` README** — it is the authoring
+reference for everything you declare (widgets, tools, webhooks, schedules,
+OAuth, storage, egress). This document covers only the local dev harness that
+renders those surfaces.
+
+> **Not published yet.** `@ekanos/harness` and `@ekanos/cli` are not on npm, so
+> the commands below do not resolve today. `@ekanos/sdk`, `@ekanos/ui` and
+> `@ekanos/integration-schema` are (`0.1.2`), and everything in the SDK README
+> works without this package — `defineIntegration()` validates at import and
+> the testing helpers need only vitest. What you cannot do until this ships is
+> *see* your surfaces rendered. This document describes what will ship.
+
+You do not normally install this by hand. `ekanos dev` scaffolds a shell around
+it and adds it to your `package.json`.
+
+```bash
+pnpm --filter <your project> exec ekanos dev
+```
+
+- [Why it is a package](#why-it-is-a-package)
+- [The registry is injected, never imported](#the-registry-is-injected-never-imported)
+- [The registry — `harness.config.ts`](#the-registry--harnessconfigts)
+- [Fixtures](#fixtures)
+  - [`HttpFixture` — the request line](#httpfixture--the-request-line)
+  - [When there is no fixture for a request](#when-there-is-no-fixture-for-a-request)
+  - [`seeds` — the react-query fast path](#seeds--the-react-query-fast-path)
+- [Live mode — real requests to your own API](#live-mode--real-requests-to-your-own-api)
+  - [`FetchProvider` — the part you have to write yourself](#fetchprovider--the-part-you-have-to-write-yourself)
+- [Triggers — running webhooks, schedules and OAuth locally](#triggers--running-webhooks-schedules-and-oauth-locally)
+  - [`triggerMocks`](#triggermocks)
+- [What ends up in the browser bundle](#what-ends-up-in-the-browser-bundle)
+- [Exports](#exports)
+- [The shell contract](#the-shell-contract)
+
+The surfaces this renders — widgets, the tile, the activation form, and the
+webhook / schedule / OAuth declarations behind Triggers — are documented in the
+`@ekanos/sdk` README. This one covers the harness's own contract.
+
+## Why it is a package
+
+So that a harness bugfix reaches you as a version bump you pick up with
+`pnpm up`, with zero edits to any file you own. The harness is a dependency,
+not code you copied.
+
+| Path | Who owns it |
+|---|---|
+| `harness.config.ts` | **you** — the registry, and the only file you have to edit |
+| your integration source | **you** |
+| the generated `app/**`, `styles/globals.css`, `next.config.mjs` | the CLI; regenerated on upgrade |
+| `@ekanos/harness` | us |
+
+## The registry is injected, never imported
+
+A package inside `node_modules` cannot reach a file in your project, so nothing
+here imports your config. The shell passes your array down instead:
+
+```tsx
+// app/harness-shell.tsx — generated
+'use client';
+
+import { RootLayout } from '@ekanos/harness/app';
+
+import { harnessIntegrations } from '~/harness.config';
+
+export default function HarnessShell(props: { children: React.ReactNode }) {
+  return <RootLayout integrations={harnessIntegrations} {...props} />;
+}
+```
+
+`RootLayout` mounts a context provider; every route reads the registry back out
+of it and takes its own `[slug]` from `useParams()`. That is why the generated
+route files are one line each:
+
+```tsx
+export { WidgetsPage as default } from '@ekanos/harness/routes';
+```
+
+`RootLayout` is the client boundary of the whole harness, and has to be: a
+`HarnessIntegration` holds live React component references and MCP `run`
+functions, which cannot be serialized across a server/client edge.
+
+## The registry — `harness.config.ts`
+
+This is the only file you edit. It exports an array of `HarnessIntegration`,
+one entry per integration, and each entry lights up four tabbed surfaces at
+`/<slug>` — `widgets`, `tile`, `activation` and `triggers` — plus a
+single-widget page at `/<slug>/widgets/<widgetId>`, which the widget grid links
+into for isolating one widget.
+
+```ts
+import { defineHarnessConfig } from '@ekanos/harness/config';
+
+import { acmePayments } from './harness/acme-payments';
+
+export const harnessIntegrations = defineHarnessConfig([acmePayments]);
+```
+
+`defineHarnessConfig()` is an identity function. It exists for the inference —
+nothing else.
+
+### `HarnessIntegration`
+
+| Field | Required | What it does |
+|---|---|---|
+| `slug` | yes | URL segment, and the id you would ship as your product slug |
+| `name`, `description` | yes | Header chrome and the index page |
+| `widgets` | yes | `HarnessWidget[]` — may be empty |
+| `fixtures` | no | `Partial<Record<FixtureVariant, HttpFixture[]>>` — the recorded HTTP exchanges, per variant. **This is how data gets in** |
+| `tile` | no | `ComponentType<MarketplaceTileProps>` — the marketplace card |
+| `activationForm` | no | `ComponentType<ActivationFormProps>`, rendered with `inline` so it does not open a dialog |
+| `definition` | no | Your validated `defineIntegration()` output. Powers Triggers |
+| `triggerMocks` | no | Seeds for the Triggers surface's mock context |
+| `live` | no | Opt in to real third-party requests |
+
+### `HarnessWidget`
+
+| Field | Required | What it does |
+|---|---|---|
+| `id` | yes | Stable id; the URL segment on `/<slug>/widgets/<widgetId>` |
+| `title` | yes | Rendered in the widget header chrome |
+| `component` | yes | `ComponentType<IntegrationComponentProps>` |
+| `width` | no | `'half'` (default) or `'full'`. Runs of `half` balance across two columns |
+| `isCollapsible` | no | Renders the collapse button. Off unless set |
+| `isPinnable` | no | Reaches `WidgetContext`; nothing draws a pin — see below |
+| `aiFooterEnabled` | no | Renders the "Ask about this" AI footer bar. Off unless set |
+| `seeds` | no | `Partial<Record<FixtureVariant, FixtureSeed[]>>` — react-query cache seeds for this widget, per variant. The fast path, not the default; see [Fixtures](#fixtures) |
+
+All three chrome flags are opt-in and behave as the type reads: omit one and
+you get nothing. The harness applies the host's own default (`?? false`) in its
+copy of the host's grid, so what renders here is what renders in production.
+
+One of them, though, renders nothing even when you do set it:
+
+**`isPinnable` is plumbed end to end with no consumer.** It reaches
+`WidgetContext` as `meta.isPinnable`, the current value is `state.pinned`, and
+`actions.togglePinned()` works — but no shipped `Widget.*` component draws a
+pin control.
+
+**This is faithful, not a harness gap.** The real dashboard does not render a
+pin in widget chrome either; it drives pinning from its own loader and
+customize panel, outside the widget. So if you want a pin *inside* your widget,
+it is yours to build, in the harness and in production alike:
+
+```tsx
+const ctx = use(WidgetContext);
+{ctx?.meta.isPinnable && (
+  <button onClick={ctx.actions.togglePinned}>
+    {ctx.state.pinned ? 'Unpin' : 'Pin'}
+  </button>
+)}
+```
+
+### Derive the widget list — don't write it twice
+
+`HarnessWidget` repeats `id`, `component`, `isCollapsible`, `isPinnable` and
+`aiFooterEnabled` from `components.widgets[]` in your `defineIntegration()`
+output, renaming `name` to `title`. Writing both by hand is two declarations of
+the same thing with nothing detecting drift, so don't:
+
+```ts HarnessIntegration
+import { harnessWidgetsFromDefinition } from '@ekanos/harness/registry';
+
+widgets: harnessWidgetsFromDefinition(acmeDefinition, {
+  'acme-payments-summary': { width: 'full' },
+}),
+```
+
+The definition supplies id, title, component and the chrome flags. The
+overrides map supplies what is genuinely harness-only — `width`, and per-widget
+`seeds` if you use them — and is **keyed by widget id**, so `id` is not a field
+inside the override value. An override wins over the definition where both
+speak.
+
+Your HTTP fixtures are not in here. They sit on the integration
+(`HarnessIntegration.fixtures`), one level up, because a URL is not owned by
+one widget.
+
+Pass your definition straight in, generic and all — unlike the `definition:`
+field on the same entry, this does **not** need `asHarnessDefinition()` (the
+generic-erasing wrapper the Triggers section below explains). That
+asymmetry is real and easy to trip on: the field stores the definition in a
+heterogeneous array and so needs the generic erased, while the helper only
+reads it.
+
+Two properties worth knowing, both deliberate:
+
+- **An override key that matches no declared widget throws**, naming the key
+  and listing the ids that do exist. A typo'd id would otherwise produce a
+  widget rendering with none of its overrides and no complaint — the same
+  silent-drift class the helper exists to kill.
+- **A chrome flag your definition does not declare is omitted, not defaulted**,
+  so it still lands on the host's default rather than one the helper invented.
+
+**Call this unless you have a reason not to.** The manual form is fully
+supported and `widgets` is still an ordinary `HarnessWidget[]` — the helper
+just returns one, so you can spread it and add entries. That is the reason to
+reach for the manual form: a scratch widget or a variant you are trying out
+that is deliberately *not* in your definition yet. The harness is exactly where
+you should be able to try something before declaring it.
+
+```ts HarnessIntegration
+widgets: [
+  ...harnessWidgetsFromDefinition(acmeDefinition, { /* … */ }),
+  { id: 'scratch-experiment', title: 'Scratch', component: Experiment },
+],
+```
+
+**Why any of this is needed: the harness never reads
+`definition.components.widgets`.** It touches your definition in four places —
+the egress cross-check, twice in the Triggers surface, and once on the
+activation page for `capabilities`/`permissions`. Widgets are not among them,
+so on this surface the registry is the *only* declaration and the definition's
+widget flags are inert. The helper is how you make the definition the source
+anyway.
+
+One thing the helper does **not** unify, because the two are genuinely
+different: **widget sizing is two unrelated systems.**
+`components.widgets[].layouts` (`lg`/`md`/`sm` grid rectangles, in the
+definition) is what the real dashboard reads. `HarnessWidget.width`
+(`'half' | 'full'`, in the registry) is what the harness reads. Setting
+`layouts` changes nothing here and setting `width` changes nothing in
+production, so set both and expect neither to validate the other.
+
+Your widgets are rendered with `HARNESS_ACCOUNT_ID`, `HARNESS_SOURCE_ID` and
+`HARNESS_ACCOUNT_SLUG`, all exported from `@ekanos/harness/registry`. They are
+plausible UUIDs rather than sentinels like `'preview-mode'`, so a widget that
+validates the shape of its `accountId` is happy. Nothing reads them — there is
+no database.
+
+## Fixtures
+
+**In fixtures mode the harness answers every request from recorded HTTP
+exchanges and refuses the network.** It patches `globalThis.fetch` itself, so
+this holds however your widgets fetch — react-query, SWR, a bare `useEffect`, a
+promise started in render and read with `use()`. There is no data layer to opt
+into and nothing to wire.
+
+You declare those exchanges on the **integration**, keyed by variant:
+
+```ts
+import type { HarnessIntegration } from '@ekanos/harness/registry';
+
+import { TidepoolForecast, TidepoolNow, TidepoolNowEmpty } from './fixtures';
+import { ForecastWidget, NowWidget } from './widgets';
+
+const API = 'https://api.tidepool.example.com';
+
+export const tidepool: HarnessIntegration = {
+  slug: 'tidepool',
+  name: 'Tidepool',
+  description: 'Tide readings and forecast.',
+
+  fixtures: {
+    default: [
+      { request: `GET ${API}/v1/tides/current`, response: TidepoolNow },
+      { request: `GET ${API}/v1/tides/forecast`, response: TidepoolForecast },
+    ],
+    empty: [
+      { request: `GET ${API}/v1/tides/current`, response: TidepoolNowEmpty },
+      {
+        request: `GET ${API}/v1/tides/forecast`,
+        response: { station: '9414290', entries: [] },
+      },
+    ],
+    error: [
+      { request: `GET ${API}/v1/tides/current`, status: 503 },
+      { request: `GET ${API}/v1/tides/forecast`, status: 503 },
+    ],
+  },
+
+  widgets: [
+    { id: 'tidepool-now', title: 'Tide Now', component: NowWidget },
+    { id: 'tidepool-forecast', title: 'Tide Forecast', component: ForecastWidget },
+  ],
+};
+```
+
+**They sit on the integration, not the widget, because a URL is not owned by
+one.** The same `GET /v1/payouts` may answer one widget, a second widget, and a
+webhook handler on the Triggers surface — and it should be written once. The
+Triggers surface reads this same list, so `ctx.fetch` inside a webhook or
+schedule handler resolves against the fixtures your widgets already use.
+
+There are exactly three variants, switched from the dev toolbar:
+
+| Variant | For |
+|---|---|
+| `default` | the populated happy path — declare this one |
+| `empty` | the zero-rows state |
+| `error` | the failure state, as ordinary responses with a failure `status` |
+
+`empty` and `error` are optional, and an omitted variant is **not** a fallback
+to `default`: the list for that variant is empty, so every request is refused
+and each widget shows the refusal. That is deliberate — a variant that silently
+served the happy path would look like your empty state working.
+
+**Switching the variant only reaches a widget that re-fetches.** The harness
+tears down and rebuilds the whole subtree on a switch, so a widget fetching in
+an effect or through react-query asks again and gets the new recording. A widget
+that starts its promise during render and caches it at MODULE scope — the
+obvious way to stop `use()` re-firing on every render — does not: the module
+outlives the remount, so it keeps serving the first variant's answer while the
+toolbar says `error`. Measured on our own tidepool example, whose forecast
+widget is exactly that shape: three switches, one `forecast` request, happy-path
+data showing under every variant.
+
+**The fix is where the promise is created, not how.** Moving the cache into the
+component that calls `use()` — `const [p] = useState(() => fetch(…))` right above
+the `use(p)` — looks right and is worse: a render that suspends is discarded
+before it commits, so the state it created is thrown away and the initializer
+runs again on every retry. Measured on the same three switches, that turns one
+request into twenty-six, and the widget still displays correctly the whole time.
+
+Create the promise in the non-suspending **parent** and pass it across the
+Suspense boundary:
+
+```tsx
+function ForecastWidget() {
+  const [request] = useState(() => fetchForecast(FORECAST_URL));
+
+  return (
+    <Suspense fallback={<Loading />}>
+      <ForecastBody request={request} />
+    </Suspense>
+  );
+}
+```
+
+The parent commits, so its state survives; the child suspends and retries
+against the same promise. It still starts during render, so nothing about the
+archetype changes.
+
+This is a widget-side trap rather than a fixtures one — the recording was
+swapped correctly; nothing asked for it — but it looks exactly like a fixture
+that did not take, so it is worth recognising. Note what does NOT distinguish
+the three states: the rendered output. Stuck, storming and correct all look
+identical on screen, and only a request count tells them apart.
+
+### `HttpFixture` — the request line
+
+```ts-mirror HttpFixture
+interface HttpFixture {
+  request: string;                     // '<METHOD> <url-or-path>'
+  response?: unknown;                  // body; JSON unless already a string
+  status?: number;                     // default 200 with a body, 204 without
+  headers?: Record<string, string>;
+}
+```
+
+`request` is a method and a target separated by a space. The method is
+case-insensitive and must be one of `GET`, `HEAD`, `POST`, `PUT`, `PATCH`,
+`DELETE`, `OPTIONS`. The target is one of three forms:
+
+| Form | Example | Resolves against |
+|---|---|---|
+| Absolute URL | `GET https://api.acme.com/v1/payouts` | itself — always unambiguous |
+| Path only | `GET /v1/payouts` | your `defineIntegration({ egress })` origin |
+| Host route | `GET /api/integrations/acme/summary` | the harness's own origin |
+
+The path-only form exists so you do not maintain a second `baseUrl` beside your
+egress declaration, and it is allowed **only when your definition declares
+exactly one origin**. With none or with two, the harness cannot make a
+defensible guess, so `compileFixture` throws while the surface renders — naming
+your fixture and printing the absolute form to write instead. It never guesses
+and it never skips a fixture it cannot parse.
+
+`/api/…` is the exception to both rules: it is the host-route namespace. A
+first-party integration's widgets call `/api/integrations/<slug>/…` rather than
+the vendor directly, because that is where the credential lives. The harness
+serves no backend, so those would 404; a fixture is the only thing that can
+answer one, and it is answered like any other.
+
+Matching, in the order the rules apply:
+
+- **Method and origin must be equal.**
+- **Path segments must agree in count.** `:param` matches exactly one segment,
+  `*` matches the rest (including nothing). So `/v1/payouts` does *not* match
+  `/v1/payouts/42`, but `/v1/payouts/:id` and `/v1/payouts/*` both do.
+- **Query is a subset match, or ignored entirely.** If your request line has a
+  `?`, every param in it must be present on the real request with the same
+  value — so you can pin the two that matter and ignore the other nine. If it
+  has no `?`, query is not consulted at all. That is what makes
+  `GET https://api.acme.com/v1/payouts` answer a request carrying a page
+  cursor, a locale and an API key.
+- **First declaration wins.** Write the specific fixture above the general one.
+
+The response side has defaults chosen so the common cases are one line.
+`{ request: 'DELETE /v1/thing/:id' }` is a complete fixture: no body, so 204. A
+`response` that is a string is sent as-is with `text/plain`; anything else is
+JSON-serialized with `application/json`. `status` overrides the default, which
+is how an error variant is written — `{ request: 'GET /v1/payouts', status: 503 }`
+is an ordinary recorded response rather than a special code path.
+
+One constraint comes from the shell rather than from fixtures:
+`harness.config.ts` is imported from both a server component and a client
+component, so **everything reachable from it must be importable in both
+graphs.** A fixture module carrying a `'use client'` directive compiles and then
+fails at request time with `Attempted to call … from the server`. Keep fixture
+data and URL constants in a plain module with no directive; put hooks and
+components in the client ones.
+
+### When there is no fixture for a request
+
+The request is **refused, not sent** — that is the promise fixtures mode makes,
+and it is unconditional. Three things happen, and they are worth being able to
+recognise:
+
+1. **The console gets a line naming the URL**, from the harness rather than
+   from your code:
+
+   ```
+   [harness:tidepool] refused GET https://api.tidepool.example.com/v1/tides/current?…
+   ```
+
+   Every third-party call is logged this way — `fixture`, `network` (live mode
+   only) or `refused` — so the console is the fastest place to see what a
+   widget actually asked for versus what you recorded.
+
+2. **The `fetch` call rejects with `NoRecordedResponseError`**, whose message
+   quotes the fixture to paste:
+
+   ```
+   No recorded response for GET https://api.tidepool.example.com/v1/tides/current?….
+
+   Fixtures mode answers every request from your registry entry and
+   never leaves the machine, so this call was refused rather than sent.
+   Record it:
+
+     fixtures: {
+       default: [{ request: 'GET https://api.tidepool.example.com/v1/tides/current', response: /* … */ }],
+     }
+
+   To exercise the failure branch instead, give it a status:
+
+     { request: 'GET https://api.tidepool.example.com/v1/tides/current', status: 403 }
+
+   The query string is hidden above because it can carry
+   credentials. It is left off the line to paste on purpose: a
+   request with no `?` matches whatever query the widget sends.
+   Add `?key=value` only to pin params you want matched.
+
+   If this URL looks unfamiliar, log it from the code that builds it —
+   the path and any pinned query params must match exactly.
+   ```
+
+3. **Where you see it depends on your own error handling**, because it is an
+   ordinary rejected `fetch`. A react-query widget lands in its error state
+   (the harness sets `retry: false`, so immediately rather than after three
+   backoffs). A widget that starts a promise in render and reads it with
+   `use()` throws, and if it does not catch it itself the harness's per-widget
+   error boundary renders the whole message in the card — one broken widget,
+   not a broken page.
+
+**Credentials are redacted from what is printed.** Any userinfo in the URL is
+stripped and the entire query string is replaced with `?…`, in the console line
+and in the error alike, because an API key in a query param is exactly the thing
+that ends up in a screenshot. The quoted `request:` line therefore has no query
+on it — which is correct as written, since a fixture with no `?` matches
+whatever query your widget sends. Add `?key=value` back only to pin a param you
+want matched.
+
+When the refused request was a **host route**, the quoted line is the path form
+(`GET /api/integrations/acme/summary`) even though the URL above it is absolute.
+That is deliberate, not an inconsistency: `/api/…` resolves against whatever port
+this harness happens to run on, and quoting that back would pin your fixture to
+a port that is ours and not yours. Paste it as printed.
+
+**A URL you do not recognise is usually the real answer.** Log it from the code
+that builds it rather than guessing: the path and any pinned query params have
+to match exactly, and a trailing slash or an extra segment is enough to miss.
+
+One thing is deliberately **not** intercepted: same-origin traffic outside
+`/api/`. That is `/_next/static`, the document itself and the `?_rsc=` payloads
+client navigation fetches — the framework's own plumbing, none of it your
+integration talking to an API.
+
+**The server render is a partial pass, not an exempt one.** It matters because a
+widget that starts its fetch during render and reads it with `use()` runs there
+too. Every fixture is compiled for that pass **except the `/api/` host-route
+shape**, which is the only one that resolves against the harness's own origin —
+and a server render has none. Absolute and path-only fixtures need no origin, so
+they answer on the server exactly as they do in the browser.
+
+A host-route request during a server render is therefore refused, with a message
+that says so and tells you there is nothing to change in your registry entry —
+the client render compiles that fixture and answers it, so what you see after
+hydration is the real result. If you need it answered on the server too, write
+the fixture and the widget's URL both absolute, at the cost of hardcoding the
+dev server's origin.
+
+Same-origin traffic **outside** `/api/` gets a third message, and it is the one
+worth reading carefully: there is no fixture to write for it. The client passes
+that traffic straight through as framework plumbing, so it is never refused in
+the browser — only the server pass has nowhere to send it. If the request was
+meant to reach a vendor, give it an absolute URL and it becomes an ordinary
+fixture in both passes.
+
+### `seeds` — the react-query fast path
+
+`HarnessWidget.seeds` writes straight into the react-query cache, so a widget
+paints populated with **no request at all**:
+
+```ts HarnessIntegration
+widgets: [
+  {
+    id: 'acme-payments-summary',
+    title: 'Payments Summary',
+    component: AcmeSummaryWidget,
+    seeds: {
+      default: [{ queryKey: summaryKey, data: acmeSummaryFixture }],
+      empty: [{ queryKey: summaryKey, data: acmeSummaryEmptyFixture }],
+      error: [{ queryKey: summaryKey, error: new Error('Acme returned 503') }],
+    },
+  },
+],
+```
+
+A `FixtureSeed` is `{ queryKey, data }` or `{ queryKey, error }`. Set both and
+`error` wins.
+
+**This is the fastest seam and the narrowest.** It only works if your data layer
+is `@tanstack/react-query`, and it addresses data by query key rather than by
+what your vendor returns — so the same payload has to be written again, in a
+different shape, for anything that is not a widget. Reach for it when you want a
+specific widget to skip the request entirely; otherwise record the exchange.
+
+Two rules if you do use it:
+
+- **Derive the key from the same factory your hook calls.** Retyping a key array
+  gives you a widget that silently renders empty when someone renames a key;
+  importing the factory makes it a compile error.
+- **A seeded key never fetches, so an HTTP fixture behind it is unreachable.**
+  Seeding short-circuits the request. Use one or the other for a given key, not
+  both.
+
+There is one error a widget can hit that no HTTP fixture can answer:
+`MissingFixtureError`, thrown when a query has neither a seed nor a `queryFn` of
+its own. Nothing makes a request in that case, so there is nothing to record —
+seed the key.
+
+Finally, `HarnessWidget.seeds` was called `fixtures` before HTTP fixtures
+existed. It was renamed rather than overloaded: two fields called `fixtures` one
+level apart, meaning different things, is a trap worth spending a rename to
+avoid.
+
+### Why the format is HTTP and not query keys
+
+Both of the problems it fixes are ones you would otherwise hit on your first
+integration:
+
+- **You authored the same vendor data twice, in two shapes, with nothing
+  relating them.** A seed takes `data` in the shape your hook *returns* —
+  domain-shaped, post-parse. A `triggerMocks.fetchHandlers` entry returns a
+  `Response`, so it is wire-shaped. The shipped Acme example used to carry both:
+  one export feeding the handler's JSON envelope, separate exports feeding the
+  widget seeds. Change one and the other went stale silently, and then the
+  widget and the webhook handler disagreed about the same account.
+- **Only react-query users could express a fixture at all.** `queryKey` was the
+  only way to address one, so a partner fetching with SWR, in a server component
+  with plain `fetch`, or from a `useEffect` had an inert fixtures surface — the
+  harness mocking a cache they did not have rather than the network they did.
+  That was also the population whose requests reached the real internet, because
+  the interception was mounted on the same seams the fixtures were.
+
+Recording the HTTP boundary fixes both at once: one declaration in one shape,
+serving the widget and the handlers alike, with no opinion about how your
+components fetch. `@tanstack/react-query` is still a hard peer of `@ekanos/sdk`
+— `useActivateIntegration` and `useOAuthConnectionStatus` are built on it, and
+the harness mounts `QueryClientProvider` unconditionally so the activation
+surface works — so you install it either way. You just no longer have to build
+on it to write a fixture.
+
+## Live mode — real requests to your own API
+
+The harness mocks Fusion, not your vendor. Declare a `live` block and the
+toolbar grows a fixtures ⇄ live switch: in live mode the harness stops seeding
+your data keys, your widgets' own query functions run, and their requests reach
+the real API. Fusion stays mocked either way — still no Supabase, no auth, no
+server actions.
+
+```ts HarnessIntegration
+live: {
+  // No `egress` here: the harness reads it off `definition`.
+  FetchProvider: AcmeFetchProvider,
+  seeds: [{ queryKey: settingsKey, data: acmeSettingsFixture }],
+},
+```
+
+**The guarantee: live mode enforces the egress your definition declares — not
+a second list you maintain beside it.** A request to an origin your definition
+did not declare throws `EgressDeniedError` on your laptop, carrying the message
+a reviewer would have seen at promotion. Flipping the toolbar to live is
+therefore a real test of the declaration under review, not of a convenience
+copy that happens to sit next to it.
+
+**So when you set `definition`, do not set `live.egress`.** Supplying both is a
+hard error naming your slug, not a silent preference — a silent preference is
+exactly how the two lists became able to disagree. The harness resolves the
+allowlist from `definition.egress` centrally (`resolveEgress`), so there is only
+one list and it is the one a reviewer reads.
+
+`live.egress` survives for the one case with nothing to read: an entry with no
+`definition` linked. There it is the only source, and `findEgressMismatch` —
+which reports a `live.egress` wider than the definition's — is what still has
+work to do. A definition declaring more than live mode exercises is fine; the
+reverse is the fault, and while it stands the harness forces fixtures mode and
+says so on the surface.
+
+**`seeds` are the keys that stay mocked in live mode.** Fusion-side state your
+widgets read before they can call anything: a saved location, an account
+preference, whatever your own host route would have returned. Everything not
+listed runs its real query function. That one line is the whole boundary the
+design draws: Fusion mocked, vendor real.
+
+An integration with no `live` block is fixtures-only; the toolbar control is
+disabled for it and says why.
+
+### `FetchProvider` — the part you have to write yourself
+
+> **Optional.** The harness patches `globalThis.fetch`, so it reaches your
+> requests whether or not you supply this — and if you do supply one, your
+> fetch still gets wrapped, because the patch sits underneath it. It is not an
+> escape hatch in either direction.
+>
+> Write it anyway if the shape fits your code: it is how you keep one path
+> serving `ctx.fetch` on the server and a browser fetch on the client, which
+> is useful well outside the harness.
+
+
+This is the awkward bit, and there is no way around it today. `ctx.fetch` — the
+egress-allowlisted fetch — is handed to server-side handlers only. **The SDK
+has no client-side equivalent.** So a widget that talks to a vendor API straight
+from the browser has nowhere to get one, and needs a seam of its own before
+live mode can hand it an allowlisted fetch.
+
+The seam is a React context whose default is the browser's own `fetch`, so
+nothing changes for a consumer that never mounts the provider. It is about
+twenty lines, and this is all of them:
+
+```tsx
+'use client';
+
+import { type ReactNode, createContext, use } from 'react';
+
+import type { IntegrationFetch } from '@ekanos/sdk';
+
+const browserFetch: IntegrationFetch = (input, init) =>
+  globalThis.fetch(input as RequestInfo, init);
+
+const AcmeFetchContext = createContext<IntegrationFetch>(browserFetch);
+
+export function AcmeFetchProvider({
+  fetch,
+  children,
+}: {
+  fetch: IntegrationFetch;
+  children: ReactNode;
+}) {
+  return <AcmeFetchContext value={fetch}>{children}</AcmeFetchContext>;
+}
+
+/** The fetch this integration's query functions should use. */
+export function useAcmeFetch(): IntegrationFetch {
+  return use(AcmeFetchContext);
+}
+```
+
+Then have your query functions **take an `IntegrationFetch` as an argument**
+rather than reaching for a global:
+
+```ts
+import type { IntegrationFetch } from '@ekanos/sdk';
+
+export async function fetchAcmeSummary(fetch: IntegrationFetch, accountId: string) {
+  const response = await fetch(`https://api.acme.example/v1/summary?a=${accountId}`);
+  if (!response.ok) throw new Error(`Acme returned ${response.status}.`);
+  return response.json();
+}
+
+// in the hook
+const fetch = useAcmeFetch();
+useQuery({ queryKey: acmeKeys.summary(accountId), queryFn: () => fetchAcmeSummary(fetch, accountId) });
+```
+
+That is the value of the pattern, beyond the harness: the *same* code path
+serves `ctx.fetch` on the server and an allowlisted browser fetch on the
+client.
+
+The provider's props are fixed by the type — `{ fetch: IntegrationFetch;
+children: ReactNode }` — because the harness mounts it. Omit `FetchProvider`
+entirely if your widgets fetch only through your own host routes: fixtures mode
+answers those (record them under `/api/…`), but live mode cannot run them —
+there is no Supabase and no `ctx` to execute a route with — so live mode has
+nothing to offer you yet.
+
+This should be SDK surface, not partner surface. It is on the list.
+
+## Triggers — running webhooks, schedules and OAuth locally
+
+Set `definition` on the registry entry and the Triggers surface reads your
+declared webhooks, schedules and OAuth straight off it. Omit it and the surface
+explains what to add.
+
+```ts HarnessIntegration
+import { asHarnessDefinition } from '@ekanos/harness/registry';
+
+import { integration as acmeDefinition } from '@you/acme-payments/integration';
+
+definition: asHarnessDefinition(acmeDefinition),
+```
+
+`asHarnessDefinition()` erases the storage generic so the definition can sit in
+the heterogeneous registry array — the same erasure the host performs when it
+registers you. Nothing rests on the generic surviving: the mock context is built
+FROM the definition's own `storage` schemas and validates every read and write
+against them at runtime.
+
+What the surface then does:
+
+- **Webhooks** get a payload editor, seeded from `examplePayload`. Delivering
+  runs your REAL handler. The payload is validated against `payloadSchema`
+  first; an invalid one never reaches the handler. Signature verification is
+  logged as skipped — it is the transport's job in every environment.
+- **Schedules** get a "Run now" button, which invokes the handler with
+  `trigger: 'manual'`.
+- **OAuth** gets a read-only declaration readout plus an egress-coverage check
+  on both endpoint origins. There is no local authorize→callback loop yet; unit
+  test `onTokens` directly with `createMockContext()` until there is.
+
+Every invocation runs against **one** `createMockContext()` per visit, so state
+accumulates across invocations the way it would in a real account. Leaving the
+page resets it.
+
+### `triggerMocks`
+
+The mock context is derived from the definition — slug, storage schemas, egress
+— and from your `fixtures`, which answer `ctx.fetch` here exactly as they answer
+a widget. `triggerMocks` supplies the rest: whatever Fusion-side state your
+handlers need to run a happy path.
+
+**So do not re-author your vendor payloads as `fetchHandlers`.** That was the
+double-authoring HTTP fixtures exist to kill — the same data in a domain shape
+for widgets and a wire shape for handlers, with nothing relating them. Reach for
+`fetchHandlers` only when a response has to be dynamic or stateful; an explicit
+handler is tried first and wins for the URLs it matches, so you keep fixtures
+for everything else.
+
+One behaviour worth knowing: a handler calling an endpoint nothing answers gets
+the same named `NoRecordedResponseError` a widget gets. `createMockContext()`'s
+own fallback is a plausible empty `200` — the trigger-side twin of a silent
+fixture miss — and the harness replaces it.
+
+```ts HarnessIntegration
+triggerMocks: {
+  // Storage rows per scope, validated against your declared schemas.
+  storage: {
+    account: { config: { merchantId: 'mrc_4820193', environment: 'sandbox' } },
+    user: {},
+  },
+  // Secrets by tier. `account` is writable via ctx.secrets.set(); `admin`
+  // stands in for admin-issued credentials and rejects writes.
+  secrets: {
+    account: { acme_api_key: 'acme_test_9f2c41ab' },
+  },
+  // ONLY for a response that has to be dynamic or stateful — your `fixtures`
+  // already answer ctx.fetch. A string `match` matches URLs that start with
+  // it; a RegExp is tested against the full URL. Tried before the fixtures.
+  fetchHandlers: [
+    {
+      match: 'https://api.acme.example',
+      respond: () => Response.json({ payments: [], totalCount: 0 }),
+    },
+  ],
+},
+```
+
+There is no Supabase and no network in here either way. Keep the values fake —
+see the bundle note below.
+
+## What ends up in the browser bundle
+
+**Everything in your registry does, including `triggerMocks.secrets`.**
+
+The shell's injection module is a client module — it has to be, because the
+registry holds live React component references — so the whole of
+`harness.config.ts` is compiled into the browser bundle and written into the
+`.next` build output on disk. There is no boundary that can prevent this while
+the registry still reaches the routes, so the harness warns at startup rather
+than pretending otherwise:
+
+```
+[harness] acme-widgets seed triggerMocks.secrets, and those literals are
+compiled into the browser bundle and written into the .next build output …
+```
+
+In practice this is your own mock values on your own machine, which is why it
+is a warning and not a refusal. Two things follow from it:
+
+- **Keep trigger mocks fake.** They are seeds for a local mock context, not
+  credentials — nothing in the harness ever authenticates.
+- **Do not commit or deploy the generated build directory.** `.ekanos/` is
+  gitignored for you; the `.next` output inside it is a build artifact.
+
+Related, and deliberate: the activation surface hides credential-shaped fields
+in its payload readout behind a **Reveal values** toggle, and the fixture
+activation actions log a redacted copy. That readout is the one place a real
+API token predictably appears on screen.
+
+## Exports
+
+| Subpath | Contents |
+|---|---|
+| `@ekanos/harness/registry` | `HarnessIntegration`, `HarnessWidget`, `HttpFixture`, `FixtureSeed`, `FixtureVariant`, `HarnessLiveMode`, `HarnessTriggerMocks`, the `HARNESS_*` ids and the pure helpers. Server-safe; this is the type surface you author against. |
+| `@ekanos/harness/config` | `defineHarnessConfig()` — an identity function that exists for the inference. |
+| `@ekanos/harness/app` | `RootLayout`, `IndexPage`, `harnessMetadata`. |
+| `@ekanos/harness/routes` | `IntegrationLayout`, `WidgetsPage`, `SingleWidgetPage`, `TilePage`, `ActivationPage`, `TriggersPage`. |
+| `@ekanos/harness/styles.css` | The harness's Tailwind layer: the Tailwind entry, the `@ekanos/ui` token preset, the Font Awesome repairs, and the `@source` globs covering everything the chrome renders. |
+| `@ekanos/harness/mocks/team-account-workspace` | The stand-in for the host's `useTeamAccountWorkspace()`. The generated `next.config.mjs` aliases `@kit/team-accounts/hooks/use-team-account-workspace` onto it, so unmodified widget source runs unchanged. |
+
+## The shell contract
+
+`package.json` declares `ekanos.shellContract`. `@ekanos/cli` reads it before
+scaffolding and refuses if its templates generate a different one, naming which
+side to upgrade.
+
+Bump it when the SHELL this package requires changes — an export renamed or
+moved between `/app` and `/routes`, the props of `RootLayout` or `IndexPage`,
+the server/client split, the alias specifier, the stylesheet's ownership of the
+Tailwind import, or the set of files the shell must contain. A release that only
+fixes a bug inside the package leaves it alone.
+
+**A shell change also needs a `@ekanos/cli` release.** The templates live there;
+only the code they import lives here. `ekanos dev` rewrites a generated file
+only when its bytes change, so bumping the harness alone regenerates nothing —
+the old CLI's templates are exactly what the old CLI intends. The contract
+integer is what turns that silent mismatch into a refusal.
+
+**What it does NOT cover is your `harness.config.ts`.** The contract is checked
+before the CLI writes the generated shell, so it guards `.ekanos/harness/**` —
+our files. Yours is bootstrapped once and never touched again, deliberately,
+because your fixtures live in it. So if we rename something in the registry
+types you write against, it reaches you as a TypeScript error in a file no tool
+will migrate for you. That is the right trade — we are not editing your file —
+but it means **the release notes are the migration path**, and you should read
+them on a minor bump rather than only on a major. The `HarnessWidget.fixtures`
+→ `seeds` rename — made when `HarnessIntegration.fixtures` took the name — is
+exactly this shape.
+
+## Building it
+
+```bash
+pnpm --filter @ekanos/harness build
+```
+
+`@ekanos/ui` must be built first — `styles.css` imports its token preset.
+
+The build compiles **per file** rather than bundling (`bundle: false` in
+`tsup.config.ts`), and that is load-bearing in three separate ways: the
+server/client boundary runs *through* the `/app` entry rather than around it,
+`next/font/google` requires its call to survive as a `const` (esbuild's bundler
+rewrites top-level `const` to `var`, which Next rejects outright), and there is
+nothing to inline in the first place. Each of those is a bug we have already
+shipped once; the build config in the source tree carries the long version.
+
+`pnpm --filter @ekanos/harness pack:test` re-checks all of that on the actual
+published tarball, in a clean room outside the workspace.
+
+## Licence
+
+MIT. Font Awesome is the consuming app's responsibility: this package ships no
+icon-font data, and the generated shell loads Font Awesome **Free**, because
+Fusion's own Pro webfonts are commercially licensed and cannot be redistributed.