@jxsuite/compiler 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
   "type": "module",
   "exports": {
     ".": "./src/compiler.ts",
+    "./asset-mounts": "./src/site/asset-mounts.ts",
     "./format-host": "./src/site/format-host.ts",
     "./project-sections": "./src/site/project-sections.ts",
     "./schema-command": "./src/site/schema-command.ts",
@@ -45,16 +46,16 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.5.0",
-    "@jxsuite/create": "^1.1.1",
-    "@jxsuite/runtime": "^1.2.0",
-    "@jxsuite/schema": "^1.2.0",
+    "@jxsuite/create": "^1.2.1",
+    "@jxsuite/runtime": "^1.3.1",
+    "@jxsuite/schema": "^1.4.0",
     "esbuild": "^0.28.1",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.10.6",
-    "@jxsuite/connector": "^0.3.1",
-    "@jxsuite/parser": "^1.2.0",
+    "@happy-dom/global-registrator": "^20.11.1",
+    "@jxsuite/connector": "^0.4.1",
+    "@jxsuite/parser": "^1.4.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/cli.ts

@@ -26,7 +26,7 @@ Commands:
   dev [root]       Start the dev server (requires @jxsuite/server and Bun)
   preview [root]   Serve an already-built dist/ directory
   schema [root]    Generate project.schema.json + document.schema.json from project.json#/extensions
-  validate [root]  Validate project.json against its generated project.schema.json
+  validate [root]  Validate the whole project: project.json, documents, classes, and fragments
   db push [root]   Sync the data section's tables to their connections (additive-only)
 
 Options:
@@ -161,18 +161,15 @@ Options:
     }
   } else if (command === "validate") {
     try {
-      const { validateProjectFile } = await import("@jxsuite/schema/validate-project");
-      const { valid, errors } = await validateProjectFile(projectRoot);
-      if (valid) {
-        console.log(`project.json is valid (${projectRoot})`);
+      const { formatProjectTreeIssues, validateProjectTree } =
+        await import("./site/validate-command.ts");
+      const result = await validateProjectTree(projectRoot);
+      if (result.valid) {
+        console.log(`Project is valid (${result.checked} files checked in ${projectRoot})`);
       } else {
-        console.error(`project.json is INVALID (${projectRoot}):`);
-        for (const error of errors ?? []) {
-          const { instancePath, message } = (error ?? {}) as {
-            instancePath?: string;
-            message?: string;
-          };
-          console.error(`  - ${instancePath || "/"}: ${message ?? JSON.stringify(error)}`);
+        console.error(`Project is INVALID (${projectRoot}):`);
+        for (const line of formatProjectTreeIssues(result)) {
+          console.error(line);
         }
         process.exit(1);
       }

package/src/shared.ts

@@ -23,6 +23,7 @@ import {
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
+  bodyReturnsValue,
   isNamedFormulaDef,
   isPrototypeDef,
   isRef,
@@ -79,7 +80,7 @@ export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: str
 export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
 // CDN defaults
-export const DEFAULT_REACTIVITY_SRC = "https://esm.sh/@vue/reactivity@3.5.32";
+export const DEFAULT_REACTIVITY_SRC = "https://esm.sh/@vue/reactivity@3.5.40";
 export const DEFAULT_LIT_HTML_SRC = "https://esm.sh/lit-html@3.3.0";
 
 // ─── Schema keywords & detection ─────────────────────────────────────────────
@@ -363,7 +364,7 @@ export function buildInitialScope(
         const fn = new Function("state", ...names, body) as (
           state: Record<string, unknown>,
         ) => unknown;
-        if (body.includes("return")) {
+        if (bodyReturnsValue(body)) {
           defineLazyScopeValue(scope, key, () => fn(scope));
         } else {
           setOwnScopeValue(scope, key, fn);

package/src/site/asset-mounts.ts

@@ -0,0 +1,140 @@
+/**
+ * Asset-mounts — host side of the extension `assets` capability (specs/extensions.md §8.5).
+ *
+ * A section-owner class publishes directories that may sit outside the project root (an external
+ * content source's co-located images) at a stable site URL. The build resolves those URLs while
+ * optimizing images, collects the ones its compiled output actually references, and copies just
+ * those files into dist — the source directory itself is never mirrored, so entry files never leak
+ * into the build output.
+ *
+ * @module asset-mounts
+ * @docs framework/site/images
+ */
+
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  collectAssetUrls,
+  normalizeAssetPrefix,
+  resolveAssetUrl,
+} from "@jxsuite/schema/asset-paths";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+/**
+ * Gather every asset mount contributed by the project's extensions.
+ *
+ * Gating matches `emit` (extensions.md §8.4): a class owning a project section contributes only
+ * when the project declares a non-empty value for that section. Mounts claiming the same URL prefix
+ * for different directories are a configuration error — the first wins and the clash is reported.
+ *
+ * @param {ExtensionRegistry} registry - The project's extension registry
+ * @param {ProjectConfig} projectConfig
+ * @param {string} projectRoot - Absolute project root
+ * @returns {Promise<{ mounts: AssetMount[]; errors: string[] }>}
+ */
+export async function loadAssetMounts(
+  registry: ExtensionRegistry,
+  projectConfig: ProjectConfig,
+  projectRoot: string,
+): Promise<{ mounts: AssetMount[]; errors: string[] }> {
+  const mounts: AssetMount[] = [];
+  const errors: string[] = [];
+  const byPrefix = new Map<string, AssetMount>();
+
+  for (const entry of registry.assetProviders()) {
+    const sectionKey = entry.project?.key;
+    const sectionValue = sectionKey
+      ? (projectConfig as unknown as Record<string, unknown>)[sectionKey]
+      : undefined;
+    if (
+      sectionKey &&
+      (sectionValue == null ||
+        (typeof sectionValue === "object" && Object.keys(sectionValue).length === 0))
+    ) {
+      continue;
+    }
+    try {
+      const declared = (await entry.call("assets", sectionValue ?? null, {
+        projectConfig,
+        root: projectRoot,
+      })) as AssetMount[] | null;
+      for (const mount of declared ?? []) {
+        if (!mount?.urlPrefix || !mount.dir) {
+          continue;
+        }
+        const normalized: AssetMount = {
+          dir: mount.dir,
+          urlPrefix: normalizeAssetPrefix(mount.urlPrefix),
+        };
+        const prior = byPrefix.get(normalized.urlPrefix);
+        if (prior) {
+          if (prior.dir !== normalized.dir) {
+            errors.push(
+              `Asset mount conflict: "${normalized.urlPrefix}" is claimed by both ` +
+                `"${prior.dir}" and "${normalized.dir}"`,
+            );
+          }
+          continue;
+        }
+        byPrefix.set(normalized.urlPrefix, normalized);
+        mounts.push(normalized);
+      }
+    } catch (error) {
+      errors.push(`Error in ${entry.name}.assets: ${(error as Error).message}`);
+    }
+  }
+
+  return { errors, mounts };
+}
+
+/**
+ * Add every mounted URL referenced by a compiled artifact to `into`.
+ *
+ * @param {string} text - Compiled HTML or CSS
+ * @param {readonly AssetMount[]} mounts
+ * @param {Set<string>} into - Accumulator across the whole build
+ */
+export function collectAssetRefs(text: string, mounts: readonly AssetMount[], into: Set<string>) {
+  if (mounts.length === 0 || !text) {
+    return;
+  }
+  for (const url of collectAssetUrls(text, mounts)) {
+    into.add(url);
+  }
+}
+
+/**
+ * Copy referenced mounted assets into the build output, each at its own URL path.
+ *
+ * @param {Iterable<string>} urls - Mounted URLs collected from the compiled output
+ * @param {readonly AssetMount[]} mounts
+ * @param {string} outDir - Absolute build output directory
+ * @returns {{ copied: number; missing: string[] }} Files written, and URLs that resolved to nothing
+ */
+export function copyMountedAssets(
+  urls: Iterable<string>,
+  mounts: readonly AssetMount[],
+  outDir: string,
+): { copied: number; missing: string[] } {
+  let copied = 0;
+  const missing: string[] = [];
+
+  for (const url of urls) {
+    // The single containment gate is resolveAssetUrl: it decodes once and refuses `.`/`..`,
+    // Empty segments, and undecodable input, so a surviving URL cannot escape either the mount
+    // Directory it reads from or the outDir path it writes to.
+    const source = resolveAssetUrl(mounts, url);
+    if (!source || !existsSync(source)) {
+      missing.push(url);
+      continue;
+    }
+    const target = resolve(outDir, decodeURIComponent(url).replace(/^\//, ""));
+    mkdirSync(dirname(target), { recursive: true });
+    cpSync(source, target);
+    copied += 1;
+  }
+
+  return { copied, missing };
+}

package/src/site/image-transform.ts

@@ -16,7 +16,9 @@ import {
   processImage,
 } from "./image-optimizer.ts";
 import { getCached, getImageCacheDir, setCached } from "./image-cache.ts";
+import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
 
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { ImageConfig, ImageManifest } from "./image-optimizer.ts";
 import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
 import type { CacheManifest } from "./image-cache.ts";
@@ -193,13 +195,20 @@ function isAllowedRemote(src: string, config: ImageConfig) {
 /**
  * Resolve a src path to an absolute filesystem path.
  *
- * Handles paths starting with "/" (relative to public dir or project root).
+ * Extension asset mounts win first — they publish directories that may sit outside the project root
+ * (extensions.md §8.5), so a mounted src has no other resolution. Otherwise paths starting with "/"
+ * resolve into `public/`, and relative ones from the project root.
  *
  * @param {string} src
  * @param {string} projectRoot
+ * @param {readonly AssetMount[]} [mounts]
  * @returns {string}
  */
-function resolveImagePath(src: string, projectRoot: string) {
+function resolveImagePath(src: string, projectRoot: string, mounts?: readonly AssetMount[]) {
+  const mounted = mounts?.length ? resolveAssetUrl(mounts, src) : null;
+  if (mounted) {
+    return mounted;
+  }
   if (src.startsWith("/")) {
     return resolve(projectRoot, "public", src.slice(1));
   }
@@ -218,6 +227,7 @@ function resolveImagePath(src: string, projectRoot: string) {
  * @param {string} projectRoot
  * @param {CacheManifest | null} cache - Variant cache (build mode); unused in cloudflare mode
  * @param {ImageMetaCache} [metaCache] - Dimension/hash memo (cloudflare mode)
+ * @param {readonly AssetMount[]} [mounts] - Extension asset mounts (extensions.md §8.5)
  * @returns {Promise<{ imageRefs: Map<string, ImageManifest> }>}
  */
 export async function transformImageNodes(
@@ -226,6 +236,7 @@ export async function transformImageNodes(
   projectRoot: string,
   cache: CacheManifest | null,
   metaCache?: ImageMetaCache,
+  mounts: readonly AssetMount[] = [],
 ) {
   const imageRefs = new Map<string, ImageManifest>();
 
@@ -234,7 +245,7 @@ export async function transformImageNodes(
   }
 
   const meta = metaCache ?? new Map();
-  await walkAndTransform(doc, config, projectRoot, cache, meta, imageRefs);
+  await walkAndTransform(doc, config, projectRoot, cache, meta, imageRefs, mounts);
 
   return { imageRefs };
 }
@@ -246,6 +257,7 @@ export async function transformImageNodes(
  * @param {CacheManifest | null} cache
  * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
+ * @param {readonly AssetMount[]} mounts
  */
 async function walkAndTransform(
   node: JxMutableNode | JxDocument,
@@ -254,13 +266,14 @@ async function walkAndTransform(
   cache: CacheManifest | null,
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
+  mounts: readonly AssetMount[],
 ) {
   if (!node || typeof node !== "object") {
     return;
   }
 
   if (node.tagName === "img") {
-    await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs);
+    await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs, mounts);
   }
 
   if (typeof node.innerHTML === "string" && node.innerHTML.includes("<img")) {
@@ -271,6 +284,7 @@ async function walkAndTransform(
       cache,
       metaCache,
       imageRefs,
+      mounts,
     );
   }
 
@@ -279,7 +293,7 @@ async function walkAndTransform(
       if (typeof child === "string") {
         continue;
       }
-      await walkAndTransform(child, config, projectRoot, cache, metaCache, imageRefs);
+      await walkAndTransform(child, config, projectRoot, cache, metaCache, imageRefs, mounts);
     }
   }
 }
@@ -291,6 +305,7 @@ async function walkAndTransform(
  * @param {CacheManifest | null} cache
  * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
+ * @param {readonly AssetMount[]} mounts
  */
 async function transformImgNode(
   node: JxMutableNode | JxDocument,
@@ -299,6 +314,7 @@ async function transformImgNode(
   cache: CacheManifest | null,
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
+  mounts: readonly AssetMount[],
 ) {
   if (!node.attributes) {
     node.attributes = {};
@@ -325,7 +341,7 @@ async function transformImgNode(
     // Fit=scale-down avoid upscaling past the source size.
     srcset = buildCloudflareSrcset(src, config, Infinity, null);
   } else {
-    const absoluteSrc = resolveImagePath(src, projectRoot);
+    const absoluteSrc = resolveImagePath(src, projectRoot, mounts);
     if (!existsSync(absoluteSrc)) {
       return;
     }
@@ -382,6 +398,7 @@ const DATA_NO_OPT_RE = /\bdata-no-optimize\b/;
  * @param {CacheManifest | null} cache
  * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
+ * @param {readonly AssetMount[]} mounts
  * @returns {Promise<string>}
  */
 async function transformInnerHtmlImages(
@@ -391,6 +408,7 @@ async function transformInnerHtmlImages(
   cache: CacheManifest | null,
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
+  mounts: readonly AssetMount[],
 ) {
   /** @type {{ match: string; replacement: string }[]} */
   const replacements = [];
@@ -418,7 +436,7 @@ async function transformInnerHtmlImages(
       continue;
     }
 
-    const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot);
+    const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot, mounts);
     if (absoluteSrc && !existsSync(absoluteSrc)) {
       continue;
     }

package/src/site/schema-command.ts

@@ -3,10 +3,12 @@
  *
  * 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.
+ * 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.
  */
 
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -57,11 +59,22 @@ export async function writeProjectSchemas(projectRoot: string) {
     }
   }
 
-  const projectSchema = emitProjectSchema({ corePath, fieldSchemaRefs, fragments });
-  const documentSchema = emitDocumentSchema({
-    corePath: coreSchemaRef(projectRoot, CORE_DOCUMENT_SPECIFIER),
-    pathsValueRefs,
-  });
+  // Bundle before committing: the emitted relative refs are an intermediate form only.
+  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 projectSchemaPath = resolve(projectRoot, "project.schema.json");
   const documentSchemaPath = resolve(projectRoot, "document.schema.json");

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,
@@ -262,6 +284,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 +348,7 @@ export async function buildSite(
         formatRegistry,
         registry,
         rewriteSidecarSrc,
+        assetMounts,
       );
 
       // Determine which component tags are fully static (for script omission)
@@ -345,6 +369,10 @@ export async function buildSite(
         );
       }
 
+      // 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 +596,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 +670,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 +785,7 @@ async function compilePage(
       projectRoot,
       imageCache,
       imageMetaCache ?? undefined,
+      assetMounts,
     );
   }