@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/init.js

@@ -1,57 +1,676 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.slugify = slugify;
+exports.sdkDependencySpec = sdkDependencySpec;
 exports.initTemplate = initTemplate;
+exports.initTemplateWithTerrain = initTemplateWithTerrain;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-// Minimal no-build starter: plain Three.js from a CDN import map, no bundler.
-// The SDK-integrated Vite templates (template-spinning-scene, template-hangout)
-// are the real starting points; this exists so `helix init` works standalone.
-const TEMPLATE_FILES = {
-    'helix.json': (slug) => JSON.stringify({
-        helixVersion: '0.1',
-        title: 'My HELIX World',
-        slug,
+const config_1 = require("./config");
+const compiler_1 = require("./sceneElements/compiler");
+const types_1 = require("./sceneImport/types");
+// Pinned ranges for a freshly scaffolded world. engine-core is pinned by DEFAULT (not left to an
+// upgrade pass) because every engine-core tool needs BOTH halves — the pin AND a matching in-world
+// call — and a world scaffolded without them cannot be measured or captured at all until someone
+// retrofits both. main.ts below makes both calls: world.ready() for `helix world inspect` /
+// inspect_world / world_metrics, and screenshots.register() + screenshots.ready() for `helix
+// screenshot` / capture_world_screenshot.
+//
+// >= 0.1.2 is what the screenshot `hide` option needs (added in 0.1.1); do not loosen it.
+const SYSTEM_PINS = {
+    'humanoid-character': '^0.3',
+    'engine-core': '^0.1.2',
+};
+// A scene world's environment IS the streamed Scene v2 document, so it pins the two systems that
+// realize it — and main.ts below calls both (the pin-without-its-call trap above).
+//
+// >= 0.1.9 is the first @helix/visual carrying the GI contributor lane `attachSceneVisuals` drives
+// (0.1.8 is the maintainers' fidelity-contract release, without it). @helix/scene 0.3 is the line with
+// Scene HLOD, activation volumes and distant trees; the 0.2 line keeps serving worlds that pinned it.
+const SCENE_SYSTEM_PINS = {
+    scene: '^0.3',
+    visual: '^0.1.9',
+};
+/** The starter document's folder under public/scene/ — `?scene=<folder>` picks between documents. */
+const SCENE_FOLDER = 'mall';
+// The starter terrain: 4 x 4 tiles at 1 m per sample (256 m each), generated from a FIXED seed so two scaffolds of the same
+// preset produce byte-identical ground, and read back by the compiler from the folder beside the document.
+const TERRAIN_FOLDER = 'terrain';
+const STARTER_TERRAIN_TILES = 4;
+const STARTER_TERRAIN_SEED = 4242;
+// The starter scene, compiled OFFLINE at scaffold time. This is a copy of the CLI's own
+// examples/minimal-mall.elements.json: `examples/` is not in package.json `files`, so it does not
+// reach the published package and cannot be read from disk at scaffold time.
+const MALL_ELEMENTS = `{
+  "format": "helix.scene-elements",
+  "version": 1,
+  "id": "scene.example.mall",
+  "title": "Minimal Mall",
+  "spawn": { "position": [0, 1.9, 4], "rotationYDeg": 180 },
+  "buildings": [
+    {
+      "id": "building.mall",
+      "type": "building",
+      "elements": [
+        {
+          "id": "floor.ground",
+          "type": "floor",
+          "center": [0, 0],
+          "elevation": -0.1,
+          "size": [20, 12],
+          "thickness": 0.2
+        },
+        {
+          "id": "wall.north",
+          "type": "wall",
+          "start": [-10, -6],
+          "end": [10, -6],
+          "height": 4,
+          "thickness": 0.25
+        },
+        {
+          "id": "ceiling.main",
+          "type": "ceiling",
+          "center": [0, 0],
+          "elevation": 4,
+          "size": [20, 12],
+          "thickness": 0.2
+        }
+      ]
+    }
+  ]
+}
+`;
+/** The mall, and — when the scaffold generated one — the terrain it stands on. */
+function starterElements(terrain) {
+    const elements = JSON.parse(MALL_ELEMENTS);
+    if (!terrain)
+        return elements;
+    elements.terrain = { type: 'terrain', id: 'ground', source: terrain.source };
+    elements.buildings[0].position = [0, terrain.groundY, 0];
+    elements.spawn.position = [0, terrain.groundY + 1.9, 4];
+    return elements;
+}
+// Compiling here (rather than shipping a pre-sealed document) keeps the pin and the bytes provably
+// the same object: `revision` and `integrity.sha256` come off the document the scaffold just wrote.
+function compileStarterScene(terrain) {
+    const scene = (0, compiler_1.compileSceneElements)(starterElements(terrain?.terrain ?? null), terrain ? { baseDir: terrain.baseDir } : {});
+    return {
+        document: (0, types_1.serializeSceneDocument)(scene),
+        pin: {
+            kind: 'scene-v2',
+            id: scene.id,
+            revision: scene.revision,
+            integrity: { sha256: scene.integrity.sha256 },
+        },
+    };
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50)
+        .padEnd(3, '0');
+}
+function manifest(opts, scenePin) {
+    // A scene world is a multiplayer world whose environment is streamed rather than built in code.
+    const multiplayer = opts.kind === 'multiplayer' || opts.kind === 'scene';
+    const base = {
+        // v0.3 adds the multiplayer block + the reserved voice.* permissions; a single-player character
+        // world stays on v0.2. Both carry `systems`, which is what `helix install` resolves.
+        helixVersion: multiplayer ? '0.3' : '0.2',
+        title: opts.title,
+        slug: opts.slug,
         entry: 'index.html',
-        maxPlayers: 1,
-        permissions: [],
+        maxPlayers: multiplayer ? opts.maxPlayers : 1,
+        permissions: multiplayer
+            ? ['auth.profile', 'multiplayer', 'voice.proximity']
+            : ['auth.profile'],
         supportsMobile: true,
         contentRating: 'everyone',
-    }, null, 2) + '\n',
-    'index.html': () => `<!doctype html>
+        systems: {
+            ...SYSTEM_PINS,
+            ...(opts.kind === 'scene' ? SCENE_SYSTEM_PINS : {}),
+        },
+        ...(multiplayer
+            ? {
+                multiplayer: {
+                    // Proximity voice is ON by default in every multiplayer world — remove this block AND
+                    // the fail-soft join in main.ts only for a deliberately silent world.
+                    voice: { mode: 'proximity' },
+                },
+            }
+            : {}),
+        // The environment a published scene world streams. `integrity.sha256` is the AUTHORITATIVE
+        // address (documents are content-addressed); id/revision are advisory display text.
+        ...(scenePin ? { scene: scenePin } : {}),
+    };
+    return `${JSON.stringify(base, null, 2)}\n`;
+}
+function sdkDependencySpec(scope = config_1.HELIX_SCOPE) {
+    return scope === '@hypersoniclabs'
+        ? '^0.1.0'
+        : `npm:${scope}/helix-sdk@latest`;
+}
+function packageJson(slug) {
+    return `${JSON.stringify({
+        name: slug,
+        version: '0.1.0',
+        private: true,
+        type: 'module',
+        scripts: {
+            dev: 'vite',
+            build: 'vite build',
+            preview: 'vite preview',
+            typecheck: 'tsc --noEmit',
+        },
+        dependencies: {
+            // Keep source imports stable while resolving the SDK from the same
+            // environment scope as this CLI build. A helix3 scaffold that silently
+            // installs the production SDK starts stale and contradicts doctor/MCP.
+            '@hypersoniclabs/helix-sdk': sdkDependencySpec(),
+        },
+        devDependencies: {
+            // Rapier is a devDependency like three: the build externalizes it and the browser resolves
+            // the bare specifier through the import map, while types + `helix dev` use the local copy.
+            '@dimforge/rapier3d-compat': '^0.14.0',
+            '@types/three': '^0.185.4',
+            three: '^0.185.1',
+            typescript: '~5.7.3',
+            vite: '^6.0.0',
+        },
+    }, null, 2)}\n`;
+}
+const VITE_CONFIG = `import { defineConfig } from 'vite';
+import { fileURLToPath } from 'node:url';
+
+// base: './' is REQUIRED. A published world is served from a nested path
+// (…/instant-worlds/<id>/<build>/), never the origin root, so root-absolute asset URLs 404 in
+// production while working perfectly in local preview. A relative base is what makes one build work
+// at both. \`helix verify-subpath dist\` proves it.
+//
+// \`three\`, \`@dimforge/rapier3d-compat\`, and platform-owned \`@helix/*\` systems stay EXTERNAL:
+// the browser resolves the bare specifiers
+// through the import map in index.html (written by \`helix install\`) to the platform-hosted single
+// instances, so the world, the platform system, and the runtime abilities all share ONE of each —
+// and the ~2 MB Rapier module is downloaded once per player, not baked into every world bundle.
+//
+// Test locally with \`npm run build\` + \`npm run preview\` — NOT the dev server, which rewrites bare
+// imports and hides whether the import map is correct.
+export default defineConfig({
+  base: './',
+  resolve: {
+    alias: {
+      // \`helix install\` materializes the resolved systems here. Every engine-core SUBPATH alias must
+      // come BEFORE the root '@helix/engine-core' entry — rollup substitutes by prefix in object
+      // order, and a root alias listed first mangles a subpath import into an ENOENT.
+      '@helix/engine-core/inspect': fileURLToPath(new URL('./public/helix_modules/engine-core/inspect/index.js', import.meta.url)),
+      '@helix/engine-core/screenshot': fileURLToPath(new URL('./public/helix_modules/engine-core/screenshot/index.js', import.meta.url)),
+      '@helix/engine-core/world-camera': fileURLToPath(new URL('./public/helix_modules/engine-core/world-camera/index.js', import.meta.url)),
+      '@helix/engine-core': fileURLToPath(new URL('./public/helix_modules/engine-core/index.js', import.meta.url)),
+      '@helix/humanoid-character': fileURLToPath(new URL('./public/helix_modules/humanoid-character/index.js', import.meta.url)),
+      // Scene-world systems. An alias is inert until something imports it, so these are harmless in a
+      // world that pins neither — the subpath-before-root rule above applies to '@helix/scene' too.
+      '@helix/scene/visual': fileURLToPath(new URL('./public/helix_modules/scene/visual/index.js', import.meta.url)),
+      '@helix/scene': fileURLToPath(new URL('./public/helix_modules/scene/index.js', import.meta.url)),
+      '@helix/visual': fileURLToPath(new URL('./public/helix_modules/visual/index.js', import.meta.url)),
+    },
+  },
+  build: {
+    target: 'es2022',
+    rollupOptions: { external: (id) => id === 'three' || id === '@dimforge/rapier3d-compat' || id.startsWith('@helix/') },
+  },
+});
+`;
+const TSCONFIG = `${JSON.stringify({
+    compilerOptions: {
+        target: 'ES2022',
+        module: 'ESNext',
+        moduleResolution: 'bundler',
+        lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        resolveJsonModule: true,
+        isolatedModules: true,
+        types: ['vite/client'],
+        paths: {
+            '@helix/humanoid-character': [
+                './public/helix_modules/humanoid-character/index.d.ts',
+            ],
+            // One entry per engine-core subpath the world can import, plus the root. TypeScript matches
+            // `paths` by longest pattern rather than object order, so ordering is cosmetic here — but it
+            // mirrors vite.config.ts, where the order IS load-bearing.
+            '@helix/engine-core/inspect': [
+                './public/helix_modules/engine-core/inspect/index.d.ts',
+            ],
+            '@helix/engine-core/screenshot': [
+                './public/helix_modules/engine-core/screenshot/index.d.ts',
+            ],
+            '@helix/engine-core/world-camera': [
+                './public/helix_modules/engine-core/world-camera/index.d.ts',
+            ],
+            '@helix/engine-core': [
+                './public/helix_modules/engine-core/index.d.ts',
+            ],
+            '@helix/scene/visual': [
+                './public/helix_modules/scene/visual/index.d.ts',
+            ],
+            '@helix/scene': [
+                './public/helix_modules/scene/index.d.ts',
+            ],
+            '@helix/visual': [
+                './public/helix_modules/visual/index.d.ts',
+            ],
+        },
+    },
+    include: ['src'],
+}, null, 2)}\n`;
+const GITIGNORE = `node_modules/
+dist/
+# Resolved system/ability CODE — re-created by \`helix install\` from helix.lock.json.
+public/helix_modules/
+`;
+// Durable, machine-readable proof for the mobile audit. The generated HUD also exposes the same
+// contract marker in the live DOM; this file survives bundling so validation does not guess from a
+// fragile source regex. A custom implementation may replace provider with "custom" while keeping
+// the required capabilities honest and proving them in touch QA.
+const MOBILE_CONTROLS_CONTRACT = `${JSON.stringify({
+    version: 1,
+    provider: '@helix/humanoid-character',
+    capabilities: ['move', 'look', 'zoom', 'jump'],
+}, null, 2)}\n`;
+// How a scene world is LIT — the per-world visual contract `helix validate` audits and `helix
+// bake-lighting` patches. sceneVisualsConfig() overlays what the scene itself declares (its authored
+// sun, probe box, exposure band) on top of this before the runtime parses it.
+const VISUALS_CONFIG = `${JSON.stringify({
+    version: 1,
+    mode: 'dynamic',
+    timeOfDay: {
+        hours: 10,
+        cycleSeconds: 0,
+        latitudeDeg: 10,
+        declinationDeg: 0,
+        noonAzimuthDeg: 130,
+    },
+}, null, 2)}\n`;
+// Read at the BUNDLE root: vite copies public/ verbatim into dist/, which is what `helix publish`
+// uploads, so this file is what makes the local documents dev-only rather than merely intended.
+const HELIXIGNORE = `# gitignore-style, read at the bundle root. A published world resolves its scene from the pin in helix.json, so
+# the documents under scene/ are a DEV OVERRIDE that must never ride into the bundle vite copies into dist/.
+scene/
+terrain/
+`;
+// GENERATED by `helix install`; emitted as placeholders so `npm run typecheck` and an editor both
+// work in a freshly scaffolded project, before install has ever run.
+const RUNTIME_STUB = `// GENERATED by \`helix install\` — do not hand-edit. These are placeholders until you run install,
+// which fills them from the resolved system: the hosted three version, its module URL + KTX2
+// transcoder path on the platform CDN, and the system's CDN asset base (from helix.lock.json).
+export const THREE_VERSION = '';
+export const THREE_MODULE_URL = '';
+export const TRANSCODER_PATH = '/runtime/basis/';
+export const SYSTEM_ASSET_BASE = '';
+`;
+const escapeHtml = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+function indexHtml(title) {
+    const escaped = escapeHtml(title);
+    return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>My HELIX World</title>
-    <style>html, body { margin: 0; height: 100%; overflow: hidden; background: #0a0a12; }</style>
+    <title>${escaped}</title>
+    <!-- data: favicon stops the browser's automatic /favicon.ico probe — that request escapes the
+         bundle's sub-path and 404s at the CDN in production for every published world. -->
+    <link rel="icon" href="data:," />
+    <!-- helix:three:start -->
+    <!-- \`helix install\` writes the import map here, pointing the bare \`three\` specifier at the
+         platform-hosted single instance. Until you run install it stays empty (the build won't load). -->
     <script type="importmap">
-      { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.172.0/build/three.module.js" } }
+    { "imports": { "three": "" } }
     </script>
+    <!-- helix:three:end -->
+    <style>
+      html, body { margin: 0; height: 100%; overflow: hidden; background: #14161a; }
+      #hud {
+        position: fixed; top: 12px; left: 12px; z-index: 10;
+        font: 12px/1.5 ui-monospace, monospace; color: #cdd6e0; white-space: pre;
+        background: rgba(20, 22, 26, 0.7); border: 1px solid #39424e;
+        border-radius: 6px; padding: 8px 10px;
+      }
+      #controls-hint {
+        position: fixed; left: 50%; bottom: 28px; z-index: 10; transform: translateX(-50%);
+        max-width: min(560px, calc(100vw - 32px)); padding: 10px 14px; border-radius: 999px;
+        color: #eef4fb; background: rgba(20, 22, 26, 0.72); border: 1px solid rgba(205, 214, 224, 0.28);
+        box-shadow: 0 10px 30px rgba(0, 0, 0, 0.22); backdrop-filter: blur(14px);
+        font: 500 13px/1.4 system-ui, sans-serif; text-align: center; pointer-events: none;
+        opacity: 1; transition: opacity 0.35s ease, transform 0.35s ease;
+      }
+      #controls-hint.hidden { opacity: 0; transform: translate(-50%, 6px); }
+      /* Loading overlay — painted on HTML parse (before any JS downloads → no flash). */
+      #loading {
+        position: fixed; inset: 0; z-index: 100; display: flex; align-items: center; justify-content: center;
+        background: #14161a; color: #cdd6e0; font: 13px/1.5 ui-monospace, monospace;
+        opacity: 1; transition: opacity 0.4s ease;
+      }
+      html[data-helix-hosted-loading] #loading { display: none; }
+      #loading.done { opacity: 0; pointer-events: none; }
+      #loading .card { width: min(360px, 76vw); text-align: center; }
+      #loading .eyebrow { font-size: 11px; letter-spacing: 0.18em; text-transform: uppercase; color: #6cc7ff; opacity: 0.75; }
+      #loading .title { margin: 6px 0 18px; font-size: 16px; font-weight: 600; color: #e6edf5; }
+      #loading .bar { height: 6px; border-radius: 3px; background: #232830; overflow: hidden; }
+      #loading #bar { width: 30%; height: 100%; border-radius: 3px; background: #6cc7ff; animation: helix-marquee 1.1s ease-in-out infinite; }
+      #loading.determinate #bar { animation: none; transition: width 0.25s ease; }
+      #loading.working #bar { animation: helix-pulse 1s ease-in-out infinite; }
+      #loading.error #bar { animation: none; width: 100% !important; background: #e5675e; }
+      #loading-text { margin-top: 12px; color: #9aa7b4; }
+      @keyframes helix-marquee { 0% { transform: translateX(-110%); } 100% { transform: translateX(370%); } }
+      @keyframes helix-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }
+    </style>
   </head>
   <body>
-    <script type="module" src="main.js"></script>
+    <script>
+      // The host owns the overlay only when it explicitly asks and this is an iframe.
+      if (window.parent !== window && new URLSearchParams(location.search).get('helixHostedLoading') === '1') {
+        document.documentElement.setAttribute('data-helix-hosted-loading', '');
+      }
+    </script>
+    <div id="loading">
+      <div class="card">
+        <div class="eyebrow">HELIX Instant</div>
+        <div class="title">${escaped}</div>
+        <div class="bar"><div id="bar"></div></div>
+        <div id="loading-text">Starting…</div>
+      </div>
+    </div>
+    <div id="hud">Loading…</div>
+    <div id="controls-hint" aria-live="polite"></div>
+    <script type="module" src="/src/main.ts"></script>
   </body>
 </html>
-`,
-    'main.js': () => `import * as THREE from 'three';
+`;
+}
+const LOADING_TS = `// Standalone owns the HTML overlay; the hosted shell owns it with ?helixHostedLoading=1.
+// Readiness means the first rendered frame, not the SDK handshake or an asset manager batch.
+import * as THREE from 'three';
+
+export type LoadingScreen = {
+  /** Register an extra async unit of work so it counts on the bar. Returns its completion callback. */
+  task: (label?: string) => () => void;
+  done: () => void;
+  error: (message: string) => void;
+};
+
+export function createLoadingScreen(): LoadingScreen {
+  const root = document.getElementById('loading');
+  const bar = document.getElementById('bar');
+  const text = document.getElementById('loading-text');
+  const hosted = window.parent !== window && new URLSearchParams(location.search).get('helixHostedLoading') === '1';
+  let parentOrigin = '*';
+  try {
+    const origin = new URL(document.referrer).origin;
+    if (origin !== 'null') parentOrigin = origin;
+  } catch { /* An opaque or absent referrer has no target origin; the shell validates our frame. */ }
+  let extraTotal = 0;
+  let extraDone = 0;
+  let assetsTotal = 0;
+  let assetsDone = 0;
+  let fraction = 0;
+  const progress = () => {
+    const total = assetsTotal + extraTotal;
+    if (total > 0) fraction = Math.max(fraction, Math.min(1, (assetsDone + extraDone) / total));
+    return { loaded: fraction * total, total };
+  };
+  let state: 'loading' | 'ready' | 'error' = 'loading';
+  let label = 'Starting…';
+  const manager = THREE.DefaultLoadingManager;
+  const previousProgress = manager.onProgress;
+
+  const report = (error?: string) => {
+    if (!hosted) return;
+    const { total } = progress();
+    window.parent.postMessage({
+      type: 'helix:loading', state, label: label.slice(0, 160),
+      ...(total > 0 ? { loaded: fraction, total: 1 } : {}),
+      ...(error !== undefined ? { error: error.slice(0, 2000) } : {}),
+    }, parentOrigin);
+  };
+  const render = () => {
+    if (state !== 'loading') return;
+    const { total } = progress();
+    if (text) text.textContent = label;
+    if (root && bar && total > 0) {
+      root.classList.add('determinate');
+      bar.style.width = \`\${Math.min(100, Math.round(fraction * 100))}%\`;
+    }
+    report();
+  };
+  const fail = (message: string) => {
+    if (state !== 'loading') return;
+    const details = message || 'World startup failed';
+    state = 'error';
+    label = details;
+    root?.classList.add('error');
+    if (text) text.textContent = details;
+    report(details);
+  };
+  const onProgress: NonNullable<typeof manager.onProgress> = (url, loaded, total) => {
+    assetsDone = loaded;
+    assetsTotal = total;
+    label = 'Loading assets…';
+    render();
+    previousProgress?.call(manager, url, loaded, total);
+  };
+  manager.onProgress = onProgress;
+  // Claim the loading lifecycle synchronously, before Helix.init() sends its handshake.
+  report();
+
+  return {
+    task(taskLabel) {
+      if (state !== 'loading') return () => {};
+      extraTotal += 1;
+      if (taskLabel) label = taskLabel;
+      render();
+      let settled = false;
+      return () => {
+        if (settled || state !== 'loading') return;
+        settled = true;
+        extraDone += 1;
+        render();
+      };
+    },
+    done() {
+      if (state !== 'loading') return;
+      state = 'ready';
+      label = 'Ready';
+      if (text) text.textContent = label;
+      if (manager.onProgress === onProgress) manager.onProgress = previousProgress;
+      if (hosted) root?.remove();
+      else {
+        root?.classList.remove('working');
+        root?.classList.add('done');
+        setTimeout(() => root?.remove(), 500);
+      }
+      report();
+    },
+    error: fail,
+  };
+}
+
+// New facades expose honest initial equipped presentation readiness; older pinned facades
+// have already assembled their compatible body by create(). Never wait on swap events.
+export async function waitForInitialAvatar(character: unknown, loading: LoadingScreen, deadlineMs = 45_000): Promise<void> {
+  const facade = character as { initialAvatarReady?: PromiseLike<{ status: string }> };
+  if (!facade.initialAvatarReady || typeof facade.initialAvatarReady.then !== 'function') {
+    const finish = loading.task('Using compatible avatar…');
+    console.info('[HELIX] This character module uses its assembled compatible avatar; equipped-avatar readiness is unavailable.');
+    finish();
+    return;
+  }
+  const finish = loading.task('Loading your avatar…');
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const result = await Promise.race([
+      facade.initialAvatarReady,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => reject(new Error('Your avatar did not finish loading. Try again.')), deadlineMs);
+      }),
+    ]);
+    if (!result || typeof result !== 'object') throw new Error('Your avatar reported an invalid readiness state. Try again.');
+    if (result.status === 'failed' || result.status === 'disposed') throw new Error('Your avatar could not be prepared. Try again.');
+    if (result.status !== 'ready' && result.status !== 'fallback') throw new Error('Your avatar reported an invalid readiness state. Try again.');
+    if (result.status === 'fallback') {
+      loading.task('Using compatible avatar…')();
+      console.info('[HELIX] The character module recovered a usable fallback avatar.');
+    }
+    finish();
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}
+`;
+// The one line this scaffold is most careful about:
+//
+//   new URL('helix_modules/', document.baseURI).href
+//
+// NOT '/helix_modules'. A published world is served from …/instant-worlds/<id>/<build>/, so a
+// root-absolute path 404s and loadInstalledAbilities THROWS — the world renders nothing but an error
+// bar. Every local gate passes anyway, because they all serve dist/ from a root. `helix
+// verify-subpath` (which `helix publish` runs) is the check that catches it.
+function mainTs(kind, title) {
+    const multiplayer = kind === 'multiplayer';
+    return `import * as THREE from 'three';
+import { Helix } from '@hypersoniclabs/helix-sdk';
+import {
+  CharacterMultiplayer,
+  InputService,
+  RapierBody,
+  createMobileControls,
+  loadInstalledAbilities,
+} from '@helix/humanoid-character';
+import { world } from '@helix/engine-core/inspect';
+import { screenshots } from '@helix/engine-core/screenshot';
+import { SYSTEM_ASSET_BASE, TRANSCODER_PATH } from './helix.runtime';
+import { createLoadingScreen, waitForInitialAvatar } from './loading';
+
+// ${title} — a HELIX Instant ${multiplayer ? 'multiplayer' : 'character'} world.
+//
+// Flow: RapierBody.create builds the world physics → CharacterMultiplayer.create assembles the platform
+// character, universal avatar, camera and emote wheel → loadInstalledAbilities loads whatever
+// \`helix install\` resolved (fly, swim, …). join:false keeps a character world solo without removing
+// its platform-owned avatar/emote/input features.
+//
+// Test with \`npm run build\` + \`npm run preview\`, NOT the dev server: dev rewrites bare imports and
+// hides whether the import map is correct.
+
+const SPAWN = { x: 0, y: 0.2, z: 0 };
+
+// The world's cover shot. A placeholder pose framing the spawn area — ADJUST position/lookAt/fov to
+// frame whatever you actually build, then rebuild so the shot is stable for everyone. Registering is
+// a no-op during normal play; it only activates under ?helixScreenshot=1, which \`helix screenshot\`
+// and capture_world_screenshot pass. Add \`warmupMs\` if your scene needs physics to settle first.
+screenshots.register('hero', { position: [12, 8, -20], lookAt: [0, 2, 0], fov: 55 });
+
+const hud = document.getElementById('hud')!;
+const controlsHint = document.getElementById('controls-hint')!;
+const loading = createLoadingScreen();
 
 const scene = new THREE.Scene();
-const camera = new THREE.PerspectiveCamera(70, innerWidth / innerHeight, 0.1, 100);
-camera.position.z = 3;
+scene.background = new THREE.Color(0x14161a);
+const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, 0.05, 200);
+
+/**
+ * Procedural sky/ground gradient used as the scene ENVIRONMENT (HYPR-5290).
+ * PBR materials need an environment to reflect: without one, metals and glossy
+ * surfaces render flat black no matter how many lights the scene has. A tiny
+ * equirect gradient gives them real ambient reflections with zero assets and no
+ * three/examples import (which would bundle a second copy of three next to the
+ * platform-hosted one). Keep an environment set; retint per the world's mood.
+ */
+function createGradientEnvironment(sky: THREE.Color, horizon: THREE.Color, ground: THREE.Color): THREE.DataTexture {
+  // 64x32 (2:1 equirect). Keep real dimensions: a few-pixel-wide texture renders
+  // BLACK — the renderer's cube-UV conversion cannot sample it (measured).
+  const width = 64, height = 32;
+  const data = new Uint8Array(width * height * 4);
+  const c = new THREE.Color();
+  for (let y = 0; y < height; y++) {
+    // Row 0 is the BOTTOM of an equirect map (ground), row height-1 the zenith.
+    const t = y / (height - 1);
+    if (t < 0.5) c.lerpColors(ground, horizon, t * 2);
+    else c.lerpColors(horizon, sky, (t - 0.5) * 2);
+    for (let x = 0; x < width; x++) {
+      const i = (y * width + x) * 4;
+      data[i] = Math.round(c.r * 255);
+      data[i + 1] = Math.round(c.g * 255);
+      data[i + 2] = Math.round(c.b * 255);
+      data[i + 3] = 255;
+    }
+  }
+  const texture = new THREE.DataTexture(data, width, height);
+  texture.mapping = THREE.EquirectangularReflectionMapping;
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.magFilter = THREE.LinearFilter;
+  texture.minFilter = THREE.LinearFilter;
+  texture.needsUpdate = true;
+  return texture;
+}
+// Matches the hemisphere light below so ambience and reflections agree.
+scene.environment = createGradientEnvironment(
+  new THREE.Color(0x9ecbff),
+  new THREE.Color(0xe8ddc8),
+  new THREE.Color(0x40382a),
+);
 
 const renderer = new THREE.WebGLRenderer({ antialias: true });
 renderer.setSize(innerWidth, innerHeight);
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+renderer.outputColorSpace = THREE.SRGBColorSpace;
+renderer.toneMapping = THREE.ACESFilmicToneMapping;
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
 document.body.appendChild(renderer.domElement);
 
-const cube = new THREE.Mesh(
-  new THREE.BoxGeometry(),
-  new THREE.MeshStandardMaterial({ color: 0x7c4dff }),
-);
-scene.add(cube);
-scene.add(new THREE.AmbientLight(0xffffff, 0.4));
-const light = new THREE.DirectionalLight(0xffffff, 1.2);
-light.position.set(2, 3, 4);
-scene.add(light);
+scene.add(new THREE.HemisphereLight(0xbfd4ff, 0x40382a, 0.9));
+const sun = new THREE.DirectionalLight(0xffffff, 2.2);
+sun.position.set(6, 12, 4);
+sun.castShadow = true;
+sun.shadow.mapSize.set(1024, 1024);
+sun.shadow.normalBias = 0.02;
+scene.add(sun);
 
 addEventListener('resize', () => {
   camera.aspect = innerWidth / innerHeight;
@@ -59,29 +678,478 @@ addEventListener('resize', () => {
   renderer.setSize(innerWidth, innerHeight);
 });
 
-renderer.setAnimationLoop(() => {
-  cube.rotation.x += 0.01;
-  cube.rotation.y += 0.013;
-  renderer.render(scene, camera);
+async function main(): Promise<void> {
+  const finishStartup = loading.task('Preparing world…');
+  // RapierBody.create is a static async factory — the constructor is private.
+  const body = await RapierBody.create({ position: SPAWN });
+  body.addStaticCuboid({ x: 24, y: 0.5, z: 24 }, { x: 0, y: -0.5, z: 0 }); // floor, top at y=0
+
+  const floor = new THREE.Mesh(
+    new THREE.BoxGeometry(48, 1, 48),
+    new THREE.MeshStandardMaterial({ color: 0x2a3138, roughness: 0.95 }),
+  );
+  floor.position.y = -0.5;
+  floor.receiveShadow = true;
+  scene.add(floor);
+  scene.add(new THREE.GridHelper(48, 48, 0x39424e, 0x232830));
+
+  // ONE world-owned InputService, injected into the character. Register every game key on this
+  // router — never a raw addEventListener — so bindings stay device-correct (keyboard/pad/touch),
+  // rebindable, and inert while a menu context is pushed. Never bind the platform-reserved keys
+  // (Escape = the tablet, KeyB = voice push-to-talk, backtick = the debug overlay).
+  const input = new InputService();
+  // An injected InputService is world-owned, so the world also owns its desktop DOM wiring.
+  // This preserves keyboard, mouse drag/pointer-lock, wheel, and gamepad alongside touch.
+  input.attach(window as never);
+  input.attachPointer(renderer.domElement as never, document as never, { dragLook: true });
+
+  // Tunables live in the system's published CONFIG, not the TS class API — read them via
+  // get_package_manifest("humanoid-character") or the character-world recipe. Never guess keys.
+  const character = await CharacterMultiplayer.create({
+    helix: Helix,
+    renderer,
+    scene,
+    camera,
+    body,
+    input,
+    domElement: renderer.domElement,
+    assetBase: SYSTEM_ASSET_BASE,
+    transcoderPath: TRANSCODER_PATH,
+    spawn: SPAWN,
+    // Platform features stay individually overridable: pass emotes:false, emoteWheel:false,
+    // universalAvatars:false or localControl:false when the world needs it. Keep helix.json systems as ranges
+    // (^0.3): never pin an exact engine version to get a fix — promote the fix instead.
+    join: ${multiplayer ? 'true' : 'false'},
+    character: {
+      character: {
+        spawn: SPAWN,
+        camera: { mode: 'third-person', lookSensitivity: 1.2 },
+      },
+      locomotion: { runSpeed: 5.5 },
+    },
+  });
+
+  // Keep rendering while the initial equipped avatar settles, and reveal only a frame
+  // rendered after readiness. The public Promise includes native fallback recovery.
+  let avatarBootReady = false;
+  void waitForInitialAvatar(character, loading).then(() => { avatarBootReady = true; }).catch((error: unknown) => {
+    loading.error(error instanceof Error ? error.message : String(error));
+  });
+
+  // CharacterMultiplayer registers the platform actions (including \`emote\`) on the injected
+  // InputService. Format binding-aware onboarding only after those actions exist.
+  const desktopHint = (captured: boolean): string => {
+    const cameraHint = captured
+      ? 'Move mouse to look · Scroll to zoom'
+      : 'Click world to control camera';
+    return input.hasAction('emote')
+      ? input.format(\`\${cameraHint} · Hold {emote} for emote wheel\`)
+      : cameraHint;
+  };
+  controlsHint.textContent = desktopHint(false);
+  renderer.domElement.addEventListener('click', () => {
+    controlsHint.textContent = desktopHint(true);
+    setTimeout(() => controlsHint.classList.add('hidden'), 4500);
+  }, { once: true });
+
+  // Everything \`helix install\` resolved. Resolve the modules base against document.baseURI so it
+  // works at the origin root (local preview) AND at the nested path a published world is served
+  // from — a root-absolute '/helix_modules' 404s in production and throws.
+  const modulesBase = new URL('helix_modules/', document.baseURI).href;
+  const installed = await loadInstalledAbilities(modulesBase, character.local);
+  if (installed.length) {
+    console.info(\`abilities installed: \${installed.map((a) => a.manifest.id).join(', ')}\`);
+  }
+
+  // Default mobile controls are a platform system, not per-world UI. They render from the actions
+  // registered above (including installed abilities), drive this SAME InputService, and remain
+  // fully replaceable/configurable. Use actions: [{ id, label, order, placement, visible }] for
+  // safe text/layout overrides; register a custom action with touch: 'button' or 'hold' to add it.
+  const mobileControls = createMobileControls(input, {
+    surface: renderer.domElement,
+    // The host can reserve space above the world without reaching across the iframe boundary.
+    platformTopOffset: 0,
+  });
+
+  // Player-facing control text NEVER hardcodes key names — format() expands {action} tokens to the
+  // CURRENT binding for the active device, so it stays correct across pad/keyboard and rebinds.
+  const clock = new THREE.Clock();
+  let firstFrame = true;
+  renderer.setAnimationLoop(() => {
+    const dt = Math.min(clock.getDelta(), 0.1);
+    mobileControls.update(); // before character.update(): delivers this frame's pinch/context state
+    character.update(dt);
+    if (body.position.y < -10) character.local.respawn(); // fell off the world
+    renderer.render(scene, camera);
+    if (firstFrame && avatarBootReady) {
+      firstFrame = false;
+      finishStartup();
+      loading.done();
+    }
+    hud.textContent = mobileControls.active
+      ? 'Drag to look · Pinch to zoom'
+      : input.format(\`{move} move · {jump} jump · {sprint} sprint · Click + move mouse to look · Scroll zoom\${input.hasAction('emote') ? ' · Hold {emote} for emote wheel' : ''}\`);
+    if (mobileControls.active) controlsHint.classList.add('hidden');
+  });
+
+  // Measurement hook for \`helix world inspect\` / inspect_world. A cheap no-op during normal play —
+  // it only activates under ?helixInspect=1. Call it at the END of boot, once the scene is built.
+  world.ready({ scene, body, spawn: SPAWN });
+
+  // The other half of the screenshot integration — the pin alone is NOT enough, so this ships wired.
+  // Both halves are required: \`helix screenshot\` / capture_world_screenshot wait on
+  // window.__helixScreenshots.ready and time out after 60s without this call. It must run at the END
+  // of boot, once the scene is built — a capture drives THIS renderer/scene/camera, applying the
+  // registered pose for one frame and restoring it after; no separate camera is created.
+  //
+  // \`hide\` blanks the local body for the whole screenshot session: headless captures run logged out,
+  // so the player renders as the bare default mannequin — rarely what you want in a cover shot. Drop
+  // it if you deliberately want the character in frame. Until you build something, that leaves the
+  // hero shot as bare floor + grid: the capture is working, the scene is just still empty.
+  screenshots.ready({ renderer, scene, camera, hide: [character.local.model] });
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(err);
+  loading.error(message);
+  hud.textContent = \`ERROR: \${message}\\nDid you run \\\`helix install\\\`?\`;
+});
+`;
+}
+// The scene kind's boot. It diverges from mainTs() in one load-bearing way — the environment is a
+// sealed Scene v2 document, so it is READ BEFORE the renderer exists (the header below says why).
+function sceneMainTs(title) {
+    return `import * as THREE from 'three';
+import { Helix } from '@hypersoniclabs/helix-sdk';
+import {
+  CharacterMultiplayer,
+  InputService,
+  RapierBody,
+  createMobileControls,
+  loadInstalledAbilities,
+} from '@helix/humanoid-character';
+import { createVisualRuntime, type VisualRuntime } from '@helix/visual';
+import {
+  createHttpSceneApi,
+  createSceneLoaders,
+  createSceneWorld,
+  loadSceneDocument,
+  type EnvironmentPin,
+} from '@helix/scene';
+import { attachSceneVisuals, sceneVisualsConfig } from '@helix/scene/visual';
+import { world } from '@helix/engine-core/inspect';
+import { screenshots } from '@helix/engine-core/screenshot';
+import { SYSTEM_ASSET_BASE, TRANSCODER_PATH } from './helix.runtime';
+import { createLoadingScreen, waitForInitialAvatar } from './loading';
+
+// ${title} — a HELIX Instant SCENE world. Its ENVIRONMENT is a published HELIX Scene v2 document
+// streamed by @helix/scene and lit by @helix/visual's runtime: geometry, materials, authored lights,
+// spawn and collision all come from the scene. No floor, no props, no hand-placed lights live here.
+//
+// BOOT ORDER IS AN INVARIANT. The document is read FIRST because the scene's own lighting shapes the
+// runtime's config: \`sceneVisualsConfig\` folds its authored sun, probe box and exposure band into
+// helix.visuals.json before \`createVisualRuntime\` parses it. The runtime comes next: it OWNS the
+// renderer (the scene loaders need it for KTX2 detection) and bakes its first probe field over a
+// still-empty room; the scene's geometry reaches that field a debounce later, through the contributor
+// lane \`attachSceneVisuals\` opens. \`loaded\` is handed back to \`createSceneWorld\` so the document
+// is fetched and verified once, not twice.
+//
+// Test with \`npm run build\` + \`npm run preview\`, NOT the dev server: dev rewrites bare imports and
+// hides whether the import map is correct.
+
+// Where the body starts until the scene's own spawn is known; the character is created with the real one.
+const PLACEHOLDER_SPAWN = { x: 0, y: 1, z: 0 };
+
+// \`?quality=low\` overrides the tier the runtime would pick itself; anything unrecognized means \`auto\`.
+const QUALITY_LEVELS = ['minimal', 'low', 'medium', 'high', 'ultra', 'auto'] as const;
+const QUALITY_PARAM = new URLSearchParams(location.search).get('quality');
+const QUALITY = QUALITY_LEVELS.find((level) => level === QUALITY_PARAM) ?? 'auto';
+
+// The backend the scene resolves its pin and its Vault surfaces through. Inside HELIX the shell
+// announces it on \`helix:init\`, which is why Helix.init() runs before the document is fetched;
+// \`?api=\` is the standalone-dev override (the local dev-stack serves it on :5000).
+function apiBaseUrl(): string {
+  const override = new URLSearchParams(location.search).get('api');
+  return override ?? Helix.multiplayer.resolveApiBase(null) ?? 'http://localhost:5000';
+}
+
+// How this world is LIT lives in public/helix.visuals.json — the per-world visual contract \`helix
+// validate\` audits and \`helix bake-lighting\` patches. Fetched raw; the runtime's parser owns validation.
+async function loadVisualsConfig(): Promise<unknown> {
+  const response = await fetch(new URL('helix.visuals.json', document.baseURI));
+  if (!response.ok) throw new Error(\`helix.visuals.json failed to load — HTTP \${response.status}\`);
+  return response.json();
+}
+
+// One folder per document under public/scene/ — \`?scene=<folder>\` picks between them. DEV ONLY: a
+// published world names the same identity in helix.json and the runtime resolves it content-addressed.
+async function loadScenePin(): Promise<{ name: string; pin: EnvironmentPin }> {
+  const name = new URLSearchParams(location.search).get('scene') ?? '${SCENE_FOLDER}';
+  const response = await fetch(new URL(\`scene/\${name}/pin.json\`, document.baseURI));
+  if (!response.ok) throw new Error(\`scene/\${name}/pin.json failed to load — HTTP \${response.status}\`);
+  const pin = (await response.json()) as EnvironmentPin;
+  // A document's OWN url is the bundle base every \`bundle\` resource resolves against, so the
+  // per-folder layout is what keeps each document's web/*.glb beside it — never a shared scene/ root.
+  if (pin.kind === 'scene-v2') pin.documentUrl = new URL(\`scene/\${name}/scene.helix-scene.json\`, document.baseURI).href;
+  return { name, pin };
+}
+
+const hud = document.getElementById('hud')!;
+const controlsHint = document.getElementById('controls-hint')!;
+const loading = createLoadingScreen();
+
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, 0.05, 200);
+
+// The runtime owns the renderer (and the sky, the sun, the shadow rig and the post stack) — the world
+// only supplies the canvas it draws into.
+const canvas = document.createElement('canvas');
+canvas.style.cssText = 'position:fixed;inset:0;display:block;width:100%;height:100%';
+document.body.appendChild(canvas);
+
+let visuals: VisualRuntime | null = null;
+
+addEventListener('resize', () => {
+  camera.aspect = innerWidth / innerHeight;
+  camera.updateProjectionMatrix();
+  visuals?.setSize({ width: innerWidth, height: innerHeight });
 });
-`,
-};
-function initTemplate(targetDir) {
-    if ((0, node_fs_1.existsSync)(targetDir))
-        throw new Error(`directory already exists: ${targetDir}`);
-    const slug = (0, node_path_1.basename)(targetDir)
-        .toLowerCase()
-        .replace(/[^a-z0-9-]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .slice(0, 50)
-        .padEnd(3, '0');
+
+async function main(): Promise<void> {
+  const finishStartup = loading.task('Preparing world…');
+  // Before the document: the shell's \`helix:init\` is where the platform API base comes from.
+  await Helix.init();
+
+  // The physics body exists before the scene so the scene's colliders register through it (the one
+  // sanctioned static path: RapierBody mirrors statics into the shared and ragdoll worlds).
+  const body = await RapierBody.create({ position: PLACEHOLDER_SPAWN });
+
+  const api = createHttpSceneApi({ apiBaseUrl: apiBaseUrl() });
+  const { name, pin } = await loadScenePin();
+  const loaded = await loadSceneDocument({ api, pin });
+  const config = await sceneVisualsConfig(loaded, await loadVisualsConfig(), { api });
+
+  visuals = await createVisualRuntime({
+    canvas,
+    scene,
+    camera,
+    config,
+    quality: QUALITY,
+    size: { width: innerWidth, height: innerHeight },
+  });
+  const renderer = visuals.renderer;
+
+  const sceneWorld = await createSceneWorld({
+    renderer,
+    scene,
+    camera,
+    api,
+    loaders: createSceneLoaders(renderer, { transcoderPath: TRANSCODER_PATH }),
+    pin,
+    loaded,
+    colliders: body,
+    // The runtime's sun and probe field ARE the light here: realizing the document's own directional
+    // sun and its legacy ambient/hemisphere fills on top would double every lit surface.
+    lighting: { realizeAuthoredSun: false, realizeLegacyFills: false },
+    viewportHeightPx: () => innerHeight,
+    onError: (error) => console.warn('[scene]', error),
+  });
+  // The scene root becomes one GI contributor and every activated node is adopted (materials, shadow
+  // policy); the probe field picks the streamed geometry up one debounce later.
+  const sceneVisuals = attachSceneVisuals(sceneWorld, visuals);
+
+  const spawn = sceneWorld.spawn?.position ?? PLACEHOLDER_SPAWN;
+  body.teleport(spawn);
+  console.info(\`[scene] \${name} · \${sceneWorld.loaded.scene.id}@\${sceneWorld.loaded.scene.revision}\`
+    + \` · spawn \${spawn.x.toFixed(1)},\${spawn.y.toFixed(1)},\${spawn.z.toFixed(1)}\`
+    + \` · colliders \${sceneWorld.colliders()} · adopted \${sceneVisuals.stats().adopted}\`);
+
+  // ONE world-owned InputService, injected into the character. Register every game key on this
+  // router — never a raw addEventListener — so bindings stay device-correct (keyboard/pad/touch),
+  // rebindable, and inert while a menu context is pushed. Never bind the platform-reserved keys
+  // (Escape = the tablet, KeyB = voice push-to-talk, backtick = the debug overlay).
+  const input = new InputService();
+  input.attach(window as never);
+  input.attachPointer(renderer.domElement as never, document as never, { dragLook: true });
+
+  // Tunables live in the system's published CONFIG, not the TS class API — read them via
+  // get_package_manifest("humanoid-character") or the character-world recipe. Never guess keys.
+  const character = await CharacterMultiplayer.create({
+    helix: Helix,
+    renderer,
+    scene,
+    camera,
+    body,
+    input,
+    domElement: renderer.domElement,
+    assetBase: SYSTEM_ASSET_BASE,
+    transcoderPath: TRANSCODER_PATH,
+    spawn,
+    join: true,
+    character: {
+      character: { spawn, camera: { mode: 'third-person', lookSensitivity: 1.2 } },
+      locomotion: { runSpeed: 5.5 },
+    },
+  });
+
+  // Keep rendering while the initial equipped avatar settles, and reveal only a frame
+  // rendered after readiness. The public Promise includes native fallback recovery.
+  let avatarBootReady = false;
+  void waitForInitialAvatar(character, loading).then(() => { avatarBootReady = true; }).catch((error: unknown) => {
+    loading.error(error instanceof Error ? error.message : String(error));
+  });
+
+  const desktopHint = (captured: boolean): string => {
+    const cameraHint = captured
+      ? 'Move mouse to look · Scroll to zoom'
+      : 'Click world to control camera';
+    return input.hasAction('emote')
+      ? input.format(\`\${cameraHint} · Hold {emote} for emote wheel\`)
+      : cameraHint;
+  };
+  controlsHint.textContent = desktopHint(false);
+  renderer.domElement.addEventListener('click', () => {
+    controlsHint.textContent = desktopHint(true);
+    setTimeout(() => controlsHint.classList.add('hidden'), 4500);
+  }, { once: true });
+
+  // Everything \`helix install\` resolved. Resolve the modules base against document.baseURI so it
+  // works at the origin root (local preview) AND at the nested path a published world is served
+  // from — a root-absolute '/helix_modules' 404s in production and throws.
+  const modulesBase = new URL('helix_modules/', document.baseURI).href;
+  const installed = await loadInstalledAbilities(modulesBase, character.local);
+  if (installed.length) {
+    console.info(\`abilities installed: \${installed.map((a) => a.manifest.id).join(', ')}\`);
+  }
+
+  // Default mobile controls are a platform system, not per-world UI. They render from the actions
+  // registered above (including installed abilities), drive this SAME InputService, and remain
+  // fully replaceable/configurable.
+  const mobileControls = createMobileControls(input, { surface: renderer.domElement, platformTopOffset: 0 });
+
+  // The camera only reached its real pose once the facade placed the player: re-aim everything that lags.
+  visuals.catchUp();
+
+  const clock = new THREE.Clock();
+  let firstFrame = true;
+  renderer.setAnimationLoop(() => {
+    const dt = Math.min(clock.getDelta(), 0.1);
+    mobileControls.update(); // before character.update(): delivers this frame's pinch/context state
+    sceneWorld.tick(dt); // residency on the scene's cadence; colliders follow the resident meshes
+    character.update(dt);
+    if (body.position.y < -10) character.local.respawn(); // fell out of the scene
+    visuals?.tick(dt); // the clock, the sun, the cadences — and the frame's own render
+    if (firstFrame && avatarBootReady) {
+      firstFrame = false;
+      finishStartup();
+      loading.done();
+    }
+    hud.textContent = mobileControls.active
+      ? 'Drag to look · Pinch to zoom'
+      : input.format(\`{move} move · {jump} jump · {sprint} sprint · Click + move mouse to look · Scroll zoom\${input.hasAction('emote') ? ' · Hold {emote} for emote wheel' : ''}\`);
+    if (mobileControls.active) controlsHint.classList.add('hidden');
+  });
+
+  // Measurement hook for \`helix world inspect\` / inspect_world. A cheap no-op during normal play —
+  // it only activates under ?helixInspect=1. Call it at the END of boot, once the scene is built.
+  world.ready({ scene, body, spawn });
+
+  // The world's cover shot, framed off the scene's own spawn. Registering is a no-op during normal
+  // play; it only activates under ?helixScreenshot=1, which \`helix screenshot\` and
+  // capture_world_screenshot pass. The graded frame comes off the runtime's POST STACK, so the
+  // capture must render through \`tick\` — a bare renderer.render would photograph the linear frame.
+  screenshots.register('hero', {
+    position: [spawn.x + 6, spawn.y + 4, spawn.z + 8],
+    lookAt: [spawn.x, spawn.y + 1, spawn.z],
+    fov: 55,
+  });
+  screenshots.ready({
+    renderer: {
+      render: () => visuals?.tick(0),
+      domElement: renderer.domElement,
+      setSize: (width, height) => visuals?.setSize({ width, height }),
+      getPixelRatio: () => renderer.getPixelRatio(),
+      setPixelRatio: (ratio) => renderer.setPixelRatio(ratio),
+    },
+    scene,
+    camera,
+    hide: [character.local.model],
+  });
+}
+
+main().catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(err);
+  loading.error(message);
+  hud.textContent = \`ERROR: \${message}\\nDid you run \\\`helix install\\\`?\`;
+});
+`;
+}
+function initTemplate(targetDir, options = {}) {
+    const kind = options.kind ?? 'character';
+    // Compiled offline, here, so the manifest pin and the bytes under public/scene/ are one object.
+    return writeScaffold(targetDir, options, kind === 'scene' ? compileStarterScene() : null);
+}
+/**
+ * `helix init --kind scene --terrain <preset>`: the same scaffold, over a generated 1 km x 1 km landform.
+ * The mall keeps its authored footprint and is lifted onto the flat plateau the generator leaves at the spawn.
+ */
+async function initTemplateWithTerrain(targetDir, options) {
+    const { bakeTerrainSplats, generateTerrain, loadPreset, tileTerrain, writeTerrainSource } = await Promise.resolve().then(() => __importStar(require('./terrain')));
+    const sceneDir = (0, node_path_1.join)(targetDir, 'public', 'scene', SCENE_FOLDER);
+    const grid = generateTerrain({
+        seed: STARTER_TERRAIN_SEED,
+        tilesX: STARTER_TERRAIN_TILES,
+        tilesZ: STARTER_TERRAIN_TILES,
+        preset: options.terrain,
+    });
+    const baked = await bakeTerrainSplats(tileTerrain(grid), loadPreset(options.terrain), { grid });
+    await writeTerrainSource((0, node_path_1.join)(sceneDir, TERRAIN_FOLDER), baked);
+    const centre = ((grid.samplesZ - 1) / 2) * grid.samplesX + (grid.samplesX - 1) / 2;
+    const groundY = Math.round(grid.heights[centre] * 100) / 100;
+    const starter = compileStarterScene({ baseDir: sceneDir, terrain: { source: TERRAIN_FOLDER, groundY } });
+    const result = writeScaffold(targetDir, { ...options, kind: 'scene' }, starter);
+    result.created.push(`public/scene/${SCENE_FOLDER}/${TERRAIN_FOLDER}/`);
+    return result;
+}
+function writeScaffold(targetDir, options, starter) {
+    const kind = options.kind ?? 'character';
+    const slug = slugify(options.slug ?? (0, node_path_1.basename)(targetDir));
+    const title = options.title ?? 'My HELIX World';
+    const maxPlayers = options.maxPlayers ?? 8;
+    const files = {
+        'package.json': packageJson(slug),
+        'vite.config.ts': VITE_CONFIG,
+        'tsconfig.json': TSCONFIG,
+        '.gitignore': GITIGNORE,
+        'index.html': indexHtml(title),
+        'public/helix.json': manifest({ title, slug, kind, maxPlayers }, starter?.pin),
+        'public/helix.controls.json': MOBILE_CONTROLS_CONTRACT,
+        'src/main.ts': kind === 'scene' ? sceneMainTs(title) : mainTs(kind, title),
+        'src/loading.ts': LOADING_TS,
+        'src/helix.runtime.ts': RUNTIME_STUB,
+        ...(starter
+            ? {
+                'public/helix.visuals.json': VISUALS_CONFIG,
+                'public/.helixignore': HELIXIGNORE,
+                [`public/scene/${SCENE_FOLDER}/scene.helix-scene.json`]: starter.document,
+                [`public/scene/${SCENE_FOLDER}/pin.json`]: `${JSON.stringify(starter.pin, null, 2)}\n`,
+            }
+            : {}),
+    };
     const created = [];
-    for (const [path, render] of Object.entries(TEMPLATE_FILES)) {
+    const skipped = [];
+    for (const [path, contents] of Object.entries(files)) {
         const absolute = (0, node_path_1.join)(targetDir, path);
+        if ((0, node_fs_1.existsSync)(absolute) && !options.overwrite) {
+            skipped.push(path);
+            continue;
+        }
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(absolute), { recursive: true });
-        (0, node_fs_1.writeFileSync)(absolute, render(slug), 'utf8');
+        (0, node_fs_1.writeFileSync)(absolute, contents, 'utf8');
         created.push(path);
     }
-    return created;
+    return { created, skipped };
 }
 //# sourceMappingURL=init.js.map