@ekanos/harness 0.1.2 → 0.1.3

package/README.md

@@ -419,9 +419,13 @@ recognise:
    [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.
+   Every third-party call is logged this way — `fixture`, `network` (a vendor
+   request in live mode) or `refused` — so the console is the fastest place to
+   see what a widget actually asked for versus what you recorded. A same-origin
+   `/api/…` request logs `fixture` or `refused` in EITHER toolbar mode: it is
+   answered from your registry entry whether the switch says Fixtures or Live
+   API, because the harness serves no backend either way. Only genuinely
+   third-party traffic can log `network`, and only in live mode.
 
 2. **The `fetch` call rejects with `NoRecordedResponseError`**, whose message
    quotes the fixture to paste:
@@ -622,6 +626,81 @@ 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.
 
+### Knowing the mode, and the activation-data channel
+
+Two things a live-mode widget routinely needs and could not get before:
+**which mode is actually running**, and **a credential to authenticate with**.
+
+`FetchProvider` — where you already have one — receives both as props, no
+extra plumbing required:
+
+```tsx
+import type { ReactNode } from 'react';
+
+import type { IntegrationFetch } from '@ekanos/sdk';
+import type { DataMode } from '@ekanos/harness/registry';
+
+export function AcmeFetchProvider({
+  fetch,
+  mode,
+  activationData,
+  children,
+}: {
+  fetch: IntegrationFetch;
+  mode: DataMode;
+  activationData: unknown;
+  children: ReactNode;
+}) {
+  return <AcmeFetchContext value={fetch}>{children}</AcmeFetchContext>;
+}
+```
+
+`mode` is `'fixtures' | 'live'` — the EFFECTIVE mode, already accounting for an
+integration with no `live` block or a `live.egress`/definition mismatch (both
+force `'fixtures'`, whatever the toolbar says). `activationData` is whatever
+was last submitted to this integration's activation form — `null` before any
+submission or after Disconnect — held **in memory only**: never written to
+`localStorage`, a fixture, or the registry, and cleared on reload and on
+disconnect. It is a dev-only convenience standing in for `ctx.secrets`, which
+is what production actually hands your server-side handlers.
+
+Threading a submitted API token into a live request looks like this:
+
+```tsx
+import type { ReactNode } from 'react';
+
+import type { IntegrationFetch } from '@ekanos/sdk';
+import type { DataMode } from '@ekanos/harness/registry';
+
+export function AcmeFetchProvider({ fetch, activationData, children }: {
+  fetch: IntegrationFetch;
+  mode: DataMode;
+  activationData: unknown;
+  children: ReactNode;
+}) {
+  const token = (activationData as { apiToken?: string } | null)?.apiToken;
+
+  const authedFetch: IntegrationFetch = (input, init) =>
+    fetch(input, {
+      ...init,
+      headers: {
+        ...(init?.headers as Record<string, string> | undefined),
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+    });
+
+  return <AcmeFetchContext value={authedFetch}>{children}</AcmeFetchContext>;
+}
+```
+
+No `FetchProvider` mounted, or need the answer somewhere else entirely? Two
+hooks answer the same two questions from `@ekanos/harness/hooks`:
+`useHarnessDataMode()` and `useLiveActivationData()`. Prefer the props above
+wherever you can — they need no import from this package, and behave
+identically whether or not `@ekanos/harness` is even installed at the call
+site. Reach for the hooks only from code that runs nowhere but inside the dev
+harness.
+
 ### `FetchProvider` — the part you have to write yourself
 
 > **Optional.** The harness patches `globalThis.fetch`, so it reaches your
@@ -693,12 +772,14 @@ 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.
+The provider's props are fixed by the type — `{ fetch: IntegrationFetch; mode:
+DataMode; activationData: unknown; children: ReactNode }` — because the harness
+mounts it (see the previous section for what `mode` and `activationData` are
+for). Omit `FetchProvider` entirely if your widgets fetch only through your own
+host routes: those are answered from fixtures (record them under `/api/…`) in
+EVERY toolbar mode, live included — there is no Supabase and no `ctx` to
+execute a route with, so there is nothing "live" to run for that traffic
+either way.
 
 This should be SDK surface, not partner surface. It is on the list.
 
@@ -827,6 +908,7 @@ API token predictably appears on screen.
 | `@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/hooks` | `useHarnessDataMode()`, `useLiveActivationData()` — see "Knowing the mode, and the activation-data channel" above. Prefer `FetchProvider`'s own `mode`/`activationData` props where you can; reach for these only from code that runs nowhere but inside the dev harness. |
 | `@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. |
 

package/dist/hooks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public hooks for widget code that only ever runs inside the harness.
+ *
+ * Most partner code should not need this entry at all: `HarnessLiveMode`'s
+ * `FetchProvider` (see `registry.ts`) already receives `mode` and
+ * `activationData` as props, which needs no import from this package and
+ * behaves the same whether or not `@ekanos/harness` is even installed at the
+ * call site. Reach for these two hooks only from code that is genuinely
+ * harness-only — a debug banner, a dev-mode-only branch — never from a
+ * widget's shipped data-fetching path.
+ */
+export { useHarnessDataMode, useLiveActivationData, } from './internal/lib/harness-hooks.js';

package/dist/hooks.js

@@ -0,0 +1,9 @@
+"use client";
+import {
+  useHarnessDataMode,
+  useLiveActivationData
+} from "./internal/lib/harness-hooks.js";
+export {
+  useHarnessDataMode,
+  useLiveActivationData
+};

package/dist/internal/components/dev-toolbar.js

@@ -21,6 +21,7 @@ import {
   resolveEgress,
   supportsLiveMode
 } from "../../registry.js";
+import { getThemeToggleAccessibleLabel } from "../lib/theme-toggle.js";
 import {
   RENDER_STATES,
   VIEWPORTS,
@@ -133,16 +134,30 @@ function DevToolbar() {
           size: "sm",
           variant: "outline",
           onClick: () => setTheme(resolvedTheme === "dark" ? "light" : "dark"),
-          "aria-label": "Toggle theme",
+          "aria-label": getThemeToggleAccessibleLabel(resolvedTheme),
           children: [
-            /* @__PURE__ */ jsxs("span", { className: cn("flex items-center dark:hidden"), children: [
-              /* @__PURE__ */ jsx(Icon, { name: "fa-solid fa-moon", className: "mr-2 h-4 w-4" }),
-              "Dark"
-            ] }),
-            /* @__PURE__ */ jsxs("span", { className: cn("hidden items-center dark:flex"), children: [
-              /* @__PURE__ */ jsx(Icon, { name: "fa-solid fa-sun-bright", className: "mr-2 h-4 w-4" }),
-              "Light"
-            ] })
+            /* @__PURE__ */ jsxs(
+              "span",
+              {
+                "aria-hidden": "true",
+                className: cn("flex items-center dark:hidden"),
+                children: [
+                  /* @__PURE__ */ jsx(Icon, { name: "fa-solid fa-moon", className: "mr-2 h-4 w-4" }),
+                  "Dark"
+                ]
+              }
+            ),
+            /* @__PURE__ */ jsxs(
+              "span",
+              {
+                "aria-hidden": "true",
+                className: cn("hidden items-center dark:flex"),
+                children: [
+                  /* @__PURE__ */ jsx(Icon, { name: "fa-solid fa-sun-bright", className: "mr-2 h-4 w-4" }),
+                  "Light"
+                ]
+              }
+            )
           ]
         }
       ),

package/dist/internal/components/harness-providers.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { Suspense, useMemo } from "react";
+import { Suspense, useMemo, useSyncExternalStore } from "react";
 import {
   IntegrationActivationProvider
 } from "@ekanos/sdk/hooks";
@@ -18,6 +18,13 @@ import {
   logHarnessFetch
 } from "../lib/harness-live-fetch.js";
 import { createHarnessQueryClient } from "../lib/harness-query-client.js";
+import {
+  clearLiveActivationData,
+  getLiveActivationServerSnapshot,
+  getLiveActivationSnapshot,
+  setLiveActivationData,
+  subscribeLiveActivationData
+} from "../lib/live-activation-store.js";
 import { redactSensitive } from "../lib/redact.js";
 import { AskAssistantBridge } from "./ask-assistant-bridge.js";
 installHarnessFetch();
@@ -27,6 +34,7 @@ const fixtureActivationActions = {
       "[harness] activate (fixture, not persisted):",
       redactSensitive(input)
     );
+    setLiveActivationData(input.integrationSlug, input.activationData ?? null);
     return { success: true };
   },
   deactivate: async (input) => {
@@ -34,6 +42,7 @@ const fixtureActivationActions = {
       "[harness] deactivate (fixture, not persisted):",
       redactSensitive(input)
     );
+    clearLiveActivationData(input.integrationSlug);
     return { success: true };
   }
 };
@@ -56,6 +65,11 @@ function HarnessProviders({
     }
     return createFixturesFetch();
   }, [mode, egress, slug]);
+  const activationData = useSyncExternalStore(
+    subscribeLiveActivationData,
+    () => getLiveActivationSnapshot(slug),
+    getLiveActivationServerSnapshot
+  );
   useMemo(() => {
     installHarnessFetch();
     publishHarnessRouting({
@@ -76,7 +90,15 @@ function HarnessProviders({
     /* @__PURE__ */ jsx(AskAssistantBridge, {}),
     /* @__PURE__ */ jsx(Suspense, { fallback: null, children })
   ] }) }) }) }) });
-  return FetchProvider ? /* @__PURE__ */ jsx(FetchProvider, { fetch: harnessFetch, children: tree }) : tree;
+  return FetchProvider ? /* @__PURE__ */ jsx(
+    FetchProvider,
+    {
+      fetch: harnessFetch,
+      mode,
+      activationData,
+      children: tree
+    }
+  ) : tree;
 }
 export {
   HarnessProviders

package/dist/internal/lib/harness-fetch-interceptor.d.ts

@@ -25,19 +25,34 @@ import { type CompiledFixture, NoRecordedResponseError } from './http-fixtures.j
  *
  * ── What is deliberately NOT intercepted ─────────────────────────────────────
  *
- * Same-origin traffic passes through untouched — with ONE exception.
+ * Same-origin traffic outside `/api/` passes through untouched — in EVERY
+ * mode, live included.
  *
- * Measured against a running harness, same-origin traffic is `/_next/static`,
- * the document, and the `?_rsc=` payloads client navigation fetches: the
+ * Measured against a running harness, that traffic is `/_next/static`, the
+ * document, and the `?_rsc=` payloads client navigation fetches: the
  * framework's own plumbing, none of it the integration talking to an API.
  * Intercepting it would break the app to no purpose.
  *
- * `/api/` is the exception, because it is the integration's own namespace. A
- * first-party integration's widgets call `/api/integrations/<slug>/…` rather
- * than the vendor directly — the vendor call happens server-side, where the
- * credential lives — and our own Acme example is shaped exactly that way. The
- * harness serves no backend, so passing those through guarantees a 404; the
- * useful answer is a fixture, or a refusal that names the URL.
+ * ── `/api/` is answered from fixtures in EVERY mode ──────────────────────────
+ *
+ * `/api/` is the one same-origin exception, because it is the integration's
+ * own namespace. A first-party integration's widgets call
+ * `/api/integrations/<slug>/…` rather than the vendor directly — the vendor
+ * call happens server-side, where the credential lives — and our own Acme
+ * example is shaped exactly that way.
+ *
+ * This is answered from the registry's `fixtures` REGARDLESS of the toolbar's
+ * fixtures/live switch. The harness serves no backend in either mode, so there
+ * is nothing "live" to run for this traffic even when live mode is on: passing
+ * it through would guarantee a 404 whichever mode asked for it, and the useful
+ * answer — a fixture, or a refusal that names the URL and says to add one — is
+ * the one fixtures mode already gives. A miss is `NoRecordedResponseError`,
+ * unconditionally, so the failure a partner sees does not change out from
+ * under them when they flip the toolbar.
+ *
+ * Only genuinely third-party traffic — a different origin — is what "live"
+ * actually means: reaching the real vendor under the egress allowlist below,
+ * instead of a recorded response.
  *
  * Scoped to `/api/` rather than "everything except `/_next/`" deliberately: a
  * rule that has to enumerate the framework's internals is a rule that breaks

package/dist/internal/lib/harness-fetch-interceptor.js

@@ -50,9 +50,19 @@ function installHarnessFetch() {
     } catch {
       throw new NoRecordedResponseError(method, target, true);
     }
-    if (globalThis.location !== void 0 && url.origin === globalThis.location.origin && !url.pathname.startsWith("/api/")) {
+    const isSameOrigin = globalThis.location !== void 0 && url.origin === globalThis.location.origin;
+    if (isSameOrigin && !url.pathname.startsWith("/api/")) {
       return original(input, init);
     }
+    if (isSameOrigin) {
+      const fixture2 = matchHttpFixture(method, url.toString(), active.fixtures);
+      if (!fixture2) {
+        notify(url, method, "refused");
+        throw new NoRecordedResponseError(method, redact(url), false);
+      }
+      notify(url, method, "fixture");
+      return fixtureResponse(fixture2);
+    }
     if (active.mode === "live") {
       if (!isEgressAllowed(url.toString(), active.egress)) {
         notify(url, method, "refused");

package/dist/internal/lib/harness-hooks.d.ts

@@ -0,0 +1,30 @@
+import { type DataMode } from '../../registry.js';
+/**
+ * The two public hooks behind `@ekanos/harness/hooks` (see src/hooks.ts).
+ *
+ * Both exist so widget code can ask "what mode am I in / what did the user
+ * just activate with" WITHOUT reaching for `globalThis.fetch` or reimplementing
+ * the toolbar's own state. Prefer the props `HarnessLiveMode.FetchProvider`
+ * already receives (`mode`, `activationData`) wherever your `FetchProvider`
+ * is already in the tree — those need no import from this package, and behave
+ * identically whether or not `@ekanos/harness` is even installed at the call
+ * site. Reach for these hooks only from code that runs nowhere but inside the
+ * dev harness.
+ */
+/**
+ * `'fixtures' | 'live'` for the integration currently rendering — the
+ * EFFECTIVE mode, not the toolbar's raw preference. See
+ * `resolveEffectiveDataMode` in `registry.ts`: an integration with no `live`
+ * block, or one whose `live.egress` mismatches its definition, reports
+ * `'fixtures'` here even with the toolbar switched to Live API.
+ */
+export declare function useHarnessDataMode(): DataMode;
+/**
+ * The `activationData` most recently submitted to THIS integration's
+ * activation form — `null` before any submission, after Disconnect, or while
+ * a different integration's activation is the one currently held.
+ *
+ * See `live-activation-store.ts` for the full contract: in memory only, never
+ * persisted, cleared on reload and on disconnect.
+ */
+export declare function useLiveActivationData(): unknown;

package/dist/internal/lib/harness-hooks.js

@@ -0,0 +1,28 @@
+"use client";
+import { useSyncExternalStore } from "react";
+import { resolveEffectiveDataMode } from "../../registry.js";
+import { useHarnessIntegration } from "../registry-context.js";
+import {
+  getLiveActivationServerSnapshot,
+  getLiveActivationSnapshot,
+  subscribeLiveActivationData
+} from "./live-activation-store.js";
+import { useToolbar } from "./toolbar-context.js";
+function useHarnessDataMode() {
+  const integration = useHarnessIntegration();
+  const { state } = useToolbar();
+  return resolveEffectiveDataMode(integration, state.dataMode);
+}
+function useLiveActivationData() {
+  const integration = useHarnessIntegration();
+  const slug = integration?.slug ?? "";
+  return useSyncExternalStore(
+    subscribeLiveActivationData,
+    () => getLiveActivationSnapshot(slug),
+    getLiveActivationServerSnapshot
+  );
+}
+export {
+  useHarnessDataMode,
+  useLiveActivationData
+};

package/dist/internal/lib/live-activation-store.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ *  THE LIVE-MODE ACTIVATION-DATA CHANNEL — in memory, never persisted
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * A live-mode widget's own query function has nowhere to get a vendor
+ * credential from without this. `ctx.secrets` is server-only, and the
+ * activation form's payload used to die the moment its `onSuccess` callback
+ * returned. A real partner build found the same workaround every time: a
+ * bespoke module-level store, set from the activation form after
+ * `useActivateIntegration()` resolved, read by a context the widgets
+ * consulted directly (see the Priority Passport reference this generalises —
+ * `setLiveCredentials` / `useLiveCredentials`).
+ *
+ * `fixtureActivationActions.activate` in harness-providers.tsx already HOLDS
+ * the submitted `activationData` — it is the function's own argument — so
+ * capturing it here costs nothing new. What this module adds is the one thing
+ * a bespoke per-integration store cannot: ONE channel every activation flows
+ * through (the plain form, the OAuth form — anything built on
+ * `useActivateIntegration()`), keyed by `integrationSlug` so switching between
+ * two registered integrations without a reload cannot leak one's credential
+ * into the other's widgets.
+ *
+ * The invariants, stated plainly because this is exactly the kind of
+ * convenience that leaks into production if it is not:
+ *
+ *  - IN MEMORY ONLY. A module-level variable, nothing else — never written to
+ *    `localStorage`, a fixture, or the registry.
+ *  - CLEARED ON RELOAD. There is nothing to clear: the module is
+ *    re-evaluated and the variable starts back at `null`.
+ *  - CLEARED ON DISCONNECT. `fixtureActivationActions.deactivate` and the
+ *    Activation surface's own Disconnect / Reset flow controls all clear the
+ *    entry for that slug, so a disconnected integration's widgets cannot keep
+ *    using a credential the UI says is gone.
+ *  - A DEV-ONLY CONVENIENCE. Production hands your handlers `ctx.secrets`
+ *    instead — server-side, encrypted, never in the browser at all. This
+ *    exists only because the harness has no server to hold a secret for the
+ *    browser to borrow from.
+ */
+/** Recorded the moment an activation flow reports success. See above. */
+export declare function setLiveActivationData(slug: string, activationData: unknown): void;
+/** A no-op for any slug other than the one currently held. */
+export declare function clearLiveActivationData(slug: string): void;
+export declare function subscribeLiveActivationData(listener: () => void): () => void;
+/** `null` when nothing has been submitted for `slug` yet, or it belongs to a different one. */
+export declare function getLiveActivationSnapshot(slug: string): unknown;
+export declare function getLiveActivationServerSnapshot(): null;
+/** Test seam: forget everything, regardless of slug. */
+export declare function resetLiveActivationData(): void;

package/dist/internal/lib/live-activation-store.js

@@ -0,0 +1,34 @@
+let entry = null;
+const listeners = /* @__PURE__ */ new Set();
+function setLiveActivationData(slug, activationData) {
+  entry = { slug, activationData: activationData ?? null };
+  listeners.forEach((listener) => listener());
+}
+function clearLiveActivationData(slug) {
+  if (entry?.slug !== slug) return;
+  entry = null;
+  listeners.forEach((listener) => listener());
+}
+function subscribeLiveActivationData(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function getLiveActivationSnapshot(slug) {
+  return entry?.slug === slug ? entry.activationData : null;
+}
+function getLiveActivationServerSnapshot() {
+  return null;
+}
+function resetLiveActivationData() {
+  entry = null;
+}
+export {
+  clearLiveActivationData,
+  getLiveActivationServerSnapshot,
+  getLiveActivationSnapshot,
+  resetLiveActivationData,
+  setLiveActivationData,
+  subscribeLiveActivationData
+};

package/dist/internal/lib/theme-toggle.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pure label logic for the dev toolbar's theme toggle button, split out of
+ * `DevToolbar` so it is testable without a DOM (this package's vitest config
+ * runs in `node` and deliberately has no component-rendering tests — see
+ * `vitest.config.ts`).
+ *
+ * The button renders BOTH "Dark"/"Light" label spans and lets CSS's `dark:`
+ * variant pick one for sighted users — necessary so the very first frame is
+ * already correct (see the comment in `dev-toolbar.tsx` on why `resolvedTheme`
+ * is not read during render for the visual label). Without an explicit
+ * `aria-label`, a screen reader concatenates BOTH spans' text into the
+ * accessible name ("DarkLight"), and the visible text names the CURRENT
+ * theme rather than the action the button performs. `getAccessibleLabel`
+ * supplies the correct accessible name instead: the ACTION the click
+ * performs, not the current state.
+ */
+export declare function getThemeToggleAccessibleLabel(resolvedTheme: string | undefined): string;

package/dist/internal/lib/theme-toggle.js

@@ -0,0 +1,6 @@
+function getThemeToggleAccessibleLabel(resolvedTheme) {
+  return resolvedTheme === "dark" ? "Switch to light theme" : "Switch to dark theme";
+}
+export {
+  getThemeToggleAccessibleLabel
+};

package/dist/internal/routes/activation-page.js

@@ -14,6 +14,11 @@ import {
 } from "@ekanos/ui/dialog";
 import { HARNESS_ACCOUNT_ID } from "../../registry.js";
 import { useDefinitionMockContext } from "../lib/definition-mock-context.js";
+import {
+  useHarnessDataMode,
+  useLiveActivationData
+} from "../lib/harness-hooks.js";
+import { clearLiveActivationData } from "../lib/live-activation-store.js";
 import { hasSensitiveValues, redactSensitive } from "../lib/redact.js";
 import {
   runOnActivateHook
@@ -30,6 +35,8 @@ function ActivationPage() {
   });
   const integration = useHarnessIntegration();
   const { state: toolbar } = useToolbar();
+  const mode = useHarnessDataMode();
+  const activationData = useLiveActivationData();
   const ctx = useDefinitionMockContext(
     integration ?? { slug: "", name: "", description: "", widgets: [] },
     toolbar.variant
@@ -79,13 +86,16 @@ function ActivationPage() {
               {
                 variant: "ghost",
                 size: "sm",
-                onClick: () => setFlow({
-                  open: false,
-                  connected: false,
-                  result: null,
-                  revealed: false,
-                  activationHook: null
-                }),
+                onClick: () => {
+                  clearLiveActivationData(integration.slug);
+                  setFlow({
+                    open: false,
+                    connected: false,
+                    result: null,
+                    revealed: false,
+                    activationHook: null
+                  });
+                },
                 children: "Reset flow"
               }
             )
@@ -111,13 +121,18 @@ function ActivationPage() {
                   ConnectedState,
                   {
                     name: integration.name,
-                    onDisconnect: () => setFlow({
-                      open: true,
-                      connected: false,
-                      result: null,
-                      revealed: false,
-                      activationHook: null
-                    })
+                    mode,
+                    hasLiveActivationData: activationData !== null,
+                    onDisconnect: () => {
+                      clearLiveActivationData(integration.slug);
+                      setFlow({
+                        open: true,
+                        connected: false,
+                        result: null,
+                        revealed: false,
+                        activationHook: null
+                      });
+                    }
                   }
                 ) : (
                   /*
@@ -270,6 +285,8 @@ function PermissionList({
 }
 function ConnectedState({
   name,
+  mode,
+  hasLiveActivationData,
   onDisconnect
 }) {
   return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-5", children: [
@@ -277,6 +294,14 @@ function ConnectedState({
       name,
       " is connected to your workspace."
     ] }),
+    /* @__PURE__ */ jsx(
+      "p",
+      {
+        className: "text-muted-foreground text-sm",
+        "data-test": "activation-mode-notice",
+        children: mode === "live" ? hasLiveActivationData ? "The toolbar is on Live API \u2014 this activation data is available to live-mode widgets on this visit." : "The toolbar is on Live API, but this activation submitted no data for live-mode widgets to authenticate with." : "This surface is Fusion-mocked; widgets read fixtures \u2014 switch the toolbar to Live API to exercise real requests."
+      }
+    ),
     /* @__PURE__ */ jsx(
       Button,
       {

package/dist/internal/routes/integration-layout.js

@@ -5,9 +5,9 @@ import { notFound } from "next/navigation";
 import { Alert, AlertDescription, AlertTitle } from "@ekanos/ui/alert";
 import {
   findEgressMismatch,
+  resolveEffectiveDataMode,
   resolveEgress,
-  seedsForMode,
-  supportsLiveMode
+  seedsForMode
 } from "../../registry.js";
 import { HarnessProviders } from "../components/harness-providers.js";
 import { SurfaceNav } from "../components/surface-nav.js";
@@ -21,7 +21,7 @@ function IntegrationLayout({ children }) {
     () => integration ? findEgressMismatch(integration) : null,
     [integration]
   );
-  const mode = supportsLiveMode(integration) && !egressMismatch ? state.dataMode : "fixtures";
+  const mode = resolveEffectiveDataMode(integration, state.dataMode);
   const seeds = useMemo(
     () => integration ? seedsForMode(integration, state.variant, mode) : [],
     [integration, state.variant, mode]

package/dist/registry.d.ts

@@ -193,12 +193,60 @@ export interface HarnessLiveMode {
      * the full worked example.
      *
      * (This used to say to omit it if your widgets only call your own host
-     * routes, because the harness could not serve those. It can: a fixture
-     * whose request is under `/api/` is answered like any other, which is how
-     * the Acme example's widgets work.)
+     * routes, because the harness could not serve those. It can, in EITHER
+     * mode: a fixture whose request is under `/api/` is answered from your
+     * registry entry whether the toolbar says Fixtures or Live API, which is
+     * how the Acme example's widgets work. There is nothing "live" to run for
+     * that traffic — the harness serves no backend either way.)
      */
     FetchProvider?: ComponentType<{
         fetch: IntegrationFetch;
+        /**
+         * `'fixtures' | 'live'` — which mode is actually running right now, so a
+         * partner's own provider can expose it to widgets (or just log it) with
+         * no context of its own and no import from this package. The
+         * `useHarnessDataMode()` hook in `@ekanos/harness/hooks` answers the same
+         * question for code that runs outside a mounted `FetchProvider`.
+         */
+        mode: DataMode;
+        /**
+         * The `activationData` most recently submitted to THIS integration's
+         * activation form — `null` before any submission, after Disconnect, or
+         * while a different integration's activation is the one currently held.
+         *
+         * The harness's sanctioned live-credential channel: every activation flow
+         * (the plain form, the OAuth form — anything built on
+         * `useActivateIntegration()`) already receives this as its own argument,
+         * and the harness threads it here instead of making every partner
+         * reinvent the module-level store that motivated this field. IN MEMORY
+         * ONLY — never written to `localStorage`, a fixture, or the registry —
+         * and cleared on reload and on Disconnect. See
+         * `internal/lib/live-activation-store.ts` for the full contract.
+         *
+         * A DEV-ONLY CONVENIENCE: production hands your handlers `ctx.secrets`
+         * instead, server-side and encrypted. Nothing reaching this prop should
+         * be mistaken for that.
+         *
+         * Worked example — an activation field landing in a live request header:
+         *
+         * ```tsx
+         * export function AcmeFetchProvider({ fetch, activationData, children }: {
+         *   fetch: IntegrationFetch;
+         *   mode: DataMode;
+         *   activationData: unknown;
+         *   children: ReactNode;
+         * }) {
+         *   const token = (activationData as { apiToken?: string } | null)?.apiToken;
+         *   const authedFetch: IntegrationFetch = (input, init) =>
+         *     fetch(input, {
+         *       ...init,
+         *       headers: { ...init?.headers, ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+         *     });
+         *   return <AcmeFetchContext value={authedFetch}>{children}</AcmeFetchContext>;
+         * }
+         * ```
+         */
+        activationData: unknown;
         children: ReactNode;
     }>;
     /**
@@ -416,3 +464,18 @@ export declare function resolveEgress(integration: HarnessIntegration): readonly
 export declare function supportsLiveMode(integration: HarnessIntegration | null): integration is HarnessIntegration & {
     live: HarnessLiveMode;
 };
+/**
+ * The EFFECTIVE data mode for one integration — not the toolbar's raw
+ * preference.
+ *
+ * Live mode has to be forced back to `'fixtures'` whenever the toolbar switch
+ * would not mean anything: an integration with no `live` block has nothing to
+ * switch, and a `live.egress`/definition mismatch (`findEgressMismatch`) would
+ * run the switch against an allowlist production never validated — the false
+ * green live mode exists to prevent.
+ *
+ * `IntegrationLayout` and `useHarnessDataMode()` both call this rather than
+ * each recomputing it, so there is exactly one place that decides and the
+ * hook can never report a mode other than the one that actually rendered.
+ */
+export declare function resolveEffectiveDataMode(integration: HarnessIntegration | null, toolbarMode: DataMode): DataMode;

package/dist/registry.js

@@ -64,6 +64,11 @@ function resolveEgress(integration) {
 function supportsLiveMode(integration) {
   return integration?.live !== void 0;
 }
+function resolveEffectiveDataMode(integration, toolbarMode) {
+  if (!supportsLiveMode(integration)) return "fixtures";
+  if (findEgressMismatch(integration)) return "fixtures";
+  return toolbarMode;
+}
 export {
   DATA_MODES,
   FIXTURE_VARIANTS,
@@ -76,6 +81,7 @@ export {
   findIntegration,
   findWidget,
   harnessWidgetsFromDefinition,
+  resolveEffectiveDataMode,
   resolveEgress,
   seedsForMode,
   supportsLiveMode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/harness",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "The Ekanos integration dev harness — every surface of an integration rendered in real Fusion chrome, from fixtures, with no Supabase, auth or network.",
   "license": "MIT",
@@ -36,6 +36,10 @@
       "types": "./dist/routes.d.ts",
       "default": "./dist/routes.js"
     },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "default": "./dist/hooks.js"
+    },
     "./styles.css": "./dist/styles.css",
     "./mocks/team-account-workspace": {
       "types": "./dist/mocks/team-account-workspace.d.ts",
@@ -62,8 +66,8 @@
     "tailwindcss": "^4.0.0"
   },
   "devDependencies": {
-    "@ekanos/sdk": "0.1.4",
-    "@ekanos/ui": "0.1.4",
+    "@ekanos/sdk": "0.1.5",
+    "@ekanos/ui": "0.1.5",
     "@kit/eslint-config": "0.2.0",
     "@kit/prettier-config": "0.1.0",
     "@kit/tsconfig": "0.1.0",