@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/NPM-LIBRARY.md

@@ -1,7 +1,7 @@
 # ToonLab npm library guide
 
 This guide is included in `@call-me-sensei/toonlab`. It is the package-first
-reference for version 0.4.21 and does not require access to the source
+reference for version 0.4.23 and does not require access to the source
 repository.
 
 ## Install
@@ -67,13 +67,13 @@ release. A one-asset Node rock annotation compiler is also repository-only.
 The npm artifact contains four supported layers:
 
 1. The JavaScript runtime and TypeScript declarations for the public imports.
-2. Text-only agent guides, prompts, references, and paired Codex/Claude skills
+2. Text-only agent guides, prompts, references, a copyable game example, and paired Codex/Claude skills
    under `agents/`.
 3. The `toonlab` manifest audit CLI and `toonlab-mcp` local stdio MCP server.
 4. The local MCP database/catalog support required for Library and asset
    discovery workflows.
 
-It does not contain the ToonLab website, Lab application UIs, examples,
+It does not contain the ToonLab website, Lab application UIs, repository demo applications,
 screenshots, models, textures, or other binary media. Optional public fixtures
 are identified by immutable `https://assets.toonlab.io` metadata rather than
 being bundled. Authored tree recipes are assets too: the reviewed public tree
@@ -115,8 +115,12 @@ await look.apply(CALL_ME_SENSEI_STYLE_BUNDLE, {
 
 renderer.setAnimationLoop(() => {
   const delta = clock.getDelta();
+  sky?.update(delta);
   look.update(delta, camera);
-  renderer.render(scene, camera);
+  // Update host-owned grass/characters here if this scene uses them.
+  water?.update(delta, camera);
+  if (post) post.render(delta);
+  else renderer.render(scene, camera);
 });
 ```
 
@@ -124,36 +128,91 @@ The host application still owns renderer creation, geometry and XZ layout,
 cameras, controls, gameplay, dynamic physics, navigation, persistence, and the
 frame loop. ToonLab does not turn a prompt into a finished world.
 
-## Install the agent guidance
+## Realistic rock surface generation
 
-Everything in this section is present in the installed npm package.
+The public `rockgen` entry includes `createNaturalRockMapData`,
+`createNaturalRockSurfaceSpecification`, `resolveNaturalRockProjection`,
+`NATURAL_ROCK_SURFACE_PROFILES`, and `NATURAL_ROCK_MAP_ROLES`.
+These are the same deterministic realistic material profiles used by the Rock
+Lab. They produce typed RGBA map data; the host creates textures and assigns
+material/projection settings. Saved library rocks retain their surface recipe.
+The published realistic GLB is also available through raw catalog acquisition.
+Composite lithologies require authored semantic regions; micro-height maps are
+surface detail, not displacement that replaces a geometric high-to-low bake.
 
-### Codex
+## Load Nature Reference Rocks
 
-```bash
-cp node_modules/@call-me-sensei/toonlab/agents/codex/AGENTS.md ./AGENTS.md
-mkdir -p .agents/skills
-cp -R node_modules/@call-me-sensei/toonlab/agents/skills/codex/* .agents/skills/
-```
+Version 0.4.23 understands both the original `rock-0001`–`rock-0480`
+identities and the Nature Reference Rocks catalog. Acquiring an asset
+directly returns its realistic PBR GLB. The one-call placement path additionally
+loads that asset's reviewed geology maps and `call_me_sensei` material settings
+before applying the selected style bundle.
 
-### Claude Code
+```js
+import {
+  createOfficialCatalogAssetRuntime,
+  createOfficialCatalogProvider,
+  createOfficialCatalogRockEditorDescriptor,
+  loadOfficialCatalogAsset,
+} from '@call-me-sensei/toonlab/official-catalog';
+import { CALL_ME_SENSEI_STYLE_BUNDLE } from '@call-me-sensei/toonlab/styles';
+
+const provider = createOfficialCatalogProvider({
+  baseUrl: 'https://toonlab.io/',
+  transport: 'public-rock',
+});
+const assets = createOfficialCatalogAssetRuntime({ provider, renderer });
+const catalog = await provider.listAssets();
+const selectedRock = catalog.assets.find((asset) => asset.label.toLowerCase().includes('sandstone'));
+if (!selectedRock) throw new Error('Select an available sandstone rock from the catalog.');
+
+// Raw acquisition keeps the realistic PBR model.
+const realistic = await assets.acquireAsset(selectedRock.id);
+scene.add(realistic.root);
+
+// Placement loads the same rock's geology maps and applies Call Me Sensei.
+const stylized = await loadOfficialCatalogAsset({
+  assetId: selectedRock.id,
+  assetRuntime: assets,
+  parent: scene,
+  styleBundle: CALL_ME_SENSEI_STYLE_BUNDLE,
+});
 
-```bash
-cp node_modules/@call-me-sensei/toonlab/agents/claude/CLAUDE.md ./CLAUDE.md
-mkdir -p .claude/skills
-cp -R node_modules/@call-me-sensei/toonlab/agents/skills/claude/* .claude/skills/
+// Rock Lab/editor integrations receive the non-destructive authoring contract.
+const rockPackage = await assets.getRockPackage(selectedRock.id);
+const editorSource = createOfficialCatalogRockEditorDescriptor(
+  rockPackage.asset,
+  rockPackage,
+);
 ```
 
-### Cursor
+`editorSource` exposes `control.glb`, retained high detail, LOD0–LOD4,
+collision, recipe, material configuration, and the required post-sculpt
+reprojection/rebake/rebuild flags. These are immutable R2 URLs; the package
+does not embed any rock media. Release acquired handles and dispose the runtime
+when their scene lifetime ends.
 
-```bash
-mkdir -p .cursor/rules
-cp node_modules/@call-me-sensei/toonlab/agents/cursor/toonlab.mdc .cursor/rules/
-```
+## Install the agent guidance
+
+Everything in this section is present in the installed npm package.
+
+### Use the installed guide
+
+Add a reference to `node_modules/@call-me-sensei/toonlab/agents/codex/AGENTS.md`
+in the project's existing instructions, or read it directly. Merge relevant
+guidance; do not replace an existing `AGENTS.md` or `CLAUDE.md`. Claude's optional
+wrapper is `agents/claude/CLAUDE.md`; Cursor's is `agents/cursor/toonlab.mdc`.
+
+Copy only the feature skills you need into the client's skill directory, while
+preserving any existing skills with the same names. Shared `agents/...`
+references remain relative to the installed package root. Keep the package
+installed; copying a single skill does not copy its reference library.
 
-Use `agents/PROMPTS.md` for ready-to-paste prompts. Begin with `game-dev` for
-an existing scene and add `asset-sourcing` when Library, Gallery, or MCP asset
-discovery is involved.
+Start with `game-dev` for a new game or existing-scene integration, then add
+`asset-sourcing` for Library/Gallery work and the focused rendering skills as
+needed. `agents/PROMPTS.md` contains the prompt cookbook.
+`agents/examples/game-foundation.mjs` is a copyable, playable blockout example;
+it is application code, not an exported ToonLab game engine.
 
 ## Connect MCP
 
@@ -169,7 +228,8 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
       "command": "npx",
       "args": [
         "-y",
-        "@call-me-sensei/toonlab@0.4.21",
+        "--package=@call-me-sensei/toonlab@0.4.23",
+        "toonlab-mcp",
         "--workspace",
         "/absolute/path/to/your-game/.toonlab"
       ],
@@ -181,7 +241,7 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
 }
 ```
 
-This server provides the anime-game profile, runtime guide, live-Lab
+This server provides the anime-game profile, live-Lab
 contracts, deterministic document creation and mutation, policy validation,
 public Gallery search/retrieval, local Library operations, and optional
 provider-backed generation when the developer supplies server-side provider

package/README.md

@@ -19,7 +19,7 @@ Use ToonLab as a focused runtime library (`@call-me-sensei/toonlab` on npm), as
 an asset/preset authoring workspace, or as an asset-discovery service—not as a
 one-shot world generator.
 
-## Versioned expectation: 0.4.21
+## Versioned expectation: 0.4.23
 
 For a correctly constructed and semantically labeled scene, one strict Call Me
 Sensei bundle application is expected to establish the supported visual
@@ -277,8 +277,9 @@ Catalog data therefore does **not** use a separate downloadable “current
 seed,” and new datasets are **not** schema migrations. Keeping every released
 batch in the repository gives fresh and upgraded installations the same final
 catalog while preserving a simple, auditable upgrade path. The checked-in
-catalog currently contains 8,163 official assets: 480 first-party ToonLab
-rocks plus 7,683 verified open assets.
+catalog includes the original 480 first-party Stylized rocks, the 100-item
+Nature Reference Rocks by ToonLab collection, and the verified open-asset
+release. The two ToonLab rock collections keep distinct searchable identities.
 
 Applied filenames and SHA-256 digests are recorded in `schema_migrations` and
 `catalog_seed_batches`. Never edit, rename, or replace a released migration or
@@ -378,7 +379,7 @@ camera behavior, and game feel remain host-owned or pre-beta.
 | Toon character shading | `@call-me-sensei/toonlab/toon` | Modern anime character shader: cel bands with art-directed face lighting, skin-tone shadow management, shadow-color HSV control, scene/self/contact shadows, average-shadow smoothing, rim light (fresnel or screen-space depth), stylized + anisotropic hair highlights, eye catchlights, role-aware specular, source map routing (normal/AO/emissive/MatCap/ramp/detail), inverted-hull outlines, glitter, stickers, perspective removal, shell fur, dither fades — 23 settings groups, all preset-serializable. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/toon-shading.md) |
 | Environment shading | `@call-me-sensei/toonlab/environment` | Modern anime-style scene shader for texture packs, standard glTF, and untextured scenes: material-role classification, wrapped lighting, packed-map hints, window cutouts, sun/lamp rigs, time-of-day, six-direction ambient probe, planar floor reflections, BVH vertex-AO baking, height fog, cloud shadows. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/environment.md) |
 | Water | `@call-me-sensei/toonlab/water` | Focused water treatment for a host-authored water footprint, continuous shore, and closed seabed: Gerstner waves, absorption color, refraction/caustics/foam, ripples, splashes, wakes, kelp, underwater treatment, and CPU buoyancy sampling. It does not design the coast or underwater habitat. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/water.md) |
-| Vegetation | `@call-me-sensei/toonlab/vegetation` | Tree/grass/flower construction and shader runtimes, including the focused procedural broadleaf `BranchTree` with deterministic branching, five leaf silhouettes, caller-supplied leaf/bark textures, and a portable recipe. No authored tree asset collection is bundled or exported: reviewed tree recipes remain searchable Gallery assets delivered through MCP with their CC0 metadata. Package-generated trees preserve authored bark first and otherwise select a registered deterministic bark surface instead of a bare trunk. The experimental species roster remains repository-only. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/vegetation-sky.md) |
+| Vegetation | `@call-me-sensei/toonlab/vegetation` | Tree/grass/flower construction and shader runtimes, including the focused procedural broadleaf `BranchTree` with deterministic branching, eight leaf silhouettes, caller-supplied leaf/bark textures, and a portable recipe. No authored tree asset collection is bundled or exported: reviewed tree recipes remain searchable Gallery assets delivered through MCP with their CC0 metadata. Package-generated trees preserve authored bark first and otherwise select a registered deterministic bark surface instead of a bare trunk. The experimental species roster remains repository-only. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/vegetation-sky.md) |
 | Rock shader | `@call-me-sensei/toonlab/rock-shader` | Detailed, versioned rock-material profiles with projected detail, distance tint, normal fading, striping, moss and optional top layers, plus explicit source-albedo and vertex-color/AO integration. Call Me Sensei is the default. Geometry generation remains separate in `rockgen`. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/rock-shader.md) |
 | Ground shader | `@call-me-sensei/toonlab/ground-shader` | Splat-weighted anime terrain with slope/cliff detail, shoreline and weather response, HDR sun/shade controls, safe shadow defaults, and flat-albedo ground-field output for vegetation adoption. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/ground-shader.md) |
 | Sky | `@call-me-sensei/toonlab/sky` | Reusable atmosphere, palette, sun, moon, stars, and god-ray settings authored by Sky Lab and Sky & Cloud Lab. Your application coordinates final lighting and scene state. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/sky.md) |
@@ -628,7 +629,7 @@ stack, with WebGL2 fallback through the same TSL path.
   shared 24-hour controls, four-state regression matrix, and required cool/blue
   daylight-shadow verification.
 - [Rock shader](https://github.com/call-me-sensei/toonlab/blob/main/docs/rock-shader.md) — the separate generator/material
-  architecture, 58-field public configuration, import policy, and bundle use.
+  architecture, schema-defined public configuration, import policy, and bundle use.
 - [Styles, style bundles, and asset routing](https://github.com/call-me-sensei/toonlab/blob/main/docs/styles-and-bundles.md) —
   rendering domains, required asset labels, fallback policy, bundle ownership,
   OSS application boundaries, and the shader/lab migration contract.
@@ -654,7 +655,7 @@ stack, with WebGL2 fallback through the same TSL path.
 - [Post-processing](https://github.com/call-me-sensei/toonlab/blob/main/docs/post-processing.md)
 - [Texture Lab and texgen](https://github.com/call-me-sensei/toonlab/blob/main/docs/texture-lab.md)
 - [Characters and animation](https://github.com/call-me-sensei/toonlab/blob/main/docs/characters.md)
-- [Settings reference](https://github.com/call-me-sensei/toonlab/blob/main/docs/settings-reference.md) — every tunable field,
+- [Settings reference](https://github.com/call-me-sensei/toonlab/blob/main/docs/settings-reference.md) — selected runtime and repository settings,
   generated from the schemas (`node scripts/generate-settings-reference.mjs`).
 - [Shader constants](https://github.com/call-me-sensei/toonlab/blob/main/docs/shader-constants.md) — the deliberately unexposed
   constants and where they live.
@@ -666,14 +667,14 @@ Cursor, …). The recommended setup has three parts: give the agent the ToonLab
 skills, connect whichever ToonLab OSS local or ToonLab Pro remote MCP surface
 the developer has, then start from a goal prompt and iterate. The npm package
 ships runtime source and the small text-only `agents/` guidance bundle. It
-ships no models, textures, labs, examples, review fixtures, or other binary or
-visual assets.
+includes a copyable playable blockout in `agents/examples/game-foundation.mjs`;
+models, textures, Lab apps, repository demos and review media are not bundled.
 
 ### 1. Install the ToonLab skills in your game project
 
 The skills teach the agent the runtime boundary, asset-discovery order,
 frame-loop contract, and each focused subsystem API. Start with `game-dev` for
-integration into an existing scene and `asset-sourcing` for Gallery/MCP work.
+new-game development or integration, and `asset-sourcing` for Gallery/MCP work.
 Experimental whole-world, natural-cliff, Weather/Climate, camera, game-feel,
 and gameplay-VFX skills are intentionally not included in the npm artifact.
 
@@ -713,7 +714,7 @@ the public tree collection—those recipes are not npm built-ins:
   "mcpServers": {
     "toonlab-local": {
       "command": "npx",
-      "args": ["-y", "@call-me-sensei/toonlab@latest", "--workspace", "/absolute/path/to/your-game/.toonlab"],
+      "args": ["-y", "--package=@call-me-sensei/toonlab@latest", "toonlab-mcp", "--workspace", "/absolute/path/to/your-game/.toonlab"],
       "env": { "TOONLAB_LEGACY_WORKSPACE": "1" }
     }
   }

package/agents/PROMPTS.md

@@ -1,7 +1,21 @@
 # ToonLab agent prompts
 
 These prompts are included with the npm package. They use only the supported
-0.4.21 runtime, agent skills, and MCP workflows.
+0.4.23 runtime, agent skills, and MCP workflows.
+
+## New playable game
+
+```text
+Use the installed ToonLab game-dev skill to build the game described in my
+request. Implement the host gameplay, input, camera, UI and level structure;
+use ToonLab's public APIs for the supported visual and runtime systems. Start
+with a playable slice that has movement, collision, one objective and restart,
+then replace placeholders and apply the selected style. Use the installed
+version's export map, preserve asset/material identities, assign one update
+owner per system, and verify actual keyboard/pointer input, resize and teardown.
+Do not invent package APIs or describe the result as polished before inspecting
+it at the gameplay camera. Report remaining limitations concretely.
+```
 
 ## Existing-scene integration
 
@@ -71,8 +85,8 @@ species engine.
 ```text
 Using the ToonLab rockgen and rock-ground-shaders skills, create or edit the
 requested rock asset with @call-me-sensei/toonlab/rockgen and style it with
-@call-me-sensei/toonlab/rock-shader. Keep geometry identity, seed, LOD,
-collision, and baked channels in the rock document; keep reusable appearance in
+@call-me-sensei/toonlab/rock-shader. Preserve geometry identity, seed, surface recipe, authored masks, LOD,
+collision, and bake provenance; keep reusable appearance in
 the rock shader profile. Validate the portable documents and verify the result
 from multiple useful views. Do not deep-import repository compilers or test
 fixtures.

package/agents/README.md

@@ -4,7 +4,8 @@ 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 the
+For a new game, implement a playable host-game slice and then apply ToonLab.
+For an existing scene, preserve its authorized layout and systems: apply the
 focused character, manufactured, ground, rock, vegetation, water, sky, cloud,
 lighting, and post runtimes; find assets through Gallery or MCP; and author
 bounded portable outputs. The package does not promise reliable one-shot scene
@@ -22,12 +23,14 @@ Layout:
   runtime-boundary, sourcing-policy, and custom-gap contracts used by every
   agent integration.
 
-Recommended feature skills (start with `game-dev` for existing-scene
+Recommended feature skills (start with `game-dev` for new-game development or existing-scene
 integration and `asset-sourcing` for Gallery/MCP work):
 
 - `asset-sourcing`
 - `environment`
 - `game-dev`
+- `lighting`
+- `scene-style-application`
 - `post-processing`
 - `rock-ground-shaders`
 - `rockgen`
@@ -42,7 +45,7 @@ artifact. This includes whole-world construction, natural cliff formation,
 Weather/Climate composition, camera behavior, game feel, and gameplay VFX.
 
 These text-only resources ship with the npm package beside the runtime source.
-The package does not include ToonLab lab applications, examples, review
+The package does not include ToonLab lab applications, repository demo applications, 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.
@@ -52,3 +55,10 @@ 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.
+
+References beginning `agents/` resolve under the installed package root. Do not
+copy the shared guide over an existing game instruction file: add a reference
+to it, or merge only relevant guidance. Individual skills copied to an agent's
+skill directory still read shared references from the installed package.
+See `references/game-lifecycle.md` for update ownership and
+`examples/game-foundation.mjs` for a copyable, verified playable blockout.

package/agents/claude/CLAUDE.md

@@ -2,6 +2,9 @@
 
 ## Claude Code
 
+- Resolve `agents/` references from the installed package root.
+- Use the `game-dev` skill for new games and integration; host-owned input,
+  gameplay and layout are part of requested game development.
 - Use `agents/skills/claude/` as the user-facing usage guides for ToonLab
   runtime features.
 - Keep this file short; shared guidance belongs in `agents/codex/AGENTS.md`.