@jxsuite/schema 1.2.0 → 1.4.0

package/schemas/project.core.schema.json

@@ -105,6 +105,24 @@
       },
       "required": ["$ref"],
       "type": "object"
+    },
+    "StyleObject": {
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "number"
+          },
+          {
+            "$ref": "#/$defs/StyleObject"
+          }
+        ]
+      },
+      "description": "CSS style definition. camelCase property names follow CSSOM convention. Keys starting with :, ., &, or [ are treated as nested CSS selectors. Keys matching $media breakpoint names (or other @-prefixed at-rules) group nested rules. Nesting is recursive: selector and at-rule groups may nest to arbitrary depth (e.g. breakpoint → selector → pseudo-class), mirroring the compiler's recursive emission.",
+      "properties": {},
+      "type": "object"
     }
   },
   "$id": "https://jxsuite.com/schema/project/core/v2",
@@ -366,11 +384,11 @@
             "type": "number"
           },
           {
-            "type": "object"
+            "$ref": "#/$defs/StyleObject"
           }
         ]
       },
-      "description": "Global CSS styles applied to the <body> element. Uses the same camelCase CSSOM convention as component styles.",
+      "description": "Global CSS styles applied to the <body> element. Uses the same camelCase CSSOM convention and recursive selector/at-rule nesting as component styles.",
       "type": "object"
     },
     "url": {

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",

package/src/guards.ts

@@ -174,6 +174,16 @@ export function isTemplateString(value?: unknown): value is string {
   return typeof value === "string" && value.includes("${");
 }
 
+/**
+ * Whether a function `body` returns a value — the heuristic that classifies a `$prototype:
+ * "Function"` as a computed value vs an event handler. Uses a word boundary so identifiers like
+ * `returned` do not match. Shared by the runtime interpreter and the compiler so both agree on the
+ * classification.
+ */
+export function bodyReturnsValue(body: string): boolean {
+  return /\breturn\b/.test(body);
+}
+
 // ─── Style guards & accessors ───────────────────────────────────────────────────
 
 /** A nested style object (selector/media block), as opposed to a scalar CSS value. */

package/src/schema.ts

@@ -92,7 +92,10 @@ import {
   classFieldDefSchema,
   classMethodDefSchema,
   classParameterDefSchema,
+  connectorBlockDefSchema,
   formatDefSchema,
+  projectBlockDefSchema,
+  serverBlockDefSchema,
   studioHintsSchema,
 } from "../defs/class-def.schema";
 import { extensionManifestSchema } from "../defs/extension-manifest.schema";
@@ -182,7 +185,11 @@ function buildEventHandlerProperties(eventHandlers: string[]) {
   for (const name of eventHandlers) {
     properties[name] = {
       description: `Event handler for the "${name.slice(2)}" event.`,
-      oneOf: [{ $ref: "#/$defs/RefObject" }, { $ref: "#/$defs/ExpressionEntry" }],
+      oneOf: [
+        { $ref: "#/$defs/RefObject" },
+        { $ref: "#/$defs/ExpressionEntry" },
+        { $ref: "#/$defs/FunctionDef" },
+      ],
     };
   }
   return properties;
@@ -216,6 +223,9 @@ export async function generateSchema() {
       ClassConstructorDef: classConstructorDefSchema,
       ClassMethodDef: classMethodDefSchema,
       FormatDef: formatDefSchema,
+      ProjectBlockDef: projectBlockDefSchema,
+      ServerBlockDef: serverBlockDefSchema,
+      ConnectorBlockDef: connectorBlockDefSchema,
       StudioHints: studioHintsSchema,
       ExternalClassDef: externalClassDefSchema,
       ExpressionPointer: expressionPointerSchema,
@@ -415,6 +425,7 @@ export function generateProjectSchema() {
   return {
     $defs: {
       ImageConfig: imageConfigSchema,
+      StyleObject: styleObjectSchema,
     },
     $id: "https://jxsuite.com/schema/project/v1",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -446,6 +457,7 @@ export function generateProjectCoreSchema() {
       ImageConfig: imageConfigSchema,
       JxFieldSchema: jxFieldSchemaDef,
       RelationshipRef: relationshipRefSchema,
+      StyleObject: styleObjectSchema,
     },
     $id: "https://jxsuite.com/schema/project/core/v2",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -514,7 +526,10 @@ export function generateClassSchema() {
       ClassFieldDef: classFieldDefSchema,
       ClassMethodDef: classMethodDefSchema,
       ClassParameterDef: classParameterDefSchema,
+      ConnectorBlockDef: connectorBlockDefSchema,
       FormatDef: formatDefSchema,
+      ProjectBlockDef: projectBlockDefSchema,
+      ServerBlockDef: serverBlockDefSchema,
       StudioHints: studioHintsSchema,
     },
     $id: "https://jxsuite.com/schema/class/v1",
@@ -565,6 +580,7 @@ export function generateClassSchema() {
       },
       $schema: { type: "string" },
       $studio: { $ref: "#/$defs/StudioHints" },
+      connector: { $ref: "#/$defs/ConnectorBlockDef" },
       description: { type: "string" },
       extends: {
         description: "Base class — string name or $ref to another .class.json.",
@@ -579,6 +595,8 @@ export function generateClassSchema() {
         ],
       },
       format: { $ref: "#/$defs/FormatDef" },
+      project: { $ref: "#/$defs/ProjectBlockDef" },
+      server: { $ref: "#/$defs/ServerBlockDef" },
       title: {
         description: "PascalCase class name, used as the export name.",
         examples: ["MarkdownFile", "DataSource", "Calculator"],
@@ -613,7 +631,19 @@ type AjvCtor = new (opts: {
 }) => AjvInstance;
 type AddFormatsFn = (ajv: AjvInstance) => void;
 
-export async function validateDocument(doc: Record<string, unknown>) {
+/**
+ * Validate a document against an arbitrary JSON Schema 2020-12 document (e.g. a bundled per-project
+ * document.schema.json from `jx schema`). The schema must be self-contained — external refs are not
+ * resolved here.
+ *
+ * @param {Record<string, unknown>} doc - The document to validate
+ * @param {Record<string, unknown>} schema - A self-contained 2020-12 schema
+ * @returns {Promise<{ errors: unknown[] | null; valid: boolean }>}
+ */
+export async function validateWithSchema(
+  doc: Record<string, unknown>,
+  schema: Record<string, unknown>,
+) {
   let Ajv: AjvCtor, addFormats: AddFormatsFn;
   try {
     // The generated schema is JSON Schema 2020-12, so use the matching Ajv build
@@ -628,13 +658,21 @@ export async function validateDocument(doc: Record<string, unknown>) {
   const ajv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
   addFormats(ajv);
 
-  const schema = await generateSchema();
   const validate = ajv.compile(schema);
   const valid = validate(doc);
 
   return { errors: validate.errors ?? null, valid };
 }
 
+export async function validateDocument(doc: Record<string, unknown>) {
+  return validateWithSchema(doc, (await generateSchema()) as Record<string, unknown>);
+}
+
+/** Validate a .class.json class definition against the generated class schema. */
+export async function validateClass(doc: Record<string, unknown>) {
+  return validateWithSchema(doc, generateClassSchema() as Record<string, unknown>);
+}
+
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
 async function runSchemaCli() {

package/src/validate-project.ts

@@ -133,6 +133,19 @@ async function loadProjectSchemaRef(uri: string, root: string): Promise<Record<s
       const selfRequire = createRequire(import.meta.url);
       resolved = selfRequire.resolve(specifier);
     } catch (error) {
+      // Exports-map subpath resolution is brittle against version-skewed shadowing installs (a
+      // Stale local copy terminates Node's walk-up with ERR_PACKAGE_PATH_NOT_EXPORTED). Our own
+      // Schema files are pure data and the running validator's copy is guaranteed to match, so
+      // Read them straight off this package's disk as the last resort.
+      const ownPrefix = "@jxsuite/schema/";
+      if (specifier.startsWith(ownPrefix)) {
+        const ownFile = fileURLToPath(
+          new URL(`../${specifier.slice(ownPrefix.length)}`, import.meta.url),
+        );
+        if (existsSync(ownFile)) {
+          return JSON.parse(readFileSync(ownFile, "utf8")) as Record<string, unknown>;
+        }
+      }
       throw new Error(
         `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
           `project or the host`,