@backmatter/studio 0.0.1

package/src/pages/selection-format.ts

@@ -0,0 +1,179 @@
+// packages/studio/src/pages/selection-format.ts
+export type BlockFormat = "paragraph" | "heading" | "list" | "quote";
+
+const BLOCK_SELECTOR = "p, h1, h2, h3, h4, h5, h6, ul, ol, blockquote";
+
+export function blockFormatOf(host: HTMLElement, range?: Range): BlockFormat {
+  const current = blockElement(host, range);
+  if (!current) return "paragraph";
+  return formatOfTag(current.tagName);
+}
+
+export function applyBlockFormat(host: HTMLElement, format: BlockFormat, range?: Range): void {
+  const current = blockElement(host, range);
+  const html = current ? contentsHtml(current) : host.innerHTML;
+  host.replaceChildren(createBlock(format, html));
+}
+
+export function marksAt(range: Range): { bold: boolean; italic: boolean; href: string | null } {
+  const element = elementFrom(range.startContainer);
+  return {
+    bold: Boolean(element?.closest("strong, b")),
+    italic: Boolean(element?.closest("em, i")),
+    href: element?.closest("a")?.getAttribute("href") ?? null,
+  };
+}
+
+export function toggleInline(range: Range, tag: "strong" | "em"): void {
+  const existing = elementFrom(range.commonAncestorContainer)?.closest(tag);
+  if (
+    existing instanceof HTMLElement &&
+    existing.contains(range.startContainer) &&
+    existing.contains(range.endContainer)
+  ) {
+    unwrap(existing);
+    return;
+  }
+  wrapRange(range, document.createElement(tag));
+}
+
+export function applyLink(range: Range, href: string): void {
+  const existing = elementFrom(range.startContainer)?.closest("a");
+  const trimmed = href.trim();
+  if (
+    existing instanceof HTMLElement &&
+    existing.contains(range.startContainer) &&
+    existing.contains(range.endContainer)
+  ) {
+    if (!trimmed) {
+      unwrap(existing);
+      return;
+    }
+    existing.setAttribute("href", trimmed);
+    selectContents(existing);
+    return;
+  }
+  if (!trimmed) return;
+  const anchor = document.createElement("a");
+  anchor.setAttribute("href", trimmed);
+  anchor.setAttribute("target", "_blank");
+  anchor.setAttribute("rel", "noreferrer");
+  wrapRange(range, anchor);
+}
+
+export function placeCaretAtEnd(host: HTMLElement): void {
+  const target = host.querySelector("p, h1, h2, h3, h4, h5, h6, li") ?? host;
+  host.focus();
+  const range = document.createRange();
+  range.selectNodeContents(target);
+  range.collapse(false);
+  const selection = window.getSelection();
+  if (!selection) return;
+  selection.removeAllRanges();
+  selection.addRange(range);
+}
+
+function blockElement(host: HTMLElement, range?: Range): HTMLElement | null {
+  const blocks = [...host.querySelectorAll(BLOCK_SELECTOR)].filter(
+    (element): element is HTMLElement => element instanceof HTMLElement,
+  );
+  if (blocks.length === 0) return null;
+  if (!range) return blocks[0] ?? null;
+  return (
+    blocks.find(
+      (element) =>
+        element.contains(range.startContainer) || element.contains(range.endContainer),
+    ) ??
+    blocks[0] ??
+    null
+  );
+}
+
+function formatOfTag(tag: string): BlockFormat {
+  if (tag === "UL" || tag === "OL") return "list";
+  if (tag === "BLOCKQUOTE") return "quote";
+  if (/^H[1-6]$/.test(tag)) return "heading";
+  return "paragraph";
+}
+
+function contentsHtml(element: HTMLElement): string {
+  const tag = element.tagName;
+  if (tag === "UL" || tag === "OL") {
+    return [...element.children]
+      .filter((child) => child.tagName === "LI")
+      .map((child) => child.innerHTML)
+      .filter(Boolean)
+      .join(" ");
+  }
+  if (tag === "BLOCKQUOTE") {
+    const inner = element.querySelector(BLOCK_SELECTOR);
+    if (inner instanceof HTMLElement && inner !== element) return contentsHtml(inner);
+    return element.innerHTML;
+  }
+  return element.innerHTML;
+}
+
+function createBlock(format: BlockFormat, html: string): HTMLElement {
+  if (format === "heading") {
+    const heading = document.createElement("h2");
+    heading.innerHTML = html;
+    return heading;
+  }
+  if (format === "list") {
+    const list = document.createElement("ul");
+    const item = document.createElement("li");
+    item.innerHTML = html;
+    list.appendChild(item);
+    return list;
+  }
+  if (format === "quote") {
+    const quote = document.createElement("blockquote");
+    const paragraph = document.createElement("p");
+    paragraph.innerHTML = html;
+    quote.appendChild(paragraph);
+    return quote;
+  }
+  const paragraph = document.createElement("p");
+  paragraph.innerHTML = html;
+  return paragraph;
+}
+
+function elementFrom(node: Node): Element | null {
+  return node instanceof Element ? node : node.parentElement;
+}
+
+function wrapRange(range: Range, wrapper: HTMLElement): void {
+  try {
+    range.surroundContents(wrapper);
+  } catch {
+    wrapper.appendChild(range.extractContents());
+    range.insertNode(wrapper);
+  }
+  selectContents(wrapper);
+}
+
+function unwrap(element: HTMLElement): void {
+  const parent = element.parentNode;
+  if (!parent) return;
+  const first = element.firstChild;
+  const last = element.lastChild;
+  while (element.firstChild) parent.insertBefore(element.firstChild, element);
+  element.remove();
+  if (!first || !last) return;
+  const range = document.createRange();
+  range.setStartBefore(first);
+  range.setEndAfter(last);
+  const selection = window.getSelection();
+  if (!selection) return;
+  selection.removeAllRanges();
+  selection.addRange(range);
+}
+
+function selectContents(element: HTMLElement): void {
+  const selection = window.getSelection();
+  if (!selection) return;
+  const range = document.createRange();
+  range.selectNodeContents(element);
+  selection.removeAllRanges();
+  selection.addRange(range);
+}

package/src/pages/type-docs.ts

@@ -0,0 +1,9 @@
+// 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 ?? "");
+}

package/src/replica/BootstrapSplash.tsx

@@ -0,0 +1,80 @@
+// packages/studio/src/replica/BootstrapSplash.tsx
+import { Snake } from "loading-dev";
+import * as stylex from "@stylexjs/stylex";
+import { Shimmer } from "../chat/Shimmer";
+import { colors, space, type } from "../styles/tokens.stylex";
+import { Text } from "../ui/Text";
+
+export function BootstrapSplash({
+  error,
+  onRetry,
+}: {
+  error?: string | null;
+  onRetry?: () => void;
+}) {
+  return (
+    <div
+      {...stylex.props(styles.root)}
+      aria-busy={!error || undefined}
+      aria-live="polite"
+    >
+      <div {...stylex.props(styles.mark)}>
+        {error ? null : (
+          <span {...stylex.props(styles.spinner)}>
+            <Snake size={20} />
+          </span>
+        )}
+        <Text as="p" size="xs" tone="muted" weight="semibold">
+          {error ? "BACKMATTER" : <Shimmer>BACKMATTER</Shimmer>}
+        </Text>
+      </div>
+      {error ? (
+        <>
+          <Text tone="danger">{error}</Text>
+          {onRetry ? (
+            <button type="button" {...stylex.props(styles.retry)} onClick={onRetry}>
+              Retry
+            </button>
+          ) : null}
+        </>
+      ) : null}
+    </div>
+  );
+}
+
+const styles = stylex.create({
+  root: {
+    display: "flex",
+    boxSizing: "border-box",
+    width: "100vw",
+    height: "100dvh",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: space.lg,
+    backgroundColor: colors.bgApp,
+    color: colors.text,
+  },
+  mark: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    gap: space.sm,
+  },
+  spinner: {
+    display: "flex",
+    color: colors.textMuted,
+  },
+  retry: {
+    cursor: "pointer",
+    borderWidth: 1,
+    borderStyle: "solid",
+    borderColor: colors.border,
+    borderRadius: 4,
+    backgroundColor: colors.bgSurface,
+    color: colors.text,
+    paddingInline: space.xl,
+    paddingBlock: space.sm,
+    fontSize: type.sm,
+  },
+});

package/src/replica/ReplicaProvider.tsx

@@ -0,0 +1,267 @@
+// packages/studio/src/replica/ReplicaProvider.tsx
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+import { useLocation } from "react-router";
+import {
+  checkoutBranch,
+  fetchAllWorkspaces,
+  fetchMe,
+  fetchReplica,
+  notifyWorkspaceChanged,
+  type ApiError,
+  type TreeChangeDetail,
+} from "../api";
+import { rememberLastUser } from "../last-user";
+import { readLastWorkspace, rememberLastWorkspace } from "../last-workspace";
+import { cmsWorkspaceSlug } from "../workspace-path";
+import { BootstrapSplash } from "./BootstrapSplash";
+import { replicaCacheFromSlot } from "./cache";
+import { replicaBoot, replicaStore } from "./instance";
+import { pullReplica } from "./pull";
+import { useReplicaState } from "./useReplica";
+
+export type ReplicaSession = {
+  user: { id: string; email: string };
+  bootstrapError: string | null;
+  retryBootstrap: () => void;
+  ensureWorkspace: (idOrSlug: string) => Promise<void>;
+  applyCheckout: (workspaceId: string, branch: string) => Promise<void>;
+  syncCheckout: (workspaceId: string, branch: string) => Promise<void>;
+  revalidate: (workspaceId: string, intendedBranch?: string) => Promise<void>;
+};
+
+export const ReplicaSessionContext = createContext<ReplicaSession | null>(null);
+
+export function useReplicaSession(): ReplicaSession {
+  const ctx = useContext(ReplicaSessionContext);
+  if (!ctx) {
+    throw new Error("useReplicaSession must be used within ReplicaProvider");
+  }
+  return ctx;
+}
+
+function errorMessage(err: unknown) {
+  return err instanceof Error ? err.message : "Could not load";
+}
+
+function resolveWorkspaceId(idOrSlug: string) {
+  const state = replicaStore.getState();
+  return state.workspace(idOrSlug)?.id ?? state.workspaceBySlug(idOrSlug)?.id ?? idOrSlug;
+}
+
+export function ReplicaProvider({
+  user,
+  children,
+}: {
+  user: { id: string; email: string };
+  children: ReactNode;
+}) {
+  const location = useLocation();
+  const slug = cmsWorkspaceSlug(location.pathname);
+  const [bootstrapError, setBootstrapError] = useState<string | null>(null);
+  const [bootGen, setBootGen] = useState(0);
+
+  const applyFetched = useCallback(
+    async (idOrSlug: string, intendedBranch?: string) => {
+      const id = resolveWorkspaceId(idOrSlug);
+      const state = replicaStore.getState();
+      const branch = intendedBranch ?? state.currentBranch(id);
+      const ok = await pullReplica({
+        workspaceId: idOrSlug,
+        cache: replicaCacheFromSlot(branch, branch ? state.checkout(id) : null),
+        intendedBranch,
+        fetchReplica,
+        store: replicaStore,
+      });
+      if (!ok) return;
+      const workspace = replicaStore.getState().workspace(id);
+      if (!workspace) return;
+      replicaStore.setActiveWorkspace(workspace.id);
+      const nextUser = replicaStore.getState().control?.user;
+      if (nextUser) rememberLastUser(nextUser);
+      rememberLastWorkspace(user.id, workspace.id);
+    },
+    [user.id],
+  );
+
+  const revalidate = useCallback(
+    async (workspaceId: string, intendedBranch?: string) => {
+      try {
+        await applyFetched(workspaceId, intendedBranch);
+      } catch (err) {
+        replicaStore.setRefreshError(errorMessage(err));
+      }
+    },
+    [applyFetched],
+  );
+
+  const ensureWorkspace = useCallback(
+    async (idOrSlug: string) => {
+      replicaStore.setActiveWorkspace(idOrSlug);
+      if (replicaStore.getState().ready) {
+        void revalidate(idOrSlug);
+        return;
+      }
+      await applyFetched(idOrSlug);
+    },
+    [applyFetched, revalidate],
+  );
+
+  const syncCheckout = useCallback(
+    async (workspaceId: string, branch: string) => {
+      const id = resolveWorkspaceId(workspaceId);
+      const result = replicaStore.setCheckout(id, branch);
+      if (result === "miss") {
+        await applyFetched(id, branch);
+      } else {
+        void revalidate(id, branch);
+      }
+    },
+    [applyFetched, revalidate],
+  );
+
+  const applyCheckout = useCallback(
+    async (workspaceId: string, branch: string) => {
+      const id = resolveWorkspaceId(workspaceId);
+      await checkoutBranch(id, branch);
+      notifyWorkspaceChanged();
+      await syncCheckout(id, branch);
+    },
+    [syncCheckout],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    setBootstrapError(null);
+
+    async function boot() {
+      if (replicaStore.getState().sessionUserId !== user.id) {
+        await replicaStore.hydrate(user.id, slug ?? readLastWorkspace(user.id));
+      } else {
+        await replicaBoot;
+      }
+      if (cancelled) return;
+
+      if (slug) {
+        replicaStore.setActiveWorkspace(slug);
+        if (replicaStore.getState().ready) {
+          void revalidate(slug);
+          return;
+        }
+        try {
+          await applyFetched(slug);
+        } catch (err) {
+          if (!cancelled) setBootstrapError(errorMessage(err));
+        }
+        return;
+      }
+
+      const last = readLastWorkspace(user.id);
+      if (last) {
+        replicaStore.setActiveWorkspace(last);
+        if (replicaStore.getState().control && replicaStore.getState().ready) {
+          void revalidate(last);
+          return;
+        }
+        try {
+          await applyFetched(last);
+          if (cancelled) return;
+          if (replicaStore.getState().ready) return;
+        } catch (err) {
+          const apiErr = err as ApiError;
+          if (apiErr.status !== 404 && !replicaStore.getState().control) {
+            if (!cancelled) setBootstrapError(errorMessage(err));
+            return;
+          }
+        }
+      }
+
+      replicaStore.setActiveWorkspace(null);
+      if (replicaStore.getState().control) return;
+      try {
+        const workspaces = await fetchAllWorkspaces();
+        if (cancelled) return;
+        rememberLastUser(user);
+        replicaStore.applyControl({
+          user,
+          workspaces: workspaces.workspaces,
+        });
+      } catch (err) {
+        if (!cancelled) setBootstrapError(errorMessage(err));
+      }
+    }
+
+    void boot();
+    return () => {
+      cancelled = true;
+    };
+  }, [user, slug, bootGen, applyFetched, revalidate]);
+
+  useEffect(() => {
+    function onTree(event: Event) {
+      const detail = (event as CustomEvent<TreeChangeDetail>).detail;
+      if (detail?.workspaceId && detail.remove) {
+        replicaStore.removeDoc(detail.workspaceId, detail);
+        return;
+      }
+      if (detail?.status && detail.workspaceId) {
+        replicaStore.patchDocStatus(detail.workspaceId, detail, detail.status);
+        return;
+      }
+      const active =
+        detail?.workspaceId ??
+        (slug ? replicaStore.getState().workspaceBySlug(slug)?.id : undefined);
+      if (active) void revalidate(active);
+    }
+    function onHead() {
+      const id = slug
+        ? replicaStore.getState().workspaceBySlug(slug)?.id
+        : null;
+      if (id) void revalidate(id);
+    }
+    window.addEventListener("backmatter:tree-changed", onTree);
+    window.addEventListener("backmatter:head-changed", onHead);
+    window.addEventListener("backmatter:workspace-changed", onHead);
+    return () => {
+      window.removeEventListener("backmatter:tree-changed", onTree);
+      window.removeEventListener("backmatter:head-changed", onHead);
+      window.removeEventListener("backmatter:workspace-changed", onHead);
+    };
+  }, [revalidate, slug]);
+
+  const value: ReplicaSession = {
+    user,
+    bootstrapError,
+    retryBootstrap: () => setBootGen((n) => n + 1),
+    ensureWorkspace,
+    applyCheckout,
+    syncCheckout,
+    revalidate,
+  };
+
+  return (
+    <ReplicaSessionContext.Provider value={value}>
+      {children}
+    </ReplicaSessionContext.Provider>
+  );
+}
+
+export function ReplicaGate({ children }: { children: ReactNode }) {
+  const { bootstrapError, retryBootstrap } = useReplicaSession();
+  const state = useReplicaState();
+  if (!state.ready) {
+    return (
+      <BootstrapSplash
+        error={bootstrapError}
+        onRetry={bootstrapError ? retryBootstrap : undefined}
+      />
+    );
+  }
+  return children;
+}

package/src/replica/cache.ts

@@ -0,0 +1,30 @@
+// packages/studio/src/replica/cache.ts
+import type { ReplicaBranchSlot } from "./types";
+
+export type ReplicaCache = {
+  branch: string;
+  headSha: string | null;
+  schemaVersion?: number;
+};
+
+export function replicaCacheFromSlot(
+  branch: string | null,
+  slot: ReplicaBranchSlot | null,
+): ReplicaCache | undefined {
+  if (!branch || !slot) return undefined;
+  return {
+    branch,
+    headSha: slot.headSha,
+    ...(slot.schema ? { schemaVersion: slot.schema.version } : {}),
+  };
+}
+
+export function replicaQuery(cache: ReplicaCache): string {
+  const params = new URLSearchParams();
+  params.set("branch", cache.branch);
+  params.set("head", cache.headSha ?? "");
+  if (cache.schemaVersion !== undefined) {
+    params.set("schema", String(cache.schemaVersion));
+  }
+  return params.toString();
+}

package/src/replica/idb.ts

@@ -0,0 +1,89 @@
+// packages/studio/src/replica/idb.ts
+import type { ReplicaPersistence, ReplicaRecord } from "./types";
+
+const DB_NAME = "backmatter-replica";
+const STORE = "records";
+
+function memoryPersistence(): ReplicaPersistence {
+  const data = new Map<string, ReplicaRecord>();
+  return {
+    async load(userId) {
+      return data.get(userId) ?? null;
+    },
+    async save(record) {
+      data.set(record.userId, record);
+    },
+    async clear() {
+      data.clear();
+    },
+  };
+}
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, 1);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE)) {
+        db.createObjectStore(STORE);
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("idb_open_failed"));
+  });
+}
+
+export function createIdbPersistence(): ReplicaPersistence {
+  if (typeof indexedDB === "undefined") return memoryPersistence();
+
+  const fallback = memoryPersistence();
+  let broken = false;
+
+  async function withStore<T>(
+    mode: IDBTransactionMode,
+    fn: (store: IDBObjectStore) => IDBRequest<T> | void,
+  ): Promise<T | undefined> {
+    const db = await openDb();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE, mode);
+      const store = tx.objectStore(STORE);
+      const req = fn(store);
+      tx.oncomplete = () => resolve(req ? req.result : undefined);
+      tx.onerror = () => reject(tx.error ?? new Error("idb_tx_failed"));
+      if (req) {
+        req.onerror = () => reject(req.error ?? new Error("idb_req_failed"));
+      }
+    });
+  }
+
+  return {
+    async load(userId) {
+      if (broken) return fallback.load(userId);
+      try {
+        const value = await withStore("readonly", (store) => store.get(userId));
+        return (value as ReplicaRecord | undefined) ?? null;
+      } catch {
+        broken = true;
+        return fallback.load(userId);
+      }
+    },
+    async save(record) {
+      if (broken) return fallback.save(record);
+      try {
+        await withStore("readwrite", (store) => store.put(record, record.userId));
+      } catch {
+        broken = true;
+        await fallback.save(record);
+      }
+    },
+    async clear() {
+      if (broken) return fallback.clear();
+      try {
+        await withStore("readwrite", (store) => store.clear());
+      } catch {
+        broken = true;
+        await fallback.clear();
+      }
+    },
+  };
+}

package/src/replica/instance.ts

@@ -0,0 +1,39 @@
+// packages/studio/src/replica/instance.ts
+import { readLastUser } from "../last-user";
+import { readLastWorkspace } from "../last-workspace";
+import { cmsWorkspaceSlug } from "../workspace-path";
+import { createIdbPersistence } from "./idb";
+import { createReplicaStore } from "./store";
+import { clearSyncReplica, readSyncReplica, writeSyncReplica } from "./sync-cache";
+
+export const replicaStore = createReplicaStore(createIdbPersistence());
+
+function bootActiveHint() {
+  try {
+    const last = readLastUser();
+    if (!last) return { last: null, active: null as string | null };
+    const slug = cmsWorkspaceSlug(window.location.pathname);
+    return { last, active: slug ?? readLastWorkspace(last.id) };
+  } catch {
+    return { last: null, active: null as string | null };
+  }
+}
+
+const boot = bootActiveHint();
+if (boot.last) {
+  const sync = readSyncReplica(boot.last.id);
+  if (sync) replicaStore.seed(sync);
+}
+
+replicaStore.subscribe(() => {
+  const dump = replicaStore.dump();
+  if (!dump) {
+    clearSyncReplica();
+    return;
+  }
+  writeSyncReplica(dump);
+});
+
+export const replicaBoot = boot.last
+  ? replicaStore.hydrate(boot.last.id, boot.active)
+  : Promise.resolve();