@guuey/create-agentic-app 0.9.0 → 0.11.0

package/dist/templates/{claude-agent-sdk → base/claude-agent-sdk}/web/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentic-app-template/web",
-  "version": "0.0.0",
   "private": true,
+  "version": "0.0.0",
   "type": "module",
   "scripts": {
     "dev": "vite --port 6890",
@@ -9,17 +9,20 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@mcp-ui/client": "^7.1.1",
-    "@silverprotocol/core": "0.5.0",
+    "@guuey/chat": "0.11.0",
+    "oidc-client-ts": "^3.1.0",
+    "qrcode": "^1.5.4",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.1.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.0.0",
+    "@types/qrcode": "^1.5.5",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@vitejs/plugin-react": "^4.3.0",
-    "typescript": "^5.8.0",
-    "vite": "^6.0.0"
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.7.2",
+    "vite": "^7.0.0"
   }
 }

package/dist/templates/base/claude-agent-sdk/web/src/components/AgentChat.tsx

@@ -0,0 +1,91 @@
+/**
+ * The configured `<GuueyChat>` for this app — distribution way #2, the
+ * embedded chat SDK. One place wires endpoint, history, identity and theme;
+ * every chat surface (the /chat page here, the fullscreen agent canvas in
+ * the agentic-app template) renders this.
+ *
+ * Identity rule: ONE mode per surface. When OIDC is configured AND a
+ * session exists, the bearer wins; otherwise the client-minted guest
+ * secret. Never both.
+ */
+import { useEffect, useState, type CSSProperties } from "react";
+import { GuueyChat } from "@guuey/chat/react";
+import type { PlanViewSummary, ViewRefItem } from "@guuey/chat";
+import { agentEndpointUrl, appConfig, historyBaseUrl } from "../config";
+import { currentIdentityMode, ensureGuestSecret } from "../lib/identity";
+import { getBearerToken, currentUser, oidcConfigured } from "../lib/oidc";
+
+/**
+ * The chat-rail bridge (agentic-app shell): with `viewsBridge` set, the
+ * chat runs the kit's CHIPS presentation — generative views collapse to
+ * compact chips in the rail, the full renders belong to the host's main
+ * canvas (fed by `onViewsChange`), and chip clicks re-select
+ * (`onViewRef` → `promotedViewKey`, the browser-history mechanic).
+ */
+export interface ViewsBridge {
+  promotedViewKey?: string | undefined;
+  onViewRef: (item: ViewRefItem) => void;
+  onViewsChange: (views: PlanViewSummary[]) => void;
+}
+
+// Module scope on purpose: props want STABLE identities. An inline
+// `policy={{ … }}` literal (or per-render arrow getters) re-mints every
+// render; the kit stabilizes structurally since 0.11.0, but the template
+// models the correct shape — one identity for the app's whole life.
+const RAIL_POLICY = { view: { timeoutMs: 8000, presentation: "chips" as const } };
+
+export function AgentChat({
+  className,
+  style,
+  viewsBridge,
+}: {
+  className?: string;
+  style?: CSSProperties;
+  viewsBridge?: ViewsBridge;
+}) {
+  // The user's CHOSEN mode wins: an explicit "Continue as guest" must never
+  // be shadowed by a cached OIDC session. Only when no choice is recorded
+  // does a live session imply oidc.
+  const chosen = currentIdentityMode();
+  const [identity, setIdentity] = useState<"resolving" | "guest" | "oidc">(
+    chosen === "guest" || !oidcConfigured() ? "guest" : chosen === "oidc" ? "oidc" : "resolving",
+  );
+
+  useEffect(() => {
+    if (identity !== "resolving") return;
+    let cancelled = false;
+    void currentUser().then((user) => {
+      if (!cancelled) setIdentity(user ? "oidc" : "guest");
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [identity]);
+
+  if (identity === "resolving") return null;
+
+  const shared = {
+    endpointUrl: agentEndpointUrl(),
+    appId: appConfig.link?.appId ?? "local",
+    apiBaseUrl: historyBaseUrl(),
+    mode: appConfig.theme.mode,
+    className,
+    style,
+    ...(viewsBridge !== undefined
+      ? {
+          policy: RAIL_POLICY,
+          promotedViewKey: viewsBridge.promotedViewKey,
+          onViewRef: viewsBridge.onViewRef,
+          onViewsChange: viewsBridge.onViewsChange,
+        }
+      : {}),
+  };
+
+  // The lib functions ARE the stable getters — no wrapping arrows (a fresh
+  // closure per render is the identity churn RAIL_POLICY exists to avoid).
+  return identity === "oidc" ? (
+    <GuueyChat {...shared} getAccessToken={getBearerToken} />
+  ) : (
+    <GuueyChat {...shared} getGuestSecret={ensureGuestSecret} />
+  );
+}

package/dist/templates/base/claude-agent-sdk/web/src/components/BootstrapGate.tsx

@@ -0,0 +1,30 @@
+/**
+ * Dev-time gate: until `pnpm bootstrap` has run, every page renders this
+ * setup screen instead of a half-configured app. Production builds are
+ * gated harder — vite.config.ts fails the build outright.
+ */
+import type { ReactNode } from "react";
+import { appConfig } from "../config";
+
+export function BootstrapGate({ children }: { children: ReactNode }) {
+  if (appConfig.bootstrapped) return <>{children}</>;
+  return (
+    <main className="gate">
+      <div className="gate-card">
+        <h1>Run bootstrap first</h1>
+        <p>
+          This project has not been configured yet. From the project root:
+        </p>
+        <pre>
+          <code>pnpm bootstrap</code>
+        </pre>
+        <p>
+          That writes <code>guuey.app.json</code> (brand, theme, copy) and
+          regenerates <code>AGENTS.md</code>. Then start the local stack with{" "}
+          <code>pnpm dev</code>. When you are ready to bind a deployed guuey
+          app: <code>pnpm bootstrap -- --link</code>.
+        </p>
+      </div>
+    </main>
+  );
+}

package/dist/templates/base/claude-agent-sdk/web/src/components/QrLink.tsx

@@ -0,0 +1,25 @@
+/** A QR code for a URL, with the plain link beneath — mobile hand-off. */
+import { useEffect, useRef, useState } from "react";
+import QRCode from "qrcode";
+
+export function QrLink({ url, size = 200 }: { url: string; size?: number }) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!canvasRef.current) return;
+    QRCode.toCanvas(canvasRef.current, url, { width: size, margin: 1 }).catch((err: unknown) => {
+      setError(err instanceof Error ? err.message : String(err));
+    });
+  }, [url, size]);
+
+  return (
+    <span className="qr-link">
+      <canvas ref={canvasRef} className="qr" />
+      <a href={url} target="_blank" rel="noreferrer">
+        {url}
+      </a>
+      {error ? <span className="error">QR render failed: {error}</span> : null}
+    </span>
+  );
+}

package/dist/templates/base/claude-agent-sdk/web/src/components/Shell.tsx

@@ -0,0 +1,50 @@
+/**
+ * Base-template chrome: brand header + nav + auth affordance. Pages render
+ * inside via the router outlet.
+ */
+import { Link, NavLink, Outlet, useLocation, useNavigate } from "react-router-dom";
+import { appConfig } from "../config";
+import { CHAT_PATH, HOME_PATH } from "../routes";
+import { currentIdentityMode, logOut } from "../lib/identity";
+import { oidcConfigured, signOutOidc } from "../lib/oidc";
+
+export function Shell() {
+  const navigate = useNavigate();
+  // Subscribing to the location re-renders this chrome on every navigation,
+  // so the render-time read below stays fresh after login/logout. (A
+  // `storage` listener would NOT work — that event only fires in OTHER
+  // tabs, never the one that wrote the change.)
+  useLocation();
+  const mode = currentIdentityMode();
+
+  async function handleLogOut() {
+    if (mode === "oidc" && oidcConfigured()) await signOutOidc();
+    logOut();
+    navigate("/");
+  }
+
+  return (
+    <div className="shell">
+      <header className="topbar">
+        <Link to="/" className="brand">
+          <span className="brand-mark">{appConfig.brand.logoText}</span>
+          <span>{appConfig.brand.name}</span>
+        </Link>
+        <nav>
+          <NavLink to={CHAT_PATH}>Chat</NavLink>
+          <NavLink to={HOME_PATH}>Home</NavLink>
+          {mode === null ? (
+            <NavLink to="/login" className="btn btn-accent">
+              Sign in
+            </NavLink>
+          ) : (
+            <button type="button" className="btn" onClick={() => void handleLogOut()}>
+              Log out{mode === "guest" ? " (guest)" : ""}
+            </button>
+          )}
+        </nav>
+      </header>
+      <Outlet />
+    </div>
+  );
+}

package/dist/templates/base/claude-agent-sdk/web/src/config.ts

@@ -0,0 +1,148 @@
+/**
+ * Typed access to `guuey.app.json` — the ONE file `pnpm bootstrap` writes.
+ *
+ * The JSON is validated structurally here (not just cast) so a hand-edited
+ * config fails with a named path instead of an undefined-deep-in-React
+ * crash. The schema is documented in `../guuey.app.schema.json`.
+ */
+import rawConfig from "../../guuey.app.json";
+
+export interface OidcConfig {
+  /** OIDC issuer URL (https). Discovery via /.well-known/openid-configuration. */
+  issuer: string;
+  clientId: string;
+}
+
+export interface AppLink {
+  appId: string;
+  env: "dev" | "staging" | "release";
+  /** Public API base ending in /v1 — history + persisted-card reads. */
+  apiBaseUrl: string;
+  /** The agent pod's public origin — live chat + health probe. */
+  endpointUrl: string;
+  /** Widget host origin serving /v1.js for this environment. */
+  widgetOrigin: string;
+  /** Portal web origin (the "talk on mobile" target). */
+  portalUrl: string;
+  slug: string | null;
+  /** The agent's own hosted page (https://<slug>.agents...), when slugged. */
+  pageUrl: string | null;
+}
+
+export interface AppConfig {
+  schema: number;
+  bootstrapped: boolean;
+  brand: { name: string; tagline: string; logoText: string };
+  theme: { accent: string; mode: "light" | "dark" };
+  copy: {
+    landing: { headline: string; sub: string };
+    login: { guestHint: string };
+  };
+  auth: { oidc: OidcConfig | null };
+  link: AppLink | null;
+  demoMode: boolean;
+}
+
+class ConfigError extends Error {
+  constructor(path: string, expected: string) {
+    super(`guuey.app.json: ${path} — expected ${expected}. Re-run \`pnpm bootstrap\` or fix the file by hand (schema: guuey.app.schema.json).`);
+  }
+}
+
+function str(v: unknown, path: string): string {
+  if (typeof v !== "string" || v.length === 0) throw new ConfigError(path, "a non-empty string");
+  return v;
+}
+
+function bool(v: unknown, path: string): boolean {
+  if (typeof v !== "boolean") throw new ConfigError(path, "a boolean");
+  return v;
+}
+
+function obj(v: unknown, path: string): Record<string, unknown> {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) throw new ConfigError(path, "an object");
+  return v as Record<string, unknown>;
+}
+
+function validate(raw: unknown): AppConfig {
+  const root = obj(raw, "$");
+  if (root.schema !== 1) throw new ConfigError("schema", "the literal 1");
+
+  const brand = obj(root.brand, "brand");
+  const theme = obj(root.theme, "theme");
+  const mode = theme.mode;
+  if (mode !== "light" && mode !== "dark") throw new ConfigError("theme.mode", '"light" | "dark"');
+  const copy = obj(root.copy, "copy");
+  const landing = obj(copy.landing, "copy.landing");
+  const login = obj(copy.login, "copy.login");
+  const auth = obj(root.auth, "auth");
+
+  let oidc: OidcConfig | null = null;
+  if (auth.oidc !== null && auth.oidc !== undefined) {
+    const o = obj(auth.oidc, "auth.oidc");
+    oidc = { issuer: str(o.issuer, "auth.oidc.issuer"), clientId: str(o.clientId, "auth.oidc.clientId") };
+  }
+
+  let link: AppLink | null = null;
+  if (root.link !== null && root.link !== undefined) {
+    const l = obj(root.link, "link");
+    const env = l.env;
+    if (env !== "dev" && env !== "staging" && env !== "release") {
+      throw new ConfigError("link.env", '"dev" | "staging" | "release"');
+    }
+    link = {
+      appId: str(l.appId, "link.appId"),
+      env,
+      apiBaseUrl: str(l.apiBaseUrl, "link.apiBaseUrl"),
+      // Normalize to the ORIGIN whatever shape was stored: the platform's
+      // deployment records carry the full `…/agent/invoke` URL, while this
+      // contract (and the probe) wants the base. The chat kit accepts
+      // either, so normalizing here makes both consumers correct.
+      endpointUrl: str(l.endpointUrl, "link.endpointUrl").replace(/\/agent\/invoke\/?$/, ""),
+      widgetOrigin: str(l.widgetOrigin, "link.widgetOrigin"),
+      portalUrl: str(l.portalUrl, "link.portalUrl"),
+      slug: typeof l.slug === "string" ? l.slug : null,
+      pageUrl: typeof l.pageUrl === "string" ? l.pageUrl : null,
+    };
+  }
+
+  return {
+    schema: 1,
+    bootstrapped: bool(root.bootstrapped, "bootstrapped"),
+    brand: {
+      name: str(brand.name, "brand.name"),
+      tagline: str(brand.tagline, "brand.tagline"),
+      logoText: str(brand.logoText, "brand.logoText"),
+    },
+    theme: { accent: str(theme.accent, "theme.accent"), mode },
+    copy: {
+      landing: { headline: str(landing.headline, "copy.landing.headline"), sub: str(landing.sub, "copy.landing.sub") },
+      login: { guestHint: str(login.guestHint, "copy.login.guestHint") },
+    },
+    auth: { oidc },
+    link,
+    demoMode: bool(root.demoMode ?? false, "demoMode"),
+  };
+}
+
+export const appConfig: AppConfig = validate(rawConfig);
+
+/** The local `guuey dev --serve` router (scripts/dev.mjs boots it). */
+export const DEV_AGENT_URL = "http://localhost:6790";
+
+export const isLinked: boolean = appConfig.link !== null;
+
+/** Live-chat base: the bound pod when linked, the local dev router otherwise. */
+export function agentEndpointUrl(): string {
+  return appConfig.link?.endpointUrl ?? DEV_AGENT_URL;
+}
+
+/**
+ * History/read-plane base. When linked this is the public API (`…/v1`);
+ * in local dev, `guuey dev --serve` exposes the same read-plane route
+ * shape (`/threads/:id/messages`) on its own origin, so history and
+ * rehydration work locally too.
+ */
+export function historyBaseUrl(): string {
+  return appConfig.link?.apiBaseUrl ?? DEV_AGENT_URL;
+}

package/dist/templates/base/claude-agent-sdk/web/src/lib/identity.ts

@@ -0,0 +1,67 @@
+/**
+ * End-user identity for this app's chat surfaces.
+ *
+ * ONE mode per surface — never both resolvers at once (a bearer + a guest
+ * secret on the same request is a silent-downgrade hazard the platform
+ * refuses to guess about):
+ *
+ * - **Guest** (always available): a client-minted 64-hex secret stored at
+ *   `localStorage["guuey:guest-secret:<appId>"]` and sent as the
+ *   `x-guuey-guest` header. Per-browser and persistent, so the agent
+ *   remembers the visitor across reloads. This is the same mechanic the
+ *   guuey widget uses. "Log out" deletes the secret — a fresh one next
+ *   visit is a fresh person as far as the agent is concerned.
+ * - **Signed in** (when `auth.oidc` is configured in guuey.app.json): an
+ *   OIDC ID token from your IdP (see ./oidc.ts), sent as a Bearer. The
+ *   bound guuey app must be in BYO auth mode for the same issuer
+ *   (`guuey apps update <appId> --auth-mode byo --issuer-url … --audience <clientId>`).
+ */
+import { appConfig } from "../config";
+
+export type IdentityMode = "guest" | "oidc";
+
+const scope = appConfig.link?.appId ?? "local";
+const GUEST_KEY = `guuey:guest-secret:${scope}`;
+const MODE_KEY = `guuey:identity-mode:${scope}`;
+
+function mintSecret(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** The stored guest secret, minting one on first use. */
+export function ensureGuestSecret(): string {
+  const existing = localStorage.getItem(GUEST_KEY);
+  if (existing && /^[0-9a-f]{64}$/.test(existing)) return existing;
+  const fresh = mintSecret();
+  localStorage.setItem(GUEST_KEY, fresh);
+  return fresh;
+}
+
+export function getStoredGuestSecret(): string | null {
+  const v = localStorage.getItem(GUEST_KEY);
+  return v && /^[0-9a-f]{64}$/.test(v) ? v : null;
+}
+
+export function currentIdentityMode(): IdentityMode | null {
+  const v = localStorage.getItem(MODE_KEY);
+  return v === "guest" || v === "oidc" ? v : null;
+}
+
+export function setIdentityMode(mode: IdentityMode | null): void {
+  if (mode === null) localStorage.removeItem(MODE_KEY);
+  else localStorage.setItem(MODE_KEY, mode);
+}
+
+/** "Continue as guest": ensure a secret exists and select guest mode. */
+export function continueAsGuest(): void {
+  ensureGuestSecret();
+  setIdentityMode("guest");
+}
+
+/** Log out of whichever mode is active. Guest logout forgets the secret. */
+export function logOut(): void {
+  if (currentIdentityMode() === "guest") localStorage.removeItem(GUEST_KEY);
+  setIdentityMode(null);
+}

package/dist/templates/base/claude-agent-sdk/web/src/lib/oidc.ts

@@ -0,0 +1,79 @@
+/**
+ * BYO-OIDC sign-in seam (only active when `auth.oidc` is configured in
+ * guuey.app.json).
+ *
+ * Standard authorization-code + PKCE via oidc-client-ts. The ID TOKEN is
+ * what the guuey pod verifies in BYO auth mode (audience = your client id),
+ * so `getAccessToken` below returns `user.id_token` — forwarding the OAuth
+ * access token instead is the classic mistake (wrong audience → 401).
+ *
+ * Works with any spec-compliant IdP that can host a "Sign in with Google"
+ * (Auth0, AWS Cognito, Okta, Keycloak, …). Configure the IdP's allowed
+ * callback URL to `<your site origin>/login`.
+ */
+import { UserManager, WebStorageStateStore, type User } from "oidc-client-ts";
+import { appConfig, type OidcConfig } from "../config";
+
+let manager: UserManager | null = null;
+
+export function oidcConfigured(): boolean {
+  return appConfig.auth.oidc !== null;
+}
+
+function requireManager(oidc: OidcConfig): UserManager {
+  if (manager) return manager;
+  manager = new UserManager({
+    authority: oidc.issuer,
+    client_id: oidc.clientId,
+    redirect_uri: `${window.location.origin}/login`,
+    response_type: "code",
+    scope: "openid profile email",
+    userStore: new WebStorageStateStore({ store: window.localStorage }),
+  });
+  return manager;
+}
+
+/** Kick off the redirect sign-in flow. */
+export async function signIn(): Promise<void> {
+  const oidc = appConfig.auth.oidc;
+  if (!oidc) throw new Error("auth.oidc is not configured in guuey.app.json");
+  await requireManager(oidc).signinRedirect();
+}
+
+/** Complete the flow when the IdP redirected back to /login?code=… */
+export async function completeSignIn(): Promise<User> {
+  const oidc = appConfig.auth.oidc;
+  if (!oidc) throw new Error("auth.oidc is not configured in guuey.app.json");
+  return requireManager(oidc).signinCallback() as Promise<User>;
+}
+
+export function isSigninCallback(): boolean {
+  const q = new URLSearchParams(window.location.search);
+  return q.has("code") && q.has("state");
+}
+
+export async function currentUser(): Promise<User | null> {
+  const oidc = appConfig.auth.oidc;
+  if (!oidc) return null;
+  const user = await requireManager(oidc).getUser();
+  return user && !user.expired ? user : null;
+}
+
+/**
+ * `getAccessToken` for `<GuueyChat>`: the current stored ID token, or null
+ * when signed out / expired (the chat surfaces it as needs-sign-in; they
+ * never silently fall back to guest — one identity mode per surface).
+ * There is NO silent renew here — when the session expires the user signs
+ * in again via /login. Wiring `automaticSilentRenew` (plus a silent
+ * redirect page) is the documented upgrade if your IdP supports it.
+ */
+export async function getBearerToken(): Promise<string | null> {
+  const user = await currentUser();
+  return user?.id_token ?? null;
+}
+
+export async function signOutOidc(): Promise<void> {
+  const oidc = appConfig.auth.oidc;
+  if (!oidc || !manager) return;
+  await manager.removeUser();
+}

package/dist/templates/base/claude-agent-sdk/web/src/lib/status.ts

@@ -0,0 +1,45 @@
+/**
+ * Live-ness probe for the Home page.
+ *
+ * Probes the agent's invoke route with a CORS preflight-shaped OPTIONS —
+ * the ONE route both servers answer cross-origin: the pod's CORS covers
+ * `/agent/invoke` for the app's allowed domains, and `guuey dev --serve`
+ * answers OPTIONS 204 on it too. (A bare `/healthz` GET carries no CORS
+ * headers on either server, so it is useless from a browser.) The
+ * platform's richer status API is credentialed and guuey-origin-CORS'd, so
+ * the CLI is the tool for detail: `pnpm status` runs `guuey apps get` +
+ * `guuey agent status`.
+ */
+import { agentEndpointUrl, isLinked } from "../config";
+
+export type AgentProbe =
+  | { state: "checking" }
+  | { state: "reachable" }
+  | {
+      /**
+       * Calm, honest failure: a fresh clone before `bootstrap --link` (or a
+       * dev session without `pnpm dev` running) is ALWAYS in this state —
+       * it is a setup stage, not an error.
+       */
+      state: "unreachable";
+      hint: string;
+    };
+
+export async function probeAgent(): Promise<AgentProbe> {
+  const base = agentEndpointUrl().replace(/\/+$/, "");
+  try {
+    const res = await fetch(`${base}/agent/invoke`, {
+      method: "OPTIONS",
+      signal: AbortSignal.timeout(5000),
+    });
+    if (res.ok) return { state: "reachable" };
+    return { state: "unreachable", hint: `agent answered ${res.status}` };
+  } catch {
+    return {
+      state: "unreachable",
+      hint: isLinked
+        ? "agent unreachable from this origin — check the app's Allowed Domains include this site, and that a deployment is live (pnpm status)"
+        : "local dev router not running — start it with `pnpm dev` (or bind a deployed app with `pnpm bootstrap -- --link`)",
+    };
+  }
+}

package/dist/templates/base/claude-agent-sdk/web/src/lib/widget.ts

@@ -0,0 +1,96 @@
+/**
+ * Host-page loader for the guuey widget (distribution way #1).
+ *
+ * The queue shim + single-init + idempotent script tag pattern — safe under
+ * React strict-mode double effects and route remounts. The widget only
+ * works against a DEPLOYED app (it loads from the environment's widget
+ * origin and frames the app's hosted chat), so callers gate on
+ * `appConfig.link`.
+ */
+import { appConfig } from "../config";
+
+interface GuueyGlobal {
+  (...args: unknown[]): void;
+  q?: unknown[][];
+  loaded?: boolean;
+}
+
+declare global {
+  interface Window {
+    guuey?: GuueyGlobal;
+  }
+}
+
+const SCRIPT_ID = "guuey-widget-v1";
+let initDispatched = false;
+
+function ensureGlobal(): GuueyGlobal {
+  if (!window.guuey) {
+    const shim: GuueyGlobal = function (...args: unknown[]) {
+      (shim.q = shim.q ?? []).push(args);
+    };
+    window.guuey = shim;
+  }
+  return window.guuey;
+}
+
+export type WidgetOutcome = "live" | "offline";
+
+/**
+ * Mount the widget launcher once: dispatches `guuey("init", …)` on first
+ * call and injects `<widget origin>/v1.js` if it is not already on the
+ * page. Subsequent calls are no-ops. Returns false when the app is not
+ * linked yet (nothing to embed).
+ */
+export function mountWidget(onOutcome?: (o: WidgetOutcome) => void): boolean {
+  const link = appConfig.link;
+  if (!link) return false;
+
+  const guuey = ensureGlobal();
+  if (!initDispatched) {
+    initDispatched = true;
+    guuey("init", {
+      app: link.appId,
+      launcher: `Ask ${appConfig.brand.name}`,
+      color: appConfig.theme.accent,
+      theme: appConfig.theme.mode,
+    });
+  }
+
+  if (!document.getElementById(SCRIPT_ID)) {
+    const script = document.createElement("script");
+    script.id = SCRIPT_ID;
+    script.src = `${link.widgetOrigin}/v1.js`;
+    script.async = true;
+    script.addEventListener("load", () => onOutcome?.("live"));
+    script.addEventListener("error", () => onOutcome?.("offline"));
+    document.head.appendChild(script);
+  } else {
+    onOutcome?.("live");
+  }
+  return true;
+}
+
+/**
+ * A value embedded inside an inline <script> on the customer's page: JSON
+ * string escaping, plus a `<` rewrite so a pathological brand name cannot
+ * smuggle `</script>` and terminate the element (the same rule the widget's
+ * own snippet generator applies).
+ */
+function jsString(value: string): string {
+  return JSON.stringify(value).replaceAll("<", "\\u003c");
+}
+
+/** The copy-paste embed snippet with this app's real values, for the Home guide. */
+export function widgetSnippet(): string | null {
+  const link = appConfig.link;
+  if (!link) return null;
+  return [
+    "<!-- guuey widget. Add this site to the app's allowed domains or the embed is refused. -->",
+    "<script>",
+    "  window.guuey = window.guuey || function(){(guuey.q=guuey.q||[]).push(arguments)};",
+    `  guuey("init", { app: ${jsString(link.appId)}, launcher: ${jsString(`Ask ${appConfig.brand.name}`)} });`,
+    "</script>",
+    `<script src="${link.widgetOrigin}/v1.js" async></script>`,
+  ].join("\n");
+}