@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/agents/codex/AGENTS.md

@@ -1,161 +1,114 @@
 # ToonLab Agent Guide
 
-Use this file when helping a developer build an anime-style game, character,
-or environment with ToonLab's runtime library in their own Three.js app.
-
-## Anime-Game Product Contract
-
-- ToonLab is specifically an anime-game toolkit, not a generic stylization
-  library. Read `agents/references/anime-art-direction.md` before making
-  visual, shader, material, or asset decisions.
-- Load the selected bundle's `artDirection` and treat it as authoritative.
-  Call Me Sensei is the first-party coordinated reference.
-- Never accept unintended photorealism, generic low-poly styling, undirected
-  cartoon rendering, or untreated PBR materials as a finished ToonLab result.
-- If supported shaders or approved assets are insufficient, document the
-  customization and why your project needs it.
-
-## Runtime Boundary
-
-- `@call-me-sensei/toonlab` is primarily a runtime library for applying
-  Three.js shaders, stylized materials, focused vegetation/water, settings,
-  and preset documents to supplied scene content.
-- Prefer public package imports such as `@call-me-sensei/toonlab/toon`,
-  `@call-me-sensei/toonlab/environment`, `@call-me-sensei/toonlab/water`,
-  `@call-me-sensei/toonlab/vegetation`, `@call-me-sensei/toonlab/post`,
-  `@call-me-sensei/toonlab/styles`,
-  `@call-me-sensei/toonlab/texgen`, and `@call-me-sensei/toonlab/rockgen`.
-- Use `@call-me-sensei/toonlab/sky` and `/cloud` for the live Sky, Cloud, and
-  Sky & Cloud Lab contracts. Weather, Climate, ambient effects, and fauna are
-  not public package entry points in this release.
-- Use `@call-me-sensei/toonlab/vegetation-shaders` and
-  `@call-me-sensei/toonlab/grass-palettes` when a consumer needs only those
-  focused contracts. They are the same bindings exposed by the vegetation and
-  root barrels.
-- Keep root imports lightweight in examples. Import only the feature subpath a
-  developer needs.
-- Public export status and product maturity are different. Toon,
-  Environment/Ground/Rock, Tree/Grass/Flower, Water on a host-authored
-  footprint/shore/bed, Post, Gallery/MCP asset workflows, loaders, portable
-  settings, Sky/Cloud, and qualified focused generators are the recommended
-  path. Whole terrain/biome/coast/cliff construction,
-  automatic set dressing, and cross-system world assembly are experimental.
-- ToonLab's labs, sample assets, local manifests, screenshots, captures, and
-  app routes are examples. Do not treat them as part of the runtime API or copy
-  their local asset assumptions into user apps.
-- The host app owns scene layout and major geometry, asset placement, cameras,
-  collision, asset loading, decoder hosting, storage, routing, persistence,
-  collaboration, and final art direction. Renderer construction stays
-  host-owned, while the public renderer helper and scene style runtime apply
-  reversible Call Me Sensei renderer, lighting, probe, and shadow settings.
-- VFX, camera, game-feel, and renderer selection are not style-bundle domains.
-  Treat project-local implementations as custom adapters and record a gap when
-  they affect the selected look. Lighting is a supported bundle domain.
-
-## Usage Rules
-
-- Use the README and docs pages first; feature skills in `agents/skills/codex/`
-  are short usage guides for public runtime APIs.
-- For existing-scene or multi-system integration, start with the `game-dev`
-  skill (boundary, frame-loop contract, task→skill routing). When sourcing or generating
-  assets, use the `asset-sourcing` skill. Feature-detect the connected ToonLab
-  OSS local and/or ToonLab Pro remote MCP surface before calling tools; their
-  overlapping tool names have different discovery roles and schemas.
-  First-party rock search must shortlist from meter dimensions and taxonomy;
-  do not load or render catalog GLBs merely to determine their size.
-- Whole-world and natural-cliff construction skills are not shipped in the npm
-  package. Prefer bounded work on an existing terrain, asset family,
-  vegetation field, or water body.
-- For any style-aware construction, use `style-presets` to record the intended
-  selector and distinguish neutral defaults from domains that already default
-  to Call Me Sensei. Before visual approval or reporting a package gap, use
-  `visual-verification` for readiness, isolation, multi-view, measurement, and
-  outlier checks. These routes apply to every agent integration, not only Codex
-  or Claude.
-- ToonLab materials are TSL/NodeMaterial-first for Three.js WebGPU with WebGL2
-  fallback through the same TSL path. Do not guide developers toward raw GLSL,
-  `ShaderMaterial`, or classic WebGL-only forks for ToonLab features.
-- Keep developer examples focused on documented settings, preset documents,
-  public constructors/helpers, and app-owned Three.js objects.
-- Keep artifact scope explicit: Shader Labs author IP profiles, Asset Labs
-  author geometry/material data, and Water Lab authors a focused runtime
-  system preset with embedded shader controls. Sky, Cloud, and Sky & Cloud are
-  live focused authoring surfaces. Vegetation is one shared
-  implementation family with separate Tree, Grass, and Flower shader profiles;
-  their Generation Labs own geometry/material data. The public package ships
-  tree construction and shader capability, not predefined tree assets. Search
-  reviewed authored tree recipes through MCP; use `StylizedTree` or
-  `BranchTree` to instantiate or deliberately author them. Repository species
-  work is experimental and must not be presented as supported. Ground is a
-  separate shader domain. Scene weather,
-  lighting, camera, interactions, and complete Sky/Cloud composition stay
-  host-owned or experimental.
-- For style-bundle, multi-shader, or arbitrary-asset work, read
-  `agents/references/style-bundles.md` first. A bundle selects coordinated treatments;
-  explicit asset labels select rendering destinations; scene state selects
-  current conditions. Inventory and label every renderable root and material.
-  Every newly modeled, generated, or imported material slot requires a stable
-  ID and valid semantic role in the versioned material contract. A root domain
-  label is not sufficient for a multi-material asset; missing roles and mixed
-  atlases without a split or ID mask block strict handoff.
-  Character anatomy, clothing, held weapons, and worn hero accessories
-  normally route to toon; manufactured props, vegetation, rocks/debris,
-  water/sky, and VFX retain their owning runtimes. For an imported manufactured
-  prop, call `proposeManufacturedStyleTargetLabel()` first, review every issue,
-  provide explicit `materialOverrides` for unresolved slots, then call
-  `applyManufacturedStyleTargetLabelProposal()`. Never collapse assisted
-  results into the automatic success rate.
-- Report unknown domains and material roles, mixed atlases without masks,
-  unsupported transparency, and custom-renderer exemptions. Never silently
-  infer a production-safe route from names, texture colors, or scene
-  parenting. Preserve asset identity and runtime conditions when changing
-  style.
-- Local style bundle creation, validation, serialization, parsing, and
-  resolution are OSS `/styles` APIs and require no database. Hosted storage
-  and `fetchStyleBundle` are optional. Scene discovery remains explicit;
-  manufactured assets have a conservative proposal/review/apply labeling path,
-  and strict bundle application reconciles declared roles against live slots
-  before the first mutation.
-- New bundles use `treeShader`, `grassShader`, `flowerShader`, and
-  `groundShader`. V1 `vegetationShader`, `tree`, `grass`, and `flowers`
-  selections are migration inputs only and never serialize into v2. Do not
-  serialize asset recipes, tree geometry, scatter, or live wind/weather
-  into shader slots.
-- Treat `call_me_sensei` as the first-party reference bundle. Optimize the
-  canonical domain implementations for the best coordinated result and apply
-  the completion gate in `agents/references/style-bundles.md`. Assigning the same
-  style id to every slot is not completion, and compatibility flattening for
-  incomplete assets must not define the signature look.
-- For sourcing or generation, read
-  `agents/references/mcp-asset-discovery.md` and
-  `agents/references/asset-sourcing-policy.md`. Reuse an
-  accepted asset first. If a procedural family has an approved stylized base
-  set and passed the reliability gate, generate directly and skip gallery
-  search. Otherwise use curated CC0, then properly attributed CC-BY; reserve
-  image-to-3D for a named remaining gap. Preserve base-set version, recipe,
-  seed, domain/material labels, license provenance, and the Call Me Sensei
-  verification result. Pro may author/review base sets; OSS consumes portable
-  artifacts without a database.
-- For Sky/Cloud and Water work, `.settings` is the portable authored baseline and
-  `.renderedSettings` is the current composition. Give Lighting, Weather, and
-  other transient owners unique `setSceneOverrideLayer` ids and clear only the
-  same id; never export composed scene state.
-- In a composed-world test, use the public Lighting bundle slot and scene style
-  runtime for the coordinated sun, sky probe, and shared shadow contract. Keep
-  host-owned Weather and any custom local-light adapters coordinated with Sky,
-  Water, and vegetation scene inputs.
-- Sky documents contain exactly 46 portable art fields. Radius and compile-time
-  quality are not portable: named tiers use 2/3/4 cloud octaves, custom quality
-  accepts `{ cloudOctaves: 1..5 }`, and `sky.setQuality()` rebuilds the material.
-  Water quality is chosen when constructing/replacing `WaterSurface`, not via
-  `applySettings()`.
-- Do not depend on ToonLab sample assets, generated manifests, or lab-only
-  model/environment discovery.
-- Keep these downloadable resources focused on runtime usage.
-
-## Developer Verification
-
-- For consumer apps, run that app's normal typecheck, test, build, and visual
-  smoke checks.
-- For generated rock assets, use a fixed seed and compare the output your app
-  expects.
+Use ToonLab's public runtime to develop the game the user requested. Build the
+host game systems when needed; “host-owned” means your application implements
+that part, not that the task must be refused or called an experiment. Preserve
+existing gameplay and layout unless the request authorizes changing them.
+
+## Find the installed contract
+
+Resolve `@call-me-sensei/toonlab` in this project and read its `package.json`
+version and export map. In this guide and the feature skills, `agents/...` and
+`NPM-LIBRARY.md` are relative to that package root, normally
+`node_modules/@call-me-sensei/toonlab/`, not the game repository root. In a
+workspace with hoisted dependencies, resolve the installed location first.
+
+Start with `NPM-LIBRARY.md`, `agents/references/runtime-entry-points.md`, and the
+`game-dev` skill. Read other skills only for the systems the task uses. The
+installed package has the supported guides and references; a source checkout,
+Lab UI, Pro account, and generative AI are not prerequisites for building a game.
+Do not overwrite the game's existing agent instructions when installing this guide.
+
+## Divide responsibilities correctly
+
+| Application work | ToonLab support |
+| --- | --- |
+| Game rules, input, camera, UI, objectives, spawning, scene layout, navigation, dynamic physics, networking, persistence | Host code composed with the runtime; do not invent ToonLab APIs for these |
+| Renderer construction, resize, frame loop, shutdown | `renderer` helpers and scene-style configuration; use Three's `WebGPURenderer` for TSL, including its WebGL2 fallback |
+| Character loading, rig/clips, conversion, animation update/disposal | `createCharacterRuntime()`; `createWalkableCharacterRuntime()` connects locomotion and grounding to host movement/physics |
+| Terrain-bound placement, grass, shore and water-bed coordination | `createSceneSurfaceRuntime()` when the host supplies a heightfield |
+| Labeled static blockers | `createSceneStyleRuntime().collision`; use explicit collision metadata or the Rapier adapter where needed |
+| Coordinated lighting, sky inputs, ground field and shared shadows | `createSceneStyleRuntime()` and the public `lighting` domain |
+| Materials, vegetation, water, sky/cloud, post and procedural assets | Focused exports listed in `agents/references/runtime-entry-points.md` |
+
+A hand-built level is valid application work. Reliable automatic world layout,
+terrain/geology synthesis, navigation, camera controllers, gameplay VFX and the
+experimental species engine are not promises of the npm package. Do not import
+repository-only implementations or turn a Lab route into a runtime dependency.
+
+## Build in useful increments
+
+For a new game, make a playable vertical slice first: controls, movement,
+collision, camera, one objective, and restart. Then apply the selected art
+direction and add assets. For an existing game, integrate the requested domains
+without replacing its renderer or update loop unnecessarily. The `game-dev`
+skill gives the integration order and the frame ownership contract.
+
+Use focused package imports. Choose the selected bundle's treatment explicitly;
+Call Me Sensei is the first-party default when the user has not chosen another.
+Its bundle ID is `call-me-sensei`; many domain preset/style selectors instead
+use `call_me_sensei`. Use the documented selector for each API.
+
+Use `style-presets` before style-aware construction.
+For anime treatment, read `agents/references/anime-art-direction.md` and
+`agents/references/style-bundles.md`. Preserve source PBR maps and material
+identity. Realistic rock maps are valid asset inputs and may also be the user's
+requested output; do not confuse them with an accidentally unstyled anime scene.
+
+Label style targets by domain and give every material slot a stable material
+ID and semantic role. A root-only label is incomplete for a multi-material
+asset. Strict mode blocks incomplete coverage. Use the manufactured-material proposal/review/apply
+helpers for imported props. Report automatic and assisted results separately.
+Do not infer a physical material solely from its color or filename. Split mixed
+atlases or supply the required mask. Strict style application must reject
+incomplete coverage before mutation; advisory results must disclose gaps.
+
+Apply scene-wide styles through `styleRuntime.apply(...)`. It manages the
+lighting, renderer, shadow, and collision integrations as well as material
+transactions. Use the lower-level `applyStyleBundle()` only when the app owns
+those integrations deliberately. A `createStyleTarget()` descriptor alone is
+not durable labeling: use `labelStyleTarget()` for scene-label discovery.
+
+## Assets and MCP
+
+Use `asset-sourcing` when discovering/importing assets or requesting generation.
+Inspect the connected server's tool schemas: local and Pro tools with the same
+name can mean different things. Follow the project's actual policy; the strict
+acceptance fixture is not a universal rule for every game.
+
+Reuse project/Library assets, shortlist Gallery results from metadata, then
+retrieve selected artifacts. Preserve IDs, license, provenance, dimensions,
+recipe and seed. First-party rock dimensions and taxonomy support shortlisting
+without rendering GLBs just to measure them. Use returned IDs and public labels;
+internal production identifiers are not product names.
+
+MCP also creates and mutates portable Lab documents. Call `list_live_labs`,
+`get_lab_features`, then `create_lab_document`; its result wraps the portable
+JSON in `document`. Save through the relevant Library tool when persistence is
+part of the task. A valid document does not guarantee its preview or generated
+asset has passed visual review.
+
+Local `generate_asset` is procedural; local provider work uses
+`generate_ai_asset` and the user's keys. Pro `generate_asset` spends separately
+purchased credits. A free Pro month grants MCP access without AI credits.
+Generation capability is not permission to spend; follow existing authorization
+and the server's sourcing-policy requirements. Keep provider keys out of source
+and portable documents.
+
+## Verify and hand off
+
+Test through the app's real input and render path. Run its applicable checks,
+wait for asset/render readiness, inspect the console, and capture the requested
+views. Test restart/teardown and verify that listeners, resources, and animation
+loops are not duplicated. Each system has one update owner and each frame has
+one final render owner. Read `visual-verification` for a visual review.
+
+For a heightfield scene, run the shared surface audit after the required passes
+have rendered. Run `styleRuntime.collision.assertReady()` before relying on its
+blockers. Test actual movement around representative obstacles. Include LOD,
+shadow and shoreline views only when those systems are used.
+
+Record missing package capabilities and material-policy exceptions when they
+matter to the requested result. Ordinary host gameplay code is not a ToonLab
+failure. Report what works, what was tested, and any remaining limitation;
+never describe a build alone as a finished or visually approved game.

package/agents/cursor/toonlab.mdc

@@ -8,8 +8,10 @@ alwaysApply: true
 
 - Treat `node_modules/@call-me-sensei/toonlab/agents/codex/AGENTS.md` as the
   shared developer guide.
-- Help developers stylize and populate supplied scenes with ToonLab runtime,
-  Gallery, and MCP workflows. Do not promise one-shot world construction.
+- Build the requested host game or integrate ToonLab into supplied scenes.
+  For new games, use the game-dev skill and start with movement, collision,
+  one objective and restart. Host-owned gameplay and layout are authorized
+  development work when requested; ToonLab does not generate finished worlds.
 - Prefer package subpath imports such as `@call-me-sensei/toonlab/toon`,
   `@call-me-sensei/toonlab/water`,
   `@call-me-sensei/toonlab/vegetation-shaders`,
@@ -20,7 +22,9 @@ alwaysApply: true
   `ShaderMaterial`, or classic WebGL-only forks for ToonLab features.
 - Treat ToonLab labs, sample assets, screenshots, captures, and generated
   manifests as examples, not runtime API.
-- Use `agents/skills/` as reference material for feature-specific workflows.
+- Resolve `agents/` references from the installed package root, including
+  when a skill is copied. Use `agents/references/game-lifecycle.md` for update
+  ownership and cleanup, and `agents/skills/` for focused workflows.
 - Material metadata is a blocking modeling deliverable. Every modeled,
   generated, converted, or imported renderable needs a stable target ID and
   domain; every material slot needs a stable material ID and semantic role in

package/agents/examples/game-foundation.mjs

@@ -0,0 +1,104 @@
+// Copyable host-game example, not a ToonLab export. Requires a bundler and canvas.
+import * as THREE from 'three';
+import { WebGPURenderer } from 'three/webgpu';
+import {
+  CALL_ME_SENSEI_STYLE_BUNDLE,
+  createSceneStyleRuntime,
+  createStyleMaterialContract,
+  createStyleTargetLabel,
+  labelStyleTarget,
+} from '@call-me-sensei/toonlab/styles';
+import { createCollisionMetadata } from '@call-me-sensei/toonlab/world-collision';
+
+export async function startGame({ canvas, onState = () => {} }) {
+  const renderer = new WebGPURenderer({ canvas, antialias: true });
+  try { await renderer.init(); }
+  catch (error) { renderer.dispose(); throw error; }
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color('#b7d8ec');
+  const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
+  camera.position.set(8, 10, 12);
+  camera.lookAt(0, 0, 0);
+  const objects = [];
+  function add(id, domain, role, geometry, color, position, collision) {
+    const material = new THREE.MeshStandardMaterial({ color });
+    material.userData.toonlabMaterialId = id;
+    const mesh = new THREE.Mesh(geometry, material);
+    mesh.position.fromArray(position);
+    labelStyleTarget(mesh, createStyleTargetLabel(domain, {
+      targetId: id,
+      materials: createStyleMaterialContract(domain, { assignments: { [id]: { roles: [role] } } }),
+      ...(collision ? { collision } : {}),
+    }));
+    scene.add(mesh); objects.push(mesh);
+    return mesh;
+  }
+  const floor = add('floor', 'terrain.ground', 'ground', new THREE.PlaneGeometry(14, 14), '#a3be76', [0, 0, 0]);
+  floor.rotation.x = -Math.PI / 2;
+  add('blocker', 'natural.rock', 'rock', new THREE.BoxGeometry(2, 2, 2), '#b4aea0', [0, 1, 0]);
+  const player = add('player', 'character', 'costume', new THREE.CapsuleGeometry(0.3, 0.8, 4, 8), '#bd6182', [-3, 0.7, 2]);
+  const goal = add('goal', 'prop', 'metal', new THREE.SphereGeometry(0.25, 12, 8), '#f5c45a', [3, 0.6, -3], createCollisionMetadata('none'));
+  scene.updateMatrixWorld(true);
+  const styleRuntime = createSceneStyleRuntime({ renderer, scene });
+  try {
+    await styleRuntime.apply(CALL_ME_SENSEI_STYLE_BUNDLE, { discovery: 'scene-labels', mode: 'strict', watch: false });
+    styleRuntime.collision.assertReady();
+  } catch (error) {
+    await styleRuntime.dispose();
+    for (const mesh of objects) { mesh.geometry.dispose(); mesh.material.dispose(); }
+    renderer.dispose(); throw error;
+  }
+
+  const keys = new Set();
+  const listeners = new AbortController();
+  let won = false, lastTime = null, disposed = false;
+  function restart() {
+    player.position.set(-3, 0.7, 2); goal.visible = true; won = false;
+    keys.clear(); lastTime = null; onState({ won });
+  }
+  window.addEventListener('keydown', (event) => {
+    if (/^(INPUT|TEXTAREA|SELECT)$/.test(event.target?.tagName) || event.target?.isContentEditable) return;
+    if (['KeyW', 'KeyA', 'KeyS', 'KeyD', 'ArrowUp', 'ArrowLeft', 'ArrowDown', 'ArrowRight'].includes(event.code)) {
+      event.preventDefault(); keys.add(event.code);
+    }
+    if (event.code === 'KeyR') restart();
+  }, { signal: listeners.signal });
+  window.addEventListener('keyup', (event) => keys.delete(event.code), { signal: listeners.signal });
+  window.addEventListener('blur', () => { keys.clear(); lastTime = null; }, { signal: listeners.signal });
+  function resize() {
+    const width = Math.max(canvas.clientWidth, 1), height = Math.max(canvas.clientHeight, 1);
+    renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+    renderer.setSize(width, height, false); camera.aspect = width / height; camera.updateProjectionMatrix();
+  }
+  window.addEventListener('resize', resize, { signal: listeners.signal });
+  resize(); restart();
+  renderer.setAnimationLoop((time) => {
+    const delta = lastTime === null ? 0 : Math.min((time - lastTime) / 1000, 0.05);
+    lastTime = time;
+    if (!won) {
+      const x = Number(keys.has('KeyD') || keys.has('ArrowRight')) - Number(keys.has('KeyA') || keys.has('ArrowLeft'));
+      const z = Number(keys.has('KeyS') || keys.has('ArrowDown')) - Number(keys.has('KeyW') || keys.has('ArrowUp'));
+      const length = Math.hypot(x, z) || 1;
+      player.position.x = THREE.MathUtils.clamp(player.position.x + x / length * delta * 3, -6.5, 6.5);
+      player.position.z = THREE.MathUtils.clamp(player.position.z + z / length * delta * 3, -6.5, 6.5);
+      styleRuntime.collision.world.resolve(player.position, 0.3);
+      if (Math.hypot(player.position.x - goal.position.x, player.position.z - goal.position.z) < 0.65) {
+        won = true; goal.visible = false; onState({ won });
+      }
+    }
+    styleRuntime.update(delta, camera);
+    renderer.render(scene, camera);
+  });
+  return {
+    restart,
+    // Read-only telemetry is useful for a host smoke test and debugging.
+    get state() { return { won, player: player.position.toArray(), collision: styleRuntime.collision.report }; },
+    async dispose() {
+      if (disposed) return; disposed = true;
+      renderer.setAnimationLoop(null); listeners.abort();
+      await styleRuntime.dispose();
+      for (const mesh of objects) { mesh.geometry.dispose(); mesh.material.dispose(); }
+      renderer.dispose();
+    },
+  };
+}

package/agents/references/game-lifecycle.md

@@ -0,0 +1,57 @@
+# Game lifecycle and update ownership
+
+The application owns the frame loop. Adding ToonLab should not create competing
+loops, duplicate physics steps or double animation updates. For a new game,
+author the host systems as part of the requested work. For integration, reuse
+the existing owners.
+
+## One owner per system
+
+| System | Owner and update |
+| --- | --- |
+| Input, game rules and dynamic physics | Host; use a fixed physics timestep where the physics engine requires it |
+| Character mixer/VRM | `character.update(delta)`; if a walkable runtime owns that character, let it perform the update instead |
+| Camera | Host; update after movement and before camera-dependent scene passes |
+| SkySystem | Host calls `sky.update(delta)` once; binding it to scene-style does not animate it |
+| Lighting, shared shadows, ground field | `styleRuntime.update(delta, camera)` |
+| Grass and other focused objects | Call their documented updates once, after the ground field they sample is current |
+| WaterSurface | Host calls `water.update(delta, camera)` once |
+| Final scene render | `post.render(delta)` when a post pipeline owns rendering; otherwise `renderer.render(scene, camera)` |
+
+Check ownership in the actual runtime you instantiate. Do not call a lower
+level character, physics or material update again when an owning controller
+already does it. Update independent transient conditions through uniquely
+named layers; clear only the owner's layer when it ends.
+
+For a scene using these systems, a typical order is host movement/physics,
+camera, sky, scene-style passes, grass/other animated content, water, then the
+final render. Clamp the resumed frame delta and reset held keys on focus loss.
+Make pause and restart explicit gameplay states rather than spawning new loops.
+
+## Renderer and readiness
+
+Create Three's `WebGPURenderer`, await `renderer.init()`, and use TSL-compatible
+materials. Its WebGL2 fallback is not the classic `WebGLRenderer` material path.
+Use `configureToonLabRenderer()` only when the scene-style runtime does not
+already own that configuration. Pick a device-appropriate pixel ratio and
+quality profile; measure before increasing shadow, cloud or water quality.
+
+Await model/texture and scene application promises. Render the required passes
+before calling the surface readiness audit. Validate collision registration and
+probe movement against real blockers. A flag such as `castShadow` or a stable
+triangle count is useful evidence, but neither proves the final image is valid.
+
+## Resize and shutdown
+
+On resize, update the camera projection, renderer size and any explicitly sized
+post/target resources. Use the renderer's actual drawing-buffer size for pixel
+budgets. On shutdown stop the animation loop and listeners, then await
+`styleRuntime.dispose()` before disposing the host objects it styled. Dispose
+each character, grass field, water, sky and post pipeline through its owner;
+scene-style does not transfer ownership of supplied systems. Release acquired
+asset handles and caller-owned textures only after their final consumer ends.
+
+The copyable `agents/examples/game-foundation.mjs` demonstrates a flat blockout
+with movement, labeled static collision, a collectible and restart. It makes no
+claim to provide dynamic physics, navigation or finished art. Add those host
+systems when the game requires them, and qualify them through real gameplay.

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

@@ -11,6 +11,8 @@ scene content. Prefer focused imports from these production-oriented areas:
 - `post`, `post-processing`
 - `rockgen`, `texgen`, `assetlib`
 - `styles`, `asset-policy`, `loaders`
+- `renderer`, `runtime`, `world-collision`, `official-catalog`, `scene-operations`
+- `react` when using the optional React/React Three Fiber peers
 
 `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
@@ -173,3 +175,27 @@ responsibilities.
 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.
+
+## Realistic rock materials
+
+The `rockgen` entry exposes `NATURAL_ROCK_SURFACE_PROFILES`,
+`NATURAL_ROCK_MAP_ROLES`, `createNaturalRockMapData`,
+`resolveNaturalRockProjection`, and `createNaturalRockSurfaceSpecification`.
+Use these for deterministic realistic surface maps on procedural or edited
+rocks. The host owns texture creation and material assignment. Preserve saved
+surface recipes and geometry identities. Composite profiles require authored
+semantic regions; do not substitute a homogeneous map or invent a residual bake.
+
+## Host game and lifecycle
+
+Building gameplay, cameras, level layout and UI is ordinary host work when the
+user requests a new game. “Host-owned” does not prohibit the agent from doing
+that work. Read `agents/references/game-lifecycle.md` for exact update owners.
+The style runtime coordinates lighting, shadow and ground-field passes; it
+does not advance bound sky, water, grass or character objects automatically.
+
+Discover current sky fields through `SKY_PARAMS_FIELD_SCHEMA` and
+`SKY_PARAMS_SCHEMA_VERSION`; modern `SkySystem` uses `toonlab/sky-params`.
+`createSkySettings` and `StylizedSky` refer to the compatibility renderer and
+its distinct settings contract. Do not mix those schemas or hardcode a field
+count from older guides.

package/agents/references/style-bundles.md

@@ -30,7 +30,10 @@ 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.
+recreate those passes in each playground or scene. Sky, Water, grass and
+character animation retain their own update owners; see
+`agents/references/game-lifecycle.md`. When post is bound, use its final
+`render(delta)` path rather than bypassing it.
 
 Strict application preflights every target before the first mutation. Missing
 slots, unknown domains, mixed material roles without an ID mask, unsupported

package/agents/skills/claude/asset-sourcing/SKILL.md

@@ -3,6 +3,10 @@ name: asset-sourcing
 description: Help agents source anime-game-ready models, textures, and presets through policy-aware ToonLab MCP discovery, provenance, supported shaders, and explicit custom-gap reporting.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Asset Sourcing
 
 Use this skill when a developer needs an asset — a model, texture, HDRI,
@@ -66,7 +70,7 @@ scene-kit role.
    Never regenerate or re-download something already available.
 3. **Use an approved procedural family only when policy permits it.** Discover
    approved families through MCP, then use their focused runtime such as
-   `@call-me-sensei/toonlab/vegetation`, `rockgen`, `debrisgen`, or `texgen`.
+   `@call-me-sensei/toonlab/vegetation`, `rockgen` or `texgen`.
    This is the direct route only when the requested family has an approved,
    versioned stylized base set and passes the policy/review gate described in
    `agents/references/asset-sourcing-policy.md`. Preserve base-set version, generator version,
@@ -97,9 +101,8 @@ scene-kit role.
    generation capability, polling, and save tools; follow the advertised schema.
 6. **Author stable visual profiles in code.** Post profiles can be generated
    deterministically through `@call-me-sensei/toonlab/post`; other stable
-   shader profiles resolve through the selected style bundle. Lighting, VFX,
-   camera, and game-feel generation are host-owned or pre-beta in the public package and
-   are not advertised by the packaged MCP server.
+   shader profiles resolve through the selected style bundle. Lighting is a supported public runtime and bundle slot. VFX, camera and
+   game-feel implementations remain host-owned; do not invent package APIs.
 
 Persist anything worth keeping with `save_creation` (or write the JSON into
 the repo); `.toonlab/creations/` is the shared surface labs and later

package/agents/skills/claude/environment/SKILL.md

@@ -3,6 +3,10 @@ name: environment
 description: Help developers use ToonLab environment shading, lighting rigs, ambient probes, reflections, fog, cloud shadows, or vertex AO in an app.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Environment
 
 Use this skill when a developer wants stylized scene materials, material-role