@jxsuite/compiler 0.34.1 → 1.0.0

package/src/site/pages-discovery.ts

@@ -3,8 +3,7 @@
  *
  * Scans the pages/ directory and builds a route table mapping URL paths to their source files,
  * layouts, and metadata. `.json` pages are native; any other extension must be claimed by a format
- * class (with the `parse` capability and a "page" document kind) registered from the project's
- * imports map.
+ * class (with the `parse` capability and a "page" document kind) provided by an enabled extension.
  *
  * Conventions (per site-architecture spec §4): pages/index.json → / pages/about.json → /about
  * pages/about/index.json → /about pages/blog/[slug].json → /blog/:slug (dynamic)
@@ -15,9 +14,9 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { parseJxDocument } from "@jxsuite/schema/parse";
 import { extname, join, relative, resolve } from "node:path";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
-import type { JxDocument, JxPathsDef } from "@jxsuite/schema/types";
-import type { ContentLoaderEntry } from "@jxsuite/parser/types";
+import type { JxDocument, JxPathsDef, ProjectConfig } from "@jxsuite/schema/types";
 
 interface Route {
   urlPattern: string; // URL pattern (e.g. "/blog/:slug")
@@ -50,9 +49,9 @@ export async function readPageDocument(
   const entry = registry?.byExtension(ext, "parse");
   if (!entry) {
     throw new Error(
-      `No format class imported for "${ext}" (${filePath}). ` +
-        `Add a format class to project.json imports, e.g. ` +
-        `"Markdown": "@jxsuite/parser/Markdown.class.json".`,
+      `No format class registered for "${ext}" (${filePath}). ` +
+        `Enable an extension providing this format in project.json "extensions", ` +
+        `e.g. "@jxsuite/parser".`,
     );
   }
   return (await entry.call("parse", source)) as JxDocument;
@@ -208,23 +207,25 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
 /**
  * Expand dynamic routes by resolving $paths from each dynamic page.
  *
- * Supports three $paths shapes (per spec §4.3): 1. Content type-based: { contentType: "blog",
- * param: "slug", field: "id" } 2. Explicit values: { values: ["en", "fr"], param: "lang" } 3. Data
- * file ref: { "$ref": "./data/products.json", param: "id", field: "sku" } 4. Legacy array: [{ slug:
- * "hello" }, { slug: "world" }]
+ * Supports these $paths shapes (per spec §4.3): 1. Explicit values: { values: ["en", "fr"], param:
+ * "lang" } 2. Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" } 3.
+ * Legacy array: [{ slug: "hello" }, { slug: "world" }] 4. Extension-discriminated: any object
+ * carrying a key an enabled extension registered as its `resolvePaths` discriminator (e.g. the
+ * parser's { contentType: "blog", param: "slug" }).
  *
  * @param {Route[]} routes - Discovered route table
  * @param {string} projectRoot - Project root for resolving $ref paths
- * @param {Map<string, ContentLoaderEntry[]>} [contentTypes] - Loaded content types (from
- *   content-loader)
- * @param {FormatRegistry} [registry] - Format registry for reading non-JSON dynamic pages
+ * @param {Record<string, unknown>} [sections] - Loaded project sections (projectData results)
+ * @param {ExtensionRegistry} [registry] - Extension registry (formats view reads non-JSON pages)
+ * @param {ProjectConfig} [projectConfig] - Already-loaded project config
  * @returns {Promise<Route[]>} Expanded routes with concrete paths
  */
 export async function expandDynamicRoutes(
   routes: Route[],
   projectRoot: string,
-  contentTypes = new Map<string, ContentLoaderEntry[]>(),
-  registry?: FormatRegistry,
+  sections: Record<string, unknown> = {},
+  registry?: ExtensionRegistry,
+  projectConfig?: ProjectConfig,
 ) {
   const expanded: Route[] = [];
 
@@ -238,7 +239,7 @@ export async function expandDynamicRoutes(
     /** @type {Record<string, unknown>} */
     let raw;
     try {
-      raw = await readPageDocument(route.sourcePath, registry);
+      raw = await readPageDocument(route.sourcePath, registry?.formats);
     } catch {
       expanded.push(route);
       continue;
@@ -249,7 +250,13 @@ export async function expandDynamicRoutes(
       continue;
     }
 
-    const pathEntries = resolvePathEntries(raw.$paths, projectRoot, contentTypes);
+    const pathEntries = await resolvePathEntries(
+      raw.$paths,
+      projectRoot,
+      sections,
+      registry,
+      projectConfig,
+    );
 
     for (const pathEntry of pathEntries) {
       let concreteUrl = route.urlPattern;
@@ -277,67 +284,72 @@ export async function expandDynamicRoutes(
 /**
  * Resolve $paths into an array of param objects.
  *
+ * Core shapes (array / `values` / `$ref`) are handled inline; any other object dispatches through
+ * the extension registry — the first key with a registered `resolvePaths` discriminator routes the
+ * whole $paths value to the owning class, with its section's loaded data as context.
+ *
  * @param {import("@jxsuite/schema/types").JxPathsDef} $paths - The $paths declaration
  * @param {string} projectRoot
- * @param {Map<string, ContentLoaderEntry[]>} contentTypes
- * @returns {Record<string, unknown>[]} Array of { paramName: value } objects
+ * @param {Record<string, unknown>} sections - Loaded project sections keyed by section key
+ * @param {ExtensionRegistry} [registry]
+ * @param {ProjectConfig} [projectConfig]
+ * @returns {Promise<Record<string, unknown>[]>} Array of { paramName: value } objects
  */
-function resolvePathEntries(
+async function resolvePathEntries(
   $paths: JxPathsDef,
   projectRoot: string,
-  contentTypes: Map<string, ContentLoaderEntry[]>,
-): Record<string, unknown>[] {
+  sections: Record<string, unknown>,
+  registry?: ExtensionRegistry,
+  projectConfig?: ProjectConfig,
+): Promise<Record<string, unknown>[]> {
   // Legacy: array of param objects
   if (Array.isArray($paths)) {
     return $paths;
   }
 
-  // Content type-based: { contentType: "blog", param: "slug", field: "id" }
-  if ("contentType" in $paths && $paths.contentType) {
-    const entries = contentTypes.get($paths.contentType);
-    if (!entries || entries.length === 0) {
-      console.warn(
-        `Warning: $paths references content type "${$paths.contentType}" but it has no entries`,
-      );
-      return [];
-    }
-    const param = $paths.param ?? "slug";
-    const field = $paths.field ?? "id";
-    return entries
-      .map((entry: ContentLoaderEntry) => ({
-        [param]: field === "id" ? entry.id : (entry.data[field] ?? entry.id),
-      }))
-      .filter((p: Record<string, unknown>) => p[param]);
-  }
-
   // Explicit values: { values: ["en", "fr"], param: "lang" }
   if ("values" in $paths && Array.isArray($paths.values)) {
-    const param = $paths.param ?? "value";
-    return $paths.values.map((v) => ({ [param]: v }));
+    const param = typeof $paths.param === "string" ? $paths.param : "value";
+    return ($paths.values as unknown[]).map((v) => ({ [param]: v }));
   }
 
   // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
-  if ("$ref" in $paths && $paths.$ref) {
-    const filePath = resolve(projectRoot, $paths.$ref);
+  if ("$ref" in $paths && typeof $paths.$ref === "string" && $paths.$ref) {
+    const refPath = $paths.$ref;
+    const filePath = resolve(projectRoot, refPath);
     let data: unknown;
     try {
       data = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
     } catch (error) {
       const err = error as Error;
-      console.warn(`Warning: $paths.$ref could not load "${$paths.$ref}": ${err.message}`);
+      console.warn(`Warning: $paths.$ref could not load "${refPath}": ${err.message}`);
       return [];
     }
     if (!Array.isArray(data)) {
-      console.warn(`Warning: $paths.$ref "${$paths.$ref}" must be a JSON array`);
+      console.warn(`Warning: $paths.$ref "${refPath}" must be a JSON array`);
       return [];
     }
-    const param = $paths.param ?? "id";
-    const field = $paths.field ?? "id";
+    const param = typeof $paths.param === "string" ? $paths.param : "id";
+    const field = typeof $paths.field === "string" ? $paths.field : "id";
     return (data as Record<string, unknown>[]).map((item: Record<string, unknown>) => ({
       [param]: item[field] ?? item.id ?? String(item),
     }));
   }
 
+  // Extension-discriminated: the first key with a registered resolvePaths discriminator routes
+  // The whole value to the owning class (specs/extensions.md §8).
+  for (const key of Object.keys($paths)) {
+    const entry = registry?.byPathsDiscriminator(key);
+    if (!entry?.project) {
+      continue;
+    }
+    return (await entry.call("resolvePaths", $paths, {
+      data: sections[entry.project.key],
+      projectConfig,
+      root: projectRoot,
+    })) as Record<string, unknown>[];
+  }
+
   console.warn(`Warning: unrecognized $paths shape — skipping`);
   return [];
 }

package/src/site/project-sections.ts

@@ -0,0 +1,48 @@
+/**
+ * Project-sections — generic section orchestration (specs/extensions.md §8, §9)
+ *
+ * Loads every extension-contributed project.json section through the owning class's `projectData`
+ * capability and returns the results keyed by section key. Hosts thread the record through the
+ * build (route expansion, prototype resolution) without knowing any section's shape.
+ */
+
+import { createNodeFormatIO } from "./format-host.ts";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+/**
+ * Load all extension-contributed project sections.
+ *
+ * A section is loaded only when its key is present in the project config: `projectData` on an
+ * absent section would only manufacture empty data (the parser's returns an empty Map), so skipping
+ * keeps `_project` free of keys the author never declared — and is the cheaper rule.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ * @param {ProjectConfig | undefined} projectConfig - Already-loaded project config
+ * @param {ExtensionRegistry} registry - The project's extension registry
+ * @returns {Promise<Record<string, unknown>>} Section key → projectData result
+ */
+export async function loadProjectSections(
+  projectRoot: string,
+  projectConfig: ProjectConfig | undefined,
+  registry: ExtensionRegistry,
+): Promise<Record<string, unknown>> {
+  const sections: Record<string, unknown> = {};
+  const io = createNodeFormatIO(projectRoot);
+  for (const entry of registry.projectContributions()) {
+    const key = entry.project?.key;
+    if (!key || !entry.capabilities.projectData) {
+      continue;
+    }
+    if (!projectConfig || !(key in projectConfig)) {
+      continue;
+    }
+    sections[key] = await entry.call("projectData", projectConfig[key], {
+      io,
+      projectConfig,
+      registry,
+      root: projectRoot,
+    });
+  }
+  return sections;
+}

package/src/site/prototype-resolver.ts

@@ -20,12 +20,14 @@ import { createRequire } from "node:module";
 import { importImplementation } from "./format-host.ts";
 import { isPrototypeDef } from "@jxsuite/schema/guards";
 import { errorMessage, parseClassDef } from "@jxsuite/schema/parse";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type {
   JsonObject,
   JsonValue,
   JxDocument,
   JxMutableNode,
   JxPrototypeDef,
+  JxStateDefinition,
 } from "@jxsuite/schema/types";
 
 /**
@@ -60,8 +62,14 @@ const RESERVED_KEYS = new Set([
  * @param {JxMutableNode | JxDocument} doc - The page document (mutated in place)
  * @param {{ sourcePath?: string; _pathParams?: Record<string, string> }} route - Route info
  * @param {string} projectRoot - Absolute path to the project root
- * @param {{ config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> }} [projectContext] -
- *   Project-level context injected into all classes
+ * @param {{
+ *   config?: Record<string, unknown>;
+ *   sections?: Record<string, unknown>;
+ *   registry?: ExtensionRegistry;
+ * }} [projectContext]
+ *   - Project-level context injected into all classes; `sections` holds the extension-loaded project
+ *     sections keyed by section key (spread into `_project`); `registry` enables manifest class
+ *     resolution and the generic `lower` capability
  */
 export async function resolvePrototypes(
   doc: JxMutableNode | JxDocument,
@@ -69,7 +77,8 @@ export async function resolvePrototypes(
   projectRoot: string,
   projectContext: {
     config?: Record<string, unknown>;
-    contentTypes?: Map<string, unknown[]>;
+    sections?: Record<string, unknown>;
+    registry?: ExtensionRegistry;
   } = {},
 ) {
   const imports = doc.imports ?? {};
@@ -85,15 +94,33 @@ export async function resolvePrototypes(
     if (SKIP_PROTOTYPES.has(def.$prototype)) {
       continue;
     }
-    // Only resolve timing: "compiler" (or unset timing with a .class.json mapping).
-    // Leave timing: "server" and timing: "client" for their respective pipelines.
+    // Only resolve timing: "compiler" (or unset timing with a class mapping). Timing: "server"
+    // And timing: "client" stay for their pipelines — but a registry class with a `lower`
+    // Capability compiles away here into a core-shape def (specs/extensions.md §8.3): dynamic
+    // Data becomes a plain reactive fetch with no extension code shipped to the browser.
     if (def.timing && def.timing !== "compiler") {
+      const entry = projectContext.registry?.byName(def.$prototype);
+      if (entry?.capabilities.lower) {
+        try {
+          const lowered = await entry.call("lower", def, {
+            projectConfig: projectContext.config,
+            root: projectRoot,
+            route,
+          });
+          state[key] = lowered as JxStateDefinition;
+        } catch (error) {
+          console.warn(
+            `prototype-resolver: failed to lower "${key}" ($prototype: "${def.$prototype}"):`,
+            errorMessage(error),
+          );
+        }
+      }
       continue;
     }
 
-    // Look up in imports if no $src already set
+    // Look up in imports (project-local wins), then the extension registry's manifest classes.
     if (!def.$src) {
-      const mapped = imports[def.$prototype];
+      const mapped = imports[def.$prototype] ?? registryClassPath(projectContext, def.$prototype);
       if (!mapped) {
         continue;
       }
@@ -116,6 +143,22 @@ export async function resolvePrototypes(
   }
 }
 
+/**
+ * Descriptor path of a manifest class from the extension registry, when one is enabled. Lets
+ * `timing: "compiler"` defs name extension classes (TableQuery, ContentCollection, …) without a
+ * project-local imports entry.
+ *
+ * @param {{ registry?: ExtensionRegistry }} projectContext
+ * @param {string} prototypeName
+ * @returns {string | undefined}
+ */
+function registryClassPath(
+  projectContext: { registry?: ExtensionRegistry },
+  prototypeName: string,
+): string | undefined {
+  return projectContext.registry?.byName(prototypeName)?.classPath;
+}
+
 /**
  * Resolve a single $prototype entry via its .class.json.
  *
@@ -123,7 +166,7 @@ export async function resolvePrototypes(
  * @param {{ sourcePath?: string; _pathParams?: Record<string, string> }} route
  * @param {string} projectRoot
  * @param {Record<string, unknown>} state - The full page state object
- * @param {{ config?: Record<string, unknown>; contentTypes?: Map<string, unknown[]> }} projectContext
+ * @param {{ config?: Record<string, unknown>; sections?: Record<string, unknown> }} projectContext
  * @returns {Promise<JsonValue>} The resolved value
  */
 async function resolveClassPrototype(
@@ -133,7 +176,7 @@ async function resolveClassPrototype(
   state: Record<string, unknown>,
   projectContext: {
     config?: Record<string, unknown>;
-    contentTypes?: Map<string, unknown[]>;
+    sections?: Record<string, unknown>;
   },
 ) {
   const src = def.$src;
@@ -191,11 +234,12 @@ async function resolveClassPrototype(
     config.basePath = dirname(route.sourcePath);
   }
 
-  // Inject universal context — available to all classes
+  // Inject universal context — available to all classes. Extension-loaded sections land under
+  // Their section keys (e.g. _project.content for the parser's content collections).
   config._project = {
     config: projectContext.config ?? null,
-    contentTypes: projectContext.contentTypes ?? null,
     root: projectRoot,
+    ...projectContext.sections,
   };
   config._document = { route, state };
 

package/src/site/schema-command.ts

@@ -0,0 +1,242 @@
+/**
+ * Schema-command — `jx schema` implementation (specs/extensions.md §5.2)
+ *
+ * Composes the per-project entry documents (project.schema.json and document.schema.json) from the
+ * core schemas and each enabled extension's shipped fragments, then writes them into the project
+ * root as committed artifacts. All fragment refs are PROJECT-RELATIVE, POSIX-style `./` paths:
+ * paths that resolve inside the project are emitted as-is; bare-specifier packages resolving
+ * through workspace symlinks (outside the root) fall back to the conventional
+ * `./node_modules/<package>/<subpath>` form, which resolves once dependencies are installed.
+ */
+
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import {
+  bundleSchema,
+  emitDocumentSchema,
+  emitProjectSchema,
+} from "@jxsuite/schema/project-schemas";
+import { buildProjectExtensionRegistry } from "./format-host.ts";
+import { loadProjectConfig } from "./site-loader.ts";
+import type { ExtensionInfo } from "@jxsuite/schema/extension-registry";
+import type { SchemaJsonLoader } from "@jxsuite/schema/project-schemas";
+
+const CORE_PROJECT_SPECIFIER = "@jxsuite/schema/schemas/project.core.schema.json";
+const CORE_DOCUMENT_SPECIFIER = "@jxsuite/schema/schema.json";
+
+/**
+ * Generate and write `<root>/project.schema.json` and `<root>/document.schema.json`.
+ *
+ * @param {string} projectRoot - Absolute path to the project directory
+ * @returns {Promise<{ projectSchemaPath: string; documentSchemaPath: string }>} Written paths
+ */
+export async function writeProjectSchemas(projectRoot: string) {
+  const { config } = loadProjectConfig(projectRoot);
+  const registry = await buildProjectExtensionRegistry(projectRoot, config);
+
+  const corePath = coreSchemaRef(projectRoot, CORE_PROJECT_SPECIFIER);
+  const fragments: string[] = [];
+  const pathsValueRefs: string[] = [];
+  const fieldSchemaRefs: string[] = [];
+  for (const ext of registry.extensions) {
+    const projectFragment = ext.schemas.project;
+    if (projectFragment) {
+      fragments.push(fragmentRef(projectRoot, ext, projectFragment));
+    }
+    const documentFragment = ext.schemas.document;
+    if (documentFragment) {
+      pathsValueRefs.push(...fragmentDefsRefs(documentFragment));
+    }
+    // The `schemas.fields` manifest convention: a fragment whose $defs members are extension
+    // Field extras, unioned into the per-project field resource (specs/extensions.md §5.3).
+    const fieldsFragment = ext.schemas.fields;
+    if (fieldsFragment) {
+      fieldSchemaRefs.push(...fragmentDefsRefs(fieldsFragment));
+      fragments.push(fragmentRef(projectRoot, ext, fieldsFragment));
+    }
+  }
+
+  const projectSchema = emitProjectSchema({ corePath, fieldSchemaRefs, fragments });
+  const documentSchema = emitDocumentSchema({
+    corePath: coreSchemaRef(projectRoot, CORE_DOCUMENT_SPECIFIER),
+    pathsValueRefs,
+  });
+
+  const projectSchemaPath = resolve(projectRoot, "project.schema.json");
+  const documentSchemaPath = resolve(projectRoot, "document.schema.json");
+  writeFileSync(projectSchemaPath, `${JSON.stringify(projectSchema, null, 2)}\n`, "utf8");
+  writeFileSync(documentSchemaPath, `${JSON.stringify(documentSchema, null, 2)}\n`, "utf8");
+  return { documentSchemaPath, projectSchemaPath };
+}
+
+/**
+ * Read the project's entry documents as PRE-BUNDLED, self-contained schemas — the payload behind
+ * the studio's `fetchProjectSchemas` PAL member (dev server route and desktop RPC). Missing or
+ * stale entry documents (older than project.json) are regenerated first via
+ * {@link writeProjectSchemas}; each is then bundled with a loader restricted to the project root,
+ * falling back to host resolution for `./node_modules/...` refs the way `jx validate` does
+ * (workspace hoisting leaves in-repo projects without their own node_modules).
+ *
+ * @param {string} projectRoot - Absolute path to the project directory
+ * @returns {Promise<{ project: Record<string, unknown>; document: Record<string, unknown> }>}
+ */
+export async function readBundledProjectSchemas(projectRoot: string) {
+  const root = resolve(projectRoot);
+  const projectJsonPath = resolve(root, "project.json");
+  const projectSchemaPath = resolve(root, "project.schema.json");
+  const documentSchemaPath = resolve(root, "document.schema.json");
+
+  const stale = (path: string): boolean => {
+    if (!existsSync(path)) {
+      return true;
+    }
+    try {
+      return statSync(projectJsonPath).mtimeMs > statSync(path).mtimeMs;
+    } catch {
+      return false;
+    }
+  };
+  if (stale(projectSchemaPath) || stale(documentSchemaPath)) {
+    await writeProjectSchemas(root);
+  }
+
+  const loadJson = restrictedSchemaLoader(root);
+  const project = await bundleSchema(
+    JSON.parse(readFileSync(projectSchemaPath, "utf8")) as Record<string, unknown>,
+    loadJson,
+    root,
+  );
+  const document = await bundleSchema(
+    JSON.parse(readFileSync(documentSchemaPath, "utf8")) as Record<string, unknown>,
+    loadJson,
+    root,
+  );
+  return { document, project };
+}
+
+/**
+ * Bundler loader restricted to the project root, with the validate-project host fallback: a missing
+ * `<root>/node_modules/<specifier>` file resolves the specifier project-first, then through the
+ * host (workspace symlinks resolve transparently).
+ *
+ * @param {string} root - Absolute project root
+ * @returns {SchemaJsonLoader}
+ */
+function restrictedSchemaLoader(root: string): SchemaJsonLoader {
+  return async (path) => {
+    const abs = resolve(path);
+    const rel = relative(root, abs);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      throw new Error(`Schema ref "${path}" escapes the project root ${root}`);
+    }
+    if (existsSync(abs)) {
+      return JSON.parse(readFileSync(abs, "utf8")) as Record<string, unknown>;
+    }
+    const posixRel = rel.split(sep).join("/");
+    const marker = "node_modules/";
+    const markerIndex = posixRel.lastIndexOf(marker);
+    if (markerIndex === -1) {
+      throw new Error(`Schema ref "${path}" does not exist`);
+    }
+    const specifier = posixRel.slice(markerIndex + marker.length);
+    let resolved: string;
+    try {
+      const projRequire = createRequire(resolve(root, "package.json"));
+      resolved = projRequire.resolve(specifier);
+    } catch {
+      try {
+        const selfRequire = createRequire(import.meta.url);
+        resolved = selfRequire.resolve(specifier);
+      } catch (error) {
+        throw new Error(
+          `Schema ref "${path}" does not exist and "${specifier}" is not resolvable from the ` +
+            `project or the host`,
+          { cause: error },
+        );
+      }
+    }
+    return JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+  };
+}
+
+/**
+ * Project-relative ref for a core schema file: resolve the specifier project-first (then host) and
+ * relativize; escape from the root (workspace symlinks) falls back to the conventional
+ * `./node_modules/...` path.
+ *
+ * @param {string} projectRoot
+ * @param {string} specifier - Bare specifier of the shipped core schema file
+ * @returns {string}
+ */
+function coreSchemaRef(projectRoot: string, specifier: string): string {
+  let resolved: string | null = null;
+  try {
+    const projRequire = createRequire(resolve(projectRoot, "package.json"));
+    resolved = projRequire.resolve(specifier);
+  } catch {
+    try {
+      const selfRequire = createRequire(import.meta.url);
+      resolved = selfRequire.resolve(specifier);
+    } catch {
+      resolved = null;
+    }
+  }
+  const conventional = `./node_modules/${specifier}`;
+  return resolved ? projectRelativeRef(projectRoot, resolved, conventional) : conventional;
+}
+
+/**
+ * Project-relative ref for an extension's fragment file. Local (relative-path) extensions live
+ * inside the project; bare-specifier packages use the conventional node_modules path built from the
+ * specifier and the fragment's manifest-relative location.
+ *
+ * @param {string} projectRoot
+ * @param {ExtensionInfo} ext
+ * @param {string} fragmentPath - Resolved absolute fragment path
+ * @returns {string}
+ */
+function fragmentRef(projectRoot: string, ext: ExtensionInfo, fragmentPath: string): string {
+  const manifestRel = relative(dirname(ext.manifestPath), fragmentPath).split(sep).join("/");
+  const conventional = `./node_modules/${ext.specifier}/${manifestRel}`;
+  return projectRelativeRef(projectRoot, fragmentPath, conventional);
+}
+
+/**
+ * Relativize an absolute path against the project root as a POSIX `./` ref, or fall back to the
+ * given conventional path when it escapes the root.
+ *
+ * @param {string} projectRoot
+ * @param {string} absPath
+ * @param {string} conventional
+ * @returns {string}
+ */
+function projectRelativeRef(projectRoot: string, absPath: string, conventional: string): string {
+  const rel = relative(projectRoot, absPath).split(sep).join("/");
+  if (rel.startsWith("..")) {
+    return conventional;
+  }
+  return rel.startsWith("./") ? rel : `./${rel}`;
+}
+
+/**
+ * Canonical "uri#/pointer" refs into a fragment's `$defs` shapes: one per `$defs` entry, addressed
+ * by the fragment's own `$id` (refs inside the entry document's embeds resolve against canonical
+ * URIs, never file locations). Serves both the document paths union and the fields-extras union.
+ *
+ * @param {string} fragmentPath - Resolved absolute fragment path
+ * @returns {string[]}
+ */
+function fragmentDefsRefs(fragmentPath: string): string[] {
+  let fragment: { $id?: unknown; $defs?: Record<string, unknown> };
+  try {
+    fragment = JSON.parse(readFileSync(fragmentPath, "utf8")) as typeof fragment;
+  } catch {
+    return [];
+  }
+  const { $id } = fragment;
+  if (typeof $id !== "string" || !fragment.$defs) {
+    return [];
+  }
+  return Object.keys(fragment.$defs).map((name) => `${$id}#/$defs/${name}`);
+}