@schlessera/brain-ui-react 0.14.0 → 0.15.0

package/src/components/images/mask-editor.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Eraser, RotateCcw, X } from "lucide-react";
 
-import { API_BASE } from "../../lib/backend.js";
+import { apiBase } from "../../lib/backend.js";
 import { useMaskStore } from "../../stores/mask-store.js";
 
 /**
@@ -43,7 +43,7 @@ export function MaskEditor({
   const [error, setError] = useState<string | null>(null);
 
   const rawUrl = request
-    ? `${API_BASE}/files/content?path=${encodeURIComponent(request.imagePath)}&raw=1`
+    ? `${apiBase()}/files/content?path=${encodeURIComponent(request.imagePath)}&raw=1`
     : null;
 
   // Reset per request: a second mask on a different image must not inherit the

package/src/config.ts

@@ -1,8 +1,21 @@
 /**
- * Deployment-tunable branding/copy. A module-level singleton, matching the
- * renderer/ASR registries: the shell calls `configureBrainUi()` once at boot
- * (before mounting), components read `uiConfig` at render time. Runtime
- * plugin-style reconfiguration is deliberately unsupported.
+ * The package's single configuration chokepoint.
+ *
+ * `ui-server` resolves its configuration once, at the edge, in `createApp()`,
+ * and nothing deeper in that package touches the ambient environment. This is
+ * the browser-side mirror of that rule: the deployment shell calls
+ * `configureBrainUi()` once at boot, before the first render, and every module
+ * below reads the resolved values instead of reaching for build-tool globals.
+ *
+ * The rule exists because a library that reads `import.meta.env` pins its
+ * consumers to one bundler. `VITE_BACKEND_URL` used to be read here at module
+ * load, so a webpack or Next.js consumer had no way to point the client at a
+ * split-topology backend at all, and no way to discover that from the types.
+ * `scripts/check-env-access.ts` now refuses `import.meta.env` anywhere in a
+ * package's `src`, so the loophole cannot reopen.
+ *
+ * Values are a module-level singleton, matching the renderer/ASR registries.
+ * Runtime plugin-style reconfiguration is deliberately unsupported.
  */
 export interface BrainUiConfig {
   /** Product name shown on the login screen and connection status. */
@@ -13,6 +26,24 @@ export interface BrainUiConfig {
   shareTitle: string;
   /** Composer placeholder. */
   composerPlaceholder: string;
+  /**
+   * Origin of the API/WebSocket backend, for a SPLIT topology (client and
+   * backend on different origins, e.g. a public frontend reaching its backend
+   * over a VPN). Empty — the default — means SAME-ORIGIN: API calls go to
+   * `/api` and the WebSocket derives its host from `window.location`.
+   *
+   * The shell resolves this however it likes (a Vite `VITE_*` define, a
+   * `<meta>` tag, a runtime fetch) and passes the result in. A trailing slash
+   * is stripped.
+   */
+  backendUrl: string;
+  /**
+   * Install the `window.__chatStore` / `window.__graphStore` debug handles,
+   * which let browser automation inject fixture messages without a live agent
+   * session. The shell decides what "development" means — this package must
+   * not infer it from a bundler's DEV flag.
+   */
+  devTools: boolean;
 }
 
 export const uiConfig: BrainUiConfig = {
@@ -20,8 +51,36 @@ export const uiConfig: BrainUiConfig = {
   assistantName: "Brain",
   shareTitle: "Shared from Brain",
   composerPlaceholder: "Ask your brain anything...",
+  backendUrl: "",
+  devTools: false,
 };
 
+/**
+ * Dev-handle installers, registered at module scope by the stores that own a
+ * handle. They cannot read `uiConfig.devTools` themselves: ES imports are
+ * hoisted, so a store's module body runs BEFORE the shell's
+ * `configureBrainUi()` call. Registering instead of reading lets the flag
+ * arrive late and still take effect.
+ */
+const devHandleInstallers: Array<() => void> = [];
+let devHandlesInstalled = false;
+
+function installDevHandles(): void {
+  if (devHandlesInstalled) return;
+  devHandlesInstalled = true;
+  for (const install of devHandleInstallers) install();
+}
+
+/** Register a debug handle to install if (and when) `devTools` is turned on. */
+export function registerDevHandle(install: () => void): void {
+  devHandleInstallers.push(install);
+  if (uiConfig.devTools) install();
+}
+
 export function configureBrainUi(overrides: Partial<BrainUiConfig>): void {
   Object.assign(uiConfig, overrides);
+  if (typeof overrides.backendUrl === "string") {
+    uiConfig.backendUrl = overrides.backendUrl.replace(/\/$/, "");
+  }
+  if (uiConfig.devTools) installDevHandles();
 }

package/src/index.ts

@@ -72,4 +72,4 @@ export { ShareIntake } from "./components/chat/share-card.js";
 
 // API surface (typed REST client + backend URL helpers).
 export { api } from "./lib/api-client.js";
-export { API_BASE, getWsUrl, getBackendUrl } from "./lib/backend.js";
+export { apiBase, getWsUrl, getBackendUrl } from "./lib/backend.js";

package/src/lib/api-client.ts

@@ -1,4 +1,4 @@
-import { API_BASE } from "./backend.js";
+import { apiBase } from "./backend.js";
 import type {
   VoiceKeytermsResponse,
   VoiceTokenResponse,
@@ -46,7 +46,7 @@ export interface BackendInfo {
 }
 
 async function fetchJson<T>(path: string, init?: RequestInit): Promise<T> {
-  const res = await fetch(`${API_BASE}${path}`, {
+  const res = await fetch(`${apiBase()}${path}`, {
     ...init,
     headers: {
       "Content-Type": "application/json",

package/src/lib/backend.ts

@@ -1,26 +1,27 @@
 /**
- * Backend URL configuration.
+ * Where the API and WebSocket live.
  *
  * Default topology is SAME-ORIGIN: the server serves the built client and the
  * API/WS from one origin, so API calls go to "/api" and the WebSocket derives
- * its host from window.location. No build-time configuration is needed.
+ * its host from window.location. Nothing needs configuring.
  *
- * VITE_BACKEND_URL is optional advanced config for a SPLIT topology (client and
- * backend on different origins, e.g. a public frontend with the backend reached
- * over a VPN). When set at build time, API and WS calls target that origin.
- * The read is defensive — outside a Vite build (bun test, Node import of the
- * dist) `import.meta.env` does not exist.
+ * A SPLIT topology (client and backend on different origins) sets
+ * `backendUrl` through `configureBrainUi()`. These are functions rather than
+ * module constants on purpose: a constant would freeze the value at import
+ * time, and ES imports are hoisted, so it would always capture the default
+ * instead of what the shell configured.
  */
-const viteEnv = (import.meta as { env?: Record<string, string | undefined> }).env;
-const BACKEND_URL = viteEnv?.VITE_BACKEND_URL?.replace(/\/$/, "") ?? "";
+import { uiConfig } from "../config.js";
 
-/** Base URL for API calls. Empty BACKEND_URL = same-origin "/api". */
-export const API_BASE = `${BACKEND_URL}/api`;
+/** Base URL for API calls. Empty backendUrl = same-origin "/api". */
+export function apiBase(): string {
+  return `${uiConfig.backendUrl}/api`;
+}
 
-/** WebSocket URL. Derives wss/ws + host from BACKEND_URL, else same-origin. */
+/** WebSocket URL. Derives wss/ws + host from backendUrl, else same-origin. */
 export function getWsUrl(): string {
-  if (BACKEND_URL) {
-    const url = new URL("/ws", BACKEND_URL);
+  if (uiConfig.backendUrl) {
+    const url = new URL("/ws", uiConfig.backendUrl);
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
     return url.toString();
   }
@@ -31,5 +32,5 @@ export function getWsUrl(): string {
 
 /** Base URL for direct fetch calls (streaming endpoints). */
 export function getBackendUrl(path: string): string {
-  return `${BACKEND_URL}${path}`;
+  return `${uiConfig.backendUrl}${path}`;
 }

package/src/lib/share-intake.ts

@@ -4,7 +4,7 @@ import {
   type ShareIntakeResult,
 } from "@schlessera/brain-ui-sdk/protocol";
 import type { StoredShare } from "@schlessera/brain-ui-sdk/share-target";
-import { API_BASE } from "./backend.js";
+import { apiBase } from "./backend.js";
 import {
   fileToAttachment,
   validateAttachments,
@@ -85,7 +85,7 @@ export async function uploadShare(
 
   let response: Response;
   try {
-    response = await fetchImpl(`${API_BASE}/share`, {
+    response = await fetchImpl(`${apiBase()}/share`, {
       method: "POST",
       body: form,
     });

package/src/lib/share.ts

@@ -1,4 +1,4 @@
-import { API_BASE } from "./backend.js";
+import { apiBase } from "./backend.js";
 import type { RenderRequest } from "@schlessera/brain-ui-sdk/protocol";
 
 export type ShareKind = "file" | "text" | "richtext";
@@ -125,7 +125,7 @@ export async function renderToFile(
   req: RenderRequest,
   filename: string
 ): Promise<File> {
-  const res = await fetch(`${API_BASE}/render`, {
+  const res = await fetch(`${apiBase()}/render`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(req),

package/src/stores/chat-store.ts

@@ -6,6 +6,7 @@ import type {
   AskUserAnnotation,
 } from "@schlessera/brain-ui-sdk/protocol";
 import { useProviderStore } from "./provider-store.js";
+import { registerDevHandle } from "../config.js";
 
 export type { MessagePart };
 
@@ -631,10 +632,12 @@ export const useChatStore = create<ChatState>((set, get) => {
 });
 
 // Dev-only handle so browser automation / manual debugging can inject
-// fixture messages without a live Claude session. The env read is defensive:
-// outside a Vite build `import.meta.env` does not exist.
-const devEnv = (import.meta as { env?: Record<string, unknown> }).env;
-if (typeof window !== "undefined" && devEnv?.DEV) {
+// fixture messages without a live Claude session. Registered rather than
+// installed: whether this is a development build is the shell's call
+// (`configureBrainUi({ devTools: true })`), not something a component library
+// infers from its bundler.
+registerDevHandle(() => {
+  if (typeof window === "undefined") return;
   (window as unknown as { __chatStore?: typeof useChatStore }).__chatStore =
     useChatStore;
-}
+});

package/src/stores/file-store.ts

@@ -6,7 +6,7 @@ import type {
   WikilinkMapResponse,
 } from "@schlessera/brain-ui-sdk/protocol";
 import { FILE_SIZE_CAP_BYTES } from "@schlessera/brain-ui-sdk/protocol";
-import { API_BASE } from "../lib/backend.js";
+import { apiBase } from "../lib/backend.js";
 import { isMermaidPath } from "../lib/mermaid.js";
 
 export type ViewMode = "preview" | "raw";
@@ -76,7 +76,7 @@ interface FileState {
 }
 
 async function fetchTree(path: string): Promise<FileEntry[]> {
-  const url = `${API_BASE}/files/tree${path ? `?path=${encodeURIComponent(path)}` : ""}`;
+  const url = `${apiBase()}/files/tree${path ? `?path=${encodeURIComponent(path)}` : ""}`;
   const res = await fetch(url);
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
@@ -87,7 +87,7 @@ async function fetchTree(path: string): Promise<FileEntry[]> {
 }
 
 async function fetchContent(path: string): Promise<FileContentResponse> {
-  const res = await fetch(`${API_BASE}/files/content?path=${encodeURIComponent(path)}`);
+  const res = await fetch(`${apiBase()}/files/content?path=${encodeURIComponent(path)}`);
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
     const err = new Error(body.error || `HTTP ${res.status}`);
@@ -99,7 +99,7 @@ async function fetchContent(path: string): Promise<FileContentResponse> {
 }
 
 async function fetchResolve(path: string): Promise<FileResolveResponse> {
-  const res = await fetch(`${API_BASE}/files/resolve?path=${encodeURIComponent(path)}`);
+  const res = await fetch(`${apiBase()}/files/resolve?path=${encodeURIComponent(path)}`);
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
     throw new Error(body.error || `HTTP ${res.status}`);
@@ -108,7 +108,7 @@ async function fetchResolve(path: string): Promise<FileResolveResponse> {
 }
 
 async function fetchWikilinks(): Promise<WikilinkMapResponse> {
-  const res = await fetch(`${API_BASE}/files/wikilinks`);
+  const res = await fetch(`${apiBase()}/files/wikilinks`);
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
     throw new Error(body.error || `HTTP ${res.status}`);

package/src/stores/graph-store.ts

@@ -4,7 +4,8 @@ import type {
   GraphSubgraphResponse,
   GraphMaintenanceResponse,
 } from "@schlessera/brain-ui-sdk/protocol";
-import { API_BASE } from "../lib/backend.js";
+import { apiBase } from "../lib/backend.js";
+import { registerDevHandle } from "../config.js";
 import { buildQuery, mergeSubgraphs } from "../components/graph/lib/graph-helpers.js";
 
 export type GraphMode = "clusters" | "discovery" | "local" | "maintenance";
@@ -135,7 +136,7 @@ function cachePut(key: string, value: GraphSubgraphResponse | GraphMaintenanceRe
 }
 
 async function fetchGraphJson<T>(pathAndQuery: string): Promise<T> {
-  const res = await fetch(`${API_BASE}/graph${pathAndQuery}`);
+  const res = await fetch(`${apiBase()}/graph${pathAndQuery}`);
   if (!res.ok) {
     const body = await res.json().catch(() => ({}) as Record<string, unknown>);
     const err = new Error(
@@ -336,10 +337,9 @@ export const useGraphStore = create<GraphState>((set, get) => ({
 }));
 
 // Dev-only handle for exercising the view with injected fixtures (the
-// window.__chatStore precedent). The env read is defensive: outside a Vite
-// build `import.meta.env` does not exist.
-const devEnv = (import.meta as { env?: Record<string, unknown> }).env;
-if (typeof window !== "undefined" && devEnv?.DEV) {
+// window.__chatStore precedent), gated on the shell's `devTools` flag.
+registerDevHandle(() => {
+  if (typeof window === "undefined") return;
   (window as unknown as { __graphStore?: typeof useGraphStore }).__graphStore =
     useGraphStore;
-}
+});