@somewhatintelligent/kit 0.0.3-beta.1783714528.6f95113 → 0.0.3-beta.1783732751.3b77dd8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@somewhatintelligent/kit",
-  "version": "0.0.3-beta.1783714528.6f95113",
+  "version": "0.0.3-beta.1783732751.3b77dd8",
   "type": "module",
   "sideEffects": false,
   "publishConfig": {
@@ -20,6 +20,7 @@
     "./react": "./src/react/index.ts",
     "./react-start": "./src/react-start/index.ts",
     "./react-start/client": "./src/react-start/client.ts",
+    "./react-start/mount": "./src/react-start/mount.ts",
     "./execution-context": "./src/execution-context/index.ts"
   },
   "files": [
@@ -30,7 +31,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@somewhatintelligent/auth": "^0.0.3-beta.1783714528.6f95113",
+    "@somewhatintelligent/auth": "^0.0.4-beta.1783732751.3b77dd8",
     "ulidx": "^2.4.1"
   },
   "devDependencies": {

package/src/react/__tests__/analytics.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test, vi } from "vitest";
+import { createAnalytics, type AnalyticsAdapter } from "../analytics";
+
+interface Events extends Record<string, object> {
+  signed_in: { method: "email" | "passkey" };
+  signed_out: Record<string, never>;
+}
+
+describe("createAnalytics — no adapter (analytics off)", () => {
+  const surface = createAnalytics<Events>();
+
+  test("useCapture returns a callable no-op", () => {
+    const capture = surface.useCapture();
+    expect(() => capture("signed_in", { method: "email" })).not.toThrow();
+  });
+
+  test("useCaptureAsync resolves immediately", async () => {
+    const captureAsync = surface.useCaptureAsync();
+    await expect(captureAsync("signed_out", {})).resolves.toBeUndefined();
+  });
+
+  test("provider renders children as-is", () => {
+    // The default provider is a plain function component — call it directly.
+    const Provider = surface.AnalyticsProvider as unknown as (props: object) => unknown;
+    const out = Provider({
+      app: "identity",
+      environment: "test",
+      session: null,
+      children: "kids",
+    });
+    expect(out).toBe("kids");
+  });
+});
+
+describe("createAnalytics — adapter injected", () => {
+  test("capture routes through the adapter hook", () => {
+    const spy = vi.fn();
+    const adapter: AnalyticsAdapter<Events> = { useCapture: () => spy };
+    const { useCapture } = createAnalytics<Events>(adapter);
+    useCapture()("signed_in", { method: "passkey" });
+    expect(spy).toHaveBeenCalledWith("signed_in", { method: "passkey" });
+  });
+
+  test("captureAsync falls back to sync capture when not implemented", async () => {
+    const spy = vi.fn();
+    const adapter: AnalyticsAdapter<Events> = { useCapture: () => spy };
+    const { useCaptureAsync } = createAnalytics<Events>(adapter);
+    await useCaptureAsync()("signed_out", {});
+    expect(spy).toHaveBeenCalledWith("signed_out", {});
+  });
+
+  test("captureAsync prefers the adapter's async hook", async () => {
+    const sync = vi.fn();
+    const asy = vi.fn().mockResolvedValue(undefined);
+    const adapter: AnalyticsAdapter<Events> = {
+      useCapture: () => sync,
+      useCaptureAsync: () => asy,
+    };
+    const { useCaptureAsync } = createAnalytics<Events>(adapter);
+    await useCaptureAsync()("signed_in", { method: "email" });
+    expect(asy).toHaveBeenCalled();
+    expect(sync).not.toHaveBeenCalled();
+  });
+
+  test("adapter provider is used verbatim", () => {
+    const Provider = vi.fn(({ children }) => children);
+    const adapter: AnalyticsAdapter<Events> = { Provider };
+    const surface = createAnalytics<Events>(adapter);
+    expect(surface.AnalyticsProvider).toBe(Provider);
+  });
+});

package/src/react/analytics.tsx

@@ -0,0 +1,102 @@
+/**
+ * Framework-independent analytics seam.
+ *
+ * `createAnalytics<Events, S>(adapter?)` returns the app-facing surface —
+ * `{ AnalyticsProvider, useCapture, useCaptureAsync }` — typed against the
+ * app's own event registry. The vendor lives entirely inside the injected
+ * `AnalyticsAdapter`; omit it and every surface is a no-op (feature absence
+ * is a branch): the provider renders children as-is, `useCapture` returns a
+ * function that does nothing, `useCaptureAsync` resolves immediately. App
+ * call sites never change when a vendor is added, swapped, or removed.
+ *
+ * The adapter's capture surfaces are HOOKS, not plain functions, because
+ * vendor SDKs typically hand out their capture function through React
+ * context (e.g. a PostHog provider + usePostHog). `useCaptureAsync` exists
+ * for events raced by navigation — sign-out into a redirect, delete-account
+ * into a hard reload — where the adapter should flush/await delivery before
+ * resolving. When an adapter implements only `useCapture`, the async
+ * surface falls back to it (fire-and-forget wrapped in a resolved promise).
+ *
+ * Apps glue it together once:
+ *
+ *   const adapter: AnalyticsAdapter<MyEvents> | undefined = myVendorAdapter;
+ *   export const { AnalyticsProvider, useCapture, useCaptureAsync } =
+ *     createAnalytics<MyEvents>(adapter);
+ */
+import type { ComponentType, ReactNode } from "react";
+
+/**
+ * An app's event registry shape: event name → required properties.
+ * A mapped-type constraint so plain interfaces qualify (no index signature).
+ */
+export type AnalyticsEventMap<E = unknown> = { [K in keyof E]: object };
+
+/** Fire-and-forget capture, typed against the app's registry. */
+export type CaptureFn<Events extends AnalyticsEventMap<Events>> = <E extends keyof Events>(
+  event: E,
+  props: Events[E],
+) => void;
+
+/** Awaitable capture: resolves once the adapter considers the event delivered. */
+export type CaptureAsyncFn<Events extends AnalyticsEventMap<Events>> = <E extends keyof Events>(
+  event: E,
+  props: Events[E],
+) => Promise<void>;
+
+/**
+ * Context handed to the adapter's provider at the app root. `session` is
+ * whatever session shape the app runs on (identify/reset transitions live
+ * inside the adapter, keyed off it).
+ */
+export interface AnalyticsProviderProps<S> {
+  /** App name stamped on events (multi-app fleets share one project). */
+  app: string;
+  environment: string | undefined;
+  session: S | null;
+  children?: ReactNode;
+}
+
+export interface AnalyticsAdapter<Events extends AnalyticsEventMap<Events>, S = unknown> {
+  /**
+   * Vendor root (SDK init, identity bridge). Omit for vendors that need no
+   * provider — capture hooks then run without vendor context.
+   */
+  Provider?: ComponentType<AnalyticsProviderProps<S>>;
+  /** Hook returning the sync capture function (may read vendor context). */
+  useCapture?: () => CaptureFn<Events>;
+  /**
+   * Hook returning the awaitable capture — implement with the vendor's
+   * flush/callback so navigation-raced events survive. Falls back to
+   * `useCapture` when omitted.
+   */
+  useCaptureAsync?: () => CaptureAsyncFn<Events>;
+}
+
+export interface AnalyticsSurface<Events extends AnalyticsEventMap<Events>, S> {
+  AnalyticsProvider: ComponentType<AnalyticsProviderProps<S>>;
+  useCapture: () => CaptureFn<Events>;
+  useCaptureAsync: () => CaptureAsyncFn<Events>;
+}
+
+export function createAnalytics<Events extends AnalyticsEventMap<Events>, S = unknown>(
+  adapter?: AnalyticsAdapter<Events, S>,
+): AnalyticsSurface<Events, S> {
+  const noopCapture: CaptureFn<Events> = () => {};
+
+  const AnalyticsProvider: ComponentType<AnalyticsProviderProps<S>> = adapter?.Provider
+    ? adapter.Provider
+    : ({ children }: AnalyticsProviderProps<S>) => children;
+
+  const useCapture = adapter?.useCapture ?? (() => noopCapture);
+
+  const useCaptureAsync: () => CaptureAsyncFn<Events> =
+    adapter?.useCaptureAsync ??
+    (adapter?.useCapture
+      ? () => {
+          const capture = adapter.useCapture!();
+          return async (event, props) => capture(event, props);
+        }
+      : () => async () => {});
+
+  return { AnalyticsProvider, useCapture, useCaptureAsync };
+}

package/src/react/index.ts

@@ -1,2 +1,11 @@
 export { createAuthContext } from "./auth";
 export type { AuthContextValue } from "./auth";
+export { createAnalytics } from "./analytics";
+export type {
+  AnalyticsAdapter,
+  AnalyticsEventMap,
+  AnalyticsProviderProps,
+  AnalyticsSurface,
+  CaptureFn,
+  CaptureAsyncFn,
+} from "./analytics";

package/src/react-start/__tests__/mount.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from "vitest";
+import { MOUNT_META_NAME, mountRewrite, normalizeBasepath, resolveBasepath } from "../mount";
+
+describe("normalizeBasepath", () => {
+  test("empty / null / undefined → '/'", () => {
+    expect(normalizeBasepath(undefined)).toBe("/");
+    expect(normalizeBasepath(null)).toBe("/");
+    expect(normalizeBasepath("")).toBe("/");
+    expect(normalizeBasepath("   ")).toBe("/");
+    expect(normalizeBasepath("/")).toBe("/");
+  });
+
+  test("adds a leading slash and strips trailing slashes", () => {
+    expect(normalizeBasepath("shop")).toBe("/shop");
+    expect(normalizeBasepath("/shop")).toBe("/shop");
+    expect(normalizeBasepath("/shop/")).toBe("/shop");
+    expect(normalizeBasepath("shop///")).toBe("/shop");
+    expect(normalizeBasepath("/account")).toBe("/account");
+  });
+});
+
+describe("resolveBasepath", () => {
+  test("server is always root (bouncer's vmf already stripped the mount)", () => {
+    // Even under the mount, the server sees the stripped path — basepath must
+    // be '/' server-side or matching fails.
+    expect(resolveBasepath({ isServer: true, publicBase: "/shop" })).toBe("/");
+    expect(resolveBasepath({ isServer: true, publicBase: "/shop/" })).toBe("/");
+    expect(resolveBasepath({ isServer: true, publicBase: undefined })).toBe("/");
+  });
+
+  test("client adopts the public mount so the URL bar keeps the prefix", () => {
+    expect(resolveBasepath({ isServer: false, publicBase: "/shop" })).toBe("/shop");
+    expect(resolveBasepath({ isServer: false, publicBase: "/shop/" })).toBe("/shop");
+    expect(resolveBasepath({ isServer: false, publicBase: "/account" })).toBe("/account");
+  });
+
+  test("client with no configured base (local dev-direct) → '/'", () => {
+    expect(resolveBasepath({ isServer: false, publicBase: undefined })).toBe("/");
+    expect(resolveBasepath({ isServer: false, publicBase: "/" })).toBe("/");
+  });
+});
+
+describe("resolveBasepath — runtime mount meta", () => {
+  test("client: mount meta wins over the build-time fallback", () => {
+    expect(resolveBasepath({ isServer: false, publicBase: "/shop", mountMeta: "/other" })).toBe(
+      "/other",
+    );
+  });
+  test("client: falls back to publicBase when no meta", () => {
+    expect(resolveBasepath({ isServer: false, publicBase: "/shop", mountMeta: null })).toBe(
+      "/shop",
+    );
+    expect(resolveBasepath({ isServer: false, publicBase: "/shop", mountMeta: "  " })).toBe(
+      "/shop",
+    );
+  });
+  test("server: meta never applies — bouncer already stripped the mount", () => {
+    expect(resolveBasepath({ isServer: true, publicBase: "/shop", mountMeta: "/shop" })).toBe("/");
+  });
+  test("meta is normalized like any base", () => {
+    expect(resolveBasepath({ isServer: false, publicBase: null, mountMeta: "shop/" })).toBe(
+      "/shop",
+    );
+  });
+});
+
+describe("MOUNT_META_NAME", () => {
+  test("is the vmf announcement contract shared with bouncer", () => {
+    expect(MOUNT_META_NAME).toBe("si-mount");
+  });
+});
+
+describe("mountRewrite", () => {
+  // The mount rides the router `rewrite` option, not `basepath`: TanStack
+  // Start's server handler AND client bootstrap both call
+  // router.update({ basepath: process.env.TSS_ROUTER_BASEPATH }), clobbering
+  // any createRouter-level basepath — the regression that unmounted the
+  // whole tree on staging the moment hydration finished. `rewrite` survives
+  // those updates, so these tests pin the strip/prepend contract.
+  const url = (path: string) => new URL(`https://example.com${path}`);
+
+  test("root mount → no rewrite at all (dev-direct, server)", () => {
+    expect(mountRewrite("/")).toBeUndefined();
+    expect(mountRewrite("")).toBeUndefined();
+    expect(mountRewrite("  ")).toBeUndefined();
+  });
+
+  test("input strips the mount (browser URL → router URL)", () => {
+    const rw = mountRewrite("/shop");
+    expect(rw).toBeDefined();
+    expect(rw?.input({ url: url("/shop") }).pathname).toBe("/");
+    expect(rw?.input({ url: url("/shop/") }).pathname).toBe("/");
+    expect(rw?.input({ url: url("/shop/products/tee") }).pathname).toBe("/products/tee");
+  });
+
+  test("input leaves non-mount paths alone", () => {
+    const rw = mountRewrite("/shop");
+    expect(rw?.input({ url: url("/shopping") }).pathname).toBe("/shopping");
+    expect(rw?.input({ url: url("/other") }).pathname).toBe("/other");
+  });
+
+  test("output prepends the mount (router URL → browser URL)", () => {
+    const rw = mountRewrite("/shop");
+    expect(rw?.output({ url: url("/") }).pathname).toBe("/shop");
+    expect(rw?.output({ url: url("/products/tee") }).pathname).toBe("/shop/products/tee");
+  });
+
+  test("input and output round-trip", () => {
+    const rw = mountRewrite("/shop");
+    for (const p of ["/", "/cart", "/products/tee"]) {
+      const out = rw?.output({ url: url(p) });
+      expect(rw?.input({ url: out as URL }).pathname).toBe(p);
+    }
+  });
+
+  test("mount is normalized before use", () => {
+    const rw = mountRewrite("shop/");
+    expect(rw?.input({ url: url("/shop/cart") }).pathname).toBe("/cart");
+    expect(rw?.output({ url: url("/cart") }).pathname).toBe("/shop/cart");
+  });
+});

package/src/react-start/mount.ts

@@ -0,0 +1,102 @@
+/**
+ * Mount-prefix helpers for TSS apps served behind a vmf mount.
+ *
+ * A vmf-mounted app (bouncer route mode `"vmf"`) is path-prefix-mounted on a
+ * shared host: bouncer STRIPS the mount before the request reaches the
+ * worker, so the SERVER always serves at root and every route definition /
+ * `<Link>` / redirect in the app stays prefix-free. The one thing bouncer's
+ * HTTP-layer rewrite cannot reach is the hydrated client router's
+ * history/link state — so the CLIENT router adopts the mount as a TanStack
+ * Router `rewrite` pair (`mountRewrite`): strip the mount when parsing the
+ * browser URL, prepend it when writing to history. Result: the URL bar keeps
+ * the mount across client-side navigation and hard refreshes, with zero
+ * prefixes in app code.
+ *
+ * The mount is announced at RUNTIME by bouncer's vmf HTML transform
+ * (`MOUNT_META_NAME` below — see `@somewhatintelligent/bouncer`'s
+ * MountMetaInjector). Apps may additionally compile a build-time fallback
+ * (e.g. a PUBLIC_BASE client var); the runtime meta always wins. With no
+ * bouncer in front (dev-direct) there is no meta and the mount is "/".
+ *
+ * This module is pure and isomorphic — safe to import from router setup
+ * code that TSS evaluates on both server and client.
+ */
+
+/**
+ * The `<meta name>` bouncer's vmf transform injects to announce the mount.
+ * Contract shared with `@somewhatintelligent/bouncer` — it imports this
+ * constant; apps read it via `readMountMeta`.
+ */
+export const MOUNT_META_NAME = "si-mount";
+
+/** Normalize a raw base to a leading-slash, no-trailing-slash form ("/" stays "/"). */
+export function normalizeBasepath(raw: string | undefined | null): string {
+  if (raw == null) return "/";
+  let b = raw.trim();
+  if (b === "" || b === "/") return "/";
+  if (!b.startsWith("/")) b = `/${b}`;
+  while (b.length > 1 && b.endsWith("/")) b = b.slice(0, -1);
+  return b;
+}
+
+/**
+ * The mount for the current execution side.
+ *
+ * - Server: always "/" — bouncer already stripped the mount, so the server
+ *   router matches the stripped (root) path. A non-root mount here would
+ *   fail to match the stripped path.
+ * - Client: the runtime mount meta wins (correct for whatever mount bouncer
+ *   actually served this document under, needs no build-time config), then
+ *   the build-time `publicBase` fallback, then "/".
+ */
+export function resolveBasepath(opts: {
+  isServer: boolean;
+  publicBase: string | undefined | null;
+  mountMeta?: string | undefined | null;
+}): string {
+  if (opts.isServer) return "/";
+  const meta = opts.mountMeta?.trim();
+  if (meta) return normalizeBasepath(meta);
+  return normalizeBasepath(opts.publicBase);
+}
+
+/** Reads bouncer's vmf mount announcement from the served document (client only). */
+export function readMountMeta(): string | null {
+  if (typeof document === "undefined") return null;
+  return document.querySelector(`meta[name="${MOUNT_META_NAME}"]`)?.getAttribute("content") ?? null;
+}
+
+/**
+ * The mount expressed as a TanStack Router `rewrite` pair (browser URL ↔
+ * router-internal URL): strip the mount on input, prepend it on output.
+ *
+ * Uses `rewrite`, not the `basepath` router option: TanStack Start's server
+ * handler (start-server-core createStartHandler) and client bootstrap
+ * (start-client-core hydrateStart) both call
+ * `router.update({ basepath: process.env.TSS_ROUTER_BASEPATH })`, overriding
+ * any basepath set in createRouter with that build-time define. `rewrite` is
+ * the documented channel for an asymmetric mount: router.update()
+ * re-composes `options.rewrite` after the basepath rewrite on every update,
+ * and Start never touches it.
+ * https://tanstack.com/router/latest/docs/guide/url-rewrites#interaction-with-basepath
+ */
+export function mountRewrite(mount: string):
+  | {
+      input: (opts: { url: URL }) => URL;
+      output: (opts: { url: URL }) => URL;
+    }
+  | undefined {
+  const m = normalizeBasepath(mount);
+  if (m === "/") return undefined;
+  return {
+    input: ({ url }) => {
+      if (url.pathname === m) url.pathname = "/";
+      else if (url.pathname.startsWith(`${m}/`)) url.pathname = url.pathname.slice(m.length);
+      return url;
+    },
+    output: ({ url }) => {
+      url.pathname = url.pathname === "/" ? m : m + url.pathname;
+      return url;
+    },
+  };
+}

package/src/version.gen.ts

@@ -2,6 +2,6 @@
 // values are dev placeholders, identical to the runtime fallbacks.
 export const PKG = {
   name: "@somewhatintelligent/kit",
-  version: "0.0.3-beta.1783714528.6f95113",
-  commit: "6f95113c5b404d3f046d97e1e51471dca322a469",
+  version: "0.0.3-beta.1783732751.3b77dd8",
+  commit: "3b77dd8189861ea843645f9e389cd5f874557345",
 } as const;