@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/agents/skills/codex/style-presets/SKILL.md

@@ -3,19 +3,23 @@ name: style-presets
 description: Explicitly select and record the intended ToonLab style or preset at every style-aware call site, distinguish neutral-default factories from Call Me Sensei-default factories, and audit overrides before reporting a custom integration note. Use before authoring environment, vegetation, grass, water, rock, ground, sky, cloud, or post settings, and whenever a subsystem looks unexpectedly unstyled.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Name the preset
 
 This skill makes an individual call site explicit; it does not imply that every
 listed subsystem is part of a live Lab. Sky and Cloud focused authoring is live.
-Weather, Climate, and automatic full-world composition remain lower-level APIs
-for users who want to assemble those systems in their own application.
+Weather and Climate engines remain repository-only; agents may author host
+scene conditions without claiming unsupported npm entry points.
 
 Style-aware ToonLab factories take a `preset`, a `style`, or both. Some
 factories intentionally resolve a neutral/default treatment when the selector
 is omitted; Rock and Ground already default to Call Me Sensei, while
 Cloud has no named style at all since the volumetric rebuild retired them.
-Always pass the intended selector anyway so the call site and capture manifest
-are auditable. Never claim that every omitted selector falls back to neutral.
+Pass the intended selector where the API has one; do not invent a selector
+for a parameter-only API. Never claim that every omitted selector falls back to neutral.
 
 Omitting a selector on the neutral-default factories is one of the most
 expensive mistakes a ToonLab agent can make. In one capability test it hit
@@ -65,10 +69,9 @@ report against ToonLab before the cause was found:
 - A bare `createVegetationShaderScopeSettings()` plus ~25 hand-authored fields —
   three revisions of look development on the wrong base.
 
-So: **before overriding a preset field, state why the shipped value is wrong for
-this scene**, in a comment, naming the scene fact the shared IP treatment cannot
-know — plane extent, bed depth, camera distance, a specific art-direction target
-with a measured value. If you cannot name one, do not override it.
+Document meaningful overrides with the scene requirement they serve, such as
+bed depth, camera distance, material identity or the requested art direction.
+Routine art iteration is allowed; do not add an approval step for every value.
 
 ## When a subsystem looks wrong
 

package/agents/skills/codex/toon-shading/SKILL.md

@@ -3,6 +3,10 @@ name: toon-shading
 description: Help developers use ToonLab character toon shading, toon settings, presets, material roles, outlines, shadows, highlights, fur, or stickers.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Toon Shading
 
 Use this skill when a developer wants ToonLab character toon materials, toon

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

@@ -3,6 +3,10 @@ name: vegetation-sky
 description: Help users apply ToonLab grass, flowers, trees, Tree/Grass/Flower shader profiles, and the live Sky/Cloud authoring surfaces to an existing scene.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Vegetation, Sky, and Cloud
 
 Use these focused systems on an existing scene with host-supplied placements,
@@ -85,7 +89,7 @@ User guidance:
   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
+  recursive branching and the supported `BRANCH_TREE_LEAF_SHAPES`, leaf color/texture plus a
   portable lit/shadow/crown palette, independent leaf `coverageScale`, bark
   color/texture, authored trunk bend/twist/taper, roots, portable documents,
   and the shared Tree Shader. `branches.children` counts lateral children;
@@ -104,7 +108,8 @@ User guidance:
   and use `trunkSurfaceProfile: 'none'` only for a deliberate flat-color art
   direction. Verify every trunk both casts and receives in shared-pass
   coverage telemetry.
-  Do not select, invent, or claim support for a botanical species. The large
+  Use supported morphology and texture controls for the requested appearance;
+  do not claim botanical fidelity from a named leaf shape alone. The large
   taxonomy/species roster visible in repository labs is experimental and is
   not a package API.
 - Author and route the independent `TREE_SHADER_PROFILE`,
@@ -118,8 +123,8 @@ User guidance:
 - 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
-  exactly 46 portable art fields; dome radius and quality are not in it.
+  atmosphere, sun, cloud, night-sky, noise, god-ray and time blocks use the
+  current `SKY_PARAMS_FIELD_SCHEMA`; quality is a separate runtime choice.
 - Cloud is a raymarched volumetric deck. The painted source/composition/card
   pipeline was replaced outright: `createCloudSourceDocument`,
   `createCloudCompositionDocument`, `createCloudField` and
@@ -132,9 +137,10 @@ User guidance:
 - `sky.settings` is the authored baseline and `sky.renderedSettings` is the
   current named-layer composition. Give Lighting, Weather, and other scene
   owners unique `setSceneOverrideLayer` ids and clear only their own id.
-- For world integration, let the host game own the sun/light adapter. Lighting
-  is not a stable public package or bundle domain; coordinate project-local
-  lighting through explicit Sky, Weather, Water, and vegetation adapters.
+- For world integration, prefer `createSceneStyleRuntime()` and its public
+  lighting slot for the sun, probe and shared shadows. The host still owns
+  time progression and authored local lights. Coordinate custom scene inputs
+  through the documented adapters.
 - The composed-world sun adapter is `setSun({ direction, color, sky })`; it
   keeps the real light/shadows and Grass, Flower, Forest, Ambient FX, Sky, and
   Water scene inputs aligned without changing their portable presets.

package/agents/skills/codex/visual-verification/SKILL.md

@@ -1,136 +1,62 @@
 ---
 name: visual-verification
-description: How to prove a ToonLab scene actually looks right — settling the scene before screenshotting, isolating a subsystem to attribute a defect, measuring colour against sampled targets with CIEDE2000, scanning the scene graph for outliers, and running an adversarial critic loop. Use whenever judging, reviewing, or iterating on a rendered scene, and before reporting that any visual defect is a ToonLab limitation.
+description: Verify ToonLab rendered output and gameplay with settled frames, relevant camera views, subsystem isolation and measurable evidence. Use for visual reviews or diagnosing a suspected rendering defect.
 ---
 
-# Verifying that it looks right
+# Verify rendered output
 
-A passing build is not visual approval, and a screenshot is not evidence unless
-you know what was in the frame when it was taken. This skill is the measurement
-discipline that turns "it looks wrong" into "this surface, this value, this
-owner".
+References beginning `agents/` resolve from the installed ToonLab package root.
+A passing build does not establish visual correctness. Choose checks that match
+the requested change, the art direction and the cameras the game actually uses.
 
-## Settle the scene before you screenshot
+## Readiness and capture
 
-ToonLab subsystems keep resolving work **after their factory returns** — GLB
-loads, render-target passes, texture uploads. Screenshotting on a fixed frame
-count produces frames with whole subsystems missing while your manifest happily
-reports them as present.
+Await every readiness promise exposed by the host, render through its real
+pipeline, and check required objects/textures have loaded. For static fixtures,
+stable drawable counts across frames are a necessary signal, not proof of GPU
+compilation or successful rendering. Animated/procedural scenes may legitimately
+change counts; use their explicit readiness signals instead.
 
-Observed: the same command produced 273,520 triangles with the entire lagoon
-absent on one run and 606,056 on the next.
+Inspect pixels from the output (a small `readPixels` grid or the captured image).
+Check that intended surfaces are visible, with useful coverage and valid alpha.
+Do not hardcode black as the only empty-frame value; an empty scene may match a
+sky-colored or transparent background. Check relevant console/network errors
+and failed textures. Do not dismiss a failed required resource because the rest
+of the scene renders. Record the camera, readiness signals and capture path.
 
-So: await every readiness promise the host exposes, render through the real
-pipeline, and re-read the scene graph until triangle and drawable counts are
-**unchanged across several consecutive reads**. Treat count stability as a
-necessary signal, not proof that GPU compilation, render targets, or external
-loads succeeded. Then screenshot. Report `settled`, the readiness signals, and
-a non-zero rendered frame count in the capture manifest, and **fail the
-capture** if any required signal is wrong. A black or half-built frame must
-never be able to pass as a render.
+## Diagnose before attributing a defect
 
-Before accepting the final frame, inspect pixels from the real output (a
-small `readPixels` grid or the captured image). Fail when nearly every sample
-matches the renderer clear/background color, when useful RGB variance or
-non-background coverage is effectively zero, or when alpha is invalid. Do not
-hardcode black as the only empty-frame value: sky blue, transparent, and custom
-clear colors can hide the same failure. Record the distinct-color count or
-coverage ratio with the capture.
+Isolate the suspect subsystem while retaining its lighting and required passes.
+Compare with and without post-processing when appropriate. Keep camera, pose,
+exposure, lighting and source textures fixed for before/after comparisons.
+Inspect world-space bounds, scale and material contracts when an object has an
+unexpected silhouette, repeated pattern or stretched surface.
 
-Also fail on any browser console error. A texture that failed to decode is a
-defect, not a warning.
+For palette-matching tasks, sample corresponding material regions and compare
+small patches in a perceptual color space such as CIEDE2000. Confirm the probe
+hits the intended surface. For ordinary feature work, clear visual inspection
+and targeted telemetry are enough; do not invent numeric color gates without a
+reference or require measurement tools unrelated to the requested result.
 
-## Isolate before you blame
+## View and interaction coverage
 
-Render subsystems alone to attribute a defect — and include the light rig, or
-you get a black frame and learn nothing.
+Use gameplay cameras first. For 3D assets or formations, choose relevant views
+from hero, wide, close, flyover, top-down; include angles that expose seams or
+repetition. A fixed-camera UI change does not need a five-camera asset audit.
+Check near/far and lit/shadowed behavior when LOD or lighting is affected.
 
-A "flowing water" texture smeared over every cliff was investigated as a
-waterfall bug for two review cycles. One isolated capture of terrain plus its
-lighting settled it in a minute: the ground shader was painting it.
+For a game slice, exercise movement, collision, interaction, success/failure and
+restart where present. Test resize, focus loss/resume and teardown when changing
+lifecycle ownership. Confirm post-processing is the final render path when used.
 
-Support a query flag that takes a **list** (`?only=terrain,lighting,sky`), and a
-flag that bypasses post. Most attribution questions collapse to two captures.
+## Review and report
 
-## Measure colour, do not argue about it
+Take a separate review pass against the requested acceptance criteria. When
+active tools and developer authorization permit an independent agent/thread,
+that reviewer should capture fresh evidence. Otherwise review locally; do not
+spawn agents or create user tasks without authorization.
 
-Sample the frame at fixed points and compare against your target values in
-**CIEDE2000**, not by eye and not by RGB distance. Average a small patch rather
-than a single pixel so dithering does not decide the answer.
-
-Two disciplines that matter more than the metric:
-
-- **Probe the right surface.** A probe that lands on terrain when you think it
-  is on rock will report a rock defect that does not exist. Prove it: change the
-  suspected material's value and re-measure. If the probe does not move, it is
-  not on that material. This exact check revealed that two "rock" probes were
-  reading the ground shader.
-- **Probe where the reference has that material.** A probe placed at coordinates
-  the reference fills with sky, on a frame where your scene has a cliff, measures
-  a composition difference and reports it as a colour failure.
-
-Keep a second sampler for arbitrary points, so a question like "is the shaded
-wall darker than the lit one, and by how much" is one command.
-
-## Scan the scene graph for outliers
-
-Traverse for meshes above a size threshold and print path, world-space extent
-and position. This catches the things nobody sees because they read as
-background:
-
-- a 104 m slab lying across a 72 m channel, damming it;
-- "cliff-top caps" built at 70–90 m across when the tower crown is 20 m.
-
-Both survived several visual reviews. A ten-line traversal found each in
-seconds.
-
-Audit transforms the same way. Report per-role mean and max uniform scale and
-the worst axis ratio; a mean scale of 6× with a max of 22× is a stretched
-surface, and it is visible long before anyone can articulate why.
-
-## Judge from every approved camera
-
-A formation can read as one coherent mass from the hero camera and as a kit row
-from above. Fix a small set of cameras — hero, wide, close, flyover, top-down —
-and require all of them before approving a change. Never approve from one view.
-
-## Run an adversarial critic
-
-Separate the builder from the judge. When the active tool surface and developer
-authorization permit an independent agent/thread, have that critic capture its
-**own** fresh evidence rather than trusting the builder's screenshots. Otherwise
-perform a separate critic pass after clearing builder assumptions. Read the
-module source and return structured blockers: region, expected, actual, fix,
-owner.
-
-Make the critic's standard a specific shipped frame, not "good". Give it the
-sampled palette and an explicit auto-fail list, and require a verdict field that
-is hard to fudge — a boolean like `readsAsOneMass` forces a judgement that a
-score can blur.
-
-Then feed the blockers back to the builder with instructions not to argue but to
-disprove with a capture if it disagrees. Loop until the critic passes it.
-
-In the qualifying run, independent critics scored subsystems 1.5–3.0 out of 10
-with 9–11 blockers each and drove the useful visual fixes. Code inspection
-still found contract defects; rendered evidence determined whether they were
-visible and whether a correction actually improved the target frame.
-
-## Keep the harness honest under parallelism
-
-If several agents capture at once:
-
-- give each run its own port, or they fight over a fixed one;
-- serialise the browser through a small semaphore — GPU-backed browsers
-  exhaust WASM memory a few instances in, and the failure surfaces to an agent
-  as a broken module rather than as machine pressure;
-- expect transient failures from another agent's mid-edit file, and retry rather
-  than "fixing" a module you do not own.
-
-## Record the measurement, not the conclusion
-
-Write down the number and the command that produced it. "The wall is too blue"
-ages badly; "left wall `#4B6E97` L105 against target `#93A9C6` L168, from
-`capture --view hero` then a point sample at 300,250" can be re-checked after
-the scene has moved on — and it repeatedly turned out that the conclusion was
-wrong while the measurement was still useful.
+Describe concrete defects with location, expected result, observed result and
+likely owner. Fix them and repeat affected checks. Report evidence and remaining
+limitations without treating every host-owned feature as a ToonLab limitation.
+Use a standalone fixture to support claims about package defects.

package/agents/skills/codex/water/SKILL.md

@@ -3,6 +3,10 @@ name: water
 description: Help developers use ToonLab water materials, waves, ripple simulation, breakers, splashes, rain, kelp, or water settings.
 ---
 
+References beginning `agents/` resolve from the installed ToonLab package root
+(normally `node_modules/@call-me-sensei/toonlab/`), even when this skill is copied.
+
+
 # Water
 
 Use this skill when a developer wants WaterSurface, water material settings,
@@ -65,8 +69,8 @@ Developer guidance:
   composition. Live scene owners use unique `setSceneOverrideLayer` ids and
   clear only their own id; they must not write composed values back to a preset.
 - In a composed world, let the host game own lighting and pass current light
-  state through Water's explicit scene adapters. Lighting is not a stable
-  public package or bundle domain.
+  state through Water's explicit scene adapters. The public lighting slot and `createSceneStyleRuntime()` coordinate the
+  supported lighting and shared-shadow contract.
 - Preserve the host renderer's depth convention. Water supports both standard
   and reversed depth; qualify contact foam and refraction using the host's
   actual `reversedDepthBuffer` setting rather than silently changing it.

package/database/apply-one-catalog-seed.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { closeDatabase, getPool, withTransaction } from './client.mjs';
+
+const fileArgument = process.argv[2];
+if (!fileArgument) throw new Error('Usage: node database/apply-one-catalog-seed.mjs database/seeds/catalog/NNNN_release.sql');
+const file = path.resolve(fileArgument);
+const catalogSeedRoot = `${path.resolve('database/seeds/catalog')}${path.sep}`;
+if (!file.startsWith(catalogSeedRoot) || !/^\d{4}_[a-z0-9._-]+\.sql$/iu.test(path.basename(file))) {
+  throw new Error('Only one numbered catalog seed below database/seeds/catalog may be applied.');
+}
+
+const sql = await readFile(file, 'utf8');
+const hash = createHash('sha256').update(sql).digest('hex');
+const name = path.basename(file);
+const release = sql.match(/^-- Release: ([a-z0-9._-]+)$/im)?.[1];
+const assetCount = Number(sql.match(/^-- Asset count: (\d+)$/m)?.[1]);
+if (!release || !Number.isSafeInteger(assetCount) || assetCount < 0) {
+  throw new Error(`${name}: missing generated release metadata.`);
+}
+
+try {
+  const pool = await getPool();
+  await pool.query(
+    `create table if not exists catalog_seed_batches (
+      name text primary key,
+      sha256 text not null,
+      release text,
+      asset_count integer not null default 0,
+      applied_at timestamptz not null default now()
+    )`,
+  );
+  const result = await withTransaction(async (client) => {
+    await client.query('select pg_advisory_xact_lock(hashtext($1))', ['toonlab:catalog_seed_batches']);
+    const existing = await client.query('select sha256 from catalog_seed_batches where name = $1', [name]);
+    if (existing.rowCount) {
+      if (existing.rows[0].sha256 !== hash) throw new Error(`${name} changed after it was applied`);
+      return { status: 'unchanged' };
+    }
+    await client.query(sql);
+    await client.query(
+      `insert into catalog_seed_batches (name, sha256, release, asset_count)
+       values ($1, $2, $3, $4)`,
+      [name, hash, release, assetCount],
+    );
+    const published = await client.query(
+      `select count(*)::int as count from catalog_assets
+       where release = $1 and availability_status = 'active'`,
+      [release],
+    );
+    if (Number(published.rows[0].count) !== assetCount) {
+      throw new Error(`${release}: expected ${assetCount} active assets after seed.`);
+    }
+    return { published: Number(published.rows[0].count), status: 'applied' };
+  });
+  process.stdout.write(`${JSON.stringify({ assetCount, hash, name, release, ...result }, null, 2)}\n`);
+} finally {
+  await closeDatabase();
+}

package/database/providers.mjs

@@ -291,6 +291,7 @@ async function runOpenAiOrArk(provider, request, key) {
         { content: request.user ?? request.prompt ?? '', role: 'user' },
       ],
       model: request.model || (provider === 'openai' ? 'gpt-5-mini' : ''),
+      ...(request.kind === 'texture-recipe' ? { max_completion_tokens: 4096 } : {}),
       ...(request.jsonMode === true ? { response_format: { type: 'json_object' } } : {}),
     }),
     headers: {