@glw907/cairn-cms 0.68.0 → 0.76.0

package/src/lib/github/backend.ts

@@ -0,0 +1,161 @@
+// cairn-cms: the Backend seam. A Backend is read, commit, and branch operations over files,
+// never a query(): that line is the constraint that keeps a store swappable and a database out.
+// The adapter holds a BackendProvider from githubApp(...); the engine resolves one live Backend
+// per request via connect(env), with the GitHub App installation token minted and cached behind
+// the seam. makeGithubBackend takes an injectable token getter so a test wires a literal token and
+// the in-memory fetch double intercepts the same GitHub URLs the production getter would reach.
+import { readRaw, listMarkdown, commitFiles } from './repo.js';
+import type { FileChange } from './repo.js';
+import { branchHeadSha, createBranch as createBranchRef, deleteBranch, listBranches } from './branches.js';
+import { appCredentials } from './credentials.js';
+import type { BackendEnv } from './credentials.js';
+import { cachedInstallationToken } from './signing.js';
+import { CommitConflictError } from './types.js';
+import type { CommitAuthor, RepoFile } from './types.js';
+
+// One BackendEnv declaration lives in credentials.js (the secret-channel owner). Re-export it here so
+// the seam and connect() name the same type the public root surfaces, with no duplicate declaration.
+export type { BackendEnv };
+
+/**
+ * A live, connected content store pinned to a default branch. The GitHub implementation already
+ * holds a minted token behind it; the engine resolves one per request. Read, commit, and branch
+ * over files only: this interface never grows a query() method.
+ */
+export interface Backend {
+  /** The site's default branch, for example "main". Callers reading published state pass it as the ref. */
+  readonly defaultBranch: string;
+
+  /** Raw file contents at a ref, or null when the path does not exist. */
+  readFile(path: string, ref: string): Promise<string | null>;
+
+  /** The markdown entries directly in a concept directory at a ref, newest id first. */
+  readEntries(dir: string, ref: string): Promise<RepoFile[]>;
+
+  /** A branch's head commit sha, or null when the branch does not exist. */
+  branchHead(branch: string): Promise<string | null>;
+
+  /** Branch names under a prefix, sorted. */
+  listBranches(prefix: string): Promise<string[]>;
+
+  /**
+   * Commit a set of path changes atomically on a branch; returns the new commit sha. When
+   * `expectedHead` is given the commit is fail-closed: it makes one attempt and throws
+   * CommitConflictError if the branch head is not `expectedHead`. Omitting it keeps the head-merge
+   * retry the entry and publish paths rely on.
+   */
+  commit(
+    branch: string,
+    changes: FileChange[],
+    author: CommitAuthor,
+    message: string,
+    expectedHead?: string,
+  ): Promise<string>;
+
+  /** Create a branch at another branch's current head. */
+  createBranch(name: string, fromBranch: string): Promise<void>;
+
+  /** Delete a branch; a missing branch is success. */
+  deleteBranch(name: string): Promise<void>;
+}
+
+/** The adapter's backend value: a provider that connect()s to a live Backend given the Worker env. */
+export interface BackendProvider {
+  /** A stable tag for the implementation, for example "github-app". The non-request readers narrow on it. */
+  readonly kind: string;
+  /** The default branch, surfaced before connect() so compose-time code can read it. */
+  readonly branch: string;
+  /** Connect to a live Backend; the GitHub implementation mints and caches its token lazily. */
+  connect(env: BackendEnv): Backend;
+}
+
+/** What githubApp() returns: the generic provider plus the GitHub App's non-secret identity facts. */
+export interface GithubAppProvider extends BackendProvider {
+  readonly kind: 'github-app';
+  readonly owner: string;
+  readonly repo: string;
+  readonly appId: string;
+  readonly installationId: string;
+}
+
+/**
+ * Narrow a provider to the GitHub App provider on its `kind` tag. The non-request readers (the
+ * health self-test, the build-time facts) call this before reading the GitHub-specific identity,
+ * since `BackendProvider.kind` is a bare string the compiler cannot narrow on its own.
+ */
+export function isGithubApp(provider: BackendProvider): provider is GithubAppProvider {
+  return provider.kind === 'github-app';
+}
+
+/** The non-secret GitHub App identity an adapter carries in source; the private key stays a Worker secret. */
+interface GithubAppConfig {
+  owner: string;
+  repo: string;
+  branch: string;
+  appId: string;
+  installationId: string;
+}
+
+/**
+ * The live GitHub Backend over the existing repo.ts and branches.ts transports. The token getter
+ * is injected rather than the env: connect() wires the production getter that mints and caches the
+ * installation token, and a unit test wires a literal so the in-memory fetch double intercepts the
+ * same GitHub URLs. Not barrel-exported; it is the internal test seam imported by path.
+ */
+export function makeGithubBackend(config: GithubAppConfig, getToken: () => string | Promise<string>): Backend {
+  return {
+    defaultBranch: config.branch,
+    async readFile(path, ref) {
+      return readRaw({ ...config, branch: ref }, path, await getToken());
+    },
+    async readEntries(dir, ref) {
+      return listMarkdown({ ...config, branch: ref }, dir, await getToken());
+    },
+    async branchHead(branch) {
+      return branchHeadSha(config, branch, await getToken());
+    },
+    async listBranches(prefix) {
+      return listBranches(config, prefix, await getToken());
+    },
+    async commit(branch, changes, author, message, expectedHead) {
+      return commitFiles({ ...config, branch }, changes, { message, author }, await getToken(), expectedHead);
+    },
+    async createBranch(name, fromBranch) {
+      const tok = await getToken();
+      const head = await branchHeadSha(config, fromBranch, tok);
+      // A null head means the source branch is gone or unreadable. Throw a defined, catchable
+      // error the save path maps to its 500 rather than letting the createBranchRef POST fail raw.
+      if (head === null) throw new CommitConflictError(`${fromBranch} (unreadable source)`);
+      await createBranchRef(config, name, head, tok);
+    },
+    async deleteBranch(name) {
+      await deleteBranch(config, name, await getToken());
+    },
+  };
+}
+
+/**
+ * The default content backend: a GitHub App over a repo branch. Returns a provider carrying the
+ * App's non-secret identity (so the build-time, health, and doctor readers narrow on kind and read
+ * it) whose connect(env) mints and caches the installation token from the Worker's private-key
+ * secret. The missing-secret CairnError stays on first token use, inside connect.
+ */
+export function githubApp(config: {
+  owner: string;
+  repo: string;
+  branch: string;
+  appId: string;
+  installationId: string;
+}): GithubAppProvider {
+  return {
+    kind: 'github-app',
+    branch: config.branch,
+    owner: config.owner,
+    repo: config.repo,
+    appId: config.appId,
+    installationId: config.installationId,
+    connect(env) {
+      return makeGithubBackend(config, () => cachedInstallationToken(appCredentials(config, env)));
+    },
+  };
+}

package/src/lib/github/credentials.ts

@@ -3,22 +3,25 @@
 // save action (Plan 05) stays thin and a misconfigured Worker fails by name, not with a deep
 // TypeError. Mirrors requireDb/requireOrigin in env.ts.
 import { CairnError } from '../diagnostics/index.js';
-import type { BackendConfig } from '../content/types.js';
 import type { AppCredentials } from './types.js';
 
-/** The Worker secret holding the GitHub App private key: base64 of the PEM, single line. */
-export interface GithubKeyEnv {
+/**
+ * The Worker secret carrier `Backend.connect` reads: the GitHub App private key as base64 of the
+ * PEM, single line. A consumer's `App.Platform.env` block names it. Aliased as the engine's
+ * `BackendEnv` since the backend seam owns the secret channel.
+ */
+export interface BackendEnv {
   GITHUB_APP_PRIVATE_KEY_B64?: string;
 }
 
 /**
- * Assemble the `AppCredentials` the signer needs from the adapter's `backend` (app id,
+ * Assemble the `AppCredentials` the signer needs from the GitHub App's identity (app id,
  * installation) and the Worker's private-key secret. Throws a CairnError naming
  * `github.app-unreachable` when the secret is unset, since the App cannot authenticate without it.
  */
 export function appCredentials(
-  backend: Pick<BackendConfig, 'appId' | 'installationId'>,
-  env: GithubKeyEnv,
+  identity: { appId: string; installationId: string },
+  env: BackendEnv,
 ): AppCredentials {
   const privateKeyB64 = env.GITHUB_APP_PRIVATE_KEY_B64;
   if (!privateKeyB64) {
@@ -26,5 +29,5 @@ export function appCredentials(
       message: 'GITHUB_APP_PRIVATE_KEY_B64 is not configured',
     });
   }
-  return { appId: backend.appId, installationId: backend.installationId, privateKeyB64 };
+  return { appId: identity.appId, installationId: identity.installationId, privateKeyB64 };
 }

package/src/lib/github/repo.ts

@@ -86,56 +86,6 @@ export async function readRaw(repo: RepoRef, path: string, token?: string): Prom
   return res.text();
 }
 
-/** Standard (padded) base64 of UTF-8 text, the form the contents API expects. */
-function toBase64(text: string): string {
-  return btoa(Array.from(new TextEncoder().encode(text), (b) => String.fromCharCode(b)).join(''));
-}
-
-/** The current blob sha for a path, or null if the file does not yet exist. */
-export async function fileSha(repo: RepoRef, path: string, token: string): Promise<string | null> {
-  const res = await fetch(contentsUrl(repo, path), { headers: ghHeaders('application/vnd.github+json', token) });
-  if (res.status === 404) return null;
-  if (!res.ok) throw new Error(`GitHub stat ${path} failed: ${res.status}`);
-  return ((await res.json()) as { sha: string }).sha;
-}
-
-/**
- * Commit `content` to `path` on the configured branch through the contents API. The author is
- * the editor; the committer is omitted, so GitHub attributes it to the App (`cairn-cms[bot]`).
- * Updates the file in place when it exists (passing its sha), creates it otherwise. Returns the
- * commit sha. A stale-sha 409 (someone committed in between) becomes a `CommitConflictError`,
- * so the save fails safe: re-fetch and ask the editor to reapply, never a merge.
- *
- * Caller preconditions this layer cannot enforce, and the save action (Plan 05) must:
- * `path` is confined to the concept's configured directory (the App token can write anywhere
- * in the repo, so an unvalidated path could overwrite CI config or source), and `author` is
- * derived from the verified server-side session, never from request input.
- */
-export async function commitFile(
-  repo: RepoRef,
-  path: string,
-  content: string,
-  opts: { message: string; author: CommitAuthor },
-  token: string,
-): Promise<string> {
-  const sha = await fileSha(repo, path, token);
-  const url = `${API}/repos/${repo.owner}/${repo.repo}/contents/${path.replace(/^\/+|\/+$/g, '')}`;
-  const res = await fetch(url, {
-    method: 'PUT',
-    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      message: opts.message,
-      content: toBase64(content),
-      branch: repo.branch,
-      author: opts.author,
-      ...(sha ? { sha } : {}),
-    }),
-  });
-  if (res.status === 409) throw new CommitConflictError(path);
-  if (!res.ok) throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
-  return ((await res.json()) as { commit: { sha: string } }).commit.sha;
-}
-
 /** A path change for an atomic commit: write `content`, or delete the path when `content` is null. */
 export interface FileChange {
   path: string;
@@ -186,6 +136,69 @@ function treeChanges(changes: FileChange[]): TreeChange[] {
 /** Retries after the initial attempt when the branch moves under an atomic commit. */
 const COMMIT_RETRIES = 3;
 
+/**
+ * Build a tree on `parent`'s tree, create the commit, and PATCH the branch ref to it. Returns the
+ * new commit sha, or null when the ref PATCH is a non-fast-forward (the head moved). A tree-create
+ * 422 (an unprocessable delete) becomes a `CommitConflictError`, and any other non-fast-forward
+ * detail is left to the caller to map.
+ */
+async function commitOnTree(
+  repo: RepoRef,
+  parent: string,
+  tree: TreeChange[],
+  opts: { message: string; author: CommitAuthor },
+  token: string,
+): Promise<{ sha: string } | { conflict: true }> {
+  const baseTree = await commitTreeSha(repo, parent, token);
+
+  const treeRes = await fetch(gitUrl(repo, 'trees'), {
+    method: 'POST',
+    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ base_tree: baseTree, tree }),
+  });
+  if (!treeRes.ok) {
+    // A 422 means an entry is unprocessable against the base tree, which a delete of an
+    // already-removed path produces (a concurrent delete or rename got there first). Treat it as
+    // the same non-fast-forward conflict the ref PATCH surfaces, so the caller fails safe with the
+    // reload-and-retry path instead of a raw 500.
+    if (treeRes.status === 422) throw new CommitConflictError(`${repo.branch} (tree create)`);
+    throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
+  }
+  const newTree = ((await treeRes.json()) as { sha: string }).sha;
+
+  const commitRes = await fetch(gitUrl(repo, 'commits'), {
+    method: 'POST',
+    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: opts.message, tree: newTree, parents: [parent], author: opts.author }),
+  });
+  if (!commitRes.ok) throw new Error(`GitHub commit create failed: ${commitRes.status} ${await commitRes.text()}`);
+  const newCommit = ((await commitRes.json()) as { sha: string }).sha;
+
+  const refRes = await fetch(gitUrl(repo, `refs/heads/${encodeURIComponent(repo.branch)}`), {
+    method: 'PATCH',
+    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sha: newCommit, force: false }),
+  });
+  if (refRes.ok) return { sha: newCommit };
+  // A non-fast-forward means the branch moved; the caller decides whether to retry or fail closed.
+  // Any other failure is not a race, so surface it.
+  if (refRes.status !== 422) throw new Error(`GitHub ref update failed: ${refRes.status} ${await refRes.text()}`);
+  return { conflict: true };
+}
+
+/** Fail-closed commit on a known head: a non-fast-forward becomes a `CommitConflictError`. */
+async function commitOnHead(
+  repo: RepoRef,
+  head: string,
+  tree: TreeChange[],
+  opts: { message: string; author: CommitAuthor },
+  token: string,
+): Promise<string> {
+  const result = await commitOnTree(repo, head, tree, opts, token);
+  if ('conflict' in result) throw new CommitConflictError(`${repo.branch} (head moved)`);
+  return result.sha;
+}
+
 /**
  * Commit several path changes in one commit over the Git Data API. The author is the editor; the
  * committer is omitted, so GitHub attributes the commit to the App. Returns the new commit sha.
@@ -197,51 +210,34 @@ const COMMIT_RETRIES = 3;
  *
  * An empty change set is rejected, since it would otherwise push an empty commit that triggers a
  * site redeploy for no content change.
+ *
+ * When `expectedHead` is supplied the commit is fail-closed: it makes a single attempt with no
+ * retry, throws a `CommitConflictError` when the branch head is not `expectedHead` (a concurrent
+ * commit landed), and otherwise commits onto that head. The nav and settings writes, which land on
+ * the default branch and trigger a deploy, pass it so a same-branch race surfaces the editor's
+ * reload-and-reapply prompt rather than a silent last-writer-wins. Omitting it keeps the
+ * head-merge retry the entry and publish paths rely on.
  */
 export async function commitFiles(
   repo: RepoRef,
   changes: FileChange[],
   opts: { message: string; author: CommitAuthor },
   token: string,
+  expectedHead?: string,
 ): Promise<string> {
   if (changes.length === 0) throw new Error('commitFiles: no changes to commit');
   const tree = treeChanges(changes);
+  if (expectedHead !== undefined) {
+    const head = await headCommitSha(repo, token);
+    if (head !== expectedHead) throw new CommitConflictError(`${repo.branch} (head moved)`);
+    return commitOnHead(repo, head, tree, opts, token);
+  }
   for (let attempt = 0; attempt <= COMMIT_RETRIES; attempt++) {
     const parent = await headCommitSha(repo, token);
-    const baseTree = await commitTreeSha(repo, parent, token);
-
-    const treeRes = await fetch(gitUrl(repo, 'trees'), {
-      method: 'POST',
-      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-      body: JSON.stringify({ base_tree: baseTree, tree }),
-    });
-    if (!treeRes.ok) {
-      // A 422 means an entry is unprocessable against the base tree, which a delete of an
-      // already-removed path produces (a concurrent delete or rename got there first). Treat it as
-      // the same non-fast-forward conflict the ref PATCH surfaces, so the caller fails safe with the
-      // reload-and-retry path instead of a raw 500.
-      if (treeRes.status === 422) throw new CommitConflictError(`${repo.branch} (tree create)`);
-      throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
-    }
-    const newTree = ((await treeRes.json()) as { sha: string }).sha;
-
-    const commitRes = await fetch(gitUrl(repo, 'commits'), {
-      method: 'POST',
-      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-      body: JSON.stringify({ message: opts.message, tree: newTree, parents: [parent], author: opts.author }),
-    });
-    if (!commitRes.ok) throw new Error(`GitHub commit create failed: ${commitRes.status} ${await commitRes.text()}`);
-    const newCommit = ((await commitRes.json()) as { sha: string }).sha;
-
-    const refRes = await fetch(gitUrl(repo, `refs/heads/${encodeURIComponent(repo.branch)}`), {
-      method: 'PATCH',
-      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-      body: JSON.stringify({ sha: newCommit, force: false }),
-    });
-    if (refRes.ok) return newCommit;
+    const result = await commitOnTree(repo, parent, tree, opts, token);
     // A non-fast-forward means the branch moved; retry on the new head so a concurrent commit
-    // is preserved. Any other failure is not a race, so surface it.
-    if (refRes.status !== 422) throw new Error(`GitHub ref update failed: ${refRes.status} ${await refRes.text()}`);
+    // is preserved.
+    if ('sha' in result) return result.sha;
   }
   throw new CommitConflictError(`${repo.branch} (atomic commit)`);
 }

package/src/lib/github/types.ts

@@ -1,9 +1,9 @@
-// cairn-cms: the GitHub backend's plain data types and its one typed error. The backend
-// reads repo coordinates from the adapter's `BackendConfig` (spec §8); `RepoRef` is the
-// `{ owner, repo, branch }` subset, so `backend` is assignable wherever a `RepoRef` is
-// wanted with no conversion.
+// cairn-cms: the GitHub backend's plain data types and its one typed error. The GitHub App
+// provider config (`githubApp`'s input) carries these repo coordinates; `RepoRef` is the
+// `{ owner, repo, branch }` subset the read and commit transports take, so the provider config
+// is assignable wherever a `RepoRef` is wanted with no conversion.
 
-/** Repo coordinates pinned to a branch: the structural subset of `BackendConfig` the read and commit paths need. */
+/** Repo coordinates pinned to a branch: the `{ owner, repo, branch }` subset the read and commit paths need. */
 export interface RepoRef {
   owner: string;
   repo: string;

package/src/lib/index.ts

@@ -9,17 +9,10 @@ export { buildMagicLinkMessage, cloudflareSend } from './email.js';
 export type {
   CairnAdapter,
   ConceptConfig,
-  FrontmatterField,
-  TextField,
-  TextareaField,
-  DateField,
-  BooleanField,
-  TagsField,
-  FreeTagsField,
-  ImageField,
+  NamedField,
   ImageValue,
   ValidationResult,
-  BackendConfig,
+  ValidationIssue,
   SenderConfig,
   NavMenuConfig,
   PreviewConfig,
@@ -30,10 +23,11 @@ export type {
   ConceptUrlPolicy,
   CairnExtension,
   CairnRuntime,
+  SiteRender,
   AdminPanel,
   FieldTypeDef,
 } from './content/types.js';
-export { CONCEPT_ROUTING, normalizeConcepts, findConcept } from './content/concepts.js';
+export { normalizeConcepts, findConcept, defineConcept } from './content/concepts.js';
 export { composeRuntime } from './content/compose.js';
 export type { ComposeInput } from './content/compose.js';
 export {
@@ -42,16 +36,30 @@ export {
   serializeMarkdown,
   parseMarkdown,
 } from './content/frontmatter.js';
-export { defineFields } from './content/schema.js';
 export { defineAdapter } from './content/adapter.js';
-export type { ConceptSchema, Infer, InferFields, DefineFieldsOptions, StandardInput, StandardSchemaV1 } from './content/schema.js';
-// The Contract v2 field vocabulary, additive beside `defineFields`. The individual *Field
-// interfaces and the bare `Infer` stay module-local: the old `FrontmatterField` model above
-// already exports those names, and the cutover plan frees them.
+export type { StandardInput, StandardSchemaV1 } from './content/standard-schema.js';
+// The Contract v2 field vocabulary: the one live field system.
 export { fields } from './content/fields.js';
-export type { FieldDescriptor } from './content/fields.js';
+export type {
+  FieldDescriptor,
+  TextField,
+  TextareaField,
+  NumberField,
+  SelectField,
+  MultiselectField,
+  UrlField,
+  EmailField,
+  DateField,
+  DatetimeField,
+  BooleanField,
+  IconField,
+  ImageField,
+  ObjectField,
+  ReferenceField,
+  ArrayField,
+} from './content/fields.js';
 export { fieldset, initialValues } from './content/fieldset.js';
-export type { Fieldset, InferFieldset, FieldsetOptions, BehaviorTable } from './content/fieldset.js';
+export type { Fieldset, InferFieldset, FieldsetOptions, BehaviorTable, FieldBehavior } from './content/fieldset.js';
 export {
   isValidId,
   idFromFilename,
@@ -71,6 +79,7 @@ export {
   parseManifest,
   emptyManifest,
   verifyManifest,
+  verifyReferences,
   diffManifests,
   upsertEntry,
   removeEntry,
@@ -78,14 +87,17 @@ export {
   manifestLinkResolver,
   inboundLinks,
 } from './content/manifest.js';
-export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink } from './content/manifest.js';
+export type { Manifest, ManifestEntry, ManifestDiff, ManifestEntryDiff, LinkTarget, InboundLink, InboundReference } from './content/manifest.js';
+export type { ReferenceEdge } from './content/references.js';
+// The read-model resolution of a reference edge to its target's identity lives at the cross-concept
+// site-resolver layer (a per-concept index cannot reach a different concept's entries). The resolver
+// function ships from the /delivery subpath; this is the type a route reads off the resolved map.
+export type { ResolvedReference } from './delivery/site-resolver.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
-export { defineRegistry, emptyValues } from './render/registry.js';
+export { defineRegistry, defineComponent, emptyValues } from './render/registry.js';
 export type {
   ComponentDef,
   ComponentRegistry,
-  FieldType,
-  AttributeField,
   SlotKind,
   SlotDef,
   ComponentValues,
@@ -107,13 +119,16 @@ export { createRenderer } from './render/pipeline.js';
 export type { RendererOptions } from './render/pipeline.js';
 
 // GitHub read-and-commit backend (Plan 03).
-export type { RepoRef, RepoFile, CommitAuthor, AppCredentials } from './github/types.js';
+export type { RepoFile, CommitAuthor } from './github/types.js';
 export { CommitConflictError } from './github/types.js';
+// The Backend seam (Contract v2 backend phase): the store interface and its default GitHub provider.
+export { githubApp } from './github/backend.js';
+export type { Backend, BackendProvider, GithubAppProvider, BackendEnv } from './github/backend.js';
+export type { FileChange } from './github/repo.js';
 
 // Nav tree and site-config helpers (Plan 06).
 export {
   parseSiteConfig,
-  urlPolicyFrom,
   extractMenu,
   setMenu,
   validateNavTree,

package/src/lib/islands/index.ts

@@ -0,0 +1,84 @@
+// cairn-cms islands (@glw907/cairn-cms/islands): the client runtime that mounts a site's live Svelte
+// components over the static fallbacks the render pipeline emits. cairn is Svelte-only by design, so this
+// mounts with Svelte's own mount()/unmount() directly, with no framework abstraction. A site imports this
+// dynamically, gated on a non-empty registry, so a static site never ships it (zero cost when unused).
+import { mount, unmount, type Component } from 'svelte';
+import type { IslandRegistry } from './types.js';
+
+export type { IslandRegistry } from './types.js';
+
+// The live Svelte instances of the current pass and the observers still waiting to fire, kept module-level
+// so the next pass can tear the previous one down. A layout calls hydrateIslands once per navigation, and
+// the previous mounts must unmount before the next mount over the same DOM.
+let mounted: Record<string, unknown>[] = [];
+let observers: IntersectionObserver[] = [];
+
+// Tear down the previous pass: unmount live instances and disconnect observers that never fired. unmount
+// runs with outro: false so teardown is synchronous and deterministic on navigation; an island declaring an
+// out: transition would otherwise linger and briefly double-render against the next pass's fresh mount.
+function teardown(): void {
+  for (const o of observers) o.disconnect();
+  observers = [];
+  for (const instance of mounted) {
+    try {
+      void unmount(instance, { outro: false });
+    } catch {
+      // a component that throws on teardown must not block the rest
+    }
+  }
+  mounted = [];
+}
+
+// Mount one island over its boundary: parse props (try/catch, a malformed payload leaves the fallback),
+// clear the fallback, mount, and on a mount failure restore the fallback so the reader still sees content.
+// WATCH: props are trusted to equal the directive's declared scalar attributes (serializeIslandProps emits
+// only those). If a directive ever carries an attribute its island does not declare, this forwards it as-is.
+function mountIsland(node: Element, Comp: Component<Record<string, unknown>>): void {
+  let props: Record<string, unknown>;
+  try {
+    props = JSON.parse(node.getAttribute('data-cairn-props') ?? '{}') as Record<string, unknown>;
+  } catch {
+    return;
+  }
+  const fallback = [...node.childNodes];
+  node.replaceChildren();
+  try {
+    mounted.push(mount(Comp, { target: node as HTMLElement, props }));
+  } catch {
+    node.replaceChildren(...fallback);
+  }
+}
+
+// Defer a 'visible' island to first intersection, then mount once and stop observing.
+function observeIsland(node: Element, Comp: Component<Record<string, unknown>>): void {
+  const observer = new IntersectionObserver((entries, self) => {
+    for (const entry of entries) {
+      if (entry.isIntersecting) {
+        self.disconnect();
+        mountIsland(node, Comp);
+      }
+    }
+  });
+  observer.observe(node);
+  observers.push(observer);
+}
+
+/**
+ * Mount each island in `root` (default `document`) over its server-rendered fallback. Call it after each
+ *  client-side navigation, once the new DOM is in place (an `afterNavigate` callback): it tears down the
+ *  previous pass first, so it is idempotent and leak-free. An eager island (`hydrate: true`) mounts at once;
+ *  a `'visible'` island mounts on first intersection. An unknown directive name, a malformed prop payload,
+ *  or a component that throws leaves the static fallback in place, so one bad island never breaks the page.
+ *  Mount-and-replace clears the fallback, so an island whose fallback holds a focusable control should
+ *  restore focus itself; the shipped fallbacks are non-interactive.
+ */
+export function hydrateIslands(islands: IslandRegistry, root: ParentNode = document): void {
+  teardown();
+  for (const node of root.querySelectorAll('[data-cairn-island]')) {
+    const name = node.getAttribute('data-cairn-island');
+    const Comp = name ? islands[name] : undefined;
+    if (!Comp) continue;
+    if (node.getAttribute('data-cairn-hydrate') === 'visible') observeIsland(node, Comp);
+    else mountIsland(node, Comp);
+  }
+}

package/src/lib/islands/types.ts

@@ -0,0 +1,11 @@
+// cairn-cms islands (@glw907/cairn-cms/islands): the type contract shared by the adapter and the client
+// runtime. Kept in its own runtime-free module so the adapter types can import it without pulling
+// Svelte's mount() into the server graph.
+import type { Component } from 'svelte';
+
+/**
+ * A site's island components, keyed by directive name. Each value is the live Svelte component
+ *  {@link hydrateIslands} mounts over the matching `hydrate` directive's static fallback. The props a
+ *  component receives are the directive's declared scalar attributes (see the island boundary contract).
+ */
+export type IslandRegistry = Record<string, Component<Record<string, unknown>>>;

package/src/lib/media/rewrite-plan.ts

@@ -16,11 +16,10 @@
 // injected, so the planner never imports the editor surface. It is internal, exported from no package
 // subpath, so it carries no reference page.
 import type { ConceptDescriptor } from '../content/types.js';
-import type { RepoRef } from '../github/types.js';
+import type { Backend } from '../github/backend.js';
 import type { Manifest } from '../content/manifest.js';
 import { findConcept } from '../content/concepts.js';
 import { filenameFromId } from '../content/ids.js';
-import { readRaw } from '../github/repo.js';
 import { buildUsageIndex } from './usage.js';
 
 /**
@@ -81,8 +80,7 @@ export interface RewritePlan<P = unknown> {
  * editor surface and node-safe; the only IO is the usage index build and the per-entry reads.
  */
 export async function planMediaRewrite<P = unknown>(args: {
-  backend: RepoRef;
-  token: string;
+  backend: Backend;
   concepts: ConceptDescriptor[];
   contentManifest: Manifest;
   hash: string;
@@ -90,7 +88,7 @@ export async function planMediaRewrite<P = unknown>(args: {
 }): Promise<RewritePlan<P>> {
   // Strict so an unverifiable branch read rejects here rather than degrading to an absent reference.
   // Do NOT wrap this: the throw is the fail-closed contract the apply relies on.
-  const index = await buildUsageIndex(args.backend, args.token, args.concepts, args.contentManifest, {
+  const index = await buildUsageIndex(args.backend, args.concepts, args.contentManifest, {
     strict: true,
   });
   const rows = index.get(args.hash) ?? [];
@@ -104,7 +102,7 @@ export async function planMediaRewrite<P = unknown>(args: {
       const concept = findConcept(args.concepts, row.concept);
       if (!concept) return null;
       const path = `${concept.dir}/${filenameFromId(row.id)}`;
-      const markdown = await readRaw(args.backend, path, args.token);
+      const markdown = await args.backend.readFile(path, args.backend.defaultBranch);
       if (markdown === null) return null;
       const result = args.transform(markdown);
       if (result.placements.length === 0) return null;