@jxsuite/compiler 1.3.0 → 1.5.0

package/src/site/schema-command.ts

@@ -3,12 +3,16 @@
  *
  * 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, SELF-CONTAINED bundles: every fragment ref is resolved through
- * {@link bundleSchema}, embedding the core + fragment resources under `$defs` keyed by their
- * canonical `$id`s. Relative `./node_modules/...` refs only resolve through Node module resolution,
- * which editors do not perform (hoisted workspaces leave projects without their own node_modules) —
- * the bundled form resolves offline for ajv `jx validate`, VS Code's JSON language service, and the
- * studio's Monaco alike, with one resolution behavior for all consumers.
+ * root as committed, SELF-CONTAINED, SINGLE-RESOURCE schemas: every fragment ref is resolved
+ * through {@link bundleSchema} (embedding the core + fragment resources under `$defs`) and then
+ * collapsed by {@link flattenSchema}, which drops the embedded `$id`s and rewrites every ref to a
+ * root-relative JSON Pointer. Both passes are needed for one resolution behavior across all
+ * consumers: relative `./node_modules/...` refs only resolve through Node module resolution, which
+ * editors do not perform (hoisted workspaces leave projects without their own node_modules), while
+ * `$id`-scoped refs inside a compound document resolve only in a fully compliant validator — VS
+ * Code's JSON language service and Monaco resolve `#/...` against the document root and fetch
+ * anything with a URI before the `#` over the network. Root pointers are what ajv, the language
+ * service, and Monaco all agree on.
  */
 
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -16,8 +20,8 @@ import { createRequire } from "node:module";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import {
   bundleSchema,
-  emitDocumentSchema,
-  emitProjectSchema,
+  composeProjectSchemas,
+  flattenSchema,
 } from "@jxsuite/schema/project-schemas";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectConfig } from "./site-loader.ts";
@@ -37,44 +41,22 @@ 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));
-    }
-  }
-
-  // Bundle before committing: the emitted relative refs are an intermediate form only.
+  /* Composition itself is host-agnostic (@jxsuite/schema `composeProjectSchemas`) — the filesystem
+     appears only in what this host contributes: project-relative refs for the fragments the
+     registry resolved, and a loader restricted to the project root. The cloud session composes the
+     same two documents from bundled artifacts through the same function. */
   const root = resolve(projectRoot);
-  const loadJson = restrictedSchemaLoader(root);
-  const projectSchema = await bundleSchema(
-    emitProjectSchema({ corePath, fieldSchemaRefs, fragments }),
-    loadJson,
-    root,
-  );
-  const documentSchema = await bundleSchema(
-    emitDocumentSchema({
-      corePath: coreSchemaRef(projectRoot, CORE_DOCUMENT_SPECIFIER),
-      pathsValueRefs,
-    }),
-    loadJson,
-    root,
-  );
+  const { document: documentSchema, project: projectSchema } = await composeProjectSchemas({
+    baseDir: root,
+    coreDocumentRef: coreSchemaRef(projectRoot, CORE_DOCUMENT_SPECIFIER),
+    coreProjectRef: coreSchemaRef(projectRoot, CORE_PROJECT_SPECIFIER),
+    extensions: registry.extensions.map((ext) => ({
+      document: ext.schemas.document && fragmentRef(projectRoot, ext, ext.schemas.document),
+      fields: ext.schemas.fields && fragmentRef(projectRoot, ext, ext.schemas.fields),
+      project: ext.schemas.project && fragmentRef(projectRoot, ext, ext.schemas.project),
+    })),
+    loadJson: restrictedSchemaLoader(root),
+  });
 
   const projectSchemaPath = resolve(projectRoot, "project.schema.json");
   const documentSchemaPath = resolve(projectRoot, "document.schema.json");
@@ -115,16 +97,16 @@ export async function readBundledProjectSchemas(projectRoot: string) {
   }
 
   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,
-  );
+  const projectFile = JSON.parse(readFileSync(projectSchemaPath, "utf8")) as Record<
+    string,
+    unknown
+  >;
+  const documentFile = JSON.parse(readFileSync(documentSchemaPath, "utf8")) as Record<
+    string,
+    unknown
+  >;
+  const project = flattenSchema(await bundleSchema(projectFile, loadJson, root));
+  const document = flattenSchema(await bundleSchema(documentFile, loadJson, root));
   return { document, project };
 }
 
@@ -231,25 +213,3 @@ function projectRelativeRef(projectRoot: string, absPath: string, 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}`);
-}

package/src/site/site-build.ts

@@ -32,6 +32,8 @@ import { loadProjectConfig } from "./site-loader.ts";
 import { discoverPages, expandDynamicRoutes, readPageDocument } from "./pages-discovery.ts";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectSections } from "./project-sections.ts";
+import { collectAssetRefs, copyMountedAssets, loadAssetMounts } from "./asset-mounts.ts";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import { resolveLayout } from "./layout-resolver.ts";
@@ -208,6 +210,26 @@ export async function buildSite(
     log(`  Loaded ${sectionKeys.length} section(s): ${sectionKeys.join(", ")}`);
   }
 
+  // ── 3c. Extension asset mounts (extensions.md §8.5) ─────────────────────
+  // Directories published at a site URL — typically an external content source's co-located
+  // Images. They resolve for image optimization below, and the files pages actually reference
+  // Are copied into dist in step 7c.
+  const { errors: mountErrors, mounts: assetMounts } = await loadAssetMounts(
+    registry,
+    projectConfig,
+    projectRoot,
+  );
+  errors.push(...mountErrors);
+  for (const message of mountErrors) {
+    console.error(message);
+  }
+  if (assetMounts.length > 0) {
+    log(
+      `  Mounted ${assetMounts.length} asset dir(s): ${assetMounts.map((m) => m.urlPrefix).join(", ")}`,
+    );
+  }
+  const assetRefs = new Set<string>();
+
   // ── 4. Expand dynamic routes ────────────────────────────────────────────
   const routes = await expandDynamicRoutes(
     staticRoutes,
@@ -234,20 +256,44 @@ export async function buildSite(
     const componentOutDir = resolve(outDir, "components");
     mkdirSync(componentOutDir, { recursive: true });
 
+    // Emitted modules are named after the component's `tagName` — the name the page's loader
+    // `<script>` and the CSS sidecar both use. So a component whose source basename differs from
+    // Its tag needs its `$elements` imports renamed to match, and those get resolved before the
+    // Dependency itself is compiled. Hence: read every component's tag up front.
+    const componentTagByPath = new Map<string, string>();
+    for (const file of componentFiles) {
+      const componentPath = resolve(componentsDir, file);
+      try {
+        const { tagName: depTag } = await readPageDocument(componentPath, formatRegistry);
+        if (depTag) {
+          componentTagByPath.set(componentPath, depTag);
+        }
+      } catch {
+        // Left to the compile pass below, which reports the parse failure with its file context.
+      }
+    }
+
     for (const file of componentFiles) {
       try {
         const componentPath = resolve(componentsDir, file);
         const result = await compileElement(componentPath, {
           ...(projectConfig.$media ? { $media: projectConfig.$media } : {}),
           formats: formatRegistry,
+          resolveElementPath: (refPath: string, currentDir: string | null) => {
+            const depPath = currentDir ? resolve(currentDir, refPath) : resolve(refPath);
+            const depTag = componentTagByPath.get(depPath);
+            return depTag ? `./${depTag}.js` : refPath.replace(/\.json$/, ".js");
+          },
           rewriteSrc: rewriteSidecarSrc,
         });
         for (const f of result.files) {
-          // Reduce the emitted path (an absolute source path with .json swapped to .js) to a bare
-          // Filename for the dist/components/ output. basename handles both / and \ — a
-          // Forward-slash-only split left the full drive path on Windows, so resolve() then wrote
-          // The sidecar back into the source tree instead of dist.
-          const outName = basename(f.path);
+          // Name the output after the tag. `injectComponentScripts` emits
+          // `<script src="/components/<tag>.js">` and the CSS sidecar is written as `<tag>.css`, so
+          // A source basename here left the loader pointing at a file that was never written.
+          // Basename is the fallback, and handles both / and \ — a forward-slash-only split left
+          // The full drive path on Windows, so resolve() then wrote the sidecar back into the
+          // Source tree instead of dist.
+          const outName = f.tagName ? `${f.tagName}.js` : basename(f.path);
           writeFileSync(resolve(componentOutDir, outName), f.content, "utf8");
           if (f.tagName) {
             compiledComponentTags.push(f.tagName);
@@ -262,6 +308,7 @@ export async function buildSite(
           const css = buildComponentCSS(doc.tagName, doc.style, doc, projectConfig.$media ?? {});
           if (css) {
             componentCSS.set(doc.tagName, css);
+            collectAssetRefs(css, assetMounts, assetRefs);
             writeFileSync(resolve(componentOutDir, `${doc.tagName}.css`), css, "utf8");
             fileCount += 1;
           }
@@ -325,6 +372,7 @@ export async function buildSite(
         formatRegistry,
         registry,
         rewriteSidecarSrc,
+        assetMounts,
       );
 
       // Determine which component tags are fully static (for script omission)
@@ -342,9 +390,14 @@ export async function buildSite(
           compiledComponentTags,
           componentCSS,
           staticTags,
+          result.files.map((f: { content: string }) => f.content).join("\n"),
         );
       }
 
+      // Mounted assets this page actually references — scanned from the finished HTML so a
+      // Reference is caught wherever it came from (markdown image, hand-authored page, $head).
+      collectAssetRefs(result.html, assetMounts, assetRefs);
+
       // Determine output path
       const outPath = routeToOutputPath(route.urlPattern, outDir, trailingSlash);
       mkdirSync(dirname(outPath), { recursive: true });
@@ -568,7 +621,19 @@ export async function buildSite(
     console.warn("sitemap.xml skipped — set `url` in project.json to enable sitemap generation.");
   }
 
-  // ── 7c. Copy public/ assets ─────────────────────────────────────────────
+  // ── 7c. Copy referenced mounted assets (extensions.md §8.5) ─────────────
+  // Only files the compiled output references are copied, so a content source's entry files
+  // Never land in dist. Runs before the public/ copy, which keeps shadowing everything.
+  if (assetRefs.size > 0) {
+    const { copied, missing } = copyMountedAssets(assetRefs, assetMounts, outDir);
+    fileCount += copied;
+    log(`Copying ${copied} mounted asset(s)...`);
+    for (const url of missing) {
+      console.warn(`Referenced asset not found: ${url}`);
+    }
+  }
+
+  // ── 7c(ii). Copy public/ assets ─────────────────────────────────────────
   if (existsSync(publicDir)) {
     log("Copying public/ assets...");
     cpSync(publicDir, outDir, { recursive: true });
@@ -630,6 +695,7 @@ async function compilePage(
   formatRegistry?: FormatRegistry,
   registry?: ExtensionRegistry,
   rewriteSidecarSrc?: (specifier: string, docDir: string | null) => string,
+  assetMounts: readonly AssetMount[] = [],
 ) {
   // Load the raw page document (.json natively, other formats via the registry)
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
@@ -744,6 +810,7 @@ async function compilePage(
       projectRoot,
       imageCache,
       imageMetaCache ?? undefined,
+      assetMounts,
     );
   }
 
@@ -1109,9 +1176,14 @@ function resolveDocTemplates(node: JxElement | string, scope: Record<string, unk
   }
   const rawChildren = node.children;
   // Legacy whole-children repeater: expand the items into the node's static children.
+  // Only when the expansion actually produced nodes. `expandMappedArrayStatic` returns `null` when
+  // `items` cannot be resolved at build time and `[]` when it resolves to an empty array — and `[]`
+  // Is truthy, so an empty build-time list used to replace the repeater with nothing, discarding the
+  // Definition the client needed. There is no prerendered output to preserve in that case, so the
+  // Repeater is left in place for the client to bind (a page containing one is never zero-JS).
   if (isMappedArray(rawChildren)) {
     const expanded = expandMappedArrayStatic(rawChildren, scope);
-    if (expanded) {
+    if (expanded && expanded.length > 0) {
       node.children = expanded;
       return;
     }
@@ -1141,10 +1213,11 @@ function resolveDocTemplates(node: JxElement | string, scope: Record<string, unk
           continue;
         }
       }
-      // Array pseudo-element among siblings: expand its items in place.
+      // Array pseudo-element among siblings: expand its items in place, on the same
+      // Produced-nothing rule as the whole-children branch above.
       if (isMappedArray(child)) {
         const expanded = expandMappedArrayStatic(child, scope);
-        if (expanded) {
+        if (expanded && expanded.length > 0) {
           node.children.splice(i, 1, ...expanded);
           i += expanded.length;
           continue;
@@ -1309,6 +1382,7 @@ function expandComponents(
  * @param {string[]} allComponentTags - All compiled component tag names
  * @param {Map<string, string>} [cssMap] - TagName → CSS text (for link injection)
  * @param {Set<string>} [staticTags] - Tags where ALL instances are fully static (skip JS)
+ * @param {string} [islandSource] - Concatenated island modules emitted for this page
  * @returns {string}
  */
 function injectComponentScripts(
@@ -1316,11 +1390,15 @@ function injectComponentScripts(
   allComponentTags: string[],
   cssMap = new Map<string, string>(),
   staticTags = new Set<string>(),
+  islandSource = "",
 ) {
-  // Find which components are actually referenced in this page
-  const usedTags = allComponentTags.filter(
-    (tag: string) => html.includes(`<${tag}`), // Matches <tag> and <tag ...>
-  );
+  // A component reaches a page two ways: as a literal tag in the static HTML, or referenced only
+  // From inside an island's client template — in which case the tag exists solely in the island's
+  // Compiled JS and never in the HTML the page ships. Searching the HTML alone missed the second
+  // Kind entirely, so its module was never loaded and the element sat in the DOM un-upgraded.
+  const inHtml = (tag: string) => html.includes(`<${tag}`); // Matches <tag> and <tag ...>
+  const inIsland = (tag: string) => islandSource.includes(`<${tag}`);
+  const usedTags = allComponentTags.filter((tag: string) => inHtml(tag) || inIsland(tag));
   if (usedTags.length === 0) {
     return html;
   }
@@ -1335,8 +1413,11 @@ function injectComponentScripts(
     result = result.replace("</head>", `  ${cssLinks}\n</head>`);
   }
 
-  // Only inject JS for components that have non-static instances
-  const jsTags = usedTags.filter((tag: string) => !staticTags.has(tag));
+  // Only inject JS for components that have non-static instances. An island-rendered instance is
+  // Never prerendered, so it needs its module even when the component itself is fully static —
+  // That module is what fills the element in client-side. This holds when the tag ALSO appears in
+  // The static HTML: those instances are prerendered, but the ones the island creates are not.
+  const jsTags = usedTags.filter((tag: string) => inIsland(tag) || !staticTags.has(tag));
   if (jsTags.length === 0) {
     return result;
   }

package/src/site/validate-command.ts

@@ -3,9 +3,11 @@
  *
  * Extends the original project.json check into the full compliance walk:
  *
- * 1. `project.json` against the generated entry schema (validateProjectFile);
- * 2. The committed entry documents are SELF-CONTAINED (no residual relative `$ref`s — the
- *    editor-resolution guarantee of the bundled form, specs/extensions.md §5.4);
+ * 1. The committed entry documents are SELF-CONTAINED and SINGLE-RESOURCE: every `$ref` is a
+ *    root-relative JSON Pointer that resolves inside the file — the editor-resolution guarantee of
+ *    the committed form (specs/extensions.md §5.4). Checked first and fatal, since walks 2–4
+ *    compile those documents;
+ * 2. `project.json` against the generated entry schema (validateProjectFile);
  * 3. Every document under `components/`, `pages/`, and `layouts/` against the bundled document schema
  *    (core + extension `$paths` union — the same schema the studio consumes);
  * 4. Every project-local `*.class.json` against the generated class schema;
@@ -94,33 +96,39 @@ export async function validateProjectTree(
   const issues: ProjectTreeIssue[] = [];
   let checked = 0;
 
-  // 1. project.json against the generated entry schema.
-  const projectResult = await validateProjectFile(root);
-  checked += 1;
-  if (!projectResult.valid) {
-    issues.push({ errors: projectResult.errors ?? [], file: "project.json" });
-  }
-
-  // 2. Committed entry documents must be self-contained (the editor-resolution guarantee).
+  /* 1. Committed entry documents must be self-contained (the editor-resolution guarantee). This
+     runs FIRST because every later walk compiles one of them: an unresolvable ref surfaces from ajv
+     as a thrown MissingRefError, so diagnosing it here turns a stack trace into "regenerate with
+     `jx schema`". Nothing downstream is meaningful until it holds, hence the early return. */
   for (const name of ["project.schema.json", "document.schema.json"]) {
     const path = resolve(root, name);
     if (!existsSync(path)) {
       continue;
     }
     checked += 1;
-    const residual: string[] = [];
-    collectRelativeRefs(JSON.parse(readFileSync(path, "utf8")), residual);
-    if (residual.length > 0) {
+    const entry = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    const unresolvable = collectUnresolvableRefs(entry);
+    if (unresolvable.length > 0) {
       issues.push({
-        errors: residual.map((ref) => ({
+        errors: unresolvable.map(({ reason, ref }) => ({
           message:
-            `relative $ref "${ref}" — committed entry documents must be self-contained; ` +
-            `regenerate with \`jx schema\``,
+            `$ref "${ref}" ${reason} — committed entry documents must be self-contained ` +
+            `single-resource schemas; regenerate with \`jx schema\``,
         })),
         file: name,
       });
     }
   }
+  if (issues.length > 0) {
+    return { checked, issues, valid: false };
+  }
+
+  // 2. project.json against the generated entry schema.
+  const projectResult = await validateProjectFile(root);
+  checked += 1;
+  if (!projectResult.valid) {
+    issues.push({ errors: projectResult.errors ?? [], file: "project.json" });
+  }
 
   const { addFormats, Ajv } = await loadAjv();
 
@@ -186,30 +194,118 @@ export async function validateProjectTree(
   return { checked, issues, valid: issues.length === 0 };
 }
 
-/** Collect relative-path `$ref`s (anything without a URI scheme that isn't a `#` pointer). */
-function collectRelativeRefs(node: unknown, out: string[]): void {
-  if (Array.isArray(node)) {
-    for (const item of node) {
-      collectRelativeRefs(item, out);
+/**
+ * Every `$ref` a committed entry document may carry must be a root-relative JSON Pointer that
+ * resolves inside the same file. Three ways that fails, all of which break editor resolution: a
+ * relative path (needs Node module resolution), a URI (VS Code fetches it over the network instead
+ * of matching an embedded `$id`), and a pointer with no node at the other end.
+ *
+ * Walks only subschema keyword positions, since `examples`/`default`/`const`/`enum` hold instance
+ * data and Jx document examples legitimately contain `$ref` strings of their own.
+ *
+ * @param {Record<string, unknown>} entry - Parsed committed entry document
+ * @returns {{ ref: string; reason: string }[]} One entry per offending `$ref`
+ */
+function collectUnresolvableRefs(
+  entry: Record<string, unknown>,
+): { ref: string; reason: string }[] {
+  const out: { ref: string; reason: string }[] = [];
+  const seen = new Set<Record<string, unknown>>();
+
+  const resolvePointer = (pointer: string): boolean => {
+    let current: unknown = entry;
+    for (const raw of pointer.slice(1).split("/")) {
+      if (raw === "") {
+        continue;
+      }
+      const segment = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+      if (typeof current !== "object" || current === null) {
+        return false;
+      }
+      current = (current as Record<string, unknown>)[segment];
+      if (current === undefined) {
+        return false;
+      }
+    }
+    return true;
+  };
+
+  const walk = (node: unknown): void => {
+    if (!isRecord(node) || seen.has(node)) {
+      return;
     }
-    return;
-  }
-  if (node === null || typeof node !== "object") {
-    return;
-  }
-  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
-    if (
-      key === "$ref" &&
-      typeof value === "string" &&
-      !value.startsWith("#") &&
-      !/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value)
-    ) {
-      out.push(value);
+    seen.add(node);
+    const ref = node.$ref;
+    if (typeof ref === "string") {
+      if (/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(ref)) {
+        out.push({ reason: "is an absolute URI editors resolve over the network", ref });
+      } else if (!ref.startsWith("#")) {
+        out.push({ reason: "is a relative path only Node module resolution can follow", ref });
+      } else if (ref.length > 1 && !ref.startsWith("#/")) {
+        out.push({ reason: "is an $anchor reference, which has no root-pointer form", ref });
+      } else if (ref.length > 1 && !resolvePointer(ref.slice(1))) {
+        out.push({ reason: "points at no node in this document", ref });
+      }
     }
-    collectRelativeRefs(value, out);
-  }
+    for (const [keyword, value] of Object.entries(node)) {
+      if (!SUBSCHEMA_KEYWORDS.has(keyword)) {
+        continue;
+      }
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          walk(item);
+        }
+      } else if (isRecord(value)) {
+        // Map-valued keywords hold subschemas one level down; single-valued ones are the schema.
+        walk(value);
+        if (MAP_SUBSCHEMA_KEYWORDS.has(keyword)) {
+          for (const item of Object.values(value)) {
+            walk(item);
+          }
+        }
+      }
+    }
+  };
+  walk(entry);
+  return out;
 }
 
+/** True for a plain object (a candidate subschema node). */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Keywords whose values map names to subschemas. */
+const MAP_SUBSCHEMA_KEYWORDS = new Set([
+  "$defs",
+  "definitions",
+  "dependencies",
+  "dependentSchemas",
+  "patternProperties",
+  "properties",
+]);
+
+/** Every keyword position a subschema can occupy (see {@link MAP_SUBSCHEMA_KEYWORDS} for maps). */
+const SUBSCHEMA_KEYWORDS = new Set([
+  ...MAP_SUBSCHEMA_KEYWORDS,
+  "additionalItems",
+  "additionalProperties",
+  "allOf",
+  "anyOf",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "oneOf",
+  "prefixItems",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+]);
+
 /** Recursively list `.json` files under a directory (absent directories yield nothing). */
 function walkJsonFiles(dir: string): string[] {
   if (!existsSync(dir)) {