@ekanos/harness 0.1.1 → 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.
 
@@ -738,6 +819,12 @@ 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.
 
+**`onActivate` runs on the Activation surface, not here.** Submitting the
+activation form there runs your real `onActivate` hook (if declared) against
+its own `createMockContext()`, seeded from the same `triggerMocks` below, and
+shows the outcome — ran / skipped (not declared) / threw with the message —
+right under the connect dialog.
+
 ### `triggerMocks`
 
 The mock context is derived from the definition — slug, storage schemas, egress
@@ -821,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/definition-mock-context.d.ts

@@ -0,0 +1,14 @@
+import { type MockIntegrationContext } from '@ekanos/sdk/testing';
+import { type FixtureVariant, type HarnessIntegration } from '../../registry.js';
+/**
+ * One `createMockContext()` derived from a harness integration's definition
+ * (slug, storage schemas, egress) plus its `triggerMocks` seeds — the exact
+ * construction the Triggers surface uses for webhooks/schedules, extracted
+ * here so the Activation surface can run `onActivate` against the SAME kind
+ * of context a partner's handlers see elsewhere in the harness.
+ *
+ * One context per mount: `useState`'s initializer keeps it stable across
+ * re-renders without an effect, and state (storage, secrets, logs)
+ * accumulates for the life of the visit, like a real account.
+ */
+export declare function useDefinitionMockContext(integration: HarnessIntegration, variant: FixtureVariant): MockIntegrationContext | null;

package/dist/internal/lib/definition-mock-context.js

@@ -0,0 +1,43 @@
+"use client";
+import { useState } from "react";
+import {
+  createMockContext
+} from "@ekanos/sdk/testing";
+import {
+  HARNESS_ACCOUNT_ID,
+  resolveEgress
+} from "../../registry.js";
+import { compileFixtures, fixturesToMockHandlers } from "./http-fixtures.js";
+function useDefinitionMockContext(integration, variant) {
+  const [ctx] = useState(() => {
+    const definition = integration.definition;
+    if (!definition) return null;
+    const mocks = integration.triggerMocks ?? {};
+    return createMockContext({
+      accountId: HARNESS_ACCOUNT_ID,
+      integration: { slug: definition.slug },
+      ...definition.storage ? { storageSchemas: definition.storage } : {},
+      egress: definition.egress ?? [],
+      ...mocks.storage ? {
+        storage: mocks.storage
+      } : {},
+      ...mocks.secrets ? { secrets: mocks.secrets } : {},
+      fetchHandlers: [
+        ...mocks.fetchHandlers ?? [],
+        ...fixturesToMockHandlers(
+          // Client-only, like the layout: no origin on the server, and
+          // nothing fetches there.
+          globalThis.location === void 0 ? [] : compileFixtures(
+            integration.fixtures?.[variant] ?? [],
+            resolveEgress(integration),
+            globalThis.location.origin
+          )
+        )
+      ]
+    });
+  });
+  return ctx;
+}
+export {
+  useDefinitionMockContext
+};

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/run-activation-hook.d.ts

@@ -0,0 +1,28 @@
+import type { IntegrationDefinition } from '@ekanos/sdk/integration';
+import { type MockIntegrationContext } from '@ekanos/sdk/testing';
+/**
+ * The outcome of one local run of a definition's `onActivate` hook, for the
+ * Activation surface's readout:
+ *
+ *  - `'skipped'`   — the definition (or the harness entry) declares no
+ *    `onActivate` at all. Not an error: most integrations have nothing to
+ *    seed and this is a perfectly good answer.
+ *  - `'ran'`       — the hook completed without throwing.
+ *  - `'threw'`     — the hook threw. In production this is NON-FATAL (logged
+ *    as a warning, activation stays active — see `OnActivateHandler`'s
+ *    TSDoc); the harness surfaces the same "not fatal, but look at this"
+ *    framing rather than treating it as a failed activation.
+ *
+ * Pulled out of the activation route component so it is testable without
+ * rendering anything — the harness deliberately carries no component/DOM
+ * tests (see vitest.config.ts), only the underlying logic.
+ */
+export type OnActivateOutcome = {
+    status: 'skipped';
+} | {
+    status: 'ran';
+} | {
+    status: 'threw';
+    message: string;
+};
+export declare function runOnActivateHook(definition: IntegrationDefinition | undefined, ctx: MockIntegrationContext | null): Promise<OnActivateOutcome>;

package/dist/internal/lib/run-activation-hook.js

@@ -0,0 +1,20 @@
+import {
+  invokeActivate
+} from "@ekanos/sdk/testing";
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runOnActivateHook(definition, ctx) {
+  if (!definition?.onActivate || !ctx) {
+    return { status: "skipped" };
+  }
+  try {
+    await invokeActivate(definition, { context: ctx });
+    return { status: "ran" };
+  } catch (error) {
+    return { status: "threw", message: describeError(error) };
+  }
+}
+export {
+  runOnActivateHook
+};

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

@@ -1,5 +1,5 @@
 "use client";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { notFound } from "next/navigation";
 import { Alert, AlertDescription, AlertTitle } from "@ekanos/ui/alert";
@@ -13,11 +13,34 @@ import {
   DialogTitle
 } 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
+} from "../lib/run-activation-hook.js";
+import { useToolbar } from "../lib/toolbar-context.js";
 import { useHarnessIntegration } from "../registry-context.js";
 function ActivationPage() {
-  const [flow, setFlow] = useState({ open: true, connected: false, result: null, revealed: false });
+  const [flow, setFlow] = useState({
+    open: true,
+    connected: false,
+    result: null,
+    revealed: false,
+    activationHook: null
+  });
   const integration = useHarnessIntegration();
+  const { state: toolbar } = useToolbar();
+  const mode = useHarnessDataMode();
+  const activationData = useLiveActivationData();
+  const ctx = useDefinitionMockContext(
+    integration ?? { slug: "", name: "", description: "", widgets: [] },
+    toolbar.variant
+  );
   if (!integration) notFound();
   const ActivationForm = integration.activationForm;
   const definition = integration.definition;
@@ -63,12 +86,16 @@ function ActivationPage() {
               {
                 variant: "ghost",
                 size: "sm",
-                onClick: () => setFlow({
-                  open: false,
-                  connected: false,
-                  result: null,
-                  revealed: false
-                }),
+                onClick: () => {
+                  clearLiveActivationData(integration.slug);
+                  setFlow({
+                    open: false,
+                    connected: false,
+                    result: null,
+                    revealed: false,
+                    activationHook: null
+                  });
+                },
                 children: "Reset flow"
               }
             )
@@ -94,12 +121,18 @@ function ActivationPage() {
                   ConnectedState,
                   {
                     name: integration.name,
-                    onDisconnect: () => setFlow({
-                      open: true,
-                      connected: false,
-                      result: null,
-                      revealed: false
-                    })
+                    mode,
+                    hasLiveActivationData: activationData !== null,
+                    onDisconnect: () => {
+                      clearLiveActivationData(integration.slug);
+                      setFlow({
+                        open: true,
+                        connected: false,
+                        result: null,
+                        revealed: false,
+                        activationHook: null
+                      });
+                    }
                   }
                 ) : (
                   /*
@@ -113,12 +146,19 @@ function ActivationPage() {
                       accountId: HARNESS_ACCOUNT_ID,
                       productSlug: integration.slug,
                       inline: true,
-                      onSuccess: (result) => setFlow({
-                        open: false,
-                        connected: true,
-                        result: result ?? null,
-                        revealed: false
-                      }),
+                      onSuccess: async (result) => {
+                        const activationHook = await runOnActivateHook(
+                          definition,
+                          ctx
+                        );
+                        setFlow({
+                          open: false,
+                          connected: true,
+                          result: result ?? null,
+                          revealed: false,
+                          activationHook
+                        });
+                      },
                       onCancel: () => setFlow((prev) => ({ ...prev, open: false }))
                     }
                   )
@@ -174,7 +214,34 @@ function ActivationPage() {
             null,
             2
           ) })
-        ] }) : null
+        ] }) : null,
+        flow.activationHook ? /* @__PURE__ */ jsx(OnActivatePanel, { outcome: flow.activationHook }) : null
+      ]
+    }
+  );
+}
+function OnActivatePanel({ outcome }) {
+  const badge = outcome.status === "ran" ? { variant: "default", label: "onActivate ran" } : outcome.status === "skipped" ? {
+    variant: "secondary",
+    label: "onActivate skipped \u2014 not declared"
+  } : { variant: "destructive", label: "onActivate threw" };
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: "bg-card flex flex-col gap-2 rounded-lg border p-6",
+      "data-test": "activation-onactivate-outcome",
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "flex items-center gap-2", children: /* @__PURE__ */ jsx(Badge, { variant: badge.variant, children: badge.label }) }),
+        outcome.status === "skipped" ? /* @__PURE__ */ jsxs("p", { className: "text-muted-foreground text-sm", children: [
+          "This integration declares no ",
+          /* @__PURE__ */ jsx("code", { children: "onActivate" }),
+          " hook \u2014 a perfectly good answer for one with nothing to seed at connect time. Add one to ",
+          /* @__PURE__ */ jsx("code", { children: "defineIntegration()" }),
+          " to warm a cache or sanity-check a credential the moment a user connects."
+        ] }) : outcome.status === "threw" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("p", { className: "text-muted-foreground text-sm", children: "In production this is NON-FATAL: the throw is logged and shown to the user as a warning, and the activation stays connected \u2014 this hook is for cache seeding and eager validation, not a connect gate." }),
+          /* @__PURE__ */ jsx("pre", { className: "bg-muted overflow-x-auto rounded-md p-3 text-xs", children: outcome.message })
+        ] }) : /* @__PURE__ */ jsx("p", { className: "text-muted-foreground text-sm", children: "Ran against the same kind of capability context (storage, secrets, egress) your schedules and webhooks run against." })
       ]
     }
   );
@@ -218,6 +285,8 @@ function PermissionList({
 }
 function ConnectedState({
   name,
+  mode,
+  hasLiveActivationData,
   onDisconnect
 }) {
   return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-5", children: [
@@ -225,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/internal/routes/triggers-page.js

@@ -4,7 +4,6 @@ import { useState } from "react";
 import { notFound } from "next/navigation";
 import { isEgressAllowed } from "@ekanos/sdk/context";
 import {
-  createMockContext,
   invokeSchedule,
   invokeWebhook
 } from "@ekanos/sdk/testing";
@@ -12,43 +11,9 @@ import { Alert, AlertDescription, AlertTitle } from "@ekanos/ui/alert";
 import { Badge } from "@ekanos/ui/badge";
 import { Button } from "@ekanos/ui/button";
 import { Textarea } from "@ekanos/ui/textarea";
-import {
-  HARNESS_ACCOUNT_ID,
-  resolveEgress
-} from "../../registry.js";
-import { compileFixtures, fixturesToMockHandlers } from "../lib/http-fixtures.js";
+import { useDefinitionMockContext } from "../lib/definition-mock-context.js";
 import { useToolbar } from "../lib/toolbar-context.js";
 import { useHarnessIntegration } from "../registry-context.js";
-function useTriggerContext(integration, variant) {
-  const [ctx] = useState(() => {
-    const definition = integration.definition;
-    if (!definition) return null;
-    const mocks = integration.triggerMocks ?? {};
-    return createMockContext({
-      accountId: HARNESS_ACCOUNT_ID,
-      integration: { slug: definition.slug },
-      ...definition.storage ? { storageSchemas: definition.storage } : {},
-      egress: definition.egress ?? [],
-      ...mocks.storage ? {
-        storage: mocks.storage
-      } : {},
-      ...mocks.secrets ? { secrets: mocks.secrets } : {},
-      fetchHandlers: [
-        ...mocks.fetchHandlers ?? [],
-        ...fixturesToMockHandlers(
-          // Client-only, like the layout: no origin on the server, and
-          // nothing fetches there.
-          globalThis.location === void 0 ? [] : compileFixtures(
-            integration.fixtures?.[variant] ?? [],
-            resolveEgress(integration),
-            globalThis.location.origin
-          )
-        )
-      ]
-    });
-  });
-  return ctx;
-}
 function OutcomePanel({ outcome }) {
   return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-3", "data-test": "trigger-outcome", children: [
     /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
@@ -320,7 +285,7 @@ function OAuthCard({ definition }) {
 function TriggersPage() {
   const integration = useHarnessIntegration();
   const { state } = useToolbar();
-  const ctx = useTriggerContext(
+  const ctx = useDefinitionMockContext(
     integration ?? { slug: "", name: "", description: "", widgets: [] },
     state.variant
   );

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/dist/styles.css

@@ -161,8 +161,12 @@ i:is(.fa-light, .fa-thin, .fa-duotone, .fa-sharp) {
  * below and the authored Pro glyph renders exactly as designed. Nothing here
  * changes what a correctly licensed host shows.
  *
- * Keep this list to names our own bundled examples actually reference; it is a
- * courtesy for the demo surfaces, not a general-purpose Pro→Free shim. */
+ * Keep this list to names our own bundled examples actually reference, or a
+ * real Pro-only name a partner build hit and reported (the block below it) —
+ * it is a courtesy for demo/partner surfaces, not a general-purpose
+ * Pro→Free shim covering every Pro glyph. `src/_impl/__tests__/
+ * fa-free-icon-names.test.tsx` in `@ekanos/ui` asserts every name here is
+ * genuinely Free-missing and every codepoint names a real Free glyph. */
 i.fa-sun-bright {
   --fa: '\f185'; /* fa-sun */
 }
@@ -194,6 +198,37 @@ i.fa-sparkles {
   --fa: '\e2ca'; /* fa-wand-magic-sparkles */
 }
 
+/* Reported by a partner build (2026-09-08): all seven are real Font Awesome
+ * PRO names (verified against packages/ui/fontawesome) that Free does not
+ * ship, so every one of them was rendering the bare circle-question fallback
+ * with no indication why. `fa-circle-question` itself was also reported, but
+ * it is NOT Free-missing — Free ships it natively at the same codepoint
+ * (`\f059`) the fallback rule above uses, so a probe that treats "content
+ * resolved to \f059" as "broken" cannot tell a genuine circle-question icon
+ * apart from the fallback. That is a probe-methodology caveat, not a shim
+ * this file can fix. */
+i.fa-cloud-snow {
+  --fa: '\f2dc'; /* fa-snowflake */
+}
+i.fa-cloud-hail {
+  --fa: '\f73b'; /* fa-cloud-meatball */
+}
+i.fa-cloud-hail-mixed {
+  --fa: '\f73b'; /* fa-cloud-meatball */
+}
+i.fa-fog {
+  --fa: '\f75f'; /* fa-smog */
+}
+i.fa-sun-cloud {
+  --fa: '\f6c4'; /* fa-cloud-sun */
+}
+i.fa-moon-cloud {
+  --fa: '\f6c3'; /* fa-cloud-moon */
+}
+i.fa-cloud-bolt-sun {
+  --fa: '\f76c'; /* fa-cloud-bolt */
+}
+
 @layer base {
   body {
     @apply bg-background text-foreground;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/harness",
-  "version": "0.1.1",
+  "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",
@@ -53,8 +57,8 @@
     "tw-animate-css": "1.4.0"
   },
   "peerDependencies": {
-    "@ekanos/sdk": "^0.1.2",
-    "@ekanos/ui": "^0.1.2",
+    "@ekanos/sdk": "^0.1.4",
+    "@ekanos/ui": "^0.1.4",
     "@tanstack/react-query": "^5.101.4",
     "next": "^16.0.0",
     "react": "^19.2.8",
@@ -62,8 +66,8 @@
     "tailwindcss": "^4.0.0"
   },
   "devDependencies": {
-    "@ekanos/sdk": "0.1.3",
-    "@ekanos/ui": "0.1.3",
+    "@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",