@backmatter/studio 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/studio",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "The Backmatter editing surface: document editor, AI chat, publish. Mounted on your site or hosted on the dashboard.",
   "type": "module",
   "publishConfig": {
@@ -36,6 +36,10 @@
     "./site-widget.css": "./dist/site-widget.css",
     "./prose-ui-node-shim": "./prose-ui-node-shim.ts",
     "./package.json": "./package.json",
+    "./src/chat/pointer-arm": "./src/chat/pointer-arm.ts",
+    "./src/install-preview-pointer": "./src/install-preview-pointer.ts",
+    "./src/preview-pointer-host": "./src/preview-pointer-host.ts",
+    "./src/site-pointer": "./src/site-pointer.ts",
     "./src/*": "./src/*"
   },
   "files": [

package/src/api.ts

@@ -501,7 +501,7 @@ export function notifyTreeChanged(detail?: TreeChangeDetail) {
   );
 }
 
-/** Branch HEAD moved (teammate push, pull, commit); clean docs should reload. */
+/** Branch HEAD moved (teammate push, pull, commit). Clean docs reload their fields. The preview frame stays up. */
 export function notifyHeadChanged() {
   window.dispatchEvent(new Event("backmatter:head-changed"));
 }

package/src/chat/ChatProvider.tsx

@@ -88,8 +88,12 @@ export type ChatUIValue = {
   mentions: DocRef[];
   addMention: (ref: DocRef) => void;
   removeMention: (ref: DocRef) => void;
-  /** Elements pointed at on the host site. Only the dev bar chat sets `pointer`. */
+  /** Point button. The dev bar sets this, and the document editor turns it on when the preview can be pointed at. */
   pointer: boolean;
+  setPreviewPointer: (on: boolean) => void;
+  /** Local outline on this page, or a highlight message on the preview channel. */
+  pointerHighlight: "local" | "channel";
+  setPointerHighlight: (mode: "local" | "channel") => void;
   pointers: ChatPointer[];
   addPointer: (pointer: ChatPointer) => void;
   removePointer: (pointer: ChatPointer) => void;
@@ -202,6 +206,8 @@ export function ChatProvider({
   const [pendingText, setPendingText] = useState<string | null>(null);
   const [mentions, setMentions] = useState<DocRef[]>([]);
   const [pointers, setPointers] = useState<ChatPointer[]>([]);
+  const [previewPointer, setPreviewPointer] = useState(false);
+  const [pointerHighlight, setPointerHighlight] = useState<"local" | "channel">("local");
   const [includeFocus, setIncludeFocus] = useState(true);
   const [threadsVersion, setThreadsVersion] = useState(0);
   const { focus } = useEditorFocus();
@@ -318,7 +324,10 @@ export function ChatProvider({
       mentions,
       addMention,
       removeMention,
-      pointer,
+      pointer: pointer || previewPointer,
+      setPreviewPointer,
+      pointerHighlight,
+      setPointerHighlight,
       pointers,
       addPointer,
       removePointer,
@@ -344,6 +353,8 @@ export function ChatProvider({
       addMention,
       removeMention,
       pointer,
+      previewPointer,
+      pointerHighlight,
       pointers,
       addPointer,
       removePointer,

package/src/chat/Composer.tsx

@@ -10,6 +10,7 @@ import { ModelPicker } from "./ModelPicker";
 import { AtIcon, CloseIcon, FileIcon, FocusIcon, PointerIcon, SendIcon, StopIcon } from "./icons";
 import { mentionQueryAt } from "./chat-helpers";
 import { PointerChip, pointerKey } from "./PointerChip";
+import { POINTER_ARM_EVENT } from "./pointer-arm";
 
 const hover = "@media (hover: hover)";
 
@@ -23,7 +24,7 @@ function isMentionKey(key: string): key is MentionKey {
   return MENTION_KEYS.has(key);
 }
 
-export const POINTER_ARM_EVENT = "backmatter:pointer-arm";
+export { POINTER_ARM_EVENT } from "./pointer-arm";
 
 function postPointer(on: boolean) {
   if (typeof window === "undefined") return;

package/src/chat/PointerChip.tsx

@@ -2,8 +2,10 @@
 import { useEffect } from "react";
 import * as stylex from "@stylexjs/stylex";
 import { colors, space, type } from "../styles/tokens.stylex";
+import { emitPreviewHighlight } from "../preview-highlight";
 import { findPointedElement, highlightPointedElement } from "../site-pointer";
 import type { ChatPointer } from "./chat-context";
+import { useChatUI } from "./ChatProvider";
 import { CloseIcon, PointerIcon } from "./icons";
 
 const hover = "@media (hover: hover)";
@@ -39,19 +41,30 @@ export function PointerChip({
 }) {
   const label = pointerChipLabel(pointer);
   const detail = pointerLabel(pointer);
+  const { pointerHighlight } = useChatUI();
+  const channel = pointerHighlight === "channel";
 
   useEffect(() => {
     return () => {
-      if (canHighlightHere()) highlightPointedElement(document, null);
+      if (channel) emitPreviewHighlight(null);
+      else if (canHighlightHere()) highlightPointedElement(document, null);
     };
-  }, []);
+  }, [channel]);
 
   function show() {
+    if (channel) {
+      emitPreviewHighlight(pointer.blockId);
+      return;
+    }
     if (!canHighlightHere()) return;
     highlightPointedElement(document, findPointedElement(document, pointer));
   }
 
   function hide() {
+    if (channel) {
+      emitPreviewHighlight(null);
+      return;
+    }
     if (!canHighlightHere()) return;
     highlightPointedElement(document, null);
   }

package/src/chat/chat-helpers.ts

@@ -72,6 +72,12 @@ export function toolLabel(name: string, input: unknown, output: unknown, state:
       return running ? `Reading ${doc}…` : `Read ${doc}`;
     case "searchDocs":
       return running ? `Searching “${q ?? ""}”…` : `Searched “${q ?? ""}”`;
+    case "searchWeb":
+      return running ? `Searching “${q ?? ""}”…` : `Searched “${q ?? ""}”`;
+    case "readUrl": {
+      const url = (input as { url?: string } | undefined)?.url ?? "";
+      return running ? `Reading ${url}…` : `Read ${url}`;
+    }
     case "writeDoc":
       return running ? `Editing ${doc}…` : `Edited ${doc}`;
     case "createDoc":

package/src/chat/pointer-arm.ts

@@ -0,0 +1,3 @@
+// packages/studio/src/chat/pointer-arm.ts
+
+export const POINTER_ARM_EVENT = "backmatter:pointer-arm";

package/src/chrome/WorkspaceStatusBar.tsx

@@ -17,11 +17,17 @@ import {
   notifyWorkspaceChanged,
   pullFromGithub,
   resolveDoc,
-  type ApiError,
   type ChangeStatus,
   type GitChange,
 } from "../api";
 import { contentDocPath } from "../workspace-path";
+import {
+  commitErrorSummary,
+  explainCommitError,
+  problemsForRef,
+  type CommitErrorView,
+} from "./commit-error";
+import { CommitFailureNotice, commitFailureLink } from "./commit-failure";
 import { CheckIcon } from "../chat/icons";
 import { WorkspaceSwitcher } from "../components/WorkspaceSwitcher";
 import { colors, radius, space, type } from "../styles/tokens.stylex";
@@ -35,9 +41,11 @@ import { replicaStore } from "../replica/instance";
 import { useReplicaSession } from "../replica/ReplicaProvider";
 import { useReplicaState } from "../replica/useReplica";
 import { useWorkspaceNav } from "./WorkspaceNavContext";
+import { branchHeadMoved } from "./branch-head";
 import { commitTriggerDisabled, statusBarAction } from "./status-bar-action";
 
 const hover = "@media (hover: hover)";
+/** Status bar only. The preview frame follows HEAD on its SSE stream, not on this poll. */
 const POLL_MS = 8000;
 
 export const STATUS_LABEL: Record<ChangeStatus, string> = {
@@ -47,18 +55,6 @@ export const STATUS_LABEL: Record<ChangeStatus, string> = {
   deleted: "deleted",
 };
 
-function formatCommitError(err: unknown): string {
-  if (!(err instanceof Error)) return "Commit failed";
-  const apiErr = err as ApiError;
-  if (apiErr.code === "conflict") return "Resolve conflicts before committing";
-  if (apiErr.code === "nothing_to_commit") return "Nothing to commit";
-  if (apiErr.code === "validation") {
-    return err.message.replace(/^validation:\s*/, "Validation failed: ");
-  }
-  if (apiErr.code === "github_not_bound") return "Connect GitHub first";
-  return err.message;
-}
-
 function changeKey(doc: GitChange) {
   return `${doc.locale}/${doc.type}/${doc.slug}`;
 }
@@ -144,10 +140,10 @@ function ConflictResolvePanel({
   );
 }
 
-function ChangeRow({ doc }: { doc: GitChange }) {
+function ChangeRow({ doc, invalid = false }: { doc: GitChange; invalid?: boolean }) {
   return (
     <div {...stylex.props(styles.changeItem)}>
-      <span {...stylex.props(styles.changeName)}>
+      <span {...stylex.props(styles.changeName, invalid && styles.conflictText)}>
         {doc.type}/{doc.slug}
       </span>
       <span
@@ -181,7 +177,9 @@ export function WorkspaceStatusBar({ workspaceId }: { workspaceId: string }) {
   const [resolvingKey, setResolvingKey] = useState<string | null>(null);
   const [message, setMessage] = useState("");
   const [error, setError] = useState<string | null>(null);
-  // HEAD identity from the last poll so we can announce "HEAD moved".
+  const [commitFailure, setCommitFailure] = useState<CommitErrorView | null>(null);
+  // Commit sha from the last poll. A new sha means HEAD moved. The preview
+  // iframe does not reload for that; its page follows the SSE head event.
   const lastHead = useRef<string | null | undefined>(undefined);
 
   async function reloadGit() {
@@ -195,11 +193,9 @@ export function WorkspaceStatusBar({ workspaceId }: { workspaceId: string }) {
       } else {
         setError(null);
       }
-      const headKey = next.head ? `${next.head.sha}:${next.head.updatedAt}` : null;
-      if (lastHead.current !== undefined && lastHead.current !== headKey) {
-        notifyHeadChanged();
-      }
-      lastHead.current = headKey;
+      const nextSha = next.head?.sha ?? null;
+      if (branchHeadMoved(lastHead.current, nextSha)) notifyHeadChanged();
+      lastHead.current = nextSha;
     } catch (err) {
       setError(err instanceof Error ? err.message : "Git status failed");
     }
@@ -323,6 +319,7 @@ export function WorkspaceStatusBar({ workspaceId }: { workspaceId: string }) {
     if (committing || conflictCount > 0 || changeCount === 0) return;
     setCommitting(true);
     setError(null);
+    setCommitFailure(null);
     try {
       const result = await commitWorkspace(workspaceId, message);
       setMessage("");
@@ -330,13 +327,29 @@ export function WorkspaceStatusBar({ workspaceId }: { workspaceId: string }) {
       publishCommittedFiles(workspaceId, result.files);
       await reloadGit();
     } catch (err) {
-      setError(formatCommitError(err));
+      setCommitFailure(explainCommitError(err));
       await reloadGit();
     } finally {
       setCommitting(false);
     }
   }
 
+  function hrefForChange(ref: string): string | null {
+    const slash = ref.indexOf("/");
+    if (slash <= 0 || !workspaceNav) return null;
+    const type = ref.slice(0, slash);
+    const slug = ref.slice(slash + 1);
+    const doc = changes.find((change) => change.type === type && change.slug === slug);
+    if (!doc) return null;
+    return contentDocPath(
+      workspaceNav.workspaceSlug,
+      doc.type,
+      doc.slug,
+      doc.locale,
+      workspaceNav.defaultLocale,
+    );
+  }
+
   const commitLabel = committing
     ? "Committing…"
     : conflictCount > 0
@@ -506,8 +519,11 @@ export function WorkspaceStatusBar({ workspaceId }: { workspaceId: string }) {
           {changeCount} uncommitted
         </StatusItem>
       ) : null}
-      {error ? <StatusItem tone="danger">{error}</StatusItem> : null}
-      {refreshError && !error ? (
+      {error ? (
+        <StatusItem tone="danger">{error}</StatusItem>
+      ) : commitFailure ? (
+        <StatusItem tone="danger">{commitErrorSummary(commitFailure)}</StatusItem>
+      ) : refreshError ? (
         <StatusItem tone="danger">{refreshError}</StatusItem>
       ) : null}
       <StatusSpacer />
@@ -562,10 +578,33 @@ export function WorkspaceStatusBar({ workspaceId }: { workspaceId: string }) {
                   <p {...stylex.props(popup.groupLabel)}>
                     {changeCount} {changeCount === 1 ? "file" : "files"} → {git?.currentBranch}
                   </p>
+                  {commitFailure ? (
+                    <CommitFailureNotice
+                      failure={commitFailure}
+                      renderRef={(ref) => {
+                        const href = hrefForChange(ref);
+                        if (!href) return ref;
+                        return (
+                          <Link
+                            to={href}
+                            onClick={() => setCommitOpen(false)}
+                            {...stylex.props(commitFailureLink.link)}
+                          >
+                            {ref}
+                          </Link>
+                        );
+                      }}
+                    />
+                  ) : null}
                   <ul {...stylex.props(styles.commitFiles)}>
                     {changes.map((doc) => (
                       <li key={`${doc.locale}/${doc.type}/${doc.slug}`}>
-                        <ChangeRow doc={doc} />
+                        <ChangeRow
+                          doc={doc}
+                          invalid={
+                            problemsForRef(commitFailure, `${doc.type}/${doc.slug}`).length > 0
+                          }
+                        />
                       </li>
                     ))}
                   </ul>

package/src/chrome/branch-head.ts

@@ -0,0 +1,14 @@
+// packages/studio/src/chrome/branch-head.ts
+
+/**
+ * Whether a later git poll is a new commit.
+ * The first sample only records the sha. `updatedAt` is not part of the
+ * identity: rewriting the head row must not look like HEAD moved.
+ */
+export function branchHeadMoved(
+  previousSha: string | null | undefined,
+  nextSha: string | null,
+): boolean {
+  if (previousSha === undefined) return false;
+  return previousSha !== nextSha;
+}

package/src/chrome/commit-error.ts

@@ -0,0 +1,82 @@
+// packages/studio/src/chrome/commit-error.ts
+import type { ApiError } from "../api";
+
+export type CommitFileProblem = {
+  /** `type/slug`, the same label the commit list uses. */
+  ref: string;
+  problems: string[];
+};
+
+export type CommitErrorView =
+  | { kind: "validation"; files: CommitFileProblem[] }
+  | { kind: "message"; text: string };
+
+/**
+ * Turn a failed commit into what the deploy window should say.
+ * Validation lists every file and field. Other failures stay one sentence.
+ */
+export function explainCommitError(err: unknown): CommitErrorView {
+  if (!(err instanceof Error)) return { kind: "message", text: "Commit failed" };
+  const apiErr = err as ApiError;
+  if (apiErr.code === "conflict") {
+    return { kind: "message", text: "Resolve conflicts before committing" };
+  }
+  if (apiErr.code === "nothing_to_commit") {
+    return { kind: "message", text: "Nothing to commit" };
+  }
+  if (apiErr.code === "github_not_bound") {
+    return { kind: "message", text: "Connect GitHub first" };
+  }
+  if (apiErr.code === "validation") {
+    return { kind: "validation", files: groupValidation(validationLines(apiErr)) };
+  }
+  return { kind: "message", text: err.message };
+}
+
+/** One line for the status bar. The window lists every problem. */
+export function commitErrorSummary(view: CommitErrorView): string {
+  if (view.kind === "message") return view.text;
+  const first = view.files[0];
+  if (!first || first.problems.length === 0) return "Can't commit";
+  const extra =
+    view.files.reduce((n, file) => n + file.problems.length, 0) - 1;
+  const lead = `${first.ref} — ${first.problems[0]}`;
+  return extra > 0 ? `${lead} (+${extra} more)` : lead;
+}
+
+export function problemsForRef(
+  view: CommitErrorView | null,
+  ref: string,
+): string[] {
+  if (!view || view.kind !== "validation") return [];
+  return view.files.find((file) => file.ref === ref)?.problems ?? [];
+}
+
+function validationLines(err: ApiError): string[] {
+  if (err.details && err.details.length > 0) return err.details;
+  const body = err.message.replace(/^validation:\s*/, "");
+  if (!body || body === err.message) return [];
+  return body.split(", ").filter((line) => line.length > 0);
+}
+
+function groupValidation(lines: string[]): CommitFileProblem[] {
+  const order: string[] = [];
+  const byRef = new Map<string, string[]>();
+  for (const line of lines) {
+    const split = line.indexOf(": ");
+    const ref = split === -1 ? line : line.slice(0, split);
+    const problem = sentence(split === -1 ? line : line.slice(split + 2));
+    if (!byRef.has(ref)) {
+      byRef.set(ref, []);
+      order.push(ref);
+    }
+    byRef.get(ref)!.push(problem);
+  }
+  return order.map((ref) => ({ ref, problems: byRef.get(ref)! }));
+}
+
+function sentence(problem: string): string {
+  const trimmed = problem.trim();
+  if (!trimmed) return trimmed;
+  return trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
+}

package/src/chrome/commit-failure.tsx

@@ -0,0 +1,111 @@
+// packages/studio/src/chrome/commit-failure.tsx
+import type { ReactNode } from "react";
+import * as stylex from "@stylexjs/stylex";
+import type { CommitErrorView } from "./commit-error";
+import { colors, space, type } from "../styles/tokens.stylex";
+
+const hover = "@media (hover: hover)";
+
+/** The explanation inside the deploy window after a commit is refused. */
+export function CommitFailureNotice({
+  failure,
+  renderRef,
+}: {
+  failure: CommitErrorView;
+  renderRef?: (ref: string) => ReactNode;
+}) {
+  if (failure.kind === "message") {
+    return (
+      <p role="alert" {...stylex.props(styles.line)}>
+        {failure.text}
+      </p>
+    );
+  }
+
+  return (
+    <div role="alert" {...stylex.props(styles.box)}>
+      <p {...stylex.props(styles.title)}>Can't commit yet</p>
+      <ul {...stylex.props(styles.list)}>
+        {failure.files.map((file) => (
+          <li key={file.ref} {...stylex.props(styles.item)}>
+            <span {...stylex.props(styles.ref)}>
+              {renderRef ? renderRef(file.ref) : file.ref}
+            </span>
+            {file.problems.map((problem, index) => (
+              <span key={`${problem}-${index}`} {...stylex.props(styles.problem)}>
+                {problem}
+              </span>
+            ))}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+const styles = stylex.create({
+  box: {
+    display: "flex",
+    flexDirection: "column",
+    gap: space.xs,
+    paddingInline: space.lg,
+    paddingBottom: space.sm,
+  },
+  title: {
+    margin: 0,
+    fontSize: type.xs,
+    fontWeight: 500,
+    color: colors.danger,
+  },
+  list: {
+    margin: 0,
+    padding: 0,
+    listStyle: "none",
+    display: "flex",
+    flexDirection: "column",
+    gap: space.sm,
+    maxHeight: "140px",
+    overflowY: "auto",
+  },
+  item: {
+    display: "flex",
+    flexDirection: "column",
+    gap: "2px",
+    minWidth: 0,
+  },
+  ref: {
+    display: "block",
+    minWidth: 0,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+    fontFamily: type.mono,
+    fontSize: type.xs,
+    color: colors.text,
+  },
+  problem: {
+    fontSize: type.xs,
+    lineHeight: 1.4,
+    color: colors.danger,
+  },
+  line: {
+    margin: 0,
+    paddingInline: space.lg,
+    paddingBottom: space.sm,
+    fontSize: type.xs,
+    lineHeight: 1.4,
+    color: colors.danger,
+  },
+});
+
+export const commitFailureLink = stylex.create({
+  link: {
+    color: "inherit",
+    textDecoration: "none",
+    [hover]: {
+      ":hover": {
+        textDecoration: "underline",
+      },
+    },
+  },
+});

package/src/install-preview-pointer.ts

@@ -0,0 +1,116 @@
+// packages/studio/src/install-preview-pointer.ts
+import { routePointerHit, type PointerArmSource, type RoutedGrab } from "@backmatter/core/preview";
+import {
+  grabAt,
+  highlightPointedElement,
+  installSitePointer,
+  isOpenModifier,
+  type PointerGrab,
+} from "./site-pointer";
+
+export function installPreviewPointer(
+  doc: Document,
+  options: {
+    bar: () => Element | null;
+    ignore?: (target: EventTarget | null) => boolean;
+    onEditorGrab: (grab: RoutedGrab) => void;
+    onDevbarGrab: (grab: PointerGrab) => void;
+    onEscape?: (source: PointerArmSource) => void;
+  },
+): {
+  arm: (source: PointerArmSource) => void;
+  disarm: () => void;
+  source: () => PointerArmSource | null;
+  dispose: () => void;
+} {
+  let source: PointerArmSource | null = null;
+
+  function deliver(grab: PointerGrab, shift: boolean) {
+    const route = routePointerHit(source, { ...grab, shift });
+    if (route.to === "editor") options.onEditorGrab(route.grab);
+    else if (route.to === "devbar") options.onDevbarGrab(route.grab);
+  }
+
+  const pointer = installSitePointer(doc, {
+    bar: options.bar,
+    ignore: options.ignore,
+    onGrab: (grab, shift) => deliver(grab, shift),
+    onEscape: () => {
+      const armed = source;
+      source = null;
+      if (armed) options.onEscape?.(armed);
+    },
+  });
+
+  let under: Element | null = null;
+
+  function elementFrom(raw: EventTarget | null): Element | null {
+    if (!raw || typeof raw !== "object" || !("nodeType" in raw) || raw.nodeType !== 1) return null;
+    return raw as Element;
+  }
+
+  function markedBlock(target: Element | null): Element | null {
+    if (!target || options.ignore?.(target)) return null;
+    const marker = target.closest("[data-backmatter-block]");
+    if (!marker?.getAttribute("data-backmatter-block")) return null;
+    return marker;
+  }
+
+  function paint(held: boolean) {
+    highlightPointedElement(doc, held ? markedBlock(under) : null, { scroll: false });
+  }
+
+  function onMove(event: PointerEvent) {
+    under = elementFrom(event.target);
+    paint(isOpenModifier(event));
+  }
+
+  function onModifier(event: KeyboardEvent) {
+    if (event.key !== "Meta" && event.key !== "Control") return;
+    paint(event.type === "keydown" || isOpenModifier(event));
+  }
+
+  function onOpen(event: MouseEvent) {
+    if (!isOpenModifier(event) || source !== null) return;
+    const target = elementFrom(event.target);
+    const grab = grabAt(target, options.bar());
+    if (!grab?.blockId) return;
+    event.preventDefault();
+    event.stopPropagation();
+    deliver(grab, true);
+  }
+
+  function onBlur() {
+    paint(false);
+  }
+
+  const view = doc.defaultView;
+  doc.addEventListener("pointermove", onMove, true);
+  doc.addEventListener("keydown", onModifier, true);
+  doc.addEventListener("keyup", onModifier, true);
+  doc.addEventListener("click", onOpen, true);
+  view?.addEventListener("blur", onBlur);
+
+  return {
+    arm(next) {
+      source = next;
+      pointer.arm();
+    },
+    disarm() {
+      source = null;
+      pointer.disarm();
+    },
+    source: () => source,
+    dispose() {
+      doc.removeEventListener("pointermove", onMove, true);
+      doc.removeEventListener("keydown", onModifier, true);
+      doc.removeEventListener("keyup", onModifier, true);
+      doc.removeEventListener("click", onOpen, true);
+      view?.removeEventListener("blur", onBlur);
+      highlightPointedElement(doc, null);
+      source = null;
+      under = null;
+      pointer.dispose();
+    },
+  };
+}