@downdraft/cli 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downdraft/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/knackstedt/downdraft.git",
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.700.0",
-    "@downdraft/engine": "^0.1.0",
+    "@downdraft/engine": "^0.2.0",
     "eta": "^3.5.0",
     "jimp": "^1.6.1",
     "resedit": "3.1.0"
@@ -31,7 +31,8 @@
     "scripts",
     "templates",
     "README.md",
-    "!**/*.spec.ts"
+    "!**/*.spec.ts",
+    "!**/*.test.ts"
   ],
   "description": "The `draft` command-line tool — project scaffolding (draft new), dev server, builds, release packaging, mobile targets, and plugin/module scaffolding."
 }

package/scripts/engine-source.mjs

@@ -0,0 +1,45 @@
+// engine-source.mjs — decides whether bundling resolves @downdraft/* via
+// the "downdraft-source" export condition (TypeScript src/) or the default
+// condition (pre-built dist/).
+//
+// Published packages ship dist/ so standalone consumers bundle fast-built
+// ESM. In the engine monorepo (or any install where dist/ hasn't been
+// generated) the default target doesn't exist — without this the packager
+// fails with "Could not resolve: @downdraft/...". Mirrors `draft dev`'s
+// rule: monorepo defaults to source, everything else defaults to dist,
+// --engine-source / --engine-dist override.
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SOURCE_CONDITION = "downdraft-source";
+
+const monorepoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+
+function enginePkgRoot(fromFile) {
+  try {
+    const req = createRequire(resolve(fromFile));
+    return dirname(req.resolve("@downdraft/engine/package.json"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string[]} argv raw flag list (process.argv.slice(2))
+ * @param {string} fromFile file to anchor @downdraft/engine resolution at
+ *   (typically the game entry — covers workspace links and standalone repos)
+ * @returns {string[] | undefined} Bun.build `conditions` override
+ */
+export function engineConditions(argv, fromFile) {
+  if (argv.includes("--engine-dist")) return undefined;
+  if (argv.includes("--engine-source")) return [SOURCE_CONDITION];
+  const pkg = enginePkgRoot(fromFile);
+  // Workspace-linked engine → always source (a stale dist/ would silently
+  // package old code). Standalone consumer → dist when it exists.
+  if (!pkg || pkg.startsWith(monorepoRoot + sep) || !existsSync(join(pkg, "dist"))) {
+    return [SOURCE_CONDITION];
+  }
+  return undefined;
+}

package/scripts/native-lib-fetch.mjs

@@ -0,0 +1,63 @@
+// ============================================================================
+// native-lib-fetch.mjs — fetch @downdraft/native-<plat>-<arch> lib dirs
+//
+// The per-platform binary packages are published to npm as optional deps of
+// @downdraft/platform-native, but npm/bun/deno skip installing packages whose
+// os/cpu don't match the host — so cross-packaging (--target=win from linux,
+// etc.) has no local copy of the target's cdylibs. The tarballs are still on
+// the registry though; this fetches and caches them under
+// <cacheRoot>/downdraft-native/<plat>-<arch>/lib.
+// ============================================================================
+
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * Return a dir containing the target platform's cdylibs — the first existing
+ * candidate, else the @downdraft/native-<platKey> npm tarball fetched into
+ * the cache. Returns null when nothing is available.
+ *
+ * @param {string} platKey e.g. "win32-x64", "darwin-arm64"
+ * @param {string[]} candidates existing dirs to try before fetching
+ * @param {string} cacheRoot parent dir for the fetch cache
+ * @param {string|null} version preferred package version (platform-native's,
+ *   lockstep) — falls back to the registry's latest tag
+ */
+export async function resolvePlatLibDir(platKey, candidates, cacheRoot, version) {
+  const hit = candidates.find((d) => d && existsSync(d));
+  if (hit) return hit;
+
+  const pkgName = `@downdraft/native-${platKey}`;
+  const cacheDir = join(cacheRoot, "downdraft-native", platKey, "lib");
+  if (existsSync(cacheDir) && readdirSync(cacheDir).length > 0) return cacheDir;
+
+  try {
+    const meta = await (await fetch(
+      `https://registry.npmjs.org/${pkgName.replace("/", "%2F")}`)).json();
+    const ver = meta?.versions?.[version] ? version : meta?.["dist-tags"]?.latest;
+    const tarball = ver && meta.versions[ver]?.dist?.tarball;
+    if (!tarball) return null;
+
+    const tmp = mkdtempSync(join(tmpdir(), "dd-native-"));
+    try {
+      const tgz = join(tmp, "pkg.tgz");
+      writeFileSync(tgz, Buffer.from(await (await fetch(tarball)).arrayBuffer()));
+      execFileSync("tar", ["-xzf", tgz, "-C", tmp], { stdio: "pipe" });
+      const libDir = join(tmp, "package", "lib");
+      if (!existsSync(libDir) || readdirSync(libDir).length === 0) return null;
+      rmSync(dirname(cacheDir), { recursive: true, force: true });
+      mkdirSync(dirname(cacheDir), { recursive: true });
+      // cpSync not renameSync: TMPDIR may be a different filesystem.
+      cpSync(libDir, cacheDir, { recursive: true });
+      console.log(`[package] fetched ${pkgName}@${ver} from npm → ${cacheDir}`);
+      return cacheDir;
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  } catch (e) {
+    console.warn(`[package] ${pkgName} fetch failed: ${e?.message ?? e}`);
+    return null;
+  }
+}

package/scripts/package-desktop.mjs

@@ -69,6 +69,8 @@ import {
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { engineConditions } from "./engine-source.mjs";
+import { resolvePlatLibDir } from "./native-lib-fetch.mjs";
 
 // ── Args ──
 
@@ -100,7 +102,7 @@ if (!["bun", "node", "deno"].includes(runtime)) {
 const formats = (flagValue("format") ?? (Array.isArray(linuxCfg.target) ? linuxCfg.target.join(",") : linuxCfg.target) ?? "dir")
   .split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
 const KNOWN_FORMATS = new Set(["dir", "deb", "appimage", "flatpak"]);
-for (const f of formats) {
+for (const f of formats.values()) {
   if (!KNOWN_FORMATS.has(f)) {
     console.error(`unknown --format "${f}" — expected dir, deb, appimage, or flatpak`);
     process.exit(1);
@@ -208,7 +210,7 @@ function assetRel(absPath) {
 function walkDir(dir, results = []) {
   let entries;
   try { entries = readdirSync(dir); } catch { return results; }
-  for (const e of entries) {
+  for (const e of entries.values()) {
     const full = `${dir}/${e}`;
     let st;
     try { st = statSync(full); } catch { continue; }
@@ -461,6 +463,7 @@ const makeEmitPlugin = (collectWorkers) => ({
 
 // ── Scan pass: discover Worker entrypoints to a fixpoint ──
 
+const engineConds = engineConditions(argv, resolve(entry));
 const scanOutdir = mkdtempSync(join(tmpdir(), "dd-scan-"));
 let prevCount = -1;
 while (workerEntries.size !== prevCount) {
@@ -468,6 +471,7 @@ while (workerEntries.size !== prevCount) {
   const scan = await Bun.build({
     entrypoints: [resolve(entry), ...workerEntries],
     target: "node",
+    conditions: engineConds,
     plugins: [makeEmitPlugin(true)],
     splitting: false,
     sourcemap: "none",
@@ -509,16 +513,21 @@ async function stageEngineLibs(nativeDir) {
   const platLibCandidates = [...new Set([
     join(repoRoot, "packages/platform-native/native", platKey),
     platPkg && join(platPkg, "native", platKey),
+    platPkg && join(platPkg, platKey),
     platNpm && join(platNpm, "lib"),
   ].filter(Boolean))];
-  const platStageDir = platLibCandidates.find((d) => existsSync(d));
-  if (platStageDir) {
-    for (const f of readdirSync(platStageDir)) {
-      if (f.endsWith(libExt)) copyFileSync(join(platStageDir, f), join(nativeDir, f));
-    }
-  } else {
+  // Foreign-platform optional deps aren't installed on this host — fetch
+  // the @downdraft/native-<plat>-<arch> tarball from npm into a cache.
+  const platPkgVersion = platPkg &&
+    JSON.parse(readFileSync(join(platPkg, "package.json"), "utf8")).version;
+  const platStageDir = await resolvePlatLibDir(
+    platKey, platLibCandidates, join(gameDir, "node_modules", ".cache"), platPkgVersion);
+  if (!platStageDir) {
     throw new Error(`no libdowndraft_platform build found for ${platKey} — searched: ${platLibCandidates.join(", ")}`);
   }
+  for (const f of readdirSync(platStageDir)) {
+    if (f.endsWith(libExt)) copyFileSync(join(platStageDir, f), join(nativeDir, f));
+  }
   // Engine cdylibs via the shared crate registry (same candidates as
   // package-native.mjs).
   let CRATES = [];
@@ -540,7 +549,7 @@ async function stageEngineLibs(nativeDir) {
         join(engineRoot, pkgRel, "dist", file),
       ] : []),
     ];
-    for (const p of candidates) {
+    for (const p of candidates.values()) {
       if (existsSync(p)) { copyFileSync(p, join(nativeDir, file)); break; }
     }
   }
@@ -586,6 +595,7 @@ if (runtime === "bun") {
     entrypoints,
     target: "node",
     root: repoRoot,
+    conditions: engineConds,
     naming: { entry: "[dir]/[name].mjs" },
     plugins: [makeEmitPlugin(false)],
     splitting: false,
@@ -663,7 +673,7 @@ stageGameNative(nativeDir);
   let grew = true;
   while (grew) {
     grew = false;
-    for (const f of [...assetFiles]) {
+    for (const f of [...assetFiles].values()) {
       if (!/\.(mjs|cjs|js)$/.test(f)) continue;
       let src;
       try { src = readFileSync(f, "utf-8"); } catch { continue; }
@@ -694,7 +704,7 @@ if (runtime !== "bun") {
 }
 
 // build.files — electron-builder-style extra files into the appdir root.
-for (const f of Array.isArray(build.files) ? build.files : []) {
+for (const f of (Array.isArray(build.files) ? build.files : []).values()) {
   const src = resolve(gameDir, typeof f === "string" ? f : f.from);
   const dest = join(appdir, typeof f === "string" ? basename(f) : (f.to ?? basename(f.from)));
   if (!existsSync(src)) { console.warn(`[package-desktop] files entry missing: ${src}`); continue; }
@@ -736,7 +746,7 @@ async function iconSet(destDir) {
     const { Jimp } = await import("jimp");
     img = await Jimp.read(iconPath);
   } catch { /* unreadable — verbatim fallback below */ }
-  for (const s of sizes) {
+  for (const s of sizes.values()) {
     const dir = join(destDir, `${s}x${s}`, "apps");
     mkdirSync(dir, { recursive: true });
     const dest = join(dir, `${exeName}.png`);
@@ -928,4 +938,4 @@ async function fetchKoffiPrebuild(pkgName, ver) {
 }
 
 console.log(`[package-desktop] done (${runtime}):`);
-for (const a of artifacts) console.log(`  ${a}`);
+for (const a of artifacts.values()) console.log(`  ${a}`);

package/scripts/package-mobile.mjs

@@ -39,6 +39,7 @@ import {
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { engineConditions } from "./engine-source.mjs";
 
 // ── args ──
 
@@ -77,11 +78,12 @@ if (!entry || !outfileArg) {
 const ABIS = { "arm64-v8a": "aarch64-linux-android", "x86_64": "x86_64-linux-android" };
 const KOFFI_PKGS = { "arm64-v8a": "@koromix/koffi-android-arm64", "x86_64": "@koromix/koffi-android-x64" };
 const abis = abiArg === "all" ? Object.keys(ABIS) : abiArg.split(",").map((s) => s.trim());
-for (const a of abis) {
+for (const a of abis.values()) {
   if (!ABIS[a]) throw new Error(`unknown --abi "${a}" — expected: ${Object.keys(ABIS).join(", ")}, all`);
 }
 
 const repoRoot = process.cwd();
+const engineConds = engineConditions(argv, resolve(entry));
 const scriptDir = dirname(fileURLToPath(import.meta.url));
 const monorepoRoot = resolve(scriptDir, "../../..");
 const gameDir = dirname(dirname(resolve(entry)));
@@ -117,7 +119,7 @@ const btVer = readdirSync(btRoot).sort().pop();
 const bt = join(btRoot, btVer);
 const platformDir = readdirSync(join(sdkRoot, "platforms")).sort().pop();
 const androidJar = join(sdkRoot, "platforms", platformDir, "android.jar");
-for (const tool of ["aapt2", "zipalign", "apksigner"]) {
+for (const tool of ["aapt2", "zipalign", "apksigner"].values()) {
   if (!existsSync(join(bt, tool))) throw new Error(`missing build-tool ${tool} in ${bt}`);
 }
 const adb = join(sdkRoot, "platform-tools", "adb");
@@ -185,7 +187,7 @@ function assetRel(absPath) {
 function walkDir(dir, results = []) {
   let entries;
   try { entries = readdirSync(dir); } catch { return results; }
-  for (const e of entries) {
+  for (const e of entries.values()) {
     const full = `${dir}/${e}`;
     let st;
     try { st = statSync(full); } catch { continue; }
@@ -443,6 +445,7 @@ while (workerEntries.size !== prevCount) {
   const scan = await Bun.build({
     entrypoints: [resolve(entry), ...workerEntries],
     target: "node",
+    conditions: engineConds,
     plugins: [makePlugin(true)],
     splitting: false,
     sourcemap: "none",
@@ -466,6 +469,7 @@ const build = await Bun.build({
   // No `compile` — libnode executes the extracted ESM files.
   target: "node",
   root: repoRoot,
+  conditions: engineConds,
   naming: { entry: "[dir]/[name].mjs" },
   plugins: [makePlugin(false)],
   splitting: false,
@@ -500,7 +504,7 @@ if (!koffiRoot) {
   const nm = join(bundleDir, "node_modules");
   cpSync(koffiRoot, join(nm, "koffi"), { recursive: true });
   const koffiVer = JSON.parse(readFileSync(join(koffiRoot, "package.json"), "utf-8")).version;
-  for (const abi of abis) {
+  for (const abi of abis.values()) {
     const pkgName = KOFFI_PKGS[abi];
     // The @koromix prebuild pkgs carry no importable entry — probe the dir
     // beside koffi (same layout koffi's loader expects), else fetch npm.
@@ -544,7 +548,7 @@ async function fetchKoffiPrebuild(pkgName, ver) {
   let grew = true;
   while (grew) {
     grew = false;
-    for (const f of [...assetFiles]) {
+    for (const f of [...assetFiles].values()) {
       if (!/\.(mjs|cjs|js)$/.test(f)) continue;
       let src;
       try { src = readFileSync(f, "utf-8"); } catch { continue; }
@@ -573,7 +577,7 @@ for (const f of assetFiles.values()) {
 // dd-env.txt — optional process env for the JS thread (debug probes like
 // DD_BENCH_TEST; Android has no launch-env channel).
 if (envPairs.length) {
-  for (const p of envPairs) {
+  for (const p of envPairs.values()) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*=/.test(p)) {
       throw new Error(`--env "${p}" must be KEY=VALUE (KEY: [A-Za-z_][A-Za-z0-9_]*)`);
     }
@@ -591,7 +595,7 @@ if (envPairs.length) {
 // (.so siblings are handled per-ABI in the native-libs section below.)
 {
   let staged = 0;
-  for (const abi of abis) {
+  for (const abi of abis.values()) {
     const platDir = join(gameDir, "native", "dist",
       `android-${abi.startsWith("arm64") ? "arm64" : "x64"}`);
     if (!existsSync(platDir)) continue;
@@ -661,7 +665,7 @@ const bundleText = walkDir(bundleDir)
   .map((f) => readFileSync(f, "utf-8"))
   .join("\n");
 
-for (const abi of abis) {
+for (const abi of abis.values()) {
   const triple = ABIS[abi];
   const libDir = join(nativeStage, abi);
   mkdirSync(libDir, { recursive: true });
@@ -717,7 +721,7 @@ for (const abi of abis) {
   // --libs= forces). JS resolves them by soname via the app lib dir.
   const crates = await import(fileURLToPath(new URL("../../../scripts/native-crates.mjs", import.meta.url)));
   const nodePlat = `android-${abi.startsWith("arm64") ? "arm64" : "x64"}`;
-  for (const crate of crates.CRATES) {
+  for (const crate of crates.CRATES.values()) {
     if (crate.androidOnly || crate.noAndroid) continue;
     const name = crate.lib.replace(/^downdraft_/, "");
     if (excludeLibs.includes(name) || excludeLibs.includes(crate.lib)) continue;

package/scripts/package-native.mjs

@@ -46,6 +46,8 @@ import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { engineConditions } from "./engine-source.mjs";
+import { resolvePlatLibDir } from "./native-lib-fetch.mjs";
 
 // CRATES is shared with the repo's scripts/native-crates.mjs when this file
 // runs inside the monorepo. In a published @downdraft/cli install the repo
@@ -100,6 +102,7 @@ let outfile = outfileArg;
 if (target.exe && !outfile.endsWith(".exe")) outfile += ".exe";
 
 const repoRoot = process.cwd();
+const engineConds = engineConditions(argv, resolve(entry));
 const QUERY_RE = /\?(raw|url|json)$/;
 const WORKER_RE = /new\s+Worker\(\s*new\s+URL\(\s*["'`]([^"'`]+)["'`]\s*,\s*import\.meta\.url\s*\)/g;
 const ASSET_URL_RE = /new\s+URL\(\s*["'`]([^"'`]+)["'`]\s*,\s*import\.meta\.url\s*\)/g;
@@ -397,6 +400,7 @@ while (workerEntries.size !== prevCount) {
   const scan = await Bun.build({
     entrypoints: [resolve(entry), ...workerEntries],
     target: "bun",
+    conditions: engineConds,
     plugins: [makePlugin(true)],
     splitting: false,
     sourcemap: "none",
@@ -419,6 +423,7 @@ const result = await Bun.build({
   entrypoints,
   compile: { outfile: resolve(outfile), ...(target.bun ? { target: target.bun } : {}) },
   target: "bun",
+  conditions: engineConds,
   plugins: [makePlugin(false)],
   splitting: false,
   sourcemap: "none",
@@ -560,20 +565,26 @@ function pkgRoot(name) {
 // wgpu — no external deps) stages under native/<platform>-<arch>/. Probe
 // order: monorepo dev staging, the installed platform-native package, the
 // per-target @downdraft/native-<plat>-<arch> package.
+const platPkg = pkgRoot("@downdraft/platform-native");
 const platLibCandidates = [...new Set([
   join(monorepoRoot, "packages/platform-native/native", platKey),
-  pkgRoot("@downdraft/platform-native") && join(pkgRoot("@downdraft/platform-native"), "native", platKey),
+  platPkg && join(platPkg, "native", platKey),
+  platPkg && join(platPkg, platKey),
   pkgRoot(`@downdraft/native-${platKey}`) && join(pkgRoot(`@downdraft/native-${platKey}`), "lib"),
 ].filter(Boolean))];
-const platStageDir = platLibCandidates.find((d) => existsSync(d));
-if (platStageDir) {
-  for (const f of readdirSync(platStageDir)) {
-    if (f.endsWith(libExt)) copyFileSync(join(platStageDir, f), join(nativeDir, f));
-  }
-} else {
+// Foreign-platform optional deps aren't installed on this host — fetch the
+// @downdraft/native-<plat>-<arch> tarball from npm into a cache instead.
+const platPkgVersion = platPkg &&
+  JSON.parse(readFileSync(join(platPkg, "package.json"), "utf8")).version;
+const platStageDir = await resolvePlatLibDir(
+  platKey, platLibCandidates, join(gameDir, "node_modules", ".cache"), platPkgVersion);
+if (!platStageDir) {
   console.error(`no libdowndraft_platform build found for ${platKey} — searched: ${platLibCandidates.join(", ")}`);
   process.exit(1);
 }
+for (const f of readdirSync(platStageDir)) {
+  if (f.endsWith(libExt)) copyFileSync(join(platStageDir, f), join(nativeDir, f));
+}
 
 // Engine cdylibs — staged if a build exists: new dist/<plat>-<arch>/ and
 // dist/ layouts (build-native.mjs), the installed @downdraft/engine package

package/src/dev.ts

@@ -6,7 +6,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, print, renderHelp } from "./args";
 import { formatGamesList } from "./list-games";
-import { buildCwd, findMonorepoRoot } from "./paths";
+import { buildCwd, findMonorepoRoot, readGameConfig } from "./paths";
 import { killProcessTree } from "./process-utils";
 import { getCommand } from "./usage";
 
@@ -76,8 +76,8 @@ export async function dev(args: string[]): Promise<void> {
 async function devNative(parsed: any): Promise<void> {
   const resolved = resolveGameDir();
   if (!resolved) {
-    log.error("DownDraft", `No game directory found (looking for downdraft.config.json or src/native-entry.ts from "${process.cwd()}").`);
-    log.error("DownDraft", `Run "draft dev" from a game directory.`);
+    log.error("draft", `No game directory found (looking for downdraft.config.json or src/native-entry.ts from "${process.cwd()}").`);
+    log.error("draft", `Run "draft dev" from a game directory.`);
     print(formatGamesList(findMonorepoRoot() ?? process.cwd()));
     process.exit(1);
   }
@@ -86,8 +86,8 @@ async function devNative(parsed: any): Promise<void> {
   const nativeEntry = resolve(gameDir, NATIVE_ENTRY);
 
   if (!existsSync(nativeEntry)) {
-    log.error("DownDraft", `No native entry point found at "${nativeEntry}".`);
-    log.error("DownDraft", `The game "${game}" needs a src/native-entry.ts to run on the native runtime.`);
+    log.error("draft", `No native entry point found at "${nativeEntry}".`);
+    log.error("draft", `The game "${game}" needs a src/native-entry.ts to run on the native runtime.`);
     process.exit(1);
   }
 
@@ -97,6 +97,9 @@ async function devNative(parsed: any): Promise<void> {
   const env = { ...process.env };
   const port = parsed.flags.port as number;
   if (port) env.MCP_PORT = String(port);
+  // --native-debug → the runtime resolves <plat>-<arch>-debug/ lib dirs
+  // (staged by build-native.mjs --debug) instead of release artifacts.
+  if (parsed.flags["native-debug"]) env.DD_NATIVE_PROFILE = "debug";
 
   // Signal handling lives outside the respawn loop — each spawn registers
   // itself as the current child so SIGINT/SIGTERM always hit the live one.
@@ -105,7 +108,7 @@ async function devNative(parsed: any): Promise<void> {
   const onSignal = () => {
     if (shuttingDown) return;
     shuttingDown = true;
-    log.info("DownDraft", "Shutting down...");
+    log.info("draft", "Shutting down...");
     const child = currentChild;
     try { child?.kill("SIGINT"); } catch {}
     if (child?.pid) {
@@ -126,9 +129,7 @@ async function devNative(parsed: any): Promise<void> {
   // ── Legacy path: --no-hmr spawns the entry directly under Bun (no watcher,
   //    no ModuleRunner — the pre-HMR behavior, kept as an escape hatch). ──
   if (noHmr) {
-    log.info("DownDraft", "Starting in native mode — direct spawn, no HMR (--no-hmr)...");
-    log.info("DownDraft", `  Game: ${game}`);
-    log.info("DownDraft", `  Entry: ${nativeEntry}`);
+    log.info("draft", `dev ${game} — ${nativeEntry} (bun, no hmr)`);
     const code = await spawnAndForward("bun", ["run", nativeEntry], buildCwd(gameDir), env, {
       onChild: (c) => { currentChild = c; },
     });
@@ -140,8 +141,8 @@ async function devNative(parsed: any): Promise<void> {
   const devDir = resolveDevShellDir();
   const devShell = join(devDir, "dev-shell.mjs");
   if (!existsSync(devShell)) {
-    log.error("DownDraft", `Dev shell not found at "${devShell}".`);
-    log.error("DownDraft", "Is @downdraft/platform-native installed? Try `draft dev --no-hmr` for the legacy path.");
+    log.error("draft", `Dev shell not found at "${devShell}".`);
+    log.error("draft", "Is @downdraft/platform-native installed? Try `draft dev --no-hmr` for the legacy path.");
     process.exit(1);
   }
 
@@ -149,13 +150,18 @@ async function devNative(parsed: any): Promise<void> {
   const { detectRuntime, spawnArgsFor, findDenoConfig } =
     await import(resolve(devDir, "runtime-detect.mjs"));
 
-  const requested = (parsed.flags.runtime as string | undefined) ?? process.env.DD_RUNTIME;
+  // --runtime flag → DD_RUNTIME → downdraft.config.json "runtime" → detect.
+  // (absent flags parse as "" here, so || not ??)
+  const requested = (parsed.flags.runtime as string | undefined)
+    || process.env.DD_RUNTIME
+    || (readGameConfig(gameDir).runtime as string | undefined)
+    || undefined;
   const runtime = detectRuntime(requested);
   if (!runtime) {
     if (requested) {
-      log.error("DownDraft", `Requested runtime "${requested}" is not available on PATH.`);
+      log.error("draft", `Requested runtime "${requested}" is not available on PATH.`);
     } else {
-      log.error("DownDraft", "No JS runtime found — need one of: bun, node, deno.");
+      log.error("draft", "No JS runtime found — need one of: bun, node, deno.");
     }
     process.exit(1);
   }
@@ -165,19 +171,43 @@ async function devNative(parsed: any): Promise<void> {
   env.DD_RUNTIME = runtime;
   env.DD_HMR = "1";
   env.DOWNDRAFT_DEV = "1";
-  if (verbose) env.DD_VERBOSE = "1";
+  if (verbose) {
+    env.DD_VERBOSE = "1";
+    // Diagnostics demoted below info (vite internals, pacing, gpu-registry)
+    // become visible under --verbose unless an explicit level is set.
+    env.EMBER_LOG_LEVEL = env.EMBER_LOG_LEVEL ?? "debug";
+  }
   const repoRoot = findMonorepoRoot();
   if (repoRoot) env.DD_REPO_ROOT = repoRoot;
 
+  // Engine resolution mode: "downdraft-source" resolves @downdraft/* to
+  // linked TypeScript source (per-module transforms + full engine HMR) —
+  // the default in the monorepo. Everything else resolves the pre-built
+  // dist/ tree (externalized native ESM — near-zero transform cost, no
+  // engine-file HMR). --engine-source/--engine-dist override.
+  let engineSource: boolean;
+  if (parsed.flags["engine-source"]) engineSource = true;
+  else if (parsed.flags["engine-dist"]) engineSource = false;
+  else engineSource = !!repoRoot;
+  if (!engineSource && !engineDistExists(gameDir)) {
+    log.warn("draft",
+      "engine dist/ not found — run `bun run build:dist` in the engine repo " +
+      "(or reinstall @downdraft/engine); resolving engine from source.");
+    engineSource = true;
+  }
+  env.DD_ENGINE_SOURCE = engineSource ? "1" : "";
+  env.DD_ENGINE_DIST = engineSource ? "" : "1";
+  // Deno reads export conditions from the env (flag equivalent passed to
+  // spawnArgsFor below); the var also propagates to Deno workers.
+  if (engineSource) env.DENO_CONDITIONS = "downdraft-source";
+
   const { cmd, args } = spawnArgsFor(runtime, devShell, {
     configPath: runtime === "deno" ? findDenoConfig(gameDir, repoRoot) : undefined,
+    conditions: engineSource ? ["downdraft-source"] : [],
   });
 
-  log.info("DownDraft", `Starting in native mode (${runtime} + SDL + wgpu-native, HMR on)...`);
-  log.info("DownDraft", `  Game: ${game}`);
-  log.info("DownDraft", `  Entry: ${nativeEntry}`);
-  log.info("DownDraft", `  Runtime: ${cmd} ${args.join(" ")}`);
-  if (verbose) log.info("DownDraft", "  Verbose: on");
+  log.info("draft", `dev ${game} — ${nativeEntry} (runtime=${runtime}, hmr, engine=${engineSource ? "source" : "dist"})`);
+  if (verbose) log.info("draft", `dev shell: ${cmd} ${args.join(" ")}`);
 
   // Respawn loop: the dev shell exits with DD_RESTART_EXIT when a changed
   // file affects the loader/config layer (Tier-5) — respawn in place.
@@ -187,13 +217,24 @@ async function devNative(parsed: any): Promise<void> {
     });
     if (shuttingDown) return; // signal handler already owns exit
     if (code === DD_RESTART_EXIT) {
-      log.info("DownDraft", "Restarting dev shell (infrastructure change)...");
+      log.info("draft", "Restarting dev shell (infrastructure change)...");
       continue;
     }
     process.exit(code);
   }
 }
 
+/** True when the resolved @downdraft/engine package has a pre-built dist/. */
+function engineDistExists(gameDir: string): boolean {
+  try {
+    const req = createRequire(join(gameDir, "package.json"));
+    const pkgRoot = dirname(req.resolve("@downdraft/engine/package.json"));
+    return existsSync(join(pkgRoot, "dist"));
+  } catch {
+    return false;
+  }
+}
+
 /** Spawn `cmd args`, forward stdio, resolve the exit code (signal exits are
  *  mapped to 128+n so the caller's respawn loop can distinguish them). */
 function spawnAndForward(
@@ -216,7 +257,7 @@ function spawnAndForward(
 
   return new Promise<number>((resolvePromise, reject) => {
     child.on("error", (err) => {
-      log.error("DownDraft", `Failed to spawn ${cmd}: ${err.message}`);
+      log.error("draft", `Failed to spawn ${cmd}: ${err.message}`);
       reject(err);
     });
 

package/src/index.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { createLogger } from "@downdraft/engine";
+import { createLogger, getLogTheme } from "@downdraft/engine";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ArgError, print, renderHelp } from "./args";
@@ -19,6 +19,12 @@ import { getCommand, renderTopLevelHelp } from "./usage";
 
 const log = createLogger();
 
+// Detect the log theme once against the real TTY and hand it to every
+// spawned child (dev shell, games, test runner) — their piped stdout can't
+// answer the OSC-11 probe, so without this they re-run blocking
+// gsettings/dbus probes per process. An explicit DD_LOG_THEME wins.
+process.env.DD_LOG_THEME ??= getLogTheme();
+
 // Read the CLI package version for --version output.
 function getCliVersion(): string {
   try {
@@ -53,8 +59,8 @@ async function main() {
     }
     const entry = getCommand(target);
     if (!entry) {
-      log.error("CLI", `Unknown command: ${target}`);
-      log.info("CLI", `Run 'draft --help' for the list of commands.`);
+      log.error("draft", `Unknown command: ${target}`);
+      log.info("draft", `Run 'draft --help' for the list of commands.`);
       process.exit(1);
     }
     print(renderHelp(entry.usage, entry.schema));
@@ -88,7 +94,7 @@ async function main() {
         await exportGame(process.argv.slice(3));
         break;
       case "mobile":
-        log.error("CLI", "`draft mobile` is removed — the Capacitor WebView shell was dormant and has been deleted. Mobile support returns with a native (winit+wgpu) port.");
+        log.error("draft", "`draft mobile` is removed — the Capacitor WebView shell was dormant and has been deleted. Mobile support returns with a native (winit+wgpu) port.");
         process.exit(1);
       case "assets":
         await assets(process.argv.slice(3));
@@ -103,7 +109,7 @@ async function main() {
         await pluginCommand(process.argv.slice(3));
         break;
       case "mod":
-        // `dd mod` is an alias for `dd plugin` but defaults to mod.json format.
+        // `draft mod` is an alias for `draft plugin` but defaults to mod.json format.
         await pluginCommand(["--mod", ...process.argv.slice(3)]);
         break;
       default:
@@ -112,7 +118,7 @@ async function main() {
     }
   } catch (err) {
     if (err instanceof ArgError) {
-      log.error("CLI", err.message);
+      log.error("draft", err.message);
       const entry = getCommand(command);
       if (entry) {
         print("");

package/src/mcp.ts

@@ -36,6 +36,7 @@ interface McpFlags {
     pid: number;
     url: string;
     token: string;
+    editor: boolean;
     json: boolean;
     out: string;
     maxBytes: number;
@@ -55,6 +56,7 @@ function selectorFrom(f: McpFlags): GameClientOptions {
         pid: f.pid || undefined,
         url: f.url || undefined,
         token: f.token || undefined,
+        endpoint: f.editor ? "editor" : undefined,
         timeoutMs: f.timeout || undefined,
     };
 }
@@ -218,6 +220,7 @@ export async function mcp(argv: string[]): Promise<void> {
         pid: parsed.flags.pid as number,
         url: parsed.flags.url as string,
         token: parsed.flags.token as string,
+        editor: parsed.flags.editor as boolean,
         json: parsed.flags.json as boolean,
         out: parsed.flags.out as string,
         maxBytes: (parsed.flags["max-bytes"] as number) || DEFAULT_MAX_BYTES,
@@ -236,13 +239,14 @@ export async function mcp(argv: string[]): Promise<void> {
 
     switch (action) {
         case "instances": {
-            const insts = listGameInstances({ appId: f.app || undefined });
+            let insts = listGameInstances({ appId: f.app || undefined });
+            if (f.editor) insts = insts.filter((i) => i.editorPort !== undefined);
             if (insts.length === 0) {
                 process.stderr.write("draft-mcp: no running instances\n");
                 return;
             }
             insts.forEach((i) => {
-                print(`${i.pid}\t${i.port}\t${i.appId ?? "-"}`);
+                print(`${i.pid}\t${i.port ?? "-"}\t${i.appId ?? "-"}\t${i.editorPort ?? "-"}`);
             });
             return;
         }

package/src/paths.ts

@@ -28,6 +28,23 @@ function isGameDir(dir: string): boolean {
     || existsSync(join(dir, NATIVE_ENTRY_FILE));
 }
 
+/**
+ * Read a game's `downdraft.config.json` — engine-level settings that apply
+ * regardless of the game's package.json build section. Missing/invalid files
+ * yield `{}` (the file doubles as a game-dir marker, so it may be absent).
+ *
+ *   { "runtime": "bun" | "node" | "deno" }  — default JS runtime for
+ *   `draft dev`/`draft release` (overridden by --runtime / DD_RUNTIME).
+ */
+export function readGameConfig(gameDir: string): Record<string, unknown> {
+  try {
+    const cfg = JSON.parse(readFileSync(join(gameDir, GAME_CONFIG_FILE), "utf8"));
+    return cfg && typeof cfg === "object" ? cfg : {};
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Find the downdraft monorepo root — a directory whose package.json is named
  * "downdraft-engine" and contains packages/engine. Searches cwd ancestry first,

package/src/plugin-command.ts

@@ -1,9 +1,9 @@
 // ============================================================================
-// `dd plugin` — CLI subcommand for plugin management.
+// `draft plugin` — CLI subcommand for plugin management.
 //
 // Usage:
-//   dd plugin new <name> --format <format> --game <game> [options]
-//   dd plugin list [--game <game>]
+//   draft plugin new <name> --format <format> --game <game> [options]
+//   draft plugin list [--game <game>]
 // ============================================================================
 
 import { createLogger } from "@downdraft/engine";
@@ -16,8 +16,8 @@ import { scaffoldPlugin } from "./scaffold-plugin";
 const log = createLogger();
 
 export async function pluginCommand(args: string[]): Promise<void> {
-  // `dd mod new ...` injects --mod flag so scaffoldPlugin generates mod.json.
-  // `dd plugin new ...` defaults to plugin.json (legacy).
+  // `draft mod new ...` injects --mod flag so scaffoldPlugin generates mod.json.
+  // `draft plugin new ...` defaults to plugin.json (legacy).
   let modMode = false;
   if (args[0] === "--mod") {
     modMode = true;
@@ -46,7 +46,7 @@ export async function pluginCommand(args: string[]): Promise<void> {
 }
 
 async function pluginNew(args: string[], modMode: boolean): Promise<void> {
-  // Simple arg parsing: dd plugin new <name> --format <format> --game <game> [--version <ver>] [--author <name>] [--description <desc>] [--target <dir>] [--force] [--mod] [--with <ext>]
+  // Simple arg parsing: draft plugin new <name> --format <format> --game <game> [--version <ver>] [--author <name>] [--description <desc>] [--target <dir>] [--force] [--mod] [--with <ext>]
   const positional: string[] = [];
   const flags: Record<string, string | boolean> = {};
   for (let i = 0; i < args.length; i++) {
@@ -67,7 +67,7 @@ async function pluginNew(args: string[], modMode: boolean): Promise<void> {
 
   const id = positional[0];
   if (!id) {
-    log.error("plugin", `Usage: dd ${modMode ? "mod" : "plugin"} new <name> --format <format> --game <game>`);
+    log.error("plugin", `Usage: draft ${modMode ? "mod" : "plugin"} new <name> --format <format> --game <game>`);
     process.exit(1);
   }
 
@@ -190,11 +190,11 @@ function pluginList(args: string[]): void {
 function printPluginHelp(modMode: boolean): void {
   const cmd = modMode ? "mod" : "plugin";
   print(`
-dd ${cmd} — manage user-authored ${modMode ? "mods" : "plugins"}
+draft ${cmd} — manage user-authored ${modMode ? "mods" : "plugins"}
 
 Usage:
-  dd ${cmd} new <name> --format <format> --game <game> [options]
-  dd ${cmd} list [--game <game>]
+  draft ${cmd} new <name> --format <format> --game <game> [options]
+  draft ${cmd} list [--game <game>]
 
 Commands:
   new     Scaffold a new ${modMode ? "mod" : "plugin"} directory

package/src/release.ts

@@ -30,7 +30,7 @@ import { basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, print, renderHelp } from "./args";
 import { formatGamesList, listGames } from "./list-games";
-import { findGameDirUpward, findMonorepoRoot, resolveGameDir } from "./paths";
+import { findGameDirUpward, findMonorepoRoot, readGameConfig, resolveGameDir } from "./paths";
 import { getCommand } from "./usage";
 
 const log = createLogger();
@@ -228,12 +228,14 @@ function packageNative(
   // when present (engine sources relativize cleanly), else the game dir.
   const cwd = findMonorepoRoot(gameDir) ?? gameDir;
 
-  // Runtime matrix: --runtime flag → build.runtime in package.json → bun.
+  // Runtime matrix: --runtime flag → build.runtime in package.json →
+  // downdraft.config.json "runtime" → bun.
   // "all" expands to the full matrix (one appdir per runtime).
   const RUNTIMES = ["bun", "node", "deno"];
-  const requested = opts.runtime ?? info.build.runtime ?? "bun";
+  const requested = opts.runtime ?? info.build.runtime
+    ?? (readGameConfig(gameDir).runtime as string | undefined) ?? "bun";
   const runtimes = requested === "all" ? RUNTIMES : [requested];
-  for (const r of runtimes) {
+  for (const r of runtimes.values()) {
     if (!RUNTIMES.includes(r)) {
       log.error("release:package", `Unknown runtime "${r}" — expected bun, node, deno, or all.`);
       return false;
@@ -248,7 +250,7 @@ function packageNative(
 
   let ok = true;
   targets.forEach((target) => {
-    for (const runtime of runtimes) {
+    for (const runtime of runtimes.values()) {
       if (target === "linux") {
         // Linux: package-desktop.mjs owns the format matrix (dir, deb,
         // appimage, flatpak). Formats come from --format → build.linux.target
@@ -276,9 +278,11 @@ function packageNative(
         }
         continue;
       }
-      // win/mac: single-binary bun compile via package-native.mjs.
+      // win/mac: single-binary bun compile via package-native.mjs. Each
+      // target gets its own dir so the staged native/ + dd-assets/ trees
+      // don't interleave across platforms.
       if (runtime !== "bun") continue;
-      const outfile = resolve(opts.out, `${game}-${target}`);
+      const outfile = resolve(opts.out, `${game}-${target}`, `${game}-${target}`);
       const argv = [
         scriptNative,
         `--target=${target}`,

package/src/scaffold-plugin.ts

@@ -1,8 +1,8 @@
 // ============================================================================
 // Plugin scaffold — generates a new plugin directory from a template.
 //
-// Usage: `dd plugin new <name> --format <format> --game <game> [options]`
-//        `dd mod new <name> --game <game> [options]`
+// Usage: `draft plugin new <name> --format <format> --game <game> [options]`
+//        `draft mod new <name> --game <game> [options]`
 //
 // Generates:
 //   - mod.json (manifest, when --mod is used) or plugin.json (legacy)

package/src/usage.ts

@@ -47,7 +47,7 @@ export const COMMANDS: CommandEntry[] = [
         { name: "games", type: "string", description: "Comma-separated game names (e.g. sandjongg,to-the-ocean)" },
         { name: "target", alias: "t", type: "string", default: "all", enum: [...RELEASE_TARGETS], description: "Target platform(s): win, linux, mac, android, or all (android can't mix with desktop targets)" },
         { name: "format", type: "string", description: "Package format(s), comma-separated: dir, deb, appimage, flatpak (linux only; default: build.linux.target in package.json, else dir)" },
-        { name: "runtime", type: "string", enum: ["bun", "node", "deno", "all"], description: "JS runtime embedded in the package: bun (compiled binary), node, deno, or all (default: build.runtime in package.json, else bun). node/deno are linux-only today" },
+        { name: "runtime", type: "string", enum: ["bun", "node", "deno", "all"], description: "JS runtime embedded in the package: bun (compiled binary), node, deno, or all (default: build.runtime in package.json, \"runtime\" in downdraft.config.json, else bun). node/deno are linux-only today" },
         { name: "stage", type: "string", default: "release", enum: [...RELEASE_STAGES], description: "Stage: build, package, or release (all compile the native binary)" },
         { name: "mode", type: "string", default: "prod", enum: [...BUILD_MODES], description: "Build mode" },
         { name: "abi", type: "string", default: "arm64-v8a", description: "Android ABI(s): arm64-v8a, x86_64, or all (android target only)" },
@@ -90,10 +90,13 @@ export const COMMANDS: CommandEntry[] = [
       flags: [
         { name: "entry", type: "string", description: "Game entrypoint file (defaults to src/native-entry.ts)" },
         { name: "port", type: "number", description: "MCP HTTP port (default: auto-assign)" },
-        { name: "runtime", type: "string", enum: ["bun", "node", "deno"], description: "JS runtime hosting the dev shell (default: bun → node → deno auto-detect)" },
+        { name: "runtime", type: "string", enum: ["bun", "node", "deno"], description: "JS runtime hosting the dev shell (default: DD_RUNTIME env, \"runtime\" in downdraft.config.json, else bun → node → deno auto-detect)" },
         { name: "watch", type: "boolean", description: "Back-compat no-op — the HMR dev shell always watches" },
         { name: "no-hmr", type: "boolean", description: "Disable HMR — spawn the entry directly (bun run), no dev shell" },
+        { name: "engine-source", type: "boolean", description: "Resolve @downdraft/engine|platform-native from linked TypeScript source (default in the monorepo; enables file-level engine HMR)" },
+        { name: "engine-dist", type: "boolean", description: "Resolve engine packages from their pre-built dist/ tree (default outside the monorepo; externalized = near-zero transform cost, no engine-file HMR)" },
         { name: "native", type: "boolean", description: "Back-compat alias — native is the default runtime" },
+        { name: "native-debug", type: "boolean", description: "Load debug native libraries (built via build-native.mjs --debug) — sets DD_NATIVE_PROFILE=debug for the spawned runtime" },
         { name: "verbose", alias: "v", type: "boolean", description: "Verbose logging" },
       ],
     },
@@ -196,6 +199,7 @@ export const COMMANDS: CommandEntry[] = [
         { name: "pid", type: "number", description: "Select instance by PID" },
         { name: "url", type: "string", description: "Explicit MCP HTTP URL (skips PID-file discovery)" },
         { name: "token", type: "string", description: "Bearer token (auto-read from <pid>.token otherwise)" },
+        { name: "editor", type: "boolean", description: "Target the instance's editor endpoint (<pid>.editor — createMcpModule transport:\"http\") instead of the automation endpoint" },
         { name: "json", type: "boolean", description: "Print the raw result envelope (image data elided to {bytes} unless --out)" },
         { name: "out", type: "string", description: "Write image/binary result blocks to file(s)" },
         { name: "max-bytes", type: "number", description: "Cap printed output in bytes (default 262144)" },

package/templates/_shared/partials/config-json-fields.eta

@@ -1,3 +1,2 @@
   "name": "<%= it.name %>",
-  "version": "<%= it.version %>",
-  "engine": "downdraft"
+  "version": "<%= it.version %>"