@backmatter/studio 0.0.14 → 0.0.16

package/src/chat/chat-context.ts

@@ -1,5 +1,6 @@
 // packages/studio/src/chat/chat-context.ts
 import {
+  docKey,
   sameDocRef,
   type DocRef,
   type EditorFocus,
@@ -7,13 +8,20 @@ import {
 
 /** An element the user pointed at on the site. The agent edits that block, or the quote. */
 export type ChatPointer = {
-  locale: string;
   type: string;
   slug: string;
   blockId: string | null;
   blockType: string | null;
   blockIndex: number | null;
   quote: string;
+  /** React component that rendered the element, when the dev server exposes it. */
+  component?: string | null;
+  /** Checkout-relative source path. */
+  file?: string | null;
+  line?: number | null;
+  column?: number | null;
+  /** Component names from the element toward the layout. */
+  stack?: string[];
 };
 
 export const POINTER_CAP = 8;
@@ -24,15 +32,23 @@ export type ChatRequestContext = {
   selection: { start: number; end: number } | null;
   mentions: DocRef[];
   pointers: ChatPointer[];
+  route: string | null;
 };
 
+function parseChatRoute(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  return raw.startsWith("/") && !raw.startsWith("//") ? raw : null;
+}
+
 function samePointer(a: ChatPointer, b: ChatPointer): boolean {
   return (
-    a.locale === b.locale &&
     a.type === b.type &&
     a.slug === b.slug &&
     a.blockId === b.blockId &&
-    a.quote === b.quote
+    a.quote === b.quote &&
+    (a.component ?? null) === (b.component ?? null) &&
+    (a.file ?? null) === (b.file ?? null) &&
+    (a.line ?? null) === (b.line ?? null)
   );
 }
 
@@ -50,7 +66,12 @@ export function pointersFromMetadata(metadata: unknown): ChatPointer[] {
   return pointers.slice(0, POINTER_CAP);
 }
 
-export function addPointer(list: ChatPointer[], next: ChatPointer): ChatPointer[] {
+export function addPointer(
+  list: ChatPointer[],
+  next: ChatPointer,
+  mode: "append" | "replace" = "append",
+): ChatPointer[] {
+  if (mode === "replace") return [next];
   if (list.some((item) => samePointer(item, next))) return list;
   const added = [...list, next];
   return added.length > POINTER_CAP ? added.slice(added.length - POINTER_CAP) : added;
@@ -61,13 +82,13 @@ export function removePointer(list: ChatPointer[], next: ChatPointer): ChatPoint
 }
 
 export function chatPointerFromGrab(
-  doc: { locale?: unknown; type?: unknown; slug?: unknown },
+  doc: { type?: unknown; slug?: unknown },
   grab: unknown,
 ): ChatPointer | null {
-  if (!doc || typeof doc.locale !== "string" || typeof doc.type !== "string" || typeof doc.slug !== "string") {
+  if (!doc || typeof doc.type !== "string" || typeof doc.slug !== "string") {
     return null;
   }
-  if (!doc.locale || !doc.type || !doc.slug) return null;
+  if (!doc.type || !doc.slug) return null;
   if (!grab || typeof grab !== "object") return null;
   const value = grab as Record<string, unknown>;
   if (value.blockId !== null && typeof value.blockId !== "string") return null;
@@ -75,21 +96,56 @@ export function chatPointerFromGrab(
   if (value.blockIndex !== null && typeof value.blockIndex !== "number") return null;
   if (typeof value.quote !== "string") return null;
   return {
-    locale: doc.locale,
     type: doc.type,
     slug: doc.slug,
     blockId: value.blockId,
     blockType: value.blockType,
     blockIndex: value.blockIndex,
     quote: value.quote.replace(/\s+/g, " ").trim().slice(0, 240),
+    ...placeFrom(value),
+  };
+}
+
+function placeFrom(value: Record<string, unknown>): Pick<ChatPointer, "component" | "file" | "line" | "column" | "stack"> {
+  const component = typeof value.component === "string" && value.component ? value.component.slice(0, 80) : null;
+  const file =
+    typeof value.file === "string" && /^[\w./@+-]+\.(?:tsx|ts|jsx|js|mdx)$/.test(value.file) && !value.file.includes("..")
+      ? value.file.slice(0, 240)
+      : null;
+  const line = typeof value.line === "number" && Number.isInteger(value.line) && value.line > 0 ? value.line : null;
+  const column = typeof value.column === "number" && Number.isInteger(value.column) && value.column > 0 ? value.column : null;
+  const stack = Array.isArray(value.stack)
+    ? value.stack.filter((item): item is string => typeof item === "string" && item.length > 0).slice(0, 4)
+    : [];
+  return {
+    ...(component ? { component } : {}),
+    ...(file ? { file } : {}),
+    ...(line ? { line } : {}),
+    ...(column ? { column } : {}),
+    ...(stack.length > 0 ? { stack } : {}),
   };
 }
 
+/** A code session sends the route and the pointed blocks, not the open document. */
+export function codeSessionChatContext(input: {
+  pointers: ChatPointer[];
+  route?: string | null;
+}): ChatRequestContext {
+  return buildChatContext({
+    focus: null,
+    includeFocus: false,
+    mentions: [],
+    pointers: input.pointers,
+    route: input.route,
+  });
+}
+
 export function buildChatContext(input: {
   focus: EditorFocus | null;
   includeFocus: boolean;
   mentions: DocRef[];
   pointers: ChatPointer[];
+  route?: string | null;
 }): ChatRequestContext {
   const focusDoc = input.includeFocus && input.focus ? input.focus.docRef : null;
   const selection =
@@ -100,14 +156,20 @@ export function buildChatContext(input: {
   for (const m of input.mentions) {
     if (sameDocRef(m, focusDoc)) continue;
     if (mentions.some((x) => sameDocRef(x, m))) continue;
-    mentions.push({ locale: m.locale, type: m.type, slug: m.slug });
+    mentions.push({ type: m.type, slug: m.slug });
   }
   const pointers: ChatPointer[] = [];
   for (const pointer of input.pointers) {
     if (pointers.some((item) => samePointer(item, pointer))) continue;
     pointers.push(pointer);
   }
-  return { focusDoc, selection, mentions, pointers: pointers.slice(-POINTER_CAP) };
+  return {
+    focusDoc,
+    selection,
+    mentions,
+    pointers: pointers.slice(-POINTER_CAP),
+    route: parseChatRoute(input.route),
+  };
 }
 
 export function addMention(list: DocRef[], ref: DocRef): DocRef[] {
@@ -118,3 +180,5 @@ export function addMention(list: DocRef[], ref: DocRef): DocRef[] {
 export function removeMention(list: DocRef[], ref: DocRef): DocRef[] {
   return list.filter((x) => !sameDocRef(x, ref));
 }
+
+export { docKey };

package/src/chat/chat-helpers.ts

@@ -10,6 +10,18 @@ export type WriteToolOutput =
   | { ok: true; change?: ChatChangeSummary; changes?: ChatChangeSummary[] }
   | { ok: false; error: string; message: string };
 
+export function isCheckoutWriteTool(name: string) {
+  return name === "writeFile" || name === "editFile" || name === "deleteFile";
+}
+
+/** A finished checkout tool changed the host, so the preview should load again. */
+export function checkoutWriteReloads(name: string, output: unknown): boolean {
+  const body = output as { ok?: boolean } | undefined;
+  if (isCheckoutWriteTool(name)) return !body || body.ok !== false;
+  if (name === "runCommand") return body?.ok === true;
+  return false;
+}
+
 export function isWriteTool(name: string) {
   return (
     name === "writeDoc" ||
@@ -39,7 +51,6 @@ const TREE_STATUSES = new Set<DocStatus>(["clean", "modified", "added", "conflic
 
 /** Statuses a tool result wants applied to the local doc list immediately. */
 export type TreeStatusPatch = {
-  locale: string;
   type: string;
   slug: string;
   status: DocStatus;
@@ -55,7 +66,6 @@ export function treeStatusPatches(output: unknown): TreeStatusPatch[] {
     if (!row || typeof row !== "object") continue;
     const item = row as Partial<TreeStatusPatch>;
     if (
-      typeof item.locale !== "string" ||
       typeof item.type !== "string" ||
       !item.type ||
       typeof item.slug !== "string" ||
@@ -66,7 +76,6 @@ export function treeStatusPatches(output: unknown): TreeStatusPatch[] {
       continue;
     }
     patches.push({
-      locale: item.locale,
       type: item.type,
       slug: item.slug,
       status: item.status as DocStatus,
@@ -82,7 +91,6 @@ export function detailForTreePatch(
   patch: TreeStatusPatch,
 ): {
   workspaceId: string;
-  locale: string;
   type: string;
   slug: string;
   status?: TreeStatusPatch["status"];
@@ -91,7 +99,6 @@ export function detailForTreePatch(
   const gone = patch.absent === true || patch.status === "deleted";
   return {
     workspaceId,
-    locale: patch.locale,
     type: patch.type,
     slug: patch.slug,
     ...(gone ? { remove: true } : { status: patch.status }),
@@ -277,7 +284,7 @@ export function changeIdsInMessage(message: UIMessage): string[] {
 
 export type ChangeStackItem = Pick<
   ChatChangeSummary,
-  "id" | "locale" | "type" | "slug" | "status" | "createdAt"
+  "id" | "type" | "slug" | "status" | "createdAt"
 >;
 
 function isLaterChange(a: ChangeStackItem, b: ChangeStackItem) {
@@ -295,10 +302,10 @@ export function presentedChangeStatus(
   all: ChangeStackItem[],
 ): ChatChangeStatus {
   if (change.status !== "applied") return change.status;
-  const key = `${change.locale}/${change.type}/${change.slug}`;
+  const key = `${change.type}/${change.slug}`;
   const covered = all.some((other) => {
     if (other.id === change.id) return false;
-    if (`${other.locale}/${other.type}/${other.slug}` !== key) return false;
+    if (`${other.type}/${other.slug}` !== key) return false;
     if (other.status !== "applied" && other.status !== "kept") return false;
     return isLaterChange(other, change);
   });

package/src/chat/chat-state.ts

@@ -57,3 +57,14 @@ export function panelReducer(state: PanelState, action: PanelAction): PanelState
 export function isPanelVisible(mode: PanelMode): boolean {
   return mode === "open" || mode === "fullscreen";
 }
+
+/** A docked column has no window chrome: it cannot close, minimize, or go fullscreen. */
+export function allowsPanelAction(action: PanelAction, docked: boolean): boolean {
+  if (!docked) return true;
+  return (
+    action.type !== "toggle" &&
+    action.type !== "close" &&
+    action.type !== "minimize" &&
+    action.type !== "toggleFullscreen"
+  );
+}

package/src/chrome/AppShell.tsx

@@ -7,17 +7,23 @@ import { ChatPanel } from "../chat/ChatPanel";
 import { ChatProvider, ChatSessionScope } from "../chat/ChatProvider";
 import { colors } from "../styles/tokens.stylex";
 import { TooltipProvider } from "../ui/Tooltip";
-import { cmsWorkspaceSlug, isOrgPickerPath } from "../workspace-path";
+import {
+  cmsWorkspaceSlug,
+  isOrgPickerPath,
+  isWorkspaceCodePath,
+  isWorkspaceListPath,
+} from "../workspace-path";
 import { AppSidebar } from "./AppSidebar";
 import { WorkspaceRail } from "./ContentExplorerSidebar";
 import { CommandPalette } from "./CommandPalette";
-import { FloatingUserMenu } from "./UserMenu";
+import { CornerUserMenu, FloatingUserMenu } from "./UserMenu";
 import { EditorActionsProvider } from "./EditorActionsContext";
 import { EditorFocusProvider } from "./EditorFocusContext";
 import { EditorStatusProvider } from "./EditorStatusContext";
 import { WorkspaceNavProvider, useWorkspaceNav } from "./WorkspaceNavContext";
 import { installParentChatHotkey } from "./hotkeys";
 import { WorkspaceStatusBar } from "./WorkspaceStatusBar";
+import { CodeSessionProvider } from "../pages/code-session-context";
 
 export function AppShell({ children }: { children: React.ReactNode }) {
   return (
@@ -26,7 +32,9 @@ export function AppShell({ children }: { children: React.ReactNode }) {
         <EditorStatusProvider>
           <EditorActionsProvider>
             <EditorFocusProvider>
-              <AppShellInner>{children}</AppShellInner>
+              <CodeSessionProvider>
+                <AppShellInner>{children}</AppShellInner>
+              </CodeSessionProvider>
             </EditorFocusProvider>
           </EditorActionsProvider>
         </EditorStatusProvider>
@@ -43,6 +51,7 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
   const workspaceKey = cmsWorkspaceSlug(location.pathname);
   const workspaceNav = useWorkspaceNav();
   const orgPicker = isOrgPickerPath(location.pathname);
+  const workspaceList = isWorkspaceListPath(location.pathname);
   const embed = searchParams.get("embed") === "1";
   const [treeHost, setTreeHost] = useState<HTMLDivElement | null>(null);
   const inWorkspace = Boolean(workspaceKey && !embed && !orgPicker);
@@ -52,8 +61,9 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
     return installParentChatHotkey();
   }, [embed]);
 
+  const codeSession = Boolean(workspaceKey && isWorkspaceCodePath(location.pathname));
   const chat =
-    workspaceKey && !embed ? (
+    workspaceKey && !embed && !codeSession ? (
       <ChatSessionScope>
         <ChatBar />
         <ChatPanel />
@@ -64,7 +74,7 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
     <div {...stylex.props(styles.shell)}>
       {workspaceKey && !embed ? <WorkspaceStatusBar workspaceId={workspaceKey} /> : null}
       <div {...stylex.props(styles.body)}>
-        {orgPicker || embed ? null : inWorkspace ? (
+        {orgPicker || embed || workspaceList ? null : inWorkspace ? (
           <WorkspaceRail workspace={workspaceNav} treeHost={treeHost} />
         ) : (
           <AppSidebar />
@@ -78,6 +88,7 @@ function AppShellInner({ children }: { children: React.ReactNode }) {
         </div>
       </div>
       {orgPicker ? <FloatingUserMenu /> : null}
+      {workspaceList ? <CornerUserMenu /> : null}
       {embed ? null : <CommandPalette />}
     </div>
   );

package/src/chrome/CommandPalette.tsx

@@ -27,6 +27,7 @@ import {
 } from "./hotkeys";
 import { parsePreviewMessage } from "@backmatter/core/preview";
 import { useWorkspaceNav } from "./WorkspaceNavContext";
+import { codeSessionEntry } from "../code-session-entry";
 import {
   contentDocPath,
   contentTypePath,
@@ -310,6 +311,17 @@ export function CommandPalette() {
       });
     }
     if (workspaceNav) {
+      const codeHref = codeSessionEntry(workspaceNav.role, workspaceNav.workspaceSlug);
+      if (codeHref) {
+        list.push({
+          id: "code-session",
+          group: "Go to",
+          icon: "document",
+          label: "Code session",
+          hint: "Host and chat",
+          run: go(codeHref),
+        });
+      }
       list.push(
         {
           id: "settings-general",
@@ -357,7 +369,7 @@ export function CommandPalette() {
       }
       for (const doc of docs) {
         list.push({
-          id: `doc-${doc.locale}-${doc.type}-${doc.slug}`,
+          id: `doc-${doc.type}-${doc.slug}`,
           group: "Documents",
           icon: "document",
           label: `${doc.type}/${doc.slug}`,
@@ -370,15 +382,7 @@ export function CommandPalette() {
                 : doc.status === "modified"
                   ? "Modified"
                   : doc.status,
-          run: go(
-            contentDocPath(
-              workspaceNav.workspaceSlug,
-              doc.type,
-              doc.slug,
-              doc.locale,
-              workspaceNav.defaultLocale,
-            ),
-          ),
+          run: go(contentDocPath(workspaceNav.workspaceSlug, doc.type, doc.slug)),
         });
       }
     }

package/src/chrome/ContentExplorerSidebar.tsx

@@ -16,13 +16,14 @@ import { Tooltip } from "../ui/Tooltip";
 import {
   contentDocPath,
   contentRailHref,
-  isWorkspaceContentPath,
+  isWorkspaceCodePath,
   isWorkspaceEditorPath,
   isWorkspaceMediaPath,
   isWorkspaceSettingsPath,
   mediaPath,
   settingsPath,
 } from "../workspace-path";
+import { codeSessionEntry } from "../code-session-entry";
 import { UserMenu } from "./UserMenu";
 import {
   groupContentTypes,
@@ -38,6 +39,7 @@ import {
   ExplorerHeaderListIcon,
   ExplorerHeaderNewFileIcon,
   ExplorerTreeNewFileIcon,
+  ExplorerRailCodeIcon,
   ExplorerRailFilesIcon,
   ExplorerRailHistoryIcon,
   ExplorerRailMediaIcon,
@@ -62,6 +64,7 @@ import {
 } from "./folder-create-context";
 import { canWriteContent } from "../workspace/permissions";
 import {
+  contentRailCurrent,
   contentTreeVisible,
   toggleContentTree,
   useContentTreeOpen,
@@ -264,6 +267,7 @@ function ContentExplorerSidebar({
         pendingCount={pendingCount}
         settingsActive={settingsActive}
         workspaceSlug={workspace.workspaceSlug}
+        role={workspace.role}
         treeOpen={treeOpen}
       />
       {tree && treeHost ? createPortal(tree, treeHost) : null}
@@ -271,22 +275,26 @@ function ContentExplorerSidebar({
   );
 }
 
-function ActivityRail({
+export function ActivityRail({
   pendingCount,
   settingsActive,
   workspaceSlug,
+  role,
   treeOpen,
 }: {
   pendingCount: number;
   settingsActive: boolean;
   workspaceSlug: string;
+  role: string;
   treeOpen: boolean;
 }) {
   const navigate = useNavigate();
   const location = useLocation();
   const onDocument = isWorkspaceEditorPath(location.pathname);
   const filesLabel = onDocument ? (treeOpen ? "Hide files" : "Show files") : "Content";
-  const filesActive = isWorkspaceContentPath(location.pathname) && (!onDocument || treeOpen);
+  const filesActive = contentRailCurrent(location.pathname, treeOpen);
+  const codeHref = codeSessionEntry(role, workspaceSlug);
+  const codeActive = isWorkspaceCodePath(location.pathname);
 
   return (
     <nav
@@ -351,6 +359,18 @@ function ActivityRail({
             <ExplorerRailMediaIcon />
           </Link>
         </Tooltip>
+        {codeHref ? (
+          <Tooltip label="Code session" side="right">
+            <Link
+              to={codeHref}
+              aria-label="Code session"
+              aria-current={codeActive ? "page" : undefined}
+              {...stylex.props(styles.railBtn, codeActive && styles.railBtnActive)}
+            >
+              <ExplorerRailCodeIcon />
+            </Link>
+          </Tooltip>
+        ) : null}
       </div>
       <div {...stylex.props(styles.railBottom)}>
         <Tooltip label="Settings" side="right">

package/src/chrome/UserMenu.tsx

@@ -16,10 +16,28 @@ export function FloatingUserMenu() {
   );
 }
 
-export function UserMenu({ quiet = false, compact = false }: { quiet?: boolean; compact?: boolean }) {
+/** Small account control for full-screen pages that have no sidebar. */
+export function CornerUserMenu() {
+  return (
+    <div {...stylex.props(styles.corner)}>
+      <UserMenu quiet placement="below-end" />
+    </div>
+  );
+}
+
+export function UserMenu({
+  quiet = false,
+  compact = false,
+  placement = "above-start",
+}: {
+  quiet?: boolean;
+  compact?: boolean;
+  placement?: "above-start" | "below-end";
+}) {
   const { email, onLogout } = useAppChrome();
   const location = useLocation();
   const onAccount = location.pathname.replace(/\/$/, "") === "/account";
+  const belowEnd = placement === "below-end";
 
   return (
     <Menu.Root>
@@ -29,6 +47,7 @@ export function UserMenu({ quiet = false, compact = false }: { quiet?: boolean;
           styles.trigger,
           quiet && styles.triggerQuiet,
           compact && styles.triggerCompact,
+          belowEnd && styles.triggerCorner,
           onAccount && styles.triggerActive,
         )}
       >
@@ -40,8 +59,8 @@ export function UserMenu({ quiet = false, compact = false }: { quiet?: boolean;
       </Menu.Trigger>
       <Menu.Portal>
         <Menu.Positioner
-          side="top"
-          align={compact ? "center" : "start"}
+          side={belowEnd ? "bottom" : "top"}
+          align={belowEnd ? "end" : compact ? "center" : "start"}
           sideOffset={6}
           className={cx(popup.positioner)}
         >
@@ -81,6 +100,13 @@ const styles = stylex.create({
     zIndex: z.dropdown,
     maxWidth: "220px",
   },
+  corner: {
+    position: "fixed",
+    top: space.lg,
+    right: space.lg,
+    zIndex: z.dropdown,
+    maxWidth: "240px",
+  },
   trigger: {
     display: "flex",
     width: "100%",
@@ -128,6 +154,11 @@ const styles = stylex.create({
     fontSize: type.sm,
     fontWeight: 500,
   },
+  triggerCorner: {
+    minHeight: "44px",
+    justifyContent: "flex-end",
+    textAlign: "right",
+  },
   triggerActive: {
     backgroundColor: colors.bgActive,
   },