@plasius/gpu-world-generator 0.0.10 → 0.0.12

package/docs/adrs/adr-0004-worker-dag-manifests-for-chunk-and-voxel-generation.md

@@ -0,0 +1,37 @@
+# ADR-0004: Worker DAG Manifests for Chunk and Voxel Generation
+
+- **Status**: Accepted
+- **Date**: 2026-03-14
+
+## Context
+
+World generation already has an inherent DAG: fractal prepass and field
+synthesis can start independently, terrain synthesis joins them, and voxel,
+mesh, bake, and serialization stages branch afterwards. Leaving this implicit
+forces consumer packages to flatten the pipeline into opaque queue work.
+
+## Decision
+
+Publish worker-first manifest helpers from `@plasius/gpu-world-generator`.
+
+- `streaming` profile:
+  runtime chunk generation and mesh-ready output
+- `bake` profile:
+  background/offline generation plus asset serialization
+
+Each manifest exports:
+
+- `queueClass: voxel`
+- `schedulerMode: dag`
+- explicit job priorities and dependencies
+- adaptive budget ladders for degradable stages
+- debug allocation metadata for observability
+
+## Consequences
+
+- Positive: chunk and voxel generation can be coordinated by shared worker and
+  performance packages without package-specific glue.
+- Positive: authoritative terrain stages remain explicit and protected from
+  visual-only degradation.
+- Negative: world-generation stage names become part of the public contract and
+  require migration discipline.

package/docs/adrs/adr-0005-render-representation-tiers-and-proxy-outputs.md

@@ -0,0 +1,51 @@
+# ADR-0005: Render Representation Tiers and Proxy Outputs
+
+## Status
+
+Accepted
+
+## Context
+
+The world architecture no longer assumes that every chunk is rendered from the
+same live representation. Near, mid, far, and horizon content should be able to
+use different visual and ray-tracing representations so the world scales in a
+predictable way.
+
+`@plasius/gpu-world-generator` already owns chunk and voxel generation, so it is
+the natural package to plan how world chunks will expose render-oriented
+representation tiers and proxy outputs before implementation begins.
+
+## Decision
+
+`@plasius/gpu-world-generator` will plan around formal representation tiers for
+rendering and RT preparation:
+
+- `near`: full live chunk output
+- `mid`: simplified live chunk output
+- `far`: HLOD, impostor, or proxy-driven chunk output
+- `horizon`: shell, skyline, or large-scale background representation
+
+The package should eventually be able to provide metadata or assets for:
+
+- chunk-local full geometry
+- simplified geometry or material reductions
+- RT proxy or reduced-fidelity instance data
+- merged or impostor-oriented distant proxies
+- low-refresh far-field or horizon assets
+
+## Consequences
+
+- Positive: distant rendering becomes a formal output tier instead of an
+  ad-hoc optimization.
+- Positive: renderer and world packages can coordinate around explicit chunk
+  representation bands.
+- Positive: RT proxy planning can start from generated world assets instead of
+  being recreated in a later stage.
+- Neutral: this ADR does not yet prescribe the final file format or buffer
+  layout for each proxy type.
+
+## Follow-On Work
+
+- Define the technical contract for chunk representation metadata and proxy
+  refresh policy.
+- Add test-first contract and unit specs before implementing new proxy outputs.

package/docs/adrs/index.md

@@ -3,3 +3,5 @@
 - [ADR-0001: GPU World Generator Package Scope](./adr-0001-package-scope.md)
 - [ADR-0002: Tiled World Generation, LOD, and Stitching](./adr-0002-world-tiling-lod-stitching.md)
 - [ADR-0003: Terrain Generation Style Mixing (Shader-Based)](./adr-0003-terrain-generation-style-mixing.md)
+- [ADR-0004: Worker DAG Manifests for Chunk and Voxel Generation](./adr-0004-worker-dag-manifests-for-chunk-and-voxel-generation.md)
+- [ADR-0005: Render Representation Tiers and Proxy Outputs](./adr-0005-render-representation-tiers-and-proxy-outputs.md)

package/docs/design/worker-manifest-integration.md

@@ -0,0 +1,42 @@
+# Worker Manifest Integration
+
+## Overview
+
+`@plasius/gpu-world-generator` now publishes chunk/voxel generation as a
+multi-root DAG so shared scheduling and performance packages can reason about
+world generation explicitly.
+
+## Streaming Profile
+
+- roots:
+  `fractalPrepass`, `fieldSynthesis`
+- join:
+  `terrainSynthesis`
+- branches after terrain:
+  `voxelMaterialize`, `tileBake`
+- final runtime visual stage:
+  `meshBuild`
+
+This profile models the latency-sensitive path used while streaming terrain
+around the active camera or player.
+
+## Bake Profile
+
+The bake profile reuses the same early stages and extends the tail with:
+
+- `assetSerialize`
+
+This represents offline or background generation where asset persistence is part
+of the pipeline.
+
+## Authority Boundaries
+
+- `fractalPrepass`, `fieldSynthesis`, `terrainSynthesis`
+  authoritative, fixed budgets
+- `voxelMaterialize`, `tileBake`
+  non-authoritative, degradable
+- `meshBuild`
+  visual, degradable
+
+This keeps core terrain correctness stable while allowing runtime pressure
+control to trim mesh and auxiliary output cost first.

package/docs/tdrs/index.md

@@ -0,0 +1,4 @@
+# TDR Index
+
+- [TDR-0001: World-Generator Worker Manifest Contract](./tdr-0001-world-generator-worker-manifest-contract.md)
+- [TDR-0002: Render Representation Tier Contract](./tdr-0002-render-representation-tier-contract.md)

package/docs/tdrs/tdr-0001-world-generator-worker-manifest-contract.md

@@ -0,0 +1,39 @@
+# TDR-0001: World-Generator Worker Manifest Contract
+
+- **Status**: Accepted
+- **Date**: 2026-03-14
+
+## Context
+
+The world-generator package needs to expose its chunk and voxel pipeline in a
+form that `@plasius/gpu-worker` and `@plasius/gpu-performance` can consume
+directly, without adding a hard dependency on either package.
+
+## Decision
+
+Publish two manifest profiles:
+
+- `streaming`
+  - `fractalPrepass`
+  - `fieldSynthesis`
+  - `terrainSynthesis`
+  - `voxelMaterialize`
+  - `meshBuild`
+  - `tileBake`
+- `bake`
+  - all streaming jobs plus `assetSerialize`
+
+Contract rules:
+
+- authoritative terrain jobs use fixed levels
+- degradable voxel/mesh/bake jobs expose low/medium/high ladders
+- job ids are namespaced as `world-generator.<profile>.<job>`
+- queue class is always `voxel`
+- scheduler mode is always `dag`
+
+## Consequences
+
+- Positive: consumers can import manifests directly and feed them into shared
+  worker-budget adapters.
+- Positive: the package stays in control of its actual generation topology.
+- Negative: adding or renaming stages becomes a public API change.

package/docs/tdrs/tdr-0002-render-representation-tier-contract.md

@@ -0,0 +1,60 @@
+# TDR-0002: Render Representation Tier Contract
+
+## Status
+
+Accepted
+
+## Goal
+
+Define the future contract for render and RT-oriented chunk representation tiers
+in `@plasius/gpu-world-generator`.
+
+## Planned Tier Outputs
+
+Each chunk or region should eventually be able to describe one or more of:
+
+- full live geometry output
+- simplified live geometry output
+- RT proxy output
+- merged HLOD or impostor output
+- horizon-shell or skyline output
+
+## Planned Metadata
+
+Representation descriptors should be able to carry:
+
+- chunk or region identifier
+- representation tier:
+  - `near`
+  - `mid`
+  - `far`
+  - `horizon`
+- refresh policy or expected update cadence
+- RT participation policy
+- shadow relevance policy
+- suggested ownership for renderer and worker scheduling
+
+## Planned Tests
+
+Contract tests should prove that:
+
+- chunk descriptors can distinguish near, mid, far, and horizon output tiers
+- proxy outputs can declare RT and shadow participation separately from the
+  live geometry output
+- refresh expectations are explicit for far and horizon content
+
+Unit tests should prove that:
+
+- world-generation manifests can describe merged or impostor-driven far-field
+  outputs without losing chunk identity
+- horizon representations can be low-frequency and still remain valid render
+  products
+- RT proxy descriptors can differ from the raster-facing representation tier
+
+## Implementation Notes
+
+The first public implementation now ships as
+`createWorldGeneratorRepresentationPlan(...)`. It publishes explicit near, mid,
+far, and horizon descriptors, exposes distinct raster and RT proxy outputs,
+retains chunk identity for proxy products, and includes refresh cadence,
+shadow-source relevance, and scheduling metadata for downstream packages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-world-generator",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "GPU-assisted world generation with hex-grid terrain synthesis.",
   "type": "module",
   "sideEffects": false,
@@ -38,13 +38,13 @@
     "prepublishOnly": "npm run build && npm run pack:check"
   },
   "dependencies": {
-    "@plasius/gpu-worker": "^0.1.8"
+    "@plasius/gpu-worker": "^0.1.10"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
+    "@types/node": "^22.10.0",
     "@typescript-eslint/eslint-plugin": "^8.46.2",
     "@typescript-eslint/parser": "^8.46.2",
-    "@types/node": "^22.10.0",
     "c8": "^10.1.3",
     "eslint": "^9.39.1",
     "globals": "^17.3.0",
@@ -65,5 +65,8 @@
   "homepage": "https://github.com/Plasius-LTD/gpu-world-generator#readme",
   "overrides": {
     "minimatch": "^10.2.1"
+  },
+  "engines": {
+    "node": ">=24"
   }
 }

package/src/index.ts

@@ -9,3 +9,4 @@ export * from "./fractal-prepass";
 export * from "./tiles";
 export * from "./tile-cache";
 export * from "./mesh";
+export * from "./worker";