astro-dev-edit 0.11.0

package/src/patcher/registry.ts

@@ -0,0 +1,11 @@
+import { astroPatcher } from './astro.ts';
+import type { Patcher } from './types.ts';
+
+/** Every available patcher. A future markdown/MDX patcher is added here. */
+const patchers: readonly Patcher[] = [astroPatcher];
+
+/** The patcher registered for a file extension (lowercased, with the dot),
+ *  or undefined when in-place editing of that type isn't supported. */
+export function patcherFor(ext: string): Patcher | undefined {
+  return patchers.find((p) => p.extensions.includes(ext));
+}

package/src/patcher/types.ts

@@ -0,0 +1,32 @@
+import type { ClassifyResult, RefusalCode, TargetType } from '../shared/protocol.ts';
+
+/**
+ * The interface every source patcher implements. Patchers are pure
+ * string-in/string-out — no fs access; the middleware reads and writes files.
+ * Adding support for a new file type = one implementation + one entry in
+ * registry.ts.
+ */
+export interface Patcher {
+  /** Lowercased extensions this patcher handles, with the dot: ['.astro']. */
+  extensions: readonly string[];
+  /** Classify the element at a source location (AST truth). */
+  classify(source: string, req: { loc: string; tag: string }): Promise<ClassifyResult>;
+  /** Verify-then-patch. Never writes; returns the new source or a refusal. */
+  apply(source: string, req: PatchRequest): Promise<ApplyResult>;
+}
+
+export interface PatchRequest {
+  /** "line:col" from data-astro-source-loc. */
+  loc: string;
+  /** Lowercased tag name of the clicked element. */
+  tag: string;
+  targetType: TargetType;
+  /** Rendered text / attr value the client saw. */
+  original: string;
+  newText: string;
+}
+
+/** Server-internal result — `newSource` never crosses the wire. */
+export type ApplyResult =
+  | { ok: true; newSource: string }
+  | { ok: false; code: RefusalCode; error: string };

package/src/server/annotate.ts

@@ -0,0 +1,173 @@
+import { parse } from '@astrojs/compiler';
+import type { Plugin as VitePlugin } from 'vite';
+
+/**
+ * Self-annotation for Astro ≥7 — inject `data-astro-source-file` / `-loc`
+ * ourselves when Astro's compiler no longer does.
+ *
+ * Astro 5/6 (WASM Go compiler) annotate every element in dev when the toolbar
+ * is on; the whole feature rides on those attributes. Astro 7's Rust compiler
+ * (@astrojs/compiler-rs) accepts the `annotateSourceFile` flag but emits
+ * nothing (withastro/compiler-rs#96). So on 7 we run a
+ * Vite `enforce: 'pre'` transform that annotates the raw `.astro` source
+ * BEFORE Astro's compiler sees it.
+ *
+ * The critical invariant: injected locs are computed from the ORIGINAL source,
+ * so they reference on-disk coordinates — the patcher resolves them against
+ * the on-disk file (`src/patcher/astro.ts`) and needs no changes. Injection
+ * adds no newlines, so line numbers stay true end to end; only columns shift
+ * in the compiled output (dev-only, cosmetic).
+ *
+ * Loc rules mirror the compiler's, as documented in `src/patcher/astro.ts`
+ * and pinned by `tests/helpers.ts::locOf`:
+ * - text first child → its own start;
+ * - element/expression first child → its start + 1 column (the tag name /
+ *   the `{` — the compiler reports an expression's start one char before it);
+ * - childless element → the element's own start + 1 column (its tag name).
+ * Empirically verified: this walker reproduces Astro 6.4.8's own annotations
+ * for the whole playground exactly (205/205 served attributes).
+ *
+ * Pure string-in/string-out like the patchers — no fs here.
+ */
+
+interface Pos {
+  line: number;
+  column: number;
+}
+interface AstNode {
+  type: string;
+  name?: string;
+  position?: { start: Pos; end?: Pos };
+  children?: AstNode[];
+}
+
+// (line, column) → JS string index; same math as src/patcher/astro.ts, which
+// verified the compiler's columns are UTF-16 units, i.e. JS string indexing.
+function lineStartIndices(source: string): number[] {
+  const starts = [0];
+  for (let i = 0; i < source.length; i++) {
+    if (source[i] === '\n') starts.push(i + 1);
+  }
+  return starts;
+}
+
+function indexOfPos(starts: number[], pos: Pos): number {
+  const lineStart = starts[pos.line - 1];
+  if (lineStart === undefined) return -1;
+  return lineStart + pos.column - 1;
+}
+
+function bump(pos: Pos): Pos {
+  return { line: pos.line, column: pos.column + 1 };
+}
+
+/** The loc the compiler would have stamped for this element. */
+function locForElement(node: AstNode): Pos | null {
+  const first = (node.children ?? []).find((k) => k.position);
+  if (!first) return node.position ? bump(node.position.start) : null;
+  if (first.type === 'text') return first.position!.start;
+  return bump(first.position!.start);
+}
+
+/**
+ * Tags that must never be stamped. Astro treats a `<script>` or `<style>`
+ * carrying an attribute it does not recognise as `is:inline` — no bundling,
+ * no TypeScript, no import resolution, no `type="module"` — which breaks
+ * every script on the page (its own `ClientRouter` included). Neither is an
+ * editable element, so nothing in the editing surface is lost.
+ */
+const NEVER_ANNOTATE = new Set(['script', 'style']);
+
+/** Plain lowercase HTML elements only — components/fragments are never
+ *  annotated (matches compiler behavior; the client walks up via
+ *  nearestSource anyway), nor is anything in NEVER_ANNOTATE. */
+function isAnnotatable(node: AstNode): boolean {
+  return (
+    node.type === 'element' &&
+    !!node.name &&
+    /^[a-z]/.test(node.name) &&
+    !NEVER_ANNOTATE.has(node.name)
+  );
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+}
+
+interface Insertion {
+  index: number;
+  text: string;
+}
+
+/**
+ * Annotate every plain element in an `.astro` source with the
+ * `data-astro-source-*` attributes Astro 5/6 would have emitted.
+ * `file` is the absolute path stamped into the attribute (what the Vite
+ * transform receives as its module id).
+ */
+export async function annotateAstroSource(source: string, file: string): Promise<string> {
+  const { ast } = await parse(source, { position: true });
+  const starts = lineStartIndices(source);
+  const insertions: Insertion[] = [];
+  const fileAttr = escapeAttr(file);
+
+  const walk = (node: AstNode): void => {
+    if (isAnnotatable(node) && node.position) {
+      const loc = locForElement(node);
+      // Insertion point: right after `<tagname`, before any existing
+      // attributes — so expression attributes / spreads are never touched.
+      const tagStart = indexOfPos(starts, node.position.start);
+      if (loc && tagStart >= 0) {
+        insertions.push({
+          index: tagStart + 1 + node.name!.length,
+          text:
+            ` data-astro-source-file="${fileAttr}"` +
+            ` data-astro-source-loc="${loc.line}:${loc.column}"`,
+        });
+      }
+    }
+    for (const child of node.children ?? []) walk(child);
+  };
+  walk(ast as unknown as AstNode);
+
+  if (insertions.length === 0) return source;
+  insertions.sort((a, b) => a.index - b.index);
+  // Build with a parts array + single join, not `out += …` in the loop: the
+  // latter recopies a growing string per insertion (O(k²) over the output).
+  // A `.map()` loop lives in source once, so real files have few insertions —
+  // but a large hand-written template shouldn't degrade.
+  const parts: string[] = [];
+  let cursor = 0;
+  for (const ins of insertions) {
+    parts.push(source.slice(cursor, ins.index), ins.text);
+    cursor = ins.index;
+  }
+  parts.push(source.slice(cursor));
+  return parts.join('');
+}
+
+/**
+ * The dev-only Vite plugin. Ordering matters twice over: Astro's `astro:build`
+ * plugin is itself `enforce: 'pre'` and compiles main `.astro` modules in a
+ * plain `transform` handler — and integration-injected plugins land AFTER it
+ * in the resolved array, so plugin-level `enforce` alone is not enough (the
+ * transform would receive compiled JS, not source). Hook-level
+ * `order: 'pre'` is the decisive lever: Vite runs order-'pre' transform
+ * handlers before all plain handlers regardless of array position, so the
+ * compiler (WASM or Rust) receives the already-annotated source. Only the
+ * main module is transformed — style/script sub-requests carry a
+ * `?astro&type=…` query and no longer end in `.astro`.
+ */
+export function createAnnotatePlugin(): VitePlugin {
+  return {
+    name: 'astro-dev-edit:annotate',
+    enforce: 'pre',
+    transform: {
+      order: 'pre',
+      async handler(code, id) {
+        if (!id.endsWith('.astro')) return null;
+        return { code: await annotateAstroSource(code, id), map: null };
+      },
+    },
+  };
+}

package/src/server/assets.ts

@@ -0,0 +1,167 @@
+import { mkdir, readdir, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import type { AssetInfo, UploadRequest } from '../shared/protocol.ts';
+import { insideRoot, isServableAsset, toWebPath } from './paths.ts';
+
+/**
+ * Asset handling: read-only image listing for the swap panel, and image
+ * uploads. Uploads write NEW files into a configured asset dir — never a
+ * source-file patch. (spec §6.3, §11)
+ */
+
+export const IMAGE_EXT = new Set(['.jpg', '.jpeg', '.png', '.webp', '.avif', '.gif', '.svg']);
+
+const EXT_BY_MIME: Record<string, string> = {
+  'image/jpeg': '.jpg',
+  'image/png': '.png',
+  'image/webp': '.webp',
+  'image/avif': '.avif',
+  'image/gif': '.gif',
+  'image/svg+xml': '.svg',
+};
+
+async function walk(dir: string): Promise<string[]> {
+  const found: string[] = [];
+  const items = await readdir(dir, { withFileTypes: true });
+  for (const item of items) {
+    const full = join(dir, item.name);
+    if (item.isDirectory()) found.push(...(await walk(full)));
+    else if (item.isFile()) found.push(full);
+  }
+  return found;
+}
+
+/** List image files under the configured asset dirs, as the paths they are
+ *  served at, with size, mtime and whether a *build* will still serve them.
+ *  Read-only. Every directory is confined to the project root. Sorted by path;
+ *  the client re-sorts (by recency, by default). (spec §6.3, §8)
+ *
+ *  `assetDirs` deliberately spans both worlds — `src/assets` has to be listed
+ *  for `image()` fields — so servability is carried per file rather than left
+ *  for each picker to infer from the path. (issue #9) */
+export async function listAssets(
+  root: string,
+  assetDirs: string[],
+  publicDir = 'public',
+): Promise<AssetInfo[]> {
+  // A Map because asset dirs may nest (e.g. public/photos inside public), so
+  // the same file can be reached twice — keyed by web path, first one wins.
+  const out = new Map<string, AssetInfo>();
+  for (const dir of assetDirs) {
+    const abs = resolve(root, dir);
+    // Refuse anything that escaped the root (e.g. via `..`). (spec §8)
+    if (!insideRoot(root, abs)) continue;
+    let entries: string[];
+    try {
+      entries = await walk(abs);
+    } catch {
+      continue; // dir may not exist; skip quietly
+    }
+    for (const file of entries) {
+      const ext = file.slice(file.lastIndexOf('.')).toLowerCase();
+      if (!IMAGE_EXT.has(ext)) continue;
+      const path = toWebPath(root, file, publicDir);
+      if (out.has(path)) continue;
+      // Statted after the extension filter, so non-images cost nothing. A file
+      // deleted between the readdir and the stat is simply left out.
+      try {
+        const info = await stat(file);
+        out.set(path, {
+          path,
+          size: info.size,
+          mtime: info.mtimeMs,
+          servable: isServableAsset(root, file, publicDir),
+        });
+      } catch {
+        continue;
+      }
+    }
+  }
+  return [...out.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+/** The mime type of a data: URL without decoding its payload — for policy
+ *  checks that must not pay for a base64 decode of the whole image. Empty
+ *  string when the value isn't a data URL. */
+export function dataUrlMime(dataUrl: string): string {
+  return /^data:([^;,]+)/.exec(dataUrl ?? '')?.[1]?.toLowerCase() ?? '';
+}
+
+/** Split a data: URL into its mime type and decoded bytes. Throws on
+ *  anything that isn't a data URL. */
+export function parseDataUrl(dataUrl: string): { mime: string; data: Buffer } {
+  const m = /^data:([^;,]+)(;base64)?,(.*)$/s.exec(dataUrl ?? '');
+  if (!m) throw new Error('expected a data: URL');
+  const mime = m[1].toLowerCase();
+  const data = m[2] ? Buffer.from(m[3], 'base64') : Buffer.from(decodeURIComponent(m[3]));
+  return { mime, data };
+}
+
+/** Sanitise a user-supplied filename to a safe basename with an allowed ext. */
+export function safeFileName(name: string, fallbackExt: string): string {
+  const base = basename(name).replace(/[^a-zA-Z0-9._-]/g, '-').replace(/^-+/, '');
+  let ext = extname(base).toLowerCase();
+  let stem = base.slice(0, base.length - ext.length) || 'image';
+  if (!IMAGE_EXT.has(ext)) ext = fallbackExt;
+  return `${stem}${ext}`;
+}
+
+/**
+ * Write image bytes into the configured upload directory. The destination is
+ * confined to the upload dir inside the project root, the mime must be an
+ * allowed image type, and the name is sanitised. On a name clash a numeric
+ * suffix is added rather than overwriting. Returns the web-servable path and
+ * the name actually written. (safe: writes a NEW asset file, never patches
+ * source)
+ *
+ * Bytes-in rather than data-URL-in because not every caller has a data URL:
+ * `/unsplash/import` downloads a response body, and synthesising a data URL
+ * from it would mean a ~33% larger base64 string and a decode straight back to
+ * the Buffer we started with.
+ */
+export async function saveBuffer(
+  root: string,
+  uploadDir: string,
+  file: { mime: string; data: Buffer; filename: string },
+  publicDir = 'public',
+): Promise<{ webPath: string; filename: string }> {
+  const fallbackExt = EXT_BY_MIME[file.mime];
+  if (!fallbackExt) throw new Error(`unsupported image type: ${file.mime}`);
+
+  // Uploads land in the configured upload dir, confined to the project root.
+  const dir = resolve(root, uploadDir);
+  if (!insideRoot(root, dir)) throw new Error('upload directory escapes the project root');
+
+  const fileName = safeFileName(file.filename || 'upload', fallbackExt);
+  let target = join(dir, fileName);
+  // Confirm the resolved target is still inside the asset dir. (spec §8)
+  if (!insideRoot(dir, target)) throw new Error('path escapes asset dir');
+
+  // Avoid clobbering an existing file.
+  const stem = fileName.slice(0, fileName.length - extname(fileName).length);
+  const ext = extname(fileName);
+  let n = 1;
+  const existing = new Set(await walk(dir).catch(() => []));
+  while (existing.has(target)) {
+    target = join(dir, `${stem}-${n++}${ext}`);
+  }
+
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, file.data);
+
+  return { webPath: toWebPath(root, target, publicDir), filename: basename(target) };
+}
+
+/**
+ * Write an uploaded image into the configured upload directory. Accepts a
+ * data-URL; everything past the decode is {@link saveBuffer}.
+ */
+export async function saveUpload(
+  root: string,
+  uploadDir: string,
+  payload: UploadRequest,
+  publicDir = 'public',
+): Promise<{ webPath: string }> {
+  const { mime, data } = parseDataUrl(payload.dataUrl);
+  return saveBuffer(root, uploadDir, { mime, data, filename: payload.filename }, publicDir);
+}

package/src/server/collection-entries.ts

@@ -0,0 +1,91 @@
+import { readdir } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import { insideRoot } from './paths.ts';
+
+/**
+ * Finding a collection's entry files on disk — the one piece of knowledge the
+ * Items listing and the entry resolver both need.
+ *
+ * It lived inside the `/collection/entries` handler until `/entry/resolve`
+ * needed the same walk. Two copies of "which files are this collection's
+ * entries" is exactly the drift that makes a resolver point at a file the
+ * listing never shows, so it is one module with one answer.
+ *
+ * Impure only in `readdir` (injected, so tests stay pure) and confined by
+ * {@link inContentRoots} before it is ever called.
+ */
+
+/** Cap on one listing. Each entry can cost a stat and a frontmatter parse
+ *  downstream, so a pathological directory can't turn a panel open into a long
+ *  scan. Exceeding it is reported, never hidden. */
+export const MAX_ENTRIES_LISTED = 500;
+
+/** Injected directory walk; defaults to a recursive `readdir`. */
+export type ReadDirRecursive = (dirAbs: string) => Promise<string[]>;
+
+const defaultReadDir: ReadDirRecursive = async (dirAbs) =>
+  (await readdir(dirAbs, { recursive: true })).map(String);
+
+/**
+ * Whether a directory is inside the configured content roots.
+ *
+ * `insideRoot` alone is not enough: it answers "under the project", while
+ * `contentRoots` is the narrower gate the user controls. Both are asked, in
+ * that order, exactly as `/collection/entries` has always asked them.
+ */
+export function inContentRoots(root: string, dirAbs: string, contentRoots: string[]): boolean {
+  if (!insideRoot(root, dirAbs)) return false;
+  const rel = relative(root, dirAbs);
+  return contentRoots.some(
+    (cr) => rel === cr || rel.startsWith(cr.endsWith(sep) ? cr : cr + sep),
+  );
+}
+
+export interface EntryListing {
+  /** Directory-relative, forward-slashed file names, sorted. */
+  names: string[];
+  /** True when the directory held more than {@link MAX_ENTRIES_LISTED}. */
+  truncated: boolean;
+}
+
+/**
+ * A collection directory's entry files, capped and sorted.
+ *
+ * A missing or unreadable directory is an empty listing, not a throw: a
+ * collection declared in the config without its directory yet is a real and
+ * common state, and neither caller has anything better to say about it.
+ */
+export async function listEntryFiles(
+  dirAbs: string,
+  extensions: readonly string[],
+  readDir: ReadDirRecursive = defaultReadDir,
+): Promise<EntryListing> {
+  let all: string[];
+  try {
+    all = await readDir(dirAbs);
+  } catch {
+    return { names: [], truncated: false };
+  }
+  const names = all
+    .map((f) => f.split(sep).join('/'))
+    .filter((f) => extensions.some((e) => f.toLowerCase().endsWith(e)))
+    .sort();
+  return { names: names.slice(0, MAX_ENTRIES_LISTED), truncated: names.length > MAX_ENTRIES_LISTED };
+}
+
+/**
+ * A directory-relative entry file name as its **entry id**.
+ *
+ * For a glob loader based at the collection directory this is precisely Astro's
+ * own id — the posix path minus the extension, nested directories included — so
+ * `2026/hello.md` is `2026/hello`, and a detail URL's tail can be matched
+ * against it directly. That equivalence is what `/entry/resolve` rests on.
+ */
+export function entryId(name: string): string {
+  return name.replace(/\.[^./]+$/, '');
+}
+
+/** Absolute path of a collection's directory, repo-relative `dir` in hand. */
+export function collectionDirAbs(root: string, dir: string): string {
+  return resolve(root, dir);
+}

package/src/server/content-config.ts

@@ -0,0 +1,210 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ViteDevServer } from 'vite';
+import type { FieldOverride } from '../shared/protocol.ts';
+import { IMAGE_STUB_DESCRIPTION } from './schema-introspect.ts';
+
+/**
+ * Resolves "which collection backs this file, and what is its zod schema?" by
+ * loading the project's own content config through the dev server's module
+ * pipeline. Impure by design and injected into the middleware, so tests can
+ * stub it. Every failure path returns null — the entry panel then falls back
+ * to value-based field inference instead of erroring.
+ */
+
+/** The editor half of a field — widget, label, hidden. Defined in `protocol.ts`
+ *  because the collection designer now reads and writes it over the wire; this
+ *  alias keeps the option-facing name the config documents. */
+export type EntryFieldOverride = FieldOverride;
+
+export interface EntryEditorOptions {
+  /** Repo-relative path to the content config; auto-detected when omitted. */
+  configPath?: string;
+  collections?: Record<
+    string,
+    {
+      /** Repo-relative collection dir; defaults to src/content/<name>. */
+      dir?: string;
+      /** Extension for entries created via the panel. When omitted it is
+       *  inferred from the collection's existing entries (falling back to .md). */
+      extension?: '.md' | '.mdx';
+      /**
+       * Offer the entry drawer on this collection's detail pages. Off by
+       * default: switching it on — from the Collections panel, or here — is
+       * what replaces hand-emitting the `astro-dev-edit:page-source` meta tag.
+       * Setting it here locks the panel's switch, like any other config value.
+       */
+      pageEditing?: boolean;
+      fields?: Record<string, EntryFieldOverride>;
+    }
+  >;
+}
+
+export interface EntryCollectionInfo {
+  collection: string;
+  /** Repo-relative directory holding the collection's entries. */
+  dir: string;
+  /** The collection's zod object schema, or null when not resolvable. */
+  schema: unknown;
+  /** Configured extension for new entries; when absent the create route
+   *  infers one from the collection's existing entries. */
+  extension?: '.md' | '.mdx';
+  /** Whether this collection's detail pages offer the entry drawer — the
+   *  effective value, config over stored. Absent reads as off, so a caller that
+   *  knows nothing about the switch (a test stub) leaves it off. */
+  pageEditing?: boolean;
+  fieldConfig: Record<string, EntryFieldOverride>;
+}
+
+export interface EntrySchemaProvider {
+  /** Info for a repo-relative entry file path, or null when unmapped. */
+  forFile(relFile: string): Promise<EntryCollectionInfo | null>;
+  /** Info for a collection by name (create flow), or null when unknown. */
+  forCollection(name: string): Promise<EntryCollectionInfo | null>;
+  /**
+   * Every collection the project declares, in config order, plus any configured
+   * explicitly in `entryEditor.collections`. Empty when no content config
+   * resolved — the collections panel then says so rather than showing nothing.
+   */
+  listCollections(): Promise<EntryCollectionInfo[]>;
+  /**
+   * Repo-relative path of the content config this provider reads, or null when
+   * none exists. The collection designer patches **this** path and never one the
+   * client supplies, which is what keeps a schema write confined.
+   */
+  configPath(): Promise<string | null>;
+}
+
+const CONFIG_CANDIDATES = [
+  'src/content.config.ts',
+  'src/content.config.mts',
+  'src/content.config.js',
+  'src/content.config.mjs',
+  'src/content/config.ts',
+  'src/content/config.mts',
+  'src/content/config.js',
+  'src/content/config.mjs',
+];
+
+export function createSchemaProvider(
+  server: ViteDevServer,
+  root: string,
+  /**
+   * The entry-editor options, **as a thunk**. Collection dirs and per-field
+   * widget overrides can now come from the Settings panel as well as from
+   * `astro.config.mjs`, so reading them once at construction would freeze the
+   * panel's changes out until the next dev-server restart.
+   */
+  readOptions: () => Promise<EntryEditorOptions>,
+): EntrySchemaProvider {
+  function collectionDir(explicit: Explicit, name: string): string {
+    return normalizeDir(explicit[name]?.dir ?? `src/content/${name}`);
+  }
+
+  /** The content config that exists on disk, repo-relative; null when none does.
+   *  Server-side discovery only — a configured path or the conventional
+   *  candidates, never anything a request names. */
+  function findConfig(configPath: string | undefined): string | null {
+    const candidates = configPath ? [configPath] : CONFIG_CANDIDATES;
+    return candidates.find((c) => existsSync(join(root, c))) ?? null;
+  }
+
+  /** Load `collections` from the project's content config; null on any failure.
+   *  ssrLoadModule is cached by Vite and invalidated when the config changes,
+   *  so calling per-request stays cheap and always fresh. */
+  async function loadCollections(
+    configPath: string | undefined,
+  ): Promise<Record<string, { schema?: unknown }> | null> {
+    try {
+      const rel = findConfig(configPath);
+      if (!rel) return null;
+      const mod = (await server.ssrLoadModule('/' + rel.replace(/\\/g, '/'))) as {
+        collections?: Record<string, { schema?: unknown }>;
+      };
+      const collections = mod.collections;
+      return collections && typeof collections === 'object' ? collections : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** A schema may be a function of a context ({ image }) — call it with a stub
+   *  whose image() is a plain string schema from the project's own zod, tagged
+   *  so the introspector renders it as an image field. */
+  async function resolveSchema(schema: unknown): Promise<unknown> {
+    if (typeof schema !== 'function') return schema ?? null;
+    try {
+      const zmod = (await server.ssrLoadModule('astro/zod')) as {
+        z?: { string(): { describe(d: string): unknown } };
+      };
+      const z = zmod.z;
+      if (!z) return null;
+      const image = () => z.string().describe(IMAGE_STUB_DESCRIPTION);
+      return (schema as (ctx: { image: typeof image }) => unknown)({ image });
+    } catch {
+      return null;
+    }
+  }
+
+  async function info(name: string): Promise<EntryCollectionInfo | null> {
+    const options = await readOptions();
+    const explicit = options.collections ?? {};
+    const collections = await loadCollections(options.configPath);
+    const entry = collections?.[name];
+    // A collection configured explicitly is usable even without a config module
+    // (dir + overrides still apply; fields fall back to inference).
+    if (!entry && !explicit[name]) return null;
+    return {
+      collection: name,
+      dir: collectionDir(explicit, name),
+      schema: entry ? await resolveSchema(entry.schema) : null,
+      extension: explicit[name]?.extension,
+      pageEditing: explicit[name]?.pageEditing === true,
+      fieldConfig: explicit[name]?.fields ?? {},
+    };
+  }
+
+  return {
+    async forCollection(name) {
+      return info(name);
+    },
+
+    async listCollections() {
+      const options = await readOptions();
+      const declared = await loadCollections(options.configPath);
+      const names = new Set([
+        ...Object.keys(declared ?? {}),
+        ...Object.keys(options.collections ?? {}),
+      ]);
+      const out: EntryCollectionInfo[] = [];
+      for (const name of names) {
+        const one = await info(name);
+        if (one) out.push(one);
+      }
+      return out;
+    },
+
+    async configPath() {
+      return findConfig((await readOptions()).configPath);
+    },
+
+    async forFile(relFile) {
+      const options = await readOptions();
+      const explicit = options.collections ?? {};
+      const posix = relFile.replace(/\\/g, '/');
+      // Explicit dirs win, then the src/content/<name>/ convention.
+      for (const name of Object.keys(explicit)) {
+        if (posix.startsWith(collectionDir(explicit, name) + '/')) return info(name);
+      }
+      const m = posix.match(/^src\/content\/([^/]+)\//);
+      return m ? info(m[1]) : null;
+    },
+  };
+}
+
+/** The `collections` map from {@link EntryEditorOptions}, non-optional. */
+type Explicit = NonNullable<EntryEditorOptions['collections']>;
+
+function normalizeDir(dir: string): string {
+  return dir.replace(/\\/g, '/').replace(/\/+$/, '');
+}