@gogitcms/editor 0.23.0

package/app/src/navigation.tsx

@@ -0,0 +1,321 @@
+import React from "react";
+import {
+  NavigationContainer,
+  useNavigationBuilder,
+  createNavigatorFactory,
+  StackRouter,
+  type LinkingOptions,
+} from "@react-navigation/native";
+
+// React Navigation owns the whole URL tree beneath the mount prefix (BASE below
+// — "/app" under the Go server, "" for a self-hosted build at the root). The
+// workspace id is the first path segment, so the picker at the root can switch
+// between workspaces. Shown here with the server's "/app" mount:
+//
+//   /app                                                  → WorkspacePicker
+//   /app/{ws}                                             → RepoPicker
+//   /app/{ws}/repositories/{repo}                         → Browser (no selection)
+//   /app/{ws}/repositories/{repo}/{collection}            → a content collection
+//   /app/{ws}/repositories/{repo}/{collection}/{path}     → a content document
+//   /app/{ws}/repositories/{repo}/configure/{path}        → a singleton document
+//
+// Two optional segments sit between the repo id and that tree:
+//
+//   .../{repo}/branches/{branchId}/…   → pin a non-default branch
+//   .../{repo}/changes/…               → the Changes surface, same shape below it
+//
+// e.g. /app/{ws}/repositories/{repo}/branches/{b}/changes/posts/hello.md
+//
+// Both are omitted in their default case (the default branch, the Edit
+// surface), so every URL that worked before this existed still resolves to
+// exactly the same screen.
+//
+// The server serves index.html for any depth under /app and ignores path
+// segments past the repo id, so deep links reload correctly with no Go change.
+// A self-hosted deployment must do the same for its own mount: serve index.html
+// for unknown paths beneath it, or reloads of a deep link will 404.
+// A pinned config.workspaceId (embedded dashboard/desktop) is handled at the
+// WorkspacePicker screen, which redirects straight into that workspace.
+
+// Which surface of the editor is showing. "edit" is the document editor;
+// "changes" is the read-only comparison of this branch against the repository's
+// default branch. They share the collection/path tree beneath them, so a
+// document has an address on both.
+// "changeRequest" is the summary page for an escalated merge, addressed as
+// `changes/[to/{id}/]request` — the changes surface with a `request` marker.
+export type Surface = "edit" | "changes" | "changeRequest";
+
+export type BrowserParams = {
+  workspaceId: string;
+  repositoryId: string;
+  // The branch, serialized as an optional `branches/{id}` segment. It is omitted
+  // from the URL when it is the repository's default branch (resolved by the
+  // Browser screen), which keeps pre-existing links byte-identical while still
+  // letting a chosen branch survive a reload — without which the Changes surface
+  // would silently snap back to a branch that has no changes.
+  branchId?: string;
+  // The repository's default branch id, carried in navigation state only (never
+  // serialized). It is what lets buildBrowser omit the branch segment for the
+  // default branch; navigating without it just means the segment is written.
+  defaultBranchId?: string;
+  // The project, serialized as an optional `projects/{name}` segment BEFORE the
+  // branch — which project you are editing is a coarser choice than which
+  // branch of it. Undefined means "the repository's only project", which is
+  // every repository without a manifest, so every URL that resolved before
+  // projects existed still resolves to exactly the same screen.
+  projectName?: string;
+  // The name of the sole project when the repository has exactly one, carried in
+  // navigation state only (never serialized). It is what lets buildBrowser omit
+  // the project segment in the single-project case, mirroring defaultBranchId.
+  soleProjectName?: string;
+  surface: Surface;
+  // The comparison target on the changes surface, serialized as an optional
+  // `to/{id}` segment after `changes`. Omitted when it is the default branch, so
+  // the common "review against main" case keeps a clean URL and existing
+  // change links (which had no target segment) still resolve to source-vs-default.
+  targetBranchId?: string;
+  // A plugin screen (docs/plugin-system.md), addressed as
+  // `plugins/{pluginId}/{path}` where the collection tree would otherwise be.
+  // `id` is the plugin's package name; `path` the subpath its routes match.
+  plugin?: { id: string; path: string };
+  // true → a singleton ("Configure") document, addressed only by its file path.
+  configure: boolean;
+  // the content collection name (empty for the configure section or the repo root).
+  collection: string;
+  // the selected document's file path (empty when only a collection is open).
+  itemPath: string;
+  // true → the "new document" form for `collection` (URL .../{collection}/new).
+  create: boolean;
+};
+
+export type RootParamList = {
+  WorkspacePicker: undefined;
+  RepoPicker: { workspaceId: string };
+  Browser: BrowserParams;
+};
+
+// The CMS-view portion of BrowserParams (everything except which repo/branch),
+// used by selection handlers that keep the current repo fixed.
+export type CmsSelection = Pick<BrowserParams, "surface" | "plugin" | "configure" | "collection" | "itemPath" | "create">;
+export const EMPTY_SELECTION: CmsSelection = {
+  surface: "edit",
+  plugin: undefined,
+  configure: false,
+  collection: "",
+  itemPath: "",
+  create: false,
+};
+
+// --- URL <-> state ----------------------------------------------------------
+
+// A file path keeps its slashes but each segment is percent-encoded so paths
+// with spaces or reserved characters round-trip through the URL.
+const encPath = (p: string) => p.split("/").map(encodeURIComponent).join("/");
+const decPath = (p: string) => p.split("/").map(decodeURIComponent).join("/");
+
+// The SPA mount prefix, taken from the path the bundle was actually built for
+// (Vite's `base`): "/app/" for the copy the Go server embeds, "/" for a
+// self-hosted build from `gogitcms-editor build`, or any subpath a self-hoster
+// chooses. Hardcoding "/app" here used to make a root-mounted instance rewrite
+// its own URL to /app/{ws}/… — a path that doesn't exist on that host, so every
+// reload, refresh and bookmark 404'd. The workspace id is NOT part of this
+// prefix; it is the first routed segment beneath it.
+const rawBase: string =
+  (typeof import.meta !== "undefined" && (import.meta as any).env?.BASE_URL) || "/";
+// Normalized to no trailing slash, so the root mount is "" and path building
+// stays a plain concatenation.
+const BASE = rawBase.replace(/\/+$/, "");
+const stripBase = (p: string): string => {
+  const clean = p.split("?")[0].split("#")[0];
+  // Anything outside the mount resolves to the picker root rather than being
+  // mistaken for a workspace id. (With BASE "" every path is inside it.)
+  if (!clean.startsWith(BASE)) return "/";
+  return clean.slice(BASE.length) || "/";
+};
+
+// Parse the repositories-and-below part of a workspace path (the segments after
+// the workspace id). Returns null when the workspace root is being addressed.
+//
+// Exported as the seam navigation.test.mjs drives: the URL grammar is the one
+// piece of this file with no runtime to catch a mistake — a wrong segment order
+// or a missed omission rule shows up as a broken deep link, in production, on
+// somebody's bookmark.
+export function parseBrowser(workspaceId: string, rest: string[]): BrowserParams | null {
+  if (rest[0] !== "repositories" || rest.length < 2) return null;
+  const repositoryId = decodeURIComponent(rest[1]);
+  let tail = rest.slice(2);
+
+  // Optional `projects/{name}` prefix, ahead of the branch: a project is a
+  // coarser choice than a branch of it, and reading the URL left to right should
+  // narrow. Absent → the Browser screen resolves the repository's only project.
+  let projectName: string | undefined;
+  if (tail[0] === "projects" && tail.length >= 2) {
+    projectName = decodeURIComponent(tail[1]);
+    tail = tail.slice(2);
+  }
+
+  // Optional `branches/{id}` prefix. Absent → the Browser screen resolves the
+  // repository's default branch, which is the pre-existing behavior.
+  let branchId: string | undefined;
+  if (tail[0] === "branches" && tail.length >= 2) {
+    branchId = decodeURIComponent(tail[1]);
+    tail = tail.slice(2);
+  }
+
+  // Optional `changes` marker, then an optional `to/{id}` target. Everything
+  // below is the same collection/path tree as the editor, so a document keeps
+  // one address shape on both surfaces.
+  let surface: Surface = "edit";
+  let targetBranchId: string | undefined;
+  if (tail[0] === "changes") {
+    surface = "changes";
+    tail = tail.slice(1);
+    if (tail[0] === "to" && tail.length >= 2) {
+      targetBranchId = decodeURIComponent(tail[1]);
+      tail = tail.slice(2);
+    }
+    // A trailing `request` marker addresses the change-request summary page.
+    if (tail[0] === "request") {
+      surface = "changeRequest";
+      tail = tail.slice(1);
+    }
+  }
+
+  const base = { workspaceId, repositoryId, projectName, branchId, surface, targetBranchId };
+  if (tail.length === 0) return { ...base, configure: false, collection: "", itemPath: "", create: false };
+  // A plugin screen: `plugins/{pluginId}[/{subpath...}]`. The id is one
+  // percent-encoded segment (package names contain "/", e.g. @acme/analytics);
+  // the rest is the path the plugin's own routes match.
+  if (tail[0] === "plugins" && tail.length >= 2) {
+    return {
+      ...base,
+      plugin: {
+        id: decodeURIComponent(tail[1]),
+        path: tail.length > 2 ? decPath(tail.slice(2).join("/")) : "",
+      },
+      configure: false, collection: "", itemPath: "", create: false,
+    };
+  }
+  if (tail[0] === "configure") {
+    return { ...base, configure: true, collection: "", itemPath: tail.length > 1 ? decPath(tail.slice(1).join("/")) : "", create: false };
+  }
+  const collection = decodeURIComponent(tail[0]);
+  // ".../{collection}/new" opens the create form for that collection.
+  if (tail.length === 2 && tail[1] === "new") {
+    return { ...base, configure: false, collection, itemPath: "", create: true };
+  }
+  return {
+    ...base,
+    configure: false,
+    collection,
+    itemPath: tail.length > 1 ? decPath(tail.slice(1).join("/")) : "",
+    create: false,
+  };
+}
+
+function buildBrowser(p: BrowserParams): string {
+  let path = `/${encodeURIComponent(p.workspaceId)}/repositories/${encodeURIComponent(p.repositoryId)}`;
+  // The project segment is written only when the repository has more than one —
+  // `soleProjectName` is set by the Browser screen once projects load. An empty
+  // name is never written: it belongs to the implicit project of a repository
+  // with no manifest, and `projects/` addresses nothing.
+  if (p.projectName && p.projectName !== p.soleProjectName) {
+    path += `/projects/${encodeURIComponent(p.projectName)}`;
+  }
+  // Only a non-default branch is written. `defaultBranchId` is set by the
+  // Browser screen once repositories load; until then nothing is emitted, so a
+  // URL never briefly names the default branch and then drops it.
+  if (p.branchId && p.branchId !== p.defaultBranchId) {
+    path += `/branches/${encodeURIComponent(p.branchId)}`;
+  }
+  if (p.surface === "changes" || p.surface === "changeRequest") {
+    path += "/changes";
+    // The target segment is written only for a non-default target, mirroring the
+    // branch segment: "review against main" stays a clean URL, and a change link
+    // that predates targets (no `to/…`) still means source-vs-default.
+    if (p.targetBranchId && p.targetBranchId !== p.defaultBranchId) {
+      path += `/to/${encodeURIComponent(p.targetBranchId)}`;
+    }
+    if (p.surface === "changeRequest") path += "/request";
+  }
+  if (p.plugin) {
+    path += `/plugins/${encodeURIComponent(p.plugin.id)}`;
+    if (p.plugin.path) path += `/${encPath(p.plugin.path)}`;
+  } else if (p.configure) path += p.itemPath ? `/configure/${encPath(p.itemPath)}` : "/configure";
+  else if (p.collection) {
+    path += `/${encodeURIComponent(p.collection)}`;
+    if (p.create) path += "/new";
+    else if (p.itemPath) path += `/${encPath(p.itemPath)}`;
+  }
+  return path;
+}
+
+// browserUrl builds the absolute, shareable URL for a Browser route (origin +
+// mount base + path) — used to hand a developer a link to the change-request
+// summary page from the "change request already open" prompt.
+export function browserUrl(p: BrowserParams): string {
+  const origin = typeof window !== "undefined" && window.location ? window.location.origin : "";
+  return `${origin}${BASE}${buildBrowser(p)}`;
+}
+
+// getStateFromPath/getPathFromState fully own the mapping so slash-containing
+// file paths stay clean in the URL. A resolved Browser route sits atop a
+// RepoPicker route so browser Back returns to the repository list.
+const linking: LinkingOptions<RootParamList> = {
+  prefixes: [],
+  getStateFromPath: (path) => {
+    const segs = stripBase(path).split("/").filter(Boolean);
+    if (segs.length === 0) return { routes: [{ name: "WorkspacePicker" }] };
+    const workspaceId = decodeURIComponent(segs[0]);
+    const browser = parseBrowser(workspaceId, segs.slice(1));
+    return browser
+      ? { routes: [{ name: "RepoPicker", params: { workspaceId } }, { name: "Browser", params: browser }] }
+      : { routes: [{ name: "RepoPicker", params: { workspaceId } }] };
+  },
+  getPathFromState: (state) => {
+    const route = state.routes[state.index ?? state.routes.length - 1];
+    if (!route) return `${BASE}/`;
+    if (route.name === "Browser") return `${BASE}${buildBrowser(route.params as BrowserParams)}`;
+    if (route.name === "RepoPicker") {
+      return `${BASE}/${encodeURIComponent((route.params as { workspaceId: string }).workspaceId)}`;
+    }
+    return `${BASE}/`;
+  },
+};
+
+// --- minimal navigator ------------------------------------------------------
+// A custom navigator (a documented React Navigation pattern) renders only the
+// focused route. Using it instead of native-stack avoids react-native-screens /
+// gesture-handler — awkward under Vite + react-native-web — while still giving
+// the NavigationContainer + linking (URL sync, back/forward, deep links).
+function BrowserNavigatorImpl({ initialRouteName, children }: any) {
+  const { state, descriptors, NavigationContent } = useNavigationBuilder(StackRouter, {
+    initialRouteName,
+    children,
+  });
+  const focused = state.routes[state.index];
+  return <NavigationContent>{descriptors[focused.key].render()}</NavigationContent>;
+}
+
+// React Navigation 7's createNavigatorFactory takes no type argument — it
+// returns `(config?: any) => any`, and the param list is declared globally
+// instead (below), which is what types useNavigation/useRoute at the call sites.
+export const RootStack = createNavigatorFactory(BrowserNavigatorImpl)();
+
+// The global registration RootParamList feeds: with it, useNavigation() and
+// useRoute() in App.tsx resolve screen names and params without each call site
+// repeating the type argument. Aliased first because the interface below shares
+// the name — referring to RootParamList directly inside the namespace would
+// resolve to the interface itself.
+type AppParamList = RootParamList;
+
+declare global {
+  namespace ReactNavigation {
+    interface RootParamList extends AppParamList {}
+  }
+}
+
+// NavigationRoot wraps the app in the container + linking.
+export function NavigationRoot({ children }: { children: React.ReactNode }) {
+  return <NavigationContainer linking={linking}>{children}</NavigationContainer>;
+}

package/app/src/plugins.ts

@@ -0,0 +1,11 @@
+// The SPA's plugin registry singleton. Populated at boot (main.tsx) from the
+// entries the build generated out of cms.config.js `plugins`; read everywhere
+// a plugin can contribute (field rendering, sidebar, user menu, routes).
+
+import { PluginRegistry } from "@gogitcms/plugin-sdk";
+import { getPreviewToken } from "./previewToken";
+
+// The host capability a preview plugin needs: a credential for a service that
+// trusts the CMS. Injected rather than reached for, so the plugin never touches
+// this tab's access token — see previewToken.ts.
+export const pluginRegistry = new PluginRegistry({ getPreviewToken });

package/app/src/previewHost.tsx

@@ -0,0 +1,263 @@
+// Host wiring for plugin document actions and plugin tabs.
+//
+// The design system knows nothing about plugins: it renders whatever
+// `documentActions` returns into a document's header, and whatever `content` an
+// OpenTab carries into a column. This module is the adapter between those two
+// generic seams and the plugin registry — the toolbar buttons, the draft bus a
+// plugin tab subscribes to, and the tab-state reducer the app drives.
+
+import React, { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
+import { Button, type CmsEntry } from "@gogitcms/design-system";
+import {
+  PluginScreenHost,
+  usePluginRegistry,
+  type PluginDocument,
+  type PluginDocumentActionContext,
+  type PluginRegistry,
+  type PluginTabSpec,
+} from "@gogitcms/plugin-sdk";
+
+/**
+ * A plugin tab in the host's open-tab list.
+ *
+ * It rides in the same list as document tabs so ordering, drag-reorder, close
+ * and the active accent are one implementation — a preview column sits between
+ * two documents exactly as a third document would.
+ */
+export type PluginTabRef = {
+  pluginId: string;
+  /** One of the plugin's registered route paths. */
+  route: string;
+  title: string;
+  params?: Record<string, string>;
+  /** The document the tab was opened from, so its drafts can be routed here. */
+  documentId: string | null;
+};
+
+// --- the draft bus ----------------------------------------------------------
+
+type DraftListener = (doc: PluginDocument) => void;
+
+/**
+ * Fan-out of in-flight document edits, keyed by document id.
+ *
+ * A bus rather than props because the producer (ContentBrowser's onEntryDraft,
+ * one callback for the whole browser) and the consumers (any number of plugin
+ * tabs, mounted and unmounted independently) have no component relationship.
+ * The last draft per document is retained so a tab opened mid-edit renders the
+ * current text rather than waiting for the next keystroke.
+ */
+export class DraftBus {
+  private listeners = new Map<string, Set<DraftListener>>();
+  private last = new Map<string, PluginDocument>();
+
+  publish(doc: PluginDocument): void {
+    this.last.set(doc.id, doc);
+    const set = this.listeners.get(doc.id);
+    if (!set) return;
+    for (const l of set) {
+      try {
+        l(doc);
+      } catch (err) {
+        // A plugin throwing in its draft handler must not break the editor's
+        // typing path, which is what called us.
+        console.error(`[plugins] a draft subscriber threw: ${String(err)}`);
+      }
+    }
+  }
+
+  subscribe(documentId: string, listener: DraftListener): () => void {
+    let set = this.listeners.get(documentId);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(documentId, set);
+    }
+    set.add(listener);
+    const retained = this.last.get(documentId);
+    if (retained) listener(retained);
+    return () => {
+      set!.delete(listener);
+      if (set!.size === 0) this.listeners.delete(documentId);
+    };
+  }
+
+  /** The last draft seen for a document, or null. */
+  peek(documentId: string | null): PluginDocument | null {
+    return documentId ? this.last.get(documentId) ?? null : null;
+  }
+
+  /** Drop retained state for documents that are no longer open. */
+  forget(documentId: string): void {
+    this.last.delete(documentId);
+    this.listeners.delete(documentId);
+  }
+}
+
+// --- toolbar buttons --------------------------------------------------------
+
+export type DocumentActionsProps = {
+  registry: PluginRegistry;
+  document: PluginDocument;
+  /**
+   * Everything the action context needs except the parts this component owns.
+   *
+   * `openTab` is supplied here in a *plugin-scoped* form: the plugin id comes
+   * from the registry record, never from the spec the plugin passed. A plugin
+   * naming another plugin's id would otherwise mount that plugin's route under
+   * its own button.
+   */
+  context: Omit<PluginDocumentActionContext, "document" | "openTab"> & {
+    openTab: (pluginId: string, spec: PluginTabSpec) => void;
+  };
+};
+
+/**
+ * The plugin buttons for one open document.
+ *
+ * Subscribes to the registry so buttons appear as plugin chunks land, rather
+ * than only for documents opened after loading finished.
+ */
+export function PluginDocumentActions({ registry, document, context }: DocumentActionsProps) {
+  usePluginRegistry(registry);
+  const actions = registry.documentActionsFor(document);
+  if (actions.length === 0) return null;
+  return (
+    <>
+      {actions.map((a) => (
+        <Button
+          key={a.key}
+          title={a.label}
+          variant="default"
+          size="sm"
+          iconLeft={a.icon}
+          testID={`doc-action-${a.key}`}
+          // Button defaults to alignSelf: "flex-start", which is right in a
+          // column (a form) and wrong in a row: it overrides the header's
+          // alignItems: "center" and pins the button to the top of the bar.
+          style={{ alignSelf: "center" }}
+          onPress={() => {
+            // A plugin's handler is untrusted code on the click path: a throw
+            // (or a rejected promise) costs its own button, not the editor.
+            void (async () => {
+              try {
+                await a.onSelect({
+                  ...context,
+                  document,
+                  openTab: (spec) => context.openTab(a.pluginId, spec),
+                });
+              } catch (err) {
+                console.error(`[plugin ${a.pluginId}] document action "${a.id}" failed: ${String(err)}`);
+              }
+            })();
+          }}
+        />
+      ))}
+    </>
+  );
+}
+
+/** Build the CmsEntry -> PluginDocument projection the actions and bus speak. */
+export function toPluginDocument(
+  entry: CmsEntry,
+  collection: string,
+  fields: Record<string, unknown>,
+  body: string | null,
+  bodyField?: string,
+): PluginDocument {
+  return {
+    id: entry.id,
+    collection,
+    path: entry.path,
+    fields,
+    body: body ?? undefined,
+    bodyField,
+  };
+}
+
+// --- the tab body -----------------------------------------------------------
+
+export type PluginTabBodyProps = {
+  registry: PluginRegistry;
+  tabId: string;
+  tab: PluginTabRef;
+  bus: DraftBus;
+  /** The document as last loaded, for a tab opened before any edit. */
+  initialDocument: PluginDocument | null;
+  workspaceId: string;
+  repositoryId: string;
+  branchId?: string;
+  gitRef?: string;
+  apiUrl: string;
+  navigate: (to: string) => void;
+  openDocument: (id: string, field?: string) => void;
+  close: () => void;
+};
+
+/** Renders a plugin route inside a column, with its tab context attached. */
+export function PluginTabBody(props: PluginTabBodyProps) {
+  const { bus, tab, initialDocument } = props;
+
+  const onDraft = useCallback(
+    (cb: (doc: PluginDocument) => void) =>
+      tab.documentId ? bus.subscribe(tab.documentId, cb) : () => {},
+    [bus, tab.documentId],
+  );
+
+  // The tab context is memoized on its inputs: it is a prop of the plugin's
+  // component, and a fresh object each render would re-run every effect the
+  // plugin keyed on it — including, for a preview plugin, the iframe's src.
+  const tabContext = useMemo(
+    () => ({
+      id: props.tabId,
+      document: initialDocument,
+      onDraft,
+      openDocument: props.openDocument,
+      close: props.close,
+    }),
+    [props.tabId, initialDocument, onDraft, props.openDocument, props.close],
+  );
+
+  return (
+    <PluginScreenHost
+      registry={props.registry}
+      pluginId={tab.pluginId}
+      path={tab.route}
+      params={tab.params}
+      workspaceId={props.workspaceId}
+      repositoryId={props.repositoryId}
+      branchId={props.branchId}
+      gitRef={props.gitRef}
+      apiUrl={props.apiUrl}
+      navigate={props.navigate}
+      tab={tabContext}
+    />
+  );
+}
+
+/** The id a plugin tab occupies in the open-tab list. */
+export function pluginTabId(pluginId: string, spec: PluginTabSpec): string {
+  return `plugin:${pluginId}:${spec.id}`;
+}
+
+/**
+ * Stable identity for a value that is rebuilt each render.
+ *
+ * Used for the per-document `initialDocument`: it is derived from the loaded
+ * document on every render, and handing a new object to PluginTabBody each time
+ * would defeat the memo above.
+ */
+export function useStable<T>(value: T, equal: (a: T, b: T) => boolean): T {
+  const ref = useRef(value);
+  if (!equal(ref.current, value)) ref.current = value;
+  return ref.current;
+}
+
+/** Subscribe a component to a bus entry (for hosts that want it directly). */
+export function useDraft(bus: DraftBus, documentId: string | null): PluginDocument | null {
+  const subscribe = useCallback(
+    (cb: () => void) => (documentId ? bus.subscribe(documentId, cb) : () => {}),
+    [bus, documentId],
+  );
+  const read = useCallback(() => bus.peek(documentId), [bus, documentId]);
+  return useSyncExternalStore(subscribe, read, read);
+}

package/app/src/previewToken.ts

@@ -0,0 +1,68 @@
+// Preview tokens for plugins.
+//
+// A preview plugin has to authenticate to a service that is not the CMS — the
+// sidecar on a developer's machine, or the hosted preview service — and the
+// obvious credential to hand it is the one already in this tab: the user's
+// access token. That is the wrong answer. Plugin code is third-party by design,
+// and the access token authenticates everything else the CMS can do.
+//
+// So the host mints something narrower on the plugin's behalf: a token naming one
+// repository, good for minutes, refused by every CMS endpoint (the API's
+// auth.ParseAccess rejects its audience). The plugin never sees the access token,
+// and a leaked preview token buys a preview of one repository until it expires.
+
+import { config } from "./config";
+import { getAuthToken } from "./apollo";
+
+type Cached = { token: string; expiresAt: number };
+
+// Cached per repository, because the alternative is a mint on every keystroke:
+// the preview plugin sends a draft as the user types, and each one is a request
+// that needs a credential.
+const cache = new Map<string, Cached>();
+
+// Re-minted this long before expiry, so a draft in flight is never the request
+// that discovers the token has died.
+const RENEW_MARGIN_MS = 60_000;
+
+export async function getPreviewToken(repositoryId: string): Promise<string> {
+  const hit = cache.get(repositoryId);
+  if (hit && hit.expiresAt - RENEW_MARGIN_MS > Date.now()) return hit.token;
+
+  const auth = getAuthToken();
+  if (!auth) throw new Error("not signed in");
+
+  const res = await fetch(`${config.apiUrl}/api/v1/git/repositories/${repositoryId}/preview-token`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${auth}`,
+      // The local server's CSRF barrier, same as apollo.ts sends.
+      ...(config.local ? { "X-GitCms-Local": "1" } : {}),
+    },
+  });
+  if (!res.ok) {
+    // Surfaced to the plugin, which shows it in its own pane. 403 here means the
+    // user cannot read that repository's content, which is worth saying plainly
+    // rather than as "the preview service refused the session".
+    throw new Error(
+      res.status === 403
+        ? "you do not have permission to preview this repository"
+        : `the CMS refused to mint a preview token (${res.status})`,
+    );
+  }
+  const body = (await res.json()) as { token: string; expiresAt: string };
+  const expiresAt = Date.parse(body.expiresAt);
+  cache.set(repositoryId, {
+    token: body.token,
+    // A server whose clock or format surprises us should not produce a token
+    // that is cached forever; an unparseable expiry is treated as "one minute".
+    expiresAt: Number.isFinite(expiresAt) ? expiresAt : Date.now() + 60_000,
+  });
+  return body.token;
+}
+
+// Cleared on sign-out: a token in a module-level map outliving the session is
+// the same mistake as persisting one.
+export function clearPreviewTokens(): void {
+  cache.clear();
+}