@backmatter/studio 0.0.1

package/src/replica/pull.ts

@@ -0,0 +1,23 @@
+// packages/studio/src/replica/pull.ts
+import type { ReplicaCache } from "./cache";
+import type { ReplicaBody, ReplicaStore } from "./types";
+
+export async function pullReplica(input: {
+  workspaceId: string;
+  cache?: ReplicaCache;
+  intendedBranch?: string;
+  fetchReplica: (
+    workspaceId: string,
+    cache?: ReplicaCache,
+  ) => Promise<ReplicaBody>;
+  store: Pick<ReplicaStore, "applyHit" | "applySnapshot">;
+}): Promise<boolean> {
+  const body = await input.fetchReplica(input.workspaceId, input.cache);
+  if (body.kind === "hit") {
+    if (input.store.applyHit(body)) return true;
+    const full = await input.fetchReplica(input.workspaceId);
+    if (full.kind === "hit") return input.store.applyHit(full);
+    return input.store.applySnapshot(full, input.intendedBranch);
+  }
+  return input.store.applySnapshot(body, input.intendedBranch);
+}

package/src/replica/store.ts

@@ -0,0 +1,497 @@
+// packages/studio/src/replica/store.ts
+import type { ChangeStatus, DocListItem, DocStatus, GitState } from "../api";
+import type { SyncReplica } from "./sync-cache";
+import type {
+  DocRef,
+  ReplicaControl,
+  ReplicaGitCache,
+  ReplicaPersistence,
+  ReplicaHit,
+  ReplicaRecord,
+  ReplicaSnapshot,
+  ReplicaStateView,
+  ReplicaStore,
+} from "./types";
+
+function docKey(ref: DocRef) {
+  return `${ref.locale}/${ref.type}/${ref.slug}`;
+}
+
+const OVERLAY_STATUSES = new Set(["modified", "added", "conflict", "deleted"]);
+
+function validOverlay(row: ReplicaHit["overlay"][number]) {
+  return Boolean(
+    row.locale &&
+      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,
+    }));
+}
+
+function withBranch(
+  git: ReplicaGitCache | undefined,
+  branch: string,
+  defaultBranch: string,
+): ReplicaGitCache {
+  const branches = git?.branches ?? [];
+  const has = branches.some((item) => item.name === branch);
+  return {
+    defaultBranch: git?.defaultBranch ?? defaultBranch,
+    branches: has ? branches : [...branches, { name: branch }],
+    head: git?.head ?? null,
+  };
+}
+
+function memoryPersistence(): ReplicaPersistence {
+  let record: ReplicaRecord | null = null;
+  return {
+    async load() {
+      return record;
+    },
+    async save(next) {
+      record = next;
+    },
+    async clear() {
+      record = null;
+    },
+  };
+}
+
+export function createReplicaStore(
+  persistence: ReplicaPersistence = memoryPersistence(),
+): ReplicaStore {
+  let sessionUserId: string | null = null;
+  let control: ReplicaControl | null = null;
+  let checkouts: ReplicaRecord["checkouts"] = {};
+  let activeWorkspaceId: string | null = null;
+  let refreshError: string | null = null;
+  let revision = 0;
+  const listeners = new Set<() => void>();
+
+  function emit() {
+    revision += 1;
+    for (const listener of listeners) listener();
+  }
+
+  function persist() {
+    if (!sessionUserId || !control) return;
+    void persistence
+      .save({ userId: sessionUserId, control, checkouts })
+      .catch(() => {
+        // memory-only if IDB fails after hydrate
+      });
+  }
+
+  function isReady() {
+    if (!control) return false;
+    if (!activeWorkspaceId) return true;
+    const entry = checkouts[activeWorkspaceId];
+    if (!entry) return false;
+    return Boolean(entry.branches[entry.currentBranch]);
+  }
+
+  function resolveWorkspaceId(idOrSlug: string) {
+    if (checkouts[idOrSlug]) return idOrSlug;
+    for (const entry of Object.values(checkouts)) {
+      if (entry.workspace.slug === idOrSlug) return entry.workspace.id;
+    }
+    const summary = control?.workspaces.find(
+      (workspace) => workspace.id === idOrSlug || workspace.slug === idOrSlug,
+    );
+    return summary?.id ?? idOrSlug;
+  }
+
+  function currentSlot(workspaceId: string) {
+    const entry = checkouts[workspaceId];
+    if (!entry) return null;
+    return entry.branches[entry.currentBranch] ?? null;
+  }
+
+  const view: ReplicaStateView = {
+    get sessionUserId() {
+      return sessionUserId;
+    },
+    get control() {
+      return control;
+    },
+    get ready() {
+      return isReady();
+    },
+    get refreshError() {
+      return refreshError;
+    },
+    checkout(workspaceId) {
+      return currentSlot(resolveWorkspaceId(workspaceId));
+    },
+    currentBranch(workspaceId) {
+      return checkouts[resolveWorkspaceId(workspaceId)]?.currentBranch ?? null;
+    },
+    workspace(workspaceId) {
+      return checkouts[resolveWorkspaceId(workspaceId)]?.workspace ?? null;
+    },
+    workspaceBySlug(slug) {
+      for (const entry of Object.values(checkouts)) {
+        if (entry.workspace.slug === slug) return entry.workspace;
+      }
+      const summary = control?.workspaces.find((w) => w.slug === slug);
+      if (!summary) return null;
+      return checkouts[summary.id]?.workspace ?? null;
+    },
+    docs(workspaceId) {
+      return currentSlot(resolveWorkspaceId(workspaceId))?.docs ?? [];
+    },
+    git(idOrSlug) {
+      const workspaceId = resolveWorkspaceId(idOrSlug);
+      const entry = checkouts[workspaceId];
+      if (!entry) return null;
+      const slot = entry.branches[entry.currentBranch];
+      const cached = withBranch(
+        entry.git,
+        entry.currentBranch,
+        entry.workspace.githubDefaultBranch ?? entry.currentBranch,
+      );
+      return {
+        defaultBranch: cached.defaultBranch,
+        currentBranch: entry.currentBranch,
+        branches: cached.branches.length
+          ? cached.branches
+          : [{ name: entry.currentBranch }],
+        head:
+          cached.head ??
+          (slot?.headSha ? { sha: slot.headSha, updatedAt: "" } : null),
+        changes: changesFromDocs(slot?.docs ?? []),
+      };
+    },
+  };
+
+  return {
+    async hydrate(userId, activeWorkspace) {
+      sessionUserId = userId;
+      let record: ReplicaRecord | null = null;
+      try {
+        record = await persistence.load(userId);
+      } catch {
+        record = null;
+      }
+      if (record && record.userId !== userId) {
+        await persistence.clear().catch(() => undefined);
+        record = null;
+      }
+      if (!record) {
+        if (!control) {
+          checkouts = {};
+          activeWorkspaceId = activeWorkspace ?? null;
+        } else if (activeWorkspace) {
+          activeWorkspaceId = resolveWorkspaceId(activeWorkspace);
+        }
+        refreshError = null;
+        emit();
+        return;
+      }
+      control = record.control;
+      checkouts = record.checkouts;
+      refreshError = null;
+      if (activeWorkspace) {
+        activeWorkspaceId = resolveWorkspaceId(activeWorkspace);
+      }
+      emit();
+    },
+
+    seed(record: SyncReplica) {
+      sessionUserId = record.userId;
+      control = record.control;
+      checkouts = record.checkouts;
+      activeWorkspaceId = record.activeWorkspaceId
+        ? resolveWorkspaceId(record.activeWorkspaceId)
+        : null;
+      refreshError = null;
+      emit();
+    },
+
+    dump() {
+      if (!sessionUserId || !control) return null;
+      return {
+        userId: sessionUserId,
+        control,
+        checkouts,
+        activeWorkspaceId,
+      };
+    },
+
+    applyControl(next) {
+      control = next;
+      refreshError = null;
+      persist();
+      emit();
+    },
+
+    applySnapshot(snapshot, intendedBranch) {
+      if (intendedBranch && snapshot.checkout.branch !== intendedBranch) {
+        return false;
+      }
+      control = {
+        user: snapshot.user,
+        workspaces: snapshot.workspaces,
+      };
+      const existing = checkouts[snapshot.workspace.id];
+      const defaultBranch =
+        snapshot.workspace.githubDefaultBranch ?? snapshot.checkout.branch;
+      checkouts = {
+        ...checkouts,
+        [snapshot.workspace.id]: {
+          workspace: snapshot.workspace,
+          currentBranch: snapshot.checkout.branch,
+          git: {
+            ...withBranch(existing?.git, snapshot.checkout.branch, defaultBranch),
+            head: snapshot.checkout.headSha
+              ? {
+                  sha: snapshot.checkout.headSha,
+                  updatedAt:
+                    existing?.git?.head?.sha === snapshot.checkout.headSha
+                      ? existing.git.head.updatedAt
+                      : "",
+                }
+              : null,
+          },
+          branches: {
+            ...(existing?.branches ?? {}),
+            [snapshot.checkout.branch]: {
+              headSha: snapshot.checkout.headSha,
+              schema: snapshot.schema,
+              docs: snapshot.docs,
+            },
+          },
+        },
+      };
+      refreshError = null;
+      persist();
+      emit();
+      return true;
+    },
+
+    applyHit(hit: ReplicaHit) {
+      const id = hit.workspace.id;
+      const existing = checkouts[id];
+      const slot = existing?.branches[existing.currentBranch];
+      if (!existing || !slot) return false;
+      if (
+        existing.currentBranch !== hit.checkout.branch ||
+        slot.headSha !== hit.checkout.headSha
+      ) {
+        return false;
+      }
+
+      let skipped = false;
+      const pending = new Map<string, ReplicaHit["overlay"][number]>();
+      for (const row of hit.overlay) {
+        if (!validOverlay(row)) {
+          skipped = true;
+          continue;
+        }
+        pending.set(docKey(row), row);
+      }
+      const docs: DocListItem[] = [];
+      for (const doc of slot.docs) {
+        const over = pending.get(docKey(doc));
+        if (over) {
+          pending.delete(docKey(doc));
+          if (over.status === "deleted") continue;
+          docs.push({
+            locale: over.locale,
+            type: over.type,
+            slug: over.slug,
+            status: over.status,
+          });
+          continue;
+        }
+        if (doc.status === "added") continue;
+        if (doc.status === "modified" || doc.status === "conflict") {
+          docs.push({ ...doc, status: "clean" });
+          continue;
+        }
+        docs.push(doc);
+      }
+      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,
+        });
+      }
+
+      control = {
+        user: hit.user,
+        workspaces: hit.workspaces,
+      };
+      checkouts = {
+        ...checkouts,
+        [id]: {
+          ...existing,
+          workspace: hit.workspace,
+          branches: {
+            ...existing.branches,
+            [existing.currentBranch]: {
+              ...slot,
+              schema: hit.schema !== undefined ? hit.schema : slot.schema,
+              docs,
+            },
+          },
+        },
+      };
+      refreshError = skipped ? "Couldn't apply some overlay rows" : null;
+      persist();
+      emit();
+      return true;
+    },
+
+    updateWorkspace(workspace) {
+      const existing = checkouts[workspace.id];
+      if (!existing) return;
+      checkouts = {
+        ...checkouts,
+        [workspace.id]: { ...existing, workspace },
+      };
+      persist();
+      emit();
+    },
+
+    setActiveWorkspace(workspaceId) {
+      activeWorkspaceId = workspaceId ? resolveWorkspaceId(workspaceId) : null;
+      emit();
+    },
+
+    setCheckout(workspaceId, branch) {
+      const id = resolveWorkspaceId(workspaceId);
+      const existing = checkouts[id];
+      if (!existing) return "miss";
+      const defaultBranch =
+        existing.git?.defaultBranch ??
+        existing.workspace.githubDefaultBranch ??
+        branch;
+      checkouts = {
+        ...checkouts,
+        [id]: {
+          ...existing,
+          currentBranch: branch,
+          git: withBranch(existing.git, branch, defaultBranch),
+        },
+      };
+      persist();
+      emit();
+      return existing.branches[branch] ? "ready" : "miss";
+    },
+
+    setGit(workspaceId, git: GitState) {
+      const id = resolveWorkspaceId(workspaceId);
+      const existing = checkouts[id];
+      if (!existing) return;
+      const currentBranch = git.currentBranch || existing.currentBranch;
+      checkouts = {
+        ...checkouts,
+        [id]: {
+          ...existing,
+          currentBranch,
+          git: {
+            defaultBranch: git.defaultBranch,
+            branches: git.branches,
+            head: git.head,
+          },
+        },
+      };
+      persist();
+      emit();
+    },
+
+    removeDoc(workspaceId, ref) {
+      const id = resolveWorkspaceId(workspaceId);
+      const entry = checkouts[id];
+      const slot = entry ? entry.branches[entry.currentBranch] : null;
+      if (!entry || !slot) return;
+      const key = docKey(ref);
+      const docs = slot.docs.filter((doc) => docKey(doc) !== key);
+      if (docs.length === slot.docs.length) return;
+      checkouts = {
+        ...checkouts,
+        [id]: {
+          ...entry,
+          branches: {
+            ...entry.branches,
+            [entry.currentBranch]: { ...slot, docs },
+          },
+        },
+      };
+      persist();
+      emit();
+    },
+
+    patchDocStatus(workspaceId, ref, status: DocStatus) {
+      const id = resolveWorkspaceId(workspaceId);
+      const entry = checkouts[id];
+      const slot = entry ? entry.branches[entry.currentBranch] : null;
+      if (!entry || !slot) return;
+      const key = docKey(ref);
+      const docs = slot.docs.slice();
+      const index = docs.findIndex((doc) => docKey(doc) === key);
+      if (index >= 0) {
+        docs[index] = { ...docs[index], status };
+      } else {
+        docs.push({ ...ref, status });
+      }
+      checkouts = {
+        ...checkouts,
+        [id]: {
+          ...entry,
+          branches: {
+            ...entry.branches,
+            [entry.currentBranch]: { ...slot, docs },
+          },
+        },
+      };
+      persist();
+      emit();
+    },
+
+    setRefreshError(message) {
+      refreshError = message;
+      emit();
+    },
+
+    async wipe() {
+      sessionUserId = null;
+      control = null;
+      checkouts = {};
+      activeWorkspaceId = null;
+      refreshError = null;
+      await persistence.clear().catch(() => undefined);
+      emit();
+    },
+
+    getState() {
+      return view;
+    },
+
+    getRevision() {
+      return revision;
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}

package/src/replica/sync-cache.ts

@@ -0,0 +1,51 @@
+// packages/studio/src/replica/sync-cache.ts
+import type { KeyValueStore } from "../last-workspace";
+import type { ReplicaRecord } from "./types";
+
+export const SYNC_REPLICA_KEY = "backmatter-replica-sync";
+
+export type SyncReplica = ReplicaRecord & {
+  activeWorkspaceId: string | null;
+};
+
+export function writeSyncReplica(
+  record: SyncReplica,
+  storage: KeyValueStore = localStorage,
+) {
+  try {
+    storage.setItem(SYNC_REPLICA_KEY, JSON.stringify(record));
+  } catch {
+    // ignore quota / private mode
+  }
+}
+
+export function readSyncReplica(
+  userId: string,
+  storage: KeyValueStore = localStorage,
+): SyncReplica | null {
+  if (!userId) return null;
+  try {
+    const raw = storage.getItem(SYNC_REPLICA_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<SyncReplica>;
+    if (!parsed || parsed.userId !== userId || !parsed.control || !parsed.checkouts) {
+      return null;
+    }
+    return {
+      userId: parsed.userId,
+      control: parsed.control,
+      checkouts: parsed.checkouts,
+      activeWorkspaceId: parsed.activeWorkspaceId ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function clearSyncReplica(storage: KeyValueStore = localStorage) {
+  try {
+    storage.removeItem(SYNC_REPLICA_KEY);
+  } catch {
+    // ignore
+  }
+}

package/src/replica/types.ts

@@ -0,0 +1,119 @@
+// packages/studio/src/replica/types.ts
+import type {
+  DocListItem,
+  DocStatus,
+  GitState,
+  SchemaPayload,
+  WorkspaceDetail,
+  WorkspaceSummary,
+} from "../api";
+import type { SyncReplica } from "./sync-cache";
+
+export type ReplicaUser = { id: string; email: string };
+
+export type ReplicaSchema = {
+  id: string;
+  version: number;
+  branch?: string;
+  payload: SchemaPayload;
+} | null;
+
+export type ReplicaSnapshot = {
+  kind?: "full";
+  user: ReplicaUser;
+  workspaces: WorkspaceSummary[];
+  workspace: WorkspaceDetail;
+  checkout: { branch: string; headSha: string | null };
+  schema: ReplicaSchema;
+  docs: DocListItem[];
+};
+
+export type ReplicaOverlayItem = {
+  locale: string;
+  type: string;
+  slug: string;
+  status: Exclude<DocStatus, "clean">;
+};
+
+export type ReplicaHit = {
+  kind: "hit";
+  user: ReplicaUser;
+  workspaces: WorkspaceSummary[];
+  workspace: WorkspaceDetail;
+  checkout: { branch: string; headSha: string | null };
+  schema?: ReplicaSchema;
+  overlay: ReplicaOverlayItem[];
+};
+
+export type ReplicaBody = ReplicaSnapshot | ReplicaHit;
+
+export type ReplicaControl = {
+  user: ReplicaUser;
+  workspaces: WorkspaceSummary[];
+};
+
+export type ReplicaBranchSlot = {
+  headSha: string | null;
+  schema: ReplicaSchema;
+  docs: DocListItem[];
+};
+
+export type ReplicaGitCache = {
+  defaultBranch: string;
+  branches: Array<{ name: string }>;
+  head: { sha: string; updatedAt: string } | null;
+};
+
+export type ReplicaCheckout = {
+  workspace: WorkspaceDetail;
+  currentBranch: string;
+  git?: ReplicaGitCache;
+  branches: Record<string, ReplicaBranchSlot>;
+};
+
+export type ReplicaRecord = {
+  userId: string;
+  control: ReplicaControl;
+  checkouts: Record<string, ReplicaCheckout>;
+};
+
+export type DocRef = { locale: string; type: string; slug: string };
+
+export type ReplicaPersistence = {
+  load(userId: string): Promise<ReplicaRecord | null>;
+  save(record: ReplicaRecord): Promise<void>;
+  clear(): Promise<void>;
+};
+
+export type ReplicaStateView = {
+  sessionUserId: string | null;
+  control: ReplicaControl | null;
+  ready: boolean;
+  refreshError: string | null;
+  checkout(workspaceId: string): ReplicaBranchSlot | null;
+  currentBranch(workspaceId: string): string | null;
+  workspace(workspaceId: string): WorkspaceDetail | null;
+  workspaceBySlug(slug: string): WorkspaceDetail | null;
+  docs(workspaceId: string): DocListItem[];
+  git(workspaceId: string): GitState | null;
+};
+
+export type ReplicaStore = {
+  hydrate(userId: string, activeWorkspace?: string | null): Promise<void>;
+  seed(record: SyncReplica): void;
+  dump(): SyncReplica | null;
+  applyControl(control: ReplicaControl): void;
+  applySnapshot(snapshot: ReplicaSnapshot, intendedBranch?: string): boolean;
+  applyHit(hit: ReplicaHit): boolean;
+  updateWorkspace(workspace: WorkspaceDetail): void;
+  setActiveWorkspace(workspaceId: string | null): void;
+  setCheckout(workspaceId: string, branch: string): "ready" | "miss";
+  setGit(workspaceId: string, git: GitState): void;
+  patchDocStatus(workspaceId: string, ref: DocRef, status: DocStatus): void;
+  removeDoc(workspaceId: string, ref: DocRef): void;
+  setRefreshError(message: string | null): void;
+  wipe(): Promise<void>;
+  getState(): ReplicaStateView;
+  getRevision(): number;
+  subscribe(listener: () => void): () => void;
+};

package/src/replica/useReplica.ts

@@ -0,0 +1,13 @@
+// packages/studio/src/replica/useReplica.ts
+import { useSyncExternalStore } from "react";
+import { replicaStore } from "./instance";
+import type { ReplicaStateView } from "./types";
+
+export function useReplicaState(): ReplicaStateView {
+  useSyncExternalStore(
+    replicaStore.subscribe,
+    replicaStore.getRevision,
+    replicaStore.getRevision,
+  );
+  return replicaStore.getState();
+}