@jxsuite/studio 2.4.3 → 4.0.0

package/src/files/fs-events.ts

@@ -9,6 +9,7 @@
  */
 
 import { getPlatform } from "../platform";
+import { reloadIgnoreCache, touchesGitignore } from "./gitignore";
 import { invalidateUsages } from "../services/references";
 import { projectState } from "../store";
 import type { DirEntry, FsEvent } from "../types";
@@ -174,6 +175,14 @@ export function startFsSync(ctx: FsSyncContext): () => void {
     // Gone.
     invalidateUsages();
     ctx.invalidateDerivedCaches?.();
+    /* A `.gitignore` governs the whole tree beneath it, so it is handled HERE rather than in the
+       batch below: the echo filter drops the events Studio caused, and an author who just edited
+       their own `.gitignore` in Studio is precisely the one waiting to see the tree change. It also
+       never reaches `applyFsEvents` — a dotfile is in no listing, so no directory reads as changed
+       and no repaint would follow. Hence the explicit one, once the rules are back. */
+    if (touchesGitignore(events.map((event) => event.path))) {
+      void reloadIgnoreCache().then(() => ctx.renderLeftPanel());
+    }
     pending.push(...events);
     if (timer) {
       clearTimeout(timer);

package/src/files/gitignore.ts

@@ -0,0 +1,432 @@
+/**
+ * Gitignore matching for the Files sidebar.
+ *
+ * A project root is a working directory, and a working directory holds two populations: the files
+ * the author writes, and the files a tool wrote for them — `node_modules`, `dist`, `coverage`,
+ * `.next`. The sidebar listed both, so a project of forty documents opened as a tree of forty
+ * thousand rows. The author already told us which is which, in the one file every project of this
+ * shape carries: `.gitignore`.
+ *
+ * **This lives in Studio, not behind the PAL, on purpose.** `listDirectory` has three
+ * implementations — the dev server's route, the desktop session's `readdir`, and the cloud backend,
+ * which is not in this repository at all. Filtering there is the same rule written three times, and
+ * a rule written three times is a rule that disagrees with itself; the cloud copy could not even be
+ * changed in the same pull request. Filtering here is written once and is true on every host the
+ * moment it ships. It costs one `readFile` per directory (cached, negatives included), which is the
+ * same round trip the listing itself already makes.
+ *
+ * **The tree cache stays faithful.** {@link isIgnoredEntry} is consulted where rows are BUILT, not
+ * where entries are stored, so `projectState.dirs` keeps mirroring the filesystem and the show/hide
+ * toggle is a repaint rather than a refetch. It also means `applyFsEvents` needs to know nothing
+ * about any of this: a file arriving into an ignored directory lands in the cache and is simply not
+ * drawn.
+ *
+ * The matcher implements `gitignore(5)` — comments, negation, trailing-space and `#`/`!` escapes,
+ * directory-only patterns, anchoring, `**`, character classes, and last-match-wins across layers
+ * ordered shallow-to-deep. What it deliberately does NOT read is `.git/info/exclude` or
+ * `core.excludesFile`: both live outside the project, neither is reachable through the PAL's
+ * project-rooted `readFile`, and a rule the author cannot see in their own repository is a poor
+ * explanation for a missing row.
+ *
+ * @docs studio/interface
+ */
+
+import { getPlatform } from "../platform";
+
+// ─── The rule ─────────────────────────────────────────────────────────────────
+
+/** One `.gitignore` line, compiled. */
+export interface IgnoreRule {
+  /** The line as written. Kept so a hidden row can be explained by the rule that hid it. */
+  source: string;
+  /** `!pattern` — re-includes what an earlier rule excluded. */
+  negated: boolean;
+  /** `pattern/` — matches a directory and never a file. */
+  dirOnly: boolean;
+  /** Matches a path relative to the directory the rule's own `.gitignore` sits in. */
+  re: RegExp;
+}
+
+/** The rules of one `.gitignore`, with the directory they are relative to. */
+export interface IgnoreLayer {
+  /** Project-relative, forward-slashed, no trailing slash; `""` is the project root. */
+  base: string;
+  rules: IgnoreRule[];
+}
+
+// ─── Parsing ──────────────────────────────────────────────────────────────────
+
+/** Characters that mean something to a RegExp and nothing to a glob. */
+const RE_SPECIAL = /[.*+?^${}()|[\]\\]/;
+
+/** One glob character as a RegExp literal. */
+function literal(ch: string): string {
+  return RE_SPECIAL.test(ch) ? `\\${ch}` : ch;
+}
+
+/**
+ * Drop trailing spaces, keeping any the author escaped.
+ *
+ * A space survives when the run of backslashes immediately before it is odd — the same rule that
+ * decides whether the backslash escaped the space or another backslash.
+ */
+function stripTrailingSpaces(line: string): string {
+  let end = line.length;
+  while (end > 0 && line[end - 1] === " ") {
+    let backslashes = 0;
+    let i = end - 2;
+    while (i >= 0 && line[i] === "\\") {
+      backslashes += 1;
+      i -= 1;
+    }
+    if (backslashes % 2 === 1) {
+      break;
+    }
+    end -= 1;
+  }
+  return line.slice(0, end);
+}
+
+/**
+ * The index of the `]` closing the class opened at `start`, or -1 when the line has none.
+ *
+ * A `]` in the first position (after an optional `!`) is a literal member rather than the close,
+ * which is POSIX's rule and git's.
+ */
+function charClassEnd(pattern: string, start: number): number {
+  let i = start + 1;
+  if (pattern[i] === "!") {
+    i += 1;
+  }
+  if (pattern[i] === "]") {
+    i += 1;
+  }
+  while (i < pattern.length) {
+    if (pattern[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (pattern[i] === "]") {
+      return i;
+    }
+    i += 1;
+  }
+  return -1;
+}
+
+/**
+ * Compile a gitignore glob body to a RegExp source.
+ *
+ * `*` and `?` stop at a separator; `**` crosses them, but only where git says it does — as a whole
+ * path segment. `a**b` is git's "two stars that are not a segment", and it behaves as one star.
+ */
+function globToRegExpSource(pattern: string): string {
+  let out = "";
+  let i = 0;
+  while (i < pattern.length) {
+    const ch = pattern[i]!;
+    if (ch === "\\") {
+      const next = pattern[i + 1];
+      if (next === undefined) {
+        // A trailing backslash escapes nothing; match it literally.
+        out += String.raw`\\`;
+        i += 1;
+      } else {
+        out += literal(next);
+        i += 2;
+      }
+      continue;
+    }
+    if (ch === "*") {
+      let stars = 0;
+      while (pattern[i] === "*") {
+        stars += 1;
+        i += 1;
+      }
+      /* `out` ends in `/` only where a separator was just emitted — every compiled form above ends
+         in `*`, `)` or an escaped literal — so this is exactly "at the start of a segment". */
+      const atSegmentStart = out === "" || out.endsWith("/");
+      if (stars >= 2 && atSegmentStart && pattern[i] === "/") {
+        // `**/` — zero or more whole directories.
+        out += "(?:[^/]+/)*";
+        i += 1;
+      } else if (stars >= 2 && atSegmentStart && i >= pattern.length) {
+        // A trailing `/**` — everything inside, at any depth.
+        out += ".*";
+      } else {
+        out += "[^/]*";
+      }
+      continue;
+    }
+    if (ch === "?") {
+      out += "[^/]";
+      i += 1;
+      continue;
+    }
+    if (ch === "[") {
+      const end = charClassEnd(pattern, i);
+      if (end === -1) {
+        out += String.raw`\[`;
+        i += 1;
+        continue;
+      }
+      const raw = pattern.slice(i + 1, end);
+      const negatedClass = raw.startsWith("!");
+      const members = negatedClass ? raw.slice(1) : raw;
+      /* A `]` in the first position is a MEMBER to git and POSIX, and {@link charClassEnd} finds
+         the real close accordingly — but JavaScript reads `[]` as an empty class that matches
+         nothing, and `[^]` as "any character". Emitting the member verbatim therefore inverts the
+         rule instead of translating it, so the leading `]` is escaped on the way out. */
+      out += `[${negatedClass ? "^" : ""}${members.startsWith("]") ? String.raw`\]${members.slice(1)}` : members}]`;
+      i = end + 1;
+      continue;
+    }
+    out += literal(ch);
+    i += 1;
+  }
+  return out;
+}
+
+/** Compile one line, or `null` when it is blank, a comment, or names nothing. */
+function parseLine(raw: string): IgnoreRule | null {
+  let line = stripTrailingSpaces(raw);
+  if (line === "" || line.startsWith("#")) {
+    return null;
+  }
+  let negated = false;
+  if (line.startsWith("!")) {
+    negated = true;
+    line = line.slice(1);
+  }
+  /* `\#` and `\!` reach the compiler with their backslash intact and come out as literals, so the
+     two checks above are the only place the unescaped forms are read. */
+  let dirOnly = false;
+  if (line.endsWith("/")) {
+    dirOnly = true;
+    line = line.slice(0, -1);
+  }
+  /* A slash anywhere but the end anchors the pattern to the `.gitignore`'s own directory; a
+     slash-less pattern matches its name at any depth below it. */
+  let anchored = line.includes("/");
+  if (line.startsWith("/")) {
+    line = line.slice(1);
+    anchored = true;
+  }
+  if (line === "") {
+    return null;
+  }
+  const body = globToRegExpSource(line);
+  return {
+    dirOnly,
+    negated,
+    re: new RegExp(`^${anchored ? "" : "(?:.*/)?"}${body}$`),
+    source: raw,
+  };
+}
+
+/** Compile a `.gitignore`'s text into rules, in file order. */
+export function parseGitignore(text: string): IgnoreRule[] {
+  const rules: IgnoreRule[] = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const rule = parseLine(raw);
+    if (rule) {
+      rules.push(rule);
+    }
+  }
+  return rules;
+}
+
+// ─── Paths ────────────────────────────────────────────────────────────────────
+
+/** Project-relative, forward-slashed, and without the `.`/`./`/trailing-slash spellings of "here". */
+export function normalizePath(path: string): string {
+  const p = path
+    .replaceAll("\\", "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+$/, "");
+  return p === "." ? "" : p;
+}
+
+/** `path` relative to `base`, or `null` when it is not underneath it. */
+function relativeTo(base: string, path: string): string | null {
+  if (base === "") {
+    return path;
+  }
+  return path.startsWith(`${base}/`) ? path.slice(base.length + 1) : null;
+}
+
+/** The project root, then each directory down to `dir`, inclusive. */
+export function ancestorDirs(dir: string): string[] {
+  const base = normalizePath(dir);
+  const chain = [""];
+  if (base === "") {
+    return chain;
+  }
+  let acc = "";
+  for (const segment of base.split("/")) {
+    acc = acc === "" ? segment : `${acc}/${segment}`;
+    chain.push(acc);
+  }
+  return chain;
+}
+
+// ─── Matching ─────────────────────────────────────────────────────────────────
+
+/**
+ * The verdict on one path, judged on its own.
+ *
+ * Last match wins, and later layers are consulted after earlier ones — which is exactly git's two
+ * precedence rules (a later line beats an earlier one; a deeper `.gitignore` beats a shallower one)
+ * expressed as a single ordering.
+ */
+function verdictFor(layers: readonly IgnoreLayer[], path: string, isDir: boolean): boolean {
+  let ignored = false;
+  for (const layer of layers) {
+    const rel = relativeTo(layer.base, path);
+    if (rel === null || rel === "") {
+      continue;
+    }
+    for (const rule of layer.rules) {
+      if (rule.dirOnly && !isDir) {
+        continue;
+      }
+      if (rule.re.test(rel)) {
+        ignored = !rule.negated;
+      }
+    }
+  }
+  return ignored;
+}
+
+/**
+ * Whether `path` is ignored by `layers`, which must be ordered shallow-to-deep.
+ *
+ * Every ancestor directory is judged before the path itself, and the first one that comes back
+ * ignored ends it. That is `gitignore(5)`'s "it is not possible to re-include a file if a parent
+ * directory of that file is excluded", and it is not decoration: `node_modules` and `dist/` are the
+ * two patterns every project has, and judging `node_modules/pkg/index.js` on its own says NOT
+ * ignored — the pattern names `node_modules`, and the path is not it. Checked against `git
+ * check-ignore` over a matrix of thirty-five paths, this rule is the difference between agreeing
+ * with git everywhere and disagreeing on the two cases that matter most.
+ *
+ * The sidebar happens not to depend on it — an ignored directory draws no row, so nothing ever asks
+ * about its children — but a predicate that is only correct for the caller that exists today is a
+ * trap for the next one.
+ */
+export function isIgnored(layers: readonly IgnoreLayer[], path: string, isDir: boolean): boolean {
+  const target = normalizePath(path);
+  if (target === "") {
+    return false;
+  }
+  const segments = target.split("/");
+  let prefix = "";
+  for (const [index, segment] of segments.entries()) {
+    prefix = prefix === "" ? segment : `${prefix}/${segment}`;
+    const last = index === segments.length - 1;
+    // Every ancestor is a directory; only the final segment is what the caller said it is.
+    if (verdictFor(layers, prefix, last ? isDir : true)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ─── The loaded layers ────────────────────────────────────────────────────────
+
+/** Directory → its own `.gitignore` compiled, or `null` for "looked, there is none". */
+const layerCache = new Map<string, IgnoreLayer | null>();
+/** Reads in progress, so a burst of sibling listings makes one request per directory. */
+const inFlight = new Map<string, Promise<IgnoreLayer | null>>();
+
+/** Forget every layer. Called when the project changes and when a `.gitignore` does. */
+export function resetIgnoreCache(): void {
+  layerCache.clear();
+  inFlight.clear();
+}
+
+/**
+ * Read and compile one directory's `.gitignore`. Uncached, and never rejects.
+ *
+ * A directory without a `.gitignore` is the common case rather than an error, and a backend that
+ * fails the read for some other reason gets the same answer — "no rules" shows the file, and
+ * showing a file the author meant to hide is the only harmless way to be wrong here. The call is
+ * wrapped rather than awaited directly because a platform adapter is free to throw synchronously.
+ */
+async function readGitignore(dir: string): Promise<IgnoreLayer | null> {
+  try {
+    const text = await getPlatform().readFile(dir === "" ? ".gitignore" : `${dir}/.gitignore`);
+    return { base: dir, rules: parseGitignore(text) };
+  } catch {
+    return null;
+  }
+}
+
+/** {@link readGitignore}, once per directory, with concurrent callers sharing the one read. */
+function readLayer(dir: string): Promise<IgnoreLayer | null> {
+  const cached = layerCache.get(dir);
+  if (cached !== undefined) {
+    return Promise.resolve(cached);
+  }
+  const pending = inFlight.get(dir);
+  if (pending) {
+    return pending;
+  }
+  const read = readGitignore(dir).then((layer) => {
+    layerCache.set(dir, layer);
+    inFlight.delete(dir);
+    return layer;
+  });
+  inFlight.set(dir, read);
+  return read;
+}
+
+/**
+ * Re-read every `.gitignore` the tree has already consulted, and swap the results in together.
+ *
+ * Read-then-swap rather than clear-then-read, and that is the whole point of the function: an empty
+ * cache means "nothing is ignored", so a repaint landing between the two would draw a
+ * `node_modules` and then take it away again. Only directories already probed are re-read — the
+ * ones nobody has listed will read their rules when someone does.
+ */
+export async function reloadIgnoreCache(): Promise<void> {
+  const dirs = [...layerCache.keys()];
+  inFlight.clear();
+  const fresh = await Promise.all(dirs.map((dir) => readGitignore(dir)));
+  layerCache.clear();
+  for (const [index, dir] of dirs.entries()) {
+    layerCache.set(dir, fresh[index] ?? null);
+  }
+}
+
+/** Load every `.gitignore` governing `dir`, so {@link isIgnoredEntry} can answer synchronously. */
+export async function ensureIgnoreLayers(dir: string): Promise<void> {
+  await Promise.all(ancestorDirs(dir).map((ancestor) => readLayer(ancestor)));
+}
+
+/** The already-loaded layers governing `dir`, shallow-to-deep. */
+export function loadedLayersFor(dir: string): IgnoreLayer[] {
+  const layers: IgnoreLayer[] = [];
+  for (const ancestor of ancestorDirs(dir)) {
+    const layer = layerCache.get(ancestor);
+    if (layer) {
+      layers.push(layer);
+    }
+  }
+  return layers;
+}
+
+/**
+ * Whether the entry at `path`, listed under `dir`, is masked by `.gitignore`.
+ *
+ * Synchronous, and answers `false` for anything whose layers have not been read yet — a row that
+ * appears and then disappears one frame later is a worse artefact than a row that stayed. The
+ * listing path awaits {@link ensureIgnoreLayers}, so that frame does not normally exist.
+ */
+export function isIgnoredEntry(dir: string, path: string, isDir: boolean): boolean {
+  return isIgnored(loadedLayersFor(dir), path, isDir);
+}
+
+/** Whether any of these paths is a `.gitignore`, i.e. whether the cache is now stale. */
+export function touchesGitignore(paths: readonly string[]): boolean {
+  return paths.some((path) => normalizePath(path).split("/").pop() === ".gitignore");
+}

package/src/files/media-paths.ts

@@ -25,27 +25,22 @@
  * as written rather than on the file as stored.
  *
  * Everything here is pure string math over project-relative, forward-slashed paths. The only input
- * from outside is the open project's content sections, read the same way `content-assets.ts` reads
- * them.
+ * from outside is the open project's content sections, read the same way `canvas/asset-refs.ts`
+ * reads them.
  *
  * @docs studio/projects/media
  */
 
-import { contentMountFor } from "../canvas/content-assets";
+import { encodeProjectPath, normalizeProjectPath, PUBLIC_DIR } from "@jxsuite/schema/asset-paths";
+import { contentMountFor, hostAssetDeclarations, projectLocales } from "../canvas/asset-refs";
+import { loopbackAssetSrc } from "../canvas/canvas-origin";
 import { projectState } from "../store";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { ContentSectionEntry } from "../types";
 
-/** The directory whose contents are served from the site root. */
-const PUBLIC_DIR = "public";
-
-/**
- * A project-relative path in the one spelling every function here expects: forward slashes, no `./`
- * prefix, no leading `/`, no trailing `/`.
- */
-export function normalizeProjectPath(path: string): string {
-  return path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
-}
+/* Re-exported rather than redefined: the same normalization is what the compiler, the servers and
+   the canvas resolver all key on, so there is one definition of it in `@jxsuite/schema`. */
+export { normalizeProjectPath } from "@jxsuite/schema/asset-paths";
 
 /** The filename of a project-relative path. */
 export function baseName(path: string): string {
@@ -75,7 +70,7 @@ function contentSections(): Record<string, ContentSectionEntry> | null {
  * rather than duplicating the loop.
  */
 function mountOf(path: string): AssetMount | null {
-  return contentMountFor(path, contentSections());
+  return contentMountFor(path, contentSections(), projectLocales());
 }
 
 /**
@@ -139,3 +134,31 @@ export function authoredRefTargets(path: string): string[] {
   }
   return targets;
 }
+
+/**
+ * The src a PARENT-REALM preview should load for a PROJECT FILE PATH — a library thumbnail, a
+ * media-browser tile.
+ *
+ * The sibling of `previewAssetSrc` in `canvas/asset-refs`, and separate from it because the two
+ * take different things and confusing them is silent. A file path is NOT an authored reference:
+ * `public/hero.jpg` is written `/hero.jpg`, a string that shares not one segment with it. The
+ * library grid built its `<img src>` by prefixing the path with a slash, so every `public/` image
+ * asked for `/public/hero.jpg` — a URL the site does not publish — and every content-collection
+ * image skipped its mount entirely.
+ *
+ * @param {string} path - A project-relative file path, as the file tree spells it
+ * @returns {string} A src the parent realm can load
+ */
+export function previewFileSrc(path: string): string {
+  const normalized = normalizeProjectPath(path);
+  if (normalized === "") {
+    return path;
+  }
+  /* In repo space nothing answers a site URL, so the site URL is the wrong question entirely: the
+     host serves the FILE, at its own path, under the declared base. */
+  const { space, fileBaseUrl } = hostAssetDeclarations();
+  if (space === "repo") {
+    return `${fileBaseUrl}${encodeProjectPath(normalized)}`;
+  }
+  return loopbackAssetSrc(mediaSiteUrl(normalized));
+}

package/src/files/media-upload.ts

@@ -17,7 +17,7 @@
  */
 
 import { errorMessage } from "@jxsuite/schema/parse";
-import { getPlatform } from "../platform";
+import { getPlatform, hasPlatform } from "../platform";
 import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
 
@@ -50,8 +50,20 @@ export const MEDIA_EXTENSIONS = new Set([
   ".otf",
 ]);
 
-/** The `accept` attribute for every upload file input. */
-export const UPLOAD_ACCEPT = [
+/** A byte count as a person reads it, for a refusal that names the limit. */
+function formatBytes(bytes: number): string {
+  const units = ["B", "KB", "MB", "GB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${unit === 0 ? value : Number(value.toFixed(1))} ${units[unit]}`;
+}
+
+/** What Studio itself offers, before any backend narrows it. */
+const DEFAULT_ACCEPT = [
   "image/*",
   "video/*",
   "audio/*",
@@ -63,6 +75,20 @@ export const UPLOAD_ACCEPT = [
   ".otf",
 ].join(",");
 
+/**
+ * The `accept` attribute for every upload file input.
+ *
+ * A backend may NARROW it by declaring `assetCapabilities.accept`; nothing widens it, because the
+ * picker offering a type Studio cannot place in a document helps no one. Read as a function, not a
+ * constant, because the platform is registered after this module is imported.
+ *
+ * @returns {string} An `<input accept>` value
+ */
+export function uploadAccept(): string {
+  const declared = hasPlatform() ? getPlatform().assetCapabilities?.accept : undefined;
+  return declared ?? DEFAULT_ACCEPT;
+}
+
 /** What kind of element an uploaded asset wants to become. */
 export type AssetKind = "image" | "video" | "audio" | "file";
 
@@ -225,18 +251,33 @@ export async function uploadAssets(
     taken = new Set(); // Directory doesn't exist yet — the backend mkdir -p's on write.
   }
 
+  /* A DECLARED limit, or none. Studio must not invent one: a limit it made up is a file the user
+     cannot upload for no reason anyone can name. A declared one is different — refusing here saves
+     the round trip and lets the refusal say the number. */
+  const maxBytes = hasPlatform() ? getPlatform().assetCapabilities?.maxUploadBytes : undefined;
+
   const uploaded: UploadedAsset[] = [];
   for (const file of list) {
+    if (maxBytes !== undefined && file.size > maxBytes) {
+      notify.error(`${file.name} is too large.`, {
+        detail: `This backend accepts at most ${formatBytes(maxBytes)}; that file is ${formatBytes(file.size)}.`,
+        source: "Media",
+      });
+      continue;
+    }
     const name = uniqueName(file.name, taken);
     taken.add(name);
-    const path = joinDir(dir, name);
+    const requested = joinDir(dir, name);
     try {
-      await platform.uploadFile(path, file);
+      /* The path the backend REPORTS, not the one asked for. A store that de-duplicates by content
+         hash, appends a collision suffix, or normalizes a name writes somewhere else, and the
+         reference that goes into the document has to name what is really there. */
+      const { path } = await platform.uploadFile(requested, file);
       uploaded.push({ kind: mediaKind(file), name, path, ref: assetRef(path) });
     } catch (error) {
       notify.error(`Could not upload ${file.name}.`, {
         detail: errorMessage(error),
-        path,
+        path: requested,
         source: "Media",
       });
     }

package/src/files/serialize-document.ts

@@ -0,0 +1,60 @@
+/**
+ * A tab's document, as the bytes a file would hold.
+ *
+ * Its own module because four callers need it and one of them is `file-ops` itself: the save path
+ * writes what this returns, the source view shows it, the collab layer publishes it, and the live
+ * preview overlay sends it. Leaving it in `file-ops` meant the overlay had to import the module
+ * that imports the overlay, and the collab layer had already worked around the same shape by
+ * injecting the function at boot. One home resolves both.
+ *
+ * That every one of them goes through this function is the point rather than an accident: what a
+ * reader sees in a preview, what a peer sees in a session and what lands on disk are the same
+ * bytes, so they cannot drift.
+ */
+
+import { getGridController } from "../grid/grid-controller";
+import {
+  defaultContentFormat,
+  formatByName,
+  formatSerialize,
+  loadFormats,
+} from "../format/format-host";
+import type { Tab } from "../tabs/tab";
+
+/**
+ * Serialize the current document to its output format. Format tabs round-trip through the format
+ * class's serialize capability; everything else is native JSON.
+ *
+ * @param {import("../tabs/tab.js").Tab} tab
+ * @returns {Promise<string>}
+ */
+export async function serializeDocument(tab: Tab): Promise<string> {
+  // Grid tabs serialize through their source (pending edits included) — e.g. the Monaco source
+  // View of a CSV grid tab shows the live file text.
+  const grid = getGridController(tab);
+  const gridText = grid?.serializeForSource();
+  if (gridText) {
+    return gridText;
+  }
+  await loadFormats();
+  const sourceFormat = formatByName(tab.doc.sourceFormat);
+  if (sourceFormat?.capabilities.serialize) {
+    const fm = tab.doc.content?.frontmatter || {};
+    const doc = tab.doc.document;
+    const fullDoc = { ...fm, ...doc, children: doc.children ?? [] };
+    return formatSerialize(sourceFormat.name, fullDoc, { mode: "roundtrip" });
+  }
+  if (tab.doc.mode === "content") {
+    const format = defaultContentFormat();
+    if (format) {
+      const fm = tab.doc.content?.frontmatter ?? {};
+      const hasFrontmatter = Object.keys(fm).length > 0;
+      const fullDoc = { ...fm, ...tab.doc.document };
+      return formatSerialize(format.name, fullDoc, {
+        frontmatter: hasFrontmatter,
+        mode: "roundtrip",
+      });
+    }
+  }
+  return JSON.stringify(tab.doc.document, null, 2);
+}