@backmatter/studio 0.0.15 → 0.0.17

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/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

@@ -165,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,
       };
     },
   };
@@ -241,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]: {
@@ -257,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 ?? {}),
@@ -400,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,
@@ -61,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 = {

package/src/shell-resets.css

@@ -150,10 +150,20 @@ html[data-theme="dark"]:has(.backmatter-studio)
   outline-color: #fafafa;
 }
 
+[data-no-ring]:focus,
 [data-no-ring]:focus-visible {
   outline: none;
+  outline-offset: 0;
+  box-shadow: none;
 }
 
+:is(
+    .backmatter-studio,
+    [data-backmatter-panel],
+    [data-base-ui-portal],
+    [data-selection-bar]
+  )
+  [data-no-ring]:focus,
 :is(
     .backmatter-studio,
     [data-backmatter-panel],
@@ -161,8 +171,13 @@ html[data-theme="dark"]:has(.backmatter-studio)
     [data-selection-bar]
   )
   [data-no-ring]:focus-visible,
+html[data-theme="dark"]:has(.backmatter-studio)
+  :is(.backmatter-studio, [data-base-ui-portal], [data-selection-bar])
+  [data-no-ring]:focus,
 html[data-theme="dark"]:has(.backmatter-studio)
   :is(.backmatter-studio, [data-base-ui-portal], [data-selection-bar])
   [data-no-ring]:focus-visible {
   outline: none;
+  outline-offset: 0;
+  box-shadow: none;
 }

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/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`.
    */