@backmatter/next 0.0.25 → 0.0.27

package/dist/config.cjs

@@ -827,7 +827,12 @@ function withBackmatter(nextConfig = {}, options = {}) {
   ensureRegistryTsconfig(loaderOptions.root, loaderOptions.outDir);
   const cacheComponents = cfg.cacheComponents ?? true;
   const transpilePackages = [
-    ...new Set([...cfg.transpilePackages ?? [], "@backmatter/next", "@backmatter/core"])
+    ...new Set([
+      ...cfg.transpilePackages ?? [],
+      "@backmatter/next",
+      "@backmatter/core",
+      "@backmatter/studio"
+    ])
   ];
   return {
     ...nextConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
@@ -50,7 +50,7 @@
     "@backmatter/core": "^0.0.21",
     "@mdx-js/mdx": "^3.1.1",
     "remark-gfm": "^4.0.1",
-    "@backmatter/studio": "^0.0.3"
+    "@backmatter/studio": "^0.0.5"
   },
   "peerDependencies": {
     "next": ">=16.3.0",

package/src/config.ts

@@ -187,7 +187,12 @@ export function withBackmatter<T extends object>(
   // files with one shared shell for every CMS URL, so a normal link would
   // prefetch the shell instead of the finished page. Hosts can still opt in.
   const transpilePackages = [
-    ...new Set([...(cfg.transpilePackages ?? []), "@backmatter/next", "@backmatter/core"]),
+    ...new Set([
+      ...(cfg.transpilePackages ?? []),
+      "@backmatter/next",
+      "@backmatter/core",
+      "@backmatter/studio",
+    ]),
   ];
   return {
     ...nextConfig,

package/src/preview-hold.tsx

@@ -0,0 +1,39 @@
+// packages/next/src/preview-hold.tsx
+"use client";
+
+// A route refresh suspends the preview branch. Its Suspense fallback would
+// otherwise be empty for the whole fetch. The last painted preview is kept
+// here, outside that branch, and shown until the next one is ready.
+import { useEffect, useSyncExternalStore, type ReactNode } from "react";
+
+let held: ReactNode = null;
+const listeners = new Set<() => void>();
+
+function emit() {
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function clearHeldPreview() {
+  if (held === null) return;
+  held = null;
+  emit();
+}
+
+/** Remember the preview that just painted, so a later refresh can keep it. */
+export function HoldPreview({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    held = children;
+    emit();
+  }, [children]);
+  return children;
+}
+
+/** Suspense fallback: the previous preview, or nothing on the first load. */
+export function HeldPreview() {
+  return useSyncExternalStore(subscribe, () => held, () => null);
+}

package/src/routes.ts

@@ -4,6 +4,7 @@
 // `route` template (including `/` via indexSlug), loads it and renders MDX
 // or JSON pages. An optional catch-all is required so `/` is a CMS route.
 import { Fragment, Suspense, createElement, type ReactNode } from "react";
+import { HeldPreview, HoldPreview } from "./preview-hold";
 import {
   DEFAULT_TEMPLATE_SLUG,
   isRoutable,
@@ -425,15 +426,19 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     const preview = await resolvePreviewState(cms, options.preview, searchParams);
     if (!previewReplacesPublished(preview)) return null;
     return createElement(
-      Fragment,
+      HoldPreview,
       null,
-      createElement("style", {
-        dangerouslySetInnerHTML: {
-          __html: "[data-backmatter-published]{display:none!important}",
-        },
-      }),
-      docBridge(hit),
-      await loadPreviewDoc(hit, preview),
+      createElement(
+        Fragment,
+        null,
+        createElement("style", {
+          dangerouslySetInnerHTML: {
+            __html: "[data-backmatter-published]{display:none!important}",
+          },
+        }),
+        docBridge(hit),
+        await loadPreviewDoc(hit, preview),
+      ),
     );
   };
 
@@ -454,7 +459,7 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
       Fragment,
       null,
       createElement(PublishedRoute, props),
-      createElement(Suspense, { fallback: null }, createElement(PreviewBranch, props)),
+      createElement(Suspense, { fallback: createElement(HeldPreview) }, createElement(PreviewBranch, props)),
     );
 
   const generateMetadata: CatchAllRoute["generateMetadata"] = async ({ params }) => {

package/src/site-editor.tsx

@@ -1,19 +1,17 @@
 // packages/next/src/site-editor.tsx
+// Host adapter for the on-site widget. The widget import is the studio build
+// (`@backmatter/studio/widget` → dist), where StyleX is already compiled.
 "use client";
 
 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 { startTransition, useCallback, useEffect, useRef, useState } from "react";
+import "@backmatter/studio/studio.css";
+import studioPkg from "@backmatter/studio/package.json";
+import { SiteWidget } from "@backmatter/studio/widget";
 import { markerCookie } from "./gate";
+import { clearHeldPreview } from "./preview-hold";
 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. */
@@ -22,10 +20,23 @@ const SESSION_RENEW_MS = 30 * 60 * 1000;
 function useSiteDoc(): SiteDocRef | null {
   const pathname = usePathname();
   const [doc, setDoc] = useState<SiteDocRef | null>(null);
+  const pathRef = useRef(pathname);
+
+  useEffect(() => {
+    if (pathRef.current === pathname) return;
+    pathRef.current = pathname;
+    clearHeldPreview();
+    setDoc(null);
+  }, [pathname]);
 
   useEffect(() => {
     const apply = (next: SiteDocRef | null) => {
-      setDoc((prev) => (sameSiteDoc(prev, next) ? prev : next));
+      setDoc((prev) => {
+        // A refresh unmounts the doc marker for a moment. Keep the document
+        // the bar already has so the chat stays mounted across that gap.
+        if (!next) return prev;
+        return sameSiteDoc(prev, next) ? prev : next;
+      });
     };
     apply(readSiteDoc());
     const stop = subscribeSiteDoc(apply);
@@ -48,106 +59,41 @@ function useSiteDoc(): SiteDocRef | null {
 /** 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({
   branch,
   tree,
   exiting,
   onExit,
-  studioPath = DEFAULT_STUDIO_PATH,
   previewEntryPath = DEFAULT_PREVIEW_ENTRY_PATH,
 }: {
   branch?: string;
   tree?: string;
   exiting?: boolean;
   onExit: () => void;
-  /** Where `@backmatter/studio` is mounted on this site. */
+  /** Kept so existing hosts can still pass it. The bar does not open the document editor. */
   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 [chatOpen, setChatOpen] = useState(false);
-  const [publishOpen, setPublishOpen] = useState(false);
-  const [changeCount, setChangeCount] = useState(0);
-  // 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(() => {
-    setBase(studioBase(studioPath));
-  }, [studioPath]);
-
-  useEffect(() => {
-    function onKey(event: KeyboardEvent) {
-      if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== "j") return;
-      event.preventDefault();
-      setChatOpen((open) => !open);
-    }
-    document.addEventListener("keydown", onKey, true);
-    return () => document.removeEventListener("keydown", onKey, true);
-  }, []);
-
-  useEffect(() => {
-    function onMessage(event: MessageEvent) {
-      if (event.origin !== origin) return;
-      const data = event.data as {
-        type?: string;
-        changeCount?: number;
-        key?: string;
-        metaKey?: boolean;
-        ctrlKey?: boolean;
-      };
-      if (data?.type === "backmatter:git" && typeof data.changeCount === "number") {
-        setChangeCount(data.changeCount);
-      }
-      if (
-        data?.type === "backmatter:hotkey" &&
-        data.key?.toLowerCase() === "j" &&
-        (data.metaKey || data.ctrlKey)
-      ) {
-        setChatOpen((open) => !open);
-      }
-      if (data?.type === "backmatter:published") {
-        setPublishOpen(false);
-        setChangeCount(0);
-        editorFrame.current?.contentWindow?.postMessage({ type: "backmatter:reload-doc" }, origin);
-        startTransition(() => router.refresh());
+  const leaving = useRef(false);
+  const leave = useCallback(() => {
+    if (leaving.current) return;
+    leaving.current = 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.
       }
-    }
-    window.addEventListener("message", onMessage);
-    return () => window.removeEventListener("message", onMessage);
-  }, [origin, router]);
+      document.cookie = markerCookie(false, location.protocol === "https:");
+      location.reload();
+    })();
+  }, [previewEntryPath]);
 
   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`, {
@@ -155,16 +101,16 @@ export function SiteChrome({
           credentials: "same-origin",
           cache: "no-store",
         });
-        if (res.status === 401) leaveEditor();
+        if (!stopped && res.status === 401) leave();
       } catch {
-        // Offline. The next send, or the next interval, tries again.
+        // Offline. 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();
+      if (event.origin !== location.origin) return;
+      if (event.data?.type === "backmatter:session-expired") leave();
     }
     window.addEventListener("message", onExpired);
     return () => {
@@ -172,300 +118,18 @@ export function SiteChrome({
       clearInterval(timer);
       window.removeEventListener("message", onExpired);
     };
-  }, [origin, previewEntryPath]);
-
-  const label = doc ? `${doc.type}/${doc.slug}` : "No document";
-  const editorSrc =
-    doc && base
-      ? `${base}/workspaces/${doc.workspaceId}/docs/${doc.locale}/${doc.type}/${doc.slug}?embed=1`
-      : "";
-
-  function onChatWrote() {
-    editorFrame.current?.contentWindow?.postMessage({ type: "backmatter:reload-doc" }, origin);
-    startTransition(() => router.refresh());
-  }
+  }, [leave, previewEntryPath]);
 
   return (
-    <>
-      <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}
-          title={`Edit ${label}`}
-          src={editorSrc}
-          style={{
-            ...editorStyle,
-            visibility: editorOpen ? "visible" : "hidden",
-            pointerEvents: editorOpen ? "auto" : "none",
-          }}
-        />
-      ) : null}
-      {doc && base ? (
-        <CmsChat
-          doc={doc}
-          hidden={!chatOpen}
-          onWrote={onChatWrote}
-          onClosed={() => setChatOpen(false)}
-          base={base}
-        />
-      ) : null}
-      {doc && base ? (
-        <iframe
-          title="Publish"
-          src={`${base}/embed/publish/${doc.workspaceId}`}
-          style={{
-            ...publishStyle,
-            visibility: publishOpen ? "visible" : "hidden",
-            pointerEvents: publishOpen ? "auto" : "none",
-          }}
-        />
-      ) : null}
-      <footer aria-label="Backmatter" className={DEVBAR_CLASS} style={barStyle}>
-        <button
-          type="button"
-          aria-pressed={editorOpen}
-          disabled={!doc}
-          onClick={() => {
-            setEditorMounted(true);
-            setEditorOpen((open) => !open);
-          }}
-          style={docButton}
-        >
-          {label}
-        </button>
-        <BarText>Preview</BarText>
-        {branch ? <BarText>{branch}</BarText> : null}
-        {tree ? <BarText>draft</BarText> : null}
-        <button type="button" aria-pressed={publishOpen} onClick={() => setPublishOpen((open) => !open)} style={barButton}>
-          Publish{changeCount ? ` ${changeCount}` : ""}
-        </button>
-        <button
-          type="button"
-          aria-pressed={chatOpen}
-          onClick={() => setChatOpen((open) => !open)}
-          title="Toggle AI chat (⌘J)"
-          style={barButton}
-        >
-          Agent
-        </button>
-        <button type="button" aria-label="Exit preview" disabled={exiting} onClick={onExit} style={barButton}>
-          Exit
-        </button>
-      </footer>
-    </>
-  );
-}
-
-function CmsChat({
-  doc,
-  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);
-  const onClosedRef = useRef(onClosed);
-  const hiddenRef = useRef(hidden);
-  onWroteRef.current = onWrote;
-  onClosedRef.current = onClosed;
-  hiddenRef.current = hidden;
-  const origin = base ? new URL(base).origin : "";
-
-  function openChat() {
-    const frameEl = frame.current;
-    if (!frameEl) return;
-    frameEl.focus();
-    frameEl.contentWindow?.postMessage({ type: "backmatter:chat-open" }, origin);
-  }
-
-  useEffect(() => {
-    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() {
-      frame.current?.contentWindow?.postMessage({ type: "backmatter:focus", doc: focus }, origin);
-    }
-    function onMessage(event: MessageEvent) {
-      if (event.origin !== origin) return;
-      if (event.data?.type === "backmatter:chat-ready") {
-        postFocus();
-        if (!hiddenRef.current) openChat();
-      }
-      if (event.data?.type === "backmatter:doc-changed") onWroteRef.current();
-      if (event.data?.type === "backmatter:chat-closed") onClosedRef.current();
-    }
-    window.addEventListener("message", onMessage);
-    postFocus();
-    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
-      ref={frame}
-      title="AI chat"
-      src={`${base}/embed/chat/${doc.workspaceId}`}
-      style={{
-        ...chatStyle,
-        visibility: hidden ? "hidden" : "visible",
-        pointerEvents: hidden ? "none" : "auto",
-      }}
+    <SiteWidget
+      doc={doc}
+      branch={branch}
+      tree={tree}
+      exiting={exiting}
+      onExit={onExit}
+      onDocChanged={() => startTransition(() => router.refresh())}
+      onSessionExpired={leave}
+      version={studioPkg.version}
     />
   );
 }
-
-function BarText({ children }: { children: ReactNode }) {
-  return <span style={mutedStyle}>{children}</span>;
-}
-
-const barStyle: CSSProperties = {
-  ...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: "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,
-  padding: "0 6px",
-  maxWidth: 140,
-  overflow: "hidden",
-  textOverflow: "ellipsis",
-  whiteSpace: "nowrap",
-};
-
-const editorStyle: CSSProperties = {
-  position: "fixed",
-  left: 0,
-  right: 0,
-  bottom: DEVBAR_CLEARANCE,
-  zIndex: 2147482999,
-  width: "100%",
-  height: "min(78vh, calc(100vh - 104px))",
-  border: 0,
-  borderTop: "1px solid #e4e4e7",
-  background: "#ffffff",
-  boxShadow: "0 -8px 24px rgba(24, 24, 27, 0.08)",
-};
-
-const chatStyle: CSSProperties = {
-  position: "fixed",
-  right: DEVBAR_RIGHT,
-  bottom: DEVBAR_CLEARANCE,
-  zIndex: 2147483001,
-  width: "min(440px, calc(100vw - 32px))",
-  height: "min(640px, calc(100vh - 148px))",
-  border: 0,
-  borderRadius: 14,
-  background: "#f4f4f5",
-  boxShadow: "0 16px 48px rgba(0,0,0,0.22), 0 2px 8px rgba(0,0,0,0.08)",
-};
-
-const publishStyle: CSSProperties = {
-  position: "fixed",
-  right: DEVBAR_RIGHT,
-  bottom: DEVBAR_CLEARANCE,
-  zIndex: 2147483001,
-  width: "min(420px, calc(100vw - 32px))",
-  height: "min(520px, calc(100vh - 148px))",
-  border: "1px solid #e4e4e7",
-  borderRadius: 8,
-  background: "#ffffff",
-  boxShadow: "0 12px 40px rgba(24, 24, 27, 0.16)",
-};

package/src/site-pointer.ts

@@ -1,199 +0,0 @@
-// 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,
-  };
-}