@backmatter/studio 0.0.2 → 0.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/studio",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "The Backmatter editing surface: document editor, AI chat, publish. Mounted on your site or hosted on the dashboard.",
   "type": "module",
   "publishConfig": {
@@ -28,6 +28,11 @@
       "default": "./dist/define.js"
     },
     "./styles": "./src/styles.ts",
+    "./widget": {
+      "types": "./src/site-widget.tsx",
+      "source": "./src/site-widget.tsx",
+      "default": "./dist/site-widget.js"
+    },
     "./studio.css": "./dist/studio.css",
     "./prose-ui-node-shim": "./prose-ui-node-shim.ts",
     "./package.json": "./package.json",
@@ -47,7 +52,7 @@
   },
   "dependencies": {
     "@ai-sdk/react": "^4.0.100",
-    "@backmatter/core": "^0.0.20",
+    "@backmatter/core": "^0.0.21",
     "@base-ui/react": "^1.6.0",
     "@dnd-kit/abstract": "^0.5.0",
     "@dnd-kit/react": "^0.5.0",

package/src/api.ts

@@ -261,6 +261,10 @@ export function attachGithubInstallation(
   });
 }
 
+export function fetchGithubRepositoryAccess(workspaceId: string) {
+  return api<{ url: string }>(`/workspaces/${workspaceId}/github/repository-access`);
+}
+
 export function fetchGithubRepos(workspaceId: string) {
   return api<{
     repos: Array<{ fullName: string; defaultBranch: string }>;

package/src/chat/ChangeCard.tsx

@@ -1,6 +1,5 @@
 // packages/studio/src/chat/ChangeCard.tsx
 import { useState } from "react";
-import { Link } from "react-router";
 import * as stylex from "@stylexjs/stylex";
 import type { ChatChangeSummary } from "../api";
 import { colors, radius, space, type } from "../styles/tokens.stylex";
@@ -8,6 +7,7 @@ import { Tooltip } from "../ui/Tooltip";
 import { contentDocPath } from "../workspace-path";
 import { useWorkspaceNav } from "../chrome/WorkspaceNavContext";
 import { CheckIcon, ChevronDownIcon, FileIcon, UndoIcon } from "./icons";
+import { DocLink } from "./DocLink";
 
 const hover = "@media (hover: hover)";
 
@@ -56,12 +56,17 @@ export function ChangeCard({
         <span {...stylex.props(styles.fileIcon)}>
           <FileIcon />
         </span>
-        <Tooltip label={`Open ${label} in the editor`}>
-          <Link to={to} {...stylex.props(styles.name)}>
+        {nav ? (
+          <Tooltip label={`Open ${label} in the editor`}>
+            <DocLink to={to} {...stylex.props(styles.name)}>
+              {label}
+            </DocLink>
+          </Tooltip>
+        ) : (
+          <DocLink to={to} {...stylex.props(styles.name)}>
             {label}
-          </Link>
-        </Tooltip>
-        <span {...stylex.props(styles.locale)}>{change.locale}</span>
+          </DocLink>
+        )}
         {change.diff?.renamedFrom ? (
           <span {...stylex.props(styles.badge)}>
             {change.diff.renamedFrom} → {change.slug}

package/src/chat/ChatMessage.tsx

@@ -19,6 +19,8 @@ import {
   type WriteToolOutput,
 } from "./chat-helpers";
 import { CheckIcon, EyeIcon, FileIcon, SearchIcon, UndoIcon } from "./icons";
+import { pointersFromMetadata } from "./chat-context";
+import { PointerChip, pointerKey } from "./PointerChip";
 
 const hover = "@media (hover: hover)";
 
@@ -117,9 +119,19 @@ export function ChatMessage({
       .filter((p): p is { type: "text"; text: string } => p.type === "text")
       .map((p) => p.text)
       .join("\n");
+    const pointers = pointersFromMetadata(message.metadata);
     return (
       <div {...stylex.props(styles.userRow, entering && styles.enter)}>
-        <div {...stylex.props(styles.userBubble)}>{text}</div>
+        <div {...stylex.props(styles.userStack)}>
+          {pointers.length > 0 ? (
+            <div {...stylex.props(styles.userChips)} aria-label="Pointed elements">
+              {pointers.map((pointer) => (
+                <PointerChip key={pointerKey(pointer)} pointer={pointer} />
+              ))}
+            </div>
+          ) : null}
+          {text ? <div {...stylex.props(styles.userBubble)}>{text}</div> : null}
+        </div>
       </div>
     );
   }
@@ -312,8 +324,21 @@ const styles = stylex.create({
     display: "flex",
     justifyContent: "flex-end",
   },
-  userBubble: {
+  userStack: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "flex-end",
+    gap: space.sm,
     maxWidth: "85%",
+  },
+  userChips: {
+    display: "flex",
+    flexWrap: "wrap",
+    justifyContent: "flex-end",
+    gap: space.sm,
+  },
+  userBubble: {
+    maxWidth: "100%",
     paddingInline: space.lg,
     paddingBlock: space.md,
     borderRadius: 10,

package/src/chat/ChatPanel.tsx

@@ -26,7 +26,7 @@ import { isPanelVisible } from "./chat-state";
 
 const hover = "@media (hover: hover)";
 
-export function ChatPanel({ fill = false }: { fill?: boolean } = {}) {
+export function ChatPanel({ fill = false, site = false }: { fill?: boolean; site?: boolean } = {}) {
   const ui = useChatUI();
   const session = useChatSession();
   const visible = isPanelVisible(ui.panel.mode);
@@ -70,7 +70,12 @@ export function ChatPanel({ fill = false }: { fill?: boolean } = {}) {
     <section
       role="dialog"
       aria-label="AI chat"
-      {...stylex.props(fill ? styles.panelFill : styles.panel, !fill && fullscreen && styles.panelFull)}
+      data-backmatter-panel=""
+      {...stylex.props(
+        fill ? styles.panelFill : styles.panel,
+        site && styles.panelSite,
+        !fill && fullscreen && styles.panelFull,
+      )}
     >
       <header {...stylex.props(styles.header)}>
         <h2 {...stylex.props(styles.title)}>{title}</h2>
@@ -245,6 +250,11 @@ const styles = stylex.create({
     width: "auto",
     height: "auto",
   },
+  panelSite: {
+    right: 16,
+    bottom: 64,
+    zIndex: 2147483001,
+  },
   panelFill: {
     position: "fixed",
     top: 0,

package/src/chat/ChatProvider.tsx

@@ -46,8 +46,11 @@ import {
 } from "../chrome/EditorFocusContext";
 import {
   addMention as addMentionTo,
+  addPointer as addPointerTo,
   buildChatContext,
   removeMention as removeMentionFrom,
+  removePointer as removePointerFrom,
+  type ChatPointer,
   type ChatRequestContext,
 } from "./chat-context";
 import {
@@ -85,6 +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`. */
+  pointer: boolean;
+  pointers: ChatPointer[];
+  addPointer: (pointer: ChatPointer) => void;
+  removePointer: (pointer: ChatPointer) => void;
+  clearPointers: () => void;
   includeFocus: boolean;
   setIncludeFocus: (v: boolean) => void;
   focus: EditorFocus | null;
@@ -171,10 +180,13 @@ function refFromInput(input: unknown): DocRef | null {
 export function ChatProvider({
   workspaceId,
   startOpen = false,
+  pointer = false,
   children,
 }: {
   workspaceId: string;
   startOpen?: boolean;
+  /** Dev bar chat can point at elements on the host page. */
+  pointer?: boolean;
   children: React.ReactNode;
 }) {
   const [panel, dispatch] = useReducer(
@@ -189,6 +201,7 @@ export function ChatProvider({
   const [freshThread, setFreshThread] = useState(false);
   const [pendingText, setPendingText] = useState<string | null>(null);
   const [mentions, setMentions] = useState<DocRef[]>([]);
+  const [pointers, setPointers] = useState<ChatPointer[]>([]);
   const [includeFocus, setIncludeFocus] = useState(true);
   const [threadsVersion, setThreadsVersion] = useState(0);
   const { focus } = useEditorFocus();
@@ -223,6 +236,7 @@ export function ChatProvider({
     setFreshThread(false);
     setPendingText(null);
     setMentions([]);
+    setPointers([]);
     setIncludeFocus(true);
   }, [workspaceId]);
 
@@ -246,6 +260,7 @@ export function ChatProvider({
     setFreshThread(false);
     setPendingText(null);
     setMentions([]);
+    setPointers([]);
     dispatch({ type: "showChat" });
   }, []);
 
@@ -255,6 +270,13 @@ export function ChatProvider({
   const removeMention = useCallback((ref: DocRef) => {
     setMentions((prev) => removeMentionFrom(prev, ref));
   }, []);
+  const addPointer = useCallback((next: ChatPointer) => {
+    setPointers((prev) => addPointerTo(prev, next));
+  }, []);
+  const removePointer = useCallback((next: ChatPointer) => {
+    setPointers((prev) => removePointerFrom(prev, next));
+  }, []);
+  const clearPointers = useCallback(() => setPointers([]), []);
   const bumpThreads = useCallback(() => setThreadsVersion((v) => v + 1), []);
 
   // Context getter kept in a ref so the session never re-renders because of it.
@@ -262,8 +284,9 @@ export function ChatProvider({
     focusDoc: null,
     selection: null,
     mentions: [],
+    pointers: [],
   }));
-  contextRef.current = () => buildChatContext({ focus, includeFocus, mentions });
+  contextRef.current = () => buildChatContext({ focus, includeFocus, mentions, pointers });
   const modelRef = useRef<string | null>(model);
   modelRef.current = model;
 
@@ -295,6 +318,11 @@ export function ChatProvider({
       mentions,
       addMention,
       removeMention,
+      pointer,
+      pointers,
+      addPointer,
+      removePointer,
+      clearPointers,
       includeFocus,
       setIncludeFocus,
       focus,
@@ -315,6 +343,11 @@ export function ChatProvider({
       mentions,
       addMention,
       removeMention,
+      pointer,
+      pointers,
+      addPointer,
+      removePointer,
+      clearPointers,
       includeFocus,
       focus,
       threadsVersion,
@@ -539,9 +572,13 @@ function LiveSession({
 
   const send = useCallback(
     async (text: string) => {
+      const context = getContext();
       await sendMessage(
-        { text },
-        { body: { model: getModel(), context: getContext() } },
+        {
+          text,
+          metadata: context.pointers.length ? { pointers: context.pointers } : undefined,
+        },
+        { body: { model: getModel(), context } },
       );
     },
     [sendMessage, getModel, getContext],

package/src/chat/Composer.tsx

@@ -7,8 +7,9 @@ import { Tooltip } from "../ui/Tooltip";
 import { useChatSession, useChatUI } from "./ChatProvider";
 import { MentionPopover, type MentionKey } from "./MentionPopover";
 import { ModelPicker } from "./ModelPicker";
-import { AtIcon, CloseIcon, FileIcon, FocusIcon, SendIcon, StopIcon } from "./icons";
+import { AtIcon, CloseIcon, FileIcon, FocusIcon, PointerIcon, SendIcon, StopIcon } from "./icons";
 import { mentionQueryAt } from "./chat-helpers";
+import { PointerChip, pointerKey } from "./PointerChip";
 
 const hover = "@media (hover: hover)";
 
@@ -22,11 +23,22 @@ function isMentionKey(key: string): key is MentionKey {
   return MENTION_KEYS.has(key);
 }
 
+export const POINTER_ARM_EVENT = "backmatter:pointer-arm";
+
+function postPointer(on: boolean) {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(POINTER_ARM_EVENT, { detail: { on } }));
+  if (window.parent !== window) {
+    window.parent.postMessage({ type: "backmatter:pointer", on }, location.origin);
+  }
+}
+
 export function Composer({ autoFocus }: { autoFocus: boolean }) {
   const ui = useChatUI();
   const session = useChatSession();
   const [text, setText] = useState("");
   const [mention, setMention] = useState<{ start: number; query: string } | null>(null);
+  const [pointing, setPointing] = useState(false);
   const ref = useRef<HTMLTextAreaElement>(null);
   const boxRef = useRef<HTMLDivElement>(null);
   const mentionKeys = useRef<((key: MentionKey) => void) | null>(null);
@@ -71,13 +83,40 @@ export function Composer({ autoFocus }: { autoFocus: boolean }) {
     return () => window.removeEventListener("backmatter:chat-prefill", onPrefill);
   }, []);
 
+  useEffect(() => {
+    if (!ui.pointer) return;
+    function disarm() {
+      setPointing(false);
+    }
+    function onArm(event: Event) {
+      if ((event as CustomEvent<{ on?: boolean }>).detail?.on === false) disarm();
+    }
+    function onMessage(event: MessageEvent) {
+      if (event.source !== window.parent || event.origin !== location.origin) return;
+      const data = event.data as { type?: string; on?: boolean };
+      if (data?.type !== "backmatter:pointer" || data.on !== false) return;
+      disarm();
+    }
+    window.addEventListener(POINTER_ARM_EVENT, onArm);
+    window.addEventListener("message", onMessage);
+    return () => {
+      window.removeEventListener(POINTER_ARM_EVENT, onArm);
+      window.removeEventListener("message", onMessage);
+    };
+  }, [ui.pointer]);
+
   const submit = useCallback(() => {
     const value = text.trim();
     if (!value || busy) return;
     setText("");
     setMention(null);
+    if (pointing) {
+      setPointing(false);
+      postPointer(false);
+    }
     void session.send(value);
-  }, [text, busy, session]);
+    ui.clearPointers();
+  }, [text, busy, session, ui, pointing]);
 
   function updateMention(el: HTMLTextAreaElement) {
     setMention(mentionQueryAt(el.value, el.selectionStart ?? el.value.length));
@@ -141,6 +180,17 @@ export function Composer({ autoFocus }: { autoFocus: boolean }) {
           </div>
       ) : null}
       <div ref={boxRef} {...stylex.props(styles.box)}>
+        {ui.pointers.length > 0 ? (
+          <div {...stylex.props(styles.chips)} aria-label="Pointed elements">
+            {ui.pointers.map((pointer) => (
+              <PointerChip
+                key={pointerKey(pointer)}
+                pointer={pointer}
+                onRemove={() => ui.removePointer(pointer)}
+              />
+            ))}
+          </div>
+        ) : null}
         <textarea
           ref={ref}
           value={text}
@@ -170,6 +220,11 @@ export function Composer({ autoFocus }: { autoFocus: boolean }) {
               e.preventDefault();
               submit();
             } else if (e.key === "Escape") {
+              if (pointing) {
+                setPointing(false);
+                postPointer(false);
+                return;
+              }
               ui.dispatch({ type: "minimize" });
             }
           }}
@@ -222,6 +277,24 @@ export function Composer({ autoFocus }: { autoFocus: boolean }) {
               </button>
             </Tooltip>
           ) : null}
+          {ui.pointer ? (
+            <Tooltip label={pointing ? "Stop pointing" : "Point at an element on the page"}>
+              <button
+                type="button"
+                aria-label="Point at an element on the page"
+                aria-pressed={pointing}
+                disabled={ui.aiAvailable !== true}
+                onClick={() => {
+                  const next = !pointing;
+                  setPointing(next);
+                  postPointer(next);
+                }}
+                {...stylex.props(styles.iconBtn, pointing && styles.iconBtnActive)}
+              >
+                <PointerIcon />
+              </button>
+            </Tooltip>
+          ) : null}
           <ModelPicker />
           {busy ? (
             <Tooltip label="Stop generating">
@@ -257,13 +330,15 @@ function ContextRow({
   icon,
   type,
   slug,
+  label,
   meta,
   removeLabel,
   onRemove,
 }: {
   icon: React.ReactNode;
-  type: string;
-  slug: string;
+  type?: string;
+  slug?: string;
+  label?: string;
   meta?: string;
   removeLabel: string;
   onRemove: () => void;
@@ -272,8 +347,14 @@ function ContextRow({
     <div {...stylex.props(styles.row)}>
       <span {...stylex.props(styles.rowIcon)}>{icon}</span>
       <span {...stylex.props(styles.rowText)}>
-        <span {...stylex.props(styles.rowType)}>{type}/</span>
-        <span {...stylex.props(styles.rowSlug)}>{slug}</span>
+        {label ? (
+          <span {...stylex.props(styles.rowSlug)}>{label}</span>
+        ) : (
+          <>
+            <span {...stylex.props(styles.rowType)}>{type}/</span>
+            <span {...stylex.props(styles.rowSlug)}>{slug}</span>
+          </>
+        )}
       </span>
       {meta ? <span {...stylex.props(styles.rowMeta)}>{meta}</span> : null}
       <button
@@ -364,6 +445,11 @@ const styles = stylex.create({
       ":hover": { backgroundColor: colors.bgHover, color: colors.text },
     },
   },
+  chips: {
+    display: "flex",
+    flexWrap: "wrap",
+    gap: space.sm,
+  },
   box: {
     position: "relative",
     zIndex: 2,

package/src/chat/DocLink.tsx

@@ -0,0 +1,31 @@
+// packages/studio/src/chat/DocLink.tsx
+// A document name that opens in the Studio router. The on-site widget has no
+// router, so the same label renders as text and the chat can still show it.
+import type { CSSProperties, ReactNode } from "react";
+import { Link, useInRouterContext } from "react-router";
+
+export function DocLink({
+  to,
+  children,
+  className,
+  style,
+}: {
+  to: string;
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}) {
+  const routed = useInRouterContext();
+  if (!routed) {
+    return (
+      <span className={className} style={style}>
+        {children}
+      </span>
+    );
+  }
+  return (
+    <Link to={to} className={className} style={style}>
+      {children}
+    </Link>
+  );
+}

package/src/chat/DocListCard.tsx

@@ -4,11 +4,11 @@
 // into the editor. Content models are user-defined, so rows lean on the
 // server-derived `title` and fall back to the slug.
 import { useState } from "react";
-import { Link } from "react-router";
 import * as stylex from "@stylexjs/stylex";
 import { colors, radius, space, type } from "../styles/tokens.stylex";
 import { contentDocPath } from "../workspace-path";
 import { useWorkspaceNav } from "../chrome/WorkspaceNavContext";
+import { DocLink } from "./DocLink";
 import { ChevronDownIcon, FileIcon } from "./icons";
 
 const hover = "@media (hover: hover)";
@@ -130,7 +130,7 @@ function DocRow({
   const secondary = doc.path ?? `${doc.type}/${doc.slug}`;
 
   return (
-    <Link to={to} {...stylex.props(styles.row)}>
+    <DocLink to={to} {...stylex.props(styles.row)}>
       <span {...stylex.props(styles.line)}>
         <span {...stylex.props(styles.icon)}>
           <FileIcon size={13} />
@@ -153,7 +153,7 @@ function DocRow({
         </span>
       </span>
       {doc.excerpt ? <span {...stylex.props(styles.excerpt)}>{doc.excerpt}</span> : null}
-    </Link>
+    </DocLink>
   );
 }
 

package/src/chat/PointerChip.tsx

@@ -0,0 +1,139 @@
+// packages/studio/src/chat/PointerChip.tsx
+import { useEffect } from "react";
+import * as stylex from "@stylexjs/stylex";
+import { colors, space, type } from "../styles/tokens.stylex";
+import { findPointedElement, highlightPointedElement } from "../site-pointer";
+import type { ChatPointer } from "./chat-context";
+import { CloseIcon, PointerIcon } from "./icons";
+
+const hover = "@media (hover: hover)";
+
+export function pointerKey(pointer: ChatPointer): string {
+  return `${pointer.locale}/${pointer.type}/${pointer.slug}/${pointer.blockId ?? ""}/${pointer.quote}`;
+}
+
+function pointerLabel(pointer: ChatPointer): string {
+  const quote = pointer.quote.replace(/\s+/g, " ").trim();
+  const short = quote.length > 42 ? `${quote.slice(0, 41)}…` : quote;
+  if (pointer.blockType && short) return `${pointer.blockType} · “${short}”`;
+  if (pointer.blockType) return pointer.blockType;
+  return short ? `“${short}”` : "element";
+}
+
+function pointerChipLabel(pointer: ChatPointer): string {
+  const quote = pointer.quote.replace(/\s+/g, " ").trim();
+  const raw = quote || pointer.blockType || `${pointer.type}/${pointer.slug}`;
+  return raw.length > 32 ? `${raw.slice(0, 31)}…` : raw;
+}
+
+function canHighlightHere(): boolean {
+  return typeof window !== "undefined" && window.parent === window;
+}
+
+export function PointerChip({
+  pointer,
+  onRemove,
+}: {
+  pointer: ChatPointer;
+  onRemove?: () => void;
+}) {
+  const label = pointerChipLabel(pointer);
+  const detail = pointerLabel(pointer);
+
+  useEffect(() => {
+    return () => {
+      if (canHighlightHere()) highlightPointedElement(document, null);
+    };
+  }, []);
+
+  function show() {
+    if (!canHighlightHere()) return;
+    highlightPointedElement(document, findPointedElement(document, pointer));
+  }
+
+  function hide() {
+    if (!canHighlightHere()) return;
+    highlightPointedElement(document, null);
+  }
+
+  return (
+    <span
+      {...stylex.props(styles.chip, !onRemove && styles.chipStatic)}
+      title={`${detail} · ${pointer.type}/${pointer.slug}`}
+      onMouseEnter={show}
+      onMouseLeave={hide}
+    >
+      <span {...stylex.props(styles.chipIcon)}>
+        <PointerIcon size={13} />
+      </span>
+      <span {...stylex.props(styles.chipLabel)}>{label}</span>
+      {onRemove ? (
+        <button
+          type="button"
+          aria-label={`Remove ${detail}`}
+          onClick={onRemove}
+          {...stylex.props(styles.chipRemove)}
+        >
+          <CloseIcon size={11} />
+        </button>
+      ) : null}
+    </span>
+  );
+}
+
+const styles = stylex.create({
+  chip: {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: space.xs,
+    maxWidth: "100%",
+    height: 26,
+    paddingLeft: space.sm,
+    paddingRight: 2,
+    borderWidth: 1,
+    borderStyle: "solid",
+    borderColor: colors.border,
+    borderRadius: 8,
+    backgroundColor: colors.bgSurface,
+    color: colors.text,
+    fontSize: type.sm,
+  },
+  chipStatic: {
+    paddingRight: space.sm,
+  },
+  chipIcon: {
+    display: "inline-flex",
+    flexShrink: 0,
+    color: colors.textMuted,
+  },
+  chipLabel: {
+    minWidth: 0,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+    fontWeight: 500,
+  },
+  chipRemove: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    flexShrink: 0,
+    width: 22,
+    height: 22,
+    padding: 0,
+    borderWidth: 0,
+    borderRadius: 6,
+    backgroundColor: "transparent",
+    color: colors.textMuted,
+    cursor: "pointer",
+    [hover]: {
+      ":hover": { backgroundColor: colors.bgHover, color: colors.text },
+    },
+    ":focus-visible": {
+      outlineWidth: 2,
+      outlineStyle: "solid",
+      outlineColor: colors.focus,
+      outlineOffset: 1,
+    },
+  },
+});