@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/agents/codex/AGENTS.md

@@ -0,0 +1,161 @@
+# 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.

package/agents/cursor/toonlab.mdc

@@ -0,0 +1,37 @@
+---
+description: ToonLab developer guidance for Cursor agents
+globs: "**/*"
+alwaysApply: true
+---
+
+# ToonLab
+
+- 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.
+- Prefer package subpath imports such as `@call-me-sensei/toonlab/toon`,
+  `@call-me-sensei/toonlab/water`,
+  `@call-me-sensei/toonlab/vegetation-shaders`,
+  `@call-me-sensei/toonlab/grass-palettes`, and
+  `@call-me-sensei/toonlab/rockgen`;
+  keep root imports lightweight.
+- Use TSL/NodeMaterial patterns. Do not guide developers toward raw GLSL,
+  `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.
+- 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
+  the versioned ToonLab material contract. A root-only label is incomplete for
+  a multi-material asset. Split incompatible atlas regions or supply an ID
+  mask. Strict mode blocks handoff; advisory mode reports the gap and must not
+  describe incomplete material coverage as bundle-ready.
+- Treat Sky and Cloud as supported focused authoring/runtime systems. Whole
+  terrain/biome/coast/cliff formation remains outside the npm boundary.
+- Before style-aware construction, read the matching `style-presets` skill.
+  Before approving screenshots or reporting a package gap use
+  `visual-verification`. The Claude and Codex copies are byte-identical, so
+  either directory is authoritative.
+- Verify with the consumer app's normal checks.

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

@@ -10,11 +10,12 @@ 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.
+  `search_public_gallery`, `get_public_gallery_asset`, `search_cc0_assets`,
+  `get_cc0_asset`, and `import_cc0_asset`. Its `search_assets` searches
+  approved built-in generator/settings entries, the local released official
+  catalog, and the disk-backed project/library/workspace. Authored assets such
+  as reviewed tree recipes are searched through `search_public_gallery` rather
+  than copied into npm.
 - **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
@@ -41,10 +42,12 @@ the surface the developer actually has and report which surface was used.
 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.
+   accepted local entry closes the role, call `search_public_gallery` for
+   authored public assets and follow `nextOffset` until null. Use
+   `type: 'tree-recipe'` for reviewed trees. Use `search_assets` with
+   `source: 'official'` only for the installed released catalog.
+2. Call local `get_public_gallery_asset` for a selected Gallery document or
+   `get_asset` for a local/released-catalog record.
 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/`.

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

@@ -145,8 +145,8 @@ surface.assertReady({
 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
+The live `cloud` entry is 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
@@ -166,8 +166,9 @@ 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.
+inverse and round-trips. This is a focused sky/cloud authoring and runtime
+contract; final scene composition and art direction remain host
+responsibilities.
 
 Use the package README and exported functions/settings as the runtime source
 of truth. Labs, internal comparison fixtures, local asset paths, and repository

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

@@ -50,9 +50,11 @@ scene-kit role.
 2. **Reuse what exists.** In OSS, earlier imports, saved presets, and exports
    live in `.toonlab/`; call local `list_my_creations` and `search_assets` with
    `source: 'workspace'`, `'workspace-storage'`, `'library'`, or `'builtin'`.
-   If those do not close the role, use local `search_assets` with
-   `source: 'official'` for the complete released Gallery catalog and follow
-   `nextOffset` until null.
+   If those do not close the role, use local `search_public_gallery` and follow
+   `nextOffset` until null; use `type: 'tree-recipe'` for authored trees and
+   retrieve a finalist with `get_public_gallery_asset`. Use local
+   `search_assets({ source: 'official' })` only for the installed released
+   catalog.
    In Pro, call cloud `list_my_creations`, then `search_public_gallery`; use
    `source: 'toonlab'` plus the appropriate catalog for first-party assets and
    follow `nextOffset`. For rocks on either surface, shortlist from positive
@@ -195,9 +197,10 @@ table, as the source of truth):
 
 - Seamless PBR material sets (brick, wood, ground …) → ambientCG.
 - Photoscanned props, HDRIs, high-end texture sets → Poly Haven.
-- Stylized/toon-ready models, vegetation, buildings → the built-in
-  procedural catalog first only for families that passed the base-set
-  reliability gate; otherwise compare curated external candidates.
+- Authored stylized/toon-ready models and vegetation → the public Gallery
+  first; retrieve their portable document and provenance through MCP. Use a
+  built-in procedural family only when it passed the base-set reliability gate
+  and the task calls for new generation rather than an existing asset.
 - Stylized *seamless textures* → `@call-me-sensei/toonlab/texgen` in code
   (60+ presets); the catalog has no texture entries, so this route is a
   package import, not an MCP call.

package/agents/skills/claude/rock-ground-shaders/SKILL.md

@@ -35,6 +35,22 @@ if (report.usedGeneratedTextures) {
 setRockShaderSceneState(rockRoot, { waterLevel });
 ```
 
+For the representative semantic hoodoo, validate before styling:
+
+```js
+import { inspectRockRegionBindings } from '@call-me-sensei/toonlab/rock-shader';
+
+const regions = inspectRockRegionBindings(hoodooRoot);
+if (regions.totalVertices !== 134981) throw new Error('Unexpected hoodoo binding');
+```
+
+The v1 binding is fixed to profile `hoodoo-caprock-normalized-height-v1` and
+channels `base/shaft/neck/cap`. Do not apply it to another family. Use only
+material styling (`detail: null`) on the annotated mesh; any position/topology
+edit requires semantic regeneration and rebaking. Prove repeated
+`applyRockShader()` / `restoreRockShader()` cycles restore exact material,
+texture, geometry, index, attribute, shadow, and user-data identities.
+
 `applyRockShader` sets `castShadow` and `receiveShadow` true by default.
 Override them only for an explicit rendering reason. It reports whether
 provided textures or first-party generated maps were used; never call the

package/agents/skills/claude/vegetation-sky/SKILL.md

@@ -80,8 +80,11 @@ User guidance:
   create the pass after all writer meshes exist, call its `update()` every frame before grass, require
   `writerCount > 0` and `ready`, and call `invalidate()` after repainting a
   writer without a transform change.
-- In the public package, use `LEGACY_TREE_PRESETS` and `createLegacyTree()` for the 12
-  supported pre-species silhouettes. Use `BranchTree` when the developer wants
+- The public package contains tree construction and shader capability, not a
+  predefined tree asset collection. For an authored tree, use the connected
+  MCP's `search_public_gallery` and `get_public_gallery_asset` tools, then
+  instantiate its portable recipe with `StylizedTree`. Use `BranchTree` when
+  the developer explicitly wants
   recursive branching, five broadleaf silhouettes, leaf color/texture plus a
   portable lit/shadow/crown palette, independent leaf `coverageScale`, bark
   color/texture, authored trunk bend/twist/taper, roots, portable documents,
@@ -108,11 +111,11 @@ User guidance:
   `GRASS_SHADER_PROFILE`, and `FLOWER_SHADER_PROFILE` through the bundle's
   `treeShader`, `grassShader`, and `flowerShader` slots. They share a renderer
   family and semantic material contract, but serialize and apply independently.
-  Keep asset albedo and legacy/BranchTree geometry/material inputs separate from all
+  Keep asset albedo and Gallery-recipe/BranchTree geometry/material inputs separate from all
   three shader treatments.
 - Grass palettes update base, tip, and shadow tint together; they do not change
   shadow strength, wind, or current weather.
-- Use the public versioned Grass, vegetation-shader, legacy/BranchTree/flower recipe, and Sky
+- Use the public versioned Grass, vegetation-shader, BranchTree/flower recipe, and Sky
   preset document APIs for portable data; do not copy lab-local validators.
 - Treat Sky as one integrated World System, not a separate Shader Lab. Its
   shader, sun, clouds, stars, and procedural motion form one system preset with

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

@@ -50,9 +50,11 @@ scene-kit role.
 2. **Reuse what exists.** In OSS, earlier imports, saved presets, and exports
    live in `.toonlab/`; call local `list_my_creations` and `search_assets` with
    `source: 'workspace'`, `'workspace-storage'`, `'library'`, or `'builtin'`.
-   If those do not close the role, use local `search_assets` with
-   `source: 'official'` for the complete released Gallery catalog and follow
-   `nextOffset` until null.
+   If those do not close the role, use local `search_public_gallery` and follow
+   `nextOffset` until null; use `type: 'tree-recipe'` for authored trees and
+   retrieve a finalist with `get_public_gallery_asset`. Use local
+   `search_assets({ source: 'official' })` only for the installed released
+   catalog.
    In Pro, call cloud `list_my_creations`, then `search_public_gallery`; use
    `source: 'toonlab'` plus the appropriate catalog for first-party assets and
    follow `nextOffset`. For rocks on either surface, shortlist from positive
@@ -195,9 +197,10 @@ table, as the source of truth):
 
 - Seamless PBR material sets (brick, wood, ground …) → ambientCG.
 - Photoscanned props, HDRIs, high-end texture sets → Poly Haven.
-- Stylized/toon-ready models, vegetation, buildings → the built-in
-  procedural catalog first only for families that passed the base-set
-  reliability gate; otherwise compare curated external candidates.
+- Authored stylized/toon-ready models and vegetation → the public Gallery
+  first; retrieve their portable document and provenance through MCP. Use a
+  built-in procedural family only when it passed the base-set reliability gate
+  and the task calls for new generation rather than an existing asset.
 - Stylized *seamless textures* → `@call-me-sensei/toonlab/texgen` in code
   (60+ presets); the catalog has no texture entries, so this route is a
   package import, not an MCP call.

package/agents/skills/codex/rock-ground-shaders/SKILL.md

@@ -35,6 +35,22 @@ if (report.usedGeneratedTextures) {
 setRockShaderSceneState(rockRoot, { waterLevel });
 ```
 
+For the representative semantic hoodoo, validate before styling:
+
+```js
+import { inspectRockRegionBindings } from '@call-me-sensei/toonlab/rock-shader';
+
+const regions = inspectRockRegionBindings(hoodooRoot);
+if (regions.totalVertices !== 134981) throw new Error('Unexpected hoodoo binding');
+```
+
+The v1 binding is fixed to profile `hoodoo-caprock-normalized-height-v1` and
+channels `base/shaft/neck/cap`. Do not apply it to another family. Use only
+material styling (`detail: null`) on the annotated mesh; any position/topology
+edit requires semantic regeneration and rebaking. Prove repeated
+`applyRockShader()` / `restoreRockShader()` cycles restore exact material,
+texture, geometry, index, attribute, shadow, and user-data identities.
+
 `applyRockShader` sets `castShadow` and `receiveShadow` true by default.
 Override them only for an explicit rendering reason. It reports whether
 provided textures or first-party generated maps were used; never call the

package/agents/skills/codex/vegetation-sky/SKILL.md

@@ -80,8 +80,11 @@ User guidance:
   create the pass after all writer meshes exist, call its `update()` every frame before grass, require
   `writerCount > 0` and `ready`, and call `invalidate()` after repainting a
   writer without a transform change.
-- In the public package, use `LEGACY_TREE_PRESETS` and `createLegacyTree()` for the 12
-  supported pre-species silhouettes. Use `BranchTree` when the developer wants
+- The public package contains tree construction and shader capability, not a
+  predefined tree asset collection. For an authored tree, use the connected
+  MCP's `search_public_gallery` and `get_public_gallery_asset` tools, then
+  instantiate its portable recipe with `StylizedTree`. Use `BranchTree` when
+  the developer explicitly wants
   recursive branching, five broadleaf silhouettes, leaf color/texture plus a
   portable lit/shadow/crown palette, independent leaf `coverageScale`, bark
   color/texture, authored trunk bend/twist/taper, roots, portable documents,
@@ -108,11 +111,11 @@ User guidance:
   `GRASS_SHADER_PROFILE`, and `FLOWER_SHADER_PROFILE` through the bundle's
   `treeShader`, `grassShader`, and `flowerShader` slots. They share a renderer
   family and semantic material contract, but serialize and apply independently.
-  Keep asset albedo and legacy/BranchTree geometry/material inputs separate from all
+  Keep asset albedo and Gallery-recipe/BranchTree geometry/material inputs separate from all
   three shader treatments.
 - Grass palettes update base, tip, and shadow tint together; they do not change
   shadow strength, wind, or current weather.
-- Use the public versioned Grass, vegetation-shader, legacy/BranchTree/flower recipe, and Sky
+- Use the public versioned Grass, vegetation-shader, BranchTree/flower recipe, and Sky
   preset document APIs for portable data; do not copy lab-local validators.
 - Treat Sky as one integrated World System, not a separate Shader Lab. Its
   shader, sun, clouds, stars, and procedural motion form one system preset with

package/cli/toonlab.mjs

@@ -36,7 +36,8 @@ function parse(argv) {
 }
 
 try {
-  const { operation, options } = parse(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  const { operation, options } = parse(argv);
   const input = JSON.parse(await readFile(options.input, 'utf8'));
   const result = runSceneStyleOperation(operation, input, options);
   const json = `${JSON.stringify(result, null, options.pretty ? 2 : 0)}\n`;
@@ -47,6 +48,6 @@ try {
   }
   if (!result.ok) process.exitCode = 2;
 } catch (error) {
-  process.stderr.write(`${error?.message ?? String(error)}\n`);
+  process.stderr.write(`${error?.code ? `${error.code}: ` : ''}${error?.message ?? String(error)}\n`);
   process.exitCode = 1;
 }

package/database/fal-patina.mjs

@@ -0,0 +1,131 @@
+export const PATINA_MATERIAL_MODEL = 'fal-ai/patina/material';
+export const PATINA_MAP_TYPES = Object.freeze(['basecolor', 'normal', 'roughness', 'metalness', 'height']);
+export const PATINA_RESOLUTIONS = Object.freeze(['1k', '2k', '4k', '8k']);
+export const PATINA_IMAGE_SIZE_PRESETS = Object.freeze([
+  'square_hd',
+  'square',
+  'portrait_4_3',
+  'portrait_16_9',
+  'landscape_4_3',
+  'landscape_16_9',
+]);
+export const PATINA_UPSCALE_FACTORS = Object.freeze([0, 2, 4]);
+
+export function patinaResolutionPlan(resolution = '2k') {
+  const normalized = String(resolution).toLowerCase();
+  if (normalized === '1k') return { imageSize: { width: 1024, height: 1024 }, upscaleFactor: 0 };
+  if (normalized === '2k') return { imageSize: { width: 2048, height: 2048 }, upscaleFactor: 0 };
+  if (normalized === '4k') return { imageSize: { width: 2048, height: 2048 }, upscaleFactor: 2 };
+  if (normalized === '8k') return { imageSize: { width: 2048, height: 2048 }, upscaleFactor: 4 };
+  throw new Error(`Fal Patina does not support resolution "${resolution}".`);
+}
+
+function integer(value, fallback, min, max, label) {
+  const resolved = value === undefined ? fallback : Number(value);
+  if (!Number.isInteger(resolved) || resolved < min || resolved > max) {
+    throw new Error(`${label} must be an integer from ${min} to ${max}.`);
+  }
+  return resolved;
+}
+
+function imageSize(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value === 'string') {
+    if (!PATINA_IMAGE_SIZE_PRESETS.includes(value)) throw new Error('Invalid Fal Patina image_size preset.');
+    return value;
+  }
+  if (!value || typeof value !== 'object') throw new Error('image_size must be a preset or { width, height }.');
+  return {
+    width: integer(value.width, NaN, 256, 2048, 'image_size.width'),
+    height: integer(value.height, NaN, 256, 2048, 'image_size.height'),
+  };
+}
+
+/** Validate and translate ToonLab's camelCase request into Fal's wire schema. */
+export function createPatinaInput(request = {}) {
+  const prompt = String(request.prompt ?? '').trim();
+  if (!prompt) throw new Error('A material prompt is required.');
+  const plan = patinaResolutionPlan(request.resolution ?? '2k');
+  const requestedMaps = request.maps === undefined ? PATINA_MAP_TYPES : request.maps;
+  if (!Array.isArray(requestedMaps)) throw new Error('maps must be an array.');
+  const maps = [...new Set(requestedMaps.map(String))];
+  if (maps.some((map) => !PATINA_MAP_TYPES.includes(map))) throw new Error('Fal Patina maps contain an unsupported map type.');
+  const tilingMode = request.tilingMode ?? request.tiling_mode ?? 'both';
+  if (!['both', 'horizontal', 'vertical'].includes(tilingMode)) throw new Error('tiling_mode must be both, horizontal, or vertical.');
+  const outputFormat = request.outputFormat ?? request.output_format ?? 'png';
+  if (!['png', 'jpeg', 'webp'].includes(outputFormat)) throw new Error('output_format must be png, jpeg, or webp.');
+  const upscaleFactor = request.upscaleFactor ?? request.upscale_factor ?? plan.upscaleFactor;
+  if (!PATINA_UPSCALE_FACTORS.includes(Number(upscaleFactor))) throw new Error('upscale_factor must be 0, 2, or 4.');
+  const input = {
+    prompt,
+    image_size: imageSize(request.imageSize ?? request.image_size, plan.imageSize),
+    num_inference_steps: integer(request.numInferenceSteps ?? request.num_inference_steps, 8, 1, 8, 'num_inference_steps'),
+    num_images: integer(request.numImages ?? request.num_images, 1, 1, 4, 'num_images'),
+    enable_prompt_expansion: (request.enablePromptExpansion ?? request.enable_prompt_expansion) !== false,
+    enable_safety_checker: (request.enableSafetyChecker ?? request.enable_safety_checker) !== false,
+    tiling_mode: tilingMode,
+    tile_size: integer(request.tileSize ?? request.tile_size, 128, 32, 256, 'tile_size'),
+    tile_stride: integer(request.tileStride ?? request.tile_stride, 64, 16, 128, 'tile_stride'),
+    maps,
+    upscale_factor: Number(upscaleFactor),
+    output_format: outputFormat,
+  };
+  const seed = request.seed;
+  if (seed !== undefined) input.seed = integer(seed, 0, -2147483648, 2147483647, 'seed');
+  const imageUrl = request.imageUrl ?? request.image_url;
+  const maskUrl = request.maskUrl ?? request.mask_url;
+  if (imageUrl) {
+    if (!/^https:\/\//i.test(String(imageUrl))) throw new Error('image_url must be a public HTTPS URL.');
+    input.image_url = String(imageUrl);
+    const strength = Number(request.strength ?? 0.6);
+    if (!Number.isFinite(strength) || strength < 0 || strength > 1) throw new Error('strength must be from 0 to 1.');
+    input.strength = strength;
+  }
+  if (maskUrl) {
+    if (!imageUrl) throw new Error('mask_url requires image_url.');
+    if (!/^https:\/\//i.test(String(maskUrl))) throw new Error('mask_url must be a public HTTPS URL.');
+    input.mask_url = String(maskUrl);
+  }
+  return input;
+}
+
+export function normalizePatinaResult(data, input) {
+  if (!Array.isArray(data?.images)) throw new Error('Fal Patina returned no material images.');
+  const images = data.images.map((image) => {
+        if (!image || typeof image.url !== 'string' || !/^https:\/\//i.test(image.url)) {
+          throw new Error('Fal Patina returned an invalid material image URL.');
+        }
+        if (image.map_type != null && !PATINA_MAP_TYPES.includes(image.map_type)) {
+          throw new Error(`Fal Patina returned an unsupported map type: ${String(image.map_type)}.`);
+        }
+        return {
+          url: image.url,
+          mapType: image.map_type == null ? null : image.map_type,
+          contentType: typeof image.content_type === 'string' ? image.content_type : null,
+          name: typeof image.file_name === 'string' ? image.file_name : null,
+          byteSize: Number.isFinite(Number(image.file_size)) ? Number(image.file_size) : null,
+          width: Number.isFinite(Number(image.width)) ? Number(image.width) : null,
+          height: Number.isFinite(Number(image.height)) ? Number(image.height) : null,
+        };
+      });
+  const variants = Number(input.num_images ?? 1);
+  const requestedMaps = Array.isArray(input.maps) ? input.maps : PATINA_MAP_TYPES;
+  const previewCount = images.filter((image) => image.mapType === null).length;
+  if (previewCount !== variants) {
+    throw new Error(`Fal Patina returned ${previewCount} previews; expected ${variants}.`);
+  }
+  for (const mapType of PATINA_MAP_TYPES) {
+    const count = images.filter((image) => image.mapType === mapType).length;
+    const expected = requestedMaps.includes(mapType) ? variants : 0;
+    if (count !== expected) {
+      throw new Error(`Fal Patina returned ${count} ${mapType} maps; expected ${expected}.`);
+    }
+  }
+  return {
+    images,
+    input,
+    prompt: typeof data.prompt === 'string' ? data.prompt : input.prompt,
+    seed: Number.isFinite(Number(data.seed)) ? Number(data.seed) : null,
+    timings: data.timings && typeof data.timings === 'object' ? data.timings : null,
+  };
+}