@call-me-sensei/toonlab 0.4.19 → 0.4.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@call-me-sensei/toonlab",
-  "version": "0.4.19",
+  "version": "0.4.21",
   "description": "Anime-style game toolkit for Three.js with cel shading, vegetation, rocks, water, sky, clouds, procedural textures, and portable Lab artifacts",
   "license": "MIT",
   "author": "Hyperbond Studio PTE. LTD. (Call Me Sensei)",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/call-me-sensei/toonlab.git"
   },
-  "homepage": "https://github.com/call-me-sensei/toonlab#readme",
+  "homepage": "https://toonlab.io/docs",
   "bugs": {
     "url": "https://github.com/call-me-sensei/toonlab/issues"
   },
@@ -83,14 +83,22 @@
     "src/collisionMetadata.js",
     "types",
     "mcp",
-    "cli",
+    "cli/toonlab.mjs",
     "database",
-    "agents/references",
+    "agents/references/anime-art-direction.md",
+    "agents/references/asset-sourcing-policy.md",
+    "agents/references/custom-gap-report.md",
+    "agents/references/mcp-asset-discovery.md",
+    "agents/references/runtime-entry-points.md",
+    "agents/references/style-bundles.md",
+    "agents/README.md",
+    "agents/PROMPTS.md",
+    "agents/claude/CLAUDE.md",
+    "agents/codex/AGENTS.md",
+    "agents/cursor/toonlab.mdc",
     "agents/skills/claude/asset-sourcing",
     "agents/skills/claude/environment",
     "agents/skills/claude/game-dev",
-    "agents/skills/claude/karst-cliff-construction",
-    "agents/skills/claude/outdoor-world",
     "agents/skills/claude/post-processing",
     "agents/skills/claude/rock-ground-shaders",
     "agents/skills/claude/rockgen",
@@ -103,8 +111,6 @@
     "agents/skills/codex/asset-sourcing",
     "agents/skills/codex/environment",
     "agents/skills/codex/game-dev",
-    "agents/skills/codex/karst-cliff-construction",
-    "agents/skills/codex/outdoor-world",
     "agents/skills/codex/post-processing",
     "agents/skills/codex/rock-ground-shaders",
     "agents/skills/codex/rockgen",
@@ -117,6 +123,7 @@
     "scripts/setup-local.mjs",
     "scripts/generate-catalog-seed.mjs",
     "compose.yaml",
+    "NPM-LIBRARY.md",
     "README.md",
     "LICENSE"
   ],
@@ -272,8 +279,20 @@
     "golden:compare": "node scripts/compare-golden-captures.mjs",
     "verify:rockgen": "node scripts/verify-rockgen.mjs",
     "verify:rock-generation-lab": "node scripts/verify-rock-generation-lab.mjs",
+    "verify:rock-c7-library": "node scripts/verify-rock-c7-surface-library.mjs",
     "verify:rock-lab-lifecycle": "node scripts/verify-rock-lab-lifecycle.mjs",
     "verify:rock-shader": "node scripts/verify-rock-shader.mjs",
+    "verify:rock-regions": "node scripts/verify-rock-regions.mjs",
+    "verify:rock-region-compiler": "node scripts/verify-rock-region-compiler.mjs",
+    "verify:rock-region-migrations": "node scripts/verify-rock-region-schema-migrations.mjs",
+    "verify:rock-regions-package": "node scripts/verify-packaged-rock-regions.mjs",
+    "verify:rock-regions-clean-consumer": "node scripts/verify-rock-region-clean-consumer.mjs",
+    "verify:rock-semantic-materials": "node scripts/verify-rock-semantic-materials.mjs",
+    "verify:rock-geology-v2-ontology": "node scripts/verify-rock-geology-v2-ontology.mjs",
+    "verify:rock-geology-v2-morphology": "node scripts/verify-rock-geology-v2-morphology.mjs",
+    "verify:rock-geology-v2-inspirations": "node scripts/verify-rock-geology-v2-inspirations.mjs",
+    "verify:rock-geology-v2-canonical-pilot": "node scripts/verify-rock-geology-v2-canonical-pilot.mjs",
+    "capture:rock-geology-v2-canonical-pilot": "node scripts/capture-rock-geology-v2-canonical-pilot.mjs",
     "verify:ground-shader": "node scripts/verify-ground-shader.mjs",
     "verify:pathgen": "node scripts/verify-pathgen.mjs",
     "visual:check": "node scripts/visual-check.mjs",
@@ -295,6 +314,7 @@
     "verify:localization": "node scripts/verify-localization.mjs",
     "verify:lab-asset-provenance": "node scripts/verify-lab-asset-provenance.mjs",
     "verify:lab-preview": "node scripts/verify-lab-preview.mjs",
+    "verify:library-preview": "node scripts/verify-library-preview-coverage.mjs",
     "verify:public-labs": "node scripts/verify-public-lab-authoring.mjs",
     "verify:vegetation-labs": "node scripts/verify-vegetation-lab-readiness.mjs",
     "verify:water-lab": "node scripts/verify-water-lab-contract.mjs",
@@ -327,7 +347,6 @@
     "verify:quality-integration": "node scripts/verify-quality-budget-integration.mjs && node scripts/verify-packaged-quality-budget-integration.mjs",
     "verify:vegetation-shader": "node scripts/verify-vegetation-shader.mjs",
     "verify:lab-styles": "node scripts/verify-lab-style-boundaries.mjs",
-    "verify:legacy-trees": "node scripts/verify-legacy-trees.mjs",
     "verify:branch-tree": "node scripts/verify-branch-tree.mjs",
     "verify:tree-doodle": "node scripts/verify-tree-doodle.mjs",
     "verify:tree-woody": "node scripts/verify-tree-woody-engine.mjs",
@@ -345,7 +364,7 @@
     "verify:collision-package": "node scripts/verify-packaged-world-collision.mjs",
     "verify:official-catalog": "node scripts/verify-official-catalog-provider.mjs && node scripts/verify-official-catalog-runtime.mjs && node scripts/verify-official-catalog-lod.mjs && node scripts/verify-official-catalog-placement.mjs && node scripts/verify-playground-official-catalog.mjs && node scripts/verify-packaged-official-catalog.mjs",
     "verify:system-style": "node scripts/verify-system-style-policy.mjs",
-    "verify:release": "npm run verify:system-style && npm run verify:style-contract && npm run verify:style-labels-package && npm run verify:collision-package && npm run verify:scene-collision && npm run verify:official-catalog && npm run verify:public-labs && npm run verify:live-labs && npm run verify:rock-shader && npm run verify:rock-generation-lab && npm run verify:rock-lab-lifecycle && npm run verify:ground-shader && npm run verify:manufactured-materials && npm run verify:material-labeling:agent && npm run verify:material-labeling:mcp && npm run verify:water-lab && npm run verify:water && npm run verify:vegetation-labs && npm run verify:texgen && npm run verify:cloud-shader && npm run verify:sky-cloud-lab && npm run verify:world-quality && npm run verify:scatter && npm run verify:legacy-trees && npm run verify:branch-tree && npm run verify:grass-package && npm run verify:character-package && npm run verify:locomotion-state && npm run verify:ground-stabilizer && npm run verify:water-interaction && npm run verify:walkable-character && npm run verify:playground-walkable && npm run verify:renderer-configuration && npm run verify:scene-scheduler && npm run verify:scene-surface && npm run verify:shared-shadow-receivers && npm run verify:scene-quality && npm run verify:quality-integration && npm run verify:lab-asset-provenance && npm run verify:api && npm run verify:types && npm run verify:mcp && npm run verify:skills && npm run verify:docs && npm run verify:local-database && npm run verify:package",
+    "verify:release": "npm run verify:system-style && npm run verify:style-contract && npm run verify:style-labels-package && npm run verify:collision-package && npm run verify:scene-collision && npm run verify:official-catalog && npm run verify:public-labs && npm run verify:live-labs && npm run verify:rock-shader && npm run verify:rock-generation-lab && npm run verify:rock-lab-lifecycle && npm run verify:ground-shader && npm run verify:manufactured-materials && npm run verify:material-labeling:agent && npm run verify:material-labeling:mcp && npm run verify:water-lab && npm run verify:water && npm run verify:vegetation-labs && npm run verify:texgen && npm run verify:cloud-shader && npm run verify:sky-cloud-lab && npm run verify:world-quality && npm run verify:scatter && npm run verify:branch-tree && npm run verify:grass-package && npm run verify:character-package && npm run verify:locomotion-state && npm run verify:ground-stabilizer && npm run verify:water-interaction && npm run verify:walkable-character && npm run verify:playground-walkable && npm run verify:renderer-configuration && npm run verify:scene-scheduler && npm run verify:scene-surface && npm run verify:shared-shadow-receivers && npm run verify:scene-quality && npm run verify:quality-integration && npm run verify:lab-asset-provenance && npm run verify:api && npm run verify:types && npm run verify:mcp && npm run verify:skills && npm run verify:docs && npm run verify:local-database && npm run verify:package",
     "verify:generation": "node scripts/verify-generation.mjs",
     "verify:post": "node scripts/verify-post.mjs",
     "verify:camera": "node scripts/verify-camera.mjs",
@@ -354,13 +373,14 @@
     "verify:soundscape": "node scripts/verify-soundscape.mjs",
     "verify:game-feel": "node scripts/verify-game-feel.mjs",
     "verify:world-quality": "node scripts/verify-world-quality.mjs",
-    "verify:all": "npm run verify:system-style && npm run verify:product-namespace && npm run verify:generation && npm run verify:post && npm run verify:camera && npm run verify:motion && npm run verify:biome && npm run verify:soundscape && npm run verify:game-feel && npm run verify:world-quality && npm run verify:rock-shader && npm run verify:ground-shader && npm run verify:rockgen && npm run verify:rock-generation-lab && npm run verify:pathgen && npm run verify:propgen && npm run verify:buildinggen && npm run verify:villagegen && npm run verify:fauna && npm run verify:ambientfx && npm run verify:vfxgen && npm run verify:water && npm run verify:landscape && npm run verify:lighting && npm run verify:lighting-lab && npm run verify:live-labs && npm run verify:lab-preview && npm run verify:weather && npm run verify:climate && npm run verify:atmospheric-condition-lab && npm run verify:sky && npm run verify:cloud-shader && npm run verify:sky-cloud-lab && npm run verify:environment-cycle && npm run verify:manufactured-materials && npm run verify:ground-field && npm run verify:grass && npm run verify:grass-package && npm run verify:character-package && npm run verify:vegetation-shader && npm run verify:lab-styles && npm run verify:scatter && npm run verify:legacy-trees && npm run verify:branch-tree && npm run verify:collision-package && npm run verify:scene-collision && npm run verify:official-catalog && npm run verify:api && npm run verify:package && npm run verify:catalog && npm run verify:assetlib && npm run verify:mcp && npm run verify:local-generation",
+    "verify:all": "npm run verify:system-style && npm run verify:product-namespace && npm run verify:generation && npm run verify:post && npm run verify:camera && npm run verify:motion && npm run verify:biome && npm run verify:soundscape && npm run verify:game-feel && npm run verify:world-quality && npm run verify:rock-shader && npm run verify:ground-shader && npm run verify:rockgen && npm run verify:rock-generation-lab && npm run verify:pathgen && npm run verify:propgen && npm run verify:buildinggen && npm run verify:villagegen && npm run verify:fauna && npm run verify:ambientfx && npm run verify:vfxgen && npm run verify:water && npm run verify:landscape && npm run verify:lighting && npm run verify:lighting-lab && npm run verify:live-labs && npm run verify:lab-preview && npm run verify:weather && npm run verify:climate && npm run verify:atmospheric-condition-lab && npm run verify:sky && npm run verify:cloud-shader && npm run verify:sky-cloud-lab && npm run verify:environment-cycle && npm run verify:manufactured-materials && npm run verify:ground-field && npm run verify:grass && npm run verify:grass-package && npm run verify:character-package && npm run verify:vegetation-shader && npm run verify:lab-styles && npm run verify:scatter && npm run verify:branch-tree && npm run verify:collision-package && npm run verify:scene-collision && npm run verify:official-catalog && npm run verify:api && npm run verify:package && npm run verify:catalog && npm run verify:assetlib && npm run verify:mcp && npm run verify:local-generation",
     "verify:catalog": "node scripts/verify-catalog.mjs",
     "verify:assetlib": "node scripts/verify-assetlib.mjs",
     "verify:mcp": "node scripts/verify-mcp.mjs",
     "verify:local-database": "node scripts/verify-local-database.mjs",
+    "verify:creation-revisions": "node scripts/verify-creation-revisions.mjs",
     "verify:gallery-database": "node scripts/verify-official-gallery-database.mjs",
-    "verify:local-generation": "node scripts/verify-local-generation.mjs",
+    "verify:local-generation": "node scripts/verify-local-generation.mjs && node scripts/verify-fal-patina.mjs",
     "thumbs:prop": "node scripts/generate-prop-thumbs.mjs",
     "thumbs:building": "node scripts/generate-building-thumbs.mjs",
     "thumbs:catalog": "node scripts/generate-catalog-thumbs.mjs",

package/scripts/generate-catalog-seed.mjs

@@ -73,6 +73,22 @@ function assertContentType(value, label) {
   }
 }
 
+function assertPublicHttpsUrl(value, label, { optional = false } = {}) {
+  if (optional && !value) return;
+  let url;
+  try {
+    url = new URL(String(value ?? ''));
+  } catch {
+    throw new Error(`${label}: must be public HTTPS`);
+  }
+  if (
+    url.protocol !== 'https:'
+    || url.username
+    || url.password
+    || /[?&](?:sign|signature|token|X-Amz-Credential|X-Amz-Signature)=/i.test(url.search)
+  ) throw new Error(`${label}: must be public HTTPS`);
+}
+
 function assertReview(asset, policy) {
   const review = asset.licenseReview;
   if (!review || typeof review !== 'object') throw new Error(`${asset.id}: licenseReview is required`);
@@ -110,7 +126,7 @@ function assertRockDimensions(asset) {
 function assertAsset(asset, release, baseUrl) {
   const required = [
     'id', 'source', 'kind', 'name', 'license', 'licenseUrl', 'downloadUrl',
-    'sha256', 'byteSize', 'contentType', 'redistributionScope', 'reviewedAt',
+    'redistributionScope', 'reviewedAt',
   ];
   for (const field of required) {
     if (asset[field] == null || asset[field] === '') throw new Error(`${asset.id ?? 'asset'}: ${field} is required`);
@@ -130,13 +146,24 @@ function assertAsset(asset, release, baseUrl) {
   if (asset.attributionRequired && !String(asset.attribution ?? '').trim()) {
     throw new Error(`${asset.id}: attribution text is required`);
   }
-  assertSha(asset.sha256, asset.id);
-  assertBytes(asset.byteSize, asset.id);
-  assertContentType(asset.contentType, asset.id);
+  const externalOnly = asset.redistributionScope === 'external-only';
+  if (!externalOnly) {
+    assertSha(asset.sha256, asset.id);
+    assertBytes(asset.byteSize, asset.id);
+    assertContentType(asset.contentType, asset.id);
+  } else if (asset.sha256 != null || asset.byteSize != null || asset.contentType != null) {
+    throw new Error(`${asset.id}: external-only assets must not claim release-owned integrity metadata`);
+  }
   assertRockDimensions(asset);
+  assertPublicHttpsUrl(asset.sourceUrl, `${asset.id}: sourceUrl`);
   const prefix = immutablePrefix(baseUrl, release, asset.id);
-  assertUrl(asset.downloadUrl, prefix, `${asset.id}: downloadUrl`);
-  assertUrl(asset.thumbnailUrl, prefix, `${asset.id}: thumbnailUrl`, { optional: true });
+  if (externalOnly) {
+    assertPublicHttpsUrl(asset.downloadUrl, `${asset.id}: external-only downloadUrl`);
+    assertPublicHttpsUrl(asset.thumbnailUrl, `${asset.id}: external-only thumbnailUrl`, { optional: true });
+  } else {
+    assertUrl(asset.downloadUrl, prefix, `${asset.id}: downloadUrl`);
+    assertUrl(asset.thumbnailUrl, prefix, `${asset.id}: thumbnailUrl`, { optional: true });
+  }
   const paths = new Set();
   const files = asset.files ?? [];
   if (!Array.isArray(files)) throw new Error(`${asset.id}: files must be an array`);
@@ -209,7 +236,7 @@ const rows = manifest.assets.map((asset) => `(
   ${sqlString(asset.sourceId)}, ${sqlString(asset.kind)}, ${sqlString(asset.name)},
   ${sqlString(asset.description)}, ${sqlString(asset.license)}, ${sqlString(asset.attribution)},
   ${sqlString(asset.sourceUrl)}, ${sqlString(asset.downloadUrl)}, ${sqlString(asset.thumbnailUrl)},
-  ${sqlString(asset.sha256.toLowerCase())}, ${Number(asset.byteSize)}, ${sqlString(asset.contentType)},
+  ${sqlString(asset.sha256?.toLowerCase())}, ${asset.byteSize == null ? 'null' : Number(asset.byteSize)}, ${sqlString(asset.contentType)},
   ${sqlArray(asset.tags)}, ${sqlString(JSON.stringify(asset.metadata ?? {}))}::jsonb,
   ${sqlString(asset.licenseUrl)}, ${asset.attributionRequired === true},
   ${sqlString(asset.redistributionScope)}, ${sqlString(asset.reviewedAt)}, 'active'

package/src/asset-policy/catalogLicenses.js

@@ -7,10 +7,35 @@ export const APPROVED_CATALOG_SPDX_LICENSES = Object.freeze([
   'MIT',
 ]);
 
-// Custom terms are deny-by-default. Applications may maintain their own
-// reviewed registry, but ToonLab ships no vendor-specific custom-license
-// approvals or pending vendor records.
-export const REVIEWED_CATALOG_LICENSES = Object.freeze({});
+// Custom terms are deny-by-default. Every shipped entry needs a checked-in,
+// authoritative approval URL and explicit redistribution scopes.
+export const REVIEWED_CATALOG_LICENSES = Object.freeze({
+  'LicenseRef-PLATEAU-PDL-1.0': Object.freeze({
+    approvalEvidence: 'https://www.mlit.go.jp/plateau/site-policy/',
+    approved: true,
+    canonicalUrl: 'https://www.mlit.go.jp/plateau/site-policy/',
+    extractedFileRedistribution: true,
+    id: 'LicenseRef-PLATEAU-PDL-1.0',
+    originalArchiveRedistribution: true,
+    spdx: false,
+    status: 'approved',
+  }),
+});
+
+/**
+ * Classification for a license field that carries no value.
+ *
+ * First-party ToonLab catalog records ship `license: null` — there is no
+ * third-party grant to record because the asset is owned. That is a different
+ * situation from a third-party asset whose license is unknown, and collapsing
+ * the two produced a misleading failure: every first-party rock record hit
+ * "(missing license) is not in the reviewed-license registry", which reads as
+ * an unreviewed third-party license rather than an absent field.
+ *
+ * Absence is still never an approval. It is reported as its own state so a
+ * caller can decide, and so the error text points at the real problem.
+ */
+export const CATALOG_LICENSE_UNSPECIFIED = 'unspecified';
 
 export function resolveCatalogLicense(id) {
   const licenseId = String(id ?? '').trim();
@@ -27,9 +52,42 @@ export function resolveCatalogLicense(id) {
   return REVIEWED_CATALOG_LICENSES[licenseId] ?? null;
 }
 
+/**
+ * Classifies a license id without throwing, so callers can branch on the
+ * outcome instead of using exceptions for control flow.
+ *
+ * `not-approved` is a distinct state from `unrecognized`: the registry exists to
+ * hold rejected policies too (see the `!policy.approved` branch below), so
+ * collapsing "reviewed and refused" into "approved" would let a caller that
+ * branches on the state ship an asset the review explicitly rejected.
+ *
+ * @returns {{state: 'approved'|'not-approved'|'unspecified'|'unrecognized', id: string|null, policy: object|null}}
+ */
+export function describeCatalogLicense(id) {
+  const licenseId = String(id ?? '').trim();
+  if (!licenseId) {
+    return { id: null, policy: null, state: CATALOG_LICENSE_UNSPECIFIED };
+  }
+  const policy = resolveCatalogLicense(licenseId);
+  if (!policy) return { id: licenseId, policy: null, state: 'unrecognized' };
+  return {
+    id: licenseId,
+    policy,
+    state: policy.approved ? 'approved' : 'not-approved',
+  };
+}
+
 export function assertCatalogLicenseRelease({ id, redistributionScope, evidence } = {}) {
-  const policy = resolveCatalogLicense(id);
-  if (!policy) throw new Error(`${id || '(missing license)'} is not in the reviewed-license registry`);
+  const described = describeCatalogLicense(id);
+  if (described.state === CATALOG_LICENSE_UNSPECIFIED) {
+    throw new Error(
+      'catalog license is unspecified: the record carries no license value. '
+      + 'First-party assets still need an explicit license id before release — '
+      + 'absence is not an approval.',
+    );
+  }
+  const policy = described.policy;
+  if (!policy) throw new Error(`${id} is not in the reviewed-license registry`);
   if (!policy.approved) throw new Error(`${id}: reviewed-license policy is ${policy.status ?? 'not approved'}`);
   if (redistributionScope !== 'external-only' && !policy.originalArchiveRedistribution) {
     throw new Error(`${id}: original-archive redistribution is not approved`);

package/src/assetlib/loadImported.js

@@ -7,6 +7,7 @@
 import * as THREE from 'three';
 import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
 
 import { readZipEntries } from './zip.js';
 
@@ -17,7 +18,13 @@ import { readZipEntries } from './zip.js';
  * LoadingManager URL modifier rewrites each request by suffix match, which
  * also covers URL-encoded variants.
  */
-export async function loadImportedModel({ url, resources = {}, dracoDecoderPath = '/draco/gltf/' }) {
+export async function loadImportedModel({
+  url,
+  resources = {},
+  dracoDecoderPath = '/draco/gltf/',
+  ktx2TranscoderPath = '/basis/',
+  renderer = null,
+}) {
   const manager = new THREE.LoadingManager();
   const byPath = Object.entries(resources);
   manager.setURLModifier((requested) => {
@@ -32,11 +39,18 @@ export async function loadImportedModel({ url, resources = {}, dracoDecoderPath
   const dracoLoader = new DRACOLoader(manager);
   dracoLoader.setDecoderPath(dracoDecoderPath);
   loader.setDRACOLoader(dracoLoader);
+  const ktx2Loader = renderer
+    ? new KTX2Loader(manager)
+      .setTranscoderPath(ktx2TranscoderPath)
+      .detectSupport(renderer)
+    : null;
+  if (ktx2Loader) loader.setKTX2Loader(ktx2Loader);
   let gltf;
   try {
     gltf = await loader.loadAsync(url);
   } finally {
     dracoLoader.dispose();
+    ktx2Loader?.dispose();
   }
   const object = gltf.scene ?? gltf.scenes?.[0];
   if (!object) throw new Error('loadImportedModel: glTF contained no scene.');

package/src/catalog/officialCatalogAssetRuntime.js

@@ -8,6 +8,11 @@ import {
   setObjectTextureColorSpaces,
   waitForObjectTextures,
 } from '../toon/toonMaterialAdapter.js';
+import {
+  copyRockSemanticMaterialBinding,
+  prepareRockSemanticMaterialBindings,
+  rockSemanticMaterialTextures,
+} from '../rock-shader/rockSemanticMaterialRuntime.js';
 import { OFFICIAL_CATALOG_ASSET_VERSION } from './officialCatalogProvider.js';
 
 const rendererPools = new WeakMap();
@@ -29,6 +34,9 @@ function collectModelResources(root) {
       Object.values(material).forEach((value) => {
         if (value?.isTexture) textures.add(value);
       });
+      for (const value of Object.values(rockSemanticMaterialTextures(material) ?? {})) {
+        if (value?.isTexture) textures.add(value);
+      }
     });
   });
   return { geometries, materials, textures };
@@ -86,7 +94,9 @@ function cloneModelRoot(sourceRoot) {
   root.traverse((object) => {
     if (!object.isMesh || !object.material) return;
     const cloneMaterial = (material) => {
-      if (!materialClones.has(material)) materialClones.set(material, material.clone());
+      if (!materialClones.has(material)) {
+        materialClones.set(material, copyRockSemanticMaterialBinding(material, material.clone()));
+      }
       return materialClones.get(material);
     };
     object.material = Array.isArray(object.material)
@@ -115,9 +125,10 @@ function releaseInstanceRoot(root, sourceResources) {
   });
 }
 
-async function defaultPrepareTextures(root) {
+async function defaultPrepareTextures(root, asset) {
   await waitForObjectTextures(root);
   setObjectTextureColorSpaces(root);
+  await prepareRockSemanticMaterialBindings(root, { modelUrl: asset?.modelUrl });
 }
 
 /**

package/src/catalog/officialCatalogLod.js

@@ -57,10 +57,16 @@ export function selectCatalogLodLevel({
   distance,
   distances,
   maxLevel = Number.POSITIVE_INFINITY,
+  currentLevel = null,
+  hysteresis = 0,
 } = {}) {
   const available = [...new Set((availableLevels ?? []).map(finiteLevel).filter((v) => v !== null))]
     .sort((left, right) => left - right);
   if (available.length === 0) return null;
+  const margin = Number(hysteresis);
+  if (!Number.isFinite(margin) || margin < 0 || margin >= 0.5) {
+    throw new RangeError('Catalog LOD hysteresis must be a finite ratio in [0, 0.5).');
+  }
   const thresholds = normalizeCatalogLodDistances(distances, available.at(-1) + 1);
   const finiteDistance = Math.max(Number(distance) || 0, 0);
   let requested = 0;
@@ -69,7 +75,26 @@ export function selectCatalogLodLevel({
   }
   requested = Math.min(requested, Math.max(Number(maxLevel) || 0, 0));
   const lower = available.filter((level) => level <= requested).at(-1);
-  return lower ?? available[0];
+  const selected = lower ?? available[0];
+
+  const current = finiteLevel(currentLevel);
+  if (current === null || !available.includes(current) || margin === 0 || selected === current) {
+    return selected;
+  }
+
+  if (selected > current) {
+    // Do not leave the current LOD until the first available coarser level's
+    // threshold plus its margin has been crossed. This also handles authored
+    // groups with deliberately missing intermediate levels.
+    const next = available.find((level) => level > current && level <= selected);
+    if (next !== undefined && finiteDistance < thresholds[next] * (1 + margin)) return current;
+  } else {
+    // Hold the current LOD while the camera jitters inside the lower half of
+    // the transition band. Crossing it permits the normal deterministic
+    // selector to choose one or several finer levels.
+    if (finiteDistance >= thresholds[current] * (1 - margin)) return current;
+  }
+  return selected;
 }
 
 /**
@@ -79,6 +104,7 @@ export function selectCatalogLodLevel({
  */
 export function createCatalogLodRuntime(root, {
   distances = [0, 45, 120],
+  hysteresis = 0,
   maxLevel = Number.POSITIVE_INFINITY,
   namePattern = DEFAULT_LOD_NAME_PATTERN,
 } = {}) {
@@ -87,6 +113,10 @@ export function createCatalogLodRuntime(root, {
     [...new Set(bindings.map((binding) => binding.level))].sort((a, b) => a - b),
   );
   const thresholds = normalizeCatalogLodDistances(distances, availableLevels.at(-1) + 1);
+  const hysteresisRatio = Number(hysteresis);
+  if (!Number.isFinite(hysteresisRatio) || hysteresisRatio < 0 || hysteresisRatio >= 0.5) {
+    throw new RangeError('Catalog LOD hysteresis must be a finite ratio in [0, 0.5).');
+  }
   const worldPosition = new Vector3();
   const worldScale = new Vector3();
   let currentLevel = null;
@@ -124,6 +154,8 @@ export function createCatalogLodRuntime(root, {
       availableLevels,
       distance,
       distances: thresholds,
+      currentLevel,
+      hysteresis: hysteresisRatio,
       maxLevel,
     });
     const changed = setLevel(level);
@@ -145,6 +177,7 @@ export function createCatalogLodRuntime(root, {
     get level() { return currentLevel; },
     setLevel,
     thresholds,
+    hysteresis: hysteresisRatio,
     update,
   });
 }

package/src/catalog/officialCatalogPlacement.js

@@ -7,6 +7,7 @@ import {
   validateCollisionMetadata,
 } from '../collisionMetadata.js';
 import { applyRockShader } from '../rock-shader/rockShaderRuntime.js';
+import { withoutDegenerateDetailMaps } from '../rock-shader/rockTextureIntegrity.js';
 import {
   applyStyleBundle,
 } from '../styles/styleApplication.js';
@@ -38,28 +39,37 @@ function rotation3(value) {
   return [0, Number(value) || 0, 0];
 }
 
-function catalogRockTextures(root) {
-  const textures = {};
-  root.traverse((object) => {
-    if (!object.isMesh || textures.rockNormal) return;
-    const source = (Array.isArray(object.material) ? object.material : [object.material])
-      .find((material) => material?.normalMap);
-    if (source) textures.rockNormal = source.normalMap;
-  });
-  return textures;
+/**
+ * Validates caller-supplied style textures without reclassifying the asset's
+ * own UV-space maps as triplanar detail maps. applyRockShader reads the full
+ * original material directly (albedo, metallic/roughness, normal, occlusion,
+ * specular, and emissive); harvesting its normal into `rockNormal` would apply
+ * that same map twice and with the wrong coordinate system.
+ */
+function catalogRockTextures(overrides = {}) {
+  const usable = withoutDegenerateDetailMaps(overrides);
+  return {
+    rejected: usable.rejected,
+    textures: usable.textures,
+  };
 }
 
-function styleAdapterFor(asset, root) {
+function styleAdapterFor(asset, root, { textures: overrides, variation }) {
   if (asset.domain !== 'natural.rock') return null;
-  const textures = catalogRockTextures(root);
+  const resolved = catalogRockTextures(overrides);
+  const report = { rejectedTextures: resolved.rejected };
   return Object.freeze({
     apply(subject, settings) {
-      return applyRockShader(subject, settings, {
+      const result = applyRockShader(subject, settings, {
         name: `ToonLab · ${asset.label}`,
-        textures,
+        textures: resolved.textures,
+        variation,
       });
+      report.rejectedTextures = [...resolved.rejected, ...(result.rejectedTextures ?? [])];
+      return result;
     },
     id: 'toonlab-official-catalog-rock',
+    report,
   });
 }
 
@@ -113,6 +123,8 @@ export async function loadOfficialCatalogAsset({
   scale = [1, 1, 1],
   styleBundle,
   targetId = null,
+  textures = {},
+  variation = 0,
 } = {}) {
   if (!assetRuntime?.acquireAsset) {
     throw new TypeError('loadOfficialCatalogAsset requires an official catalog asset runtime.');
@@ -136,6 +148,7 @@ export async function loadOfficialCatalogAsset({
   container.updateWorldMatrix(true, true);
 
   let metadata;
+  let adapter = null;
   let style = null;
   let lod = null;
   let collisionRegistration = null;
@@ -147,7 +160,7 @@ export async function loadOfficialCatalogAsset({
       collision: metadata,
       targetId: id,
     }));
-    const adapter = styleAdapterFor(asset, root);
+    adapter = styleAdapterFor(asset, root, { textures, variation });
     style = await applyStyleBundle(styleBundle, {
       targets: [createStyleTarget(id, asset.domain, root, { adapter })],
     });
@@ -209,6 +222,8 @@ export async function loadOfficialCatalogAsset({
     normalization,
     object: root,
     quality: qualityProfile,
+    /** Detail maps the artifact shipped that were too small to be usable. */
+    get rejectedTextures() { return adapter?.report?.rejectedTextures ?? []; },
     async release() {
       if (released) return false;
       released = true;

package/src/character/animationRetarget.js

@@ -838,6 +838,7 @@ async function loadPackagedLocomotionClipsForTarget(targetMesh, rig, {
   retargetMode = 'world',
   rootMotion = false,
   sourceUrl = TOONLAB_MANNEQUIN_ASSET_URL,
+  trackNameStyle = 'skeleton',
 } = {}) {
   const sourceAsset = await loadModelAsset(sourceUrl);
   let sourceMesh = null;
@@ -942,6 +943,7 @@ async function loadPackagedLocomotionClipsForTarget(targetMesh, rig, {
           mode: retargetMode,
           rootMotion,
           sourceRig,
+          trackNameStyle,
         },
       );
       const clip = spec.filter(retargeted);

package/src/character/characterRig.js

@@ -14,7 +14,12 @@
 
 // Mixamo bone per VRM humanoid role. Also the source-side chain map used for
 // rest-pose direction corrections lives on these names (MIXAMO_CHAIN_CHILD).
-const MIXAMO_BONE_BY_ROLE = Object.freeze({
+/**
+ * The humanoid contract itself: role -> canonical Mixamo bone name. Exported so
+ * a host can audit a rig against it (which roles resolved, which are missing)
+ * rather than inferring the answer from a bone count.
+ */
+export const MIXAMO_BONE_BY_ROLE = Object.freeze({
   hips: 'mixamorigHips',
   spine: 'mixamorigSpine',
   chest: 'mixamorigSpine1',