@backmatter/studio 0.0.3 → 0.0.5

package/src/site-pointer.ts

@@ -0,0 +1,271 @@
+// packages/studio/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 = createPointerOutline(doc);
+    return outline;
+  }
+
+  function place(target: Element | null) {
+    current = target;
+    if (!target) {
+      if (outline) outline.style.display = "none";
+      return;
+    }
+    positionPointerOutline(ensureOutline(), target);
+  }
+
+  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,
+  };
+}
+
+function createPointerOutline(doc: Document): HTMLDivElement {
+  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);
+  return el;
+}
+
+function positionPointerOutline(outline: HTMLDivElement, target: Element) {
+  const rect = target.getBoundingClientRect();
+  if (rect.width < 1 && rect.height < 1) {
+    outline.style.display = "none";
+    return;
+  }
+  outline.style.display = "block";
+  outline.style.left = `${rect.left}px`;
+  outline.style.top = `${rect.top}px`;
+  outline.style.width = `${rect.width}px`;
+  outline.style.height = `${rect.height}px`;
+  const label = outline.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 isSiteChrome(el: Element): boolean {
+  return el.closest("[data-backmatter-panel], .backmatter-devbar, [data-backmatter-pointer]") !== null;
+}
+
+/** The page element a stored pointer refers to. Chat chrome is ignored. */
+export function findPointedElement(
+  doc: Document,
+  pointer: { blockId: string | null; quote: string },
+): Element | null {
+  if (pointer.blockId) {
+    for (const el of doc.querySelectorAll("[data-backmatter-block]")) {
+      if (el.getAttribute("data-backmatter-block") !== pointer.blockId) continue;
+      if (!isSiteChrome(el)) return el;
+    }
+  }
+  const quote = pointer.quote.replace(/\s+/g, " ").trim();
+  if (quote.length < 2) return null;
+  let best: Element | null = null;
+  let bestLen = Infinity;
+  for (const el of doc.querySelectorAll("[data-backmatter-block]")) {
+    if (isSiteChrome(el)) continue;
+    const text = (el.textContent ?? "").replace(/\s+/g, " ");
+    if (!text.includes(quote) || text.length >= bestLen) continue;
+    best = el;
+    bestLen = text.length;
+  }
+  return best;
+}
+
+let hoverOutline: HTMLDivElement | null = null;
+let hoverTarget: Element | null = null;
+let hoverDoc: Document | null = null;
+
+function repositionHover() {
+  if (!hoverOutline || !hoverTarget) return;
+  positionPointerOutline(hoverOutline, hoverTarget);
+}
+
+/** Outline a page element while a pointer chip is hovered. Pass null to clear. */
+export function highlightPointedElement(doc: Document, target: Element | null) {
+  if (!target) {
+    hoverOutline?.remove();
+    hoverOutline = null;
+    hoverTarget = null;
+    if (hoverDoc) {
+      hoverDoc.removeEventListener("scroll", repositionHover, true);
+      hoverDoc.defaultView?.removeEventListener("resize", repositionHover);
+      hoverDoc = null;
+    }
+    return;
+  }
+  const sameDoc = hoverDoc === doc;
+  if (!sameDoc) highlightPointedElement(doc, null);
+  hoverDoc = doc;
+  hoverTarget = target;
+  if (!hoverOutline?.isConnected) hoverOutline = createPointerOutline(doc);
+  if (!sameDoc) {
+    doc.addEventListener("scroll", repositionHover, true);
+    doc.defaultView?.addEventListener("resize", repositionHover);
+  }
+  target.scrollIntoView({ block: "nearest", inline: "nearest" });
+  requestAnimationFrame(() => {
+    if (hoverTarget === target && hoverOutline) positionPointerOutline(hoverOutline, target);
+  });
+}

package/src/site-widget.tsx

@@ -0,0 +1,395 @@
+// packages/studio/src/site-widget.tsx
+// The on-site bar: agent and publish in one tree. The host page mounts this
+// after the site session verifies. Calls go through the host's same-origin
+// CMS proxy.
+import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import * as stylex from "@stylexjs/stylex";
+import { ChatPanel } from "./chat/ChatPanel";
+import { PublishIcon, SparkIcon } from "./chat/icons";
+import { chatPointerFromGrab } from "./chat/chat-context";
+import { POINTER_ARM_EVENT } from "./chat/Composer";
+import { ChatProvider, ChatSessionScope, useChatUI } from "./chat/ChatProvider";
+import { isPanelVisible } from "./chat/chat-state";
+import { DOC_CHANGED_EVENT, EditorFocusProvider, useEditorFocus } from "./chrome/EditorFocusContext";
+import { matchAppHotkey, modifierSymbol } from "./chrome/hotkeys";
+import { EmbedPublishPage } from "./pages/EmbedPublishPage";
+import { installSitePointer } from "./site-pointer";
+import { lightTheme } from "./styles/themes";
+import { configureStudio } from "./studio-config";
+import { applyThemeClass } from "./theme/apply-theme-class";
+import { TooltipProvider } from "./ui/Tooltip";
+
+export type SiteWidgetDoc = {
+  locale: string;
+  type: string;
+  slug: string;
+  workspaceId: string;
+};
+
+export type SiteWidgetProps = {
+  doc: SiteWidgetDoc | null;
+  branch?: string;
+  tree?: string;
+  exiting?: boolean;
+  onExit: () => void;
+  /** The host re-renders the page after a write. */
+  onDocChanged?: () => void;
+  /** The site session was rejected. The host drops the widget. */
+  onSessionExpired?: () => void;
+  /** Same-origin CMS proxy. Default `/api/backmatter/cms`. */
+  proxyPath?: string;
+  version?: string;
+};
+
+const DEVBAR_CLASS = "backmatter-devbar";
+
+export function SiteWidget({
+  doc,
+  branch,
+  tree,
+  exiting,
+  onExit,
+  onDocChanged,
+  onSessionExpired,
+  proxyPath = "/api/backmatter/cms",
+  version,
+}: SiteWidgetProps) {
+  const expiredRef = useRef(onSessionExpired);
+  expiredRef.current = onSessionExpired;
+  useState(() => {
+    configureStudio({
+      baseUrl: proxyPath.replace(/\/+$/, ""),
+      credentials: "same-origin",
+      dev: false,
+      version,
+      onUnauthorized: ({ status }) => {
+        if (status === 401) expiredRef.current?.();
+      },
+    });
+    return true;
+  });
+
+  useLayoutEffect(() => {
+    return applyThemeClass(document.documentElement, stylex.props(lightTheme).className);
+  }, []);
+
+  const [chatOpen, setChatOpen] = useState(false);
+  const [publishOpen, setPublishOpen] = useState(false);
+  const [changeCount, setChangeCount] = useState(0);
+  const label = doc ? `${doc.type}/${doc.slug}` : "No document";
+
+  function wrote() {
+    onDocChanged?.();
+  }
+
+  useEffect(() => {
+    function onKey(event: KeyboardEvent) {
+      if (matchAppHotkey(event) !== "chat") return;
+      event.preventDefault();
+      setPublishOpen(false);
+      setChatOpen((open) => !open);
+    }
+    document.addEventListener("keydown", onKey, true);
+    return () => document.removeEventListener("keydown", onKey, true);
+  }, []);
+
+  const bar = (
+    <footer aria-label="Backmatter" className={DEVBAR_CLASS} style={barStyle}>
+      <span style={docLabel}>{label}</span>
+      <BarText>Preview</BarText>
+      {branch ? <BarText>{branch}</BarText> : null}
+      {tree ? <BarText>draft</BarText> : null}
+      <button
+        type="button"
+        className={`${DEVBAR_CLASS}-btn${publishOpen ? ` ${DEVBAR_CLASS}-on` : ""}`}
+        aria-pressed={publishOpen}
+        disabled={!doc}
+        onClick={() => {
+          setChatOpen(false);
+          setPublishOpen((open) => !open);
+        }}
+      >
+        <PublishIcon />
+        <span>Publish{changeCount ? ` ${changeCount}` : ""}</span>
+      </button>
+      <button
+        type="button"
+        className={`${DEVBAR_CLASS}-btn ${DEVBAR_CLASS}-agent${chatOpen ? ` ${DEVBAR_CLASS}-on` : ""}`}
+        aria-pressed={chatOpen}
+        aria-keyshortcuts="Meta+J Control+J"
+        disabled={!doc}
+        onClick={() => {
+          setPublishOpen(false);
+          setChatOpen((open) => !open);
+        }}
+      >
+        <SparkIcon />
+        <span>Agent</span>
+        <kbd>
+          {modifierSymbol()}J
+        </kbd>
+      </button>
+      <button type="button" aria-label="Exit preview" disabled={exiting} onClick={onExit} style={barButton}>
+        Exit
+      </button>
+    </footer>
+  );
+
+  return (
+    <>
+      <style>{BAR_CSS}</style>
+      {doc ? (
+        <TooltipProvider>
+          <EditorFocusProvider>
+            <ChatProvider workspaceId={doc.workspaceId} pointer>
+              <DocFocus doc={doc} />
+              <DocChanged onDocChanged={wrote} />
+              <ChatOpenSync open={chatOpen} />
+              <ChatCloseSync onClose={() => setChatOpen(false)} />
+              <SitePointer doc={doc} />
+              <ChatSessionScope>{chatOpen ? <ChatPanel site /> : null}</ChatSessionScope>
+            </ChatProvider>
+          </EditorFocusProvider>
+        </TooltipProvider>
+      ) : null}
+      {doc ? (
+        <div data-backmatter-panel="" hidden={!publishOpen} style={publishStyle}>
+          <EmbedPublishPage
+            workspaceId={doc.workspaceId}
+            onStatus={({ changeCount: count }) => setChangeCount(count)}
+            onPublished={() => {
+              setPublishOpen(false);
+              setChangeCount(0);
+              wrote();
+            }}
+          />
+        </div>
+      ) : null}
+      {bar}
+    </>
+  );
+}
+
+function DocFocus({ doc }: { doc: SiteWidgetDoc }) {
+  const { setFocus } = useEditorFocus();
+  useEffect(() => {
+    setFocus({
+      docRef: { locale: doc.locale, type: doc.type, slug: doc.slug },
+      frontmatter: {},
+      body: "",
+      selection: null,
+    });
+  }, [doc.locale, doc.type, doc.slug, setFocus]);
+  return null;
+}
+
+function DocChanged({ onDocChanged }: { onDocChanged: () => void }) {
+  const onDocChangedRef = useRef(onDocChanged);
+  onDocChangedRef.current = onDocChanged;
+  useEffect(() => {
+    function onDoc() {
+      onDocChangedRef.current();
+    }
+    window.addEventListener(DOC_CHANGED_EVENT, onDoc);
+    return () => window.removeEventListener(DOC_CHANGED_EVENT, onDoc);
+  }, []);
+  return null;
+}
+
+function ChatOpenSync({ open }: { open: boolean }) {
+  const { dispatch } = useChatUI();
+  useEffect(() => {
+    dispatch({ type: open ? "open" : "close" });
+    if (!open) return;
+    requestAnimationFrame(() => {
+      window.dispatchEvent(new Event("backmatter:chat-focus"));
+    });
+  }, [open, dispatch]);
+  return null;
+}
+
+function ChatCloseSync({ onClose }: { onClose: () => void }) {
+  const { panel } = useChatUI();
+  const mode = panel.mode;
+  const previous = useRef(mode);
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+  useEffect(() => {
+    const wasVisible = isPanelVisible(previous.current);
+    previous.current = mode;
+    if (wasVisible && !isPanelVisible(mode)) onCloseRef.current();
+  }, [mode]);
+  return null;
+}
+
+function SitePointer({ doc }: { doc: SiteWidgetDoc }) {
+  const { addPointer, panel } = useChatUI();
+  const visible = isPanelVisible(panel.mode);
+  const visibleRef = useRef(visible);
+  const docRef = useRef(doc);
+  visibleRef.current = visible;
+  docRef.current = doc;
+
+  useEffect(() => {
+    const pointer = installSitePointer(document, {
+      bar: () => document.querySelector(`.${DEVBAR_CLASS}`),
+      ignore: (target) => {
+        if (!(target instanceof Element)) return true;
+        if (target.closest("[data-backmatter-panel]")) return true;
+        return target.closest("iframe") !== null;
+      },
+      onGrab: (grab) => {
+        const next = chatPointerFromGrab(docRef.current, grab);
+        if (!next) return;
+        addPointer(next);
+        requestAnimationFrame(() => {
+          window.dispatchEvent(new Event("backmatter:chat-focus"));
+        });
+      },
+      onEscape: () => {
+        window.dispatchEvent(new CustomEvent(POINTER_ARM_EVENT, { detail: { on: false } }));
+      },
+    });
+    function onArm(event: Event) {
+      const on = (event as CustomEvent<{ on?: boolean }>).detail?.on;
+      if (on && visibleRef.current) pointer.arm();
+      else pointer.disarm();
+    }
+    window.addEventListener(POINTER_ARM_EVENT, onArm);
+    return () => {
+      window.removeEventListener(POINTER_ARM_EVENT, onArm);
+      pointer.dispose();
+    };
+  }, [addPointer]);
+
+  return null;
+}
+
+function BarText({ children }: { children: ReactNode }) {
+  return <span style={mutedStyle}>{children}</span>;
+}
+
+const barStyle: CSSProperties = {
+  position: "fixed",
+  right: "max(16px, env(safe-area-inset-right, 0px))",
+  bottom: 0,
+  zIndex: 2147483000,
+  isolation: "isolate",
+  display: "flex",
+  alignItems: "center",
+  gap: 2,
+  width: "max-content",
+  maxWidth: "calc(100vw - 32px)",
+  minHeight: 36,
+  padding: "0 6px 0 10px",
+  boxSizing: "border-box",
+  border: "1px solid #e4e4e7",
+  borderRadius: "12px 12px 0 0",
+  background: "#ffffff",
+  color: "#71717a",
+  boxShadow: "0 10px 28px rgba(24, 24, 27, 0.12), 0 1px 2px rgba(24, 24, 27, 0.06)",
+  font: '12px/1 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+  WebkitFontSmoothing: "antialiased",
+};
+
+const barButton: CSSProperties = {
+  border: 0,
+  borderRadius: 8,
+  background: "transparent",
+  color: "#18181b",
+  font: "inherit",
+  cursor: "pointer",
+  padding: "0 8px",
+  minHeight: 28,
+};
+
+const docLabel: CSSProperties = {
+  fontWeight: 600,
+  color: "#18181b",
+  maxWidth: 200,
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+  padding: "0 6px",
+};
+
+const mutedStyle: CSSProperties = {
+  color: "#71717a",
+  fontSize: 12,
+  margin: 0,
+  padding: "0 6px",
+  maxWidth: 140,
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+};
+
+const publishStyle: CSSProperties = {
+  position: "fixed",
+  right: "max(16px, env(safe-area-inset-right, 0px))",
+  bottom: "calc(env(safe-area-inset-bottom, 0px) + 48px)",
+  zIndex: 2147483001,
+  width: "min(320px, calc(100vw - 32px))",
+  maxHeight: "min(420px, calc(100vh - 80px))",
+  overflow: "auto",
+  border: "1px solid #e4e4e7",
+  borderRadius: 10,
+  background: "#ffffff",
+  boxShadow: "0 16px 40px rgba(24, 24, 27, 0.14), 0 2px 8px rgba(24, 24, 27, 0.06)",
+};
+
+const BAR_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; }
+}
+.${DEVBAR_CLASS}-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 26px;
+  margin-inline: 4px;
+  padding: 0 8px;
+  border: 1px solid #e4e4e7;
+  border-radius: 6px;
+  background: #ffffff;
+  color: #18181b;
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 1;
+  cursor: pointer;
+}
+.${DEVBAR_CLASS}-agent kbd {
+  font-family: Geist Mono, ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  font-weight: 400;
+  opacity: 0.7;
+}
+.${DEVBAR_CLASS} button.${DEVBAR_CLASS}-on,
+.${DEVBAR_CLASS} button.${DEVBAR_CLASS}-on:hover:not(:disabled) {
+  background: #18181b;
+  border-color: #18181b;
+  color: #fafafa;
+}
+@media (hover: hover) {
+  .${DEVBAR_CLASS} button:hover:not(:disabled) { background: #f4f4f5; }
+  .${DEVBAR_CLASS} button.${DEVBAR_CLASS}-btn:hover:not(:disabled) {
+    background: rgba(24, 24, 27, 0.05);
+  }
+  .${DEVBAR_CLASS} button.${DEVBAR_CLASS}-on:hover:not(:disabled) {
+    background: #18181b;
+  }
+}
+.${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} *,
+html.backmatter-pointing [data-backmatter-panel],
+html.backmatter-pointing [data-backmatter-panel] * { cursor: pointer !important; }
+html.backmatter-pointing .${DEVBAR_CLASS} button:disabled { cursor: default !important; }
+`;