@jxsuite/schema 1.3.0 → 1.4.0

package/class-schema.json

@@ -181,6 +181,7 @@
             "resolvePaths",
             "lower",
             "emit",
+            "assets",
             "mount",
             "dialect",
             "deploySchema",

package/defs/class-def.schema.ts

@@ -15,6 +15,7 @@ export const CLASS_METHOD_ROLES = [
   "resolvePaths",
   "lower",
   "emit",
+  "assets",
   "mount",
   "dialect",
   "deploySchema",

package/package.json

@@ -50,7 +50,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -634,6 +634,7 @@
             "resolvePaths",
             "lower",
             "emit",
+            "assets",
             "mount",
             "dialect",
             "deploySchema",

package/src/asset-paths.ts

@@ -1,11 +1,14 @@
 /**
- * Deterministic mapping from Function-def `$src` module specifiers to bundled asset URLs. Shared
- * between the compiler's sidecar bundler (which writes the bundle) and extension `lower()`
+ * Deterministic mapping from Function-def `$src` module specifiers to bundled asset URLs, plus the
+ * asset-mount math that publishes files living outside the project root at a stable site URL.
+ * Shared between the compiler's sidecar bundler (which writes the bundle) and extension `lower()`
  * implementations (which emit the URL into client code) so neither needs to depend on the other.
  *
  * The mapping is intentionally hash-free: the same specifier always yields the same URL, letting
  * lowered defs reference bundles the compiler produces later in the build. Distinct specifiers that
  * collide on a slug are rejected by the bundler at build time.
+ *
+ * Pure string math only — no node imports — so browser hosts can import this module.
  */
 
 /** Prefix for npm package specifiers in `$src` (spec §12): `npm:<pkg>[/subpath]`. */
@@ -40,3 +43,135 @@ export function sidecarAssetPath(specifier: string): string {
     .replaceAll(/^-|-$/g, "");
   return `${SIDECAR_ASSET_DIR}${base}.js`;
 }
+
+// ─── Asset mounts (specs/extensions.md §8.5) ─────────────────────────────────
+
+/**
+ * A site URL prefix backed by a real directory. Extensions declaring the `assets` capability return
+ * mounts so hosts can publish files that live outside the project root (an external content
+ * source's co-located images) without knowing anything about the section that owns them.
+ */
+export interface AssetMount {
+  /** Site-absolute URL prefix, e.g. `/content/docs` (no trailing slash). */
+  urlPrefix: string;
+  /** Absolute directory the prefix maps onto. */
+  dir: string;
+}
+
+/** Normalize a path or prefix for comparison: forward slashes, no trailing slash. */
+function normalizeDir(value: string): string {
+  const forward = value.replaceAll("\\", "/");
+  return forward.length > 1 && forward.endsWith("/") ? forward.slice(0, -1) : forward;
+}
+
+/** Normalize a mount's URL prefix: leading slash, no trailing slash. */
+export function normalizeAssetPrefix(prefix: string): string {
+  const forward = normalizeDir(prefix);
+  return forward.startsWith("/") ? forward : `/${forward}`;
+}
+
+/** Mounts sorted so the most specific (longest) candidate matches first. */
+function bySpecificity(mounts: readonly AssetMount[], key: "dir" | "urlPrefix"): AssetMount[] {
+  return [...mounts].toSorted((a, b) => b[key].length - a[key].length);
+}
+
+/** True when `path` is `dir` itself or sits underneath it (both already normalized). */
+function isUnder(path: string, dir: string): boolean {
+  return path === dir || path.startsWith(`${dir}/`);
+}
+
+/**
+ * Map an absolute file path to its mounted site URL, or null when no mount contains it. Path
+ * segments are percent-encoded so the URL survives HTML attributes; `resolveAssetUrl` reverses it.
+ *
+ * @param {readonly AssetMount[]} mounts
+ * @param {string} absolutePath - Absolute filesystem path
+ * @returns {string | null}
+ */
+export function assetUrlFor(mounts: readonly AssetMount[], absolutePath: string): string | null {
+  const path = normalizeDir(absolutePath);
+  for (const mount of bySpecificity(mounts, "dir")) {
+    const dir = normalizeDir(mount.dir);
+    if (!isUnder(path, dir) || path === dir) {
+      continue;
+    }
+    const rest = path.slice(dir.length + 1);
+    const encoded = rest
+      .split("/")
+      .map((segment) => encodeURIComponent(segment))
+      .join("/");
+    return `${normalizeAssetPrefix(mount.urlPrefix)}/${encoded}`;
+  }
+  return null;
+}
+
+/**
+ * Map a mounted site URL back to its absolute file path, or null when it matches no mount. Query
+ * and hash are dropped, the path is decoded ONCE (a still-encoded dot or slash after that decode is
+ * a bypass attempt and is rejected), and `.`/`..` segments are refused outright — so the result can
+ * never escape the mount directory.
+ *
+ * @param {readonly AssetMount[]} mounts
+ * @param {string} url - Site-absolute URL (e.g. `/content/docs/images/hero.png`)
+ * @returns {string | null}
+ */
+export function resolveAssetUrl(mounts: readonly AssetMount[], url: string): string | null {
+  const pathname = url.split("#")[0]!.split("?")[0]!;
+  if (!pathname.startsWith("/")) {
+    return null;
+  }
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  if (/%2e|%2f/i.test(decoded)) {
+    return null;
+  }
+  for (const mount of bySpecificity(mounts, "urlPrefix")) {
+    const prefix = normalizeAssetPrefix(mount.urlPrefix);
+    if (!decoded.startsWith(`${prefix}/`)) {
+      continue;
+    }
+    const rest = decoded.slice(prefix.length + 1);
+    const segments = rest.split("/");
+    if (segments.some((s) => s === "" || s === "." || s === "..")) {
+      return null;
+    }
+    return `${normalizeDir(mount.dir)}/${segments.join("/")}`;
+  }
+  return null;
+}
+
+/** Characters that terminate a URL inside markup: quotes, whitespace, CSS `url()` parens, `<>`. */
+const URL_TERMINATOR = String.raw`"'\s<>()\\`;
+
+/**
+ * Collect every mounted URL referenced by a compiled artifact (HTML, CSS, JSON-LD). Scanning output
+ * text rather than the document tree catches references wherever they came from — markdown images,
+ * hand-authored pages, `$head` metadata, `url()` in stylesheets — with no per-attribute knowledge.
+ *
+ * @param {string} text - Compiled HTML or CSS
+ * @param {readonly AssetMount[]} mounts
+ * @returns {string[]} Unique mounted URLs, in first-seen order
+ */
+export function collectAssetUrls(text: string, mounts: readonly AssetMount[]): string[] {
+  const found = new Set<string>();
+  for (const mount of mounts) {
+    const prefix = normalizeAssetPrefix(mount.urlPrefix);
+    const pattern = new RegExp(
+      `${prefix.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)}/[^${URL_TERMINATOR}]+`,
+      "g",
+    );
+    for (const match of text.matchAll(pattern)) {
+      const url = match[0].split("#")[0]!.split("?")[0]!;
+      // A trailing slash names a directory, not a file — prose quoting the mount prefix
+      // ("published under /content/docs/images/") is a mention, not a reference.
+      if (!url.endsWith("/")) {
+        found.add(url);
+      }
+    }
+  }
+  return [...found].filter(Boolean);
+}

package/src/extension-registry.ts

@@ -156,6 +156,11 @@ export class ExtensionRegistry {
     return this.#classes.filter((e) => e.capabilities.emit !== undefined);
   }
 
+  /** Classes declaring an `assets` capability (static asset mounts, §8.5), in declaration order. */
+  assetProviders(): FormatEntry[] {
+    return this.#classes.filter((e) => e.capabilities.assets !== undefined);
+  }
+
   /** Server-mount classes, sorted by `server.order` (ascending; default 100), then name. */
   serverMounts(): FormatEntry[] {
     return this.#classes

package/src/format-registry.ts

@@ -22,8 +22,8 @@ export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
 /**
  * All well-known static capability roles across admission blocks (specs/extensions.md §8): format
  * roles plus project-section (`projectData`, `resolvePaths`), compile-away (`lower`), build-time
- * asset emission (`emit`), server-mount (`mount`), and connector (`dialect`, `deploySchema`,
- * `bindings`, `testConnection`) roles.
+ * asset emission (`emit`), static asset mounts (`assets`), server-mount (`mount`), and connector
+ * (`dialect`, `deploySchema`, `bindings`, `testConnection`) roles.
  */
 export type ExtensionCapability =
   | FormatCapability
@@ -31,6 +31,7 @@ export type ExtensionCapability =
   | "resolvePaths"
   | "lower"
   | "emit"
+  | "assets"
   | "mount"
   | "dialect"
   | "deploySchema"
@@ -43,6 +44,7 @@ export const EXTENSION_CAPABILITIES: readonly ExtensionCapability[] = [
   "resolvePaths",
   "lower",
   "emit",
+  "assets",
   "mount",
   "dialect",
   "deploySchema",