tachlon 0.0.1 → 0.1.0

package/dist-lib/cli/doctor.js

@@ -0,0 +1,205 @@
+// `doctor`: reads a project that lists the package and says, check by check, whether the chart is installed right. It writes nothing.
+// A `Finding` is a code, a status, what was seen and one sentence to fix it; `run.ts` prints them and picks the exit code (1 when one failed).
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { validate } from "../adapters/validate.js";
+import { codeFor, fixFor } from "../errors.js";
+import { allowsConnect, allowsWasm, configPolicies } from "./csp.js";
+import { readJsonObject, Refusal } from "./detect.js";
+import { BROWSER_VARIABLE } from "./gpu.js";
+const pass = (code, what) => ({ code, status: "pass", what, fix: "" });
+const fail = (code, what, fix) => ({ code, status: "fail", what, fix });
+const MAGIC = [0x00, 0x61, 0x73, 0x6d];
+const why = (e) => (e instanceof Error ? e.message : String(e)).replace(/\s+/g, " ");
+/** Every distinct copy of package `name` the project can load: the nearest `node_modules/<name>` first, then the ones nested one level down (inside another package, or in pnpm's store). */
+export function copiesOf(dir, name) {
+    let modules;
+    for (let d = dir; modules === undefined; d = dirname(d)) {
+        if (existsSync(join(d, "node_modules", name, "package.json")))
+            modules = join(d, "node_modules");
+        else if (dirname(d) === d)
+            return [];
+    }
+    const found = new Set([realpathSync(join(modules, name))]);
+    const nested = (holder) => {
+        const copy = join(holder, "node_modules", name);
+        if (existsSync(join(copy, "package.json")))
+            found.add(realpathSync(copy));
+    };
+    for (const entry of readdirSync(modules)) {
+        const sub = join(modules, entry);
+        if (entry === ".pnpm" || entry.startsWith("@"))
+            readdirSync(sub).forEach((s) => nested(join(sub, s)));
+        else if (!entry.startsWith("."))
+            nested(sub);
+    }
+    return [...found];
+}
+/** The engine size the package's build recorded in `copy` (`dist-lib/engine-size.json`, written by `scripts/emit-engine-size.ts`); undefined when the file is missing or holds no whole number. */
+function recordedSize(copy) {
+    try {
+        const { bytes } = JSON.parse(readFileSync(join(copy, "dist-lib", "engine-size.json"), "utf8"));
+        return typeof bytes === "number" && Number.isInteger(bytes) && bytes > 0 ? bytes : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The engine in the installed copy: there, starts `\0asm`, and the size the copy's own build recorded (never a file read from the running install, which may be the copy itself). */
+function engineFinding(project, copy) {
+    const file = join(copy, "dist-lib", "app_bg.wasm");
+    const shown = relative(project.dir, file);
+    const again = `Delete the package from node_modules and install it again with \`${project.manager} ${project.manager === "npm" ? "install" : "add"}\``;
+    if (!existsSync(file))
+        return fail("ENGINE_MISSING", `${shown} is missing`, `${again}, and stop any cleanup step that deletes .wasm files.`);
+    const bytes = readFileSync(file);
+    if (!MAGIC.every((b, i) => bytes[i] === b))
+        return fail("ENGINE_NOT_WASM", `${shown} does not start with "\\0asm"`, `${again}: the file is not the engine, which a half-finished install or a tool that rewrites .wasm files leaves behind.`);
+    const want = recordedSize(copy);
+    if (want === undefined)
+        return fail("ENGINE_UNRECORDED", `${relative(project.dir, join(copy, "dist-lib", "engine-size.json"))} is missing or unreadable, so the engine's size cannot be checked`, `${again}: the package's build records the engine's size there, and a copy without it is not a whole package.`);
+    if (bytes.length !== want)
+        return fail("ENGINE_SIZE", `${shown} is ${bytes.length} bytes; the size recorded when the package was built is ${want} bytes`, `${again}: a file of another size is cut short or comes from another version of the package.`);
+    return pass("ENGINE_OK", `${shown} starts with "\\0asm" and is ${want} bytes, the size recorded when the package was built`);
+}
+/** A Next app serves the engine from its own copy, `public/app_bg.wasm` (`init` writes it and never overwrites it): there, starts `\0asm`, and the size the installed package recorded, so a copy left from an older version is named. None when the package recorded no size (`engineFinding` fails that). */
+function engineCopyFindings(project, copy) {
+    const file = join(project.dir, "public", "app_bg.wasm");
+    const shown = relative(project.dir, file);
+    const from = relative(project.dir, join(copy, "dist-lib", "app_bg.wasm"));
+    const refresh = `Copy the installed engine over it with \`cp ${from} ${shown}\``;
+    if (!existsSync(file))
+        return [fail("ENGINE_COPY_MISSING", `${shown} is missing`, `${refresh}, or run init again to write it.`)];
+    const want = recordedSize(copy);
+    if (want === undefined)
+        return [];
+    const bytes = readFileSync(file);
+    const wasm = MAGIC.every((b, i) => bytes[i] === b);
+    const source = join(copy, "dist-lib", "app_bg.wasm");
+    // The installed engine itself when it is there (a build of the same size can hold other code); `engineFinding` fails a missing or cut-short one.
+    const other = existsSync(source) && !bytes.equals(readFileSync(source));
+    if (bytes.length !== want || !wasm || other) {
+        const how = !wasm ? `${bytes.length} bytes and does not start with "\\0asm"` : bytes.length === want ? `${want} bytes like the installed engine, but its content differs` : `${bytes.length} bytes`;
+        return [fail("ENGINE_COPY_STALE", `${shown} is ${how}; the engine in the installed package is ${want} bytes`, `${refresh}: a copy that differs comes from another version of the package, and the page would run that engine.`)];
+    }
+    return [pass("ENGINE_COPY_OK", `${shown} starts with "\\0asm" and is the same ${want} bytes as the engine in the installed package`)];
+}
+/** The page's Content-Security-Policy: the project's config and, with `--url`, the served page. The engine needs `'wasm-unsafe-eval'`, and `connect-src` must allow the engine, even one on the page's own origin (`'self'` matches it; checked only against a served policy and a known engine address, `engineKnown`). Every fault of a policy is reported in one run. No policy found, no finding. */
+function cspFindings(project, probe, engineKnown) {
+    const out = [];
+    const policies = [...configPolicies(project.dir), ...(probe?.policies ?? [])];
+    const [page, engine] = probe && engineKnown ? [new URL(probe.page), new URL(probe.engine.url)] : [];
+    for (const p of policies) {
+        if (!allowsWasm(p.text))
+            out.push(fail("CSP_WASM_EVAL", `${p.source} sets a policy whose script-src (or default-src) does not allow 'wasm-unsafe-eval', so the browser refuses to compile the engine`, `Add 'wasm-unsafe-eval' to the script-src (or default-src) directive in ${p.source}.`));
+        if (page && engine && probe?.policies.includes(p) && !allowsConnect(p.text, engine, page))
+            out.push(fail("CSP_CONNECT_SRC", `${p.source} sets a policy whose connect-src (or default-src) does not allow the engine at ${engine.origin}`, engine.origin === page.origin ? `Add 'self' to the connect-src (or default-src) directive in the page's policy.` : `Add ${engine.origin} to the connect-src directive in the page's policy, or serve the engine from the page's own origin.`));
+    }
+    return policies.length > 0 && out.length === 0 ? [pass("CSP_OK", `the policy in ${[...new Set(policies.map((p) => p.source))].join(", ")} lets the engine compile${page && probe?.policies.length ? " and connect" : ""}`)] : out;
+}
+/** The engine at the address the page names, as served: status 200, starts `\0asm`, type `application/wasm`; in a Next app also byte-equal to the installed engine (`installed`). A page that names none has no address to check outside a Next app, whose engine `init` puts at `/app_bg.wasm`: there is nothing to fail, so the check is skipped. */
+function servedFindings({ engine: e }, installed, next) {
+    if (!e.named && !next)
+        return [{ code: "ENGINE_URL_SKIPPED", status: "skipped", what: "not checked: the page names no .wasm address (a Vite build names its hashed engine file only in a script)", fix: "Open the page in a browser, take the address of the .wasm file from its network panel and request it: it must answer 200 as application/wasm." }];
+    const serve = `Serve the engine file at ${e.url}`;
+    if (e.status === null)
+        return [fail("ENGINE_FETCH", `${e.url} could not be requested: ${e.error}`, `${serve} and check that the address is reachable.`)];
+    if (e.status !== 200)
+        return [fail("ENGINE_FETCH", `${e.url} answered with status ${e.status}`, `${serve}; a missing file or a blocked path answers with another status.`)];
+    if (!MAGIC.every((b, i) => e.bytes[i] === b))
+        return [fail("ENGINE_NOT_WASM", `${e.url} does not start with "\\0asm": it starts with "${e.bytes.subarray(0, 8).toString("latin1").replace(/[^\x20-\x7e]/g, "?")}"`, `${serve}: a fallback that answers every unknown path with the page hides a missing file.`)];
+    if (!/^application\/wasm\s*(?:;|$)/i.test(e.type))
+        return [fail("ENGINE_CONTENT_TYPE", `${e.url} answers with the type "${e.type}", not "application/wasm"`, `Serve .wasm files as application/wasm, which the browser needs to compile the engine as it downloads.`)];
+    if (installed !== undefined && existsSync(installed) && !e.bytes.equals(readFileSync(installed)))
+        return [fail("ENGINE_URL_STALE", `${e.url} serves ${e.bytes.length} bytes that differ from the engine in the installed package`, `Copy the installed engine to public/app_bg.wasm and deploy again: the site serves an engine of another version.`)];
+    return [pass("ENGINE_URL_OK", `${e.url} answers 200 with ${e.bytes.length} bytes of WebAssembly as application/wasm`)];
+}
+const SOURCE = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|s?css|html)$/;
+const SKIPPED_FOLDERS = new Set(["node_modules", "dist", "build", "out", "coverage"]);
+/** Whether some source file under `dir` holds `needle`; node_modules, build output and dot folders are not source. */
+function mentions(dir, needle) {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        if (e.name.startsWith("."))
+            continue;
+        const path = join(dir, e.name);
+        if (e.isDirectory()) {
+            if (!SKIPPED_FOLDERS.has(e.name) && mentions(path, needle))
+                return true;
+        }
+        else if (e.isFile() && SOURCE.test(e.name) && statSync(path).size < 1e6 && readFileSync(path, "utf8").includes(needle))
+            return true;
+    }
+    return false;
+}
+/** `validate()` on the JSON in `file`: one finding for each issue. A file that cannot be read is a refusal (exit 2); one that is not JSON is a finding. */
+function dataFindings(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (e) {
+        throw new Refusal(`${file} cannot be read: ${why(e)}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (e) {
+        return [fail("DATA_NOT_JSON", `${file} is not valid JSON: ${why(e)}`, "Fix the JSON syntax the message names, then run doctor again.")];
+    }
+    const result = validate(data);
+    if (result.ok)
+        return [pass("DATA_OK", `${file} passes validate()`)];
+    return result.issues.map((i) => fail("DATA_INVALID", `${i.path || "data"}: expected ${i.expected}, got ${i.got}`, i.fix));
+}
+/** The findings for `project`: its package listed and installed once, the engine, a stylesheet import, the data file when given, and the GPU the browser reported (skipped when none answered). */
+export function diagnose(project, own, c) {
+    const pkg = readJsonObject(join(project.dir, "package.json"));
+    if (!Object.hasOwn({ ...pkg.dependencies, ...pkg.devDependencies }, own.name)) {
+        return [fail("NOT_LISTED", `package.json lists no ${own.name}`, `Run \`${own.name} init\` here, or add ${own.name} with \`${project.manager} ${project.manager === "npm" ? "install" : "add"} ${own.name}\`.`)];
+    }
+    const copies = copiesOf(project.dir, own.name);
+    const version = (copy) => String(readJsonObject(join(copy, "package.json")).version);
+    const at = (copy) => `${version(copy)} at ${relative(project.dir, copy)}`;
+    const out = [];
+    if (copies.length === 0)
+        out.push(fail("NOT_INSTALLED", `package.json lists ${own.name} but node_modules holds no copy`, `Run \`${project.manager} install\` in ${project.dir}.`));
+    else {
+        out.push(pass("INSTALLED", `${own.name} ${at(copies[0])}`));
+        out.push(copies.length === 1 ? pass("ONE_COPY", "one copy is installed") : fail("MANY_COPIES", `${copies.length} copies are installed: ${copies.map(at).join(", ")}`, "Give every package that depends on it the same version range and install again, so the page loads one copy."));
+        out.push(engineFinding(project, copies[0]));
+        if (project.bundler === "next")
+            out.push(...engineCopyFindings(project, copies[0]));
+    }
+    const next = project.bundler === "next";
+    out.push(...cspFindings(project, c.probe, c.probe !== undefined && (c.probe.engine.named || next)));
+    if (c.probe)
+        out.push(...servedFindings(c.probe, next && copies.length > 0 ? join(copies[0], "dist-lib", "app_bg.wasm") : undefined, next));
+    const css = `${own.name}/gantt.css`;
+    out.push(mentions(project.dir, css) ? pass("STYLESHEET_OK", `a source file imports ${css}`) : fail("STYLESHEET_MISSING", `no source file imports ${css}`, `Add \`import "${css}";\` to the module that mounts the chart, or the chart draws unstyled.`));
+    if (c.data !== undefined)
+        out.push(...dataFindings(c.data));
+    out.push(gpuFinding(c.gpu));
+    return out;
+}
+/** The graphics path a browser gave the chart: WebGPU or WebGL2 with the adapter's name, or neither (the fault `mount` rejects with). With no browser answer, the check is skipped and says why: a Node process has no WebGPU or WebGL2 to ask. */
+function gpuFinding(gpu) {
+    const none = codeFor("GPU_NONE");
+    if (gpu && "api" in gpu) {
+        if (gpu.api === "webgpu")
+            return pass("GPU_WEBGPU", `the browser has a WebGPU adapter (${gpu.adapter}), so the chart draws with WebGPU`);
+        if (gpu.api === "webgl2")
+            return pass("GPU_WEBGL2", `the browser has no WebGPU adapter but has WebGL2 (${gpu.adapter}), so the chart draws with WebGL2`);
+        return fail("GPU_NONE", `the browser has neither WebGPU nor WebGL2, so \`mount\` rejects with ${none}`, fixFor(none));
+    }
+    return { code: "GPU_SKIPPED", status: "skipped", what: `not checked: ${gpu ? gpu.unavailable : "no browser was asked"}; a Node process has no WebGPU or WebGL2 itself, and \`mount\` reports ${none} when the browser has neither`, fix: `Install Chrome, Edge or Chromium (or name one with ${BROWSER_VARIABLE}) and run doctor again, or open the page in a browser and read the error \`mount\` rejects with.` };
+}
+/** The findings as lines a person reads. */
+export function describeFindings(findings, where) {
+    const mark = { pass: "ok  ", fail: "FAIL", skipped: "skip" };
+    const lines = [`doctor in ${where}`];
+    for (const f of findings)
+        lines.push(`  ${mark[f.status]} ${f.code}: ${f.what}`, ...(f.fix ? [`       fix: ${f.fix}`] : []));
+    const n = findings.filter((f) => f.status === "fail").length;
+    return [...lines, n === 0 ? "No problems found." : `${n} problem${n === 1 ? "" : "s"} found.`, ""].join("\n");
+}

package/dist-lib/cli/gpu.js

@@ -0,0 +1,66 @@
+// What `doctor` asks a real browser about the GPU: it opens a page of its own, headless, in a Chrome, Edge or Chromium found on this machine, and reads the answer the page writes.
+// Only this file starts a browser; `doctor.ts` turns what it returns into a finding.
+import { execFile } from "node:child_process";
+import { accessSync, constants, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { PRODUCT_NAME } from "../product.js";
+/** The environment variable that names the browser to ask, for a machine where it is not on the path. */
+export const BROWSER_VARIABLE = `${PRODUCT_NAME.toUpperCase()}_BROWSER`;
+const NAMES = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge"];
+const APPS = ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"];
+const TIMEOUT_MS = 30_000;
+/** The page: it asks as `mount` does, and writes the answer into its title, which `--dump-dom` prints. A file address is a secure context, where `navigator.gpu` exists. */
+const PAGE = `<!doctype html><title></title><script>
+(async () => {
+  const adapter = await navigator.gpu?.requestAdapter().catch(() => null);
+  if (adapter) return { api: "webgpu", adapter: [adapter.info.vendor, adapter.info.architecture, adapter.info.description].filter(Boolean).join(" ") || "unnamed adapter" };
+  const gl = document.createElement("canvas").getContext("webgl2");
+  if (!gl) return { api: "none", adapter: "" };
+  const info = gl.getExtension("WEBGL_debug_renderer_info");
+  return { api: "webgl2", adapter: String(gl.getParameter(info ? info.UNMASKED_RENDERER_WEBGL : gl.RENDERER)) };
+})().then((answer) => (document.title = "gpu=" + encodeURIComponent(JSON.stringify(answer))));
+</script>`;
+const exec = promisify(execFile);
+const why = (e) => (e instanceof Error ? e.message : String(e)).replace(/\s+/g, " ").slice(0, 200);
+/** The browser to ask: the one the environment variable names, else the first of the usual names on the path, else the usual place of an app on a Mac. */
+function findBrowser(env) {
+    if (env[BROWSER_VARIABLE])
+        return env[BROWSER_VARIABLE];
+    const runnable = (file) => {
+        try {
+            accessSync(file, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const onPath = (env.PATH ?? "").split(delimiter).filter(Boolean).flatMap((d) => NAMES.map((n) => join(d, n)));
+    return [...onPath, ...APPS].find(runnable);
+}
+/** Opens the page in the browser `env` leads to and returns what it said; no browser, one that fails, or one that prints no report is `unavailable`, with the reason. */
+export async function askBrowser(env = process.env) {
+    const browser = findBrowser(env);
+    if (!browser)
+        return { unavailable: `no Chrome, Edge or Chromium was found on this machine (name one with ${BROWSER_VARIABLE})` };
+    const dir = mkdtempSync(join(tmpdir(), "doctor-gpu-"));
+    try {
+        const page = join(dir, "gpu.html");
+        writeFileSync(page, PAGE);
+        const { stdout } = await exec(browser, ["--headless=new", "--no-first-run", `--user-data-dir=${join(dir, "profile")}`, "--virtual-time-budget=10000", "--dump-dom", pathToFileURL(page).href], { timeout: TIMEOUT_MS, maxBuffer: 5e6 });
+        const report = /<title>gpu=([^<]*)<\/title>/.exec(stdout)?.[1];
+        const got = report === undefined ? undefined : JSON.parse(decodeURIComponent(report));
+        if (got?.api !== "webgpu" && got?.api !== "webgl2" && got?.api !== "none")
+            return { unavailable: `${browser} ran the page but sent no GPU report` };
+        return { api: got.api, adapter: String(got.adapter ?? "") };
+    }
+    catch (e) {
+        return { unavailable: `${browser} did not answer: ${why(e)}` };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist-lib/cli/init.js

@@ -0,0 +1,103 @@
+// `init`: plans how to add the chart to a project (`planInit`, also `--dry-run`), then does it (`applyInit`): install the package, write the chart module.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, posix, relative } from "node:path";
+import { Refusal } from "./detect.js";
+import { copiesOf } from "./doctor.js";
+import { chartModule } from "./template.js";
+/** Why `init` cannot run in `project`, or undefined. */
+export function refusal(project, o) {
+    if (project.workspace && !o.explicitDir)
+        return `${project.dir} is a workspace root; pass --dir <the package to add it to>`;
+    if (project.bundler === undefined && !o.plain)
+        return `init supports Vite and found ${project.otherBundler ?? "no bundler"} instead; pass --plain to write a chart module that needs no bundler`;
+    if (project.bundler === "next" && project.routerRoot === undefined)
+        return "this is a Next.js project with neither an app/ nor a pages/ folder (looked in the project folder and src/)";
+    return undefined;
+}
+function newFiles(project, own, plain) {
+    const kind = project.framework === "none" || plain ? "plain" : "react";
+    const ext = project.typescript ? (kind === "plain" ? "ts" : "tsx") : kind === "plain" ? "js" : "jsx";
+    const file = `${own.name}-chart.${ext}`;
+    const text = chartModule(kind, project.typescript, own.name, project.bundler === "next");
+    if (project.bundler === "next")
+        return [{ path: posix.join(project.routerRoot ?? "", "components", file), text }, { path: "public/app_bg.wasm", text: undefined }];
+    return [{ path: existsSync(join(project.dir, "src")) ? posix.join("src", file) : file, text }];
+}
+const installCommand = (project, own, o) => [project.manager, [project.manager === "npm" ? "install" : "add", o.spec ?? `${own.name}@${own.version}`]];
+/** The plan for `project` and the files it writes, or the sentence that says why it cannot be made. */
+export function planInit(project, own, o) {
+    const why = refusal(project, o);
+    if (why !== undefined)
+        return { error: why };
+    const outputs = newFiles(project, own, o.plain);
+    const taken = outputs.filter((f) => existsSync(join(project.dir, f.path)));
+    // The engine copy (no text) is left as it is whatever it holds: `doctor` names a copy that is out of date.
+    const same = (f) => f.text === undefined || readFileSync(join(project.dir, f.path), "utf8") === f.text;
+    const blocking = taken.find((f) => !same(f));
+    if (blocking !== undefined)
+        return { error: `${blocking.path} already exists, and init never overwrites a file` };
+    const [cmd, args] = installCommand(project, own, o);
+    // Done when every file is there; a file that is missing from a partly set up project is still written.
+    const done = taken.length === outputs.length;
+    const files = (done ? outputs : outputs.filter((f) => !taken.includes(f))).map((f) => f.path);
+    const plan = { dir: project.dir, manager: project.manager, framework: o.plain ? "none" : project.framework, bundler: project.bundler ?? "none", install: [cmd, ...args].join(" "), files, done, dryRun: o.dryRun };
+    return { plan, outputs };
+}
+/** The engine file Next serves from `public/`: the installed package's copy, or a refusal when the package is not there to copy from. */
+function engineBytes(project, own, installed) {
+    const copy = copiesOf(project.dir, own.name)[0];
+    const file = copy === undefined ? undefined : join(copy, "dist-lib", "app_bg.wasm");
+    if (file === undefined || !existsSync(file))
+        throw new Refusal(`${own.name}/dist-lib/app_bg.wasm is not in node_modules, so there is no engine to copy to public/; ${installed ? "the package was installed and " : ""}no file was written`);
+    return readFileSync(file);
+}
+/** Installs the package (unless `o.install` is false), then writes each file; a failed install writes no file. Returns the lines to print. */
+export function applyInit(project, own, o, plan, outputs) {
+    if (plan.done)
+        return [`already set up, nothing changed: ${plan.files.join(", ")} is already here`];
+    const lines = [];
+    if (o.install) {
+        const [cmd, args] = installCommand(project, own, o);
+        const ran = spawnSync(cmd, args, { cwd: project.dir, encoding: "utf8", shell: process.platform === "win32" });
+        if (ran.error || ran.status !== 0)
+            throw new Refusal(`${plan.install} failed${ran.error ? `: ${ran.error.message}` : ` (exit ${ran.status})`}; init wrote no files\n${(ran.stderr ?? "").trim()}`.trim());
+        lines.push(`  ran: ${plan.install}`);
+    }
+    else
+        lines.push("  install skipped (--no-install)");
+    const todo = outputs.filter((f) => plan.files.includes(f.path));
+    const bodies = todo.map((f) => f.text ?? engineBytes(project, own, o.install)); // read first: a missing engine writes no file
+    const wrote = [];
+    for (const [i, f] of todo.entries()) {
+        try {
+            mkdirSync(dirname(join(project.dir, f.path)), { recursive: true });
+            writeFileSync(join(project.dir, f.path), bodies[i], { flag: "wx" });
+        }
+        catch (e) {
+            const why = (e instanceof Error ? e.message : String(e)).replace(/\s+/g, " ");
+            throw new Refusal(`${f.path} cannot be written (${why}); ${o.install ? "the package was installed and " : ""}${wrote.length === 0 ? "no file was written" : `only ${wrote.join(", ")} was written`}`);
+        }
+        wrote.push(f.path);
+        lines.push(`  wrote: ${f.path}`);
+    }
+    return lines;
+}
+/** What to add to a page and run next, as lines. */
+export function nextSteps(plan, outputs) {
+    const module = `${plan.bundler === "next" ? "../components" : "."}/${posix.basename(outputs[0].path).replace(/\.[jt]sx?$/, "")}`; // a Next page sits in app/ or pages/, one folder below components/
+    const line = /\.[jt]sx$/.test(outputs[0].path) ? `import Chart from "${module}"; // then render <Chart />` : `import { mountChart } from "${module}"; // then mountChart(<a div with the class "gantt" and a height>)`;
+    return ["Add this line to a page:", `  ${line}`, `Then run: ${plan.manager} run dev`];
+}
+/** The plan as lines a person reads (`--dry-run`). */
+export function describe(plan, cwd) {
+    const where = relative(cwd, plan.dir) || ".";
+    return [
+        `init (dry run) in ${where}`,
+        `  package manager: ${plan.manager}`,
+        `  framework: ${plan.framework} (${plan.bundler})`,
+        ...(plan.done ? ["  already set up: nothing to install or write"] : [`  would run: ${plan.install}`, ...plan.files.map((f) => `  would write: ${f}`)]),
+        "Nothing was written (--dry-run).",
+        "",
+    ].join("\n");
+}

package/dist-lib/cli/main.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The `bin` entry (built to dist-lib/cli/main.js by tsconfig.cli.json): runs the command line and exits with its code. See run.ts.
+import { runAsync } from "./run.js";
+const result = await runAsync(process.argv.slice(2), process.cwd());
+process.stdout.write(result.out);
+process.stderr.write(result.err);
+process.exitCode = result.code;

package/dist-lib/cli/probe.js

@@ -0,0 +1,35 @@
+// What `doctor --url <page>` reads from the network: the page's policy, and the engine at the address the page names (or `/app_bg.wasm`, where `init` puts it in a Next app).
+// Only this file touches the network; `doctor.ts` turns what it returns into findings.
+import { Refusal } from "./detect.js";
+import { metaPolicies } from "./csp.js";
+const TIMEOUT_MS = 15_000;
+/** A `.wasm` address the page's HTML names, such as a preload link; the first one wins. */
+const WASM_REF = /["'(=\s]([^"'()\s<>=]+\.wasm)(?:[?#][^"'()\s<>]*)?(?=["')\s>])/;
+/** The error's message with its cause's: `fetch failed` alone does not say refused, not found or timed out. */
+const why = (e) => (e instanceof Error ? `${e.message}${e.cause instanceof Error ? ` (${e.cause.message})` : ""}` : String(e)).replace(/\s+/g, " ");
+/** Fetches `page` and its engine. A page that cannot be fetched is a refusal (exit 2); an engine that cannot be is an answer with no status, which `doctor` reports as a finding. */
+export async function probePage(page) {
+    let res;
+    let html;
+    try {
+        res = await fetch(page, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+        html = await res.text();
+    }
+    catch (e) {
+        throw new Refusal(`${page} could not be fetched: ${why(e)}`);
+    }
+    if (res.status !== 200)
+        throw new Refusal(`${page} answered with status ${res.status}, not 200; pass the address of the page that mounts the chart`);
+    const source = `the response of ${page}`;
+    const header = (res.headers.get("content-security-policy") ?? "").split(",").map((t) => t.trim()).filter(Boolean);
+    const ref = WASM_REF.exec(html)?.[1];
+    const url = new URL(ref ?? "/app_bg.wasm", res.url).href;
+    const policies = [...header.map((text) => ({ source, text })), ...metaPolicies(html, source)];
+    try {
+        const got = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+        return { page: res.url, policies, engine: { url, status: got.status, type: got.headers.get("content-type") ?? "", bytes: Buffer.from(await got.arrayBuffer()), error: "", named: ref !== undefined } };
+    }
+    catch (e) {
+        return { page: res.url, policies, engine: { url, status: null, type: "", bytes: Buffer.alloc(0), error: why(e), named: ref !== undefined } };
+    }
+}

package/dist-lib/cli/run.js

@@ -0,0 +1,92 @@
+// The command line: arguments in, exit code and the two streams out. `main.ts` only prints them and exits, so tests call this.
+//   exit 0: done, the plan printed, or `doctor` found nothing wrong. 1: `doctor` found problems. 2: could not run (bad arguments, a refusal).
+import { relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRODUCT_NAME } from "../product.js";
+import { parseArgs } from "./args.js";
+import { detect, findProjectDir, readJsonObject, Refusal } from "./detect.js";
+import { describeFindings, diagnose } from "./doctor.js";
+import { applyInit, describe, nextSteps, planInit } from "./init.js";
+import { askBrowser, BROWSER_VARIABLE } from "./gpu.js";
+import { probePage } from "./probe.js";
+/** This package's own name and version: `../../package.json` is the package's from `src/cli/` and from `dist-lib/cli/` alike. */
+function own() {
+    const { name, version } = readJsonObject(fileURLToPath(new URL("../../package.json", import.meta.url)));
+    return { name: String(name), version: String(version) };
+}
+const usage = (name) => `${PRODUCT_NAME} command line\n\nusage: ${name} init [--dry-run] [--dir <folder>] [--spec <package spec>] [--no-install] [--plain] [--json]\n       ${name} doctor [--dir <folder>] [--data <file>] [--url <page>] [--json]\n\n  init   install the package into a Vite or Next.js project and write the chart module (src/<name>-chart; for Next, components/<name>-chart and the engine file public/app_bg.wasm);\n         --dry-run only prints the plan;\n         --plain writes the module that needs no framework; a second run changes nothing\n  doctor check an installed chart and say how to fix each problem: the package listed and installed once, the engine file (in Next, its copy in public/), a stylesheet import, the page's Content-Security-Policy in the project's config (it must allow 'wasm-unsafe-eval');\n         --data checks a task data file; --url fetches the served page and checks its policy and that its engine address (the .wasm it names; in a Next app, else /app_bg.wasm) answers with the engine;\n         it writes nothing in the project, and asks a Chrome, Edge or Chromium on this machine (${BROWSER_VARIABLE} names one) whether the chart gets WebGPU or WebGL2\n\nexit codes: 0 done, 1 problems found, 2 could not run\n`;
+const refuse = (err) => ({ code: 2, out: "", err: `${err}\n` });
+/** Runs the command line `argv` (without `node` and the script) from the folder `cwd`; a file it cannot read is exit 2 and one sentence. `doctor --url` needs the page read first, and `doctor` the browser asked about the GPU: `runAsync` does both, and passes them as `probe` and `gpu`. */
+export function run(argv, cwd, probe, gpu) {
+    try {
+        return runCommand(argv, cwd, probe, gpu);
+    }
+    catch (e) {
+        if (e instanceof Refusal)
+            return refuse(e.message);
+        throw e;
+    }
+}
+/** `run`, reading the page first when `doctor` is given `--url` and asking a browser (`askGpu`) about the GPU; the entry `main.ts` calls. A page it cannot fetch is exit 2. */
+export async function runAsync(argv, cwd, askGpu = askBrowser) {
+    const args = parseArgs(argv);
+    if ("error" in args || args.command !== "doctor" || args.help || args.version)
+        return run(argv, cwd);
+    try {
+        const probe = args.url === undefined ? undefined : await probePage(args.url);
+        return run(argv, cwd, probe, await askGpu());
+    }
+    catch (e) {
+        if (e instanceof Refusal)
+            return refuse(e.message);
+        throw e;
+    }
+}
+function runCommand(argv, cwd, probe, gpu) {
+    const me = own();
+    const args = parseArgs(argv);
+    if ("error" in args)
+        return refuse(`${args.error}\n\n${usage(me.name)}`);
+    if (args.version)
+        return { code: 0, out: `${me.version}\n`, err: "" };
+    if (args.help)
+        return { code: 0, out: usage(me.name), err: "" };
+    if (args.command !== "init" && args.command !== "doctor")
+        return refuse(`${args.command === undefined ? "no command" : `unknown command ${args.command}`}\n\n${usage(me.name)}`);
+    const dir = findProjectDir(args.dir === undefined ? cwd : resolve(cwd, args.dir), args.dir !== undefined);
+    if (dir === undefined)
+        return refuse("no package.json here or in a folder above it; pass --dir <project folder>");
+    if (args.url !== undefined && args.command !== "doctor")
+        return refuse(`--url is for doctor\n\n${usage(me.name)}`);
+    if (args.url !== undefined && probe === undefined)
+        throw new Error("run cannot read a page: call runAsync for doctor --url");
+    const project = detect(dir);
+    if (args.command === "doctor") {
+        if (project.workspace && args.dir === undefined)
+            return refuse(`${dir} is a workspace root; pass --dir <the package to check>`);
+        let findings;
+        try {
+            findings = diagnose(project, me, { data: args.data === undefined ? undefined : resolve(cwd, args.data), probe, gpu });
+        }
+        catch (e) {
+            // A folder or file the check must read but cannot (permission, a vanished file) means it could not run: exit 2, never the exit 1 of a finding, and never a pass.
+            const fs = e;
+            if (e instanceof Error && typeof fs.code === "string" && typeof fs.syscall === "string")
+                throw new Refusal(`doctor could not read ${fs.path ?? "a file"} (${fs.code}); fix its permissions or remove it, then run doctor again`);
+            throw e;
+        }
+        const code = findings.some((f) => f.status === "fail") ? 1 : 0;
+        return { code, out: args.json ? `${JSON.stringify({ dir, findings }, null, 2)}\n` : describeFindings(findings, relative(cwd, dir) || "."), err: "" };
+    }
+    const options = { explicitDir: args.dir !== undefined, dryRun: args.dryRun, install: args.install, spec: args.spec, plain: args.plain };
+    const made = planInit(project, me, options);
+    if ("error" in made)
+        return refuse(made.error);
+    const { plan, outputs } = made;
+    if (args.dryRun)
+        return { code: 0, out: args.json ? `${JSON.stringify(plan, null, 2)}\n` : describe(plan, cwd), err: "" };
+    const wrote = applyInit(project, me, options, plan, outputs);
+    if (args.json)
+        return { code: 0, out: `${JSON.stringify(plan, null, 2)}\n`, err: "" };
+    return { code: 0, out: [`init in ${relative(cwd, dir) || "."}`, ...wrote, ...(plan.done ? [] : nextSteps(plan, outputs)), ""].join("\n"), err: "" };
+}

package/dist-lib/cli/template.js

@@ -0,0 +1,52 @@
+// The chart module `init` writes into a project: three sample tasks, the stylesheet, and the call that removes the chart.
+// `name` is the package's own name, read at run time (the product's name is written in one place only).
+const SAMPLE = `const tasks = [
+  { id: 1, name: "Design", start: "2026-11-02", duration: 3 },
+  { id: 2, name: "Build", start: "2026-11-05", duration: 5 },
+  { id: 3, name: "Ship", start: "2026-11-12", duration: 1 },
+];
+const links = [
+  { from: 1, to: 2 },
+  { from: 2, to: 3 },
+];
+`;
+/** The module's text: `kind` is a React component or a function for any page; `ts` adds the types; `next` marks it a client component and names the engine file in public/. */
+export function chartModule(kind, ts, name, next = false) {
+    const use = next ? `"use client";\n` : "";
+    const options = next ? `{ tasks, links, wasmUrl: "/app_bg.wasm" }` : "{ tasks, links }";
+    if (kind === "plain") {
+        return `${use}// Draws the chart in a div with the class "gantt" and a height. Call it once the page has the div; keep what it returns and call that to remove the chart.
+import { mount } from "${name}";
+import "${name}/gantt.css";
+
+${SAMPLE}
+export async function mountChart(element${ts ? ": HTMLDivElement" : ""})${ts ? ": Promise<() => void>" : ""} {
+  const chart = await mount(element, ${options});
+  return () => chart.destroy();
+}
+`;
+    }
+    return `${use}// The chart as a React component: <Chart /> draws it when it mounts and removes it when it unmounts.
+import { useEffect, useRef } from "react";
+import { mount${ts ? ", type Gantt" : ""} } from "${name}";
+import "${name}/gantt.css";
+
+${SAMPLE}
+export default function Chart() {
+  const element = useRef${ts ? "<HTMLDivElement>" : ""}(null);
+  useEffect(() => {
+    let chart${ts ? ": Gantt | undefined" : ""};
+    let unmounted = false;
+    mount(element.current${ts ? " as HTMLDivElement" : ""}, ${options}).then((made) => {
+      if (unmounted) made.destroy();
+      else chart = made;
+    });
+    return () => {
+      unmounted = true;
+      chart?.destroy();
+    };
+  }, []);
+  return <div ref={element} className="gantt" style={{ width: "100%", height: 300 }} />;
+}
+`;
+}

package/dist-lib/engine-size.json

@@ -0,0 +1 @@
+{"bytes":5693596}

package/dist-lib/errors.js

@@ -0,0 +1,44 @@
+// What a failed start tells a person or a coding assistant (tl#1249): one stable `code` for each cause `mount` can name, and for each
+// code one `fix`, a sentence to act on. The code is the product name in capitals and the cause (`<NAME>_ENGINE_FETCH`), read from
+// `PRODUCT_NAME`, so a rename is that file. This file is pure: no DOM, no wasm. `mount-load.ts` probes the page and asks it what to say.
+import { PRODUCT_NAME } from "./product.js"; // `.ts`, so the Node tier can load this file as it loads the adapters
+/** Every cause `mount` names, with the sentence that says what to do. */
+const FIXES = {
+    DATA_INVALID: "Correct the fields `message` lists and call `mount` again; `validate(data)` checks plain task data against the same rules without mounting.",
+    ENGINE_FETCH: "Serve the engine file (`app_bg.wasm`, the file the chart's script names with `new URL`) from the address the page asks for, with status 200; the `message` has the status.",
+    ENGINE_NOT_WASM: "The address answers with something other than the engine. Serve the file `app_bg.wasm` itself, as `application/wasm`, and make a single-page fallback route skip `.wasm` files.",
+    ENGINE_LOAD_FAILED: "The file is the engine, but it did not start. Rebuild so `app.js` and `app_bg.wasm` come from the same build, and read the browser console and the error in `cause` for the underlying error.",
+    ENGINE_CSP: "Add `'wasm-unsafe-eval'` to the page's `script-src` (or `default-src`) in its Content-Security-Policy, so the browser may compile the engine.",
+    GPU_NONE: "The browser has neither WebGPU nor WebGL2 here. Try a current Chrome, Edge, Firefox or Safari with hardware acceleration on; a headless or remote desktop session often has none.",
+    FILE_UNREADABLE: "The browser could not read the `File` given as `schedule`: it was moved, deleted or is locked. Pick the file again and call `mount` again.",
+};
+/** Where the codes are explained: a heading in `docs/WASM_API.md`, the page that lists every code with its `fix`. */
+export const ERROR_DOCS = "docs/WASM_API.md#mount-error-codes";
+/** The code for a cause. */
+export function codeFor(cause) {
+    return `${PRODUCT_NAME.toUpperCase()}_${cause}`;
+}
+/** The sentence that says what to do about `code`. */
+export function fixFor(code) {
+    return FIXES[code.slice(PRODUCT_NAME.length + 1)];
+}
+const MAGIC = [0x00, 0x61, 0x73, 0x6d];
+/** The code and the one line for a failed engine load, from the probe and from what `init` threw. A pure function of both. */
+export function engineFailure(probe, thrown) {
+    const text = thrown instanceof Error ? thrown.message : String(thrown);
+    if (probe.status === null)
+        return { code: codeFor("ENGINE_FETCH"), message: `The chart's engine file could not be requested: ${text}` };
+    if (probe.status < 200 || probe.status > 299)
+        return { code: codeFor("ENGINE_FETCH"), message: `The chart's engine file answered with status ${probe.status}.` };
+    if (!MAGIC.every((byte, i) => probe.head[i] === byte)) {
+        const shown = [...probe.head].map((b) => (b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : `\\x${b.toString(16).padStart(2, "0")}`)).join("");
+        return { code: codeFor("ENGINE_NOT_WASM"), message: `The chart's engine file is not WebAssembly: it starts with "${shown}", not "\\0asm".` };
+    }
+    if (/content security polic|blocked by CSP/i.test(text))
+        return { code: codeFor("ENGINE_CSP"), message: "The page's Content-Security-Policy does not let the browser compile the chart's engine." };
+    return { code: codeFor("ENGINE_LOAD_FAILED"), message: `The chart's engine file is WebAssembly, but it did not start: ${text}` };
+}
+/** `GPU_NONE` when the browser has neither a WebGPU adapter (`gpu`) nor WebGL2 (`webgl2`, asked only when `gpu` is false), else `undefined`. */
+export function graphicsCode(gpu, webgl2) {
+    return gpu || webgl2() ? undefined : codeFor("GPU_NONE");
+}