@glw907/cairn-cms 0.55.0 → 0.56.1

package/src/lib/components/editor-folding.ts

@@ -1,21 +1,23 @@
-// Container folding: CodeMirror's fold system driven by cairn's directive grammar, with the rail
-// band as the affordance. Client-only like editor-highlight and editor-modes; MarkdownEditor
+// Container folding: CodeMirror's fold system driven by cairn's directive grammar, with a real
+// gutter column as the affordance. Client-only like editor-highlight and editor-modes; MarkdownEditor
 // reaches this module through a dynamic import, so the static @codemirror imports here never enter
 // a server bundle (guarded by the editor-boundary test).
 //
-// The architecture (plan decision 4): @codemirror/language's codeFolding plus foldEffect/
+// The architecture (spec 2026-06-14): @codemirror/language's codeFolding plus foldEffect/
 // unfoldEffect, never a custom fold store. Fold ranges come only from containerRanges, the pure
 // pairing helper beside fenceScan. The safety invariant lives in one transactionExtender that
-// appends unfold effects when a change or selection touches a folded range. The chevrons are
-// widget decorations from this module's own ViewPlugin (the rails are box-shadows, there is no CM
-// gutter element to hang a foldGutter on).
+// appends unfold effects when a change or selection touches a folded range. The control is a custom
+// gutter() whose GutterMarker is a focusable button on each paired-opener row; a lower-level
+// gutter (not foldGutter) is what lets the caret-inside state stay live, since its lineMarkerChange
+// recomputes on selection changes.
 //
 // The safety invariant: an author never edits, deletes, or fails to see hidden text.
 import {
   Decoration,
   EditorView,
+  GutterMarker,
   ViewPlugin,
-  WidgetType,
+  gutter,
   keymap,
   type DecorationSet,
   type ViewUpdate,
@@ -24,17 +26,11 @@ import { EditorState, Prec, RangeSetBuilder, StateEffect, StateField, type Exten
 import { codeFolding, foldEffect, foldedRanges, unfoldEffect } from '@codemirror/language';
 import { caretContainerRange, containerRanges, fenceScan, type ContainerRange } from './markdown-directives.js';
 
-// Deeper nesting shares the third visual step, matching the rail stepping in editor-highlight.
-const DEPTH_STEPS = 3;
-// The chevron sits over the container's own innermost bar: depth 1 at x0, depth 2 at x8, depth 3
-// at x16, so indentation telegraphs the nesting and depth 3 never collides with depth 2.
-const chevronX = (depth: number) => (Math.min(depth, DEPTH_STEPS) - 1) * 8;
-
-// The two chevron glyphs from the gold-standard mockup: down (caret inside) and right (folded).
+// One chevron glyph; CSS rotates it (down open, right folded) and reveals it on gutter hover. The
+// gutter is the fixed-x home, so the chevron no longer encodes depth by position.
 const CHEVRON_DOWN = 'm6 9 6 6 6-6';
-const CHEVRON_RIGHT = 'm9 6 6 6-6 6';
 
-function chevronSvg(direction: 'down' | 'right'): SVGSVGElement {
+function chevronSvg(): SVGSVGElement {
   const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
   svg.setAttribute('viewBox', '0 0 24 24');
   svg.setAttribute('fill', 'none');
@@ -44,57 +40,11 @@ function chevronSvg(direction: 'down' | 'right'): SVGSVGElement {
   svg.setAttribute('stroke-linejoin', 'round');
   svg.setAttribute('aria-hidden', 'true');
   const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
-  path.setAttribute('d', direction === 'down' ? CHEVRON_DOWN : CHEVRON_RIGHT);
+  path.setAttribute('d', CHEVRON_DOWN);
   svg.appendChild(path);
   return svg;
 }
 
-// The opener-row band: the whole 28px gutter is the click target (cursor pointer over the band
-// only, the opener text never folds), and the chevron lives inside it at the container's bar x.
-// The widget knows its own container and whether it is folded, so the click toggles the right
-// range; the depth class lets the theme step the chevron ink.
-class FoldBandWidget extends WidgetType {
-  constructor(
-    readonly range: ContainerRange,
-    readonly folded: boolean,
-    readonly caretInside: boolean,
-  ) {
-    super();
-  }
-  eq(other: FoldBandWidget) {
-    return (
-      other.range.fromLine === this.range.fromLine &&
-      other.range.toLine === this.range.toLine &&
-      other.range.depth === this.range.depth &&
-      other.folded === this.folded &&
-      other.caretInside === this.caretInside
-    );
-  }
-  toDOM(view: EditorView): HTMLElement {
-    const band = document.createElement('span');
-    const depth = Math.min(this.range.depth, DEPTH_STEPS);
-    // Folded rows always show the chevron (right); an open container shows it down while the caret
-    // is inside; otherwise it fades in on rail-band hover (the band's own :hover, in the theme).
-    // The depth class carries the stepped ink.
-    const state = this.folded ? ' cm-cairn-fold-folded' : this.caretInside ? ' cm-cairn-fold-active' : '';
-    band.className = `cm-cairn-fold-band cm-cairn-fold-depth-${depth}${state}`;
-    const chevron = chevronSvg(this.folded ? 'right' : 'down');
-    chevron.style.left = `${chevronX(this.range.depth)}px`;
-    band.appendChild(chevron);
-    band.addEventListener('mousedown', (e) => {
-      // mousedown, not click: a click would first move the caret into the line. preventDefault
-      // keeps the caret where it is and stops the band from stealing focus from the editor.
-      e.preventDefault();
-      e.stopPropagation();
-      toggleFold(view, this.range);
-    });
-    return band;
-  }
-  ignoreEvent() {
-    return false;
-  }
-}
-
 // The pill placeholder: a real focusable button counting the hidden lines, the screen-reader story
 // for a fold. preparePlaceholder computes the count off the folded char range so placeholderDOM
 // renders it without re-deriving. Clicking unfolds through CodeMirror's own onclick handler.
@@ -114,8 +64,7 @@ function placeholderDOM(view: EditorView, onclick: (event: Event) => void, lines
 
 // The char range a container folds: end-of-opener-line to end-of-closer-line, so the bare closer
 // never dangles. Null when the opener and closer share a line (nothing to hide). The one place
-// that turns a line range into the fold range, shared by the toggle, the keymap, and the
-// decoration build.
+// that turns a line range into the fold range, shared by the toggle, the keymap, and the gutter.
 function foldCharRange(state: EditorState, range: ContainerRange): { from: number; to: number } | null {
   const opener = state.doc.line(range.fromLine + 1);
   const closer = state.doc.line(range.toLine + 1);
@@ -144,22 +93,47 @@ function foldExists(state: EditorState, from: number, to: number): boolean {
 // returns the nearest enclosing container, but a container that never closes (an unbalanced
 // opener) must not fold, so the result is only honored when containerRanges actually pairs it.
 function caretFoldRange(view: EditorView): ContainerRange | null {
-  const scan = fenceScan(docLines(view));
+  const { scan, ranges } = foldScanFor(view.state);
   const caretLine = view.state.doc.lineAt(view.state.selection.main.head).number - 1;
   const inner = caretContainerRange(scan, caretLine);
   if (!inner) return null;
-  return (
-    containerRanges(scan).find((r) => r.fromLine === inner.fromLine && r.toLine === inner.toLine) ?? null
-  );
+  return ranges.find((r) => r.fromLine === inner.fromLine && r.toLine === inner.toLine) ?? null;
 }
 
-function docLines(view: EditorView): string[] {
-  const doc = view.state.doc;
+function docLines(state: EditorState): string[] {
   const lines: string[] = [];
-  for (let n = 1; n <= doc.lines; n++) lines.push(doc.line(n).text);
+  for (let n = 1; n <= state.doc.lines; n++) lines.push(state.doc.line(n).text);
   return lines;
 }
 
+// The scan and its paired ranges, memoized per state so the gutter's per-line lookups stay linear
+// rather than rescanning the whole document on every line.
+const scanCache = new WeakMap<EditorState, { scan: ReturnType<typeof fenceScan>; ranges: ContainerRange[] }>();
+function foldScanFor(state: EditorState): { scan: ReturnType<typeof fenceScan>; ranges: ContainerRange[] } {
+  let cached = scanCache.get(state);
+  if (!cached) {
+    const scan = fenceScan(docLines(state));
+    cached = { scan, ranges: containerRanges(scan) };
+    scanCache.set(state, cached);
+  }
+  return cached;
+}
+
+// The paired container whose opener sits at this line start, or null (a closer, a prose line, or an
+// unbalanced opener gets nothing). The sole source of which rows carry a fold control.
+function openerRangeAt(state: EditorState, lineFrom: number): ContainerRange | null {
+  const lineIndex = state.doc.lineAt(lineFrom).number - 1;
+  return foldScanFor(state).ranges.find((r) => r.fromLine === lineIndex) ?? null;
+}
+
+// Whether the caret's innermost container is exactly this one, the caret-inside active state.
+function caretInside(state: EditorState, range: ContainerRange): boolean {
+  const { scan } = foldScanFor(state);
+  const caretLine = state.doc.lineAt(state.selection.main.head).number - 1;
+  const inner = caretContainerRange(scan, caretLine);
+  return !!inner && inner.fromLine === range.fromLine && inner.toLine === range.toLine;
+}
+
 // The keymap: Ctrl+Shift+[ folds, Ctrl+Shift+] unfolds, the innermost container at the caret. No
 // fold-all, no chords. (CodeMirror's own foldKeymap binds the same keys to its tree-folding
 // commands; this module replaces them with the container-aware versions and never adds foldKeymap.)
@@ -258,33 +232,21 @@ function safetyExtender(): Extension {
   });
 }
 
-// The chevron-and-wash plugin: a widget on each opener row of a paired container (the band with
-// the chevron) and the folded-row wash line decoration. Rebuilds on doc change (the container set
-// moves), selection change (the caret-inside chevron state), viewport change, and any fold change
-// (a fold flips a chevron and adds a wash). The hover reveal is the band's own CSS :hover in the
-// theme, so it costs no rebuild.
-function foldDecorations(view: EditorView, scan: ReturnType<typeof fenceScan>, ranges: ContainerRange[]): DecorationSet {
+// The folded-row wash plugin: a line decoration on each folded opener row, square and full-row so
+// folded spots read in a scan. Rebuilds on doc change (the container set moves), viewport change,
+// and any fold change (a fold adds a wash, an unfold removes it). The chevron lives in the gutter
+// now, not here; this plugin carries only the wash and the unfold flash scheduling.
+function foldDecorations(view: EditorView, ranges: ContainerRange[]): DecorationSet {
   const builder = new RangeSetBuilder<Decoration>();
-  const caretLine = view.state.doc.lineAt(view.state.selection.main.head).number - 1;
-  const inner = caretContainerRange(scan, caretLine);
-  // One opener row may host several enclosing containers' bars, but only its OWN container opens
-  // there, so a single band per opener row. Sort by opener line so the builder receives ascending
-  // positions; equal openers cannot happen (one open per line).
+  // Sort by opener line so the builder receives ascending positions; equal openers cannot happen
+  // (one open per line).
   const byOpener = [...ranges].sort((a, b) => a.fromLine - b.fromLine);
   for (const range of byOpener) {
     const span = foldCharRange(view.state, range);
     if (!span) continue;
     const opener = view.state.doc.line(range.fromLine + 1);
-    const folded = foldExists(view.state, span.from, span.to);
-    // The folded opener row carries the wash; a line decoration so the rails (box-shadows on the
-    // same element) run through it unbroken.
-    if (folded) builder.add(opener.from, opener.from, washLine);
-    const caretInside = !!inner && inner.fromLine === range.fromLine && inner.toLine === range.toLine;
-    builder.add(
-      opener.from,
-      opener.from,
-      Decoration.widget({ widget: new FoldBandWidget(range, folded, caretInside), side: -1 }),
-    );
+    // A line decoration so the rails (box-shadows on the same element) run through it unbroken.
+    if (foldExists(view.state, span.from, span.to)) builder.add(opener.from, opener.from, washLine);
   }
   return builder.finish();
 }
@@ -295,23 +257,20 @@ function foldPlugin() {
   return ViewPlugin.fromClass(
     class {
       decorations: DecorationSet;
-      scan: ReturnType<typeof fenceScan>;
       ranges: ContainerRange[];
       constructor(view: EditorView) {
-        this.scan = fenceScan(docLines(view));
-        this.ranges = containerRanges(this.scan);
-        this.decorations = foldDecorations(view, this.scan, this.ranges);
+        this.ranges = foldScanFor(view.state).ranges;
+        this.decorations = foldDecorations(view, this.ranges);
       }
       update(update: ViewUpdate) {
         if (update.docChanged) {
-          this.scan = fenceScan(docLines(update.view));
-          this.ranges = containerRanges(this.scan);
+          this.ranges = foldScanFor(update.view.state).ranges;
         }
         const foldChanged = update.transactions.some((tr) =>
           tr.effects.some((e) => e.is(foldEffect) || e.is(unfoldEffect)),
         );
-        if (update.docChanged || update.viewportChanged || update.selectionSet || foldChanged) {
-          this.decorations = foldDecorations(update.view, this.scan, this.ranges);
+        if (update.docChanged || update.viewportChanged || foldChanged) {
+          this.decorations = foldDecorations(update.view, this.ranges);
         }
         // Flash the revealed lines on an unfold, then schedule the clear. Folding adds no flash.
         for (const tr of update.transactions) {
@@ -335,15 +294,88 @@ function foldPlugin() {
   );
 }
 
+const FOLD_KEY_HINT = ' (Ctrl+Shift+[)';
+const UNFOLD_KEY_HINT = ' (Ctrl+Shift+])';
+
+// The gutter control: a real focusable button per paired-opener row, holding one chevron that CSS
+// rotates (down open, right folded) and reveals on gutter hover. mousedown keeps the caret and
+// focus where they are; click toggles, so one handler serves a mouse click and a keyboard
+// activation (Enter/Space) with no double-toggle. The folded and caret-active classes carry the
+// state the theme reads.
+class FoldMarker extends GutterMarker {
+  constructor(
+    readonly container: ContainerRange,
+    readonly folded: boolean,
+    readonly active: boolean,
+  ) {
+    super();
+  }
+  eq(other: GutterMarker) {
+    return (
+      other instanceof FoldMarker &&
+      other.container.fromLine === this.container.fromLine &&
+      other.container.toLine === this.container.toLine &&
+      other.folded === this.folded &&
+      other.active === this.active
+    );
+  }
+  toDOM(view: EditorView) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    const label = this.folded ? 'Unfold this section' : 'Fold this section';
+    btn.className =
+      'cm-cairn-fold-btn' +
+      (this.folded ? ' cm-cairn-fold-folded' : '') +
+      (this.active ? ' cm-cairn-fold-active' : '');
+    btn.setAttribute('aria-label', label);
+    btn.title = label + (this.folded ? UNFOLD_KEY_HINT : FOLD_KEY_HINT);
+    btn.appendChild(chevronSvg());
+    btn.addEventListener('mousedown', (e) => e.preventDefault());
+    btn.addEventListener('click', (e) => {
+      e.preventDefault();
+      toggleFold(view, this.container);
+    });
+    return btn;
+  }
+}
+
+// The fold gutter: a fixed-x column (width from the theme) carrying one FoldMarker per paired
+// opener. lineMarker returns null for every other row, so the column is empty whitespace down the
+// rest of the surface. lineMarkerChange recomputes the markers on a doc change, a selection change
+// (the caret-inside state follows the cursor), and any fold effect (a fold flips the chevron).
+function foldGutterColumn(): Extension {
+  return gutter({
+    class: 'cm-cairn-fold-gutter',
+    lineMarker(view, line) {
+      const range = openerRangeAt(view.state, line.from);
+      if (!range) return null;
+      const span = foldCharRange(view.state, range);
+      if (!span) return null;
+      const folded = foldExists(view.state, span.from, span.to);
+      return new FoldMarker(range, folded, caretInside(view.state, range));
+    },
+    lineMarkerChange(update) {
+      return (
+        update.docChanged ||
+        update.selectionSet ||
+        update.transactions.some((tr) =>
+          tr.effects.some((e) => e.is(foldEffect) || e.is(unfoldEffect)),
+        )
+      );
+    },
+  });
+}
+
 // The design notes' diagnostics rules (a deliberately refolded erroring container keeps its fold
 // and tints the pill warning ink instead of re-springing on every lint) have no trigger today: the
 // editor carries no lint source, so there is nothing to refold around or to tint. Deliberately not
 // built; do not invent a lint system to satisfy a rule with no input.
 
 /**
- * The cairn fold extension: the CodeMirror fold system with the pill placeholder, the chevron and
- * wash affordance, the safety invariant, and the Ctrl+Shift+[ / ] keymap. Session-local and never
- * persisted: the fold state lives in CodeMirror's foldState field, which this never serializes.
+ * The cairn fold extension: the CodeMirror fold system with the pill placeholder, the gutter chevron
+ * and folded-row wash affordance, the safety invariant, and the Ctrl+Shift+[ / ] keymap.
+ * Session-local and never persisted: the fold state lives in CodeMirror's foldState field, which
+ * this never serializes.
  */
 export function cairnFolding(): Extension {
   return [
@@ -351,6 +383,7 @@ export function cairnFolding(): Extension {
     flashField,
     safetyExtender(),
     foldPlugin(),
+    foldGutterColumn(),
     foldKeymap,
   ];
 }

package/src/lib/components/editor-highlight.ts

@@ -7,7 +7,6 @@ import { Decoration, ViewPlugin, type DecorationSet, type EditorView, type ViewU
 import { RangeSetBuilder } from '@codemirror/state';
 import {
   caretContainerRange,
-  containerRanges,
   directiveLineKind,
   fenceScan,
   fenceTokens,
@@ -63,11 +62,6 @@ const fenceLines = DEPTH_STEPS.map((d) =>
 );
 const contentLines = DEPTH_STEPS.map((d) => Decoration.line({ class: `cm-cairn-directive-content cm-cairn-depth-${d}` }));
 const leafLine = Decoration.line({ class: 'cm-cairn-directive-leaf', attributes: { title: MACHINERY_HINT } });
-// A paired container's opener row, where the fold chevron replaces the container's own innermost
-// rail bar. The class is additive over the fence depth class, so the theme drops only the deepest
-// bar on this row while the outer bars stay; an unbalanced opener never gets it (no chevron, bar
-// intact). Added just after the fence depth line decoration so the row carries both classes.
-const openerLine = Decoration.line({ class: 'cm-cairn-directive-opener' });
 const inlineMark = Decoration.mark({ class: 'cm-cairn-directive-inline' });
 // Within a fence line, machinery (colons, brackets, braces) dims to the marker tone while the
 // directive name and label keep a depth-stepped ink: meaning over machinery.
@@ -118,9 +112,6 @@ function buildDirectiveDecorations(view: EditorView, scan: FenceScan): Decoratio
   // as its own line decoration just ahead of the row's depth decoration.
   const caretLine = view.state.doc.lineAt(view.state.selection.main.head).number - 1;
   const caret = caretContainerRange(scan, caretLine);
-  // The opener rows that carry a fold chevron, so the rail rule drops their innermost bar. Only
-  // paired containers fold, so an unbalanced opener is absent here and keeps its full rail.
-  const openerLines = new Set(containerRanges(scan).map((r) => r.fromLine));
   for (const { from, to } of view.visibleRanges) {
     for (let pos = from; pos <= to; ) {
       const line = view.state.doc.lineAt(pos);
@@ -133,9 +124,6 @@ function buildDirectiveDecorations(view: EditorView, scan: FenceScan): Decoratio
       // inside a code block, outside any container); it gets no machinery treatment.
       if (kind === 'fence' && depth > 0) {
         builder.add(line.from, line.from, fenceLines[depth - 1]);
-        // A paired opener row gets the opener class just after its fence depth class, so the rail
-        // rule below drops the innermost bar where the chevron renders.
-        if (openerLines.has(line.number - 1)) builder.add(line.from, line.from, openerLine);
       } else if (kind === 'leaf') {
         builder.add(line.from, line.from, leafLine);
       } else if (kind === null && depth > 0) {

package/src/lib/content/concepts.ts

@@ -100,9 +100,11 @@ export function normalizeConcepts(
     const conceptRouting = routing[id] ?? DEFAULT_ROUTING;
     const policy = urlPolicy[id] ?? {};
     validateUrlPolicy(id, policy, conceptRouting.dated);
+    const label = config.label ?? defaultLabel(id);
     descriptors.push({
       id,
-      label: config.label ?? defaultLabel(id),
+      label,
+      singular: config.singular ?? label,
       dir: config.dir,
       routing: conceptRouting,
       permalink: policy.permalink ?? defaultPermalink(id),

package/src/lib/content/types.ts

@@ -108,6 +108,8 @@ export interface ConceptConfig<S extends ConceptSchema = ConceptSchema> {
   dir: string;
   /** Sidebar label; defaults from the concept id when omitted. */
   label?: string;
+  /** The singular noun for the create affordances ("New post"); defaults to `label` when omitted. */
+  singular?: string;
   /** The concept's schema: the form projection, the generated validator, and the inferred type. */
   schema: S;
   /** Frontmatter keys to surface on each `ContentSummary.fields`, so a list card reads an authored
@@ -241,6 +243,9 @@ export interface ConceptDescriptor {
   /** Concept id, the key under `content`, e.g. "posts". */
   id: string;
   label: string;
+  /** The singular noun for the create affordances ("New post"); resolved from `ConceptConfig.singular`,
+   *  defaulting to `label` when the config omits it. */
+  singular: string;
   dir: string;
   routing: RoutingRule;
   /** The resolved permalink pattern, defaulted by `normalizeConcepts`. */

package/src/lib/sveltekit/content-routes.ts

@@ -67,6 +67,9 @@ export interface EntrySummary {
 export interface ListData {
   conceptId: string;
   label: string;
+  /** The singular noun for the create affordances ("New post"); from the descriptor, which defaults
+   *  it to `label`. */
+  singular: string;
   /** Posts carry a date in the new-entry form; pages do not (concept routing, spec §7.2). */
   dated: boolean;
   entries: EntrySummary[];
@@ -306,7 +309,7 @@ export function createContentRoutes(runtime: CairnRuntime, deps: ContentRoutesDe
     const formError = event.url.searchParams.get('error');
     const publishedAllRaw = event.url.searchParams.get('publishedAll');
     const publishedAll = publishedAllRaw !== null && /^\d+$/.test(publishedAllRaw) ? Number(publishedAllRaw) : null;
-    const base = { conceptId: concept.id, label: concept.label, dated: concept.routing.dated, formError, publishedAll };
+    const base = { conceptId: concept.id, label: concept.label, singular: concept.singular, dated: concept.routing.dated, formError, publishedAll };
     let token: string;
     try {
       token = await mintToken(event.platform?.env ?? {});

package/src/lib/sveltekit/index.ts

@@ -25,3 +25,5 @@ export { healthLoad, type HealthData } from './health.js';
 export type { RequestContext, CookieJar, HandleInput } from './types.js';
 // Re-exported here, not from root, so the public ContentRoutesDeps consumer can name it.
 export type { GithubKeyEnv } from '../github/credentials.js';
+// Re-exported here, not just from root, so the app.d.ts Platform block can name it.
+export type { AuthEnv } from '../auth/types.js';

package/src/lib/vite/index.ts

@@ -8,6 +8,7 @@
 import type { Plugin, PluginOption } from 'vite';
 import { writeFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { resolveViteRoot } from './resolve-root.js';
 
 /** The key the cairnManifest plugin stashes its options under, so the write path can read them off the
  *  plugin instance in the consumer's loaded config without re-parsing the config file. */
@@ -152,10 +153,12 @@ export function cairnManifest(opts: CairnManifestOptions): Plugin {
 }
 
 /** Regenerate the committed manifest from the consumer's corpus and write it to the configured
- *  manifestPath. It loads the consumer's Vite config from `cwd`, reads the cairnManifest plugin's
- *  options off the instance, evaluates the write-mode virtual module through the build's own
- *  resolution, and writes the serialized manifest. The cairn-manifest bin calls this; it is exported
- *  so the write logic is testable apart from the CLI shell. */
+ *  manifestPath. It searches for the consumer's Vite config from `cwd`, derives the authoritative
+ *  Vite root from the loaded config (so a configured `root` or a non-root cwd resolves correctly),
+ *  reads the cairnManifest plugin's options off the instance, evaluates the write-mode virtual
+ *  module through the build's own resolution, and writes the serialized manifest under the Vite
+ *  root. The cairn-manifest bin calls this; it is exported so the write logic is testable apart
+ *  from the CLI shell. */
 export async function writeManifest(cwd: string = process.cwd()): Promise<void> {
   const { loadConfigFromFile } = await import('vite');
   const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, undefined, cwd);
@@ -168,11 +171,12 @@ export async function writeManifest(cwd: string = process.cwd()): Promise<void>
       'cairn-manifest: the Vite config has no cairnManifest() plugin. Add it so the bin shares the build options.',
     );
   }
-  const serialized = await buildManifestFromVite(opts, cwd);
+  const root = resolveViteRoot(loaded, cwd);
+  const serialized = await buildManifestFromVite(opts, root);
   const manifestPath = opts.manifestPath ?? DEFAULT_MANIFEST_PATH;
   // The manifest path is app-root-absolute (a leading slash relative to the project), so resolve it
-  // against cwd, not the filesystem root.
-  const outPath = join(cwd, manifestPath.replace(/^\//, ''));
+  // against the Vite root, not the filesystem root or the config-search cwd.
+  const outPath = join(root, manifestPath.replace(/^\//, ''));
   await mkdir(dirname(outPath), { recursive: true });
   await writeFile(outPath, serialized);
 }

package/src/lib/vite/resolve-root.ts

@@ -0,0 +1,24 @@
+// The manifest bin's root derivation, split out so it is unit-testable without widening the public
+// /vite surface (only src/lib/vite/index.ts is the package subpath; this sibling is internal).
+import { dirname, isAbsolute, resolve } from 'node:path';
+
+/** The shape of `loadConfigFromFile`'s result that the root derivation reads: the config file's own
+ *  path and its `root` field. Typed structurally so the helper is testable without a real load. */
+export interface LoadedViteConfig {
+  /** The resolved path of the config file Vite loaded. */
+  path: string;
+  /** The user config, of which only `root` is read here. */
+  config: { root?: string };
+}
+
+/** The authoritative Vite root for the manifest bin, derived from the loaded config the way Vite
+ *  resolves a relative `root`: against the config file's own directory, not cwd. An absolute `root`
+ *  stands as given, and no `root` falls back to `cwd` (the directory the bin was run from). This
+ *  separates the config-search dir (cwd) from the Vite root, so a non-root cwd or a config that
+ *  sets `root` reads and writes the manifest under the real app root. */
+export function resolveViteRoot(loaded: LoadedViteConfig, cwd: string): string {
+  const root = loaded.config.root;
+  if (!root) return cwd;
+  if (isAbsolute(root)) return root;
+  return resolve(dirname(loaded.path), root);
+}