@backmatter/next 0.0.23 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
@@ -47,10 +47,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@backmatter/core": "^0.0.20",
+    "@backmatter/core": "^0.0.21",
     "@mdx-js/mdx": "^3.1.1",
     "remark-gfm": "^4.0.1",
-    "@backmatter/studio": "^0.0.1"
+    "@backmatter/studio": "^0.0.3"
   },
   "peerDependencies": {
     "next": ">=16.3.0",

package/src/devbar-client.tsx

@@ -8,16 +8,19 @@ import {
   fetchHostPreviewSession,
   resolveDevMode,
   type CmsSessionUser,
+  type HostSessionReason,
 } from "@backmatter/core/preview";
 import {
   ENTER_ATTEMPT_KEY,
   enterPath,
-  gateOpen,
+  hasMarker,
+  hasOptInParam,
   isGateShortcut,
   markerCookie,
   recentEnterAttempt,
   stripOptInParam,
 } from "./gate";
+import { DEVBAR_CLASS, DEVBAR_ENTER_CSS, devbarShellStyle } from "./devbar-motion";
 
 /** The bar and its panels load only after the gate opens. */
 const SiteChrome = lazy(() => import("./site-editor").then((m) => ({ default: m.SiteChrome })));
@@ -25,7 +28,7 @@ const SiteChrome = lazy(() => import("./site-editor").then((m) => ({ default: m.
 export type { CmsSessionUser };
 
 export type DevModeState =
-  | { status: "hidden" }
+  | { status: "hidden"; reason?: HostSessionReason }
   | {
       status: "ready";
       user?: CmsSessionUser;
@@ -34,11 +37,33 @@ export type DevModeState =
       tree?: string;
     };
 
+export type SessionGateAction = "show" | "bounce" | "quiet" | "wait";
+
+/**
+ * What the bar does after the site-session check. A verified session shows
+ * the bar. An explicit enter (shortcut or `?backmatter=1`) with no session
+ * sends the whole window to the dashboard. A leftover marker stays on the
+ * public page. An unreachable API waits and keeps the marker.
+ */
+export function sessionGateAction(input: {
+  explicit: boolean;
+  enabled: boolean;
+  reason: HostSessionReason;
+  recentAttempt: boolean;
+}): SessionGateAction {
+  if (input.enabled) return "show";
+  if (input.reason === "unavailable") return "wait";
+  if (input.explicit && !input.recentAttempt) return "bounce";
+  return "quiet";
+}
+
 export function devModeState(
   user: CmsSessionUser | null,
-  session: { enabled: boolean; branch?: string; tree?: string },
+  session: { enabled: boolean; branch?: string; tree?: string; reason?: HostSessionReason },
 ): DevModeState {
-  if (!user && !session.enabled) return { status: "hidden" };
+  if (!user && !session.enabled) {
+    return session.reason ? { status: "hidden", reason: session.reason } : { status: "hidden" };
+  }
   const resolved = resolveDevMode(session);
   return {
     status: "ready",
@@ -77,40 +102,15 @@ export function useDevMode(options: { apiUrl: string }): DevModeState {
   return state;
 }
 
-/** Above typical host sticky headers/modals; below max 32-bit int so a host can still overlay. */
-const DEVBAR_Z_INDEX = 2147483000;
-
 const barStyle: CSSProperties = {
-  position: "fixed",
-  bottom: 0,
-  left: "50%",
-  transform: "translateX(-50%)",
-  zIndex: DEVBAR_Z_INDEX,
-  isolation: "isolate",
+  ...devbarShellStyle,
   pointerEvents: "auto",
-  display: "flex",
-  alignItems: "center",
   gap: 10,
-  minHeight: 32,
-  maxWidth: "min(520px, calc(100vw - 24px))",
   padding: "0 12px",
-  paddingBottom: "env(safe-area-inset-bottom, 0px)",
-  background: "#f4f4f5",
-  color: "#71717a",
-  border: "1px solid #e4e4e7",
-  borderBottom: "none",
-  borderTopLeftRadius: 8,
-  borderTopRightRadius: 8,
-  borderBottomLeftRadius: 0,
-  borderBottomRightRadius: 0,
-  fontFamily:
-    'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
-  fontSize: 11,
+  fontFamily: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+  fontSize: 12,
   fontWeight: 500,
-  lineHeight: "32px",
-  WebkitFontSmoothing: "antialiased",
-  fontVariantNumeric: "tabular-nums",
-  boxSizing: "border-box",
+  lineHeight: "44px",
 };
 
 const brandStyle: CSSProperties = {
@@ -151,8 +151,8 @@ const exitButtonStyle: CSSProperties = {
   fontFamily: "inherit",
   fontSize: 11,
   fontWeight: 500,
-  lineHeight: "32px",
-  minHeight: 32,
+  lineHeight: "44px",
+  minHeight: 44,
   touchAction: "manipulation",
   WebkitFontSmoothing: "antialiased",
 };
@@ -217,8 +217,9 @@ export function DevBarView({
   const ariaLabel = parts.join(", ");
 
   return (
-    <div role="status" aria-label={ariaLabel} style={barStyle}>
+    <div role="status" aria-label={ariaLabel} className={DEVBAR_CLASS} style={barStyle}>
       <style>{`
+        ${DEVBAR_ENTER_CSS}
         @media (hover: hover) {
           button.backmatter-devbar-exit:hover:not(:disabled) { color: #71717a; }
         }
@@ -289,12 +290,12 @@ export function DevBarView({
 
 const DEFAULT_PREVIEW_ENTRY_PATH = "/api/backmatter/preview";
 
-type Gate = "closed" | "open";
+type Gate = "closed" | "resume" | "enter";
 
 /**
- * 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.
+ * Opt-in check with no network. Public visitors stop here. `?backmatter=1`
+ * and the shortcut are an explicit enter. The marker only resumes a session
+ * that is still valid.
  */
 function useGate(): Gate {
   const [gate, setGate] = useState<Gate>("closed");
@@ -304,18 +305,19 @@ function useGate(): Gate {
     // 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 })) {
+    const explicit = hasOptInParam(location.search);
+    if (explicit || hasMarker(document.cookie)) {
       document.cookie = markerCookie(true, secure);
       const clean = stripOptInParam(location.href);
       if (clean) history.replaceState(history.state, "", clean);
-      setGate("open");
+      setGate(explicit ? "enter" : "resume");
       return;
     }
     const onKey = (e: KeyboardEvent) => {
       if (!isGateShortcut(e)) return;
       e.preventDefault();
       document.cookie = markerCookie(true, secure);
-      setGate("open");
+      setGate("enter");
     };
     window.addEventListener("keydown", onKey);
     return () => window.removeEventListener("keydown", onKey);
@@ -325,32 +327,43 @@ function useGate(): 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.
+ * Past the gate: ask this origin whether the site session still verifies.
+ * Only an explicit enter with no session leaves the page, and it leaves
+ * top-level. A stale marker stays on the public page.
  */
 function useSiteSession(gate: Gate, previewEntryPath: string): DevModeState {
   const [state, setState] = useState<DevModeState>({ status: "hidden" });
 
   useEffect(() => {
-    if (gate !== "open") return;
+    if (gate === "closed") return;
     let cancelled = false;
     void loadDevModeState("").then((next) => {
       if (cancelled) return;
-      if (next.status === "ready" && next.mode === "preview") {
+      const enabled = next.status === "ready" && next.mode === "preview";
+      const reason = next.status === "hidden" ? (next.reason ?? "anonymous") : "anonymous";
+      const action = sessionGateAction({
+        explicit: gate === "enter",
+        enabled,
+        reason,
+        recentAttempt: recentEnterAttempt(sessionStorage.getItem(ENTER_ATTEMPT_KEY), Date.now()),
+      });
+      if (action === "show") {
         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" });
+      if (action === "wait") {
+        setState({ status: "hidden", reason: "unavailable" });
+        return;
+      }
+      if (action === "bounce") {
+        sessionStorage.setItem(ENTER_ATTEMPT_KEY, String(Date.now()));
+        location.assign(enterPath(previewEntryPath, location.pathname + location.search + location.hash));
         return;
       }
-      sessionStorage.setItem(ENTER_ATTEMPT_KEY, String(Date.now()));
-      location.assign(enterPath(previewEntryPath, location.pathname + location.search + location.hash));
+      sessionStorage.removeItem(ENTER_ATTEMPT_KEY);
+      document.cookie = markerCookie(false, location.protocol === "https:");
+      setState({ status: "hidden", reason });
     });
     return () => {
       cancelled = true;
@@ -389,6 +402,7 @@ export function DevBarClient({
           exiting={exiting}
           onExit={exit}
           studioPath={studioPath}
+          previewEntryPath={previewEntryPath}
         />
       </Suspense>
     );

package/src/devbar-motion.ts

@@ -0,0 +1,58 @@
+// packages/next/src/devbar-motion.ts
+import type { CSSProperties } from "react";
+
+/** Above typical host sticky headers; below the max 32-bit int so a host can still overlay. */
+export const DEVBAR_Z_INDEX = 2147483000;
+
+export const DEVBAR_CLASS = "backmatter-devbar";
+
+/** Space panels need above the corner bar: 16px inset + 44px bar + 12px gap. */
+export const DEVBAR_CLEARANCE =
+  "calc(max(16px, env(safe-area-inset-bottom, 0px)) + 56px)";
+
+export const DEVBAR_RIGHT = "max(16px, env(safe-area-inset-right, 0px))";
+
+/** Shared chrome for the corner bar. Resting position does not use transform, so the enter animation can. */
+export const devbarShellStyle: CSSProperties = {
+  position: "fixed",
+  right: DEVBAR_RIGHT,
+  bottom: "max(16px, env(safe-area-inset-bottom, 0px))",
+  zIndex: DEVBAR_Z_INDEX,
+  isolation: "isolate",
+  display: "flex",
+  alignItems: "center",
+  width: "max-content",
+  maxWidth: "calc(100vw - 32px)",
+  minHeight: 44,
+  boxSizing: "border-box",
+  border: "1px solid #e4e4e7",
+  borderRadius: 12,
+  background: "#ffffff",
+  color: "#71717a",
+  boxShadow: "0 10px 28px rgba(24, 24, 27, 0.12), 0 1px 2px rgba(24, 24, 27, 0.06)",
+  transformOrigin: "100% 100%",
+  WebkitFontSmoothing: "antialiased",
+  fontVariantNumeric: "tabular-nums",
+};
+
+/** Plays when the bar mounts — that is when the session is ready, not on first paint. */
+export const DEVBAR_ENTER_CSS = `
+@keyframes backmatter-devbar-in {
+  from {
+    opacity: 0;
+    transform: translateY(10px) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+.${DEVBAR_CLASS} {
+  animation: backmatter-devbar-in 240ms cubic-bezier(0.23, 1, 0.32, 1) both;
+}
+@media (prefers-reduced-motion: reduce) {
+  .${DEVBAR_CLASS} {
+    animation: none;
+  }
+}
+`;

package/src/devbar.tsx

@@ -8,16 +8,20 @@ export {
   devModeState,
   exitHostPreview,
   loadDevModeState,
+  sessionGateAction,
   useDevMode,
   type CmsSessionUser,
   type DevModeState,
+  type SessionGateAction,
 } from "./devbar-client";
 
 /**
  * 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.
+ * bytes that makes no request. The bar appears only when the site session
+ * verifies. `?backmatter=1` or ⌘⇧E with no session sends the whole window to
+ * the dashboard; a leftover `bm_ui` marker stays on the public page.
+ * `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.
  */

package/src/page-render.ts

@@ -87,7 +87,7 @@ export async function renderPage(
 ): Promise<ReactNode> {
   const blocks = asBlocks(doc.frontmatter.blocks);
   const children = await Promise.all(
-    blocks.map(async (block) => {
+    blocks.map(async (block, index) => {
       if (typeof block.type !== "string") return null;
       const entry = components?.[block.type];
       if (!entry) {
@@ -107,8 +107,18 @@ export async function renderPage(
         console.warn(`[backmatter] skipping unknown block type "${block.type}"`);
         return null;
       }
-      const key = typeof block.id === "string" ? block.id : undefined;
-      return createElement(Cmp, { key, ...props, [RESERVED_BLOCK_PROP]: data });
+      const id = typeof block.id === "string" && block.id ? block.id : String(index);
+      return createElement(
+        "div",
+        {
+          key: id,
+          "data-backmatter-block": id,
+          "data-backmatter-type": block.type,
+          "data-backmatter-index": String(index),
+          style: { display: "contents" },
+        },
+        createElement(Cmp, { ...props, [RESERVED_BLOCK_PROP]: data }),
+      );
     }),
   );
   const rendered = children.filter((child) => child != null);

package/src/preview-route.ts

@@ -7,6 +7,7 @@ import {
   PREVIEW_SESSION_TTL_MS,
   previewLocationWithCheckout,
   readPreviewCookie,
+  readPreviewSession,
   readPreviewTicket,
   resolveDashboardUrl,
   studioEnterUrl,
@@ -25,6 +26,17 @@ export type PreviewRouteDeps = {
   now?: () => number;
   /** Dashboard that holds the login, for `?enter=1`. Default: `resolveDashboardUrl()`. */
   dashboardUrl?: string;
+  /**
+   * Exchange the current site session for a fresh token. Default calls
+   * `POST /preview/session/renew` on the API. Null means the session is dead.
+   * Throw when the API cannot be reached; that becomes a 503 and keeps the cookies.
+   */
+  renewSession?: (token: string) => Promise<string | null>;
+  /**
+   * Ask the API whether this site-session token is still logged in, epoch
+   * included. Default calls `GET /preview/session`.
+   */
+  confirmSession?: (token: string) => Promise<"ok" | "invalid" | "unavailable">;
 };
 
 /** The gate's marker: readable by the page script, so never HttpOnly. */
@@ -73,6 +85,42 @@ async function nextDraftEnabled(): Promise<boolean> {
   return (await mod.draftMode()).isEnabled;
 }
 
+async function renewSessionOnApi(apiUrl: string, token: string): Promise<string | null> {
+  let res: Response;
+  try {
+    res = await fetch(`${apiUrl}/preview/session/renew`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}` },
+      cache: "no-store",
+    });
+  } catch {
+    throw new Error("renew unavailable");
+  }
+  if (res.status === 401 || res.status === 403) return null;
+  if (!res.ok) throw new Error(`renew unavailable: ${res.status}`);
+  const body = (await res.json()) as { token?: unknown };
+  return typeof body.token === "string" && body.token ? body.token : null;
+}
+
+async function confirmSessionOnApi(
+  apiUrl: string | undefined,
+  token: string,
+): Promise<"ok" | "invalid" | "unavailable"> {
+  const base = apiUrl?.replace(/\/$/, "");
+  if (!base) return "unavailable";
+  try {
+    const res = await fetch(`${base}/preview/session`, {
+      headers: { authorization: `Bearer ${token}` },
+      cache: "no-store",
+    });
+    if (res.status === 401 || res.status === 403) return "invalid";
+    if (!res.ok) return "unavailable";
+    return "ok";
+  } catch {
+    return "unavailable";
+  }
+}
+
 function cookieFrom(req: Request, name: string): string | undefined {
   const header = req.headers.get("cookie");
   if (!header) return undefined;
@@ -102,15 +150,39 @@ export function createPreviewRoute(
     const secure = url.protocol === "https:";
 
     if (url.searchParams.get("session") === "1") {
-      const checkout = secret ? await checkoutFrom(req, secret, url) : null;
-      if (checkout) {
-        return Response.json({
-          mode: "preview",
-          ...checkout,
-        });
+      // The bar's only login signal. The checkout cookie and draft mode still
+      // render drafts; they do not mean the visitor is signed in.
+      const token = cookieFrom(req, PREVIEW_SESSION_COOKIE);
+      const claims = secret && token ? await readPreviewSession(secret, token) : null;
+      const workspaceOk = !cms.config.workspaceId || claims?.workspaceId === cms.config.workspaceId;
+      const clearLogin = async () => {
+        await (deps.disableDraft ?? (() => nextDraft(false)))();
+        const headers = new Headers({ "Cache-Control": "no-store" });
+        headers.append("Set-Cookie", cookieBase(PREVIEW_COOKIE, secure, 0, ""));
+        headers.append("Set-Cookie", cookieBase(PREVIEW_SESSION_COOKIE, secure, 0, ""));
+        headers.append("Set-Cookie", markerCookieHeader(secure, false));
+        return Response.json({ mode: "live", reason: "invalid" }, { headers });
+      };
+      if (!claims || !token || !workspaceOk) {
+        if (token) return clearLogin();
+        return Response.json(
+          { mode: "live", reason: "anonymous" },
+          { headers: { "Cache-Control": "no-store" } },
+        );
+      }
+      const confirm = deps.confirmSession ?? ((current: string) => confirmSessionOnApi(cms.config.apiUrl, current));
+      const verdict = await confirm(token);
+      if (verdict === "unavailable") {
+        return Response.json(
+          { mode: "live", reason: "unavailable" },
+          { headers: { "Cache-Control": "no-store" } },
+        );
       }
-      const draftOn = await (deps.isDraftEnabled ?? nextDraftEnabled)();
-      return Response.json({ mode: draftOn ? "preview" : "live" });
+      if (verdict !== "ok") return clearLogin();
+      return Response.json(
+        { mode: "preview", branch: claims.branch, tree: claims.tree },
+        { headers: { "Cache-Control": "no-store" } },
+      );
     }
 
     // The bar found the marker but no session: go top-level to the dashboard,
@@ -210,6 +282,34 @@ export function createPreviewRoute(
   };
 
   const POST = async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    // Slide the site session while the bar is open. The cookie is HttpOnly, so
+    // the browser cannot renew it itself; a dead session is a 401 and the bar
+    // bounces to the dashboard instead of failing the next chat send.
+    if (url.searchParams.get("renew") === "1") {
+      const token = cookieFrom(req, PREVIEW_SESSION_COOKIE);
+      const apiUrl = cms.config.apiUrl?.replace(/\/$/, "");
+      if (!token || !apiUrl) return Response.json({ error: "unauthorized" }, { status: 401 });
+      let renewed: string | null;
+      try {
+        renewed = await (deps.renewSession ?? ((current) => renewSessionOnApi(apiUrl, current)))(token);
+      } catch {
+        return Response.json({ error: "unavailable" }, { status: 503 });
+      }
+      if (!renewed) return Response.json({ error: "unauthorized" }, { status: 401 });
+      const headers = new Headers();
+      headers.append(
+        "Set-Cookie",
+        cookieBase(
+          PREVIEW_SESSION_COOKIE,
+          url.protocol === "https:",
+          Math.floor(PREVIEW_SESSION_TTL_MS / 1000),
+          renewed,
+        ),
+      );
+      return new Response(null, { status: 204, headers });
+    }
+
     await (deps.disableDraft ?? (() => nextDraft(false)))();
     const secure = new URL(req.url).protocol === "https:";
     const headers = new Headers();

package/src/site-editor.tsx

@@ -3,8 +3,21 @@
 
 import { usePathname, useRouter } from "next/navigation";
 import { startTransition, useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import {
+  DEVBAR_CLASS,
+  DEVBAR_CLEARANCE,
+  DEVBAR_ENTER_CSS,
+  DEVBAR_RIGHT,
+  devbarShellStyle,
+} from "./devbar-motion";
+import { markerCookie } from "./gate";
 import { subscribeSiteDoc } from "./site-doc-bridge";
 import { readSiteDoc, sameSiteDoc, type SiteDocRef } from "./site-doc";
+import { installSitePointer } from "./site-pointer";
+
+const DEFAULT_PREVIEW_ENTRY_PATH = "/api/backmatter/preview";
+/** Slide the 12h site session while the bar is on screen. */
+const SESSION_RENEW_MS = 30 * 60 * 1000;
 
 function useSiteDoc(): SiteDocRef | null {
   const pathname = usePathname();
@@ -51,6 +64,7 @@ export function SiteChrome({
   exiting,
   onExit,
   studioPath = DEFAULT_STUDIO_PATH,
+  previewEntryPath = DEFAULT_PREVIEW_ENTRY_PATH,
 }: {
   branch?: string;
   tree?: string;
@@ -58,12 +72,13 @@ export function SiteChrome({
   onExit: () => void;
   /** Where `@backmatter/studio` is mounted on this site. */
   studioPath?: string;
+  /** Ticket route. `POST ?renew=1` slides the site session. A 401 drops the bar. */
+  previewEntryPath?: string;
 }) {
   const router = useRouter();
   const doc = useSiteDoc();
   const [editorMounted, setEditorMounted] = useState(false);
   const [editorOpen, setEditorOpen] = useState(false);
-  const [chatMounted, setChatMounted] = useState(false);
   const [chatOpen, setChatOpen] = useState(false);
   const [publishOpen, setPublishOpen] = useState(false);
   const [changeCount, setChangeCount] = useState(0);
@@ -80,7 +95,6 @@ export function SiteChrome({
     function onKey(event: KeyboardEvent) {
       if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== "j") return;
       event.preventDefault();
-      setChatMounted(true);
       setChatOpen((open) => !open);
     }
     document.addEventListener("keydown", onKey, true);
@@ -105,7 +119,6 @@ export function SiteChrome({
         data.key?.toLowerCase() === "j" &&
         (data.metaKey || data.ctrlKey)
       ) {
-        setChatMounted(true);
         setChatOpen((open) => !open);
       }
       if (data?.type === "backmatter:published") {
@@ -119,6 +132,48 @@ export function SiteChrome({
     return () => window.removeEventListener("message", onMessage);
   }, [origin, router]);
 
+  useEffect(() => {
+    let stopped = false;
+    let left = false;
+    function leaveEditor() {
+      if (left || stopped) return;
+      left = true;
+      void (async () => {
+        try {
+          await fetch(previewEntryPath, { method: "POST", credentials: "same-origin", cache: "no-store" });
+        } catch {
+          // The cookies expire on their own. Still drop the bar.
+        }
+        document.cookie = markerCookie(false, location.protocol === "https:");
+        location.reload();
+      })();
+    }
+    async function renew() {
+      try {
+        const res = await fetch(`${previewEntryPath}?renew=1`, {
+          method: "POST",
+          credentials: "same-origin",
+          cache: "no-store",
+        });
+        if (res.status === 401) leaveEditor();
+      } catch {
+        // Offline. The next send, or the next interval, tries again.
+      }
+    }
+    void renew();
+    const timer = setInterval(() => void renew(), SESSION_RENEW_MS);
+    function onExpired(event: MessageEvent) {
+      if (event.origin !== origin) return;
+      if (event.data?.type === "backmatter:session-expired") leaveEditor();
+    }
+    window.addEventListener("message", onExpired);
+    return () => {
+      stopped = true;
+      clearInterval(timer);
+      window.removeEventListener("message", onExpired);
+    };
+  }, [origin, previewEntryPath]);
+
   const label = doc ? `${doc.type}/${doc.slug}` : "No document";
   const editorSrc =
     doc && base
@@ -132,7 +187,33 @@ export function SiteChrome({
 
   return (
     <>
-      <style>{"body{padding-bottom:36px}"}</style>
+      <style>{`
+        ${DEVBAR_ENTER_CSS}
+        @media (hover: hover) {
+          .${DEVBAR_CLASS} button:hover:not(:disabled) {
+            background: #f4f4f5;
+          }
+        }
+        .${DEVBAR_CLASS} button:focus-visible {
+          outline: 2px solid #18181b;
+          outline-offset: 2px;
+        }
+        .${DEVBAR_CLASS} button:disabled {
+          cursor: default;
+          opacity: 0.5;
+        }
+        html.backmatter-pointing,
+        html.backmatter-pointing * {
+          cursor: crosshair !important;
+        }
+        html.backmatter-pointing .${DEVBAR_CLASS},
+        html.backmatter-pointing .${DEVBAR_CLASS} * {
+          cursor: pointer !important;
+        }
+        html.backmatter-pointing .${DEVBAR_CLASS} button:disabled {
+          cursor: default !important;
+        }
+      `}</style>
       {editorMounted && doc && editorSrc ? (
         <iframe
           ref={editorFrame}
@@ -145,7 +226,7 @@ export function SiteChrome({
           }}
         />
       ) : null}
-      {chatMounted && doc ? (
+      {doc && base ? (
         <CmsChat
           doc={doc}
           hidden={!chatOpen}
@@ -165,7 +246,7 @@ export function SiteChrome({
           }}
         />
       ) : null}
-      <footer aria-label="Backmatter" style={barStyle}>
+      <footer aria-label="Backmatter" className={DEVBAR_CLASS} style={barStyle}>
         <button
           type="button"
           aria-pressed={editorOpen}
@@ -181,17 +262,13 @@ export function SiteChrome({
         <BarText>Preview</BarText>
         {branch ? <BarText>{branch}</BarText> : null}
         {tree ? <BarText>draft</BarText> : null}
-        <span style={{ flex: 1 }} />
         <button type="button" aria-pressed={publishOpen} onClick={() => setPublishOpen((open) => !open)} style={barButton}>
           Publish{changeCount ? ` ${changeCount}` : ""}
         </button>
         <button
           type="button"
           aria-pressed={chatOpen}
-          onClick={() => {
-            setChatMounted(true);
-            setChatOpen((open) => !open);
-          }}
+          onClick={() => setChatOpen((open) => !open)}
           title="Toggle AI chat (⌘J)"
           style={barButton}
         >
@@ -239,6 +316,9 @@ function CmsChat({
     if (!hidden) openChat();
   }, [hidden, origin]);
 
+  const docRef = useRef(doc);
+  docRef.current = doc;
+
   useEffect(() => {
     const focus = { locale: doc.locale, type: doc.type, slug: doc.slug };
     function postFocus() {
@@ -258,6 +338,41 @@ function CmsChat({
     return () => window.removeEventListener("message", onMessage);
   }, [doc.locale, doc.type, doc.slug, origin]);
 
+  useEffect(() => {
+    if (!origin) return;
+    const pointer = installSitePointer(document, {
+      bar: () => document.querySelector(`.${DEVBAR_CLASS}`),
+      ignore: (target) => {
+        if (!(target instanceof Element)) return true;
+        const frameEl = frame.current;
+        if (frameEl && (target === frameEl || frameEl.contains(target))) return true;
+        return target.closest("iframe") !== null;
+      },
+      onGrab: (grab) => {
+        frame.current?.contentWindow?.postMessage(
+          { type: "backmatter:pointer-grab", grab, doc: docRef.current },
+          origin,
+        );
+      },
+      onEscape: () => {
+        frame.current?.contentWindow?.postMessage({ type: "backmatter:pointer", on: false }, origin);
+      },
+    });
+    function onMessage(event: MessageEvent) {
+      if (event.origin !== origin || event.source !== frame.current?.contentWindow) return;
+      const data = event.data as { type?: string; on?: boolean };
+      if (data?.type !== "backmatter:pointer" || typeof data.on !== "boolean") return;
+      if (data.on && !hiddenRef.current) pointer.arm();
+      else pointer.disarm();
+    }
+    window.addEventListener("message", onMessage);
+    return () => {
+      window.removeEventListener("message", onMessage);
+      pointer.dispose();
+      frame.current?.contentWindow?.postMessage({ type: "backmatter:pointer", on: false }, origin);
+    };
+  }, [origin, hidden]);
+
   if (!base) return null;
   return (
     <iframe
@@ -278,48 +393,51 @@ function BarText({ children }: { children: ReactNode }) {
 }
 
 const barStyle: CSSProperties = {
-  position: "fixed",
-  left: 0,
-  right: 0,
-  bottom: 0,
-  zIndex: 2147483000,
-  display: "flex",
-  alignItems: "center",
-  gap: 12,
-  height: 36,
-  padding: "0 12px",
-  paddingBottom: "env(safe-area-inset-bottom, 0px)",
-  boxSizing: "border-box",
-  borderTop: "1px solid #e4e4e7",
-  background: "#f4f4f5",
-  color: "#71717a",
-  font: "12px/1 ui-sans-serif, system-ui, sans-serif",
+  ...devbarShellStyle,
+  gap: 2,
+  padding: "0 6px 0 10px",
+  font: '12px/1 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
 };
 
 const barButton: CSSProperties = {
   border: 0,
+  borderRadius: 8,
   background: "transparent",
   color: "#18181b",
   font: "inherit",
   cursor: "pointer",
-  padding: "4px 6px",
+  padding: "0 10px",
+  minHeight: 44,
 };
 
 const docButton: CSSProperties = {
   ...barButton,
   fontWeight: 600,
+  maxWidth: 200,
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
 };
 
-const mutedStyle: CSSProperties = { color: "#71717a", fontSize: 12, margin: 0 };
+const mutedStyle: CSSProperties = {
+  color: "#71717a",
+  fontSize: 12,
+  margin: 0,
+  padding: "0 6px",
+  maxWidth: 140,
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+};
 
 const editorStyle: CSSProperties = {
   position: "fixed",
   left: 0,
   right: 0,
-  bottom: 36,
+  bottom: DEVBAR_CLEARANCE,
   zIndex: 2147482999,
   width: "100%",
-  height: "min(78vh, calc(100vh - 48px))",
+  height: "min(78vh, calc(100vh - 104px))",
   border: 0,
   borderTop: "1px solid #e4e4e7",
   background: "#ffffff",
@@ -328,11 +446,11 @@ const editorStyle: CSSProperties = {
 
 const chatStyle: CSSProperties = {
   position: "fixed",
-  right: 12,
-  bottom: 48,
+  right: DEVBAR_RIGHT,
+  bottom: DEVBAR_CLEARANCE,
   zIndex: 2147483001,
-  width: "min(440px, calc(100vw - 24px))",
-  height: "min(640px, calc(100vh - 120px))",
+  width: "min(440px, calc(100vw - 32px))",
+  height: "min(640px, calc(100vh - 148px))",
   border: 0,
   borderRadius: 14,
   background: "#f4f4f5",
@@ -341,11 +459,11 @@ const chatStyle: CSSProperties = {
 
 const publishStyle: CSSProperties = {
   position: "fixed",
-  right: 12,
-  bottom: 48,
+  right: DEVBAR_RIGHT,
+  bottom: DEVBAR_CLEARANCE,
   zIndex: 2147483001,
-  width: "min(420px, calc(100vw - 24px))",
-  height: "min(520px, calc(100vh - 120px))",
+  width: "min(420px, calc(100vw - 32px))",
+  height: "min(520px, calc(100vh - 148px))",
   border: "1px solid #e4e4e7",
   borderRadius: 8,
   background: "#ffffff",

package/src/site-pointer.ts

@@ -0,0 +1,199 @@
+// packages/next/src/site-pointer.ts
+// Hit-test a click on the host page and draw the armed pointer outline.
+
+export const POINTER_QUOTE_MAX = 240;
+
+export type PointerGrab = {
+  blockId: string | null;
+  blockType: string | null;
+  blockIndex: number | null;
+  quote: string;
+};
+
+function quoteOf(target: Element): string {
+  return (target.textContent ?? "").replace(/\s+/g, " ").trim().slice(0, POINTER_QUOTE_MAX);
+}
+
+function presentAttr(el: Element, name: string): string | null {
+  const value = el.getAttribute(name);
+  return value ? value : null;
+}
+
+/** Resolve the block marker and visible text under a click. Clicks on the bar are ignored. */
+export function grabAt(target: Element | null, bar: Element | null): PointerGrab | null {
+  if (!target) return null;
+  const doc = target.ownerDocument;
+  if (target === doc.documentElement || target === doc.body) return null;
+  if (bar && (target === bar || bar.contains(target))) return null;
+  if (target.closest("[data-backmatter-pointer]")) return null;
+
+  const marker = target.closest("[data-backmatter-block]");
+  const quote = quoteOf(target);
+  if (!marker) {
+    if (!quote) return null;
+    return { blockId: null, blockType: null, blockIndex: null, quote };
+  }
+  const indexRaw = marker.getAttribute("data-backmatter-index");
+  const blockIndex = indexRaw !== null && /^\d+$/.test(indexRaw) ? Number(indexRaw) : null;
+  return {
+    blockId: presentAttr(marker, "data-backmatter-block"),
+    blockType: presentAttr(marker, "data-backmatter-type"),
+    blockIndex,
+    quote,
+  };
+}
+
+export type SitePointer = {
+  arm: () => void;
+  disarm: () => void;
+  dispose: () => void;
+};
+
+/**
+ * While armed, the page shows a crosshair and an outline. A click reports the
+ * element and does not follow links. Escape disarms. The picker stays armed
+ * after a click so another element can be added.
+ */
+export function installSitePointer(
+  doc: Document,
+  options: {
+    bar: () => Element | null;
+    ignore?: (target: EventTarget | null) => boolean;
+    onGrab: (grab: PointerGrab) => void;
+    onEscape?: () => void;
+  },
+): SitePointer {
+  let armed = false;
+  let current: Element | null = null;
+  let outline: HTMLDivElement | null = null;
+  const root = doc.documentElement;
+
+  function ignored(target: EventTarget | null): boolean {
+    if (!(target instanceof Element)) return true;
+    if (target === root || target === doc.body) return true;
+    if (target.closest("[data-backmatter-pointer]")) return true;
+    const bar = options.bar();
+    if (bar && (target === bar || bar.contains(target))) return true;
+    return options.ignore?.(target) ?? false;
+  }
+
+  function ensureOutline(): HTMLDivElement {
+    if (outline?.isConnected) return outline;
+    outline?.remove();
+    outline = null;
+    const el = doc.createElement("div");
+    el.setAttribute("data-backmatter-pointer", "");
+    el.style.position = "fixed";
+    el.style.pointerEvents = "none";
+    el.style.zIndex = "2147482980";
+    el.style.boxSizing = "border-box";
+    el.style.border = "1.5px solid #18181b";
+    el.style.borderRadius = "4px";
+    el.style.background = "rgba(24, 24, 27, 0.06)";
+    const label = doc.createElement("div");
+    label.setAttribute("data-backmatter-pointer-label", "");
+    label.style.position = "absolute";
+    label.style.left = "0";
+    label.style.top = "0";
+    label.style.maxWidth = "240px";
+    label.style.overflow = "hidden";
+    label.style.textOverflow = "ellipsis";
+    label.style.whiteSpace = "nowrap";
+    label.style.padding = "2px 6px";
+    label.style.borderRadius = "4px";
+    label.style.background = "#18181b";
+    label.style.color = "#ffffff";
+    label.style.font = '11px/1.4 ui-sans-serif, system-ui, sans-serif';
+    label.style.display = "none";
+    el.appendChild(label);
+    doc.body.appendChild(el);
+    outline = el;
+    return el;
+  }
+
+  function place(target: Element | null) {
+    current = target;
+    if (!target) {
+      if (outline) outline.style.display = "none";
+      return;
+    }
+    const el = ensureOutline();
+    const rect = target.getBoundingClientRect();
+    if (rect.width < 1 && rect.height < 1) {
+      el.style.display = "none";
+      return;
+    }
+    el.style.display = "block";
+    el.style.left = `${rect.left}px`;
+    el.style.top = `${rect.top}px`;
+    el.style.width = `${rect.width}px`;
+    el.style.height = `${rect.height}px`;
+    const label = el.firstElementChild as HTMLElement | null;
+    const name = target.closest("[data-backmatter-block]")?.getAttribute("data-backmatter-type") ?? "";
+    if (!label) return;
+    if (!name) {
+      label.textContent = "";
+      label.style.display = "none";
+      return;
+    }
+    label.textContent = name;
+    label.style.display = "block";
+    label.style.transform = rect.top < 28 ? "none" : "translateY(calc(-100% - 4px))";
+  }
+
+  function onMove(event: PointerEvent) {
+    const target = event.target instanceof Element ? event.target : null;
+    place(target && !ignored(target) ? target : null);
+  }
+
+  function onScroll() {
+    if (current && !ignored(current)) place(current);
+    else place(null);
+  }
+
+  function onClick(event: MouseEvent) {
+    if (!armed || ignored(event.target)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const target = event.target instanceof Element ? event.target : null;
+    const grab = grabAt(target, options.bar());
+    if (grab) options.onGrab(grab);
+  }
+
+  function onKey(event: KeyboardEvent) {
+    if (!armed || event.key !== "Escape") return;
+    event.preventDefault();
+    event.stopPropagation();
+    disarm();
+    options.onEscape?.();
+  }
+
+  function arm() {
+    if (armed) return;
+    armed = true;
+    root.classList.add("backmatter-pointing");
+    doc.addEventListener("pointermove", onMove, true);
+    doc.addEventListener("scroll", onScroll, true);
+    doc.addEventListener("click", onClick, true);
+    doc.addEventListener("keydown", onKey, true);
+  }
+
+  function disarm() {
+    if (!armed) return;
+    armed = false;
+    current = null;
+    root.classList.remove("backmatter-pointing");
+    doc.removeEventListener("pointermove", onMove, true);
+    doc.removeEventListener("scroll", onScroll, true);
+    doc.removeEventListener("click", onClick, true);
+    doc.removeEventListener("keydown", onKey, true);
+    outline?.remove();
+    outline = null;
+  }
+
+  return {
+    arm,
+    disarm,
+    dispose: disarm,
+  };
+}

package/src/studio-client.tsx

@@ -24,6 +24,32 @@ export type StudioMountProps = {
 
 type SiteStudioComponent = ComponentType<StudioMountProps>;
 
+const fallbackStyle = {
+  minHeight: "100dvh",
+  display: "grid",
+  placeItems: "center",
+  fontFamily: "ui-sans-serif, system-ui, sans-serif",
+  color: "#71717a",
+} as const;
+
+const SESSION_EXPIRED_MESSAGE = "backmatter:session-expired";
+
+/**
+ * Rendered instead of redirecting to the dashboard. A frame tells the parent
+ * to drop the bar. The top window goes to `enterUrl` to sign in.
+ */
+export function StudioSignedOut({ enterUrl }: { enterUrl: string }) {
+  useEffect(() => {
+    const framed = Boolean(window.top && window.top !== window);
+    if (framed) {
+      window.parent.postMessage({ type: SESSION_EXPIRED_MESSAGE }, window.location.origin);
+      return;
+    }
+    window.location.assign(enterUrl);
+  }, [enterUrl]);
+  return <div style={fallbackStyle} aria-busy="true" />;
+}
+
 export function StudioMount(props: StudioMountProps) {
   const [Studio, setStudio] = useState<SiteStudioComponent | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -52,11 +78,3 @@ export function StudioMount(props: StudioMountProps) {
   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

@@ -10,8 +10,8 @@
 //   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.
+// session cookie. Without a session, a frame tells the parent page and a
+// top-level visit goes to the dashboard `enter` route.
 import { Suspense, type ReactNode } from "react";
 import {
   PREVIEW_SESSION_COOKIE,
@@ -23,7 +23,7 @@ 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";
+import { StudioMount, StudioSignedOut } from "./studio-client";
 
 export { requestUrlFrom };
 
@@ -50,21 +50,22 @@ type NextHeaders = {
   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}`;
 }
 
+type StudioPageProps = {
+  params: Promise<{ path?: string[] }> | { path?: string[] };
+  searchParams?:
+    | Promise<Record<string, string | string[] | undefined>>
+    | Record<string, string | string[] | undefined>;
+};
+
 export function createStudioPage(
   cms: Pick<BackmatterClient, "config">,
   options: StudioPageOptions = {},
@@ -73,14 +74,18 @@ export function createStudioPage(
   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>;
-  }) {
+  function requireWorkspaceId(): string {
     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)");
     }
+    return workspaceId;
+  }
+
+  // Cookie and header reads stay in this child. The page returns Suspense
+  // first so Cache Components can prerender the route shell.
+  async function StudioSession(props: StudioPageProps & { workspaceId: string }) {
+    const { workspaceId } = props;
     const dashboardUrl = resolveDashboardUrl(options.dashboardUrl);
     const { cookies, headers } = await nextHeaders();
     const [cookieStore, headerStore] = await Promise.all([cookies(), headers()]);
@@ -102,8 +107,7 @@ export function createStudioPage(
         (name) => headerStore.get(name),
         studioPathFor(basePath, params.path, searchText),
       );
-      const { redirect } = await nextNavigation();
-      redirect(studioEnterUrl(dashboardUrl, { workspaceId, returnUrl }));
+      return <StudioSignedOut enterUrl={studioEnterUrl(dashboardUrl, { workspaceId, returnUrl })} />;
     }
 
     return (
@@ -118,6 +122,15 @@ export function createStudioPage(
         studio={options.studio}
       />
     );
+  }
+
+  return function StudioPage(props: StudioPageProps) {
+    const workspaceId = requireWorkspaceId();
+    return (
+      <Suspense fallback={null}>
+        <StudioSession {...props} workspaceId={workspaceId} />
+      </Suspense>
+    );
   };
 }
 
@@ -133,7 +146,7 @@ export function StudioLayout({ children }: { children: ReactNode }) {
         <script dangerouslySetInnerHTML={{ __html: THEME_BOOT }} />
       </head>
       <body style={{ margin: 0 }}>
-        {/* The page reads cookies; with Cache Components that must sit under Suspense. */}
+        {/* The page suspends on the session. This boundary keeps the document shell outside that hole. */}
         <Suspense fallback={null}>{children}</Suspense>
       </body>
     </html>