create-shallot 0.5.2 → 0.8.0

package/index.ts

@@ -3,21 +3,16 @@
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { dirname, join, resolve } from "path";
 
-export interface TemplateOptions {
-    /**
-     * dependency spec for `@dylanebert/shallot`. `"latest"` for the published `bun create shallot`
-     * scaffold; `"workspace:*"` when `bun run build` regenerates examples/templates/starter in-repo.
-     */
-    shallot?: string;
-}
-
 /**
- * the project files keyed by relative path, with the project name interpolated. single source of
- * truth for both `bun create shallot <name>` and the in-repo examples/templates/starter example
- * (regenerated by `bun run build`).
+ * the project files keyed by relative path, with the project name interpolated. the single source of
+ * truth for `bun create shallot <name>`.
+ *
+ * the project is pure data — a `shallot.json` manifest + plugin modules + `public/`, no vite
+ * boilerplate. the CLI provides every harness over it: `shallot dev` runs it standalone with hot
+ * reload, `shallot build` ships it (web + native targets). the emitted CLAUDE.md / AGENTS.md point an
+ * agent at the installed engine's contract.
  */
-export function template(name: string, opts: TemplateOptions = {}): Record<string, string> {
-    const shallot = opts.shallot ?? "latest";
+export function template(name: string): Record<string, string> {
     return {
         "public/icon.svg": ICON,
         ".gitignore": "node_modules/\ndist/\nbuild/\n",
@@ -28,9 +23,8 @@ export function template(name: string, opts: TemplateOptions = {}): Record<strin
                     version: "0.0.0",
                     private: true,
                     type: "module",
-                    scripts: { dev: "vite", build: "vite build", preview: "vite preview" },
-                    dependencies: { "@dylanebert/shallot": shallot },
-                    devDependencies: { typescript: "^5.9.3", vite: "^8.0.0" },
+                    dependencies: { "@dylanebert/shallot": "latest" },
+                    devDependencies: { typescript: "^7.0.2" },
                 },
                 null,
                 2,
@@ -43,7 +37,7 @@ export function template(name: string, opts: TemplateOptions = {}): Record<strin
                         module: "ESNext",
                         moduleResolution: "bundler",
                         lib: ["ESNext", "DOM", "DOM.Iterable"],
-                        types: ["@webgpu/types", "vite/client"],
+                        types: ["@webgpu/types"],
                         strict: true,
                         noEmit: true,
                         skipLibCheck: true,
@@ -53,29 +47,13 @@ export function template(name: string, opts: TemplateOptions = {}): Record<strin
                 null,
                 2,
             ) + "\n",
-        "index.html": `<!doctype html>
-<html lang="en">
-    <head>
-        <meta charset="UTF-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <link rel="icon" type="image/svg+xml" href="./icon.svg" />
-        <title>${name}</title>
-        <style>
-            * { box-sizing: border-box; margin: 0; padding: 0; }
-            body { background: #0c0a09; overflow: hidden; }
-            canvas { display: block; width: 100vw; height: 100vh; }
-        </style>
-    </head>
-    <body>
-        <canvas id="canvas"></canvas>
-        <script type="module" src="./src/main.ts"></script>
-    </body>
-</html>
-`,
-        "vite.config.ts": VITE,
-        "src/lib.ts": LIB,
-        "src/main.ts": MAIN,
+        "shallot.json": MANIFEST,
+        "src/env.d.ts": ENV,
+        "src/spin.ts": SPIN,
         "public/scenes/scene.scene": SCENE,
+        "README.md": readme(name),
+        "AGENTS.md": agents(name),
+        "CLAUDE.md": agents(name),
     };
 }
 
@@ -108,58 +86,114 @@ const ICON = `<svg id="Shallot" xmlns="http://www.w3.org/2000/svg" viewBox="0 0
 </svg>
 `;
 
-const VITE = `import { defineConfig } from "vite";
+const readme = (name: string) => `# ${name}
 
-export default defineConfig({
-    base: "./",
-    server: { port: 3000 },
-    build: {
-        target: "esnext",
-        outDir: "dist",
-        emptyOutDir: true,
-    },
-});
+A shallot project.
+
+## Develop
+
+\`\`\`bash
+bun install
+bunx shallot dev
+\`\`\`
+
+\`bun install\` fetches the engine. \`bunx shallot dev\` runs the project with hot
+reload. Edit \`src/spin.ts\` (a plugin) and \`shallot.json\` (the manifest: scene +
+plugin enablement) in your IDE.
+
+## Ship
+
+\`\`\`bash
+bunx shallot build
+\`\`\`
+
+Builds a web bundle to \`dist/\`. For native targets:
+\`bunx shallot build --target windows|mac|linux\` (add \`--release\` for an optimized build).
+`;
+
+const agents = (name: string) => `# ${name}
+
+A WebGPU game built on \`@dylanebert/shallot\`.
+
+## Layout
+
+- \`shallot.json\` — the manifest: which scene to open + which plugins to enable
+- \`public/scenes/*.scene\` — the world as declarative XML (each \`<a>\` is an entity, each attribute a component)
+- \`src/*.ts\` — your plugins (a plugin is data: components + systems)
+
+## Build, run, verify
+
+\`\`\`bash
+bunx tsc --noEmit                                # typecheck — run after every change
+bunx shallot dev                                 # run with hot reload while you work
+bunx shallot build [--target windows|mac|linux]  # ship it (web bundle, or a native app)
+bunx shallot verify                              # prove it: boot headless, check it renders, exit 0/nonzero
+\`\`\`
+
+\`shallot verify\` is the verification step — a self-terminating gate that boots the project in a real
+headless browser, waits for a settled frame, and exits nonzero on failure. Nothing left running. \`--json\`
+emits the full result; \`--screenshot <path>\` saves a frame. It drives Playwright, an optional one-time
+install: \`bun add -d playwright && bunx playwright install chromium\` (exit code 3 names this command if
+it's missing). By default it checks the scene rendered; to assert your own pass/fail (entity poses,
+physics state) install \`window.__harness\` via \`installHarness\` from \`@dylanebert/shallot/harness\` — in a
+manifest project like this one, from a plugin's \`initialize(state)\` hook (the engine's AGENTS.md has the
+worked example).
+
+## Engine reference
+
+The engine is the documentation. Read \`node_modules/@dylanebert/shallot/AGENTS.md\` for the full
+contract (ECS, plugins, scenes, GPU, UI, and the \`shallot verify\` harness), and every public export
+carries JSDoc. The examples index lives at \`node_modules/@dylanebert/shallot/examples/AGENTS.md\` — grep
+it for the problem you have, then read that recipe's source, before writing a pattern from scratch.
+
+## Conventions
+
+Data-oriented, ECS, declarative. Add components and systems, not methods — a \`Jump\` marker plus a
+system, never \`player.jump()\`. Scenes declare; code transforms. One source of truth: every value has
+one authoritative home; derive, don't duplicate.
+`;
+
+// The project manifest: `shallot dev` and a shipped `shallot build` both read it. `scene` is the scene
+// to open; `plugins` is enablement — "Orbit": true turns on the orbit camera the scene uses, and
+// "Spin": "./src/spin" declares our own plugin by its module path. The default plugins (render, lit
+// surface) are on unless you set one false.
+const MANIFEST = `{
+  "$schema": "./node_modules/@dylanebert/shallot/shallot.schema.json",
+  "scene": "scenes/scene.scene",
+  "plugins": {
+    "Orbit": true,
+    "Spin": "./src/spin"
+  }
+}
 `;
 
-const LIB = `import { type Config, Part, quat, type State, type System, Transform } from "@dylanebert/shallot";
+// Ambient types + the tsconfig anchor. `include: ["src"]` needs at least one matching file, so this
+// keeps `bunx tsc --noEmit` green (no TS18003) even when spin.ts is deleted for a static scene. It's
+// infrastructure, not demo content — don't delete it.
+const ENV = `/// <reference types="@webgpu/types" />
+`;
+
+const SPIN = `import { type Plugin, type State, type System, Part, quat, Transform } from "@dylanebert/shallot";
 
-// A system is plain data: an \`update\` the engine runs each frame. This one spins
-// every Part around Y. It runs in the standalone app but not the editor — \`shallot .\`
-// builds in edit mode, where unannotated systems are skipped, so the cube stays put
-// and editable there. Delete it (and the plugin entry below) for a static scene.
-let angle = 0;
+// A plugin is plain data: components + systems the engine runs. This system spins every Part around Y.
+// It runs in the "simulation" group, which plays when the project runs. Delete this file (and its
+// \`shallot.json\` entry) for a static scene.
 const SpinSystem: System = {
     group: "simulation",
     update(state: State) {
-        angle = (angle + state.time.deltaTime * 45) % 360;
-        const q = quat(0, angle, 0);
+        // Derive the angle from elapsed time, not a module-level accumulator, so it stays
+        // correct after a hot reload or State rebuild rather than carrying stale rotation.
+        const q = quat(0, (state.time.elapsed * 45) % 360, 0);
         for (const eid of state.query([Part, Transform])) {
             Transform.rot.set(eid, q.x, q.y, q.z, q.w);
         }
     },
 };
 
-// The project definition, shared by the standalone app (src/main.ts) and the shallot
-// editor (\`shallot .\`). The default plugins (render, lit surface, orbit camera) stay
-// on; the spin plugin adds our one system. The scene lives here too, so main.ts stays
-// untouched as the project grows.
-export const config: Config = {
-    plugins: [{ name: "spin", systems: [SpinSystem] }],
-    scene: "scenes/scene.scene",
-};
-`;
-
-const MAIN = `import { run } from "@dylanebert/shallot";
-import { config } from "./lib";
-
-// One config source (src/lib.ts) drives both this standalone build and the editor. The camera
-// auto-binds to the page's <canvas>.
-const { dispose } = await run(config);
-
-// HMR re-runs this module — dispose the old State + RAF loop or each reload stacks another.
-if (import.meta.hot) {
-    import.meta.hot.dispose(() => dispose());
-}
+// The default export is the plugin — \`shallot.json\` references this file by path and imports
+// its default. The name ("Spin") is how the manifest lists it.
+const SpinPlugin: Plugin = { name: "Spin", systems: [SpinSystem] };
+export default SpinPlugin;
 `;
 
 const SCENE = `<scene>
@@ -175,7 +209,8 @@ const SCENE = `<scene>
 `;
 
 if (import.meta.main) {
-    const name = process.argv[2];
+    const args = process.argv.slice(2);
+    const name = args.find((a) => !a.startsWith("--"));
     if (!name) {
         console.error("Usage: bun create shallot <project-name>");
         process.exit(1);
@@ -194,5 +229,5 @@ if (import.meta.main) {
     console.log("Next steps:");
     console.log(`  cd ${name}`);
     console.log("  bun install");
-    console.log("  bun dev");
+    console.log("  bunx shallot dev");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-shallot",
-    "version": "0.5.2",
+    "version": "0.8.0",
     "type": "module",
     "bin": "./index.ts",
     "files": ["index.ts"],