@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/docs/environment.md

@@ -0,0 +1,186 @@
+# Environment shading
+
+A modern anime-style scene shader for rooms, props, and terrain. It targets three
+input classes with no shader edits: convention-named texture packs
+(Liyue-style `Diffuse/SMBE/LSAB/ESA/Normal` siblings), standard glTF scenes,
+and untextured/flat-color scenes.
+
+```js
+import {
+  applyEnvironmentShader,
+  resolveEnvironmentPreset,
+  createEnvironmentSunRig,
+  createEnvironmentLampRig,
+  captureEnvironmentAmbientProbe,
+  createEnvironmentPlanarReflection,
+  advanceEnvironmentShaderTime,
+} from '@call-me-sensei/toonlab/environment';
+
+const preset = resolveEnvironmentPreset('interiorDay');
+await applyEnvironmentShader(root, { environmentBox, hasSun: true, ...preset });
+
+const sun = createEnvironmentSunRig({ scene, environmentBox });
+const lamps = createEnvironmentLampRig({ scene, environmentBox, root, spot: { castShadow: true } });
+captureEnvironmentAmbientProbe({ renderer, scene, position: roomCenter });
+
+// per frame:
+advanceEnvironmentShaderTime(delta);
+```
+
+(Inside this repo the labs import from `../../src/environment/...`.)
+
+## Adapter and settings
+
+`applyEnvironmentShader(root, options)` walks the scene, resolves texture
+sets, classifies material roles, and converts materials. Configuration is
+`{ features, parameters }`, normalized by `createEnvironmentSettings()`:
+
+```js
+await applyEnvironmentShader(sceneRoot, {
+  features: { packedMap: true, shadowMask: true, skyTint: true, spotLights: true },
+  parameters: {
+    exposure: 0.95,
+    ambientLightInfluence: 0.22,
+    shadowTintColor: [0.86, 0.82, 0.78],
+    saturation: 1.08,
+  },
+});
+```
+
+All 72 fields are in the [settings reference](settings-reference.md)
+(`ENVIRONMENT_SETTING_GROUPS` / `ENVIRONMENT_SETTING_FIELD_SCHEMA`); color
+parameters accept `THREE.Color`, hex strings/numbers, `{ r, g, b }`, or
+`[r, g, b]`. Runtime re-tuning goes through
+`applyEnvironmentSettingsToMaterial(material, settings)`.
+
+The shader consumes standard maps — `normalMap` (derivative-TBN, no tangents
+required), `aoMap`/`lightMap` (uv1/uv2-aware, warm-tinted occlusion,
+painterly lightmap remap), `emissiveMap` (scaled down by day, full at night)
+— plus convention-pack siblings found by filename probing. Every sampler is
+define-gated per material, so unused maps cost nothing. Author hooks:
+`material.userData.envNormalMap/envAoMap/envLightMap/envEmissiveMap`.
+
+## Classification and roles
+
+Materials get environment roles — foliage, window cutout, emissive, shadow
+mesh, AO overlay, glossFloor — resolved in priority order:
+
+1. `userData.envRole` on the material or mesh,
+2. conversion option `roleOverrides: [{ match, role }]`,
+3. built-in keyword heuristics (`classifyEnvironmentMaterialRole`).
+
+`applyEnvironmentShader` returns a `classification` report
+(`{ object, material, role, source }` per material) so misfires are
+diagnosable at a glance.
+
+## Presets and preset documents
+
+`resolveEnvironmentPreset(name)` returns `{ features, parameters, rig }` for
+`default`, `interiorDay`, `interiorEvening`, `interiorNight`,
+`interiorStudio` (tuned for untextured scenes), `exteriorDay`, `showcase`,
+and `call_me_sensei` — the studio-managed signature look, curated and
+updated over releases. The `rig` hints (`sun`, `spotShadows`, `probe`,
+`planarReflection`, `dustMotes`, `bakeVertexAo`, `lampIntensity`,
+`timeOfDayHour`) tell the host app which rigs to construct — the labs
+consume them automatically via `?envPreset=`.
+
+Register your own, either in code or as a shareable JSON document
+(`toonlab/environment-preset`, versioned and validated like toon presets):
+
+```js
+import {
+  registerEnvironmentPreset,
+  createEnvironmentPresetDocument,
+  validateEnvironmentPresetDocument,
+  registerEnvironmentPresetDocument,
+} from '@call-me-sensei/toonlab/environment';
+
+registerEnvironmentPreset('myRoom', { features: {...}, parameters: {...}, rig: {...} });
+
+const document = createEnvironmentPresetDocument('myRoom', { label: 'My Room' });
+// ...save/share JSON.stringify(document), then on another machine:
+const result = validateEnvironmentPresetDocument(document);
+if (result.ok) registerEnvironmentPresetDocument(result.value, { overwrite: true });
+```
+
+## Rigs
+
+Stylized light rigs positioned relative to the environment bounds
+(`environmentRelativePoint`):
+
+- `createEnvironmentSunRig({ scene, environmentBox })` — key directional
+  light plus visible sun disk, spill, beam, and shaft quads.
+- `createEnvironmentLampRig({ scene, environmentBox, root, spot })` — lamp
+  point/spot lights with optional shadowed downlight spots;
+  `applyEnvironmentLampEmissive(root, multiplier)` couples fixture emissive
+  textures to lamp intensity.
+- `createEnvironmentBackdrop(...)` — timed window backdrop
+  (morning/day/evening/night images, `environmentBackdropPeriodForHour`).
+- `createEnvironmentDustMotes(...)` — deterministic drifting motes for sun
+  shafts.
+
+## Time of day
+
+```js
+import { sampleEnvironmentTimeOfDay, applyEnvironmentTimeOfDay } from '@call-me-sensei/toonlab/environment';
+
+const state = sampleEnvironmentTimeOfDay(17.5); // hour 0..24
+applyEnvironmentTimeOfDay(state, { sunRig, lampRig, backdrop, environmentRoot });
+```
+
+`sampleEnvironmentTimeOfDay(hour)` interpolates keyframed sun
+color/intensity/position, ambient and lamp scales, sky tints, fog color, and
+backdrop period (sunrise 06:00, sunset 18:00); `applyEnvironmentTimeOfDay`
+pushes the sampled state everywhere in one call. In the labs: `?envTime=14`,
+`?envFreezeTime=1` for deterministic captures.
+
+## Ambient probe
+
+`captureEnvironmentAmbientProbe({ renderer, scene, position })` renders a
+six-direction probe at a point (typically the room center) so ambient light
+follows the room's own palette instead of a flat constant. Blend with the
+`ambientProbeBlend` parameter; colors land on every converted material via
+`setEnvironmentAmbientProbeColors`.
+
+## Planar reflection
+
+`createEnvironmentPlanarReflection({ renderer, scene, camera, ... })` adds
+one oblique-clipped mirror pass for glossy floors (`glossFloor` role),
+fresnel-faded, including character reflections. Call `reflection.update()`
+per frame. `detectEnvironmentFloorY(root)` finds the floor height.
+
+## Vertex AO for untextured scenes
+
+With `bakeVertexAo: 'auto'` (the default), untextured meshes get per-vertex
+ambient occlusion baked at conversion — BVH-accelerated
+(`three-mesh-bvh`), deterministic, budgeted with explicit skip warnings.
+Direct API: `bakeEnvironmentVertexAo`. Untextured materials also get a
+designed gradient (floor falloff + sky tint) so flat-color rooms read
+art-directed; the `interiorStudio` preset tunes the whole look for this
+class.
+
+## Interior occlusion, fog, cloud shadows
+
+- `setEnvironmentOpenings(openings)` + the `interiorOcclusionStrength`
+  parameter darken interiors based on where the real openings (windows,
+  doors) are.
+- Converted materials participate in `scene.fog`, plus world-height fog via
+  `heightFogDensity/Falloff/Color`.
+- `setEnvironmentCloudShadow({ strength, coverage, scale, velocity })`
+  drives the same procedural cloud-shadow field the grass, trees, and water
+  use; advance the shared clock once per frame with
+  `advanceEnvironmentShaderTime(delta)`.
+
+## Debug views
+
+`?envDebug=<mode>` in the labs or `setEnvironmentDebugOutput(root, mode)` in
+code renders one term in isolation:
+
+```text
+albedo | lit | ambient | direct | shadowMask | pointLight | spotLight |
+occlusion | bakedGi | normal | vertexAo | specular | emissive | windowMask |
+roomOcclusion | alpha
+```
+
+Debug branches compile out entirely unless requested. Captures freeze the
+shared environment clock automatically (`?envFreezeTime=1`).

package/docs/getting-started.md

@@ -0,0 +1,180 @@
+# Getting started
+
+## Clone and run
+
+```bash
+git clone https://github.com/call-me-sensei/toonlab.git && cd toonlab
+npm install
+npm run dev
+```
+
+Vite opens `http://localhost:5175` on the curated Labs home. Pick **Character
+Shader Lab** (`/shader-lab/`) to see the bundled CC0
+mannequin already toon-shaded. Everything you see out of the box — water,
+sky, grass, trees, flowers, splashes — is procedural; the mannequin is the
+only bundled model.
+
+Rendering uses Three's `WebGPURenderer` by default. Use `?renderer=webgl` for
+the TSL WebGL2 fallback, or `?renderer=webgpu` to make the default explicit.
+
+`npm run build` produces a production build in `dist/`.
+
+## The labs
+
+The lab UIs live in `labs/` and are not part of the npm package. The catalog
+separates Shader Labs, Asset Labs, World Systems, and gameplay demos; some
+supporting editors are available only by direct URL. See
+[Lab responsibilities](lab-architecture.md) for the ownership rules.
+
+| Lab | URL | What it shows |
+|---|---|---|
+| Labs home | `/` | The curated catalog, grouped into Shader Labs, Asset Labs, World Systems, and demos. |
+| Character Shader Lab | `/shader-lab/` | A focused editor for the shared character treatment: every toon setting (23 groups), preset selection/export/import, debug views, and animation playback. Exercises `@call-me-sensei/toonlab/toon` and `@call-me-sensei/toonlab/debug`; the mannequin is preview content, not part of the preset. |
+| Environment Shader Lab | `/environment-lab/` | A focused editor for the shared environment-material treatment: feature paths, light response, interior occlusion, surface styling, preset selection/export/import, and debug views. Exercises `@call-me-sensei/toonlab/environment`; the room, lights, camera, and walk controls are preview-only. |
+| Playground: Controller Test | `/playground/` | Third-person character controller (WASD + mouse, Space to jump, Shift to sprint) on a vegetated stage. Exercises `@call-me-sensei/toonlab/character` retargeting + the vegetation systems. |
+| Environment Playground (Indoor) | `/playground/?scene=indoor` | Walkable indoor environment scene with a live Environment Settings panel (every environment shader feature and parameter from the field schema). Loads the first environment from your gitignored `assets-local/environments/` drop-in (bring your own scene — a load banner appears without one). Exercises `@call-me-sensei/toonlab/environment` + `@call-me-sensei/toonlab/debug`. |
+| Lighting Lab | `/lighting-lab/` | A focused lighting authoring and diagnostics surface with editable light outliner, transforms, physical/artistic intensity, shadow and quality budgets, five test stages, many-light stress testing, reusable JSON presets, and Unreal Engine 5.8 MegaLights/Lumen intent export. Exercises `@call-me-sensei/toonlab/lighting`. |
+| Weather Lab | `/weather-lab/` | The standalone weather editor: 22 shared conditions, smooth transitions, live atmosphere/wind/precipitation/lightning/surface controls, a lightning test, and portable preset import/save/export. Exercises `@call-me-sensei/toonlab/weather` across sky, light, fog, vegetation, water, and GPU precipitation. |
+| Water Lab | `/water-lab/` | The standalone water editor: every authored preset field for waves, surface color, foam, lighting/reflections, ripples, and splashes, plus construction-time quality selection, preset save/load/export, debug views, and interactor toys (splashes, buoyant balls, rain). Three stage grounds follow the preset — a gentle beach where the swash runs up and down the sand, a beach-to-deep basin with depth-test rocks/fish/kelp, and open water with a small island and a floating CC0 ship (PolyHaven `dutch_ship_medium` from `assets-local/`, toon boat fallback). **Preview in scene** carries your authored settings into the walkable Water Playground. Exercises the full `@call-me-sensei/toonlab/water` system. |
+| Sky Lab | `/sky-lab/` | The standalone sky-system editor: gradient curves, horizon scattering, sun-disc and glow treatment, painterly cloud structure/motion, star pattern/twinkle, portable presets, and renderer parity. Lighting, weather, and camera are preview-owned rather than saved in the sky preset. Exercises `@call-me-sensei/toonlab/sky`. |
+| Water Playground | `/playground/?scene=water` | The walkable beach diorama — wadeable lake (ripples, wakes, buoyancy), flowing river with current, and ocean beach with shoaling swell, plunging breakers, and swash. Walk in past chest depth and the character swims; C/Ctrl dives, Space swims up. **Edit in Water Lab** round-trips the live settings back to the editor. |
+| Rock Lab | `/rock-lab/` | Procedural stylized rocks, cliffs, heightfields, sculpt edits, and GLB export from `@call-me-sensei/toonlab/rockgen`. |
+| Tree Lab | `/tree-lab/` | Procedural stylized trees and bushes, sketch authoring, attached canopy blossoms, recipes, and GLB export from `@call-me-sensei/toonlab/vegetation`. |
+| Flower Lab | `/flower-lab/` | Standalone procedural flowers with stem, leaf, bloom, recipe, and GLB controls from `@call-me-sensei/toonlab/vegetation`. |
+| Grass Lab | `/grass-lab/` | Procedural blade dimensions, planting-ready grass material data, motion response, coordinated base/tip/shadow palettes, portable presets, and gameplay-scale previews from `@call-me-sensei/toonlab/vegetation`. Current scene light and preview placement are not saved. |
+| Vegetation Shader Lab | `/vegetation-shader-lab/` | One IP-wide vegetation treatment, validated across grass, foliage, flowers, bark, and stems while asset palette and scene-owned wind, wetness, and snow remain outside the shader profile. |
+| Debris Lab | `/debris-lab/` | Procedural debris and scatter pieces with preset thumbnails and GLB export from `@call-me-sensei/toonlab/debrisgen`. |
+| Texture Lab | `/texture-lab/` | Seamless procedural PBR textures for anything — 60+ material presets, layered pattern/color/overlay controls, an AI prompt box (offline mapper built in; add your own Gemini/OpenAI key for smarter mapping), and PNG/ZIP export from `@call-me-sensei/toonlab/texgen`. |
+| Outdoor World | `/examples/outdoor-world/` | Walkable integration scene for terrain, paths, bridges, villages, lighting, water, and vegetation at world scale. |
+| VFX Arena | `/examples/vfx-arena/` | Walkable combat-effects integration scene for `@call-me-sensei/toonlab/vfxgen`. |
+| Fauna Demo | `/examples/fauna-demo/` | Gameplay-scale preview for birds, butterflies, dragonflies, and koi from `@call-me-sensei/toonlab/fauna`. |
+| Ambient VFX Demo | `/examples/ambientfx-demo/` | Gameplay-scale preview for petals, leaves, fireflies, pollen, and mist from `@call-me-sensei/toonlab/ambientfx`. |
+| Prop Lab | `/prop-lab/` | Direct supporting editor for procedural prop recipes, placement contracts, and export. |
+| Building Lab | `/building-lab/` | Direct supporting editor for procedural building recipes and export. |
+| Gallery | `/gallery/` | Search and import open third-party textures, models, and HDRIs from supported public sources. |
+
+These categories describe ownership, not just navigation. Shader Labs save a
+reusable IP-wide material treatment; Asset Labs save the identity, geometry,
+and material data of an asset class; World Systems save coupled runtime
+behavior and appearance. Sky and Water therefore keep their shader controls in
+their complete system presets instead of creating separate Sky Shader or Water
+Shader documents.
+
+### World-system composition and quality
+
+For both `StylizedSky` and `WaterSurface`, `.settings` is the authored baseline
+used by portable documents. Lighting, Weather, or another live scene owner
+should use a unique id with `setSceneOverrideLayer(id, valuesOrResolver)` and
+remove only that id with `clearSceneOverrideLayer(id)`. The composed result is
+available through `.renderedSettings`; it must not be written back into a
+preset. `setSceneOverrides()` is only the convenience manual layer, and
+`clearAllSceneOverrideLayers()` is reserved for an explicit full teardown.
+
+Create a `LightingSystem`, then call `lighting.attachWorld(world)` to drive the
+world-owned sun adapter and private Lighting layers for Sky and Water. When the
+world has Weather, it also installs Lighting as Weather's sun/ambient/fog
+bridge: Lighting remains the sole writer for those outputs, while Weather
+supplies modulation and its own higher-priority Sky/Water layers. Detaching
+Lighting restores its world state and clears only Lighting-owned layers.
+
+A Sky preset contains exactly 46 portable art fields; dome radius and quality
+are runtime policy. Named Sky quality tiers compile 2, 3, or 4 cloud octaves,
+and `{ cloudOctaves: 1..5 }` defines a custom tier. `sky.setQuality()` rebuilds
+the Sky material while preserving authored settings and live layers. Water
+quality is also compile-time, but is selected when constructing
+`WaterSurface`; changing it requires replacing/rebuilding the surface. The
+Water Lab performs that rebuild, while `water.applySettings()` remains a live
+art/simulation update rather than a quality switch.
+
+The water scenes expose an **Env** lighting select (Noon / Sunset / Moonlit /
+Overcast / Storm), water **Mode** and **Tone** selects, quality tiers, debug
+views (`?waterDebug=foam`, `depth`, `ripple`, ...), and Drop Ball / Drop
+Sinker buttons for buoyancy testing.
+
+## URL params, persistence, and Reset Lab
+
+Every URL parameter has a HUD control — the HUD writes the parameter back
+into the URL, so any lab state is shareable as a deep link. Key params:
+
+```text
+?model=<path or URL>       character model (see below)
+?toonPreset=default        toon preset
+?toonDebug=band            toon debug view (docs/toon-shading.md)
+?envPreset=interiorDay     environment preset
+?envDebug=albedo           environment debug view (docs/environment.md)
+?waterMode=ocean           water preset; ?waterTone=, ?waterQuality=, ?waterDebug=
+?skyPreset=golden_hour     sky system preset
+?post=1&postPreset=softAnime  post-processing (docs/post-processing.md)
+```
+
+Lab state (selected model, presets, debug views) is saved per lab in
+`localStorage` and restored when you return with a bare URL. An explicit URL
+parameter always wins over a stored value. The **Reset Lab** button clears
+the stored state for the current lab and reloads it clean.
+
+## Loading your own models
+
+Three ways, no code changes required (details in
+[characters.md](characters.md)):
+
+1. **Model URL input** — paste any local path or hosted URL into the HUD's
+   Model URL field (or use `?model=`). Supported formats: GLB/glTF, VRM 0
+   and 1, PMX/PMD, FBX, OBJ (+ `&mtl=`), and text-based USDZ. Hosted URLs
+   must be served with CORS headers (`Access-Control-Allow-Origin`);
+   failures show an error banner in the HUD instead of a blank scene.
+2. **`assets-local/` drop-in folder** — a gitignored folder for private test
+   assets. Drop a character in `assets-local/models/` and run
+   `npm run assets:local`; it appears in every model-aware lab's Model select alongside
+   the bundled mannequin. A model is picked up when its path matches one of
+   these shapes (sibling textures/materials load automatically):
+
+   ```
+   assets-local/models/hero.glb                 # loose file
+   assets-local/models/hero/hero.pmx            # folder named after the character
+   assets-local/models/hero/model.vrm           # or a "model.*" main file
+   assets-local/models/hero/source/hero.fbx     # packaged marketplace download
+   assets-local/models/tests/<FORMAT>/<name>/…  # format test grid
+   ```
+
+   Nothing in `assets-local/` is ever committed or published. The discovery
+   rules live in `labs/shared/localModelCatalog.js`.
+3. **Bundled default** — the CC0 Quaternius mannequin
+   (`public/characters/mannequin.glb`) with 45 embedded clips, so every
+   character/model preview works with zero downloads.
+
+### Mixamo animation clips
+
+Models without embedded locomotion clips are animated by retargeting Mixamo
+FBX clips. Adobe's terms do not allow redistributing the clips, so download
+them with your own Adobe account from [mixamo.com](https://www.mixamo.com)
+and drop the FBX files into `assets-local/animations/` (e.g. `Idle.fbx`,
+`Walking.fbx`, `Swimming.fbx`). Without them, models fall back to their own
+embedded clips. See [ATTRIBUTION.md](../ATTRIBUTION.md) for the full
+asset-licensing picture.
+
+## Regenerating the settings reference
+
+[settings-reference.md](settings-reference.md) is generated from the settings
+schemas — never edit it by hand:
+
+```bash
+node scripts/generate-settings-reference.mjs
+```
+
+The script starts its own dev server on port 5192, extracts every settings
+schema through a headless browser, and writes the markdown. Set
+`TOONLAB_DOCS_BASE_URL=http://localhost:5175` to reuse a dev server that is
+already running.
+
+## Next steps
+
+- [Toon character shading](toon-shading.md)
+- [Environment shading](environment.md)
+- [Lighting](lighting.md)
+- [Generative style labs](style-labs.md)
+- [Water](water.md)
+- [Sky](sky.md)
+- [Vegetation](vegetation-sky.md)
+- [Post-processing](post-processing.md)
+- [Characters and animation](characters.md)
+- [Debug panel](debug-panel.md)

package/docs/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Cpath d='M0 0H100V78L78 100H0Z' fill='%23e8332e'/%3E%3Ctext x='50' y='72' font-size='64' font-weight='900' font-family='Hiragino Sans, Yu Gothic, Noto Sans JP, sans-serif' fill='white' text-anchor='middle'%3E%E3%83%88%3C/text%3E%3C/svg%3E" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="ToonLab open-source documentation: use the runtime library, connect the local MCP server, and drive it all with an AI coding agent." />
+    <title>Documentation — ToonLab</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/docs/main.jsx"></script>
+  </body>
+</html>

package/docs/lab-architecture.md

@@ -0,0 +1,100 @@
+# Lab responsibilities
+
+ToonLab separates authoring tools by the lifetime and reuse scope of the
+artifact they produce. A lab is not named after every shader program it happens
+to use; it is named after the reusable thing a developer saves and ships.
+
+## What “shader” means here
+
+A shader is GPU code plus a stable parameter contract that defines how a class
+of materials responds to light, view direction, shadows, and other world
+inputs. The shader implementation may have several technical variants, while
+one saved profile supplies the coherent art direction for an IP.
+
+The shader profile does not own an asset's geometry, textures, base color, or
+species. It also does not own the scene's current sun, wind, wetness, or snow.
+Those values are inputs to the profile.
+
+## Catalog groups
+
+| Group | Saved artifact | Labs | Responsibility |
+|---|---|---|---|
+| Shader Labs | An IP-wide rendering profile | Character Shader Lab, Vegetation Shader Lab, Environment Shader Lab | Reusable material treatment across many compatible assets. |
+| Asset Labs | A model, texture, or asset recipe | Rock Lab, Tree Lab, Flower Lab, Grass Lab, Debris Lab, Texture Lab | Geometry, species/shape identity, material data, and export. |
+| World Systems | A complete runtime-system preset | Water Lab, Sky Lab | Coupled appearance, animation/simulation, runtime integration, and quality behavior. |
+| Playgrounds & demos | No production preset of their own | Playground, Water Playground, Outdoor World, VFX Arena, Fauna Demo, Ambient VFX Demo | Validate authored artifacts in gameplay-scale scenes. |
+
+Weather Lab and Lighting Lab are direct supporting editors for their npm
+systems. They are not shader profiles: Weather coordinates current world
+state, while Lighting authors light rigs and day-cycle behavior.
+
+## Why Water and Sky are not separate Shader Labs
+
+Water and sky both contain substantial GPU shading, but their useful shipping
+artifact is larger than a material profile.
+
+- A Water preset keeps surface color, refraction, reflections, and foam
+  together with waves, shoreline behavior, ripples, splashes, underwater
+  response, and quality limits. Its Surface, Foam, and Lighting groups are the
+  embedded water-shader controls.
+- A Sky preset keeps the gradient, horizon scattering, sun, procedural clouds,
+  stars, and animation behavior together. Its
+  Gradient, Sun, Clouds, and Stars groups are the embedded sky-shader controls.
+
+Splitting either system into a second shader lab would create two documents
+that must be kept compatible and would make ownership of shared parameters
+unclear. The system lab therefore owns one versioned preset and exposes its
+shader/appearance section explicitly.
+
+## Parameter scope
+
+| Scope | Examples | Saved by |
+|---|---|---|
+| IP shader profile | Cel bands, shadow-color treatment, thin-surface response, role-specific bark or petal lighting | Character, Vegetation, or Environment Shader Lab |
+| Runtime-system preset | Water spectrum and surface response; sky gradient, sun disc, cloud shapes, star field, and cloud motion | Water or Sky Lab |
+| Asset/material | Grass base/tip/shadow palette, flower species colors, bark texture, mesh topology | Asset Lab document |
+| Scene/world state | Current time, sun direction, weather, wind, wetness, snow, exposure | Host game, Weather, or Lighting system |
+| Instance/interaction | Placement, seed, scale, bend target, splash source | Host game or preview scene |
+
+Lab previews may expose scene and instance controls so an artifact can be
+tested, but preview-only values are labeled and excluded from exported preset
+documents. Sky-dome radius remains a runtime constructor option for
+compatibility, but because the dome is pinned to the far plane it has no
+art-direction effect and is not surfaced or saved by Sky Lab.
+
+System presets may carry authored fallback sun/sky values so Water or Sky
+renders coherently in isolation. In a composed world those are baselines, not
+competing owners: Lighting installs priority-100 Sky/Water layers and drives
+the world sun-direction adapter; Weather supplies Lighting modulation plus
+priority-200 Sky/Water layers; a manual scene layer is priority 300. Portable
+`settings` remain unchanged and effective `renderedSettings` stay inspectable.
+Each system clears only its own Symbol-keyed layer on teardown.
+
+World Systems also own deployment behavior without confusing it with art. Sky
+quality is a non-portable compile-time preview/device tier. Water retains a
+portable preferred quality default for compatibility, but hosts choose the
+actual tier when constructing the surface. Neither is a reason to split out a
+second shader document.
+
+## npm boundary
+
+Labs are development tools and are not published in the npm package. Every
+artifact they produce maps to a public runtime import:
+
+```text
+Character Shader Lab   -> @call-me-sensei/toonlab/toon
+Vegetation Shader Lab  -> @call-me-sensei/toonlab/vegetation
+Environment Shader Lab -> @call-me-sensei/toonlab/environment
+Water Lab              -> @call-me-sensei/toonlab/water
+Sky Lab                -> @call-me-sensei/toonlab/sky
+```
+
+The package owns settings normalization, schemas, preset registries, versioned
+document validation and serialization, runtime application, and lifecycle
+methods. The lab is a consumer of those APIs; it must not maintain a private
+copy of the production contract.
+
+`@call-me-sensei/toonlab/styles` can embed the typed documents produced by
+these labs. Its `vegetationShader`, `grass`, `water`, and `sky` slots validate
+the corresponding public document type and resolve it to runtime settings, so
+a published style bundle does not depend on a browser lab's private storage.