@backmatter/studio 0.0.14 → 0.0.16

package/src/pages/home-rows.ts

@@ -0,0 +1,140 @@
+// packages/studio/src/pages/home-rows.ts
+import type { ChangeStatus, RecentCommit } from "../api";
+import { routeFor } from "@backmatter/core";
+import { docTreeLabel } from "../chrome/content-repo-path";
+import type { ContentTypeNav } from "../chrome/content-type-groups";
+import { contentDocPath, settingsPath } from "../workspace-path";
+
+const STATUS_WORD: Record<ChangeStatus, string> = {
+  modified: "modified",
+  added: "new",
+  conflict: "conflict",
+  deleted: "deleted",
+};
+
+export type HomeChange = {
+  type: string;
+  slug: string;
+  status: ChangeStatus;
+  updatedAt?: string;
+};
+
+export type HomeModel = Pick<ContentTypeNav, "type" | "path"> & {
+  route?: string | false;
+  indexSlug?: string;
+};
+
+export type HomeRow = {
+  key: string;
+  label: string;
+  /** Public path when the model is routable. Null for data with no route. */
+  route: string | null;
+  status: string;
+  href: string | null;
+  updatedAt: string;
+};
+
+/** Public path for a changed document. Data models with `route: false` have none. */
+export function changedRoute(
+  change: Pick<HomeChange, "type" | "slug">,
+  model: Pick<HomeModel, "type" | "route" | "indexSlug"> | undefined,
+): string | null {
+  if (model?.route === false) return null;
+  const path = routeFor(
+    { type: change.type, route: model?.route, indexSlug: model?.indexSlug },
+    change.slug,
+  );
+  return path || null;
+}
+
+/** Working-tree rows for the workspace home, newest edit first. */
+export function homeRows(
+  changes: HomeChange[],
+  models: HomeModel[],
+  workspaceSlug: string,
+): HomeRow[] {
+  const rows = changes.map((change) => {
+    const model = models.find((item) => item.type === change.type);
+    const label = model ? docTreeLabel(model, change) : change.slug;
+    return {
+      key: `${change.type}/${change.slug}`,
+      label,
+      route: changedRoute(change, model),
+      status: STATUS_WORD[change.status],
+      href:
+        change.status === "deleted"
+          ? null
+          : contentDocPath(workspaceSlug, change.type, change.slug),
+      updatedAt: change.updatedAt ?? "",
+    };
+  });
+  rows.sort((a, b) => {
+    if (a.updatedAt !== b.updatedAt) return a.updatedAt < b.updatedAt ? 1 : -1;
+    return a.label.localeCompare(b.label);
+  });
+  return rows;
+}
+
+const RECENT_LIMIT = 4;
+
+export type HomeSummary = {
+  name: string;
+  branch: string;
+  defaultBranch: string;
+  uncommitted: number;
+  conflicts: number;
+  recent: HomeRow[];
+  modelCount: number;
+  repository: string | null;
+  siteUrl: string | null;
+  schemaHref: string;
+  githubHref: string;
+  generalHref: string;
+  /** Null until git status has loaded. Empty means the branch has no commits. */
+  commits: RecentCommit[] | null;
+};
+
+/** How long ago a commit landed, stable enough to test. */
+export function commitAge(iso: string, now: number): string {
+  const then = Date.parse(iso);
+  if (!Number.isFinite(then)) return "";
+  const minutes = Math.max(0, Math.round((now - then) / 60_000));
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.round(hours / 24);
+  if (days < 14) return `${days}d ago`;
+  return iso.slice(0, 10);
+}
+
+/** The few facts the workspace home can show without inventing activity. */
+export function homeSummary(input: {
+  name: string;
+  slug: string;
+  branch: string;
+  defaultBranch: string;
+  repository: string | null;
+  siteUrl: string | null;
+  modelCount: number;
+  changes: HomeChange[];
+  models: HomeModel[];
+  commits?: RecentCommit[] | null;
+}): HomeSummary {
+  const rows = homeRows(input.changes, input.models, input.slug);
+  return {
+    name: input.name,
+    branch: input.branch,
+    defaultBranch: input.defaultBranch,
+    uncommitted: rows.length,
+    conflicts: input.changes.filter((change) => change.status === "conflict").length,
+    recent: rows.slice(0, RECENT_LIMIT),
+    modelCount: input.modelCount,
+    repository: input.repository,
+    siteUrl: input.siteUrl,
+    schemaHref: settingsPath(input.slug, "schema"),
+    githubHref: settingsPath(input.slug, "github"),
+    generalHref: settingsPath(input.slug, "general"),
+    commits: input.commits ?? null,
+  };
+}

package/src/pages/preview-size.ts

@@ -0,0 +1,33 @@
+// packages/studio/src/pages/preview-size.ts
+export type PreviewSize = "desktop" | "tablet" | "phone";
+
+export const PREVIEW_SIZE_KEY = "backmatter-preview-size";
+
+export type PreviewSizeStore = {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+};
+
+export function previewFrameWidth(size: PreviewSize): "390px" | "768px" | null {
+  if (size === "phone") return "390px";
+  if (size === "tablet") return "768px";
+  return null;
+}
+
+export function readPreviewSize(store?: PreviewSizeStore): PreviewSize {
+  try {
+    const raw = (store ?? localStorage).getItem(PREVIEW_SIZE_KEY);
+    if (raw === "desktop" || raw === "tablet" || raw === "phone") return raw;
+  } catch {
+    // Private mode, or no browser storage.
+  }
+  return "desktop";
+}
+
+export function persistPreviewSize(size: PreviewSize, store?: PreviewSizeStore) {
+  try {
+    (store ?? localStorage).setItem(PREVIEW_SIZE_KEY, size);
+  } catch {
+    // Ignore quota and private mode.
+  }
+}

package/src/pages/session-preview.ts

@@ -0,0 +1,109 @@
+// packages/studio/src/pages/session-preview.ts
+// Studio side of pointing at the running host. Same preview channel as the
+// document editor. The session never pushes a document into the page.
+import { matchRoute, type RouteModel } from "@backmatter/core";
+import {
+  createPreviewEditor,
+  type PreviewChannelRef,
+  type PreviewEditorSession,
+  type PreviewTransport,
+} from "@backmatter/core/preview";
+import type { ChatPointer } from "../chat/chat-context";
+
+/** The document a hello or grab refers to. A route ref is resolved against the models. */
+export function sessionDocument(
+  ref: PreviewChannelRef,
+  models: readonly RouteModel[],
+): { type: string; slug: string } | null {
+  if (ref.type === "route") {
+    const path = ref.slug.split(/[?#]/, 1)[0] || "/";
+    const hit = matchRoute(models, path);
+    return hit ? { type: hit.type, slug: hit.slug } : null;
+  }
+  if (!ref.type || !ref.slug) return null;
+  return { type: ref.type, slug: ref.slug };
+}
+
+export type SessionPreviewBinding = {
+  arm(on: boolean): void;
+  highlight(blockId: string | null): void;
+  /** Ask a page that already loaded to send hello again. */
+  nudge(): void;
+  close(): void;
+};
+
+export function bindSessionPreview(options: {
+  transport: PreviewTransport;
+  onCanPoint(on: boolean): void;
+  onPointer(pointer: ChatPointer): void;
+  onDisarm(): void;
+  /** The document a hello or grab refers to. A route ref is resolved by the caller. */
+  documentAt(ref: PreviewChannelRef): { type: string; slug: string } | null;
+}): SessionPreviewBinding {
+  let ref: PreviewChannelRef = { type: "_", slug: "_" };
+  let known = false;
+  let wantPoint = false;
+  let editor: PreviewEditorSession | null = null;
+
+  function remember(next: PreviewChannelRef) {
+    ref = {
+      type: next.type,
+      slug: next.slug,
+      ...(next.branch ? { branch: next.branch } : {}),
+      ...(next.tree ? { tree: next.tree } : {}),
+    };
+    known = true;
+  }
+
+  editor = createPreviewEditor({
+    transport: options.transport,
+    ref: () => ref,
+    onHello(next, capabilities) {
+      remember(next);
+      options.onCanPoint(capabilities?.includes("point") ?? false);
+      editor?.point(wantPoint);
+    },
+    onGrab(grab) {
+      const doc = options.documentAt(grab.ref);
+      if (!doc) return;
+      options.onPointer({
+        type: doc.type,
+        slug: doc.slug,
+        blockId: grab.blockId,
+        blockType: grab.blockType,
+        blockIndex: grab.blockIndex,
+        quote: grab.quote,
+        ...(grab.component ? { component: grab.component } : {}),
+        ...(grab.file ? { file: grab.file } : {}),
+        ...(grab.line ? { line: grab.line } : {}),
+        ...(grab.column ? { column: grab.column } : {}),
+        ...(grab.stack ? { stack: grab.stack } : {}),
+      });
+    },
+    onPoint(on) {
+      if (!on) {
+        wantPoint = false;
+        options.onDisarm();
+      }
+    },
+  });
+
+  options.onCanPoint(false);
+
+  return {
+    arm(on) {
+      wantPoint = on;
+      if (known) editor?.point(on);
+    },
+    highlight(blockId) {
+      if (known) editor?.highlight(blockId);
+    },
+    nudge() {
+      if (!known) editor?.point(false);
+    },
+    close() {
+      editor?.close();
+      editor = null;
+    },
+  };
+}

package/src/pages/type-docs.ts

@@ -1,9 +1,6 @@
 // packages/studio/src/pages/type-docs.ts
 
-/** Slug order. A missing locale is not a language — data models omit it. */
-export function compareTypeDocs(
-  a: { slug: string; locale?: string },
-  b: { slug: string; locale?: string },
-) {
-  return a.slug.localeCompare(b.slug) || (a.locale ?? "").localeCompare(b.locale ?? "");
+/** Slug order for type index lists. */
+export function compareTypeDocs(a: { slug: string }, b: { slug: string }) {
+  return a.slug.localeCompare(b.slug);
 }

package/src/pages/use-session-preview.ts

@@ -0,0 +1,70 @@
+// packages/studio/src/pages/use-session-preview.ts
+import { useEffect, useRef } from "react";
+import type { RouteModel } from "@backmatter/core";
+import { POINTER_ARM_EVENT } from "../chat/pointer-arm";
+import { useChatUIOptional } from "../chat/ChatProvider";
+import { registerPreviewHighlight } from "../preview-highlight";
+import { previewFrameTransport } from "./preview-bridge";
+import { bindSessionPreview, sessionDocument } from "./session-preview";
+
+/** Point at a block in the code session's host, the same way the document editor does. */
+export function useSessionPreview(input: {
+  frame: HTMLIFrameElement | null;
+  origin: string | null;
+  models: readonly RouteModel[];
+  enabled: boolean;
+}): void {
+  const ui = useChatUIOptional();
+  const uiRef = useRef(ui);
+  uiRef.current = ui;
+  const modelsRef = useRef(input.models);
+  modelsRef.current = input.models;
+  const armRef = useRef<(on: boolean) => void>(() => {});
+  const highlightRef = useRef<(blockId: string | null) => void>(() => {});
+
+  useEffect(() => {
+    if (!input.enabled) return;
+    const stop = registerPreviewHighlight((blockId) => highlightRef.current(blockId));
+    function onArm(event: Event) {
+      const on = (event as CustomEvent<{ on?: boolean }>).detail?.on === true;
+      armRef.current(on);
+    }
+    window.addEventListener(POINTER_ARM_EVENT, onArm);
+    return () => {
+      window.removeEventListener(POINTER_ARM_EVENT, onArm);
+      stop();
+      uiRef.current?.setPointerHighlight("local");
+      uiRef.current?.setPreviewPointer(false);
+    };
+  }, [input.enabled]);
+
+  useEffect(() => {
+    const chat = uiRef.current;
+    const frame = input.frame;
+    const origin = input.origin;
+    if (!input.enabled || !chat?.codeSessionId || !frame || !origin) return;
+    const transport = previewFrameTransport({ frame, siteOrigin: origin });
+    if (!transport) return;
+    chat.setPointerHighlight("channel");
+    const binding = bindSessionPreview({
+      transport,
+      onCanPoint: (on) => uiRef.current?.setPreviewPointer(on),
+      onPointer: (pointer) => uiRef.current?.addPointer(pointer),
+      onDisarm: () => {
+        window.dispatchEvent(new CustomEvent(POINTER_ARM_EVENT, { detail: { on: false } }));
+      },
+      documentAt: (ref) => sessionDocument(ref, modelsRef.current),
+    });
+    armRef.current = (on) => binding.arm(on);
+    highlightRef.current = (blockId) => binding.highlight(blockId);
+    binding.nudge();
+    return () => {
+      armRef.current = () => {};
+      highlightRef.current = () => {};
+      binding.close();
+      transport.close();
+      window.dispatchEvent(new CustomEvent(POINTER_ARM_EVENT, { detail: { on: false } }));
+      uiRef.current?.setPreviewPointer(false);
+    };
+  }, [input.enabled, input.frame, input.origin]);
+}

package/src/replica/store.ts

@@ -14,25 +14,19 @@ import type {
 } from "./types";
 
 function docKey(ref: DocRef) {
-  return `${ref.locale}/${ref.type}/${ref.slug}`;
+  return `${ref.type}/${ref.slug}`;
 }
 
 const OVERLAY_STATUSES = new Set(["modified", "added", "conflict", "deleted"]);
 
 function validOverlay(row: ReplicaHit["overlay"][number]) {
-  return Boolean(
-    typeof row.locale === "string" &&
-      row.type &&
-      row.slug &&
-      OVERLAY_STATUSES.has(row.status),
-  );
+  return Boolean(row.type && row.slug && OVERLAY_STATUSES.has(row.status));
 }
 
 function changesFromDocs(docs: DocListItem[]) {
   return docs
     .filter((doc): doc is DocListItem & { status: ChangeStatus } => doc.status !== "clean")
     .map((doc) => ({
-      locale: doc.locale,
       type: doc.type,
       slug: doc.slug,
       status: doc.status,
@@ -171,6 +165,8 @@ export function createReplicaStore(
           cached.head ??
           (slot?.headSha ? { sha: slot.headSha, updatedAt: "" } : null),
         changes: changesFromDocs(slot?.docs ?? []),
+        fetchedChanges: entry.git?.fetched,
+        recentCommits: entry.git?.recentCommits,
       };
     },
   };
@@ -247,6 +243,7 @@ export function createReplicaStore(
       const existing = checkouts[snapshot.workspace.id];
       const defaultBranch =
         snapshot.workspace.githubDefaultBranch ?? snapshot.checkout.branch;
+      const sameBranch = existing?.currentBranch === snapshot.checkout.branch;
       checkouts = {
         ...checkouts,
         [snapshot.workspace.id]: {
@@ -263,6 +260,12 @@ export function createReplicaStore(
                       : "",
                 }
               : null,
+            ...(sameBranch && existing?.git?.fetched
+              ? { fetched: existing.git.fetched }
+              : {}),
+            ...(sameBranch && existing?.git?.recentCommits
+              ? { recentCommits: existing.git.recentCommits }
+              : {}),
           },
           branches: {
             ...(existing?.branches ?? {}),
@@ -308,7 +311,6 @@ export function createReplicaStore(
           pending.delete(docKey(doc));
           if (over.status === "deleted") continue;
           docs.push({
-            locale: over.locale,
             type: over.type,
             slug: over.slug,
             status: over.status,
@@ -325,7 +327,6 @@ export function createReplicaStore(
       for (const over of pending.values()) {
         if (over.status === "deleted") continue;
         docs.push({
-          locale: over.locale,
           type: over.type,
           slug: over.slug,
           status: over.status,
@@ -408,6 +409,8 @@ export function createReplicaStore(
             defaultBranch: git.defaultBranch,
             branches: git.branches,
             head: git.head,
+            fetched: git.changes,
+            recentCommits: git.recentCommits,
           },
         },
       };

package/src/replica/types.ts

@@ -2,7 +2,9 @@
 import type {
   DocListItem,
   DocStatus,
+  GitChange,
   GitState,
+  RecentCommit,
   SchemaPayload,
   WorkspaceDetail,
   WorkspaceSummary,
@@ -29,7 +31,6 @@ export type ReplicaSnapshot = {
 };
 
 export type ReplicaOverlayItem = {
-  locale: string;
   type: string;
   slug: string;
   status: Exclude<DocStatus, "clean">;
@@ -62,6 +63,10 @@ export type ReplicaGitCache = {
   defaultBranch: string;
   branches: Array<{ name: string }>;
   head: { sha: string; updatedAt: string } | null;
+  /** Git status changes for the current branch, once fetched. */
+  fetched?: GitChange[];
+  /** Latest commits on this branch, once git status has been fetched. */
+  recentCommits?: RecentCommit[];
 };
 
 export type ReplicaCheckout = {
@@ -77,7 +82,7 @@ export type ReplicaRecord = {
   checkouts: Record<string, ReplicaCheckout>;
 };
 
-export type DocRef = { locale: string; type: string; slug: string };
+export type DocRef = { type: string; slug: string };
 
 export type ReplicaPersistence = {
   load(userId: string): Promise<ReplicaRecord | null>;

package/src/site-pointer.ts

@@ -1,6 +1,8 @@
 // packages/studio/src/site-pointer.ts
 // Hit-test a click on the host page and draw the armed pointer outline.
 
+import { readElementOrigin, type ElementOrigin } from "./element-origin";
+
 export const POINTER_QUOTE_MAX = 240;
 
 export type PointerGrab = {
@@ -8,6 +10,14 @@ export type PointerGrab = {
   blockType: string | null;
   blockIndex: number | null;
   quote: string;
+} & ElementOrigin;
+
+const EMPTY_ORIGIN: ElementOrigin = {
+  component: null,
+  file: null,
+  line: null,
+  column: null,
+  stack: [],
 };
 
 function quoteOf(target: Element): string {
@@ -29,9 +39,10 @@ export function grabAt(target: Element | null, bar: Element | null): PointerGrab
 
   const marker = target.closest("[data-backmatter-block]");
   const quote = quoteOf(target);
+  const origin = readElementOrigin(target) ?? EMPTY_ORIGIN;
   if (!marker) {
-    if (!quote) return null;
-    return { blockId: null, blockType: null, blockIndex: null, quote };
+    if (!quote && !origin.component && !origin.file) return null;
+    return { blockId: null, blockType: null, blockIndex: null, quote, ...origin };
   }
   const indexRaw = marker.getAttribute("data-backmatter-index");
   const blockIndex = indexRaw !== null && /^\d+$/.test(indexRaw) ? Number(indexRaw) : null;
@@ -40,6 +51,7 @@ export function grabAt(target: Element | null, bar: Element | null): PointerGrab
     blockType: presentAttr(marker, "data-backmatter-type"),
     blockIndex,
     quote,
+    ...origin,
   };
 }
 
@@ -104,10 +116,13 @@ export function installSitePointer(
   }
 
   function onClick(event: MouseEvent) {
-    if (!armed || ignored(event.target)) return;
+    if (!armed) return;
+    const raw = event.target instanceof Element ? event.target : null;
+    // The outline sits on the element. A click on it belongs to the element under it.
+    const target = raw?.closest("[data-backmatter-pointer]") ? current : raw;
+    if (!target || ignored(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, isOpenModifier(event));
   }
@@ -174,6 +189,7 @@ function createPointerOutline(doc: Document): HTMLDivElement {
   label.style.background = "#18181b";
   label.style.color = "#ffffff";
   label.style.font = "11px/1.4 ui-sans-serif, system-ui, sans-serif";
+  label.style.pointerEvents = "none";
   label.style.display = "none";
   el.appendChild(label);
   doc.body.appendChild(el);
@@ -216,7 +232,10 @@ function positionPointerOutline(outline: HTMLDivElement, target: Element) {
   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") ?? "";
+  const name =
+    target.closest("[data-backmatter-block]")?.getAttribute("data-backmatter-type") ||
+    readElementOrigin(target)?.component ||
+    "";
   if (!label) return;
   if (!name) {
     label.textContent = "";

package/src/site-widget.tsx

@@ -27,7 +27,6 @@ import { applyThemeClass } from "./theme/apply-theme-class";
 import { TooltipProvider } from "./ui/Tooltip";
 
 export type SiteWidgetDoc = {
-  locale: string;
   type: string;
   slug: string;
   workspaceId: string;
@@ -200,12 +199,12 @@ function DocFocus({ doc }: { doc: SiteWidgetDoc }) {
   const { setFocus } = useEditorFocus();
   useEffect(() => {
     setFocus({
-      docRef: { locale: doc.locale, type: doc.type, slug: doc.slug },
+      docRef: { type: doc.type, slug: doc.slug },
       frontmatter: {},
       body: "",
       selection: null,
     });
-  }, [doc.locale, doc.type, doc.slug, setFocus]);
+  }, [doc.type, doc.slug, setFocus]);
   return null;
 }
 

package/src/studio-config.ts

@@ -14,7 +14,7 @@ export type StudioConfig = {
   dev: boolean;
   /**
    * The CMS API origin as the outside world reaches it, for URLs the Studio
-   * shows rather than fetches (the Content API popover). A site Studio fetches
+   * shows rather than fetches (the Content API URL in General settings). A site Studio fetches
    * through a relative proxy, so its host passes the real origin here.
    * Defaults to `baseUrl`.
    */

package/src/ui/ListRow.tsx

@@ -11,13 +11,13 @@ export function ListRow({
   meta,
   trailing,
 }: {
-  to: string;
+  to?: string;
   title: string;
   meta?: string;
   trailing?: string;
 }) {
-  return (
-    <Link to={to} {...stylex.props(styles.row)}>
+  const body = (
+    <>
       <span {...stylex.props(styles.body)}>
         <span {...stylex.props(styles.title)}>{title}</span>
         {meta ? <span {...stylex.props(styles.meta)}>{meta}</span> : null}
@@ -25,6 +25,12 @@ export function ListRow({
       {trailing ? (
         <span {...stylex.props(styles.trailing)}>{trailing}</span>
       ) : null}
+    </>
+  );
+  if (!to) return <div {...stylex.props(styles.row, styles.static)}>{body}</div>;
+  return (
+    <Link to={to} {...stylex.props(styles.row)}>
+      {body}
     </Link>
   );
 }
@@ -66,6 +72,9 @@ const styles = stylex.create({
       },
     },
   },
+  static: {
+    cursor: "default",
+  },
   body: {
     display: "flex",
     minWidth: 0,

package/src/ui/Page.tsx

@@ -6,10 +6,12 @@ export function PageFrame({
   children,
   flush,
   centered,
+  wide,
 }: {
   children: React.ReactNode;
   flush?: boolean;
   centered?: boolean;
+  wide?: boolean;
 }) {
   return (
     <div
@@ -22,7 +24,13 @@ export function PageFrame({
       {flush ? (
         children
       ) : (
-        <div {...stylex.props(styles.inner, centered && styles.innerCentered)}>
+        <div
+          {...stylex.props(
+            styles.inner,
+            centered && styles.innerCentered,
+            wide && styles.innerWide,
+          )}
+        >
           {children}
         </div>
       )}
@@ -108,6 +116,9 @@ const styles = stylex.create({
   innerCentered: {
     maxWidth: "440px",
   },
+  innerWide: {
+    maxWidth: "960px",
+  },
   header: {
     display: "flex",
     alignItems: "flex-start",