@backmatter/next 0.0.22 → 0.0.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
@@ -33,7 +33,8 @@
     "./cms-proxy": "./src/cms-proxy.ts",
     "./proxy": "./src/proxy.ts",
     "./middleware": "./src/middleware.ts",
-    "./page": "./src/page-render.ts"
+    "./page": "./src/page-render.ts",
+    "./studio": "./src/studio.tsx"
   },
   "files": [
     "src",
@@ -46,9 +47,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@backmatter/core": "^0.0.19",
+    "@backmatter/core": "^0.0.20",
     "@mdx-js/mdx": "^3.1.1",
-    "remark-gfm": "^4.0.1"
+    "remark-gfm": "^4.0.1",
+    "@backmatter/studio": "^0.0.1"
   },
   "peerDependencies": {
     "next": ">=16.3.0",
@@ -56,7 +58,9 @@
     "react-dom": ">=19"
   },
   "peerDependenciesMeta": {
-    "next": { "optional": true }
+    "next": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",

package/src/cms-proxy.ts

@@ -6,21 +6,41 @@ import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
 
 const DOC = "/workspaces/[^/]+/docs/[^/]+/[^/]+/[^/]+";
 
+const WS = "/workspaces/[^/]+";
+
+/**
+ * Everything the Studio does from a customer site. Admin surfaces that change
+ * the workspace itself (members, settings, GitHub binding, tokens) are absent
+ * on purpose: they stay on the dashboard.
+ */
 const ALLOWED: Array<{ method: string; pattern: RegExp }> = [
-  { method: "GET", pattern: /^\/workspaces\/[^/]+\/docs$/ },
+  { method: "GET", pattern: /^\/me$/ },
+  { method: "GET", pattern: /^\/workspaces$/ },
+  { method: "GET", pattern: new RegExp(`^${WS}$`) },
+  { method: "GET", pattern: new RegExp(`^${WS}/replica$`) },
+  { method: "GET", pattern: new RegExp(`^${WS}/schema$`) },
+  { method: "GET", pattern: new RegExp(`^${WS}/docs$`) },
   { method: "GET", pattern: new RegExp(`^${DOC}$`) },
   { method: "PUT", pattern: new RegExp(`^${DOC}$`) },
   { method: "DELETE", pattern: new RegExp(`^${DOC}$`) },
   { method: "DELETE", pattern: new RegExp(`^${DOC}/tree$`) },
   { method: "POST", pattern: new RegExp(`^${DOC}/resolve$`) },
-  { method: "GET", pattern: /^\/workspaces\/[^/]+\/git$/ },
-  { method: "POST", pattern: /^\/workspaces\/[^/]+\/git\/commit$/ },
-  { method: "POST", pattern: /^\/workspaces\/[^/]+\/preview-ticket$/ },
+  { method: "GET", pattern: new RegExp(`^${WS}/git$`) },
+  { method: "POST", pattern: new RegExp(`^${WS}/git/commit$`) },
+  { method: "POST", pattern: new RegExp(`^${WS}/git/checkout$`) },
+  { method: "POST", pattern: new RegExp(`^${WS}/git/branches$`) },
+  { method: "POST", pattern: new RegExp(`^${WS}/preview-ticket$`) },
   { method: "GET", pattern: /^\/preview\/workspaces\/[^/]+\/docs\/[^/]+\/[^/]+\/[^/]+\/stream$/ },
   { method: "GET", pattern: /^\/preview\/workspaces\/[^/]+\/tree\/stream$/ },
-  { method: "GET", pattern: /^\/workspaces\/[^/]+\/ai\/threads\/[^/]+$/ },
-  { method: "POST", pattern: /^\/workspaces\/[^/]+\/ai\/threads$/ },
-  { method: "POST", pattern: /^\/workspaces\/[^/]+\/ai\/threads\/[^/]+\/messages$/ },
+  { method: "GET", pattern: new RegExp(`^${WS}/ai/models$`) },
+  { method: "GET", pattern: new RegExp(`^${WS}/ai/threads$`) },
+  { method: "POST", pattern: new RegExp(`^${WS}/ai/threads$`) },
+  { method: "GET", pattern: new RegExp(`^${WS}/ai/threads/[^/]+$`) },
+  { method: "PATCH", pattern: new RegExp(`^${WS}/ai/threads/[^/]+$`) },
+  { method: "DELETE", pattern: new RegExp(`^${WS}/ai/threads/[^/]+$`) },
+  { method: "POST", pattern: new RegExp(`^${WS}/ai/threads/[^/]+/messages$`) },
+  { method: "POST", pattern: new RegExp(`^${WS}/ai/threads/[^/]+/messages/[^/]+/changes/(keep-all|undo-all)$`) },
+  { method: "POST", pattern: new RegExp(`^${WS}/ai/changes/[^/]+/(keep|undo)$`) },
   { method: "GET", pattern: /^\/preview\/session$/ },
   { method: "POST", pattern: /^\/preview\/session\/renew$/ },
 ];
@@ -35,6 +55,40 @@ export function workspaceIdFromProxyPath(path: string): string | null {
   return match?.[1] ?? null;
 }
 
+const WORKSPACE_ID = /^ws_/;
+
+/**
+ * The Studio addresses a workspace by slug, as the dashboard does. The proxy
+ * cannot verify a slug, so a slug segment is rewritten to the session's
+ * workspace id — the session is scoped to exactly one workspace anyway, and
+ * the API still checks the token against the workspace it resolves. A
+ * different workspace *id* is refused outright.
+ */
+export function resolveProxyPath(
+  path: string,
+  sessionWorkspaceId: string,
+): { ok: true; path: string } | { ok: false } {
+  const segment = workspaceIdFromProxyPath(path);
+  if (!segment || segment === sessionWorkspaceId) return { ok: true, path };
+  if (WORKSPACE_ID.test(segment)) return { ok: false };
+  return {
+    ok: true,
+    path: path.replace(
+      /^(\/(?:preview\/)?workspaces\/)[^/]+/,
+      (_m, prefix: string) => `${prefix}${sessionWorkspaceId}`,
+    ),
+  };
+}
+
+/** Public origin of the site, behind a proxy when forwarded headers say so. */
+export function siteOrigin(req: Request, url: URL): string {
+  const host = req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? url.host;
+  const proto =
+    req.headers.get("x-forwarded-proto") ??
+    (host.startsWith("localhost") || host.startsWith("127.0.0.1") ? "http" : url.protocol.replace(":", ""));
+  return `${proto}://${host}`;
+}
+
 function cookieValue(header: string | null, name: string): string | undefined {
   if (!header) return undefined;
   for (const part of header.split(";")) {
@@ -74,15 +128,15 @@ export function createCmsProxy(
     const token = await readSessionToken(req);
     const session = await readPreviewSession(secret, token);
     if (!session) return Response.json({ error: "unauthorized" }, { status: 401 });
-    const pathWorkspace = workspaceIdFromProxyPath(path);
-    if (pathWorkspace && pathWorkspace !== session.workspaceId) {
+    const resolved = resolveProxyPath(path, session.workspaceId);
+    if (!resolved.ok) {
       return Response.json({ error: "forbidden" }, { status: 403 });
     }
     if (cms.config.workspaceId && session.workspaceId !== cms.config.workspaceId) {
       return Response.json({ error: "forbidden" }, { status: 403 });
     }
 
-    const upstream = new URL(`${apiUrl.replace(/\/$/, "")}${path}`);
+    const upstream = new URL(`${apiUrl.replace(/\/$/, "")}${resolved.path}`);
     upstream.search = url.search;
     const headers = new Headers();
     headers.set("Authorization", `Bearer ${token}`);
@@ -90,6 +144,10 @@ export function createCmsProxy(
     if (contentType) headers.set("Content-Type", contentType);
     const accept = req.headers.get("accept");
     if (accept) headers.set("Accept", accept);
+    const studio = req.headers.get("x-backmatter-studio");
+    if (studio) headers.set("X-Backmatter-Studio", studio);
+    // Which site this Studio runs on, so the dashboard can list versions per site.
+    headers.set("X-Backmatter-Site", siteOrigin(req, url));
 
     const hasBody = req.method !== "GET" && req.method !== "HEAD";
     const res = await forward(upstream, {
@@ -104,5 +162,5 @@ export function createCmsProxy(
     return new Response(res.body, { status: res.status, headers: responseHeaders });
   };
 
-  return { GET: handle, POST: handle, PUT: handle, DELETE: handle };
+  return { GET: handle, POST: handle, PUT: handle, DELETE: handle, PATCH: handle };
 }

package/src/css.d.ts

@@ -0,0 +1,2 @@
+// packages/next/src/css.d.ts
+declare module "*.css";

package/src/devbar-client.tsx

@@ -1,8 +1,7 @@
 // packages/next/src/devbar-client.tsx
 "use client";
 
-import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
-import { SiteChrome } from "./site-editor";
+import { Suspense, lazy, useEffect, useState, type CSSProperties, type ReactNode } from "react";
 import {
   clearHostPreviewSession,
   fetchCmsSession,
@@ -10,6 +9,18 @@ import {
   resolveDevMode,
   type CmsSessionUser,
 } from "@backmatter/core/preview";
+import {
+  ENTER_ATTEMPT_KEY,
+  enterPath,
+  gateOpen,
+  isGateShortcut,
+  markerCookie,
+  recentEnterAttempt,
+  stripOptInParam,
+} from "./gate";
+
+/** The bar and its panels load only after the gate opens. */
+const SiteChrome = lazy(() => import("./site-editor").then((m) => ({ default: m.SiteChrome })));
 
 export type { CmsSessionUser };
 
@@ -276,8 +287,90 @@ export function DevBarView({
   );
 }
 
-export function DevBarClient({ apiUrl }: { apiUrl: string }) {
-  const state = useDevMode({ apiUrl });
+const DEFAULT_PREVIEW_ENTRY_PATH = "/api/backmatter/preview";
+
+type Gate = "closed" | "open";
+
+/**
+ * Opt-in check with no network: `?backmatter=1` (then stripped from the URL and
+ * remembered in the marker cookie), the marker itself, or the desktop
+ * shortcut. Public visitors stop here.
+ */
+function useGate(): Gate {
+  const [gate, setGate] = useState<Gate>("closed");
+
+  useEffect(() => {
+    // Framed by an editor (the Studio's split preview, the dashboard's split
+    // view): that editor is the chrome, so the page shows no bar of its own.
+    if (window.self !== window.top) return;
+    const secure = location.protocol === "https:";
+    if (gateOpen({ search: location.search, cookie: document.cookie })) {
+      document.cookie = markerCookie(true, secure);
+      const clean = stripOptInParam(location.href);
+      if (clean) history.replaceState(history.state, "", clean);
+      setGate("open");
+      return;
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (!isGateShortcut(e)) return;
+      e.preventDefault();
+      document.cookie = markerCookie(true, secure);
+      setGate("open");
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  return gate;
+}
+
+/**
+ * Past the gate: ask this origin for the session. None means a top-level
+ * bounce to the dashboard, which returns here with a ticket. A return without
+ * a session (login abandoned, site not in the workspace) clears the marker
+ * instead of bouncing again.
+ */
+function useSiteSession(gate: Gate, previewEntryPath: string): DevModeState {
+  const [state, setState] = useState<DevModeState>({ status: "hidden" });
+
+  useEffect(() => {
+    if (gate !== "open") return;
+    let cancelled = false;
+    void loadDevModeState("").then((next) => {
+      if (cancelled) return;
+      if (next.status === "ready" && next.mode === "preview") {
+        sessionStorage.removeItem(ENTER_ATTEMPT_KEY);
+        setState(next);
+        return;
+      }
+      if (recentEnterAttempt(sessionStorage.getItem(ENTER_ATTEMPT_KEY), Date.now())) {
+        sessionStorage.removeItem(ENTER_ATTEMPT_KEY);
+        document.cookie = markerCookie(false, location.protocol === "https:");
+        setState({ status: "hidden" });
+        return;
+      }
+      sessionStorage.setItem(ENTER_ATTEMPT_KEY, String(Date.now()));
+      location.assign(enterPath(previewEntryPath, location.pathname + location.search + location.hash));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [gate, previewEntryPath]);
+
+  return state;
+}
+
+export function DevBarClient({
+  studioPath,
+  previewEntryPath = DEFAULT_PREVIEW_ENTRY_PATH,
+}: {
+  /** Unused since the bar stopped calling the CMS origin; kept for host layouts that still pass it. */
+  apiUrl?: string;
+  studioPath?: string;
+  previewEntryPath?: string;
+}) {
+  const gate = useGate();
+  const state = useSiteSession(gate, previewEntryPath);
   const [exiting, setExiting] = useState(false);
   const exit = () => {
     if (exiting) return;
@@ -286,8 +379,19 @@ export function DevBarClient({ apiUrl }: { apiUrl: string }) {
       if (!ok) setExiting(false);
     });
   };
-  if (state.status === "ready" && state.mode === "preview") {
-    return <SiteChrome branch={state.branch} tree={state.tree} exiting={exiting} onExit={exit} />;
+  if (state.status !== "ready") return null;
+  if (state.mode === "preview") {
+    return (
+      <Suspense fallback={null}>
+        <SiteChrome
+          branch={state.branch}
+          tree={state.tree}
+          exiting={exiting}
+          onExit={exit}
+          studioPath={studioPath}
+        />
+      </Suspense>
+    );
   }
   return <DevBarView state={state} exiting={exiting} onExit={exit} />;
 }

package/src/devbar.tsx

@@ -13,7 +13,24 @@ export {
   type DevModeState,
 } from "./devbar-client";
 
-/** Host layout: `<DevBar />`. Optional apiUrl for local/self-hosted CMS. */
-export function DevBar({ apiUrl }: { apiUrl?: string } = {}) {
-  return <DevBarClient apiUrl={resolveDevBarApiUrl(apiUrl)} />;
+/**
+ * Host layout: `<DevBar />`. Public visitors get a gate of a few hundred
+ * bytes that makes no request; `?backmatter=1`, the `bm_ui` marker cookie or
+ * ⌘⇧E opens it. `studioPath` is where `@backmatter/studio` is mounted on this
+ * site (default `/backmatter`); the bar's panels are frames of that route.
+ * `previewEntryPath` is the ticket route (default `/api/backmatter/preview`).
+ * `apiUrl` is accepted for older layouts and no longer used.
+ */
+export function DevBar({
+  apiUrl,
+  studioPath,
+  previewEntryPath,
+}: { apiUrl?: string; studioPath?: string; previewEntryPath?: string } = {}) {
+  return (
+    <DevBarClient
+      apiUrl={resolveDevBarApiUrl(apiUrl)}
+      studioPath={studioPath}
+      previewEntryPath={previewEntryPath}
+    />
+  );
 }

package/src/gate.ts

@@ -0,0 +1,85 @@
+// packages/next/src/gate.ts
+// The visitor gate in front of the editing bar. Pure helpers so the decision
+// is testable without a DOM: a page opens the bar only when the visitor opted
+// in through `?backmatter=1`, carries the marker cookie `bm_ui=1`, or presses
+// the desktop shortcut. Anyone else gets no fetch and no editor code.
+
+export const MARKER_COOKIE = "bm_ui";
+export const OPT_IN_PARAM = "backmatter";
+/** 30 days, per origin. Not HttpOnly: the gate reads it before any request. */
+export const MARKER_TTL_S = 30 * 24 * 60 * 60;
+/** Written when the gate bounces to the dashboard; read on return to stop a loop. */
+export const ENTER_ATTEMPT_KEY = "backmatter:enter";
+export const ENTER_ATTEMPT_WINDOW_MS = 60_000;
+
+export function hasMarker(cookieHeader: string | null | undefined): boolean {
+  if (!cookieHeader) return false;
+  for (const part of cookieHeader.split(";")) {
+    const [key, ...rest] = part.trim().split("=");
+    if (key === MARKER_COOKIE) return rest.join("=") === "1";
+  }
+  return false;
+}
+
+export function hasOptInParam(search: string): boolean {
+  return new URLSearchParams(search).get(OPT_IN_PARAM) === "1";
+}
+
+export function gateOpen(input: { search: string; cookie: string | null | undefined }): boolean {
+  return hasOptInParam(input.search) || hasMarker(input.cookie);
+}
+
+/** `document.cookie` assignment that sets or clears the marker. */
+export function markerCookie(on: boolean, secure = false): string {
+  const parts = [
+    `${MARKER_COOKIE}=${on ? "1" : ""}`,
+    "Path=/",
+    `Max-Age=${on ? MARKER_TTL_S : 0}`,
+    "SameSite=Lax",
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+/** The same href without `?backmatter=1`, or null when the param was absent. */
+export function stripOptInParam(href: string): string | null {
+  const url = new URL(href);
+  if (url.searchParams.get(OPT_IN_PARAM) !== "1") return null;
+  url.searchParams.delete(OPT_IN_PARAM);
+  return url.toString();
+}
+
+/** ⌘⇧E on macOS, Ctrl+Shift+E elsewhere. Not bound by the major browsers. */
+export function isGateShortcut(e: {
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+}): boolean {
+  if (!e.shiftKey || e.altKey) return false;
+  if (!(e.metaKey || e.ctrlKey)) return false;
+  return e.key === "E" || e.key === "e";
+}
+
+/** Same-origin path only: must start with one `/`. Anything else goes home. */
+export function safeReturnPath(raw: string | null | undefined): string {
+  const value = raw?.trim() ?? "";
+  if (!value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\")) return "/";
+  return value;
+}
+
+/** The host route that bounces to the dashboard `enter` and comes back to `returnPath`. */
+export function enterPath(previewEntryPath: string, returnPath: string): string {
+  return `${previewEntryPath}?enter=1&return=${encodeURIComponent(safeReturnPath(returnPath))}`;
+}
+
+/**
+ * Loop guard: true when a bounce started within the window, meaning we came
+ * back from the dashboard without a session. The caller then gives up and
+ * clears the marker instead of bouncing again.
+ */
+export function recentEnterAttempt(stored: string | null, now: number): boolean {
+  const at = Number(stored);
+  return Number.isFinite(at) && at > 0 && now - at < ENTER_ATTEMPT_WINDOW_MS;
+}

package/src/preview-refresh.tsx

@@ -39,17 +39,6 @@ function referrerOrigin(): string {
   }
 }
 
-function dashboardOriginFromMeta(): string {
-  const marked = document
-    .querySelector('meta[name="backmatter:dashboard"]')
-    ?.getAttribute("content");
-  if (marked) return marked.replace(/\/$/, "");
-  if (location.hostname === "localhost" || location.hostname === "127.0.0.1") {
-    return `${location.protocol}//${location.hostname}:5173`;
-  }
-  return "";
-}
-
 function subscribeDocStream(
   ref: { locale: string; type: string; slug: string },
   onEvent: (event: { raw?: string; body?: string; frontmatter?: Record<string, unknown> }) => void,
@@ -169,13 +158,15 @@ export function PreviewClient({
       ...(branch ? { branch } : {}),
       ...(tree ? { tree } : {}),
     };
+    // Framed by the dashboard's split view: the parent is the dashboard.
+    // Otherwise the Studio mounted on this site posts from same-origin frames.
     const parentOrigin = referrerOrigin();
-    const dashboardOrigin = dashboardOriginFromMeta();
-    const allowed = [...originsKey.split("\0"), parentOrigin, dashboardOrigin].filter(
+    const selfOrigin = window.location.origin;
+    const allowed = [...originsKey.split("\0"), parentOrigin, selfOrigin].filter(
       (origin) => origin.length > 0,
     );
     const framed = window.parent !== window;
-    const targetOrigin = framed ? parentOrigin || allowed[0] || "" : dashboardOrigin;
+    const targetOrigin = framed ? parentOrigin || allowed[0] || "" : selfOrigin;
     const windowTransport: PreviewTransport | null = targetOrigin
       ? createWindowPreviewTransport({
           target: framed ? window.parent : { postMessage() {} },

package/src/preview-route.ts

@@ -8,19 +8,37 @@ import {
   previewLocationWithCheckout,
   readPreviewCookie,
   readPreviewTicket,
+  resolveDashboardUrl,
+  studioEnterUrl,
   writePreviewCookie,
   type PreviewCheckout,
 } from "@backmatter/core";
 import { previewStreamUrl, previewTreeStreamUrl } from "@backmatter/core/preview";
 import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
+import { MARKER_COOKIE, MARKER_TTL_S, safeReturnPath } from "./gate";
+import { requestUrlFrom } from "./request-url";
 
 export type PreviewRouteDeps = {
   enableDraft?: () => void | Promise<void>;
   disableDraft?: () => void | Promise<void>;
   isDraftEnabled?: () => boolean | Promise<boolean>;
   now?: () => number;
+  /** Dashboard that holds the login, for `?enter=1`. Default: `resolveDashboardUrl()`. */
+  dashboardUrl?: string;
 };
 
+/** The gate's marker: readable by the page script, so never HttpOnly. */
+function markerCookieHeader(secure: boolean, on: boolean): string {
+  const parts = [
+    `${MARKER_COOKIE}=${on ? "1" : ""}`,
+    "Path=/",
+    `Max-Age=${on ? MARKER_TTL_S : 0}`,
+    "SameSite=Lax",
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
 function cookieBase(name: string, secure: boolean, maxAge: number, value: string) {
   // HTTPS is cross-site from the CMS iframe (dash → customer origin). Lax is
   // not sent there, so draftMode can be on while the checkout cookie is missing
@@ -95,6 +113,23 @@ export function createPreviewRoute(
       return Response.json({ mode: draftOn ? "preview" : "live" });
     }
 
+    // The bar found the marker but no session: go top-level to the dashboard,
+    // which mints a ticket after login and returns to this page.
+    if (url.searchParams.get("enter") === "1") {
+      if (!cms.config.workspaceId) {
+        return Response.json({ error: "preview_not_configured" }, { status: 503 });
+      }
+      const returnUrl = requestUrlFrom(
+        (name) => req.headers.get(name),
+        safeReturnPath(url.searchParams.get("return")),
+      );
+      const dashboardUrl = resolveDashboardUrl(deps.dashboardUrl);
+      return Response.redirect(
+        studioEnterUrl(dashboardUrl, { workspaceId: cms.config.workspaceId, returnUrl }),
+        302,
+      );
+    }
+
     if (url.searchParams.get("stream") === "1") {
       if (!secret || !cms.config.apiUrl || !cms.config.workspaceId) {
         return new Response("preview not configured", { status: 503 });
@@ -169,6 +204,8 @@ export function createPreviewRoute(
         ),
       );
     }
+    // Entry opts the visitor in, so the bar shows on later pages without a param.
+    headers.append("Set-Cookie", markerCookieHeader(secure, true));
     return new Response(null, { status: 302, headers });
   };
 
@@ -178,6 +215,8 @@ export function createPreviewRoute(
     const headers = new Headers();
     headers.append("Set-Cookie", cookieBase(PREVIEW_COOKIE, secure, 0, ""));
     headers.append("Set-Cookie", cookieBase(PREVIEW_SESSION_COOKIE, secure, 0, ""));
+    // Exit also drops the marker; otherwise the next page would bounce straight back in.
+    headers.append("Set-Cookie", markerCookieHeader(secure, false));
     return new Response(null, { status: 204, headers });
   };
 

package/src/request-url.ts

@@ -0,0 +1,13 @@
+// packages/next/src/request-url.ts
+
+/** Absolute URL of the current request, from forwarded headers when behind a proxy. */
+export function requestUrlFrom(
+  get: (name: string) => string | null,
+  pathWithSearch: string,
+): string {
+  const host = get("x-forwarded-host") ?? get("host") ?? "localhost:3000";
+  const proto =
+    get("x-forwarded-proto") ??
+    (host.startsWith("localhost") || host.startsWith("127.0.0.1") ? "http" : "https");
+  return `${proto}://${host}${pathWithSearch}`;
+}

package/src/site-editor.tsx

@@ -32,14 +32,17 @@ function useSiteDoc(): SiteDocRef | null {
   return doc;
 }
 
-function dashboardOrigin(): string {
-  if (typeof document === "undefined") return "";
-  const marked = document.querySelector('meta[name="backmatter:dashboard"]')?.getAttribute("content");
-  if (marked) return marked.replace(/\/$/, "");
-  if (location.hostname === "localhost" || location.hostname === "127.0.0.1") {
-    return `${location.protocol}//${location.hostname}:5173`;
-  }
-  return "";
+/** Default route the host mounts `@backmatter/studio` on. */
+export const DEFAULT_STUDIO_PATH = "/backmatter";
+
+/**
+ * The panels are frames of the Studio mounted on this same origin. Same
+ * origin means the site session cookie is first-party and postMessage needs
+ * no foreign origin.
+ */
+function studioBase(studioPath: string): string {
+  if (typeof location === "undefined") return "";
+  return `${location.origin}${studioPath.replace(/\/+$/, "")}`;
 }
 
 export function SiteChrome({
@@ -47,11 +50,14 @@ export function SiteChrome({
   tree,
   exiting,
   onExit,
+  studioPath = DEFAULT_STUDIO_PATH,
 }: {
   branch?: string;
   tree?: string;
   exiting?: boolean;
   onExit: () => void;
+  /** Where `@backmatter/studio` is mounted on this site. */
+  studioPath?: string;
 }) {
   const router = useRouter();
   const doc = useSiteDoc();
@@ -61,12 +67,14 @@ export function SiteChrome({
   const [chatOpen, setChatOpen] = useState(false);
   const [publishOpen, setPublishOpen] = useState(false);
   const [changeCount, setChangeCount] = useState(0);
-  const [origin, setOrigin] = useState("");
+  // Set in an effect so SSR and the first client render agree.
+  const [base, setBase] = useState("");
+  const origin = typeof location === "undefined" ? "" : location.origin;
   const editorFrame = useRef<HTMLIFrameElement>(null);
 
   useEffect(() => {
-    setOrigin(dashboardOrigin());
-  }, []);
+    setBase(studioBase(studioPath));
+  }, [studioPath]);
 
   useEffect(() => {
     function onKey(event: KeyboardEvent) {
@@ -113,8 +121,8 @@ export function SiteChrome({
 
   const label = doc ? `${doc.type}/${doc.slug}` : "No document";
   const editorSrc =
-    doc && origin
-      ? `${origin}/workspaces/${doc.workspaceId}/docs/${doc.locale}/${doc.type}/${doc.slug}?embed=1`
+    doc && base
+      ? `${base}/workspaces/${doc.workspaceId}/docs/${doc.locale}/${doc.type}/${doc.slug}?embed=1`
       : "";
 
   function onChatWrote() {
@@ -143,12 +151,13 @@ export function SiteChrome({
           hidden={!chatOpen}
           onWrote={onChatWrote}
           onClosed={() => setChatOpen(false)}
+          base={base}
         />
       ) : null}
-      {doc && origin ? (
+      {doc && base ? (
         <iframe
           title="Publish"
-          src={`${origin}/embed/publish/${doc.workspaceId}`}
+          src={`${base}/embed/publish/${doc.workspaceId}`}
           style={{
             ...publishStyle,
             visibility: publishOpen ? "visible" : "hidden",
@@ -201,11 +210,14 @@ function CmsChat({
   hidden,
   onWrote,
   onClosed,
+  base,
 }: {
   doc: SiteDocRef;
   hidden: boolean;
   onWrote: () => void;
   onClosed: () => void;
+  /** Studio origin plus base path. */
+  base: string;
 }) {
   const frame = useRef<HTMLIFrameElement>(null);
   const onWroteRef = useRef(onWrote);
@@ -214,7 +226,7 @@ function CmsChat({
   onWroteRef.current = onWrote;
   onClosedRef.current = onClosed;
   hiddenRef.current = hidden;
-  const origin = dashboardOrigin();
+  const origin = base ? new URL(base).origin : "";
 
   function openChat() {
     const frameEl = frame.current;
@@ -246,12 +258,12 @@ function CmsChat({
     return () => window.removeEventListener("message", onMessage);
   }, [doc.locale, doc.type, doc.slug, origin]);
 
-  if (!origin) return null;
+  if (!base) return null;
   return (
     <iframe
       ref={frame}
       title="AI chat"
-      src={`${origin}/embed/chat/${doc.workspaceId}`}
+      src={`${base}/embed/chat/${doc.workspaceId}`}
       style={{
         ...chatStyle,
         visibility: hidden ? "hidden" : "visible",

package/src/studio-client.tsx

@@ -0,0 +1,62 @@
+"use client";
+// packages/next/src/studio-client.tsx
+// Loads @backmatter/studio in the browser only. The Studio is a client app
+// (react-router, IndexedDB replica, StyleX output); it has no server render.
+import { useEffect, useState, type ComponentType } from "react";
+import type { StudioDefinition } from "@backmatter/studio/define";
+import "@backmatter/studio/studio.css";
+
+export type StudioMountProps = {
+  workspaceId: string;
+  basePath: string;
+  dashboardUrl: string;
+  version: string;
+  proxyPath: string;
+  previewEntryPath: string;
+  /** CMS API origin for display (Content API URLs); requests use the proxy. */
+  apiUrl?: string;
+  /**
+   * `defineStudio(...)` from a `"use client"` module. The server page passes
+   * the client reference; it resolves to the object here.
+   */
+  studio?: StudioDefinition;
+};
+
+type SiteStudioComponent = ComponentType<StudioMountProps>;
+
+export function StudioMount(props: StudioMountProps) {
+  const [Studio, setStudio] = useState<SiteStudioComponent | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    import("@backmatter/studio")
+      .then((mod) => {
+        if (!cancelled) setStudio(() => mod.SiteStudio as SiteStudioComponent);
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) setError(err instanceof Error ? err.message : "Could not load the Studio");
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (error) {
+    return (
+      <div style={fallbackStyle} role="alert">
+        {error}
+      </div>
+    );
+  }
+  if (!Studio) return <div style={fallbackStyle} aria-busy="true" />;
+  return <Studio {...props} />;
+}
+
+const fallbackStyle = {
+  minHeight: "100dvh",
+  display: "grid",
+  placeItems: "center",
+  fontFamily: "ui-sans-serif, system-ui, sans-serif",
+  color: "#71717a",
+} as const;

package/src/studio.tsx

@@ -0,0 +1,144 @@
+// packages/next/src/studio.tsx
+// Mount the Backmatter Studio on a route of the site.
+//
+//   // app/(backmatter)/backmatter/layout.tsx
+//   export { StudioLayout as default } from "@backmatter/next/studio";
+//
+//   // app/(backmatter)/backmatter/[[...path]]/page.tsx
+//   import { createStudioPage } from "@backmatter/next/studio";
+//   import { cms } from "@/.backmatter";
+//   export default createStudioPage(cms);
+//
+// The Studio talks to `/api/backmatter/cms/*` on this origin with the site
+// session cookie. Without a session the page redirects top-level to the
+// dashboard `enter` route, which mints a ticket and returns here.
+import { Suspense, type ReactNode } from "react";
+import {
+  PREVIEW_SESSION_COOKIE,
+  readPreviewSession,
+  resolveDashboardUrl,
+  studioEnterUrl,
+} from "@backmatter/core";
+import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
+import studioPkg from "@backmatter/studio/package.json";
+import type { StudioDefinition } from "@backmatter/studio/define";
+import { requestUrlFrom } from "./request-url";
+import { StudioMount } from "./studio-client";
+
+export { requestUrlFrom };
+
+export type StudioPageOptions = {
+  /** Where the Studio is mounted. Default `/backmatter`. */
+  basePath?: string;
+  /** Dashboard that holds the login. Default: `resolveDashboardUrl()`. */
+  dashboardUrl?: string;
+  /** Workspace to open. Default: `cms.config.workspaceId`. */
+  workspaceId?: string;
+  /** Same-origin proxy route. Default `/api/backmatter/cms`. */
+  proxyPath?: string;
+  /** Ticket entry route. Default `/api/backmatter/preview`. */
+  previewEntryPath?: string;
+  /**
+   * Site customization: the default export of a `"use client"` module that
+   * calls `defineStudio`. The server only forwards the reference.
+   */
+  studio?: StudioDefinition;
+};
+
+type NextHeaders = {
+  cookies: () => Promise<{ get: (name: string) => { value: string } | undefined }>;
+  headers: () => Promise<{ get: (name: string) => string | null }>;
+};
+
+type NextNavigation = { redirect: (url: string) => never };
+
+async function nextHeaders(): Promise<NextHeaders> {
+  return (await import("next/headers" as string)) as NextHeaders;
+}
+
+async function nextNavigation(): Promise<NextNavigation> {
+  return (await import("next/navigation" as string)) as NextNavigation;
+}
+
+export function studioPathFor(basePath: string, segments: string[] | undefined, search = ""): string {
+  const rest = segments && segments.length > 0 ? `/${segments.map(encodeURIComponent).join("/")}` : "";
+  return `${basePath}${rest}${search}`;
+}
+
+export function createStudioPage(
+  cms: Pick<BackmatterClient, "config">,
+  options: StudioPageOptions = {},
+) {
+  const basePath = (options.basePath ?? "/backmatter").replace(/\/+$/, "") || "/backmatter";
+  const proxyPath = options.proxyPath ?? "/api/backmatter/cms";
+  const previewEntryPath = options.previewEntryPath ?? "/api/backmatter/preview";
+
+  return async function StudioPage(props: {
+    params: Promise<{ path?: string[] }> | { path?: string[] };
+    searchParams?: Promise<Record<string, string | string[] | undefined>> | Record<string, string | string[] | undefined>;
+  }) {
+    const workspaceId = options.workspaceId ?? cms.config.workspaceId;
+    if (!workspaceId) {
+      throw new Error("backmatter: the Studio needs a workspaceId (backmatter.config.ts or BACKMATTER_WORKSPACE_ID)");
+    }
+    const dashboardUrl = resolveDashboardUrl(options.dashboardUrl);
+    const { cookies, headers } = await nextHeaders();
+    const [cookieStore, headerStore] = await Promise.all([cookies(), headers()]);
+
+    const token = cookieStore.get(PREVIEW_SESSION_COOKIE)?.value;
+    const secret = cms.config.previewToken;
+    const claims = token && secret ? await readPreviewSession(secret, token) : null;
+    const valid = claims !== null && claims.workspaceId === workspaceId;
+
+    if (!valid) {
+      const params = await props.params;
+      const search = props.searchParams ? await props.searchParams : {};
+      const qs = new URLSearchParams();
+      for (const [key, value] of Object.entries(search)) {
+        if (typeof value === "string") qs.set(key, value);
+      }
+      const searchText = qs.size > 0 ? `?${qs.toString()}` : "";
+      const returnUrl = requestUrlFrom(
+        (name) => headerStore.get(name),
+        studioPathFor(basePath, params.path, searchText),
+      );
+      const { redirect } = await nextNavigation();
+      redirect(studioEnterUrl(dashboardUrl, { workspaceId, returnUrl }));
+    }
+
+    return (
+      <StudioMount
+        workspaceId={workspaceId}
+        basePath={basePath}
+        dashboardUrl={dashboardUrl}
+        version={studioPkg.version}
+        proxyPath={proxyPath}
+        previewEntryPath={previewEntryPath}
+        apiUrl={cms.config.apiUrl}
+        studio={options.studio}
+      />
+    );
+  };
+}
+
+/**
+ * Root layout for the Studio route group. Its own `<html>` so the site's
+ * layout, fonts and global CSS do not wrap the editor.
+ */
+export function StudioLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <meta name="robots" content="noindex, nofollow" />
+        <script dangerouslySetInnerHTML={{ __html: THEME_BOOT }} />
+      </head>
+      <body style={{ margin: 0 }}>
+        {/* The page reads cookies; with Cache Components that must sit under Suspense. */}
+        <Suspense fallback={null}>{children}</Suspense>
+      </body>
+    </html>
+  );
+}
+
+// Same first-paint theme pick as the dashboard's index.html.
+const THEME_BOOT = `(function(){try{var s=localStorage.getItem("backmatter-theme");var m=s==="light"||s==="dark"?s:"system";var d=m==="dark"||(m!=="light"&&window.matchMedia("(prefers-color-scheme: dark)").matches);document.documentElement.dataset.theme=d?"dark":"light";document.documentElement.style.colorScheme=d?"dark":"light"}catch(e){}})();`;