@immediately-run/grove 0.1.1

package/src/lib/directory.ts

@@ -0,0 +1,262 @@
+// Directory listings — the pure half (ways_of_working §5).
+//
+// Grove's route space is a filesystem, so a reader can always ask for a path that names a
+// FOLDER rather than an entry: a typed URL, a link into a namespace, the host's file
+// explorer, a trailing slash on a citation. Before this module every one of those resolved
+// to the 404 ("No entry at …"), which is a lie — the entries are right there, one level
+// down. A folder is a legitimate destination and this is what it renders.
+//
+// Everything here is a pure function over (directory listing, frontmatter index) so the
+// ordering, classification, and column-selection rules are testable without a filesystem
+// and without React. The effectful half is `hooks/useDirectoryListing`; the rendering half
+// is `components/DirectoryList`.
+
+import type { Frontmatter } from './frontmatter';
+import { contentDir, isContentEntry, keyToHref } from './content';
+
+/** One `readdir` result — the slice of `Dirent` this module needs. */
+export interface DirEntry {
+  name: string;
+  isDirectory: boolean;
+}
+
+/** What a row IS, which decides whether it is a link and how it is iconed.
+ *  - `dir`   — a subfolder; navigates to its own listing.
+ *  - `entry` — a content entry (`isContentEntry`); navigates to the page.
+ *  - `file`  — anything else (an asset, a data file). Listed, never linked: the
+ *    viewer's route space only renders entries, so a link would land on a 404. */
+export type DirRowKind = 'dir' | 'entry' | 'file';
+
+export interface DirRow {
+  /** The on-disk name (`onboarding.mdx`, `people`). */
+  name: string;
+  /** The canonical key — the absolute fs path, the same identifier the metadata
+   *  index and `<Include>` use (see lib/content). */
+  key: string;
+  kind: DirRowKind;
+  /** The `<Link>` target, or null for a row that is not navigable. */
+  href: string | null;
+  /** The entry's frontmatter, when the index has any. `null` for dirs and assets. */
+  meta: Frontmatter | null;
+}
+
+/** The metadata columns a listing can carry. `name` is structural and always shown;
+ *  the rest are *grove-specific frontmatter* and appear only when the corpus supplies
+ *  them — a folder of plain markdown gets a plain table rather than four empty columns. */
+export type DirColumn = 'name' | 'description' | 'tags' | 'updated' | 'status';
+
+export const ALL_COLUMNS: readonly DirColumn[] = ['name', 'description', 'tags', 'updated', 'status'];
+
+/** Folders that are machinery, never content — hidden even with `hidden` set, because
+ *  they are not part of any corpus and walking into one is never what a reader meant.
+ *  Mirrors `corpusScan`'s SKIP_DIRS. */
+const NEVER_LIST = new Set(['.git', 'node_modules', '.immediately.run']);
+
+/** `_`-prefixed files are STRUCTURE (`_layout.mdx`), dot-prefixed files are hidden by
+ *  filesystem convention. Neither is a reader-facing entry, so both stay out of the
+ *  default listing — `isContentEntry` already excludes them from every other Grove
+ *  enumeration, and a listing that disagreed would offer a row that renders nothing. */
+function isHiddenName(name: string): boolean {
+  return name.startsWith('.') || name.startsWith('_');
+}
+
+/** Strip Grove's headline-ends-on-a-period house style for use as a table label. */
+export function rowLabel(row: DirRow): string {
+  const title = typeof row.meta?.title === 'string' ? row.meta.title.trim() : '';
+  if (title) return title.replace(/\.$/, '');
+  return row.kind === 'entry' ? row.name.replace(/\.mdx?$/, '') : row.name;
+}
+
+/** The value a metadata column shows for a row, or `null` when the row has none.
+ *  `updated` accepts either spelling — corpora in the wild use `updated:` (the docs
+ *  wiki) or `date:` (the sample corpus), and a listing that knew only one would show
+ *  an empty column over a corpus that dates every entry. */
+export function columnValue(row: DirRow, col: DirColumn): string | string[] | null {
+  if (col === 'name') return rowLabel(row);
+  const m = row.meta;
+  if (!m) return null;
+  if (col === 'tags') {
+    const tags = Array.isArray(m.tags) ? m.tags.filter((t): t is string => typeof t === 'string') : [];
+    // `ui/…` tags are wiring (nav placement), not subject matter — the same filter
+    // <DocList> applies, so the two surfaces describe an entry the same way.
+    const visible = tags.filter((t) => !t.startsWith('ui/'));
+    return visible.length ? visible : null;
+  }
+  const raw = col === 'updated' ? (m.updated ?? m.date) : m[col];
+  // Scalars only. A frontmatter key can hold a map (`owns:`) or a list, and
+  // `String()`-ing one into a table cell prints `[object Object]` — worse than an
+  // empty cell, because it looks like data.
+  if (typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean') {
+    const text = String(raw).trim();
+    return text ? text : null;
+  }
+  return null;
+}
+
+/** The columns to render: `name`, plus every requested metadata column that at least
+ *  one row actually carries. Adaptive rather than fixed so the table describes the
+ *  corpus it is over instead of the corpus its author imagined. */
+export function visibleColumns(rows: DirRow[], requested: readonly DirColumn[] = ALL_COLUMNS): DirColumn[] {
+  const out: DirColumn[] = ['name'];
+  for (const col of requested) {
+    if (col === 'name') continue;
+    if (rows.some((r) => columnValue(r, col) !== null)) out.push(col);
+  }
+  return out;
+}
+
+/** Parse a `columns="description,tags"` attribute into a validated column list.
+ *  Unknown names are dropped rather than thrown: the attribute is author input in
+ *  content, and one typo must not take the page down. */
+export function parseColumns(spec: string | undefined): readonly DirColumn[] {
+  if (!spec) return ALL_COLUMNS;
+  const named = spec
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s): s is DirColumn => (ALL_COLUMNS as readonly string[]).includes(s));
+  return named.length ? named : ALL_COLUMNS;
+}
+
+export interface BuildOptions {
+  /** Include dot- and `_`-prefixed names (default false). */
+  hidden?: boolean;
+  /** `name` (default) sorts on the on-disk name; `title` on the rendered label;
+   *  `updated` puts the most recently updated first. Directories always sort first —
+   *  they are the navigational skeleton and a reader scans for them. */
+  sort?: 'name' | 'title' | 'updated';
+}
+
+/**
+ * Turn a directory listing plus the frontmatter index into display rows.
+ *
+ * `dirKey` is the absolute key of the folder (no trailing slash needed); `metadata` is
+ * the same `Record<absolutePath, frontmatter>` every other Grove surface reads, so a
+ * dispatched corpus (scanned) and a fork (bundler-fed) behave identically here.
+ */
+export function buildDirectoryRows(
+  dirKey: string,
+  entries: readonly DirEntry[],
+  metadata: Record<string, Frontmatter> = {},
+  opts: BuildOptions = {}
+): DirRow[] {
+  const base = dirKey.replace(/\/+$/, '');
+  const rows: DirRow[] = [];
+  for (const e of entries) {
+    if (NEVER_LIST.has(e.name)) continue;
+    if (!opts.hidden && isHiddenName(e.name)) continue;
+    const key = `${base}/${e.name}`;
+    if (e.isDirectory) {
+      rows.push({ name: e.name, key, kind: 'dir', href: keyToHref(key), meta: null });
+      continue;
+    }
+    const entry = isContentEntry(key);
+    rows.push({
+      name: e.name,
+      key,
+      kind: entry ? 'entry' : 'file',
+      href: entry ? keyToHref(key) : null,
+      meta: metadata[key] ?? null,
+    });
+  }
+  return sortRows(rows, opts.sort ?? 'name');
+}
+
+// Three tiers, always, whatever the sort key: subfolders, then entries, then assets.
+// Interleaving assets with entries by name buries the content — measured on a dispatched
+// corpus where `diagram.svg` sorted above every page in the folder purely on its initial.
+// Folders lead because they are the navigational skeleton a reader scans for.
+const KIND_RANK: Record<DirRowKind, number> = { dir: 0, entry: 1, file: 2 };
+
+function sortRows(rows: DirRow[], sort: NonNullable<BuildOptions['sort']>): DirRow[] {
+  const rank = (r: DirRow): number => KIND_RANK[r.kind];
+  return rows.sort((a, b) => {
+    if (rank(a) !== rank(b)) return rank(a) - rank(b);
+    if (sort === 'title') return rowLabel(a).localeCompare(rowLabel(b));
+    if (sort === 'updated') {
+      const av = String(columnValue(a, 'updated') ?? '');
+      const bv = String(columnValue(b, 'updated') ?? '');
+      if (av !== bv) return bv.localeCompare(av); // newest first; undated sinks
+    }
+    return a.name.localeCompare(b.name);
+  });
+}
+
+/**
+ * The folder a listing is FOR, given a `path` attribute and the route's own directory.
+ *
+ * A leading `/` means corpus-relative (`/handbook`); anything else resolves against
+ * `fromDir`, exactly the rule `hrefKeyCandidates` applies to author-written links — an
+ * author writes paths relative to the entry they are in. Traversal is resolved, then the
+ * result is confined to the corpus: a `path` is author (or reader) input, and under
+ * dispatch it is foreign, so `../../..` must not become a readdir of somebody's mount.
+ * Out-of-corpus resolves to the corpus root rather than erroring — the same
+ * fail-to-home posture `sandboxPathToKey` takes.
+ */
+export function resolveDirKey(path: string | undefined, fromDir: string): string {
+  const root = contentDir().replace(/\/+$/, '');
+  const from = fromDir.replace(/\/+$/, '') || root;
+  const raw = !path ? from : path.startsWith('/') ? `${root}${path}` : `${from}/${path}`;
+  const out: string[] = [];
+  for (const seg of raw.split('/')) {
+    if (!seg || seg === '.') continue;
+    if (seg === '..') out.pop();
+    else out.push(seg);
+  }
+  const abs = `/${out.join('/')}`;
+  return abs === root || abs.startsWith(`${root}/`) ? abs : root;
+}
+
+/** The breadcrumb segments of a directory key, corpus-root first. */
+export function dirCrumbs(dirKey: string): Array<{ label: string; key: string }> {
+  const root = contentDir().replace(/\/+$/, '');
+  const rel = dirKey.replace(/\/+$/, '').slice(root.length).replace(/^\//, '');
+  const out: Array<{ label: string; key: string }> = [];
+  let acc = root;
+  for (const seg of rel.split('/').filter(Boolean)) {
+    acc = `${acc}/${seg}`;
+    out.push({ label: seg, key: acc });
+  }
+  return out;
+}
+
+/**
+ * The entry a folder URL should render INSTEAD of a generated listing — the folder-index
+ * convention. This is the corpus's own override: an author who wants `handbook/` to be a
+ * curated page writes `handbook/index.mdx` and gets it, with no engine change and no
+ * component registration. Absent one, the listing is the answer.
+ */
+const INDEX_NAMES = ['index.mdx', 'index.md'];
+
+export function folderIndexKey(dirKey: string, keys: readonly string[]): string | null {
+  const base = dirKey.replace(/\/+$/, '');
+  for (const name of INDEX_NAMES) {
+    const candidate = `${base}/${name}`;
+    if (keys.includes(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** A directory key → the corpus-relative `path` attribute that names it
+ *  (`/app/content/handbook` → `/handbook`; the corpus root → `/`). The inverse of
+ *  {@link resolveDirKey}'s leading-slash form, so the router can hand a folder to the
+ *  overridable `<DirectoryList/>` through its PUBLIC prop rather than a private one. */
+export function dirKeyToPath(dirKey: string): string {
+  const root = contentDir().replace(/\/+$/, '');
+  const rel = dirKey.replace(/\/+$/, '').slice(root.length);
+  return rel || '/';
+}
+
+/**
+ * Does this key name a FOLDER that contains entries, judged from the frontmatter index
+ * alone?
+ *
+ * Index-only on purpose: this answers a question asked once per link in a rendered body,
+ * and a `readdir` per link would turn a page of prose into a burst of host RPCs. The
+ * blind spot is a folder holding nothing but assets — which no author links to as a
+ * destination, and which the ROUTE still resolves correctly because that path does ask
+ * the filesystem.
+ */
+export function isFolderKey(key: string, keys: readonly string[]): boolean {
+  const prefix = `${key.replace(/\/+$/, '')}/`;
+  return keys.some((k) => k.startsWith(prefix));
+}

package/src/lib/fragment.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { fragmentOf, resolveFragmentTarget } from './fragment';
+
+/** A minimal DOM stand-in: enough of `querySelectorAll('[data-entry]')` + scoped
+ *  `querySelector` for what `resolveFragmentTarget` does. */
+function makeDoc(bodies: { entry: string; ids: string[]; slugs?: string[] }[]): Document {
+  const scopeFor = (b: { entry: string; ids: string[]; slugs?: string[] }) => ({
+    getAttribute: (name: string) => (name === 'data-entry' ? b.entry : null),
+    querySelector: (sel: string) => {
+      const id = sel.match(/^\[id="(.*)"\]$/)?.[1];
+      const slug = sel.match(/^\[data-slug="(.*)"\]$/)?.[1];
+      if (id && b.ids.includes(id)) return { entry: b.entry, id, scrollIntoView() {} } as unknown as HTMLElement;
+      if (slug && (b.slugs ?? []).includes(slug)) return { entry: b.entry, slug, scrollIntoView() {} } as unknown as HTMLElement;
+      return null;
+    },
+  });
+  const scopes = bodies.map(scopeFor);
+  return {
+    querySelectorAll: (sel: string) => (sel === '[data-entry]' ? scopes : []),
+    // The no-marker fallback searches the whole document.
+    querySelector: (sel: string) => {
+      for (const s of scopes) {
+        const hit = s.querySelector(sel);
+        if (hit) return hit;
+      }
+      return null;
+    },
+  } as unknown as Document;
+}
+
+describe('fragmentOf', () => {
+  it('strips the leading hash', () => {
+    expect(fragmentOf('#sec-8-9')).toBe('sec-8-9');
+    expect(fragmentOf('sec-8-9')).toBe('sec-8-9');
+  });
+
+  it('drops the local dev provider locator glued onto the fragment', () => {
+    // `immediately.run dev` puts `#ir-endpoint=…&ir-token=…` on the URL, so a fragment can
+    // arrive with the locator attached. Taking the whole string would look for an id
+    // called `sec-4#ir-endpoint=…` and silently never scroll.
+    expect(fragmentOf('#sec-4#ir-endpoint=http%3A%2F%2F127.0.0.1%3A7700&ir-token=abc')).toBe('sec-4');
+    expect(fragmentOf('#sec-4&ir-token=abc')).toBe('sec-4');
+  });
+
+  it('is empty for no hash', () => {
+    expect(fragmentOf('')).toBe('');
+    expect(fragmentOf(undefined)).toBe('');
+  });
+});
+
+describe('resolveFragmentTarget — the stale-document guard (R3-249)', () => {
+  const OUTGOING = '/app/content/specs/PERSISTENCE_SPEC.mdx';
+  const INCOMING = '/app/content/context/core_concepts.mdx';
+
+  it('refuses to resolve while the PREVIOUS entry is still the one rendered', () => {
+    // Both documents have a `sec-4` — the whole reason the bug exists. Asking for the
+    // incoming entry's section while the outgoing body is on screen must yield nothing,
+    // so the caller waits instead of scrolling to the wrong page's section.
+    const doc = makeDoc([{ entry: OUTGOING, ids: ['sec-1', 'sec-4', 'sec-8'] }]);
+    expect(resolveFragmentTarget(doc, INCOMING, 'sec-4')).toBeNull();
+  });
+
+  it('resolves once the incoming entry is the one rendered', () => {
+    const doc = makeDoc([{ entry: INCOMING, ids: ['sec-1', 'sec-4'] }]);
+    expect(resolveFragmentTarget(doc, INCOMING, 'sec-4')).not.toBeNull();
+  });
+
+  it('picks the section from the CURRENT entry when both bodies are in the DOM', () => {
+    // The transition window: the outgoing body has not unmounted yet.
+    const doc = makeDoc([
+      { entry: OUTGOING, ids: ['sec-4'] },
+      { entry: INCOMING, ids: ['sec-4'] },
+    ]);
+    const el = resolveFragmentTarget(doc, INCOMING, 'sec-4') as unknown as { entry: string };
+    expect(el?.entry).toBe(INCOMING);
+  });
+
+  it('accepts a numbered heading by its prose slug too', () => {
+    const doc = makeDoc([{ entry: INCOMING, ids: ['sec-4'], slugs: ['4-principal'] }]);
+    expect(resolveFragmentTarget(doc, INCOMING, '4-principal')).not.toBeNull();
+  });
+
+  it('returns null for an unknown fragment, and for an empty one', () => {
+    const doc = makeDoc([{ entry: INCOMING, ids: ['sec-4'] }]);
+    expect(resolveFragmentTarget(doc, INCOMING, 'sec-99')).toBeNull();
+    expect(resolveFragmentTarget(doc, INCOMING, '')).toBeNull();
+  });
+});

package/src/lib/fragment.ts

@@ -0,0 +1,55 @@
+// Deep-link fragment resolution — pure helpers, no React (the Fast-Refresh rule).
+//
+// The problem these solve is specific to a corpus whose documents share section ids. Every
+// spec numbers its sections from 1, so `#sec-4` exists in almost every entry. A scroll
+// fired when navigation *starts* therefore finds a perfectly good `#sec-4` — belonging to
+// the document the reader is leaving — scrolls to it, reports success, and is then undone
+// when the incoming entry renders. The reader lands at the top of the right page.
+//
+// The fix is to refuse to scroll until the element found belongs to the entry that is
+// actually on screen, which the `data-entry` marker inside the suspended body makes
+// checkable (see `SafeEntryBody`).
+
+/** The fragment the current navigation is asking for, without its `#`. */
+export function fragmentOf(hash: string | undefined | null): string {
+  if (!hash) return '';
+  const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+  // The local dev provider appends its own `#ir-endpoint=…&ir-token=…` locator, so a
+  // fragment can arrive with the locator glued onto it. Take the leading component.
+  return raw.split(/[#&]/)[0].trim();
+}
+
+/**
+ * The element a fragment names, but only once the body on screen is the one being asked
+ * about. Returns null while the previous entry is still rendered, which is the signal to
+ * wait rather than to scroll.
+ *
+ * Falls back to the whole document when no marked body is present — the compiled
+ * (`<Include>`) path does not carry the marker, and scrolling imperfectly there is better
+ * than not at all.
+ */
+export function resolveFragmentTarget(doc: Document, entryKey: string, frag: string): HTMLElement | null {
+  if (!frag) return null;
+  // Compare the attribute VALUE rather than selecting on it. An entry key is a path
+  // (`/app/content/context/core_concepts.mdx`), and getting it through a CSS attribute
+  // selector means trusting `CSS.escape` and the selector parser to agree about slashes
+  // and dots — a silent no-match if they do not. Reading the attribute and comparing
+  // strings has no such failure mode, and there are only a handful of marked bodies.
+  const marked = Array.from(doc.querySelectorAll<HTMLElement>('[data-entry]'));
+  const scope: ParentNode | null = marked.find((n) => n.getAttribute('data-entry') === entryKey) ?? null;
+  // No marked body at all: the compiled (`<Include>`) path does not carry the marker, so
+  // fall back to the document. A marked body for a DIFFERENT entry means the previous
+  // document is still on screen — return null and wait, rather than scroll the wrong page.
+  const root: ParentNode | null = scope ?? (marked.length === 0 ? doc : null);
+  if (!root) return null;
+  const byId = root.querySelector<HTMLElement>(`[id="${cssEscape(frag)}"]`);
+  if (byId) return byId;
+  // A numbered heading also carries its prose slug, which is a valid landing hook.
+  return root.querySelector<HTMLElement>(`[data-slug="${cssEscape(frag)}"]`);
+}
+
+/** `CSS.escape`, with a conservative fallback for the characters ids here can contain. */
+function cssEscape(value: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(value);
+  return value.replace(/["\\]/g, '\\$&');
+}

package/src/lib/frontmatter.ts

@@ -0,0 +1,26 @@
+// Frontmatter parsing for the viewer-side corpus scan (R3-265).
+//
+// IMPORTED, not ported, since R3-277a. This file used to carry a documented port of
+// the docs repo's `scripts/lib/wiki.mjs` parser — the one that has read the whole
+// docs corpus for the generator and the conformance checker. The port was faithful,
+// and that was the problem: the two agreed because someone kept them agreeing, and
+// nothing would have reported the day that stopped. A viewer that parses frontmatter
+// differently from the tooling that validates it renders a corpus the gate says is
+// fine and the reader says is broken.
+//
+// The canon is `@immediately-run/mdx-plugins` — the package that already owns the
+// slug grammar (R3-277), so a consumer gets both halves of the corpus contract from
+// one place at one version.
+//
+// Why a parser at all, rather than the bundler's metadata: under DISPATCH the corpus
+// is a mount, and the bundler only scans the app's own source. Nothing else has read
+// these bytes.
+//
+// The re-export keeps every import site in this repo unchanged. `Frontmatter` is
+// re-exported under its local name — the viewer's own code says `Frontmatter`, and
+// renaming it across the repo would be churn for no reader's benefit.
+export { parseFrontmatter } from '@immediately-run/mdx-plugins';
+export type {
+  FrontmatterValue,
+  ParsedFrontmatter as Frontmatter,
+} from '@immediately-run/mdx-plugins';

package/src/lib/layout.ts

@@ -0,0 +1,84 @@
+// Layout resolution — the "outlet chain" for a content entry. Pure helpers (no
+// React), so the same rules drive rendering and any future manifest/validation.
+//
+// A LAYOUT is an MDX file (`…/_layout.mdx`) that renders shared chrome — nav,
+// section hero, footer — around an `<Outlet/>` where the page (or an inner
+// layout) renders. This is Grove's answer to React Router's nested layout
+// routes: the URL always names the *leaf content file*, and the layout chain is
+// resolved *around* it at render time, invisible to routing.
+//
+// Association is FOLDER CONVENTION, nested up the namespace: a `_layout.mdx` in a
+// directory wraps every entry in that subtree, and directories nest
+// (`content/_layout.mdx` wraps `content/people/_layout.mdx` wraps the page).
+// The `frame` frontmatter key OVERRIDES the convention on a per-entry basis; the
+// existing `layout` field (the CSS `data-layout` variant) is unrelated and
+// untouched.
+import { contentDir, slugToKey, isLayoutKey } from './content';
+
+/** The `_layout.mdx` key for a directory key (which ends in `/`). */
+function layoutKeyForDir(dir: string): string {
+  return dir + '_layout.mdx';
+}
+
+/** Does an entry/layout opt out of an inherited layout chain? `frame: none`
+ *  (or `frame: false`) means "render me bare / stop inheritance above here". */
+function optsOut(meta: Record<string, unknown> | undefined): boolean {
+  const f = meta?.frame;
+  return f === 'none' || f === false;
+}
+
+/**
+ * Resolve the ordered chain of layout files that wrap `entryKey`, **outermost
+ * first** (root → nearest). The caller nests them so the last one is closest to
+ * the page and the page renders at the innermost `<Outlet/>`.
+ *
+ * Rules, in precedence order:
+ *   1. `frame: none` / `frame: false` on the entry → `[]` (render bare, no chrome).
+ *   2. `frame: '<slug>'` on the entry → exactly that one layout, if it exists.
+ *   3. Otherwise folder convention: every `_layout.mdx` from the content root down to
+ *      the entry's own directory that exists in `allKeys`. A `_layout.mdx` whose
+ *      own frontmatter opts out (`frame: none`) becomes a new root — layouts above
+ *      it are dropped.
+ *
+ * Layout files never wrap themselves (a `_layout.mdx` gets no layout chain).
+ */
+export function layoutChainForKey(
+  entryKey: string,
+  filesMetadata: Record<string, Record<string, unknown> | undefined>,
+): string[] {
+  if (isLayoutKey(entryKey)) return [];
+
+  const allKeys = Object.keys(filesMetadata);
+  const metaOf = (key: string) => filesMetadata[key];
+  const entryMeta = metaOf(entryKey);
+  if (optsOut(entryMeta)) return [];
+
+  const explicit = entryMeta?.frame;
+  if (typeof explicit === 'string' && explicit && explicit !== 'none') {
+    const key = slugToKey(explicit);
+    return allKeys.includes(key) ? [key] : [];
+  }
+
+  const present = new Set(allKeys.filter(isLayoutKey));
+  const root = contentDir();
+  if (!entryKey.startsWith(root)) return [];
+
+  // Directories from the content root down to (but not including) the entry file.
+  const rel = entryKey.slice(root.length); // e.g. "people/ada.mdx"
+  const segs = rel.split('/').slice(0, -1); // e.g. ["people"]
+  const dirs = [root];
+  let dir = root;
+  for (const s of segs) {
+    dir = dir + s + '/';
+    dirs.push(dir);
+  }
+
+  const chain: string[] = [];
+  for (const d of dirs) {
+    const lk = layoutKeyForDir(d);
+    if (!present.has(lk)) continue;
+    if (optsOut(metaOf(lk))) chain.length = 0; // this layout is a new root
+    chain.push(lk);
+  }
+  return chain;
+}