@call-me-sensei/toonlab 0.3.0 → 0.4.19

package/agents/README.md

@@ -0,0 +1,59 @@
+# ToonLab Agent Resources
+
+These are downloadable AI coding agent resources for developers using ToonLab
+runtime features in their own apps. They are not maintenance instructions for
+this repository.
+
+The recommended agent workflow starts from an existing scene: apply focused
+shaders/vegetation/water/post, find assets through Gallery or MCP, and author
+bounded portable outputs. `outdoor-world`, `karst-cliff-construction`, and
+current Sky/Cloud guidance are experimental research/qualification resources,
+not a promise of reliable one-shot scene construction.
+
+Layout:
+
+- `codex/AGENTS.md` — shared Codex-style runtime usage guide.
+- `claude/CLAUDE.md` — Claude Code wrapper for the shared guide.
+- `cursor/toonlab.mdc` — Cursor rule file; copy it to `.cursor/rules/` in a
+  project if desired.
+- `skills/codex/` — Codex-oriented feature skills.
+- `skills/claude/` — Claude-oriented feature skills.
+- `references/` — public anime art direction, style routing, MCP discovery,
+  runtime-boundary, sourcing-policy, and custom-gap contracts used by every
+  agent integration.
+
+Recommended feature skills (start with `game-dev` for existing-scene
+integration and `asset-sourcing` for Gallery/MCP work):
+
+- `asset-sourcing`
+- `environment`
+- `game-dev`
+- `post-processing`
+- `rock-ground-shaders`
+- `rockgen`
+- `style-presets`
+- `toon-shading`
+- `vegetation-sky` (vegetation path; its Sky/Cloud path is experimental)
+- `visual-verification`
+- `water`
+
+Experimental or host-owned boundary skills:
+
+- `camera`
+- `game-feel`
+- `karst-cliff-construction`
+- `lighting`
+- `outdoor-world`
+- `weather`
+
+These text-only resources ship with the npm package beside the runtime source.
+The package does not include ToonLab lab applications, examples, review
+fixtures, models, textures, or other redistributed visual/media assets.
+First-party grass geometry and materials are generated by runtime code; the
+optional CC0 mannequin resolves from immutable public R2 rather than npm.
+
+All integrations share one non-optional authored-asset rule: every renderable
+root needs a stable target ID/domain, and every material slot needs a stable
+material ID plus semantic role in the versioned ToonLab material contract.
+Root-only labels do not make multi-material assets bundle-ready. Strict mode
+blocks incomplete assets; advisory mode must report them as incomplete.

package/agents/references/anime-art-direction.md

@@ -0,0 +1,24 @@
+# ToonLab Anime-Game Art Direction
+
+ToonLab is for anime-style games, characters, and environments. Do not treat
+"stylized" as permission to drift toward generic low-poly, western cartoon,
+pixel-art, or untreated photoreal rendering.
+
+The selected style bundle is the visual authority. Its `artDirection` must
+declare `family: "anime-game"`, `rendering: "cel-shaded"`, and both character
+and environment subjects.
+
+Evaluate every scene at gameplay camera distance:
+
+- Group values into intentional light and shadow shapes.
+- Preserve readable silhouettes and important material boundaries.
+- Reduce high-frequency texture detail deliberately; do not merely blur it.
+- Coordinate shadow color, atmosphere, sky, water, and post-processing.
+- Use material-aware graphic highlights for skin, hair, cloth, metal, leaves,
+  rock, ground, and water rather than one universal specular response.
+- Keep imported PBR maps as useful source information, then route the asset
+  through its owning ToonLab shader.
+
+If an asset or renderer cannot meet this direction with a supported shader,
+record a custom integration note instead of silently accepting a visually inconsistent
+fallback.

package/agents/references/asset-sourcing-policy.md

@@ -0,0 +1,23 @@
+# Asset-Sourcing Policy
+
+Import from `@call-me-sensei/toonlab/asset-policy`.
+
+Policies use one of three modes:
+
+- `strict`: a candidate is usable only when its domain rule explicitly lists
+  the candidate's source class.
+- `advisory`: preferred sources are ranked first; other registered sources
+  remain usable with a warning.
+- `open`: every registered source class is allowed, with provenance retained.
+
+Registered source classes are `project-library`, `toonlab-library`,
+`toonlab-gallery`, `external-cc0`, `procedural`, and `custom`.
+
+No policy means “ask, then advisory.” It never means strict and it never gives
+an agent permission to claim that a sourcing requirement was satisfied.
+
+The strict Call Me Sensei acceptance fixture allows rocks only from the
+project library, ToonLab library, or ToonLab gallery. Trees may also use the
+package's supported procedural legacy set or `BranchTree`. Other custom trees must be
+reviewed and admitted to one of the approved libraries before that fixture can
+use them.

package/agents/references/custom-gap-report.md

@@ -0,0 +1,16 @@
+# Custom integration records
+
+Custom work should be traceable instead of becoming an invisible fallback. Before adding it, use
+`record_asset_gap` or `createAssetGapRecord()` and record:
+
+- Target and rendering domain.
+- Relevant style-bundle slot.
+- MCP searches, queries, candidate IDs, and rejection reasons.
+- Why permitted library, gallery, external, or procedural routes failed.
+- What custom model, texture, shader, or adapter was introduced.
+- Provenance, license, generator/recipe/seed where relevant, and the decision owner.
+- Why the customization exists and what your team may want to revisit later.
+
+The MCP server maintains `.toonlab/reports/style-asset-gaps.json` and the
+project-level `TOONLAB_ASSET_GAPS.md`. Keep both with your project whenever it
+uses custom rendering or content outside the supported library.

package/agents/references/geology-playbook.md

@@ -0,0 +1,118 @@
+# Geology assembly playbook
+
+Use this reference with `karst-cliff-construction` and `outdoor-world`. It
+describes reusable landform craft without depending on project-specific
+helpers, asset IDs, or a frozen catalog count.
+
+## 1. Establish the parent mass
+
+Approve an untextured continuous terrain/heightfield silhouette first:
+headlands, bays, terraces, tower envelopes, channel, beach, and submerged bed.
+Catalog rocks dress and articulate that parent mass; they must not be the only
+thing preventing the world from reading as hollow.
+
+Reject before dressing when:
+
+- the hero silhouette is wrong;
+- the channel or beach footprint is clogged;
+- the cliff is a thin wall with no top/underwater continuation;
+- separate towers overlap into one clump from an approved camera.
+
+## 2. Select donors by visible role
+
+Query the connected ToonLab OSS or Pro catalog and shortlist with positive
+`dimensionsMeters`, taxonomy, scale class, and immutable preview/asset URLs.
+Family names and tags are search hints, not visual proof. Review contact sheets
+or finalists under one neutral material and camera azimuth.
+
+Useful morphology:
+
+| Role | Visible requirement |
+|---|---|
+| Primary face | Broad load-bearing plane, gravity-aligned relief, no prop-like outline |
+| Corner/termination | A turn or return face that buries cleanly into the parent mass |
+| Bedding ledge | A real horizontal lip with enough depth to cast a recess shadow |
+| Buttress/wedge | A seam bridge whose rear and toe can be buried |
+| Waterline notch | Rounded or undercut lip that continues below the surface |
+| Talus | Small jointed collapse block; free rotation is appropriate only here |
+
+Choose target dimensions in metres from the published native dimensions.
+Reject missing or invalid dimensions before download. Avoid solving an entire
+wall by stretching one small donor; report mean/max scale and worst axis ratio
+per structural role.
+
+## 3. Build courses, not rubble
+
+Primary faces share a near-common up axis and facing. Vary crop, burial,
+neighbour overlap, tier, yaw silhouette, and moderate scale; do not tumble
+load-bearing panels. Free three-axis tumbling belongs to collapse products.
+
+Starting burial ranges, to be verified in silhouette:
+
+- primary faces: bury roughly 30–60% of module depth;
+- bedding ledges: bury the rear majority so only the lip projects;
+- tower cores: seat the footing/course overlap, not most of the tower;
+- talus: rest in contact and bury enough to remove floating toes.
+
+Build in this order:
+
+1. primary faces at noses, re-entrants, terminations, and terrace breaks;
+2. bridging ledges, buttresses, crevice wedges, and recessed corbels;
+3. waterline/submerged continuation and restrained talus;
+4. vegetation caps and story dressing.
+
+If a placement helper automatically splits an oversized request into a stack,
+make that result explicit and refusable. Subdivision must not introduce yaw,
+pitch, or roll jitter unless the caller deliberately requests a tumbled role.
+
+## 4. Publish shared formation contracts
+
+Sibling modules must consume the same world-space values rather than derive
+private approximations:
+
+- parent height/envelope;
+- water level and submerged bed;
+- bedding elevation ladder;
+- visible face plane/standoff;
+- cliff-top and vegetation-cap polygons;
+- fall lips, landing pools, and exclusion zones.
+
+One useful bedding ladder is `base + courseIndex * spacing`; derive `base` and
+`spacing` from the terrain terracing/style rather than copying the qualifying
+scene's numbers. Align visible beds across neighbouring formations.
+
+## 5. Unify the material treatment
+
+Use one intentional parent lithology. The rock shader can replace source
+albedo and apply one projected treatment across morphologically compatible
+donors, but it cannot change incompatible geometry into the same geology.
+Record any cross-taxonomy donor override and judge the result from silhouette,
+bedding, and surface response.
+
+Prefer one `applyRockShader(formationRoot, settings)` call. Verify the report's
+texture source and shadow defaults. Use `setRockShaderSceneState` for the
+current water level so the wet band follows the shoreline.
+
+## 6. Prevent recognizable repetition
+
+Repeated asset ids are normal modular modelling. Repeated camera-facing
+silhouettes are the defect. For nearby copies vary at least three of: visible
+crop/burial, tier, neighbour overlap, meaningful scale, and camera-facing yaw.
+Never use regular spacing or a visible kit row.
+
+Placement metrics are rejection floors. They cannot prove that the rendered
+formation reads as one mass.
+
+## 7. Verify before approval
+
+- Wait for application readiness and a stable rendered scene graph.
+- Capture hero, wide, close, flyover, and top-down views.
+- Isolate terrain, rock formation, water, and lighting when assigning a defect.
+- Scan world-space extents for accidental slabs, dams, or oversized caps.
+- Report module counts, donor dimensions, transformed dimensions, burial,
+  per-role scale statistics, and active LODs.
+- Squint at the silhouette: if individual boulders or a sawtooth crest remain
+  legible, the cliff is still a pile.
+
+Automated checks may reject gaps, invalid scale, and repeated transforms. Only
+rendered multi-view evidence can approve the formation.

package/agents/references/mcp-asset-discovery.md

@@ -0,0 +1,104 @@
+# MCP Asset Discovery
+
+Use MCP for discovery, provenance, shared workspace state, and policy-aware
+imports. Use runtime package APIs for shader application and deterministic
+runtime construction.
+
+## Detect the available ToonLab surface
+
+Inspect the connected server's tool names before calling anything. Do not
+assume the developer has ToonLab Pro, and do not assume a local OSS checkout.
+
+- **ToonLab OSS local MCP** exposes `get_workspace_info`,
+  `search_cc0_assets`, `get_cc0_asset`, and `import_cc0_asset`. Its
+  `search_assets` searches built-in procedural entries, the complete official
+  R2-backed Gallery catalog, and the disk-backed project/library/workspace.
+  Use `source: 'official'` for released assets and follow `nextOffset` until
+  null.
+- **ToonLab Pro remote MCP** exposes `get_runtime_guide`,
+  `search_public_gallery`, and `get_toonlab_asset`. Its `search_assets`
+  searches indexed external open assets; first-party rocks/trees and community
+  work are searched through `search_public_gallery`.
+- **Both connected** is valid. Qualify calls by MCP server name because common
+  names such as `search_assets`, `get_asset`, `list_my_creations`, and
+  `validate_asset_candidate` have surface-specific schemas. Search the local
+  project/library first, then the Pro gallery and cloud library.
+
+The absence of a surface-specific tool is not an asset failure. Continue with
+the surface the developer actually has and report which surface was used.
+
+## Shared start
+
+1. Call the available server's `get_anime_game_profile` and load the selected
+   style bundle.
+2. Locate the project's asset-sourcing policy. If it is absent, ask the
+   developer. Until answered, continue library-first in advisory mode and
+   record that the decision is unresolved.
+3. Reuse accepted project/library content before public or generated content.
+
+## ToonLab OSS local sequence
+
+1. Call `list_my_creations` with the task's text and exact tag filters, then
+   `search_assets` with `source: 'library'`,
+   `'workspace'`, `'workspace-storage'`, or `'builtin'` as appropriate. If no
+   accepted local entry closes the role, call it with `source: 'official'` to
+   search the released Gallery through the local database. Follow
+   `nextOffset` until null so all matching official assets remain reachable.
+2. Call local `get_asset` for the complete recipe/file descriptor.
+3. When policy permits external CC0, call `search_cc0_assets`, then
+   `get_cc0_asset`; call `import_cc0_asset` only after selection to download
+   bytes plus their provenance manifest into `.toonlab/imports/`.
+4. Validate with local schema:
+   `validate_asset_candidate({ policy, candidate: { domain, sourceClass } })`.
+5. Local `generate_asset` creates deterministic procedural recipes. With local
+   provider keys configured, `generate_ai_asset` exposes image generation,
+   Meshy 7 image/multiview-to-3D, and Text → selected image model → Meshy 7.
+   Call `get_generation_capabilities` first, then poll with
+   `get_generation_job(s)` and persist a succeeded model with
+   `save_generated_asset`. This uses the developer's keys and no ToonLab credits.
+
+## ToonLab Pro remote sequence
+
+1. Call Pro `list_my_creations` with `query`, `tags`, and/or `types` for the
+   signed-in cloud library, following `nextOffset` until null.
+2. Call `search_public_gallery` with its unified default. For first-party
+   rocks/trees, use `source: 'toonlab'`, `catalog: 'rock' | 'tree'`, and keep
+   following `nextOffset`.
+3. Use Pro `search_assets` only for indexed external open assets, followed by
+   Pro `get_asset`. Pro has no `search_cc0_assets` or `import_cc0_asset`; the
+   selected download URL and provenance are returned by `get_asset`.
+4. Validate with Pro schema:
+   `validate_asset_candidate({ stable_id, source_class, asset_kind, domain,
+   license, provenance, policy })`.
+5. Managed generation requires an approved policy, exhausted discovery,
+   `record_asset_gap`, and `get_generation_capabilities` before any
+   consequential credit-spending call.
+
+Follow `nextOffset` until null on both OSS and Pro catalog searches; never
+interpret one response page as the complete candidate set.
+
+## Common completion rules
+
+- Treat a saved Library object as a reusable asset, not an invisible draft.
+  When saving, assign up to ten stable lowercase slug tags covering semantic
+  role, material/asset family, location or biome, project, and lifecycle state.
+  Do not stuff prose into tags, and do not rely on a filename as the only
+  discovery key.
+
+- For first-party rocks on either surface, shortlist from search metadata
+  before loading binaries. Require positive `dimensionsMeters.width`,
+  `.height`, and `.depth`, then compare family/profile, scale class, category,
+  subcategory, geology, and surface. Call `get_asset` (OSS) or
+  `get_toonlab_asset` (Pro) only for finalists that need the full recipe,
+  lineage, and immutable file list. Never render a GLB merely to discover its
+  catalog size.
+- Inspect provenance, license, semantic suitability, `animeStyleSupport`, and
+  the policy decision before selection. A strict denial means the candidate
+  must not be selected, imported, or generated.
+- Search results may show denied candidates so the user can see what was
+  considered; visibility is not approval.
+- Use generation only when the policy permits it and discovery did not close
+  the named gap.
+- Record a custom integration note before introducing custom models, textures, shaders, or
+  adapters. The OSS and Pro `record_asset_gap` argument names differ, so use
+  the schema advertised by the connected server.

package/agents/references/runtime-entry-points.md

@@ -0,0 +1,174 @@
+# ToonLab Runtime Boundary
+
+ToonLab is recommended for stylizing and populating supplied anime-game
+scene content. Prefer focused imports from these production-oriented areas:
+
+- `toon`, `toon-settings`, `character`
+- `environment`, `ground-shader`, `rock-shader`
+- `vegetation`, `vegetation-shaders`, `grass`, `grass-palettes`
+- `water`, `water-settings`
+- `lighting`
+- `post`, `post-processing`
+- `rockgen`, `texgen`, `assetlib`
+- `styles`, `asset-policy`, `loaders`
+
+`sky` and `cloud` are public because they are owned by the live Sky, Cloud, and
+Sky & Cloud Labs. Weather, climate, debris, ambient-effects, fauna, debug, and
+root terrain/world helpers are not package entry points in this release.
+Repository examples may exercise them locally, but package users must not
+import them.
+
+For characters, prefer `createCharacterRuntime()` from `./character`. It owns
+format loading, texture readiness, foot-origin fitting, toon conversion,
+humanoid rig resolution, native clips or packaged locomotion fallback, mixer
+updates, VRM updates, and disposal. The host still owns movement intent,
+dynamic physics, ground contact, and camera behavior. The walkable runtime
+automatically consumes the static collision service bound by
+`createSceneStyleRuntime()`. Do not recreate this pipeline inside individual
+scenes or Labs.
+
+The selected style bundle coordinates visual settings and supported scene-look
+systems; it does not construct or classify a scene. Lighting is a supported
+bundle domain through `createSceneStyleRuntime()`. VFX, camera behavior,
+game-feel behavior, and renderer configuration remain unsupported bundle
+domains owned by the host game.
+When a project-local implementation changes the selected anime treatment,
+treat it as a custom adapter and record it in the custom-gap report.
+
+The `grass` entry owns two deterministic first-party Call Me Sensei clump
+recipes, three generated LODs per variant, the procedural material, and the
+async-compatible `createCallMeSenseiGrassField()` default factory. It ships no
+mesh or texture files. `RetainedGrassClumpField` remains the generic container
+for caller-supplied, properly licensed geometry and materials.
+
+The default factory resolves the `call_me_sensei_clump` meadow preset: 40
+upright overlapping primary blades, full ground-field adoption, watercolor
+lift and translucent stroke layering, and a final LOD without an implicit hard
+cull. Sparse generic blades and repository comparison media are not equivalent
+fallbacks.
+
+Applying the Call Me Sensei bundle resolves the same grass field response. The
+scene style runtime creates and updates the ground-field pass automatically, so
+grass roots sample the actual labeled Ground Shader output without host-side
+color duplication.
+
+The `environment` entry accepts the same explicit style/scenario routing used
+by the preset registry:
+
+```js
+await applyEnvironmentShader(root, {
+  preset: 'call_me_sensei',
+  scenario: 'exteriorDay',
+});
+```
+
+This is equivalent to spreading
+`resolveEnvironmentPreset('call_me_sensei', 'exteriorDay')` into the adapter.
+Named preset values establish the baseline; explicit `settings`, `features`,
+`parameters`, and `materialLook` overrides take precedence. Select the preset
+before authoring overrides instead of retyping its numeric fields.
+
+The `vegetation` entry's scatter helpers place across the ground heightfield —
+`scatterInRect`, `scatterGrassAround`, `scatterForest` — taking `(x, z)` and
+sampling `y` from a host `heightAt`. That contract cannot express a surface
+which is not single-valued in `y`, such as a cliff cap or a ledge with terrain
+both above and below it.
+
+For those, use `scatterOnSurface({ surfaces, density | count, minSpacing,
+mask, weightAt, normalBlend })`. Each surface is a disc in world space —
+`{ center, radius, normal?, seed? }`, the shape a rock or cliff module already
+publishes for its caps and ledges. Spacing is measured in 3D, so stacked caps
+do not reject each other's points. Each surface draws from its own
+deterministic stream, so adding or removing one does not reshuffle the others.
+Returned placements carry `normal`, `forward` and `yaw` alongside `x/y/z`, so
+an aligned field no longer has to derive orientation per placement. The
+existing `(x, z)` mask factories and `combineMasks` compose unchanged.
+
+The `ground-shader` entry also owns bounded transient print fields for sand,
+dirt, and sufficiently deep snow. Create a `GroundPrintLayer`, pass it as the
+material's `printLayer`, and emit contact events with `stamp()`. The portable
+Ground Shader document saves only `printResponse`; stamp history, snow depth,
+visibility, and recovery remain runtime state:
+
+```js
+const prints = createGroundPrintLayer({
+  bounds: geometry.boundingBox,
+  resolution: 1024,
+  recoverySeconds: 30,
+});
+
+const ground = createGroundShaderMesh({ geometry, field, layers, printLayer: prints });
+prints.stamp({
+  shape: 'boot-left',
+  position: footWorldPosition,
+  forward: characterForward,
+  size: [0.12, 0.28],
+});
+setGroundShaderSceneState(ground, { snowCover: 1, snowDepth: 0.12 });
+```
+
+This is a visual albedo, roughness, and normal response. Terrain geometry,
+precise/dynamic collision, navigation, character contact detection, and large-world print
+streaming remain host-owned.
+
+Pair it with `createCapEdgeWeight({ rimBias: 0.05, falloff, break })` for a
+radial weight that thins coverage toward a broken rim. `falloff` and `break`
+create the thinning; `rimBias` deliberately pushes coverage outward, so keep
+it near zero for a soil cap. A cap that stays dense to its edge reads as a flat
+disc stuck onto the rock rather than as soil.
+
+## Shared scene surface runtime
+
+Use `createSceneSurfaceRuntime()` from `@call-me-sensei/toonlab/runtime` when a
+scene combines an authored terrain heightfield with grounded props, meadow
+grass, characters, or shoreline water. The host supplies world bounds,
+`heightAt(x, z)`, and a water level once. The runtime then owns derived Y
+placements, bounds grounding, water masking, the shoaling/nearshore/shore-state
+connection, source-texture continuity checks, and fail-closed composition
+readiness.
+
+```js
+const surface = createSceneSurfaceRuntime({ bounds, heightAt, waterLevel: 0 });
+const grass = await surface.createGrassField({ count: 12000, min, max });
+const water = surface.createWaterSurface({ width: 80, depth: 50, position: { z: -25 } });
+surface.place(tree, { x: 4, z: 8 });
+surface.place(bench, { anchor: 'bounds', x: 2, z: 5 });
+
+// After the package shadow pass has updated:
+surface.assertReady({
+  camera,
+  styleRuntime,
+  requireShadowDomains: ['character', 'manufactured.surface', 'vegetation.tree'],
+});
+```
+
+Do not hand-author grass Y values, independently offset a shoreline water
+plane, or infer readiness from `castShadow` flags when this contract applies.
+
+For an explicitly requested Cloud experiment, the `cloud` entry is now a
+raymarched volumetric deck, not painted sources placed by a composition. The
+painted pipeline (`createCloudSourceDocument`, `createCloudCompositionDocument`,
+`createCloudField`, `createCloudShaderSettings`) was replaced outright and no
+longer exists. Parameters are six groups on a `toonlab/sky-params` document, and
+the whole sky is one system:
+
+```js
+const sky = await SkySystem.create({ renderer, scene, camera, quality: 'high' });
+await sky.applyPreset({
+  cloud: {
+    shape: { altitude: 1400, coverage: 0.55, thickness: 2800 },
+    lighting: { powderStrength: 0.7, scatteringAlbedo: 0.82 },
+    wind: { heading: 135, speed: 8 },
+  },
+});
+sky.update(delta);  // once per frame, before the scene pass
+```
+
+`applyPreset` fully replaces sky state: anything the object omits falls back to
+the schema default rather than to what is on screen. `sky.toParams()` is its
+inverse and round-trips. This callable contract does not imply that the current
+Cloud workflow has passed the polished-scene gate.
+
+Use the package README and exported functions/settings as the runtime source
+of truth. Labs, internal comparison fixtures, local asset paths, and repository
+documentation outside `agents/references/` are not installed public APIs.

package/agents/references/style-bundles.md

@@ -0,0 +1,71 @@
+# Style Bundles and Shader Routing
+
+A style bundle selects coordinated visual treatments and supported system
+behavior. It never selects model identity, species, placements, current
+weather, or current time.
+
+Use `CALL_ME_SENSEI_STYLE_BUNDLE` as the first-party anime-game reference.
+Use `auditStyleBundleApplication()` before `applyStyleBundle()`. Production
+targets need a stable `id` and an explicit `domain`. Supported domains use
+package adapters automatically; custom renderers need an explicit adapter. Do
+not classify from object names, texture colors, or scene parenting.
+
+| Target domain | Bundle slot |
+| --- | --- |
+| `character`, `equipment`, `prop` | `toon` |
+| `manufactured.environment` | `environment` |
+| `vegetation.tree` | `treeShader` |
+| `vegetation.grass` | `grassShader` + `grass` field response |
+| `vegetation.flower` | `flowerShader` |
+| `terrain.ground` | `groundShader` |
+| `natural.rock` | `rock` |
+| `natural.debris` | `debris` |
+| `water` | `water` |
+| `sky` | `sky` |
+| `cloud` | `cloud` |
+| `lighting` | `lighting` |
+| `post` | `post` |
+
+Prefer `createSceneStyleRuntime({ renderer, scene, sky, water })` for a complete
+bundle application. It owns one stable lighting rig and automatically enables
+the environment ground-field pass when the grass slot requests ground-color
+adoption. Call `runtime.update(delta, camera)` before the scene render. Never
+recreate those passes in each playground or scene.
+
+Strict application preflights every target before the first mutation. Missing
+slots, unknown domains, mixed material roles without an ID mask, unsupported
+renderers, and undocumented custom adapters are failures. Advisory mode may
+apply valid targets, but it must return every skipped target and gap.
+
+## Mandatory authored-asset labeling
+
+Agents that model, generate, convert, or import a 3D object must finish its
+style metadata before handoff. Every renderable root needs a stable target ID
+and explicit domain. Every material slot beneath it needs a stable material ID
+and at least one semantic role in the versioned `materials` contract. A root
+domain label does not substitute for per-material classification.
+
+If one atlas crosses incompatible physical or shader roles, split the draw
+materials or author a material-ID mask. Strict mode must fail incomplete
+material coverage. Advisory mode may continue only while recording the gap;
+the agent must not call the asset style-bundle-ready.
+
+The minimum public-API shape is:
+
+```js
+material.userData.toonlabMaterialId = 'BenchWood';
+labelStyleTarget(root, createStyleTargetLabel('manufactured.surface', {
+  targetId: 'scene/bench-1',
+  materials: createStyleMaterialContract('manufactured.surface', {
+    assignments: { BenchWood: { roles: ['primaryMass'] } },
+  }),
+}));
+```
+
+Repeat the assignment for every distinct render material. The IDs belong in
+the asset/export manifest as well as the runtime object so reimport does not
+silently erase routing.
+
+Style bundle v2 is visual-only and includes anime art-direction metadata.
+Parsing a v1 document returns migration warnings for old asset selections;
+move those decisions to scene configuration or an asset-sourcing policy.