@backmatter/studio 0.0.14 → 0.0.16

package/src/element-origin.ts

@@ -0,0 +1,149 @@
+// packages/studio/src/element-origin.ts
+// Where a rendered element comes from, read from the React fiber the dev server
+// already attached. A production build or a non-React host yields nothing.
+
+export type ElementOrigin = {
+  component: string | null;
+  file: string | null;
+  line: number | null;
+  column: number | null;
+  stack: string[];
+};
+
+const STACK_CAP = 4;
+const SOURCE_ROOT = /(?:^|\/)((?:src|app|pages|components|blocks|lib|content)\/[\w./@+-]+\.(?:tsx|ts|jsx|js|mdx))$/;
+const SOURCE_FILE = /^[\w./@+-]+\.(?:tsx|ts|jsx|js|mdx)$/;
+
+type Fiber = {
+  type?: unknown;
+  elementType?: unknown;
+  return?: Fiber | null;
+  _debugStack?: unknown;
+  _debugInfo?: unknown;
+};
+
+function fiberOf(element: Element): Fiber | null {
+  for (const key of Object.keys(element)) {
+    if (!key.startsWith("__reactFiber$") && !key.startsWith("__reactInternalInstance$")) continue;
+    const value = (element as unknown as Record<string, unknown>)[key];
+    if (value && typeof value === "object") return value as Fiber;
+  }
+  return null;
+}
+
+function functionName(value: unknown): string | null {
+  if (typeof value === "function") {
+    const named = value as { displayName?: string; name?: string };
+    const name = named.displayName || named.name;
+    return name && name !== "Unknown" ? name : null;
+  }
+  if (!value || typeof value !== "object") return null;
+  const record = value as { displayName?: string; render?: unknown; type?: unknown };
+  if (typeof record.displayName === "string" && record.displayName) return record.displayName;
+  const rendered = functionName(record.render);
+  if (rendered) return rendered;
+  return functionName(record.type);
+}
+
+function componentName(fiber: Fiber): string | null {
+  const named = functionName(fiber.type);
+  if (named) return named;
+  return functionName(fiber.elementType);
+}
+
+function pushName(names: string[], name: string | null) {
+  if (!name || names.includes(name) || names.length >= STACK_CAP) return;
+  names.push(name);
+}
+
+function normalizeFile(raw: string): string | null {
+  let file = raw.trim();
+  file = file.replace(/^webpack-internal:\/\/\/(?:\([^)]*\)\/)?/, "");
+  file = file.replace(/^webpack:\/\/\/?/, "");
+  if (file.startsWith("./")) file = file.slice(2);
+  if (file.startsWith("file://")) {
+    try {
+      file = decodeURIComponent(new URL(file).pathname);
+    } catch {
+      return null;
+    }
+  }
+  file = file.split(/[?#]/)[0] ?? "";
+  if (/node_modules|react-dom|react-jsx|next\/dist|webpack\/bootstrap|_next\/|https?:/i.test(file)) return null;
+  const rooted = file.match(SOURCE_ROOT);
+  if (rooted?.[1]) return rooted[1];
+  if (SOURCE_FILE.test(file) && !file.startsWith("/") && !file.includes("..")) return file;
+  return null;
+}
+
+function frameAt(line: string): { file: string; line: number; column: number } | null {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.includes("react-stack-top-frame") || trimmed.includes("react_stack_bottom_frame")) {
+    return null;
+  }
+  const chrome = trimmed.match(/^at\s+(?:async\s+)?(?:.*?\s+\()?(.+?):(\d+):(\d+)\)?$/);
+  const firefox = chrome ? null : trimmed.match(/^(?:.*@)?(.+?):(\d+):(\d+)$/);
+  const match = chrome ?? firefox;
+  if (!match?.[1]) return null;
+  const file = normalizeFile(match[1]);
+  if (!file) return null;
+  const lineNo = Number(match[2]);
+  const column = Number(match[3]);
+  if (!Number.isInteger(lineNo) || lineNo < 1 || !Number.isInteger(column) || column < 1) return null;
+  return { file, line: lineNo, column };
+}
+
+function stackText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && "stack" in value) {
+    const stack = (value as { stack?: unknown }).stack;
+    return typeof stack === "string" ? stack : "";
+  }
+  return "";
+}
+
+function locationFromStack(value: unknown): { file: string; line: number; column: number } | null {
+  const text = stackText(value);
+  if (!text) return null;
+  for (const line of text.split("\n")) {
+    if (line.includes("react_stack_bottom_frame")) break;
+    const frame = frameAt(line);
+    if (frame) return frame;
+  }
+  return null;
+}
+
+function debugNames(value: unknown, names: string[]) {
+  if (!Array.isArray(value)) return;
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object") continue;
+    const name = (entry as { name?: unknown }).name;
+    if (typeof name === "string") pushName(names, name);
+  }
+}
+
+/** The component and source behind an element, when the dev fiber exposes them. */
+export function readElementOrigin(element: Element): ElementOrigin | null {
+  const names: string[] = [];
+  let file: string | null = null;
+  let line: number | null = null;
+  let column: number | null = null;
+  let fiber = fiberOf(element);
+  const seen = new Set<Fiber>();
+  while (fiber && !seen.has(fiber) && names.length < STACK_CAP) {
+    seen.add(fiber);
+    pushName(names, componentName(fiber));
+    debugNames(fiber._debugInfo, names);
+    if (!file) {
+      const located = locationFromStack(fiber._debugStack);
+      if (located) {
+        file = located.file;
+        line = located.line;
+        column = located.column;
+      }
+    }
+    fiber = fiber.return ?? null;
+  }
+  if (names.length === 0 && !file) return null;
+  return { component: names[0] ?? null, file, line, column, stack: names };
+}

package/src/host-pointer-bootstrap.ts

@@ -0,0 +1,11 @@
+// packages/studio/src/host-pointer-bootstrap.ts
+// Built into the script the code session sandbox injects. The source of truth
+// is bindHostPointer, the same pointer the document editor's preview uses.
+import { bindHostPointer } from "./host-pointer";
+
+function start() {
+  bindHostPointer(document);
+}
+
+if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start);
+else start();

package/src/host-pointer.ts

@@ -0,0 +1,147 @@
+// packages/studio/src/host-pointer.ts
+//
+// Page side of the preview channel for a framed host that is not running the
+// preview client. The document editor's preview page uses the same pointer and
+// the same messages (hello, point, grab, highlight). This does not accept a
+// document push.
+import {
+  createWindowPreviewTransport,
+  samePreviewRef,
+  type PreviewChannelRef,
+  type PreviewWindowLike,
+} from "@backmatter/core/preview";
+import { installPreviewPointer } from "./install-preview-pointer";
+import { findPointedElement, highlightPointedElement } from "./site-pointer";
+
+const POINTER_STYLE = "html.backmatter-pointing, html.backmatter-pointing * { cursor: crosshair !important; }";
+
+function parentOrigin(view: Window): string {
+  try {
+    if (view.document.referrer) return new URL(view.document.referrer).origin;
+  } catch {
+    // A malformed referrer means we cannot name the framing Studio.
+  }
+  const ancestors = (view.location as Location & { ancestorOrigins?: DOMStringList }).ancestorOrigins;
+  if (ancestors && ancestors.length > 0) return ancestors.item(0) ?? "";
+  return "";
+}
+
+/** The document the page announces. A missing marker falls back to the route. */
+export function hostPointerRef(doc: Document): PreviewChannelRef {
+  const marker = doc.querySelector("[data-backmatter-doc]");
+  const type = marker?.getAttribute("data-type");
+  const slug = marker?.getAttribute("data-slug");
+  if (type && slug) return { type, slug };
+  const path = doc.defaultView?.location.pathname || "/";
+  return { type: "route", slug: path };
+}
+
+/**
+ * Tell the framing Studio this page can be pointed at, and arm when it asks.
+ * No-ops on a top-level page and on a page that already runs the preview client.
+ */
+export function bindHostPointer(doc: Document): () => void {
+  const view = doc.defaultView;
+  if (!view || view.parent === view) return () => {};
+  if (doc.querySelector("[data-backmatter-preview]")) return () => {};
+  const flagged = view as Window & { __backmatterHostPointer?: boolean };
+  if (flagged.__backmatterHostPointer) return () => {};
+
+  const origin = parentOrigin(view);
+  if (!origin) return () => {};
+  flagged.__backmatterHostPointer = true;
+
+  const ref = hostPointerRef(doc);
+  if (!doc.querySelector("[data-backmatter-pointer-style]")) {
+    const style = doc.createElement("style");
+    style.setAttribute("data-backmatter-pointer-style", "");
+    style.textContent = POINTER_STYLE;
+    doc.head.appendChild(style);
+  }
+
+  const transport = createWindowPreviewTransport({
+    target: view.parent,
+    targetOrigin: origin,
+    allowedOrigins: [origin],
+    host: view as unknown as PreviewWindowLike,
+  });
+    function sendGrab(grab: {
+      blockId: string | null;
+      blockType: string | null;
+      blockIndex: number | null;
+      quote: string;
+      shift: boolean;
+      component?: string | null;
+      file?: string | null;
+      line?: number | null;
+      column?: number | null;
+      stack?: string[];
+    }) {
+      transport.send({
+        type: "backmatter:grab",
+        v: 1,
+        ref,
+        blockId: grab.blockId,
+        blockType: grab.blockType,
+        blockIndex: grab.blockIndex,
+        quote: grab.quote,
+        shift: grab.shift,
+        ...(grab.component ? { component: grab.component } : {}),
+        ...(grab.file ? { file: grab.file } : {}),
+        ...(grab.line ? { line: grab.line } : {}),
+        ...(grab.column ? { column: grab.column } : {}),
+        ...(grab.stack && grab.stack.length > 0 ? { stack: grab.stack } : {}),
+      });
+    }
+    const pointer = installPreviewPointer(doc, {
+    bar: () => doc.querySelector("[data-backmatter-devbar]"),
+    includeUnmarked: true,
+    ignore: (target) => {
+      if (!(target instanceof view.Element)) return true;
+      if (target.closest("[data-backmatter-panel]")) return true;
+      return target.closest("iframe") !== null;
+    },
+    onEditorGrab: sendGrab,
+    onUnmarkedGrab: sendGrab,
+    onDevbarGrab: () => {},
+    onEscape: (source) => {
+      if (source !== "editor") return;
+      transport.send({ type: "backmatter:point", v: 1, ref, on: false });
+    },
+  });
+  const unsubscribe = transport.subscribe((message) => {
+    if (message.type === "backmatter:hotkey" || message.type === "backmatter:hello") return;
+    if (!("ref" in message)) return;
+    // Studio binds after the first hello on a reload. A message for another
+    // document is the cue to announce this page again.
+    if (!samePreviewRef(message.ref, ref)) {
+      if (message.type === "backmatter:point" || message.type === "backmatter:highlight") hello();
+      return;
+    }
+    if (message.type === "backmatter:point") {
+      if (message.on) pointer.arm("editor");
+      else if (pointer.source() === "editor") pointer.disarm();
+      return;
+    }
+    if (message.type === "backmatter:highlight") {
+      const target = message.blockId
+        ? findPointedElement(doc, { blockId: message.blockId, quote: "" })
+        : null;
+      highlightPointedElement(doc, target);
+    }
+  });
+
+  function hello() {
+    transport.send({ type: "backmatter:hello", v: 1, ref, capabilities: ["point"] });
+  }
+  hello();
+  const retries = [100, 500].map((ms) => view.setTimeout(hello, ms));
+
+  return () => {
+    for (const id of retries) view.clearTimeout(id);
+    unsubscribe();
+    pointer.dispose();
+    transport.close();
+    flagged.__backmatterHostPointer = false;
+  };
+}

package/src/install-preview-pointer.ts

@@ -8,12 +8,25 @@ import {
   type PointerGrab,
 } from "./site-pointer";
 
+function placeOf(grab: PointerGrab) {
+  return {
+    ...(grab.component ? { component: grab.component } : {}),
+    ...(grab.file ? { file: grab.file } : {}),
+    ...(grab.line ? { line: grab.line } : {}),
+    ...(grab.column ? { column: grab.column } : {}),
+    ...(grab.stack.length > 0 ? { stack: grab.stack } : {}),
+  };
+}
+
 export function installPreviewPointer(
   doc: Document,
   options: {
     bar: () => Element | null;
     ignore?: (target: EventTarget | null) => boolean;
-    onEditorGrab: (grab: RoutedGrab) => void;
+    /** Armed clicks that are not page blocks. The document editor leaves this off. */
+    includeUnmarked?: boolean;
+    onEditorGrab: (grab: RoutedGrab & ReturnType<typeof placeOf>) => void;
+    onUnmarkedGrab?: (grab: PointerGrab & { shift: boolean }) => void;
     onDevbarGrab: (grab: PointerGrab) => void;
     onEscape?: (source: PointerArmSource) => void;
   },
@@ -27,8 +40,11 @@ export function installPreviewPointer(
 
   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);
+    if (route.to === "editor") options.onEditorGrab({ ...route.grab, ...placeOf(grab) });
+    else if (route.to === "devbar") options.onDevbarGrab(grab);
+    else if (options.includeUnmarked && source === "editor" && (grab.quote || grab.component || grab.file)) {
+      options.onUnmarkedGrab?.({ ...grab, shift });
+    }
   }
 
   const pointer = installSitePointer(doc, {

package/src/pages/CodeSessionFiles.tsx

@@ -0,0 +1,221 @@
+// packages/studio/src/pages/CodeSessionFiles.tsx
+import { useMemo } from "react";
+import * as stylex from "@stylexjs/stylex";
+import { colors, space, type } from "../styles/tokens.stylex";
+import { Text } from "../ui/Text";
+import { fileTree, type FileNode, type WorkspaceFile } from "./code-session-files";
+
+export type FilesView = {
+  /** Checkout paths, or null while they load. */
+  list: string[] | null;
+  error: string | null;
+  selected: string | null;
+  opened: WorkspaceFile | "loading" | null;
+  onSelect: (path: string) => void;
+};
+
+export function CodeSessionFiles({ list, error, selected, opened, onSelect }: FilesView) {
+  const tree = useMemo(() => fileTree(list ?? []), [list]);
+
+  return (
+    <div {...stylex.props(styles.shell)} aria-label="Session files">
+      <nav {...stylex.props(styles.tree)} aria-label="Checkout">
+        {error ? (
+          <p {...stylex.props(styles.note, styles.error)}>{error}</p>
+        ) : list === null ? (
+          <p {...stylex.props(styles.note)}>Reading the checkout…</p>
+        ) : list.length === 0 ? (
+          <p {...stylex.props(styles.note)}>The checkout is empty.</p>
+        ) : (
+          <TreeLevel nodes={tree} depth={0} selected={selected} onSelect={onSelect} />
+        )}
+      </nav>
+      <section {...stylex.props(styles.viewer)} aria-label="File">
+        {selected ? (
+          <>
+            <header {...stylex.props(styles.viewerHeader)}>
+              <span {...stylex.props(styles.path)}>{selected}</span>
+            </header>
+            <FileBody opened={opened} />
+          </>
+        ) : (
+          <div {...stylex.props(styles.empty)}>
+            <Text size="sm" tone="muted">
+              Pick a file to read it as the host has it now.
+            </Text>
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}
+
+function TreeLevel({
+  nodes,
+  depth,
+  selected,
+  onSelect,
+}: {
+  nodes: FileNode[];
+  depth: number;
+  selected: string | null;
+  onSelect: (path: string) => void;
+}) {
+  const indent = { paddingLeft: `${8 + depth * 12}px` };
+  return (
+    <ul {...stylex.props(styles.level)}>
+      {nodes.map((node) =>
+        node.kind === "dir" ? (
+          <li key={node.path}>
+            <details open={selected?.startsWith(`${node.path}/`) ?? false}>
+              <summary {...stylex.props(styles.row, styles.dir)} style={indent}>
+                {node.name}
+              </summary>
+              <TreeLevel
+                nodes={node.children}
+                depth={depth + 1}
+                selected={selected}
+                onSelect={onSelect}
+              />
+            </details>
+          </li>
+        ) : (
+          <li key={node.path}>
+            <button
+              type="button"
+              aria-current={selected === node.path ? "true" : undefined}
+              onClick={() => onSelect(node.path)}
+              {...stylex.props(styles.row, styles.file, selected === node.path && styles.fileActive)}
+              style={indent}
+            >
+              {node.name}
+            </button>
+          </li>
+        ),
+      )}
+    </ul>
+  );
+}
+
+function FileBody({ opened }: { opened: WorkspaceFile | "loading" | null }) {
+  if (opened === "loading" || opened === null) {
+    return <p {...stylex.props(styles.note)}>{opened === "loading" ? "Opening…" : ""}</p>;
+  }
+  if ("binary" in opened) {
+    return <p {...stylex.props(styles.note)}>Binary file, {formatSize(opened.size)}.</p>;
+  }
+  if ("tooLarge" in opened) {
+    return <p {...stylex.props(styles.note)}>Too large to show here ({formatSize(opened.size)}).</p>;
+  }
+  return <pre {...stylex.props(styles.code)}>{opened.content}</pre>;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+const hover = "@media (hover: hover)";
+
+const styles = stylex.create({
+  shell: {
+    display: "flex",
+    flex: 1,
+    minWidth: 0,
+    minHeight: 0,
+  },
+  tree: {
+    width: "260px",
+    flexShrink: 0,
+    overflow: "auto",
+    paddingBlock: space.sm,
+    borderRightWidth: 1,
+    borderRightStyle: "solid",
+    borderRightColor: colors.border,
+    backgroundColor: colors.bgSurface,
+  },
+  level: {
+    margin: 0,
+    padding: 0,
+    listStyle: "none",
+  },
+  row: {
+    display: "block",
+    width: "100%",
+    boxSizing: "border-box",
+    paddingBlock: "3px",
+    paddingRight: space.sm,
+    font: "inherit",
+    fontSize: type.xs,
+    lineHeight: 1.5,
+    textAlign: "left",
+    whiteSpace: "nowrap",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    cursor: "pointer",
+    borderWidth: 0,
+    color: colors.text,
+    backgroundColor: {
+      default: "transparent",
+      [hover]: { default: null, ":hover": colors.bgHover },
+    },
+  },
+  dir: {
+    fontWeight: 500,
+  },
+  file: {
+    color: colors.textMuted,
+  },
+  fileActive: {
+    color: colors.text,
+    backgroundColor: colors.bgActive,
+  },
+  viewer: {
+    display: "flex",
+    flex: 1,
+    flexDirection: "column",
+    minWidth: 0,
+    minHeight: 0,
+    backgroundColor: colors.bgApp,
+  },
+  viewerHeader: {
+    paddingBlock: space.sm,
+    paddingInline: space.lg,
+    borderBottomWidth: 1,
+    borderBottomStyle: "solid",
+    borderBottomColor: colors.border,
+  },
+  path: {
+    fontFamily: type.mono,
+    fontSize: type.xs,
+    color: colors.textMuted,
+  },
+  code: {
+    flex: 1,
+    margin: 0,
+    overflow: "auto",
+    padding: space.lg,
+    fontFamily: type.mono,
+    fontSize: "12px",
+    lineHeight: 1.6,
+    tabSize: 2,
+    color: colors.text,
+  },
+  empty: {
+    display: "flex",
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  note: {
+    margin: 0,
+    paddingBlock: space.sm,
+    paddingInline: space.lg,
+    fontSize: type.xs,
+    color: colors.textMuted,
+  },
+  error: {
+    color: colors.danger,
+  },
+});