pelican-engine 0.0.0-stage → 0.3.1

package/docs/npm/DISTRIBUTION.md

@@ -0,0 +1,130 @@
+# Pelican Engine npm development distribution
+
+The installed package is `pelican-engine`. Its root export is the same compiled
+public SDK used by repository games, not a wrapper or a separate SDK. The package
+also provides the `pelican` executable. This is an M3 development distribution,
+not accepted M3 hardware evidence or a complete engine release.
+
+## Windows project workflow
+
+Use Node 24 and npm in an empty project directory. The explicit prefix keeps npm
+in this directory even when a parent directory is also an npm project:
+
+```powershell
+npm --prefix . i -D pelican-engine
+npx pelican dev
+```
+
+The first installed `dev` creates the minimal `game.ts`, `pelican.project.json`
+version lock, and game-author `AGENTS.md` when the directory contains only npm
+installation metadata. An existing game or manifest is used as supplied; other
+project files or author instructions prevent automatic scaffolding. Files are
+never overwritten. Stop dev with Ctrl+C, then use the same local CLI:
+
+```powershell
+npx --no-install pelican api
+npx --no-install pelican setup --install-browser
+npx --no-install pelican check
+npx --no-install pelican dev --port 4173
+npx --no-install pelican capture --port 4174 --output capture.png
+npx --no-install pelican build
+```
+
+For an exact-version install use `npm --prefix . i -D --save-exact pelican-engine@0.3.1`,
+or substitute the local `pelican-engine-0.3.1.tgz` tarball before registry
+publication. `pelican create --template minimal` remains available explicitly.
+
+Without `--prefix .`, npm may select an ancestor `package.json` or `node_modules`
+as the install root and modify that parent. The shorter `npm i -D pelican-engine`
+works when npm selects the intended directory; verify `npm prefix` before using
+it. The smoke harness uses an explicit prefix and does not require `npm init`.
+
+`create --template minimal` uses the same primitive starter in npm and repository
+workflows. npm defaults to `minimal` and reports the selected template; repository
+default `m2` is preserved with its historical sample assets. Samples are not engine
+capabilities. Identical authored game/asset inputs use the same API/compiler/runtime
+in either channel. npm does not bundle the `m2` sample or any sample/game assets.
+
+`create` writes `game.ts`, `AGENTS.md` and an exact `pelican.project.json` lock in the current
+directory. Existing project files are never overwritten. Author TypeScript with
+named imports from `pelican-engine` and project-local imports only. The compiler
+reports `TC_PUBLIC_API` for renderer, Three.js, TSL, physics, Node and internal
+package imports, including type-only and unused imports. Package subpaths are not
+public exports. Project lock mismatches report `TC_ENGINE_VERSION_MISMATCH`;
+mixed package/API versions report `TC_ENGINE_SDK_VERSION`. Reinstall a matching
+exact version, or migrate through the public API before explicitly changing a lock.
+
+After npm dependencies and Playwright Chromium have been installed, authoring,
+API inspection, checks, builds, dev/control commands and capture need no network
+service. `setup --offline` never installs dependencies or downloads a browser in
+an installed package. Keep the game package-lock for repeatable future installs;
+an offline _reinstall_ additionally requires the npm cache or a dependency mirror.
+`TC_DISTRIBUTION_DEPENDENCY_MISSING` and
+`TC_DISTRIBUTION_DEPENDENCY_VERSION` identify broken tool dependencies.
+
+Serve the generated `dist/` directory over HTTP(S), including its `generated/`
+files, license files, notices and compression manifests. No Node process, engine
+repository, SDK installation, external AI service or development control server
+is needed by players. Use `build --base /game/` for a nested deployment URL.
+Capture requires installed Chromium and actual supported graphics capability.
+No software renderer result establishes hardware acceptance.
+
+## AI entry points
+
+Read the game-author `AGENTS.md`, `docs/npm/GAME-AUTHOR.md`, `docs/CAPABILITIES.md` and
+`docs/api/REFERENCE.md` inside `node_modules/pelican-engine`. The machine-readable
+API is `docs/api/index.json`, also discoverable through `pelican api`.
+`lib/sdk/index.d.ts` is the authoritative installed declaration surface.
+`docs/PELICAN-MIGRATION.md` explains current names and historical provenance.
+Repository paths and release instructions in copied documents are historical
+context; the installed workflow above replaces source-checkout commands.
+The JSON CLI protocol and dev control operations are shared with the repository.
+
+## Maintainer validation and publishing
+
+```powershell
+npm run distribution:test
+npm run distribution:pack
+npm run distribution:smoke
+npm run distribution:smoke -- --gpu
+```
+
+Build output is regenerated from current sources into ignored
+`.pelican/npm/package/`; tarballs and smoke reports go in `.pelican/npm/artifacts/`.
+Neither staging nor tarballs are inside the deployable game `dist/`.
+Pack that staging directory, not the private repository root. Compiled relative
+imports use `lib/` modules and `.js`, never the TypeScript source layout. The
+tarball allowlist excludes source maps, evidence, examples and game assets;
+SDK declarations, engine runtime code, MIT, copied AI docs, and dependency
+license texts are included. `distribution.json` records version and file hashes.
+Dependencies are normal pinned npm dependencies, not vendored engine sources.
+
+The npm workflow runs only for a published GitHub milestone release. Its gate
+requires tag/version/SDK/manifest identity and the existing milestone acceptance
+and source-fingerprint checks. An ordinary push or CPU-green build cannot publish.
+M3 is deliberately blocked until its release profile and real acceptance exist.
+The default smoke install uses npm cache only; `--online-install` allows network
+for initial dependency installation, then runs every operation offline with a
+disabled registry. CI uses this flag because `npm ci` alone need not populate
+registry metadata for a fresh external install. `--gpu` additionally measures
+the installed WebGPU backend, renders path/hybrid/raster, checks a nonblank canvas,
+captures through both CLI routes, verifies WebGL2 fallback rejection, and loads
+the nested-base static build without a development hook. It is not M3 acceptance.
+
+The single unscoped package is `pelican-engine`, its only public import is
+`pelican-engine`, and its executable is `pelican`. The GitHub target is
+`danchar12138/pelican-engine`; main completed the public repository rename and
+verified the updated origin. No new organization is required. The authorized
+npm Automation Token was authenticated as `danchar12138`, and main confirmed
+the repository Actions secret `NPM_TOKEN` is configured. `npm view pelican-engine`
+returned `E404` before publication. The package remains unpublished pending
+genuine M3 acceptance; this is not an authentication or organization blocker.
+`setup-node` configures the registry;
+only the final publication step receives `NODE_AUTH_TOKEN`. A missing secret
+fails with `TC_NPM_AUTH_MISSING`, without printing the value. The token must have
+permission to publish the fixed unscoped package. No OIDC/trusted-publisher setup
+or provenance flag is required by this workflow. Prereleases use `next`; stable
+versions use `latest`. These credentials do not bypass milestone acceptance.
+No token value is stored in source, documentation, or probe output. No publication
+is performed by this packaging task. See
+`tools/npm/publish-gate.ts` in the source distribution.

package/docs/npm/GAME-AUTHOR.md

@@ -0,0 +1,147 @@
+# Pelican Engine Game Author
+
+Your workspace is the game project. Use the public `pelican-engine` API and local
+game modules. Do not modify engine internals or `node_modules`, import Three.js,
+TSL, GPU devices, physics-library objects, compiler internals or Node APIs into
+game code. Engine research, hardware acceptance, evidence and publishing tasks
+are not part of game authoring.
+
+Read the API reference at `docs/api/REFERENCE.md` and machine-readable symbols at
+`docs/api/index.json` under the engine/package directory. Installed declarations
+are `lib/sdk/index.d.ts`. `pelican api` discovers the index;
+`pelican api --symbol defineGame` returns exact, case-sensitive public signatures
+as JSON in both source and npm distributions. `pelican help`
+lists the JSON CLI protocol. `docs/CAPABILITIES.md` records implemented scope and
+limitations. The longer `docs/AI-WORKFLOW.md` is shared design context, not an
+instruction to run source-only engine acceptance tasks.
+
+The shared `docs/M3-USAGE.md` describes the current rendering and compute
+contracts. Its `examples/`, engine `packages/`, and `npm run probe:*` references
+are maintainer references available only in a source checkout; the npm package
+intentionally contains no example projects, game assets, or engine source. Use
+the same public declarations in your own game project and validate them with the
+installed `pelican` commands. Do not try to import an internal compiled module.
+
+Models using `KHR_animation_pointer` animation channels are currently rejected
+with `TC_MODEL_EXTENSION_UNSUPPORTED`; pointer-driven material animation is not
+implemented. A merely declared optional extension without such a channel does
+not cause this runtime rejection.
+
+## Standalone Rendering Recipe
+
+The following complete asset-free `game.ts` works with either distribution and
+exercises the public opaque-IOR and specular material controls:
+
+<!-- standalone-render-recipe:start -->
+```ts
+import { defineGame, defineMaterial, defineScene } from "pelican-engine";
+
+const material = defineMaterial({
+  id: "paint",
+  color: "#303030",
+  roughness: 0.35,
+  metalness: 0,
+  ior: 1.5,
+  specularIntensity: 0.7,
+  specularColor: "#ffb080",
+});
+
+export default defineGame({
+  id: "render-recipe",
+  scene: defineScene({
+    id: "main",
+    camera: { position: [0, 1, 5], target: [0, 0, 0], fov: 45 },
+    environment: { background: "#17212a", ambientIntensity: 0.4 },
+    entities: [
+      { id: "object", mesh: { geometry: { kind: "box" }, material } },
+      { id: "light", transform: { position: [2, 4, 5] },
+        light: { kind: "directional", intensity: 3 } },
+    ],
+  }),
+});
+```
+<!-- standalone-render-recipe:end -->
+
+Use `npx --no-install pelican check` and `npx --no-install pelican dev` in an
+installed project, then `npx --no-install pelican build`. A repository-based
+project uses the same source and equivalent engine CLI commands listed below.
+Imported opaque GLB materials support `KHR_materials_specular` intensity and
+color textures with `TEXCOORD_0`. Positive transmission combined with specular
+textures or non-default specular remains unsupported. The tracer rejects PNG
+color maps with ICC profiles. Low-bit-depth grayscale and indexed Adam7 PNGs
+are decoded with explicit pass/filter validation. For 16-bit PNG,
+supported color chunks are gAMA 45455 or 100000, standard sRGB cHRM, sRGB
+intent 0, and cICP [1,13,0,1]; other values are diagnosed. Use supported PNG
+or JPEG and retain diagnostics rather than silently changing material semantics.
+
+Audio voices returned by `ctx.audio.play(soundId, options)` can be paused and
+resumed with `ctx.audio.pause(voice)` and `ctx.audio.resume(voice)`. Both are
+idempotent; a valid unknown voice is a no-op. Playback position follows fixed
+simulation ticks, including while browser audio is locked. Paused time does not
+advance the voice. Snapshots restore playback intent and logical position, not
+the browser's internal audio processing state.
+
+Declare `audioBuses: [{ id: "music", volume: 0.5 }]` in `defineGame`, route a
+sound with `sounds: [{ id: "theme", asset: musicAsset, bus: "music" }]`, and
+change its bus using `ctx.audio.busVolume("music", 0.25)`. A `play` call can
+override the sound's bus with `{ bus: "music" }`. Bus, voice and master gains
+multiply; `ctx.audio.volume` controls master gain. Unknown buses and gains
+outside 0–1 return diagnostics. Games with no buses keep their existing routing.
+
+Use `ctx.audio.fadeBus("music", 0, 1.5)` for a fixed-tick linear fade in
+seconds. A new fade or `busVolume` replaces the previous fade. `play` accepts
+an optional integer `priority` from 0 to 255; when the voice limit is full, a
+new voice only replaces the earliest voice with a strictly lower priority.
+Invalid priority or a non-winning full voice returns a stable diagnostic.
+
+For orthogonal grid routing, game systems may call `ctx.navigation.createGrid`
+with `{ id, owner, width, height }`, then `setBlocked(id, { x, y }, true)` and
+`findPath(id, start, end)`. Paths contain both endpoints; `destroyGrid` and
+`destroyOwner` release grids. The default 65,536-cell `searchCellBudget` limits
+distinct cells considered per query; set it explicitly when needed. Budget
+exhaustion returns `TC_NAVIGATION_CAPACITY`, not an unreachable result. Owners
+are explicit strings, not entities. This is a development-stage grid service,
+not continuous-world, flying or underwater navigation.
+
+Keyboard bindings use the browser's `KeyboardEvent.key` values, not physical
+`KeyboardEvent.code` values. For example, use `input: { up: ["w", "W", "ArrowUp"],
+restart: ["r", "R"] }`, not `"KeyW"` or `"KeyR"`. Letter case depends on the
+actual keyboard event; Space is `" "`. Actions are read inside systems through
+`ctx.input.held`, `pressed`, `released`, or `axis`. Always exercise real keyboard
+input in the browser; a mocked system test does not establish browser bindings.
+
+## Work Loop
+
+1. Inspect `pelican.project.json`, `game.ts`, asset declarations and the public API.
+2. Make small game-only edits. Keep the exact engine version lock.
+3. Run `pelican check`, then `pelican dev` and exercise actual gameplay.
+4. Use `inspect`, `input`, `step`, `pause`, `resume`, `snapshot`, `restore`,
+   `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port.
+5. Run `capture --live` against the dev port or a standalone `capture`, inspect
+   the actual screenshot, and preserve explicit failures rather than claiming success.
+6. Run `build` and serve `dist/` over HTTP(S). Keep notices and license files.
+
+Installed package commands use `npx --no-install pelican <command>` from the game
+directory. Repository commands use `node --import tsx <engine>/tools/cli.ts
+<command> --project <game-directory>` with the same operations and protocol.
+Both `create` commands generate a project `AGENTS.md` pointing to these same docs.
+In a new installed workspace, `npm --prefix . i -D pelican-engine` followed by
+`npx pelican dev` automatically creates that same minimal starter when no project
+files exist. Existing games, manifests and author instructions are preserved.
+The explicit prefix prevents npm from choosing a parent project when one exists.
+
+Dependencies and Chromium must be installed before offline work. Once prepared,
+checks/builds/dev/capture use local files and loopback only. `setup --offline`
+never downloads a missing browser. In npm projects use `setup --install-browser`
+once while online. No Git checkout, account, external AI service or source tree
+is required to author an installed game.
+
+Do not assume all render modes are supported. Use `engine.render.capabilities()`
+to inspect the actual backend. WebGL2 fallback does not silently implement
+compute-dependent path/hybrid features. Observe structured diagnostics and keep
+the prior valid state on rejected operations. Hardware acceptance is separate
+from a successful software-rendered or CPU-only run.
+
+For project-version mismatches, migrate via public API, then explicitly update
+the lock. For package integrity/dependency errors, reinstall one exact package
+version. Never work around a diagnostic by importing an internal dependency.

package/engine.manifest.json

@@ -0,0 +1,15 @@
+{
+  "name": "pelican-engine",
+  "version": "0.3.1",
+  "milestone": "M3",
+  "stage": "advanced-rendering-development",
+  "license": "MIT",
+  "protocolVersion": "0.1.0",
+  "agentEntry": "AGENTS.md",
+  "developmentPlatform": "windows",
+  "renderer": "webgpu-with-webgl2-fallback",
+  "publicApi": "lib/sdk/index.d.ts",
+  "workflow": "docs/npm/GAME-AUTHOR.md",
+  "releasePolicy": "docs/npm/DISTRIBUTION.md",
+  "releaseScope": "dynamic-raytracing"
+}

package/lib/assets/audio.js

@@ -0,0 +1,67 @@
+import path from "node:path";
+export function inspectWAV(data, ctx) {
+    if (data.toString("latin1", 0, 4) !== "RIFF") {
+        const magic = data.toString("latin1", 0, 4);
+        if (path.extname(ctx.file).toLowerCase() === ".wav" &&
+            !["RF64", "RIFX"].includes(magic))
+            ctx.invalid("WAV/header", "Missing or damaged RIFF header.");
+        ctx.unsupported("audio/format", "Only little-endian RIFF/WAVE PCM and IEEE float audio are implemented.");
+    }
+    ctx.check(data.length >= 12 && data.toString("latin1", 8, 12) === "WAVE", "WAV/header", "Missing or truncated WAVE header.");
+    ctx.check(data.readUInt32LE(4) + 8 === data.length, "WAV/length", "RIFF length does not match the file.");
+    let offset = 12;
+    let format;
+    let samples;
+    let factFrames;
+    while (offset < data.length) {
+        ctx.check(offset + 8 <= data.length, "WAV/chunk", "Truncated chunk header.");
+        const id = data.toString("latin1", offset, offset + 4), size = data.readUInt32LE(offset + 4);
+        const end = offset + 8 + size, padded = end + (size % 2);
+        ctx.check(padded <= data.length, `WAV/${id}`, "Chunk exceeds RIFF boundary or is missing padding.");
+        const chunk = data.subarray(offset + 8, end);
+        if (id === "fmt ") {
+            ctx.check(!format && !samples && size >= 16, "WAV/fmt", "Missing, duplicate, misplaced or truncated format chunk.");
+            const encoding = chunk.readUInt16LE(0), channels = chunk.readUInt16LE(2), sampleRate = chunk.readUInt32LE(4);
+            const byteRate = chunk.readUInt32LE(8), blockAlign = chunk.readUInt16LE(12), bitsPerSample = chunk.readUInt16LE(14);
+            if (![1, 3].includes(encoding))
+                ctx.unsupported("WAV/encoding", `WAVE format tag ${encoding} is not implemented (PCM=1, float=3).`);
+            ctx.check(size === 16 || (size >= 18 && chunk.readUInt16LE(16) === size - 18), "WAV/fmt", "Invalid format extension length.");
+            ctx.check(channels > 0 &&
+                sampleRate > 0 &&
+                (encoding === 1 ? [8, 16, 24, 32] : [32, 64]).includes(bitsPerSample), "WAV/fmt", "Invalid channels, sample rate or sample size.");
+            ctx.check(blockAlign === (channels * bitsPerSample) / 8 &&
+                byteRate === sampleRate * blockAlign, "WAV/fmt", "Inconsistent block alignment or byte rate.");
+            format = { encoding, channels, sampleRate, bitsPerSample, blockAlign };
+        }
+        else if (id === "fact") {
+            ctx.check(factFrames === undefined && size >= 4, "WAV/fact", "Duplicate or truncated fact chunk.");
+            factFrames = chunk.readUInt32LE(0);
+        }
+        else if (id === "data") {
+            ctx.check(format && !samples, "WAV/data", "Missing format chunk or duplicate data chunk.");
+            ctx.check(size > 0 && size % format.blockAlign === 0, "WAV/data", "Empty or incomplete sample frame.");
+            samples = chunk;
+        }
+        offset = padded;
+    }
+    ctx.check(format && samples, "WAV/chunks", "Both fmt and data chunks are required.");
+    if (format.encoding === 3) {
+        const step = format.bitsPerSample / 8;
+        for (let i = 0; i < samples.length; i += step)
+            ctx.check(Number.isFinite(step === 4 ? samples.readFloatLE(i) : samples.readDoubleLE(i)), "WAV/data", "Non-finite floating point sample.");
+    }
+    const frameCount = samples.length / format.blockAlign;
+    ctx.check(format.encoding !== 3 || factFrames !== undefined, "WAV/fact", "IEEE float WAVE requires a fact sample count.");
+    if (factFrames !== undefined)
+        ctx.check(factFrames === frameCount, "WAV/fact", "Fact sample count does not match data frames.");
+    return {
+        format: "wav",
+        encoding: format.encoding === 1 ? "pcm" : "ieee-float",
+        channels: format.channels,
+        sampleRate: format.sampleRate,
+        bitsPerSample: format.bitsPerSample,
+        frameCount,
+        duration: frameCount / format.sampleRate,
+        dataBytes: samples.length,
+    };
+}

package/lib/assets/errors.js

@@ -0,0 +1,36 @@
+export class AssetInspectionError extends Error {
+    code;
+    file;
+    resource;
+    suggestion;
+    constructor(code, file, resource, detail, suggestion) {
+        super(`${code}: ${file} [${resource}]: ${detail} ${suggestion}`);
+        this.code = code;
+        this.file = file;
+        this.resource = resource;
+        this.suggestion = suggestion;
+        this.name = "AssetInspectionError";
+    }
+}
+export class InspectionContext {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    invalid(resource, detail) {
+        throw new AssetInspectionError("TC_ASSET_INVALID", this.file, resource, detail, "Repair or re-export the source asset and inspect it again.");
+    }
+    unsupported(resource, detail) {
+        throw new AssetInspectionError("TC_ASSET_UNSUPPORTED", this.file, resource, detail, "Convert to a supported self-contained format; see packages/assets/README.md.");
+    }
+    check(condition, resource, detail) {
+        if (!condition)
+            this.invalid(resource, detail);
+    }
+    integer(value, resource, min = 0, max = Number.MAX_SAFE_INTEGER) {
+        this.check(Number.isSafeInteger(value) &&
+            Number(value) >= min &&
+            Number(value) <= max, resource, `Expected an integer in [${min}, ${max}].`);
+        return value;
+    }
+}