dotframe 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.6
+
+From the Craft Ones native port.
+
+- Native: mouse buttons read 0 while the window lacks input focus, so clicks in other apps no longer reach the game. The pointer position stays global, so aiming is unchanged.
+- Templates: `src/setup.ts` reads the pointer and touches with a hold-to-charge, release-to-act pattern (a charge meter while holding, a tone on release), on web and native. Each `game.ts` declares the `POINTER_BIT` a release sets.
+- Skills: the macos guide gains "Porting existing TypeScript" (what scriptc rejects and the fix for each, plus runtime traps such as structural coercion copying and out-of-range reads) and "Debugging a native crash" with lldb. Netplay warns against checksums built on `JSON.stringify`.
+
+## 0.1.5
+
+- Native builds follow the entry's import graph instead of copying the game folder: relative imports that leave the game root and workspace packages that resolve to source are staged with their relative layout and rewritten to relative paths, so ports inside monorepos compile.
+
 ## 0.1.4
 
 Fixes from rounds 2 and 3 of the Craft Ones dogfood.

package/cli/native.ts

@@ -1,6 +1,6 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { CliError, type Ctx, exec, home, print, type RunResult, which } from "./lib";
 
 // The engine this CLI belongs to: a git checkout or node_modules/dotframe.
@@ -44,42 +44,104 @@ export function vendorFix(platform: NativePlatform): string {
   return `dotframe vendor ${platform}`;
 }
 
-const SKIP = new Set(["node_modules", ".git", ".dotframe", "dist", "build", ".vercel"]);
-
-function copyTs(from: string, to: string): number {
-  let n = 0;
-  for (const name of readdirSync(from)) {
-    if (SKIP.has(name)) continue;
-    const src = join(from, name);
-    if (statSync(src).isDirectory()) n += copyTs(src, join(to, name));
-    else if (name.endsWith(".ts") || name.endsWith(".json")) {
-      mkdirSync(to, { recursive: true });
-      cpSync(src, join(to, name));
-      n += 1;
+const SPECIFIER = /(?:from\s+|import\s*\(\s*|import\s+)(["'])([^"']+)\1/g;
+const EXTENSIONS = ["", ".ts", ".tsx", ".json", "/index.ts", "/index.tsx"];
+
+function resolveFile(base: string): string | null {
+  const candidates = [base.replace(/\.js$/, ".ts"), base];
+  for (const c of candidates) for (const ext of EXTENSIONS) if (existsSync(c + ext) && statSync(c + ext).isFile()) return realpathSync(c + ext);
+  return null;
+}
+
+// A bare specifier that resolves, through node_modules, to TypeScript source outside node_modules: a workspace
+// package (bun and npm link those). Published packages stay packages.
+function resolveWorkspace(specifier: string, fromDir: string): string | null {
+  const parts = specifier.split("/");
+  const name = specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+  const sub = parts.slice(name.split("/").length).join("/");
+  for (let dir = fromDir; ; dir = dirname(dir)) {
+    const pkgDir = join(dir, "node_modules", name);
+    if (existsSync(pkgDir)) {
+      const real = realpathSync(pkgDir);
+      if (real.split(sep).includes("node_modules")) return null;
+      if (sub) return resolveFile(join(real, sub));
+      const pkg = JSON.parse(readFileSync(join(real, "package.json"), "utf8")) as Record<string, unknown>;
+      const exp = pkg.exports as Record<string, unknown> | string | undefined;
+      const dot = typeof exp === "string" ? exp : (exp?.["."] as Record<string, string> | string | undefined);
+      const entry = typeof dot === "string" ? dot : (dot?.import ?? dot?.default ?? dot?.types ?? (pkg.module as string) ?? (pkg.main as string) ?? "index.ts");
+      return resolveFile(join(real, entry));
     }
+    if (dirname(dir) === dir) return null;
   }
-  return n;
 }
 
-// scriptc's static build takes relative imports only, and treats anything under node_modules as package code
-// for its dynamic engine. Staging copies the engine and the game side by side and rewrites "dotframe/..."
-// imports to relative paths.
-function rewriteImports(dir: string, engineRoot: string): void {
-  for (const name of readdirSync(dir)) {
-    const path = join(dir, name);
-    if (statSync(path).isDirectory()) {
-      rewriteImports(path, engineRoot);
-      continue;
+interface Graph {
+  files: string[];
+  // Per file, the specifiers to rewrite and the absolute file each one points at.
+  links: Map<string, Map<string, string>>;
+}
+
+// Every source file the entry reaches: relative imports (including ones that leave the game root) and workspace
+// packages. "dotframe/..." is the engine, staged separately.
+function importGraph(entry: string): Graph {
+  const files: string[] = [];
+  const links = new Map<string, Map<string, string>>();
+  const queue = [realpathSync(entry)];
+  const seen = new Set(queue);
+  while (queue.length > 0) {
+    const file = queue.shift() as string;
+    files.push(file);
+    if (!/\.tsx?$/.test(file)) continue;
+    const map = new Map<string, string>();
+    for (const m of readFileSync(file, "utf8").matchAll(SPECIFIER)) {
+      const spec = m[2];
+      if (spec.startsWith("dotframe/") || spec.startsWith("node:")) continue;
+      const target = spec.startsWith(".") ? resolveFile(resolve(dirname(file), spec)) : resolveWorkspace(spec, dirname(file));
+      if (!target) continue;
+      if (!spec.startsWith(".")) map.set(spec, target);
+      if (!seen.has(target)) {
+        seen.add(target);
+        queue.push(target);
+      }
+    }
+    links.set(file, map);
+  }
+  return { files, links };
+}
+
+function commonDir(paths: string[]): string {
+  let base = dirname(paths[0]);
+  for (const p of paths) while (!(p + sep).startsWith(base === sep ? sep : base + sep)) base = dirname(base);
+  return base;
+}
+
+function rel(fromFile: string, to: string): string {
+  const r = relative(dirname(fromFile), to);
+  return r.startsWith(".") ? r : `./${r}`;
+}
+
+// scriptc's static build takes relative imports only, and treats anything under node_modules as package code for
+// its dynamic engine. Staging copies the engine and every reached game file side by side, keeping their relative
+// layout, and rewrites "dotframe/..." and workspace imports to relative paths.
+function stageGame(root: string, entry: string, tree: string, engineStage: string): string {
+  const graph = importGraph(join(root, entry));
+  const base = commonDir([realpathSync(root) + sep + "x", ...graph.files]);
+  const staged = (file: string): string => join(tree, relative(base, file));
+  for (const file of graph.files) {
+    const to = staged(file);
+    mkdirSync(dirname(to), { recursive: true });
+    let text = readFileSync(file, "utf8");
+    if (/\.tsx?$/.test(file)) {
+      const map = graph.links.get(file) ?? new Map<string, string>();
+      text = text.replace(SPECIFIER, (whole: string, q: string, spec: string): string => {
+        if (spec.startsWith("dotframe/")) return whole.replace(`${q}${spec}${q}`, `${q}${rel(to, join(engineStage, spec.slice("dotframe/".length)))}${q}`);
+        const target = map.get(spec);
+        return target ? whole.replace(`${q}${spec}${q}`, `${q}${rel(to, staged(target)).replace(/\.tsx?$/, "")}${q}`) : whole;
+      });
     }
-    if (!name.endsWith(".ts")) continue;
-    const text = readFileSync(path, "utf8");
-    const next = text.replace(/(from\s+|import\s*\(\s*)(["'])dotframe\/([^"']+)\2/g, (_m: string, head: string, q: string, rest: string): string => {
-      let rel = relative(dirname(path), join(engineRoot, rest));
-      if (!rel.startsWith(".")) rel = `./${rel}`;
-      return `${head}${q}${rel}${q}`;
-    });
-    if (next !== text) writeFileSync(path, next);
+    writeFileSync(to, text);
   }
+  return join(tree, relative(base, realpathSync(root)));
 }
 
 export async function buildNative(ctx: Ctx, root: string, gameName: string, targetName: string, t: NativeTarget): Promise<{ binary: string; log: string; steps: RunResult[] }> {
@@ -95,6 +157,7 @@ export async function buildNative(ctx: Ctx, root: string, gameName: string, targ
   const log = join(logDir, `build-${targetName}.log`);
   const out = join(root, "dist", targetName);
   const binary = join(out, `${t.name ?? gameName}${platform === "windows" ? ".exe" : ""}`);
+  if (!existsSync(join(root, t.entry))) throw new CliError("ENTRY_MISSING", `native entry ${t.entry} does not exist`, `add ${t.entry} (see the macos skill) or fix targets.${targetName}.native.entry`, skill);
   if (ctx.dryRun) {
     print(ctx, { dryRun: true, platform, stage, vendor: vendor.dir, binary }, (): string => `would stage the engine and game in ${stage} and build ${binary}`);
     return { binary, log, steps: [] };
@@ -104,9 +167,7 @@ export async function buildNative(ctx: Ctx, root: string, gameName: string, targ
   mkdirSync(out, { recursive: true });
   const engineStage = join(stage, "dotframe");
   cpSync(join(ENGINE, "src"), join(engineStage, "src"), { recursive: true });
-  const gameStage = join(stage, "game");
-  copyTs(root, gameStage);
-  rewriteImports(gameStage, engineStage);
+  const gameStage = stageGame(root, t.entry, join(stage, "game"), engineStage);
 
   const inc = [`-I${join(vendor.dir, vendor.sdl ?? "", "include")}`, `-I${join(vendor.dir, "wgpu", platform, "include")}`];
   const lib = join(stage, "lib");
@@ -120,8 +181,6 @@ export async function buildNative(ctx: Ctx, root: string, gameName: string, targ
   const ffi = JSON.parse(readFileSync(join(ENGINE, "native", `ffi.${platform}.json`), "utf8")) as { libraries: string[] };
   ffi.libraries = [join(lib, "libdf_native.a"), join(vendor.dir, "build", `sdl-${platform}`, "libSDL3.a"), join(vendor.dir, "wgpu", platform, "lib", "libwgpu_native.a")];
   writeFileSync(join(stage, "ffi.json"), JSON.stringify(ffi, null, 2));
-  const entry = join(gameStage, t.entry);
-  if (!existsSync(entry)) throw new CliError("ENTRY_MISSING", `native entry ${t.entry} does not exist`, `add ${t.entry} (see the macos skill) or fix targets.${targetName}.native.entry`, skill);
   let env: Record<string, string> = {};
   if (platform === "windows") {
     // A devDependency of dotframe, so an npm install of dotframe does not bring it; the game can.

package/native/df_native.c

@@ -227,6 +227,8 @@ static void mouse_relative(double *nx, double *ny) {
 // Field 0 x, 1 y (normalized), 2 buttons (bit 0 left, bit 1 middle, bit 2 right).
 double df_mouse(int32_t field) {
   if (field == 2) {
+    // Clicks in other apps must not reach the game: buttons count only while the window has input focus.
+    if (!(SDL_GetWindowFlags(g_window) & SDL_WINDOW_INPUT_FOCUS)) return 0;
     SDL_MouseButtonFlags flags = SDL_GetGlobalMouseState(NULL, NULL);
     return (flags & SDL_BUTTON_LMASK ? 1 : 0) | (flags & SDL_BUTTON_MMASK ? 2 : 0) | (flags & SDL_BUTTON_RMASK ? 4 : 0);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotframe",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "TS-first game engine and agent-first CLI: one codebase for web, Discord, iOS and native binaries",
   "license": "MIT",
   "type": "module",

package/skill-data/macos/SKILL.md

@@ -20,7 +20,7 @@ A target with `"native"` is built by the CLI itself:
 "windows": { "native": { "platform": "windows", "entry": "main.native.ts" } }
 ```
 
-The CLI copies the engine (`src/`) and the game's `.ts` and `.json` files into `.dotframe/native/<target>/`, rewrites `dotframe/...` imports to relative paths, compiles the C shim against the vendored SDL3 and wgpu-native, and runs scriptc. This is why it works from `node_modules`: scriptc treats code under `node_modules` as package code for its dynamic engine and takes only relative imports in a static build, so building in place fails.
+The CLI copies the engine (`src/`) and every file the entry reaches into `.dotframe/native/<target>/`: relative imports (including ones that leave the game folder, as in a monorepo port importing `../../packages/shared/src`) and workspace packages that resolve to source (`@my/shared` linked by bun or npm workspaces). It keeps their relative layout, rewrites `dotframe/...` and workspace imports to relative paths, compiles the C shim against the vendored SDL3 and wgpu-native, and runs scriptc. This is why it works from `node_modules`: scriptc treats code under `node_modules` as package code for its dynamic engine and takes only relative imports in a static build, so building in place fails.
 
 - Vendor lives in `DOTFRAME_VENDOR`, else a dotframe git checkout's `vendor/` when populated, else `~/.dotframe/vendor`. It survives reinstalling dotframe and is shared by every game.
 - Output goes to the game's `dist/<target>/`, never into `node_modules`.
@@ -39,6 +39,33 @@ scriptc compiles a subset of TypeScript. What tripped the templates:
 
 Run `dotframe build macos` early and after each feature: one scriptc error is a quick fix, ninety are a port.
 
+## Porting existing TypeScript
+
+What a real port (Craft Ones, 66 errors) hit, and the fix for each:
+
+| scriptc rejects | Do instead |
+|---|---|
+| `Object.assign(target, ...)` | Assign fields one by one |
+| `ArrayLike<T>` / `Iterable<T>` parameters | Take `T[]` |
+| `readonly T[]`, `.find`/`.filter` on readonly tuples, `for...of` over tuples | Plain arrays (`T[]`), indexed loops |
+| Destructuring an `unknown` network payload | Narrow field by field with `typeof` checks |
+| Non-literal index into a tuple | Make it an array |
+| Dynamic keyed reads on a record whose entries have different shapes | Give every entry the same shape (optional fields), or a `switch` |
+| `string[i]` | `s.charAt(i)` or `s.charCodeAt(i)` |
+| `Number.parseInt` in a static build | `parseInt` or `Math.trunc(Number(s))` |
+| `++`/`--` inside an expression | Its own statement |
+| `satisfies Record<K, Record<string, T>>` | A plain type annotation |
+
+Runtime traps (compile clean, fail when run):
+
+- **Structural coercion copies.** Passing a class instance, or a wider record, to a parameter typed as a narrower structural type passes a copy: the callee's writes to scalar fields are lost (arrays inside still alias). In Craft Ones every projectile froze mid-flight. Pass the exact type, or return the updated record and copy it back. Reported to scriptc.
+- **Out-of-range reads.** `rows[y - 1]?.[x]` typed as `string` but `undefined` at runtime crashes with "undefined is not representable in the target union". Bounds-check before reading.
+- **`JSON.stringify` key order** differed from JavaScript in Craft Ones (not reproduced in a minimal case). Never build checksums or netplay comparisons from it.
+
+## Debugging a native crash
+
+`--optimization dev` builds failed to link in Craft Ones (undefined `_main`; a template game links fine). When that happens, debug the release binary with lldb: `lldb ./dist/macos/<name>`, `breakpoint set -n scr_error_new`, `run`, then `bt` shows the TypeScript call site of a runtime error.
+
 ## Other notes
 
 - Benchmarks mean nothing while other processes load the machine. Check `top` first and say what else was running.

package/skill-data/netplay/SKILL.md

@@ -30,6 +30,8 @@ Run several seeds and a high latency (474 ms is what a transatlantic relay measu
 
 ## Rules
 
+- Build checksums from numbers in a fixed order, never from `JSON.stringify`: native builds can order keys differently from JavaScript, so a web peer and a native peer would report false desyncs.
+
 - The camera, effects, and HUD timers are simulation state if the simulation ever reads them. Update them once per step, never per drawn frame.
 - Render must restore any random state it uses, or use a separate visual generator.
 - Input delay (`--delay`, default 2) trades latency for fewer rollbacks.

package/templates/_base/src/setup.ts

@@ -1,27 +1,49 @@
-// Shared by main.web.ts and main.native.ts: fixed 60 Hz steps from the keyboard, then one render per frame.
+// Shared by main.web.ts and main.native.ts: keyboard and pointer to inputs, fixed 60 Hz steps, one render per frame.
 import { createDraw2D } from "dotframe/src/draw2d";
 import type { Frame, Setup } from "dotframe/src/gpu";
-import { Key } from "dotframe/src/input";
+import { Key, MouseButton } from "dotframe/src/input";
 import type { Platform } from "dotframe/src/platform";
-import { createGame, keyInput, PLAYERS, render, step, WINDOW } from "./game";
+import { createGame, keyInput, PLAYERS, POINTER_BIT, render, step, WINDOW } from "./game";
 
 const STEP = 1 / 60;
+// A full charge takes one second of holding.
+const FULL_CHARGE = 60;
 
 export function createSetup(): Setup {
-  return ({ gpu, input }: Platform): Frame => {
+  return ({ gpu, input, audio }: Platform): Frame => {
     const draw = createDraw2D(gpu, WINDOW.width, WINDOW.height);
     const game = createGame(Math.floor(Math.random() * 1e9));
     let simulated = -1;
+    // Hold to charge, release to act: the pattern most mouse and touch games need.
+    let charge = 0;
+    let wasDown = false;
     return (time: number): boolean => {
       if (simulated < 0) simulated = time;
-      // Fixed steps, so every target plays exactly what dotframe sim simulates.
       for (let n = 0; simulated + STEP <= time && n < 5; n++) {
+        const pointer = input.pointer();
+        const inside = pointer.x >= 0 && pointer.x <= 1 && pointer.y >= 0 && pointer.y <= 1;
+        const down = inside && ((pointer.buttons & MouseButton.Left) !== 0 || input.touches().length > 0);
+        let released = false;
+        if (down) charge = Math.min(FULL_CHARGE, charge + 1);
+        else if (wasDown) {
+          released = true;
+          // Audio is presentation, never simulation state: the pitch says how charged the release was.
+          audio.tone(220 + (charge / FULL_CHARGE) * 660, 0.12, 0.25);
+          charge = 0;
+        }
+        wasDown = down;
         const keys = [keyInput(input, [Key.A, Key.D, Key.W, Key.J]), keyInput(input, [Key.Left, Key.Right, Key.Up, Key.L])];
+        if (released) keys[0] = keys[0] | POINTER_BIT;
         step(game, keys.slice(0, PLAYERS));
         simulated += STEP;
       }
       draw.begin();
       render(game, draw);
+      if (charge > 0) {
+        // Charge meter under the play area.
+        draw.setFillStyle("#ffffff");
+        draw.fillRect(20, WINDOW.height - 16, (WINDOW.width - 40) * (charge / FULL_CHARGE), 6);
+      }
       draw.end({ r: 0, g: 0, b: 0 });
       return true;
     };

package/templates/blank/game.ts

@@ -4,6 +4,8 @@ import type { Draw2D } from "dotframe/src/draw2d";
 import type { Input } from "dotframe/src/input";
 
 export const WINDOW = { width: 960, height: 540, title: "__NAME__" };
+// The input bit a released mouse or touch press sets for player 1 (fires the action bit); see src/setup.ts.
+export const POINTER_BIT = 8;
 export const PLAYERS = 2;
 
 export interface Game {

package/templates/fighter/game.ts

@@ -11,6 +11,8 @@ const RIGHT = 2;
 const JUMP = 4;
 const ATTACK = 8;
 const GROUND = 440;
+// The input bit a released mouse or touch press sets for player 1 (attacks); see src/setup.ts.
+export const POINTER_BIT = ATTACK;
 const GRAVITY = 0.8;
 const SPEED = 5;
 const JUMP_SPEED = 15;

package/templates/platformer/game.ts

@@ -9,6 +9,8 @@ export const PLAYERS = 1;
 const LEFT = 1;
 const RIGHT = 2;
 const JUMP = 4;
+// The input bit a released mouse or touch press sets for player 1 (jumps); see src/setup.ts.
+export const POINTER_BIT = JUMP;
 const GRAVITY = 0.7;
 const SPEED = 4.5;
 const JUMP_SPEED = 13;