@backmatter/next 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "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.2"
   },
   "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,20 +1,34 @@
 // 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,
   fetchHostPreviewSession,
   resolveDevMode,
   type CmsSessionUser,
+  type HostSessionReason,
 } from "@backmatter/core/preview";
+import {
+  ENTER_ATTEMPT_KEY,
+  enterPath,
+  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 })));
 
 export type { CmsSessionUser };
 
 export type DevModeState =
-  | { status: "hidden" }
+  | { status: "hidden"; reason?: HostSessionReason }
   | {
       status: "ready";
       user?: CmsSessionUser;
@@ -23,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",
@@ -66,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 = {
@@ -140,8 +151,8 @@ const exitButtonStyle: CSSProperties = {
   fontFamily: "inherit",
   fontSize: 11,
   fontWeight: 500,
-  lineHeight: "32px",
-  minHeight: 32,
+  lineHeight: "44px",
+  minHeight: 44,
   touchAction: "manipulation",
   WebkitFontSmoothing: "antialiased",
 };
@@ -206,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; }
         }
@@ -276,8 +288,102 @@ export function DevBarView({
   );
 }
 
-export function DevBarClient({ apiUrl }: { apiUrl: string }) {
-  const state = useDevMode({ apiUrl });
+const DEFAULT_PREVIEW_ENTRY_PATH = "/api/backmatter/preview";
+
+type Gate = "closed" | "resume" | "enter";
+
+/**
+ * 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");
+
+  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:";
+    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(explicit ? "enter" : "resume");
+      return;
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (!isGateShortcut(e)) return;
+      e.preventDefault();
+      document.cookie = markerCookie(true, secure);
+      setGate("enter");
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  return gate;
+}
+
+/**
+ * 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 === "closed") return;
+    let cancelled = false;
+    void loadDevModeState("").then((next) => {
+      if (cancelled) return;
+      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 (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.removeItem(ENTER_ATTEMPT_KEY);
+      document.cookie = markerCookie(false, location.protocol === "https:");
+      setState({ status: "hidden", reason });
+    });
+    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 +392,20 @@ 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}
+          previewEntryPath={previewEntryPath}
+        />
+      </Suspense>
+    );
   }
   return <DevBarView state={state} exiting={exiting} onExit={exit} />;
 }

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,12 +8,33 @@ export {
   devModeState,
   exitHostPreview,
   loadDevModeState,
+  sessionGateAction,
   useDevMode,
   type CmsSessionUser,
   type DevModeState,
+  type SessionGateAction,
 } 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. 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.
+ */
+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/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);