@jxsuite/compiler 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -45,15 +45,16 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.5.0",
-    "@jxsuite/create": "^1.0.0",
-    "@jxsuite/runtime": "^1.0.0",
-    "@jxsuite/schema": "^1.0.0",
+    "@jxsuite/create": "^1.1.1",
+    "@jxsuite/runtime": "^1.2.0",
+    "@jxsuite/schema": "^1.2.0",
+    "esbuild": "^0.28.1",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",
-    "@jxsuite/connector": "^0.2.0",
-    "@jxsuite/parser": "^1.0.0",
+    "@jxsuite/connector": "^0.3.1",
+    "@jxsuite/parser": "^1.2.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/cli.ts

@@ -23,6 +23,8 @@ async function main() {
 
 Commands:
   build [root]     Build a Jx site to dist/
+  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
   db push [root]   Sync the data section's tables to their connections (additive-only)
@@ -30,6 +32,7 @@ Commands:
 Options:
   --verbose      Print detailed build progress
   --no-clean     Don't clean outDir before building
+  --port <n>     dev/preview: port to listen on (default 3000 / 4173)
   --dry-run      db push: print the statements without executing them
   --connection   db push: restrict to one connection name`);
     process.exit(0);
@@ -42,11 +45,18 @@ Options:
   const flags = new Set<string>();
   const positionals: string[] = [];
   let connectionArg: string | undefined;
+  let portArg: number | undefined;
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index]!;
     if (arg === "--connection") {
       index += 1;
       connectionArg = rest[index];
+    } else if (arg === "--port") {
+      index += 1;
+      const parsed = Math.trunc(Number(rest[index] ?? ""));
+      if (Number.isFinite(parsed) && parsed >= 0) {
+        portArg = parsed;
+      }
     } else if (arg.startsWith("--")) {
       flags.add(arg);
     } else {
@@ -118,6 +128,26 @@ Options:
       console.error(`Build failed: ${err.message}`);
       process.exit(1);
     }
+  } else if (command === "dev") {
+    try {
+      const { runDev } = await import("./site/dev-command.ts");
+      runDev(projectRoot, portArg);
+    } catch (error) {
+      const err = error as Error;
+      console.error(err.message);
+      process.exit(1);
+    }
+  } else if (command === "preview") {
+    const { existsSync } = await import("node:fs");
+    const distDir = resolve(projectRoot, "dist");
+    if (!existsSync(distDir)) {
+      console.error(`No build output at ${distDir} — run \`jx build\` first.`);
+      process.exit(1);
+    }
+    const { startPreviewServer } = await import("./site/preview-server.ts");
+    const port = portArg ?? 4173;
+    startPreviewServer(distDir, port);
+    console.log(`Previewing ${distDir} at http://localhost:${port}`);
   } else if (command === "schema") {
     try {
       const { writeProjectSchemas } = await import("./site/schema-command.ts");

package/src/compiler.ts

@@ -46,6 +46,13 @@ export interface CompileOptions {
   litHtmlSrc?: string;
   projectStyle?: JxStyle | null;
   formats?: FormatRegistry;
+  /** Rewrite Function-def `$src` specifiers to served URLs (see CompileElementOptions). */
+  rewriteSrc?: (specifier: string) => string;
+  /**
+   * Inject the color-scheme pre-paint script when `$media` declares a pure scheme query (default
+   * true). The site pipeline disables this and injects via the merged <head> instead.
+   */
+  prePaintScheme?: boolean;
   [key: string]: unknown;
 }
 
@@ -107,6 +114,8 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
       litHtmlSrc,
       projectStyle,
       reactivitySrc,
+      ...(opts.prePaintScheme === false ? { prePaintScheme: false } : {}),
+      ...(opts.rewriteSrc ? { rewriteSrc: opts.rewriteSrc } : {}),
       title,
     });
   }
@@ -115,7 +124,7 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
   if (raw.tagName && raw.tagName.includes("-")) {
     const { tagName } = raw;
     const className = tagNameToClassName(tagName);
-    const moduleContent = emitElementModule(raw, className, []);
+    const moduleContent = emitElementModule(raw, className, [], opts.rewriteSrc);
     const moduleFile = {
       content: moduleContent,
       path: `${tagName}.js`,
@@ -149,7 +158,14 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
   }
 
   // Route 3: Dynamic with standard tagName → pre-rendered HTML + reactive bindings
-  return compileClient(raw, { litHtmlSrc, projectStyle, reactivitySrc, title });
+  return compileClient(raw, {
+    litHtmlSrc,
+    projectStyle,
+    reactivitySrc,
+    ...(opts.prePaintScheme === false ? { prePaintScheme: false } : {}),
+    ...(opts.rewriteSrc ? { rewriteSrc: opts.rewriteSrc } : {}),
+    title,
+  });
 }
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────

package/src/shared.ts

@@ -6,13 +6,24 @@
  * compilation targets (static, client, element, server).
  */
 
-import { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
+import {
+  COLOR_SCHEME_ATTR,
+  COLOR_SCHEME_STORAGE_KEY,
+  RESERVED_KEYS,
+  camelToKebab,
+  pureSchemeOf,
+  schemeSelectors,
+  toCSSText,
+} from "@jxsuite/runtime";
 import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { runStatements } from "@jxsuite/runtime/statements";
 import {
   childrenContainArray,
+  hasStructuredBody,
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
+  isNamedFormulaDef,
   isPrototypeDef,
   isRef,
   isSchemaOnlyDef as isSchemaOnly,
@@ -33,8 +44,38 @@ import type {
 } from "@jxsuite/schema/types";
 
 // Re-export runtime utilities used by submodules
-export { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
+export {
+  COLOR_SCHEME_ATTR,
+  COLOR_SCHEME_STORAGE_KEY,
+  RESERVED_KEYS,
+  camelToKebab,
+  pureSchemeOf,
+  schemeSelectors,
+  toCSSText,
+} from "@jxsuite/runtime";
 export { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+export { compileStatements, runStatements } from "@jxsuite/runtime/statements";
+
+/**
+ * Emit the JS source of a named formula's scope callable: positional arguments are mapped onto the
+ * declared parameter names (honoring CemParameter defaults) as the `_args` object the compiled
+ * body's `$args/` refs read from. Call sites stay positional, matching the interpreter.
+ */
+export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: string): string {
+  const entries: string[] = [];
+  for (const [i, p] of (def.parameters ?? []).entries()) {
+    const name = typeof p === "string" ? p : ((p as { name?: string } | null)?.name ?? "");
+    if (!name) {
+      continue;
+    }
+    const hasDefault = typeof p === "object" && p !== null && "default" in p;
+    const arg = hasDefault
+      ? `_a[${i}] === undefined ? ${JSON.stringify((p as { default?: unknown }).default)} : _a[${i}]`
+      : `_a[${i}]`;
+    entries.push(`${JSON.stringify(name)}: ${arg}`);
+  }
+  return `(..._a) => { const _args = { ${entries.join(", ")} }; return ${compiledBody}; }`;
+}
 export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
 // CDN defaults
@@ -283,7 +324,24 @@ export function buildInitialScope(
     }
     if (isExpressionDef(def)) {
       const node = def.$expression as ExpressionNode;
-      if (isMutating(node.operator)) {
+      if (isNamedFormulaDef(def)) {
+        // Named formula: callable, positional args mapped onto its declared parameters.
+        const params = def.parameters as (string | { name?: string; default?: unknown })[];
+        setOwnScopeValue(scope, key, (...argValues: unknown[]) => {
+          const args: Record<string, unknown> = {};
+          for (const [i, p] of params.entries()) {
+            const name = typeof p === "string" ? p : (p?.name ?? "");
+            if (!name) {
+              continue;
+            }
+            args[name] =
+              argValues[i] === undefined && typeof p === "object" && p !== null && "default" in p
+                ? p.default
+                : argValues[i];
+          }
+          return evaluateExpression(node, scope, null, { args });
+        });
+      } else if (isMutating(node.operator)) {
         setOwnScopeValue(scope, key, (s: Record<string, unknown>, event: Event) =>
           evaluateExpression(node, s, event),
         );
@@ -293,12 +351,19 @@ export function buildInitialScope(
       continue;
     }
     if (isFunctionDef(def)) {
-      if (def.body) {
+      if (hasStructuredBody(def)) {
+        // Structured body (spec §20): a side-effecting handler in the build-time scope.
+        const { body } = def;
+        setOwnScopeValue(scope, key, (s: Record<string, unknown>, event?: Event) => {
+          void runStatements(body, s ?? scope, event ?? null);
+        });
+      } else if (typeof def.body === "string") {
         const names = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
-        const fn = new Function("state", ...names, def.body) as (
+        const { body } = def;
+        const fn = new Function("state", ...names, body) as (
           state: Record<string, unknown>,
         ) => unknown;
-        if (def.body.includes("return")) {
+        if (body.includes("return")) {
           defineLazyScopeValue(scope, key, () => fn(scope));
         } else {
           setOwnScopeValue(scope, key, fn);
@@ -593,6 +658,94 @@ export function buildInner(
 
 // ─── CSS extraction ───────────────────────────────────────────────────────────
 
+/**
+ * The inline pre-paint script injected into <head> when a project declares a pure color-scheme
+ * media query: restores the visitor's persisted forced scheme before first paint (no FOUC).
+ *
+ * @returns {string}
+ * @docs framework/concepts/color-schemes
+ */
+export function colorSchemePrePaintScript(): string {
+  const key = JSON.stringify(COLOR_SCHEME_STORAGE_KEY);
+  const attr = JSON.stringify(COLOR_SCHEME_ATTR);
+  return `(function(){try{var s=localStorage.getItem(${key});if(s==="light"||s==="dark"){document.documentElement.setAttribute(${attr},s)}}catch(e){}})()`;
+}
+
+/**
+ * Resolve an `@`-prefixed style key into an emit function that pushes conditional rules. Pure
+ * color-scheme queries dual-emit per the forced-scheme contract (spec §9.5): a media-guarded copy
+ * that applies while no scheme is forced plus an unconditional copy under the forced root
+ * attribute.
+ *
+ * @param {string} atKey
+ * @param {Record<string, string>} mediaQueries
+ * @param {string[]} rules
+ * @returns {(selector: string, props: string) => void}
+ * @docs framework/concepts/color-schemes
+ */
+function conditionalRuleEmitter(
+  atKey: string,
+  mediaQueries: Record<string, string>,
+  rules: string[],
+): (selector: string, props: string) => void {
+  const query = atKey.startsWith("@--")
+    ? (mediaQueries[atKey.slice(1)] ?? atKey.slice(1))
+    : atKey.startsWith("@(")
+      ? atKey.slice(1)
+      : null;
+  const atRule = query === null ? atKey : `@media ${query}`;
+  const scheme = query === null ? null : pureSchemeOf(query);
+  return (selector: string, props: string) => {
+    if (!props) {
+      return;
+    }
+    if (scheme) {
+      const { auto, forced } = schemeSelectors(selector, scheme);
+      rules.push(`${atRule} { ${auto} { ${props} } }`, `${forced} { ${props} }`);
+    } else {
+      rules.push(`${atRule} { ${selector} { ${props} } }`);
+    }
+  };
+}
+
+/**
+ * Push the rules for one `@`-prefixed style block scoped to `selector`: flat props plus one level
+ * of nested selectors, routed through conditionalRuleEmitter (scheme-aware).
+ *
+ * @param {string[]} rules
+ * @param {string} atKey
+ * @param {Record<string, string>} mediaQueries
+ * @param {string} selector
+ * @param {Record<string, unknown>} obj
+ */
+function pushConditionalRule(
+  rules: string[],
+  atKey: string,
+  mediaQueries: Record<string, string>,
+  selector: string,
+  obj: Record<string, unknown>,
+) {
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+    return;
+  }
+  const emit = conditionalRuleEmitter(atKey, mediaQueries, rules);
+  emit(selector, toCSSText(obj));
+  for (const [sel, sub] of Object.entries(obj)) {
+    if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
+      continue;
+    }
+    if (sel.startsWith("@")) {
+      continue;
+    }
+    const resolved = sel.startsWith("&")
+      ? sel.replace("&", selector)
+      : sel.startsWith(":") || sel.startsWith(".") || sel.startsWith("[")
+        ? `${selector}${sel}`
+        : `${selector} ${sel}`;
+    emit(resolved, toCSSText(sub));
+  }
+}
+
 /**
  * Walk the entire document tree and collect all static nested CSS rules.
  *
@@ -622,30 +775,7 @@ export function compileStyles(
           continue;
         }
         if (key.startsWith("@")) {
-          const atRule = key.startsWith("@--")
-            ? `@media ${mediaQueries[key.slice(1)] ?? key.slice(1)}`
-            : key;
-          const mProps = toCSSText(val);
-          if (mProps) {
-            rules.push(`${atRule} { ${selector} { ${mProps} } }`);
-          }
-          for (const [sel, sub] of Object.entries(val as Record<string, unknown>)) {
-            if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
-              continue;
-            }
-            if (sel.startsWith("@")) {
-              continue;
-            }
-            const resolved = sel.startsWith("&")
-              ? sel.replace("&", selector)
-              : sel.startsWith(":") || sel.startsWith(".") || sel.startsWith("[")
-                ? `${selector}${sel}`
-                : `${selector} ${sel}`;
-            const subProps = toCSSText(sub);
-            if (subProps) {
-              rules.push(`${atRule} { ${resolved} { ${subProps} } }`);
-            }
-          }
+          pushConditionalRule(rules, key, mediaQueries, selector, val as Record<string, unknown>);
           continue;
         }
         const resolved = key.startsWith("&")
@@ -657,27 +787,6 @@ export function compileStyles(
       }
     };
 
-    for (const [key, val] of Object.entries(projectStyle)) {
-      if (key.startsWith(":") || key.startsWith(".") || key.startsWith("[")) {
-        emitProjectRules(key, val as Record<string, unknown>);
-      } else if (
-        val !== null &&
-        typeof val === "object" &&
-        !Array.isArray(val) &&
-        !key.startsWith("@") &&
-        !key.startsWith("--")
-      ) {
-        emitProjectRules(key, val as Record<string, unknown>);
-      } else if (key.startsWith("@")) {
-        // @media block at top level
-        const atRule = key.startsWith("@--")
-          ? `@media ${mediaQueries[key.slice(1)] ?? key.slice(1)}`
-          : key.startsWith("@(")
-            ? `@media ${key.slice(1)}`
-            : key;
-        rules.push(`${atRule} { body { ${toCSSText(val as Record<string, unknown>)} } }`);
-      }
-    }
     // Collect CSS custom properties into :root {}
     const rootProps: Record<string, unknown> = {};
     // Collect direct CSS properties into body {}
@@ -700,6 +809,7 @@ export function compileStyles(
         bodyProps[key] = val;
       }
     }
+    // Base rules precede conditional blocks so equal-specificity overrides win by source order.
     const rootCSS = toCSSText(rootProps);
     if (rootCSS) {
       rules.push(`:root { ${rootCSS} }`);
@@ -708,6 +818,62 @@ export function compileStyles(
     if (bodyCSS) {
       rules.push(`body { ${bodyCSS} }`);
     }
+
+    for (const [key, val] of Object.entries(projectStyle)) {
+      if (key.startsWith(":") || key.startsWith(".") || key.startsWith("[")) {
+        emitProjectRules(key, val as Record<string, unknown>);
+      } else if (
+        val !== null &&
+        typeof val === "object" &&
+        !Array.isArray(val) &&
+        !key.startsWith("@") &&
+        !key.startsWith("--")
+      ) {
+        emitProjectRules(key, val as Record<string, unknown>);
+      } else if (
+        key.startsWith("@") &&
+        val !== null &&
+        typeof val === "object" &&
+        !Array.isArray(val)
+      ) {
+        // Conditional block at project top level: custom properties override :root, direct
+        // Properties override body, selector-keyed sub-objects their own selector.
+        const emit = conditionalRuleEmitter(key, mediaQueries, rules);
+        const condRoot: Record<string, unknown> = {};
+        const condBody: Record<string, unknown> = {};
+        const condSubs: [string, Record<string, unknown>][] = [];
+        for (const [k, v] of Object.entries(val as Record<string, unknown>)) {
+          if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+            if (!k.startsWith("@")) {
+              condSubs.push([k, v as Record<string, unknown>]);
+            }
+            continue;
+          }
+          if (k.startsWith("--")) {
+            condRoot[k] = v;
+          } else {
+            condBody[k] = v;
+          }
+        }
+        emit(":root", toCSSText(condRoot));
+        emit("body", toCSSText(condBody));
+        for (const [sel, sub] of condSubs) {
+          emit(sel, toCSSText(sub));
+        }
+      }
+    }
+  }
+
+  // Forced-scheme UA hint: native widgets follow the forced attribute, not only the OS scheme.
+  if (
+    Object.values(mediaQueries).some((q) => pureSchemeOf(q) !== null) &&
+    !(projectStyle && typeof projectStyle === "object" && "colorScheme" in projectStyle)
+  ) {
+    rules.push(
+      ":root { color-scheme: light dark }",
+      `:root:where([${COLOR_SCHEME_ATTR}="light"]) { color-scheme: light }`,
+      `:root:where([${COLOR_SCHEME_ATTR}="dark"]) { color-scheme: dark }`,
+    );
   }
 
   const counter = { n: 0 };
@@ -741,32 +907,7 @@ function emitNestedElement(
       continue;
     }
     if (key.startsWith("@")) {
-      const atRule = key.startsWith("@--")
-        ? `@media ${mediaQueries[key.slice(1)] ?? key.slice(1)}`
-        : key.startsWith("@(")
-          ? `@media ${key.slice(1)}`
-          : key;
-      const mProps = toCSSText(val);
-      if (mProps) {
-        rules.push(`${atRule} { ${selector} { ${mProps} } }`);
-      }
-      for (const [sel, sub] of Object.entries(val as Record<string, unknown>)) {
-        if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
-          continue;
-        }
-        if (sel.startsWith("@")) {
-          continue;
-        }
-        const resolved = sel.startsWith("&")
-          ? sel.replace("&", selector)
-          : sel.startsWith(":") || sel.startsWith(".") || sel.startsWith("[")
-            ? `${selector}${sel}`
-            : `${selector} ${sel}`;
-        const subProps = toCSSText(sub);
-        if (subProps) {
-          rules.push(`${atRule} { ${resolved} { ${subProps} } }`);
-        }
-      }
+      pushConditionalRule(rules, key, mediaQueries, selector, val as Record<string, unknown>);
       continue;
     }
     const resolved = key.startsWith("&")
@@ -838,35 +979,7 @@ export function collectStyles(
         continue;
       }
       if (prop.startsWith("@")) {
-        const atRule = prop.startsWith("@--")
-          ? `@media ${mediaQueries[prop.slice(1)] ?? prop.slice(1)}`
-          : prop.startsWith("@(")
-            ? `@media ${prop.slice(1)}`
-            : prop;
-        const atBaseProps = toCSSText(val);
-        if (atBaseProps) {
-          rules.push(`${atRule} { ${selector} { ${atBaseProps} } }`);
-        }
-        for (const [sel, nestedRules] of Object.entries(
-          /** @type {Record<string, unknown>} */ val,
-        )) {
-          if (
-            nestedRules === null ||
-            typeof nestedRules !== "object" ||
-            Array.isArray(nestedRules)
-          ) {
-            continue;
-          }
-          if (sel.startsWith("@")) {
-            continue;
-          }
-          const resolved = sel.startsWith("&")
-            ? sel.replace("&", selector)
-            : sel.startsWith(":") || sel.startsWith(".") || sel.startsWith("[")
-              ? `${selector}${sel}`
-              : `${selector} ${sel}`;
-          rules.push(`${atRule} { ${resolved} { ${toCSSText(nestedRules)} } }`);
-        }
+        pushConditionalRule(rules, prop, mediaQueries, selector, val as Record<string, unknown>);
       } else {
         const resolved = prop.startsWith("&")
           ? prop.replace("&", selector)
@@ -1276,12 +1389,7 @@ export function buildComponentCSS(
 
     for (const [prop, val] of Object.entries(styleDef)) {
       if (prop.startsWith("@")) {
-        const atRule = prop.startsWith("@--")
-          ? `@media ${mediaQueries[prop.slice(1)] ?? prop.slice(1)}`
-          : prop.startsWith("@(")
-            ? `@media ${prop.slice(1)}`
-            : prop;
-        rules.push(`${atRule} { ${tagName} { ${toCSSText(val as Record<string, unknown>)} } }`);
+        pushConditionalRule(rules, prop, mediaQueries, tagName, val as Record<string, unknown>);
       } else if (
         prop.startsWith(":") ||
         prop.startsWith(".") ||