@backmatter/studio 0.0.1

package/src/site.tsx

@@ -0,0 +1,230 @@
+// packages/studio/src/site.tsx
+// Root of a Studio mounted on a customer site. Same pages as the dashboard,
+// one workspace, authenticated by the site session through the host's
+// same-origin proxy. No login here: without a session the browser goes
+// top-level to the dashboard `enter` route and comes back with a ticket.
+import { useEffect, useState, type ReactNode } from "react";
+import * as stylex from "@stylexjs/stylex";
+import { BrowserRouter, Navigate, Route, Routes, useLocation } from "react-router";
+import { studioEnterUrl } from "@backmatter/core";
+import { fetchMe, fetchWorkspace } from "./api";
+import { Shell } from "./components/Shell";
+import { StudioDefinitionProvider, type StudioDefinition } from "./define-studio";
+import { AccentOverride } from "./theme/AccentOverride";
+import { EmbedChatPage } from "./pages/EmbedChatPage";
+import { EmbedPublishPage } from "./pages/EmbedPublishPage";
+import { LegacyWorkspaceRedirect } from "./pages/LegacyWorkspaceRedirect";
+import { BootstrapSplash } from "./replica/BootstrapSplash";
+import { ReplicaGate, ReplicaProvider } from "./replica/ReplicaProvider";
+import { replicaStore } from "./replica/instance";
+import { configureStudio, studioConfig, type StudioConfig } from "./studio-config";
+import { colors, space } from "./styles/tokens.stylex";
+import { ThemeProvider } from "./theme/ThemeProvider";
+import { Text } from "./ui/Text";
+import { workspaceRoutes } from "./WorkspaceRoutes";
+
+export type SiteStudioProps = {
+  workspaceId: string;
+  /** Route the host mounted the Studio on. Default `/backmatter`. */
+  basePath?: string;
+  /** Dashboard that holds the login. Default `https://dash.backmatter.app`. */
+  dashboardUrl?: string;
+  /** Same-origin proxy the host exposes. Default `/api/backmatter/cms`. */
+  proxyPath?: string;
+  /** The CMS API origin, shown in Content API URLs. Requests still go through the proxy. */
+  apiUrl?: string;
+  /** Package version for the API handshake. */
+  version?: string;
+  /** Where the host's preview entry route lives; POST clears the site session. */
+  previewEntryPath?: string;
+  /** Site customization from `defineStudio` in `backmatter.studio.tsx`. */
+  studio?: StudioDefinition;
+};
+
+const ENTER_GUARD_KEY = "backmatter:enter-at";
+const ENTER_LOOP_MS = 10_000;
+
+/**
+ * Send the browser to the dashboard to mint a session for this site. Refuses
+ * to bounce twice within a few seconds so a broken proxy shows an error
+ * instead of a redirect loop.
+ */
+export function bounceToEnter(workspaceId: string, dashboardUrl: string): boolean {
+  if (typeof window === "undefined") return false;
+  const last = Number(window.sessionStorage.getItem(ENTER_GUARD_KEY) ?? 0);
+  if (Date.now() - last < ENTER_LOOP_MS) return false;
+  window.sessionStorage.setItem(ENTER_GUARD_KEY, String(Date.now()));
+  window.location.assign(
+    studioEnterUrl(dashboardUrl, { workspaceId, returnUrl: window.location.href }),
+  );
+  return true;
+}
+
+export function configureSiteStudio(props: SiteStudioProps): StudioConfig {
+  const dashboardUrl = props.dashboardUrl ?? "https://dash.backmatter.app";
+  configureStudio({
+    baseUrl: props.proxyPath ?? "/api/backmatter/cms",
+    publicApiUrl: props.apiUrl,
+    credentials: "same-origin",
+    dev: false,
+    version: props.version,
+    dashboardUrl,
+    onUnauthorized: ({ status }) => {
+      if (status === 401) bounceToEnter(props.workspaceId, dashboardUrl);
+    },
+  });
+  return studioConfig();
+}
+
+export function SiteStudio(props: SiteStudioProps) {
+  const basePath = props.basePath ?? "/backmatter";
+  // Configure synchronously on first render so child effects already see it.
+  const [configured] = useState(() => configureSiteStudio(props));
+  void configured;
+  return (
+    <StudioDefinitionProvider definition={props.studio}>
+      <ThemeProvider>
+        <AccentOverride />
+        <BrowserRouter basename={basePath}>
+          <SiteInner {...props} />
+        </BrowserRouter>
+      </ThemeProvider>
+    </StudioDefinitionProvider>
+  );
+}
+
+type Session =
+  | "loading"
+  | { user: { id: string; email: string }; slug: string }
+  | "unauthorized"
+  | "outdated";
+
+function SiteInner(props: SiteStudioProps) {
+  const location = useLocation();
+  const dashboardUrl = props.dashboardUrl ?? "https://dash.backmatter.app";
+  const [session, setSession] = useState<Session>("loading");
+
+  useEffect(() => {
+    let cancelled = false;
+    const previous = studioConfig().onUnauthorized;
+    configureStudio({
+      ...studioConfig(),
+      onUnauthorized: (info) => {
+        if (info.status === 426) setSession("outdated");
+        else previous?.(info);
+      },
+    });
+    void fetchMe()
+      .then(async (me) => {
+        if (cancelled) return;
+        if (!me?.user) {
+          if (!bounceToEnter(props.workspaceId, dashboardUrl)) setSession("unauthorized");
+          return;
+        }
+        // The Studio routes by slug; the site only knows its workspace id.
+        const { workspace } = await fetchWorkspace(props.workspaceId);
+        if (cancelled) return;
+        setSession({ user: { id: me.user.id, email: me.user.email }, slug: workspace.slug });
+      })
+      .catch(() => {
+        if (cancelled) return;
+        setSession((s) => (s === "outdated" ? s : "unauthorized"));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [props.workspaceId, dashboardUrl]);
+
+  if (session === "loading") return <BootstrapSplash />;
+  if (session === "outdated") {
+    return (
+      <Notice title="This site's editor is out of date">
+        Update <code>@backmatter/studio</code> and <code>@backmatter/next</code> on the site, then
+        reload.
+      </Notice>
+    );
+  }
+  if (session === "unauthorized") {
+    return (
+      <Notice title="Could not start editing">
+        The site did not receive a session from the dashboard. Check that this site's origin is
+        listed in the workspace settings and that <code>/api/backmatter</code> routes are
+        deployed.
+      </Notice>
+    );
+  }
+
+  const embedChat = location.pathname.match(/^\/embed\/chat\/([^/]+)\/?$/);
+  if (embedChat?.[1]) {
+    return <EmbedChatPage workspaceId={decodeURIComponent(embedChat[1])} />;
+  }
+  const embedPublish = location.pathname.match(/^\/embed\/publish\/([^/]+)\/?$/);
+  if (embedPublish?.[1]) {
+    return <EmbedPublishPage workspaceId={decodeURIComponent(embedPublish[1])} />;
+  }
+
+  return (
+    <ReplicaProvider user={session.user}>
+      <ReplicaGate>
+        <Shell
+          userId={session.user.id}
+          email={session.user.email}
+          onLogout={() => {
+            void exitSite(props.previewEntryPath ?? "/api/backmatter/preview", dashboardUrl);
+          }}
+        >
+          <Routes>
+            <Route path="/" element={<Navigate to={`/${session.slug}`} replace />} />
+            {/* The bar links by workspace id; this rewrites to the slug route. */}
+            <Route path="/workspaces/:workspaceId/*" element={<LegacyWorkspaceRedirect />} />
+            {workspaceRoutes()}
+            <Route path="*" element={<Navigate to="/" replace />} />
+          </Routes>
+        </Shell>
+      </ReplicaGate>
+    </ReplicaProvider>
+  );
+}
+
+/** Clear the site session and draft mode, then leave for the dashboard. */
+async function exitSite(previewEntryPath: string, dashboardUrl: string) {
+  try {
+    await fetch(previewEntryPath, { method: "POST", credentials: "same-origin" });
+  } catch {
+    // The cookie expires on its own; still leave.
+  }
+  void replicaStore.wipe();
+  window.location.assign(dashboardUrl);
+}
+
+function Notice({ title, children }: { title: string; children: ReactNode }) {
+  return (
+    <div {...stylex.props(styles.page)}>
+      <div {...stylex.props(styles.card)}>
+        <Text size="lg" weight="medium">
+          {title}
+        </Text>
+        <Text tone="muted">{children}</Text>
+      </div>
+    </div>
+  );
+}
+
+const styles = stylex.create({
+  page: {
+    minHeight: "100dvh",
+    display: "grid",
+    placeItems: "center",
+    padding: space.xl,
+  },
+  card: {
+    display: "flex",
+    flexDirection: "column",
+    gap: space.md,
+    maxWidth: 440,
+    padding: space.xl,
+    borderRadius: 12,
+    backgroundColor: colors.bgPanel,
+    border: `1px solid ${colors.border}`,
+  },
+});

package/src/studio-config.ts

@@ -0,0 +1,81 @@
+// packages/studio/src/studio-config.ts
+// Where the Studio sends requests and how it authenticates. Set once by the
+// host before rendering. The dashboard points at the CMS API with its cookie;
+// a customer site points at its own same-origin proxy with the site session.
+
+export type StudioCredentials = "include" | "same-origin";
+
+export type StudioConfig = {
+  /** Origin and base path for every API request. No trailing slash. */
+  baseUrl: string;
+  /** `include` for the cross-origin dashboard cookie, `same-origin` for the host proxy. */
+  credentials: StudioCredentials;
+  /** Dev-only surfaces (UI kit, palette entries). */
+  dev: boolean;
+  /**
+   * The CMS API origin as the outside world reaches it, for URLs the Studio
+   * shows rather than fetches (the Content API popover). A site Studio fetches
+   * through a relative proxy, so its host passes the real origin here.
+   * Defaults to `baseUrl`.
+   */
+  publicApiUrl?: string;
+  /** Package version, sent as `X-Backmatter-Studio` so the API can refuse an old Studio. */
+  version?: string;
+  /**
+   * Where the host can log in. A site Studio without a session bounces here.
+   * The dashboard itself leaves this unset.
+   */
+  dashboardUrl?: string;
+  /**
+   * Called when the API answers 401 or 426. A site Studio redirects to the
+   * dashboard enter route; the dashboard shows its login page instead.
+   */
+  onUnauthorized?: (info: { status: 401 | 426; code?: string }) => void;
+};
+
+const DEFAULT_CONFIG: StudioConfig = {
+  baseUrl: "http://localhost:3001",
+  credentials: "include",
+  dev: false,
+};
+
+let current: StudioConfig = DEFAULT_CONFIG;
+
+export function configureStudio(config: Partial<StudioConfig> & Pick<StudioConfig, "baseUrl">) {
+  current = {
+    ...DEFAULT_CONFIG,
+    ...config,
+    baseUrl: config.baseUrl.replace(/\/+$/, ""),
+    publicApiUrl: (config.publicApiUrl ?? config.baseUrl).replace(/\/+$/, ""),
+  };
+}
+
+export function studioConfig(): StudioConfig {
+  return current;
+}
+
+export function apiUrl(path = ""): string {
+  return `${current.baseUrl}${path}`;
+}
+
+/** The API origin to show users; see `StudioConfig.publicApiUrl`. */
+export function publicApiUrl(): string {
+  return current.publicApiUrl ?? current.baseUrl;
+}
+
+export function apiCredentials(): StudioCredentials {
+  return current.credentials;
+}
+
+/** Headers every API request carries. */
+export function apiHeaders(): Record<string, string> {
+  return current.version ? { "X-Backmatter-Studio": current.version } : {};
+}
+
+export function isStudioDev(): boolean {
+  return current.dev;
+}
+
+export function reportUnauthorized(status: 401 | 426, code?: string) {
+  current.onUnauthorized?.({ status, code });
+}

package/src/styles/themes.ts

@@ -0,0 +1,49 @@
+// packages/studio/src/styles/themes.ts
+import * as stylex from "@stylexjs/stylex";
+import { colors } from "./tokens.stylex";
+
+export const lightTheme = stylex.createTheme(colors, {
+  bgApp: "#f7f7f8",
+  bgSidebar: "#ececee",
+  bgPanel: "#f4f4f5",
+  bgPanelInset: "#ececef",
+  bgSurface: "#ffffff",
+  bgHover: "rgba(24, 24, 27, 0.05)",
+  bgActive: "rgba(24, 24, 27, 0.08)",
+  bgInput: "#ffffff",
+  bgStatus: "#f4f4f5",
+  text: "#18181b",
+  textMuted: "#71717a",
+  textInverse: "#fafafa",
+  border: "#e4e4e7",
+  accent: "#18181b",
+  accentHover: "#3f3f46",
+  accentMuted: "#f4f4f5",
+  danger: "#dc2626",
+  success: "#059669",
+  overlay: "rgba(24, 24, 27, 0.45)",
+  focus: "#18181b",
+});
+
+export const darkTheme = stylex.createTheme(colors, {
+  bgApp: "#18181b",
+  bgSidebar: "#111113",
+  bgPanel: "#131316",
+  bgPanelInset: "#0f0f12",
+  bgSurface: "#1f1f23",
+  bgHover: "rgba(255, 255, 255, 0.06)",
+  bgActive: "rgba(255, 255, 255, 0.1)",
+  bgInput: "#18181b",
+  bgStatus: "#111113",
+  text: "#e4e4e7",
+  textMuted: "#a1a1aa",
+  textInverse: "#18181b",
+  border: "#27272a",
+  accent: "#fafafa",
+  accentHover: "#e4e4e7",
+  accentMuted: "rgba(255, 255, 255, 0.1)",
+  danger: "#f87171",
+  success: "#34d399",
+  overlay: "rgba(0, 0, 0, 0.6)",
+  focus: "#fafafa",
+});

package/src/styles/tokens.stylex.ts

@@ -0,0 +1,58 @@
+// packages/studio/src/styles/tokens.stylex.ts
+import * as stylex from "@stylexjs/stylex";
+
+export const colors = stylex.defineVars({
+  bgApp: "#f7f7f8",
+  bgSidebar: "#ececee",
+  bgPanel: "#f4f4f5",
+  bgPanelInset: "#ececef",
+  bgSurface: "#ffffff",
+  bgHover: "rgba(24, 24, 27, 0.05)",
+  bgActive: "rgba(24, 24, 27, 0.08)",
+  bgInput: "#ffffff",
+  bgStatus: "#f4f4f5",
+  text: "#18181b",
+  textMuted: "#71717a",
+  textInverse: "#fafafa",
+  border: "#e4e4e7",
+  accent: "#18181b",
+  accentHover: "#3f3f46",
+  accentMuted: "#f4f4f5",
+  danger: "#dc2626",
+  success: "#059669",
+  overlay: "rgba(24, 24, 27, 0.45)",
+  focus: "#18181b",
+});
+
+export const space = stylex.defineVars({
+  xs: "4px",
+  sm: "6px",
+  md: "8px",
+  lg: "12px",
+  xl: "16px",
+  xxl: "24px",
+});
+
+export const radius = stylex.defineVars({
+  sm: "4px",
+  md: "6px",
+});
+
+export const type = stylex.defineVars({
+  sans: "Geist Sans, Inter, ui-sans-serif, system-ui, sans-serif",
+  mono: "Geist Mono, ui-monospace, SFMono-Regular, Menlo, monospace",
+  xs: "11px",
+  sm: "12px",
+  md: "13px",
+  lg: "14px",
+  xl: "16px",
+  display: "20px",
+});
+
+export const z = stylex.defineVars({
+  dropdown: "20",
+  overlay: "40",
+  palette: "50",
+  popover: "60",
+  tooltip: "70",
+});

package/src/styles.ts

@@ -0,0 +1,11 @@
+// packages/studio/src/styles.ts
+// Every stylesheet the Studio needs. Hosts import this once; the library build
+// emits it as a single CSS file next to the StyleX output.
+import "@fontsource/geist-sans/400.css";
+import "@fontsource/geist-sans/500.css";
+import "@fontsource/geist-sans/600.css";
+import "@fontsource/geist-mono/400.css";
+import "@prose-ui/style/prose-ui.css";
+import "@prose-ui/style/katex.css";
+import "react-medium-image-zoom/dist/styles.css";
+import "./index.css";

package/src/theme/AccentOverride.tsx

@@ -0,0 +1,29 @@
+// packages/studio/src/theme/AccentOverride.tsx
+// `defineStudio({ theme: { accent } })` recolors primary actions and focus
+// rings. StyleX tokens compile to CSS variables; an inline value on <html>
+// outranks the theme class that sets them.
+import { useLayoutEffect } from "react";
+import { colors } from "../styles/tokens.stylex";
+import { useStudioDefinition } from "../define-studio";
+
+/** `var(--x)` → `--x`, or null when the token is not a variable reference. */
+export function cssVarName(token: string): string | null {
+  const match = /^var\((--[^,)]+)/.exec(token);
+  return match?.[1] ?? null;
+}
+
+const ACCENT_TOKENS = [colors.accent, colors.accentHover, colors.focus] as unknown as string[];
+
+export function AccentOverride() {
+  const accent = useStudioDefinition().theme?.accent?.trim();
+  useLayoutEffect(() => {
+    if (!accent) return;
+    const root = document.documentElement;
+    const names = ACCENT_TOKENS.map(cssVarName).filter((n): n is string => Boolean(n));
+    for (const name of names) root.style.setProperty(name, accent);
+    return () => {
+      for (const name of names) root.style.removeProperty(name);
+    };
+  }, [accent]);
+  return null;
+}

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,130 @@
+// packages/studio/src/theme/ThemeProvider.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useState,
+} from "react";
+import * as stylex from "@stylexjs/stylex";
+import { colors, type } from "../styles/tokens.stylex";
+import { darkTheme, lightTheme } from "../styles/themes";
+import { applyThemeClass } from "./apply-theme-class";
+
+const STORAGE_KEY = "backmatter-theme";
+
+export type ThemePreference = "system" | "light" | "dark";
+export type ResolvedTheme = "light" | "dark";
+
+type ThemeContextValue = {
+  preference: ThemePreference;
+  resolved: ResolvedTheme;
+  setPreference: (preference: ThemePreference) => void;
+  cyclePreference: () => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function readPreference(): ThemePreference {
+  try {
+    const value = localStorage.getItem(STORAGE_KEY);
+    if (value === "light" || value === "dark" || value === "system") {
+      return value;
+    }
+  } catch {
+    // ignore
+  }
+  return "system";
+}
+
+function resolvePreference(preference: ThemePreference): ResolvedTheme {
+  if (preference === "light" || preference === "dark") return preference;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches
+    ? "dark"
+    : "light";
+}
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [preference, setPreferenceState] =
+    useState<ThemePreference>(readPreference);
+  const [resolved, setResolved] = useState<ResolvedTheme>(() =>
+    resolvePreference(readPreference()),
+  );
+
+  useEffect(() => {
+    function apply() {
+      const next = resolvePreference(preference);
+      setResolved(next);
+      document.documentElement.dataset.theme = next;
+      document.documentElement.style.colorScheme = next;
+      // Prose UI switches tokens from the `dark` / `light` class on <html>.
+      document.documentElement.classList.toggle("dark", next === "dark");
+      document.documentElement.classList.toggle("light", next === "light");
+    }
+    apply();
+    if (preference !== "system") return;
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    media.addEventListener("change", apply);
+    return () => media.removeEventListener("change", apply);
+  }, [preference]);
+
+  const theme = resolved === "dark" ? darkTheme : lightTheme;
+
+  // Base UI portals mount on document.body, outside the wrapper that holds the
+  // StyleX theme. Put the same theme class on <html> so menus/dialogs inherit it.
+  useLayoutEffect(() => {
+    return applyThemeClass(
+      document.documentElement,
+      stylex.props(theme).className,
+    );
+  }, [theme]);
+
+  const setPreference = useCallback((next: ThemePreference) => {
+    try {
+      localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+      // ignore
+    }
+    setPreferenceState(next);
+  }, []);
+
+  const cyclePreference = useCallback(() => {
+    const order: ThemePreference[] = ["system", "light", "dark"];
+    const index = order.indexOf(preference);
+    setPreference(order[(index + 1) % order.length]!);
+  }, [preference, setPreference]);
+
+  const value = useMemo(
+    () => ({ preference, resolved, setPreference, cyclePreference }),
+    [preference, resolved, setPreference, cyclePreference],
+  );
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <div
+        {...stylex.props(theme, styles.root)}
+      >
+        {children}
+      </div>
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
+  return ctx;
+}
+
+const styles = stylex.create({
+  root: {
+    minHeight: "100dvh",
+    backgroundColor: colors.bgApp,
+    color: colors.text,
+    fontFamily: type.sans,
+    fontSize: type.md,
+    lineHeight: 1.45,
+  },
+});

package/src/theme/apply-theme-class.ts

@@ -0,0 +1,12 @@
+// packages/studio/src/theme/apply-theme-class.ts
+/** Puts StyleX theme classes on a root (usually <html>) so portaled UI inherits tokens. */
+export function applyThemeClass(
+  target: Element,
+  className: string | undefined,
+): () => void {
+  const tokens = className?.split(/\s+/).filter(Boolean) ?? [];
+  if (tokens.length > 0) target.classList.add(...tokens);
+  return () => {
+    if (tokens.length > 0) target.classList.remove(...tokens);
+  };
+}

package/src/ui/BackLink.tsx

@@ -0,0 +1,28 @@
+// packages/studio/src/ui/BackLink.tsx
+import { Link } from "react-router";
+import * as stylex from "@stylexjs/stylex";
+import { colors, space, type } from "../styles/tokens.stylex";
+
+export function BackLink({
+  to,
+  children,
+}: {
+  to: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <Link to={to} {...stylex.props(styles.link)}>
+      {children}
+    </Link>
+  );
+}
+
+const styles = stylex.create({
+  link: {
+    display: "inline-block",
+    marginBottom: space.sm,
+    fontSize: type.xs,
+    color: colors.textMuted,
+    textDecoration: "none",
+  },
+});