x4js 2.2.74 → 2.3.1

package/bin/x4js.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../cli/main.mjs";

package/cli/build-options.mjs

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { sassPlugin } from "esbuild-sass-plugin";
+import { lessPlugin } from "./less-plugin.mjs";
+import { copyPlugin } from "./copy-plugin.mjs";
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url));
+const devClient = path.join(cliDir, "dev-client.js");
+
+function versionId() {
+    const now = new Date();
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${pad(now.getFullYear() - 2000)}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+}
+
+export function createBuildOptions(config, mode) {
+    const production = mode === "production";
+    const dev = mode === "dev";
+
+    const defaults = {
+        absWorkingDir: config.root,
+        entryPoints: config.entryPoints,
+        outdir: config.outdir,
+        bundle: true,
+        charset: "utf8",
+        keepNames: true,
+        platform: "browser",
+        format: "iife",
+        target: "es2020",
+        minify: production,
+        sourcemap: production ? false : "inline",
+        logLevel: "info",
+        external: config.external,
+        assetNames: "assets/[name]-[hash]",
+        loader: {
+            ".svg": "dataurl",
+            ".jpg": "file",
+            ".jpeg": "file",
+            ".png": "file",
+            ".ttf": "file",
+            ".woff": "file",
+            ".woff2": "file",
+        },
+        define: {
+            ...config.define,
+            DEBUG_MODE: production ? "false" : "true",
+            VERSION_ID: versionId(),
+        },
+        plugins: [
+            sassPlugin({
+                type: "css",
+                filter: /\.s[ac]ss$/,
+            }),
+            lessPlugin(config.root),
+            copyPlugin(config, { dev }),
+        ],
+    };
+
+    if (dev)
+        defaults.inject = [devClient];
+
+    // x4.esbuild is intentionally last: it is the escape hatch for projects
+    // that need native esbuild options not modeled by x4js.
+    return {
+        ...defaults,
+        ...config.esbuild,
+    };
+}

package/cli/build.mjs

@@ -0,0 +1,33 @@
+import fs from "node:fs/promises";
+import { parseArgs } from "node:util";
+import esbuild from "esbuild";
+import { loadConfig } from "./config.mjs";
+import { createBuildOptions } from "./build-options.mjs";
+import { info, success } from "./log.mjs";
+
+export async function build(argv = [], root = process.cwd()) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            debug: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+
+    if (positionals.length)
+        throw new Error(`Unexpected argument: ${positionals[0]}`);
+
+    const config = loadConfig(root);
+    const mode = values.debug ? "debug" : "production";
+
+    info("mode", mode);
+    info("outdir", config.outdir);
+
+    await fs.rm(config.outdir, { recursive: true, force: true });
+    await fs.mkdir(config.outdir, { recursive: true });
+
+    const started = performance.now();
+    await esbuild.build(createBuildOptions(config, mode));
+    success("built", `${Math.round(performance.now() - started)}ms`);
+}

package/cli/config.mjs

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULTS = Object.freeze({
+    entryPoints: ["src/main.ts"],
+    outdir: "./bin",
+    copy: [],
+    external: [],
+    define: {},
+    dev: {
+        host: "127.0.0.1",
+        port: 8000,
+        https: false,
+    },
+});
+
+export function expandEnv(value, env = process.env) {
+    if (typeof value !== "string")
+        return value;
+
+    return value.replace(
+        /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g,
+        (_, braced, plain) => {
+            const name = braced ?? plain;
+            const result = env[name];
+            if (result === undefined)
+                throw new Error(`Environment variable '${name}' is not defined`);
+            return result;
+        },
+    );
+}
+
+export function resolvePath(root, value, env = process.env) {
+    const expanded = expandEnv(value, env);
+    return path.isAbsolute(expanded)
+        ? path.normalize(expanded)
+        : path.resolve(root, expanded);
+}
+
+function validateCopy(copy) {
+    if (!Array.isArray(copy))
+        throw new Error("x4.copy must be an array");
+
+    for (const item of copy) {
+        if (!item || typeof item !== "object" || typeof item.from !== "string" || typeof item.to !== "string")
+            throw new Error("Each x4.copy entry must contain string 'from' and 'to' fields");
+        if (path.isAbsolute(item.to))
+            throw new Error(`x4.copy destination must be relative to outdir: '${item.to}'`);
+        const normalized = path.normalize(item.to);
+        if (normalized === ".." || normalized.startsWith(`..${path.sep}`))
+            throw new Error(`x4.copy destination escapes outdir: '${item.to}'`);
+    }
+}
+
+export function loadConfig(root = process.cwd(), env = process.env) {
+    root = path.resolve(root);
+    const packageFile = path.join(root, "package.json");
+
+    if (!fs.existsSync(packageFile))
+        throw new Error(`Cannot find package.json in '${root}'`);
+
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read package.json: ${error.message}`);
+    }
+
+    const cfg = pkg.x4 ?? {};
+    if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg))
+        throw new Error("package.json field 'x4' must be an object");
+
+    const entryPoints = cfg.entryPoints ?? DEFAULTS.entryPoints;
+    if (!Array.isArray(entryPoints) || !entryPoints.length || entryPoints.some((entry) => typeof entry !== "string"))
+        throw new Error("x4.entryPoints must be a non-empty array of strings");
+
+    const copy = cfg.copy ?? DEFAULTS.copy;
+    validateCopy(copy);
+
+    const external = cfg.external ?? DEFAULTS.external;
+    if (!Array.isArray(external) || external.some((entry) => typeof entry !== "string"))
+        throw new Error("x4.external must be an array of strings");
+
+    const define = cfg.define ?? DEFAULTS.define;
+    if (!define || typeof define !== "object" || Array.isArray(define))
+        throw new Error("x4.define must be an object");
+    if (Object.values(define).some((value) => typeof value !== "string"))
+        throw new Error("x4.define values must be strings containing esbuild define expressions");
+
+    const devCfg = cfg.dev ?? {};
+    if (!devCfg || typeof devCfg !== "object" || Array.isArray(devCfg))
+        throw new Error("x4.dev must be an object");
+
+    const host = devCfg.host ?? DEFAULTS.dev.host;
+    if (typeof host !== "string" || !host)
+        throw new Error("x4.dev.host must be a non-empty string");
+
+    const port = devCfg.port ?? DEFAULTS.dev.port;
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error("x4.dev.port must be an integer between 0 and 65535");
+
+    const https = devCfg.https ?? DEFAULTS.dev.https;
+    if (typeof https !== "boolean")
+        throw new Error("x4.dev.https must be a boolean");
+
+    if (devCfg.tls !== undefined) {
+        if (!devCfg.tls || typeof devCfg.tls !== "object" || Array.isArray(devCfg.tls))
+            throw new Error("x4.dev.tls must be an object");
+        if (typeof devCfg.tls.cert !== "string" || typeof devCfg.tls.key !== "string")
+            throw new Error("x4.dev.tls requires string 'cert' and 'key' fields");
+    }
+
+    const outdirRaw = cfg.outdir ?? DEFAULTS.outdir;
+    if (typeof outdirRaw !== "string")
+        throw new Error("x4.outdir must be a string");
+
+    const outdir = resolvePath(root, outdirRaw, env);
+    if (outdir === root)
+        throw new Error("x4.outdir cannot be the project root");
+    if (outdir === path.parse(outdir).root)
+        throw new Error("x4.outdir cannot be a filesystem root");
+
+    return {
+        root,
+        packageFile,
+        package: pkg,
+        entryPoints: entryPoints.map((entry) => resolvePath(root, entry, env)),
+        outdir,
+        copy: copy.map((item) => ({
+            from: resolvePath(root, item.from, env),
+            to: path.normalize(item.to),
+        })),
+        external: [...external],
+        define: { ...define },
+        dev: {
+            host,
+            port,
+            https,
+            tls: devCfg.tls ? { ...devCfg.tls } : undefined,
+        },
+        esbuild: (() => {
+            if (cfg.esbuild === undefined)
+                return {};
+            if (!cfg.esbuild || typeof cfg.esbuild !== "object" || Array.isArray(cfg.esbuild))
+                throw new Error("x4.esbuild must be an object");
+            return { ...cfg.esbuild };
+        })(),
+    };
+}
+
+export function resolveTls(config, env = process.env) {
+    const tls = config.dev.tls;
+    if (!tls)
+        throw new Error("HTTPS is enabled but x4.dev.tls.cert/key are not configured");
+
+    const certfile = resolvePath(config.root, tls.cert, env);
+    const keyfile = resolvePath(config.root, tls.key, env);
+
+    if (!fs.existsSync(certfile))
+        throw new Error(`TLS certificate not found: ${certfile}`);
+    if (!fs.existsSync(keyfile))
+        throw new Error(`TLS private key not found: ${keyfile}`);
+
+    return { certfile, keyfile };
+}

package/cli/copy-plugin.mjs

@@ -0,0 +1,115 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+async function walk(source) {
+    const files = [];
+    const dirs = [];
+
+    async function visit(current) {
+        const stat = await fs.stat(current);
+        if (!stat.isDirectory()) {
+            files.push({ path: current, stat });
+            return;
+        }
+
+        dirs.push(current);
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries)
+            await visit(path.join(current, entry.name));
+    }
+
+    try {
+        await visit(source);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+
+    return { files, dirs, isDirectory: dirs.includes(source) };
+}
+
+function destinationFor(entry, sourceFile) {
+    if (!entry.sourceIsDirectory)
+        return entry.destRoot;
+    return path.join(entry.destRoot, path.relative(entry.from, sourceFile));
+}
+
+export function copyPlugin(config, { dev = false } = {}) {
+    const entries = config.copy.map((entry) => ({
+        ...entry,
+        destRoot: path.resolve(config.outdir, entry.to),
+    }));
+    let previousDestinations = new Set();
+    let snapshot = { files: [], dirs: [], fingerprint: "0" };
+
+    async function scan() {
+        const files = [];
+        const dirs = [];
+        const fingerprint = [];
+
+        for (const entry of entries) {
+            const result = await walk(entry.from);
+            entry.sourceIsDirectory = result.isDirectory;
+            dirs.push(...result.dirs);
+            for (const item of result.files) {
+                files.push({ entry, ...item });
+                fingerprint.push(`${item.path}\0${item.stat.size}\0${item.stat.mtimeMs}`);
+            }
+        }
+
+        snapshot = {
+            files,
+            dirs,
+            fingerprint: fingerprint.sort().join("\n"),
+        };
+    }
+
+    async function copyFiles() {
+        const destinations = new Set();
+
+        for (const item of snapshot.files) {
+            const dest = destinationFor(item.entry, item.path);
+            destinations.add(dest);
+            await fs.mkdir(path.dirname(dest), { recursive: true });
+            await fs.copyFile(item.path, dest);
+        }
+
+        for (const stale of previousDestinations) {
+            if (!destinations.has(stale)) {
+                try { await fs.rm(stale, { force: true }); }
+                catch { /* ignored */ }
+            }
+        }
+
+        previousDestinations = destinations;
+    }
+
+    return {
+        name: "x4-copy",
+        setup(build) {
+            build.onStart(async () => {
+                await scan();
+            });
+
+            if (dev) {
+                build.onResolve({ filter: /^x4:copy-state$/ }, () => ({
+                    path: "copy-state",
+                    namespace: "x4-internal",
+                }));
+
+                build.onLoad({ filter: /^copy-state$/, namespace: "x4-internal" }, async () => ({
+                    contents: `export default ${JSON.stringify(snapshot.fingerprint)};`,
+                    loader: "js",
+                    watchFiles: snapshot.files.map((item) => item.path),
+                    watchDirs: snapshot.dirs,
+                }));
+            }
+
+            build.onEnd(async (result) => {
+                if (result.errors.length === 0)
+                    await copyFiles();
+            });
+        },
+    };
+}

package/cli/create.mjs

@@ -0,0 +1,141 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import { fetchTemplates, fetchTemplateFiles, downloadTemplateFile } from "./templates-source.mjs";
+import { info, success } from "./log.mjs";
+
+function x4Minor(version) {
+    const match = /^(\d+)\.(\d+)/.exec(version);
+    if (!match)
+        throw new Error(`Invalid x4js version '${version}'`);
+    return `${match[1]}.${match[2]}`;
+}
+
+function validatePackageName(name) {
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(name))
+        throw new Error(`Invalid project name '${name}'. Use lowercase letters, digits, '.', '_' or '-'.`);
+}
+
+async function ensureEmptyTarget(target) {
+    try {
+        const entries = await fs.readdir(target);
+        if (entries.length)
+            throw new Error(`Target directory is not empty: ${target}`);
+        return false;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            await fs.mkdir(target, { recursive: true });
+            return true;
+        }
+        throw error;
+    }
+}
+
+async function clearDirectory(target) {
+    const entries = await fs.readdir(target, { withFileTypes: true });
+    await Promise.all(entries.map((entry) =>
+        fs.rm(path.join(target, entry.name), { recursive: true, force: true })
+    ));
+}
+
+async function patchPackage(target, projectName, version) {
+    const filename = path.join(target, "package.json");
+    let pkg;
+    try {
+        pkg = JSON.parse(await fs.readFile(filename, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Template package.json is missing or invalid: ${error.message}`);
+    }
+
+    pkg.name = projectName;
+    const minor = x4Minor(version);
+
+    if (pkg.dependencies?.x4js !== undefined)
+        pkg.dependencies.x4js = minor;
+    else if (pkg.devDependencies?.x4js !== undefined)
+        pkg.devDependencies.x4js = minor;
+    else {
+        pkg.dependencies ??= {};
+        pkg.dependencies.x4js = minor;
+    }
+
+    await fs.writeFile(filename, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+async function npmInstall(target) {
+    const command = process.platform === "win32" ? "npm.cmd" : "npm";
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, ["install"], {
+            cwd: target,
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("exit", (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`npm install failed${signal ? ` (${signal})` : ` (exit ${code})`}`));
+        });
+    });
+}
+
+export async function create(argv = [], { version = "unknown", cwd = process.cwd() } = {}) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            template: { type: "string", short: "t", default: "app" },
+            "no-install": { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+
+    if (positionals.length !== 1)
+        throw new Error("Usage: x4js create <project> [--template <name>] [--no-install]");
+
+    const target = path.resolve(cwd, positionals[0]);
+    const projectName = path.basename(target);
+    validatePackageName(projectName);
+
+    const manifest = await fetchTemplates(version);
+    if (!(values.template in manifest))
+        throw new Error(`Unknown template '${values.template}'. Run 'x4js templates' to list templates.`);
+
+    const targetCreated = await ensureEmptyTarget(target);
+    info("create", target);
+    info("template", values.template);
+
+    try {
+        const files = await fetchTemplateFiles(values.template, version);
+
+        await Promise.all(files.map(async (file) => {
+            if (!file.path || file.path.split("/").includes(".."))
+                throw new Error(`Unsafe template path '${file.path}'`);
+            const destination = path.join(target, ...file.path.split("/"));
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            const data = await downloadTemplateFile(file.url, version);
+            await fs.writeFile(destination, data);
+        }));
+
+        await patchPackage(target, projectName, version);
+
+        if (!values["no-install"]) {
+            info("install", "npm");
+            await npmInstall(target);
+        }
+
+        success("created", target);
+    }
+    catch (error) {
+        if (targetCreated)
+            await fs.rm(target, { recursive: true, force: true });
+        else
+            await clearDirectory(target);
+        throw error;
+    }
+}
+
+export { x4Minor };

package/cli/dev-client.js

@@ -0,0 +1,41 @@
+import copyState from "x4:copy-state";
+
+// Keep the copy-state module in the bundle so changes to copied files also
+// produce a changed JS output and therefore a live-reload event.
+const events = new EventSource("/esbuild");
+Object.defineProperty(events, "__x4CopyState", { value: copyState });
+
+events.addEventListener("change", (event) => {
+    const change = JSON.parse(event.data);
+    const changed = [...change.added, ...change.removed, ...change.updated];
+
+    if (
+        change.added.length === 0 &&
+        change.removed.length === 0 &&
+        change.updated.length > 0 &&
+        change.updated.every((file) => file.endsWith(".css"))
+    ) {
+        const pending = new Set(change.updated);
+        const links = document.querySelectorAll('link[rel="stylesheet"]');
+
+        for (const link of links) {
+            const current = new URL(link.href);
+            if (!pending.has(current.pathname))
+                continue;
+
+            const next = link.cloneNode();
+            const url = new URL(link.href);
+            url.searchParams.set("x4", Date.now().toString());
+            next.href = url.href;
+            next.onload = () => link.remove();
+            link.after(next);
+            pending.delete(current.pathname);
+        }
+
+        if (pending.size === 0)
+            return;
+    }
+
+    if (changed.length)
+        location.reload();
+});

package/cli/dev.mjs

@@ -0,0 +1,188 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import esbuild from "esbuild";
+import { loadConfig, resolveTls } from "./config.mjs";
+import { createBuildOptions } from "./build-options.mjs";
+import { info, success, failure } from "./log.mjs";
+
+function openBrowser(url) {
+    let command;
+    let args;
+
+    if (process.platform === "win32") {
+        command = "cmd";
+        args = ["/c", "start", "", url];
+    }
+    else if (process.platform === "darwin") {
+        command = "open";
+        args = [url];
+    }
+    else {
+        command = "xdg-open";
+        args = [url];
+    }
+
+    const child = spawn(command, args, {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+}
+
+function protocolConfig(config, values) {
+    if (values.http && values.https)
+        throw new Error("--http and --https are mutually exclusive");
+
+    let https = config.dev.https;
+    if (values.http)
+        https = false;
+    if (values.https)
+        https = true;
+
+    return https;
+}
+
+function serverUrl(host, port, https) {
+    let displayHost = host;
+    if (host === "0.0.0.0")
+        displayHost = "127.0.0.1";
+    else if (host === "::")
+        displayHost = "[::1]";
+    else if (host.includes(":") && !host.startsWith("["))
+        displayHost = `[${host}]`;
+    return `${https ? "https" : "http"}://${displayHost}:${port}/`;
+}
+
+export async function dev(argv = [], root = process.cwd()) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            host: { type: "string" },
+            port: { type: "string" },
+            http: { type: "boolean", default: false },
+            https: { type: "boolean", default: false },
+            open: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+
+    if (positionals.length)
+        throw new Error(`Unexpected argument: ${positionals[0]}`);
+
+    if (values.port !== undefined && !/^\d+$/.test(values.port))
+        throw new Error("--port must be an integer");
+
+    let context;
+    let packageWatcher;
+    let stopping = false;
+    let restartTimer;
+    let restartChain = Promise.resolve();
+    let browserOpened = false;
+
+    async function start(config) {
+        const host = values.host ?? config.dev.host;
+        const port = values.port === undefined ? config.dev.port : Number(values.port);
+        if (port < 0 || port > 65535)
+            throw new Error("--port must be between 0 and 65535");
+
+        const useHttps = protocolConfig(config, values);
+        const serveOptions = {
+            host,
+            port,
+            servedir: config.outdir,
+        };
+
+        if (useHttps)
+            Object.assign(serveOptions, resolveTls(config));
+
+        const next = await esbuild.context(createBuildOptions(config, "dev"));
+        try {
+            await next.watch();
+            const result = await next.serve(serveOptions);
+            context = next;
+
+            const actualHost = result.hosts.includes(host) ? host : (result.hosts[0] ?? host);
+            const url = serverUrl(actualHost, result.port, useHttps);
+            info("mode", "dev");
+            info("outdir", config.outdir);
+            success("listening", url);
+
+            if (values.open && !browserOpened) {
+                browserOpened = true;
+                openBrowser(url);
+            }
+        }
+        catch (error) {
+            await next.dispose();
+            throw error;
+        }
+    }
+
+    async function reload() {
+        let config;
+        try {
+            config = loadConfig(root);
+            protocolConfig(config, values);
+            if ((values.https || (!values.http && config.dev.https)))
+                resolveTls(config);
+        }
+        catch (error) {
+            failure(`config: ${error.message}`);
+            return;
+        }
+
+        const previous = context;
+        context = undefined;
+        if (previous)
+            await previous.dispose();
+
+        try {
+            await start(config);
+            success("config", "reloaded");
+        }
+        catch (error) {
+            failure(`restart: ${error.message}`);
+            // The old context cannot be restored after dispose. Keep watching
+            // package.json so fixing the configuration starts dev again.
+        }
+    }
+
+    function scheduleReload() {
+        clearTimeout(restartTimer);
+        restartTimer = setTimeout(() => {
+            restartChain = restartChain.then(reload, reload);
+        }, 150);
+    }
+
+    const initialConfig = loadConfig(root);
+    await start(initialConfig);
+
+    packageWatcher = fs.watch(path.resolve(root), { persistent: true }, (_event, filename) => {
+        if (filename === null || filename.toString() === "package.json")
+            scheduleReload();
+    });
+
+    async function stop() {
+        if (stopping)
+            return;
+        stopping = true;
+        clearTimeout(restartTimer);
+        packageWatcher?.close();
+        await restartChain.catch(() => {});
+        await context?.dispose();
+    }
+
+    process.once("SIGINT", async () => {
+        await stop();
+        process.exit(0);
+    });
+    process.once("SIGTERM", async () => {
+        await stop();
+        process.exit(0);
+    });
+
+    return { stop };
+}

package/cli/less-plugin.mjs

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+async function loadLess(projectRoot) {
+    const require = createRequire(path.join(projectRoot, "package.json"));
+    let resolved;
+    try {
+        resolved = require.resolve("less");
+    }
+    catch {
+        throw new Error(
+            'LESS support requires the "less" package.\n' +
+            'Install it with: npm install -D less',
+        );
+    }
+
+    const module = await import(pathToFileURL(resolved).href);
+    return module.default ?? module;
+}
+
+export function lessPlugin(projectRoot) {
+    let lessPromise;
+
+    return {
+        name: "x4-less",
+        setup(build) {
+            build.onLoad({ filter: /\.less$/ }, async (args) => {
+                const source = await fs.readFile(args.path, "utf8");
+                lessPromise ??= loadLess(projectRoot);
+                const less = await lessPromise;
+
+                const result = await less.render(source, {
+                    filename: args.path,
+                });
+
+                return {
+                    contents: result.css,
+                    loader: "css",
+                    resolveDir: path.dirname(args.path),
+                    watchFiles: [args.path, ...(result.imports ?? [])],
+                };
+            });
+        },
+    };
+}

package/cli/log.mjs

@@ -0,0 +1,41 @@
+import { styleText } from "node:util";
+
+function useColor(stream = process.stdout) {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR !== undefined)
+        return process.env.FORCE_COLOR !== "0";
+    return !!stream.isTTY;
+}
+
+function paint(style, value, stream = process.stdout) {
+    const text = String(value);
+    return useColor(stream) ? styleText(style, text) : text;
+}
+
+export const color = {
+    cyan: (value) => paint("cyan", value),
+    green: (value) => paint("green", value),
+    yellow: (value) => paint("yellow", value),
+    red: (value) => paint("red", value, process.stderr),
+    gray: (value) => paint("gray", value),
+    white: (value) => paint("white", value),
+};
+
+export function info(label, value = "") {
+    const left = color.cyan(String(label).padEnd(11));
+    console.log(value === "" ? left.trimEnd() : `${left}${value}`);
+}
+
+export function success(label, value = "") {
+    const left = color.green(String(label).padEnd(11));
+    console.log(value === "" ? left.trimEnd() : `${left}${value}`);
+}
+
+export function warning(message) {
+    console.warn(color.yellow(message));
+}
+
+export function failure(message) {
+    console.error(color.red(message));
+}

package/cli/main.mjs

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { failure } from "./log.mjs";
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url));
+const packageFile = path.join(cliDir, "..", "package.json");
+
+function getVersion() {
+    try {
+        return JSON.parse(fs.readFileSync(packageFile, "utf8")).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+
+function printHelp(version) {
+    console.log(`x4js ${version}
+
+Usage:
+  x4js create <project> [--template <name>] [--no-install]
+  x4js templates
+  x4js dev [--host <host>] [--port <port>] [--http|--https] [--open]
+  x4js build [--debug]
+
+Options:
+  -h, --help       Show help
+  -v, --version    Show version`);
+}
+
+const version = getVersion();
+const [command, ...argv] = process.argv.slice(2);
+
+try {
+    switch (command) {
+        case "create": {
+            const { create } = await import("./create.mjs");
+            await create(argv, { version });
+            break;
+        }
+        case "templates": {
+            const { templates } = await import("./templates.mjs");
+            await templates(argv, { version });
+            break;
+        }
+        case "dev": {
+            const { dev } = await import("./dev.mjs");
+            await dev(argv);
+            break;
+        }
+        case "build": {
+            const { build } = await import("./build.mjs");
+            await build(argv);
+            break;
+        }
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp(version);
+            break;
+        case "--version":
+        case "-v":
+            console.log(version);
+            break;
+        default:
+            throw new Error(`Unknown command '${command}'. Run 'x4js --help'.`);
+    }
+}
+catch (error) {
+    failure(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/cli/templates-source.mjs

@@ -0,0 +1,61 @@
+const OWNER = "rlibre";
+const REPO = "x4-templates";
+const REF = "main";
+
+function headers(version = "unknown") {
+    return {
+        "Accept": "application/vnd.github+json",
+        "User-Agent": `x4js/${version}`,
+        "X-GitHub-Api-Version": "2022-11-28",
+    };
+}
+
+async function checkedFetch(url, options) {
+    const response = await fetch(url, options);
+    if (!response.ok)
+        throw new Error(`Template repository request failed (${response.status} ${response.statusText})`);
+    return response;
+}
+
+export async function fetchTemplates(version = "unknown") {
+    const url = `https://raw.githubusercontent.com/${OWNER}/${REPO}/${REF}/templates.json`;
+    const response = await checkedFetch(url, { headers: headers(version) });
+    const manifest = await response.json();
+
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("Invalid templates.json");
+
+    for (const [name, description] of Object.entries(manifest)) {
+        if (!name || typeof description !== "string")
+            throw new Error("Invalid templates.json entry");
+    }
+
+    return manifest;
+}
+
+export async function fetchTemplateFiles(name, version = "unknown") {
+    const treeUrl = `https://api.github.com/repos/${OWNER}/${REPO}/git/trees/${REF}?recursive=1`;
+    const response = await checkedFetch(treeUrl, { headers: headers(version) });
+    const tree = await response.json();
+
+    if (!Array.isArray(tree.tree))
+        throw new Error("Invalid template repository tree");
+
+    const prefix = `${name}/`;
+    const files = tree.tree
+        .filter((item) => item.type === "blob" && item.path.startsWith(prefix))
+        .map((item) => ({
+            path: item.path.slice(prefix.length),
+            url: `https://raw.githubusercontent.com/${OWNER}/${REPO}/${REF}/${item.path.split("/").map(encodeURIComponent).join("/")}`,
+        }));
+
+    if (!files.length)
+        throw new Error(`Template '${name}' contains no files`);
+
+    return files;
+}
+
+export async function downloadTemplateFile(url, version = "unknown") {
+    const response = await checkedFetch(url, { headers: headers(version) });
+    return Buffer.from(await response.arrayBuffer());
+}

package/cli/templates.mjs

@@ -0,0 +1,13 @@
+import { fetchTemplates } from "./templates-source.mjs";
+import { color } from "./log.mjs";
+
+export async function templates(_argv = [], { version = "unknown" } = {}) {
+    const manifest = await fetchTemplates(version);
+    const names = Object.keys(manifest).sort();
+    const width = names.reduce((max, name) => Math.max(max, name.length), 0) + 3;
+
+    console.log(color.cyan("Available templates"));
+    console.log();
+    for (const name of names)
+        console.log(`  ${color.green(name.padEnd(width))}${manifest[name]}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x4js",
-  "version": "2.2.74",
+  "version": "2.3.1",
   "type": "module",
   "main": "src/x4.ts",
   "module": "src/x4.ts",
@@ -9,6 +9,9 @@
     ".": "./src/x4.ts",
     "./monaco": "./src/components/monaco/monaco.ts"
   },
+  "bin": {
+    "x4js": "./bin/x4js.mjs"
+  },
   "scripts": {
     "build-publish": "deno run --allow-all ./publish.ts",
     "build-doc": "typedoc",
@@ -16,6 +19,8 @@
   },
   "files": [
     "src",
+    "bin",
+    "cli",
     "README.md",
     "LICENSE"
   ],
@@ -32,6 +37,10 @@
     "desktop",
     "application"
   ],
+  "dependencies": {
+    "esbuild": "0.28",
+    "esbuild-sass-plugin": "^3.7"
+  },
   "devDependencies": {
     "typescript": "^5.8.3",
     "typedoc": "^0.28.19",

package/readme.npm.md

@@ -0,0 +1,248 @@
+# x4js
+
+**A TypeScript framework for building applications, not markup.**
+
+x4js is designed for rich web and desktop applications: business software, industrial interfaces, dashboards, data-heavy tools and desktop-like applications.
+
+It uses persistent TypeScript objects associated with the real DOM. No virtual DOM, no reconciliation layer, and no application architecture imposed by JSX.
+
+**TypeScript objects. JSX when it helps. Real DOM.**
+
+## Install
+
+```bash
+npm install x4js
+```
+
+## Quick start
+
+Create a project:
+
+```bash
+npx x4build create demo --type=html
+cd demo
+npm install
+```
+
+Run it in development mode with HMR:
+
+```bash
+npx x4build --watch --hmr --serve
+```
+
+## More than 50 UI components
+
+x4 includes a complete UI toolkit for building real applications.
+
+Among the available components:
+
+`Button`, `Input`, `TextEdit`, `TextArea`, `Checkbox`, `Radio`, `Switch`, `Select`, `Combobox`, `Slider`, `ColorPicker`, `Form`, `Dialog`, `Popup`, `Menu`, `Tabs`, `Gridview`, `Treeview`, `PropertyGrid`, `Spreadsheet`, `Calendar`, `Gauge`, `Progress`, `FileDrop`, `MonacoEditor`, layouts and more.
+
+The framework also provides:
+
+* drag & drop
+* SVG primitives and builder
+* routing
+* PDF generation
+* internationalization
+* data stores and views
+* application-wide events
+* persistence helpers
+* CSS infrastructure and theming
+
+## Easy to extend
+
+x4 components are ordinary TypeScript classes.
+
+```ts
+import { Component, ComponentProps } from 'x4js'
+
+interface StatusBadgeProps extends ComponentProps {
+    text: string
+}
+
+class StatusBadge extends Component<StatusBadgeProps> {
+    constructor(props: StatusBadgeProps) {
+        super(props)
+
+        this.setContent(props.text)
+    }
+}
+```
+
+Your own components use the same DOM, lifecycle and event model as the components provided by x4.
+
+Because x4 works with the real browser DOM, third-party UI libraries can also be integrated where they make sense. There is no separate plugin architecture to satisfy.
+
+## Real DOM
+
+A `Component` is a persistent TypeScript object associated with an actual DOM element.
+
+```ts
+const button = new Button({
+    label: 'Restart'
+})
+
+button.on('click', () => restartMachine())
+```
+
+The object remains alive for the lifetime of the component. You can keep references, call methods and listen to events directly.
+
+There is no virtual tree to rebuild or reconcile.
+
+## JSX is optional
+
+x4 supports JSX, but JSX is syntax — not the application architecture.
+
+Object API:
+
+```ts
+this.setContent([
+    new Label({
+        text: 'Temperature'
+    }),
+
+    new Gauge({
+        min: 0,
+        max: 100
+    })
+])
+```
+
+JSX:
+
+```tsx
+this.setContent(
+    <VBox>
+        <Label text="Temperature" />
+        <Gauge min={0} max={100} />
+    </VBox>
+)
+```
+
+Both create the same x4 Components and the same real DOM.
+
+Use whichever makes the code clearer.
+
+## Data-heavy applications
+
+x4 treats grids, trees, forms and structured data as first-class application concerns.
+
+`DataStore`, `DataView` and `Gridview` are designed to work together for tabular data:
+
+```ts
+const store = new DataStore({
+    model,
+    data
+})
+
+const grid = new Gridview({
+    store,
+    columns: [
+        { id: 'name', title: 'Name', width: 200 },
+        { id: 'age', title: 'Age', width: 80 }
+    ]
+})
+```
+
+Changes to the data are reflected by the components using it.
+
+## Routing
+
+```ts
+const router = new Router(true)
+
+router.get('/home', () => showHome())
+router.get('/device/:id', p => showDevice(p.id))
+
+router.init()
+```
+
+## Internationalization
+
+Internationalization support is built in.
+
+```ts
+createLanguage('de', 'en')
+addTranslation('de', translations)
+
+selectLanguage('de')
+```
+
+x4 includes French and English translations by default and allows applications to add their own languages.
+
+## SVG and PDF
+
+SVG is part of the framework surface through `SvgComponent` and `SvgBuilder`.
+
+PDF documents can be generated programmatically with `X4PDFBuilder`:
+
+```ts
+const pdf = new X4PDFBuilder()
+
+pdf.page(595, 842, page => {
+    // draw page
+})
+
+const data = pdf.build()
+```
+
+## CSS and themes
+
+x4 includes the CSS foundation used by its components.
+
+Applications can use the default styling, adapt it to their product, or provide their own CSS. Components expose their real DOM and CSS classes, so standard browser styling techniques remain available.
+
+No CSS-in-JS runtime is required.
+
+## HMR and development workflow
+
+The standard x4 build workflow supports watch mode, development serving and HMR:
+
+```bash
+x4build --watch --hmr --serve
+```
+
+Edit the application, save, see the result.
+
+## Ship only what you use
+
+The `x4js` npm package ships its TypeScript sources directly.
+
+Your application and x4 therefore participate in the same module graph, allowing the bundler to tree-shake unused code.
+
+Import a small part of x4 and the rest of the component library does not need to become part of your application bundle.
+
+## Web and desktop
+
+x4 targets both browser and desktop applications.
+
+The same component model can be used in the browser or inside a desktop wrapper such as Electron, Tauri or NW.js.
+
+## AI-friendly documentation
+
+x4 provides a generated `aicontext.md` containing the actual TypeScript API signatures.
+
+AI coding agents can also inspect the framework sources directly because they are distributed with the npm package:
+
+```text
+node_modules/x4js/src/
+```
+
+The goal is not to make x4 an “AI framework”.
+
+The goal is simpler: an explicit architecture and an API that are readable by humans and predictable for machines.
+
+## Philosophy
+
+x4 deliberately keeps its conceptual model small.
+
+Use TypeScript when TypeScript is enough.
+Use the browser when the browser is enough.
+Add an abstraction only when it solves a real problem.
+
+**Use the simplest tool that fits.**
+
+---
+
+MIT License