@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/docs/shader-constants.md

@@ -0,0 +1,77 @@
+# Shader constants reference
+
+Constants that are deliberately **not** exposed as settings — either because
+they are physics, because a CPU mirror must stay in lockstep with the GPU
+code, or because changing them requires re-deriving neighbors. If you need to
+tune one, edit the TSL shader source or its CPU mirror; this page tells you where and what will
+break.
+
+Everything that *is* meant to be tuned lives in the settings schemas
+(`TOON_SETTING_FIELD_SCHEMA`, `WATER_SETTING_FIELD_SCHEMA`,
+`ENVIRONMENT_SETTING_FIELD_SCHEMA`, `POST_PROCESSING_SETTING_FIELD_SCHEMA`,
+`VEGETATION_SHADER_FIELD_SCHEMA`, and the
+`GRASS/FLOWER/STYLIZED_TREE/SKY_SETTING_FIELD_SCHEMA` families) and renders in the
+`@call-me-sensei/toonlab/debug` panel.
+
+## Water
+
+| Constant | Where | Why fixed |
+|---|---|---|
+| `WATER_GERSTNER_WAVE_COUNT = 8` | `src/water/waterSettings.js` + wave loops in `src/shaders-tsl/chunks/water-waves.js` | Loop count baked into the shader; `buildGerstnerWaves()` (the CPU mirror used for buoyancy/physics) must produce exactly this many waves. Changing it means editing both in lockstep. |
+| Wavelength falloff `0.68`, min wavelength `0.05` | `buildGerstnerWaves()` in `waterSettings.js` | Wave-spectrum shape: each successive wave is 0.68× the previous wavelength. Part of the tuned spectrum, mirrored on the GPU. |
+| Slope limit `0.4` (`amplitude * waveNumber > 0.4`) | `buildGerstnerWaves()` | Gerstner waves self-intersect (loop over) past steepness ~1; 0.4 keeps the tuned look stable at every `waveIntensity`. |
+| Gravity `9.81` | `buildGerstnerWaves()` | Deep-water dispersion relation (`speed = sqrt(g/k)`). Physics. |
+| Detail-normal distance fade `smoothstep(16.0, 60.0, viewDistance)` and near/far blend `mix(0.2, 1.0, detailFade)` | `src/shaders-tsl/water.js` | Screen-stability tuning: full detail near, 20% far, fading over 16–60 m. Honest candidates for uniforms later; documented here until then. |
+| Detail UV advection factors `0.55` / `0.34`, second-layer rotation `1.9` rad | `src/shaders-tsl/water.js` | Two detail layers must drift at different, incommensurate rates or the surface visibly tiles. The triplet was tuned together. |
+| View-depth blend `0.18` (`effectiveDepth = columnDepth + viewDepthDiff * 0.18`) | `src/shaders-tsl/chunks/water-color.js` | How much grazing-angle view depth deepens the absorption color; tuned against the shoreline film fix. |
+| Absorption divisor `24.0` (`viewDepthDiff / 24.0`) | `src/shaders-tsl/chunks/water-color.js` | Far-field opacity floor so open water never goes glassy at distance. |
+
+Quality tiers (`WATER_DETAIL_OCTAVES`, `WATER_FOAM_OCTAVES`) **are** exposed:
+pass `quality: 'low'|'medium'|'high'` or a custom
+`{ detailOctaves, foamOctaves, qualityLevel }` — see
+`resolveWaterQualityDefines()` in `src/water/waterMaterial.js`.
+
+## Character (toon)
+
+| Constant | Where | Why fixed |
+|---|---|---|
+| Bayer 4×4 dither matrix | `src/shaders-tsl/chunks/character-color.js` | Screen-door fade pattern (`alpha.ditherOpacity`); the matrix itself is canonical. |
+| Cel edge anti-alias derivative math | `src/shaders-tsl/chunks/character-lighting.js` | Driven by `celShade.edgeAntiAliasStrength` (exposed); the fwidth-based widening formula is not a tunable. |
+| Self-shadow PCF tap offsets (4/9-tap) | `characterRenderPasses.js` + shadow chunks | Kernel shape; strength/bias are exposed via `selfShadow.*`. |
+
+## Environment
+
+| Constant | Where | Why fixed |
+|---|---|---|
+| Lightmap painterly remap (warm dark end, lift floor) | `src/shaders-tsl/chunks/environment-lighting.js` | The remap curve IS the art direction; its inputs (strengths, tints) are exposed in `environmentSettings`. |
+| Vertex-AO golden-spiral hemisphere sample set | `src/environment/environmentVertexAo.js` | Deterministic sampling pattern — changing it invalidates every baked result. Budget/strength are exposed. |
+
+## Vegetation / sky
+
+Formerly hardcoded uniforms (grass cloud-shadow coverage/scale/velocity,
+backlit strength, tree gnarl frequencies/amplitude, foliage shadow strengths)
+are now settings — see the vegetation/sky schemas. What remains fixed:
+
+| Constant | Where | Why fixed |
+|---|---|---|
+| Grass blade segment count / geometry proportions | `stylizedGrass.js` geometry builder | Baked into instanced geometry at construction; density/height ARE settings (construction-time). |
+| Tree trunk ring/segment tessellation | `stylizedTree.js` | Geometry topology; regenerating is the designed path (see the tree recipe system). |
+| Sky far-plane clip epsilon and horizon branch guards | `src/shaders-tsl/sky.js` | Numerical/render-order safeguards, not art direction. Dome radius remains constructor-compatible but is visually invariant because the vertex stage pins the dome to the far plane. |
+| Sky FBM implementation and deployment octave tiers | `src/shaders-tsl/sky.js`, `src/sky/skyQuality.js`, `chunks/water-common.js` | Noise/hash internals define deterministic parity. Shipped quality tiers compile 2/3/4 octaves (`low`/`medium`/`high`), with 1–5 custom; quality stays outside the portable art preset while cloud shape, seed, projection, softness, shading, and motion are exposed. |
+| Sky coverage calibration and projection singularity guards | `src/shaders-tsl/sky.js` | Stable mapping from the authored coverage/altitude controls to safe procedural thresholds. All visually meaningful colors, curve shapes, sun/glow terms, cloud treatment, and star treatment are schema fields. |
+
+## Post-processing
+
+All colors, strengths, and thresholds are exposed
+(`POST_PROCESSING_SETTING_FIELD_SCHEMA`, 29 parameters). The bloom pyramid's
+level count is exposed (`bloomLevels`, 2–8); the downsample filter weights are
+not (standard dual-filter kernel).
+
+## TSL texture binding budget
+
+The raw GLSL `USE_*` define plumbing was removed with Phase 11, but the
+binding budget did not disappear. The app currently requests default WebGPU
+limits, so native WebGPU and the forced WebGL2 fallback both need the same
+16-sampled-texture discipline. Optional maps must stay graph-gated in
+`src/shaders-tsl/anime.js`, `src/shaders-tsl/environment.js`, and their chunks:
+only construct/sample a texture node when the corresponding map exists.

package/docs/sky.md

@@ -0,0 +1,182 @@
+# Sky system
+
+`@call-me-sensei/toonlab/sky` provides a procedural stylized sky for Three.js:
+a three-stop vertical dome, sun disc and glow, sun-side horizon scattering,
+two-tone painterly clouds, and a procedural star field. It uses the same TSL
+material on WebGPU and the WebGL2 fallback and requires no texture assets.
+
+Sky is a World System in ToonLab. Its appearance shader and procedural motion
+ship as one versioned preset because the cloud, sun, horizon, and star terms
+must be judged together. It is not a fourth IP-wide Shader Lab; see
+[Lab responsibilities](lab-architecture.md).
+
+## Quickstart
+
+```js
+import { StylizedSky } from '@call-me-sensei/toonlab/sky';
+
+const sky = new StylizedSky({
+  preset: 'call_me_sensei',
+  quality: 'high', // deployment policy; not saved in the art preset
+});
+scene.add(sky);
+
+renderer.setAnimationLoop(() => {
+  const delta = clock.getDelta();
+  sky.update(delta, camera); // animates clouds/stars and follows the camera
+  renderer.render(scene, camera);
+});
+
+// Live runtime retuning does not rebuild the material.
+sky.applySettings({ cloudCoverage: 0.55, starsStrength: 0.2 });
+sky.setPreset('golden_hour'); // replaces the authored look from scratch
+```
+
+`StylizedSky` centers its dome on the camera and pins it to the far plane, so it
+does not intersect scene geometry. Add the same sky to scenes containing a
+`WaterSurface`; water reflection passes then capture the active composed sky rather
+than relying on a separate color approximation.
+
+## Settings and scope
+
+`createSkySettings(options)` normalizes flat settings. The public
+`SKY_SETTING_GROUPS` and `SKY_SETTING_FIELD_SCHEMA` drive Sky Lab and custom
+editors. The schema contains 46 portable art fields; the constructor-only dome
+radius is the single non-portable field.
+
+| Group | Owns |
+|---|---|
+| Gradient | Zenith, horizon, and below-horizon colors; zenith/ground curve shape; horizon-band width, sun focus, and scattering strength. |
+| Sun | Baseline disc direction and color; size, edge softness, intensity; broad/core glow shape; dense-cloud occlusion. |
+| Clouds | Coverage, scale, deterministic seed, projection, silhouette softness/opacity, direction and speed, two-tone shade controls, light-sample depth, silver lining, and horizon fade. |
+| Stars | Strength, color, deterministic seed, density, pattern scale, glint size, twinkle depth/speed, and horizon fade. |
+
+The runtime constructor still accepts `radius` for compatibility. Because the
+dome is centered on the camera and pinned to the far plane, changing that
+geometry radius does not change the rendered look. Sky Lab therefore does not
+surface it, and portable Sky preset documents do not serialize it.
+
+Sky settings do not own the current clock, directional-light intensity or
+shadow policy, precipitation, weather transition, fog volume, exposure, or
+camera. Lighting and Weather systems remain authoritative and may modulate the
+active sky at runtime. Independent owners use ordered layers rather than
+writing the same settings object:
+
+```js
+import { SKY_SCENE_OVERRIDE_PRIORITIES } from '@call-me-sensei/toonlab/sky';
+
+const lightingLayer = Symbol('lighting');
+const weatherLayer = Symbol('weather');
+
+sky.setSceneOverrideLayer(lightingLayer, {
+  sunDirection: lightingState.sunDirection,
+  zenithColor: lightingState.zenithColor,
+}, { priority: SKY_SCENE_OVERRIDE_PRIORITIES.lighting });
+
+// A resolver receives the result of lower-priority layers. Rain therefore
+// darkens the current time-of-day instead of replacing it with a stale color.
+sky.setSceneOverrideLayer(weatherLayer, (base) => ({
+  cloudCoverage: weatherState.atmosphere.cloudCoverage,
+  zenithColor: base.zenithColor.map((channel) => channel * weatherSkyScale),
+}), { priority: SKY_SCENE_OVERRIDE_PRIORITIES.weather });
+
+sky.clearSceneOverrideLayer(weatherLayer); // Lighting remains active
+```
+
+Layers compose in ascending priority: Lighting (100), Weather (200), then the
+manual scene layer (300). `applySettings()` edits the authored baseline and
+recomposes every active resolver; `setPreset(name, overrides)` replaces that
+baseline. `sky.settings` is always authored data, while
+`sky.renderedSettings`, `sky.sceneOverrides`, and `sky.sceneOverrideLayers`
+expose the effective runtime state.
+
+`setSceneOverrides()` is the convenience manual layer and
+`clearSceneOverrides()` removes only that layer. Named owners must call
+`clearSceneOverrideLayer(id)` so they cannot erase each other;
+`clearAllSceneOverrideLayers()` is reserved for a host that explicitly owns
+the complete teardown. `LightingSystem.attachWorld(world)` and
+`WeatherSystem` use private layers and release only their own state.
+
+The visible dome clouds and the world-projected cloud-shadow field are related
+weather signals, not the same procedural texture: the dome is angular and the
+shadow field is spatial over terrain, water, and vegetation. Weather coordinates
+coverage, wind, and intensity policy; games that require exact cloud-to-shadow
+registration should supply a shared host cloud-field adapter.
+
+## Deployment quality
+
+Sky quality is runtime policy, not art direction. `quality: 'low' | 'medium' |
+'high'` compiles two, three, or four FBM octaves respectively for each cloud
+sample. The graph is compile-time-unrolled, so `sky.setQuality(tier)` rebuilds
+only the Sky material while preserving authored settings, active scene layers,
+and animation time. Custom policies may pass `{ cloudOctaves: 1..5 }`.
+
+`SKY_QUALITY_TIERS`, `SKY_QUALITY_OPTIONS`, and `resolveSkyQuality()` are public.
+Quality is a preview control in Sky Lab and is deliberately absent from
+portable Sky preset documents.
+
+## Presets and portable documents
+
+Built-in presets include `default`, `call_me_sensei`, `clear_day`,
+`golden_hour`, `overcast`, and `moonlit`. `getSkyPresetOptions()` lists them
+and any project registrations.
+
+```js
+import {
+  createSkyPresetDocument,
+  createSkySettings,
+  parseSkyPresetDocument,
+  registerSkyPreset,
+  registerSerializedSkyPreset,
+  serializeSkyPreset,
+} from '@call-me-sensei/toonlab/sky';
+
+registerSkyPreset('violet_twilight', {
+  label: 'Violet Twilight',
+  settings: {
+    zenithColor: [0.12, 0.08, 0.32],
+    horizonColor: [0.88, 0.38, 0.5],
+    starsStrength: 0.35,
+  },
+});
+
+const document = createSkyPresetDocument('violet_twilight', {
+  label: 'Violet Twilight',
+  settings: createSkySettings('violet_twilight'),
+});
+const json = serializeSkyPreset(document);
+const result = parseSkyPresetDocument(json);
+if (result.ok) registerSerializedSkyPreset(json, { overwrite: true });
+```
+
+Documents use `{ type: 'toonlab/sky-preset', version, id, label,
+description, settings }`. Use `validateSkyPresetDocument` when a parsed object
+is already available. Documents contain complete normalized appearance
+settings, so they remain portable if a named base preset changes later.
+
+## Low-level material API
+
+Applications that own their dome mesh can use the same production material:
+
+```js
+import {
+  applySkySettingsToMaterial,
+  createSkyMaterial,
+} from '@call-me-sensei/toonlab/sky';
+
+const material = createSkyMaterial({ preset: 'moonlit' });
+applySkySettingsToMaterial(material, { starsStrength: 1.2 });
+applySkySettingsToMaterial(material, { preset: 'clear_day' }); // full reset
+```
+
+`createSkyMaterial` returns the TSL node material used by `StylizedSky`.
+`applySkySettingsToMaterial` updates the shared uniform contract without
+replacing the material.
+
+## Sky Lab
+
+Run `/sky-lab/` in the repository or `/labs/sky` on ToonLab Pro. The lab uses
+the npm settings schema directly and supports preset selection, undo/redo,
+local saves, JSON import/export, WebGPU/WebGL comparison, and preview-only
+weather/lighting fixtures. Exported documents contain all 46 reusable
+sky-system art fields and no current scene state or quality tier.

package/docs/style-labs.md

@@ -0,0 +1,309 @@
+# Generative style domains
+
+ToonLab's style domains are configuration authoring tools, not small preset
+catalogs. A developer defines a domain, chooses a nonzero seed in the 32-bit seed
+space, locks the decisions that already work, and keeps generating. The same
+recipe can therefore produce thousands or millions of reproducible candidates,
+and applications can register new families, operators, graph nodes, events, and
+layer types without changing ToonLab's built-in lists.
+
+## Status (2026-07 triage)
+
+The dedicated browser labs for these domains were removed from the labs grid:
+behavioral domains (camera, game feel, motion) cannot be judged against a demo
+stage, and the visual ones are curated via MCP batches + review instead. The
+domains themselves were triaged by one test — *does this simplify a Three.js
+game developer's life today?*
+
+| Domain | npm export | Lab | Notes |
+|---|---|---|---|
+| Post & color | ✅ `./post` | removed (future feature) | Curate presets via MCP; needs 3–5 owner-reviewed presets |
+| Camera | ✅ `./camera` | removed (future feature) | Ships as a code library; needs README quickstart |
+| Game feel | ✅ `./game-feel` | removed (future feature) | Ships as a code library; needs README quickstart |
+| Lighting | ✅ `./lighting` | ✅ `/lighting-lab/` | Styles + fixtures; see [lighting.md](lighting.md) |
+| Motion | ⏸ held (source at `src/motion/`) | removed (future feature) | Returns when a demo drives real GLTF clips end-to-end |
+| Soundscape | ⏸ held (source at `src/soundscape/`) | removed (future feature) | Rethink as adaptive mixing over curated audio assets |
+| Biome | ❌ cut (source at `src/biome/`) | removed (future feature) | Value lives in `stylizedTerrain`/`stylizedWorld`, already exported |
+| UI theme | ❌ removed entirely | removed (future feature) | Out of scope for a Three.js game library; recoverable from history |
+
+The product boundary is:
+
+```mermaid
+flowchart LR
+  M["Local MCP server"] --> R["Portable generator recipe"]
+  R --> G["Deterministic seed resolution"]
+  G --> P["Flat runtime preset"]
+  P --> N["npm package runtime"]
+  N --> F["Game frame loop"]
+```
+
+- MCP provides design-time recipe creation, validation, batch generation, and
+  `.toonlab/` persistence to coding agents.
+- The npm package owns shipping runtime behavior. It accepts resolved presets,
+  enforces relevant quality budgets, exposes update/configure/regenerate and
+  dispose lifecycle methods, and never depends on a lab UI.
+
+## One open generator contract
+
+Every generator recipe is a versioned JSON document with the same core fields:
+
+```js
+{
+  type: 'toonlab/biome-generator',
+  version: 1,
+  id: 'painted-valley',
+  label: 'Painted Valley',
+  seed: 4635,
+  basePreset: 'outdoorGameplay',
+  configuration: {},
+  domains: {
+    terrain: {
+      morphology: {
+        rolling: {
+          amp: { $type: 'range', min: 8, max: 42, step: 0.25 },
+        },
+      },
+    },
+  },
+  locks: ['terrain.palette.meadow'],
+}
+```
+
+Domain leaves support continuous ranges, weighted choices, booleans, colors,
+and constants. A domain can be narrowed, widened, replaced, or extended with
+new paths. Named random streams make a result deterministic and keep unrelated
+settings stable when another branch is added. Locks preserve selected paths
+while the remaining paths continue to vary.
+
+The result of generation is a flat, versioned preset. Runtime code does not
+sample a domain every frame. This keeps shipping behavior deterministic,
+serializable, debuggable, and inexpensive.
+
+## The domains
+
+### Post & color
+
+**Shipped in npm; lab removed (future feature).** Authors color grade, bloom,
+outline, vignette, depth cue, motion blur, and vertical grade together so the
+result reads as one look.
+
+- Open generation: every feature flag and numeric/color parameter is a domain;
+  custom post families and ordinary runtime presets are registerable.
+- Runtime: `createPostProcessingPipeline` applies the resolved settings, lazily
+  allocates the pyramid bloom chain, skips inactive passes, reports render-target
+  statistics, resizes safely, and disposes owned GPU resources.
+- Budgets: mobile removes depth-heavy effects and limits bloom; balanced limits
+  simultaneous depth consumers; cinematic preserves the authored intent.
+
+Import from `@call-me-sensei/toonlab/post`.
+
+### Camera
+
+**Shipped in npm; lab removed (future feature).** Builds a stack of camera
+operators instead of selecting one hard-coded camera type. Follow, framing,
+collision, damping, procedural noise, impulses, and lens behavior can be
+composed or extended.
+
+- Open generation: archetypes seed an editable domain; new generator
+  archetypes and runtime operator factories can be registered.
+- Runtime: `createCameraRig` evaluates the operator stack without editor state;
+  `createCameraDirector` blends between rigs and `addImpulse` handles event
+  response without coupling gameplay code to camera math.
+- Scale: one resolved operator stack is evaluated per active camera. Noise and
+  impulses are time-based and no candidate generation occurs in the frame loop.
+
+Import from `@call-me-sensei/toonlab/camera`.
+
+### Motion (held — future feature)
+
+**Held out of the npm exports; lab removed.** The runtime survives at
+`src/motion/` (verified by `verify:motion`) but does not ship until a demo
+drives real GLTF clips on a real character end-to-end. Authors an arbitrary
+animation graph, not a finite animation menu. Clip slots keep game assets
+separate from reusable locomotion logic.
+
+- Open generation: recursive 1D/2D/weighted blend nodes, any number of states,
+  transitions, parameters, layers, masks, and clip slots; procedural harmonic,
+  keyframe, and Three.js clip samplers share one pose contract.
+- Runtime: `createMotionController` evaluates transitions and layered poses,
+  supports root-motion policies and stepped/smooth cadence, and applies results
+  through a replaceable rig adapter.
+- Scale: graph validation catches missing slots and transition references
+  before runtime. Generation changes timing/style parameters while preserving
+  arbitrary user graph topology.
+
+### UI Theme Lab (removed — future feature)
+
+UI theming (semantic token generation, contrast auditing, scoped CSS export)
+was removed from the package and the labs grid: it serves web UI authoring, not
+Three.js game development, so it sits outside ToonLab's scope. The domain may
+return as a separate product if game-HUD theming becomes a real need. The last
+implementation lived at `src/ui-theme/` + `labs/ui-theme-lab/` (removed
+2026-07; recoverable from history).
+
+### Biome (cut — future feature)
+
+**Export cut; lab removed.** The runtime at `src/biome/` is a lifecycle wrapper
+that hard-requires ToonLab's own renderer/scene, so it is not consumable as a
+standalone package export; the underlying value (`stylizedTerrain`,
+`stylizedWorld`) is already exported from the package root. Treated a biome as
+continuous terrain morphology plus a linked palette, water, atmosphere, and
+vegetation system.
+
+- Open generation: terrain height/depth/frequency/terracing/islands, palette
+  endpoints, water colors, fog, grass/flower/tree density and size, and wind
+  are domain values; new terrain archetypes and biome families are registerable.
+- Runtime: `createBiomeRuntime` constructs the terrain and stylized world,
+  exposes race-safe asynchronous regeneration, updates world systems, reports
+  scene statistics, and owns disposal.
+- Budgets: mobile, balanced, and cinematic cap terrain segments and vegetation
+  radius/density/spacing so authored density never defeats the target device.
+
+### Soundscape (held — future feature)
+
+**Held out of the npm exports; lab removed.** The runtime survives at
+`src/soundscape/` (verified by `verify:soundscape`) but purely synthesized
+ambience has a quality ceiling below the asset bar; the likely return path is
+adaptive mixing over curated audio assets. A procedural audio graph that can
+use synthesized layers immediately and resolve project audio through an asset
+resolver later.
+
+- Open generation: any number of buses, layers, adaptive parameters,
+  modulation mappings, snapshots, and transitions; both generator families and runtime
+  layer factories are registerable.
+- Runtime: `createSoundscapeRuntime` creates its `AudioContext` lazily after a
+  user gesture, owns Web Audio nodes, transitions without rebuilding every
+  frame, exposes adaptive inputs, and disposes or closes owned resources.
+- Budgets: quality tiers cap nodes, layers, and voices. The runtime reports
+  skipped layers rather than silently exceeding its budget.
+
+### Game feel
+
+**Shipped in npm; lab removed (future feature).** Maps named gameplay events to
+coordinated response graphs. It is the integration layer for impact, not
+another VFX asset catalog.
+
+- Open generation: event definitions and effect factories are registries;
+  projects can add `parry`, `harvest`, `dialogueBeat`, or any other event and
+  compose built-in camera punch, hit-stop/time warp, squash, flash, audio, and
+  haptics; custom effect factories can connect project VFX or particles.
+- Runtime: `createGameFeelRuntime` schedules effects on scaled and unscaled
+  clocks, enforces cooldown/concurrency rules, returns gameplay delta after
+  time effects, and drives replaceable adapters instead of assuming a renderer
+  or input library.
+- Safety: haptics and audio are capability-gated; an adapter returning `false`
+  explicitly declines so fallback diagnostics remain honest. Unsupported
+  effects do not consume supported-effect capacity, errors are isolated,
+  trigger/drop statistics are exposed, and disposal restores time/camera/UI
+  state. Runtime quality tiers can tighten recipes, resolved presets, or raw
+  settings.
+
+Import from `@call-me-sensei/toonlab/game-feel`.
+
+### Lighting Lab
+
+`/lighting-lab/` authors the game's lighting identity as two generative
+artifacts instead of per-scene light configuration: **lighting styles**
+(`toonlab/lighting-style` — the full day as one curve: sun kelvin/intensity
+per hour, sun path, ambient policy, fog palette, exposure philosophy, shadow
+policy) and **light fixtures** (`toonlab/light-fixture` — reusable practicals
+like street lamps and lanterns with seeded per-placement variation, flicker,
+and day/night schedules).
+
+- Open generation: style families (`anime-day`, `call-me-sensei`, `golden`,
+  `noir-neon`, `pastel-overcast`) and fixture families (`warm-practical`,
+  `cms-practical`, `flame`, `neon`) are registries on the shared domain
+  grammar; subtree locks (`sun`, `atmosphere`, `exposure`) survive reseeds.
+- Runtime: `createLightingSystem` applies a style + fixtures to any scene or
+  stylized world — `setTimeOfDay(hour)` moves the whole look along the day
+  cycle, `place(fixture, position, { seed })` realizes budget-managed lights
+  with deterministic variation, `setWeatherModulation` is the single hook for
+  weather, and `dispose()` restores captured fog/exposure/sun state. Area
+  lights gate on LTC lookup-texture loading instead of crashing node backends.
+- Preview scenes: outdoor, interior, and city-night stages with a time-of-day
+  scrubber and weather modulation presets, so a style is judged standing next
+  to a lantern at night, not only at editor noon.
+
+Import from `@call-me-sensei/toonlab/lighting`.
+
+## MCP authoring
+
+The local MCP server exposes four tools shared by the shipped domains (post,
+camera, game feel, lighting styles, light fixtures):
+
+- `list_style_labs` returns runtime imports/APIs, extension families,
+  and generation capabilities.
+- `create_style_recipe` creates and optionally saves a recipe below
+  `.toonlab/creations/`.
+- `generate_style_presets` resolves one to 64 consecutive seeds in one call,
+  validates every result, and optionally saves the deterministic batch.
+- `validate_style_document` validates either an editable recipe or flat preset.
+
+For example, an agent can create a broad post-look recipe, lock the grade after
+review, generate seeds 2000–2063, and save the batch without inventing a finite
+catalog of look names. See [Local MCP and workspace](mcp.md) for connection
+instructions.
+
+## Runtime example
+
+```js
+import {
+  createPostGeneratorRecipe,
+  createGeneratedPostPresetDocument,
+  createPostProcessingPipeline,
+} from '@call-me-sensei/toonlab/post';
+
+// Usually authored and saved via MCP.
+const recipe = createPostGeneratorRecipe('soft-anime', { seed: 4635 });
+const preset = createGeneratedPostPresetDocument(recipe, { quality: 'balanced' });
+
+const post = createPostProcessingPipeline({
+  camera,
+  renderer,
+  scene,
+  settings: preset.settings,
+});
+
+renderer.setAnimationLoop(() => {
+  post.render(clock.getDelta());
+});
+
+// post.dispose();
+```
+
+Applications may ship recipes when runtime re-rolling is a feature, or resolve
+and check in presets when exact art direction is required. Both paths use the
+same npm implementation.
+
+## Engine practices adopted
+
+The architecture follows useful patterns from established engines while
+remaining native to Three.js:
+
+- Unreal Engine's Procedural Content Generation framework separates reusable
+  graphs, subgraphs, inspection/debugging, and editor/runtime generation. The
+  ToonLab equivalent is an extensible recipe domain plus a flat inspected
+  result.
+- Unreal Engine MetaSounds treats audio as a procedural runtime graph with
+  reusable patches and parameterized inputs. Soundscape uses the same graph and
+  registry mindset with explicit Web Audio budgets.
+- Unity Volume profiles separate reusable effect settings from local runtime
+  overrides. ToonLab recipes, resolved presets, locks, and quality overrides
+  serve the same separation.
+- Unity Cinemachine composes camera behaviors and provides separate impulse and
+  noise systems. ToonLab's camera domain uses an operator stack with event-driven impulses
+  and deterministic noise.
+- Unity Audio Mixer snapshots support controlled transitions between mixes;
+  Soundscape transitions buses and layers rather than hard-switching graphs.
+- Unity's Input System makes haptic support an optional device capability;
+  Game Feel uses adapters and capability checks rather than assuming a gamepad.
+
+Primary references:
+
+- [Unreal Engine Procedural Content Generation Framework](https://dev.epicgames.com/documentation/en-us/unreal-engine/procedural-content-generation-framework-in-unreal-engine)
+- [Unreal Engine MetaSounds](https://dev.epicgames.com/documentation/unreal-engine/metasounds-the-next-generation-sound-sources-in-unreal-engine?lang=en-US)
+- [Unity URP Volumes](https://docs.unity3d.com/ja/Packages/com.unity.render-pipelines.universal%4014.0/manual/Volumes.html)
+- [Unity Cinemachine](https://docs.unity3d.com/ja/current/Manual/com.unity.cinemachine.html)
+- [Unity Cinemachine Impulse](https://docs.unity3d.com/ja/Packages/com.unity.cinemachine%402.6/manual/CinemachineImpulse.html)
+- [Unity Audio Mixer snapshot transitions](https://docs.unity3d.com/jp/current/ScriptReference/Audio.AudioMixer.TransitionToSnapshots.html)
+- [Unity Input System gamepad haptics](https://docs.unity3d.com/ja/Packages/com.unity.inputsystem%401.4/api/UnityEngine.InputSystem.Gamepad.html)