@call-me-sensei/toonlab 0.4.21 → 0.4.23

package/mcp/vite-plugin.mjs

@@ -154,7 +154,10 @@ export function toonlabWorkspacePlugin({ rootDirectory = process.cwd(), workspac
       'multiview_to_model',
       'model_segment',
     ]);
-    if (!imageKinds.has(kind) && !modelKinds.has(kind) && !materialKinds.has(kind)) {
+    if (kind === 'texture-recipe' && !['gemini', 'openai'].includes(provider)) {
+      throw Object.assign(new Error('Texture recipes require Gemini or OpenAI.'), { statusCode: 400 });
+    }
+    if (kind !== 'texture-recipe' && !imageKinds.has(kind) && !modelKinds.has(kind) && !materialKinds.has(kind)) {
       throw Object.assign(new Error('Unsupported generation kind.'), { statusCode: 400 });
     }
     const providerKinds = {
@@ -203,6 +206,7 @@ export function toonlabWorkspacePlugin({ rootDirectory = process.cwd(), workspac
       );
       const result = await runProvider(provider, {
         ...requestBody,
+        ...(kind === 'texture-recipe' ? { jsonMode: true, responseMimeType: 'application/json', maxOutputTokens: 4096 } : {}),
         kind,
         prompt,
         referenceImages,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@call-me-sensei/toonlab",
-  "version": "0.4.21",
+  "version": "0.4.23",
   "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)",
@@ -61,6 +61,7 @@
     "src/catalog/officialCatalog.js",
     "src/catalog/officialCatalogLod.js",
     "src/catalog/officialCatalogPlacement.js",
+    "src/catalog/officialCatalogRockPackage.js",
     "src/core",
     "src/environment",
     "src/ground-shader",
@@ -125,7 +126,11 @@
     "compose.yaml",
     "NPM-LIBRARY.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "agents/references/game-lifecycle.md",
+    "agents/examples/game-foundation.mjs",
+    "agents/skills/codex/lighting",
+    "agents/skills/claude/lighting"
   ],
   "exports": {
     ".": {
@@ -278,7 +283,8 @@
     "golden:capture": "node scripts/capture-golden-fixtures.mjs",
     "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-dense-field-lod": "node scripts/verify-rock-dense-field-lod.mjs && node scripts/verify-official-catalog-lod.mjs",
+    "verify:rock-generation-lab": "node scripts/verify-rock-tool-behavior.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",
@@ -304,7 +310,8 @@
     "verify:fauna": "node scripts/verify-fauna.mjs",
     "verify:ambientfx": "node scripts/verify-ambientfx.mjs",
     "verify:vfxgen": "node scripts/verify-vfxgen.mjs",
-    "verify:water": "node scripts/verify-watergen.mjs",
+    "verify:water-experiments": "node scripts/verify-water-experiments.mjs",
+    "verify:water": "node scripts/verify-watergen.mjs && node scripts/verify-water-physics.mjs && node scripts/verify-water-dynamics.mjs && node scripts/verify-water-beach-swash.mjs",
     "verify:texgen": "node scripts/verify-texgen.mjs",
     "verify:landscape": "node scripts/verify-landscape.mjs",
     "verify:lighting": "node scripts/verify-lighting.mjs",
@@ -315,9 +322,9 @@
     "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",
+    "verify:public-labs": "node scripts/verify-public-lab-authoring.mjs && node scripts/verify-lab-audit-regressions.mjs && node scripts/verify-lab-editing-regressions.mjs",
+    "verify:vegetation-labs": "node scripts/verify-vegetation-lab-readiness.mjs && node scripts/verify-vegetation-preview-runtime.mjs",
+    "verify:water-lab": "node scripts/verify-water-lab-contract.mjs && node scripts/verify-water-experiments.mjs",
     "verify:weather": "node scripts/verify-weather.mjs",
     "verify:climate": "node scripts/verify-climate.mjs",
     "verify:atmospheric-condition-lab": "node scripts/verify-atmospheric-condition-lab.mjs",
@@ -356,15 +363,15 @@
     "verify:tree-species-references": "node scripts/verify-tree-species-references.mjs",
     "verify:product-namespace": "node scripts/verify-product-namespace.mjs",
     "verify:skills": "node scripts/verify-agent-skills.mjs",
-    "verify:docs": "node scripts/verify-package-documentation.mjs",
+    "verify:docs": "node scripts/verify-package-documentation.mjs && node scripts/generate-settings-reference.mjs --check && node scripts/verify-documentation-examples.mjs",
     "verify:api": "node scripts/verify-public-api.mjs",
     "verify:package": "node scripts/verify-package-boundary.mjs",
     "verify:style-contract": "node scripts/verify-style-contract.mjs",
     "verify:style-labels-package": "node scripts/verify-packaged-style-labels.mjs",
     "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:official-catalog": "node scripts/verify-official-catalog-provider.mjs && node scripts/verify-official-catalog-rock-package.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: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:natural-rock-surfaces && 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",
@@ -376,7 +383,7 @@
     "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:mcp": "node scripts/sync-mcp-tree-contract.mjs --check && node scripts/verify-mcp.mjs && node scripts/verify-packaged-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",
@@ -386,20 +393,21 @@
     "thumbs:catalog": "node scripts/generate-catalog-thumbs.mjs",
     "thumbs:home": "node scripts/generate-home-shots.mjs",
     "prepublishOnly": "npm run verify:release",
-    "verify:scatter": "node scripts/verify-scatter.mjs"
+    "verify:scatter": "node scripts/verify-scatter.mjs",
+    "verify:natural-rock-surfaces": "node scripts/verify-natural-rock-surfaces.mjs && node scripts/verify-natural-rock-replay.mjs"
   },
   "dependencies": {
     "3d-tiles-renderer": "^0.5.0",
     "pg": "^8.22.0"
   },
   "peerDependencies": {
-    "@react-three/fiber": "^9.0.0",
     "@dimforge/rapier3d-compat": "^0.19.0",
     "@pixiv/three-vrm": "^3.5.4",
+    "@react-three/fiber": "^9.0.0",
+    "react": "^19.0.0",
     "three": "^0.185.1",
-    "three-mesh-bvh": "^0.8.3",
-    "three-stdlib": "^2.36.1",
-    "react": "^19.0.0"
+    "three-mesh-bvh": "0.9.14",
+    "three-stdlib": "^2.36.1"
   },
   "peerDependenciesMeta": {
     "@react-three/fiber": {
@@ -436,9 +444,12 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "three": "^0.185.1",
-    "three-mesh-bvh": "^0.8.3",
+    "three-mesh-bvh": "0.9.14",
     "three-stdlib": "^2.36.1",
     "typescript": "^5.9.3",
-    "vite": "^5.0.0"
+    "vite": "^5.0.0",
+    "manifold-3d": "3.5.1",
+    "meshoptimizer": "1.1.1",
+    "three-bvh-csg": "0.0.18"
   }
 }

package/src/catalog/officialCatalog.js

@@ -2,3 +2,4 @@ export * from './officialCatalogProvider.js';
 export * from './officialCatalogAssetRuntime.js';
 export * from './officialCatalogLod.js';
 export * from './officialCatalogPlacement.js';
+export * from './officialCatalogRockPackage.js';

package/src/catalog/officialCatalogAssetRuntime.js

@@ -14,6 +14,10 @@ import {
   rockSemanticMaterialTextures,
 } from '../rock-shader/rockSemanticMaterialRuntime.js';
 import { OFFICIAL_CATALOG_ASSET_VERSION } from './officialCatalogProvider.js';
+import {
+  loadOfficialCatalogRockPackage,
+  loadOfficialCatalogRockShaderInput,
+} from './officialCatalogRockPackage.js';
 
 const rendererPools = new WeakMap();
 const headlessPools = new Map();
@@ -141,18 +145,25 @@ async function defaultPrepareTextures(root, asset) {
 export function createOfficialCatalogAssetRuntime({
   decoderBasePath = '/',
   loadModel = loadModelAsset,
+  loadRockPackage = loadOfficialCatalogRockPackage,
+  loadRockShaderInput = loadOfficialCatalogRockShaderInput,
   prepareTextures = defaultPrepareTextures,
   provider,
   renderer = null,
+  rockTextureLoader = null,
   transcodersFactory = createModelAssetTranscoders,
 } = {}) {
   if (!provider || typeof provider.getAsset !== 'function') {
     throw new TypeError('Official catalog asset runtime requires a provider with getAsset().');
   }
   if (typeof loadModel !== 'function') throw new TypeError('loadModel must be a function.');
+  if (typeof loadRockPackage !== 'function') throw new TypeError('loadRockPackage must be a function.');
+  if (typeof loadRockShaderInput !== 'function') throw new TypeError('loadRockShaderInput must be a function.');
   if (typeof prepareTextures !== 'function') throw new TypeError('prepareTextures must be a function.');
 
   const assetPromises = new Map();
+  const rockPackagePromises = new Map();
+  const rockShaderInputPromises = new Map();
   const sourcePromises = new Map();
   const sourceEntries = new Map();
   const handles = new Set();
@@ -190,6 +201,53 @@ export function createOfficialCatalogAssetRuntime({
     return assetPromises.get(id);
   }
 
+  async function getAsset(assetOrId) {
+    assertActive();
+    return resolveAsset(assetOrId);
+  }
+
+  async function getRockPackage(assetOrId, options = {}) {
+    assertActive();
+    const asset = await resolveAsset(assetOrId);
+    assertActive();
+    const includeManifest = options.includeManifest === true;
+    const includeNatureProvenance = options.includeNatureProvenance === true;
+    const key = `${asset.identity}|manifest:${includeManifest}|nature:${includeNatureProvenance}`;
+    if (!rockPackagePromises.has(key)) {
+      const promise = Promise.resolve(loadRockPackage(asset, options)).catch((error) => {
+        if (rockPackagePromises.get(key) === promise) rockPackagePromises.delete(key);
+        throw error;
+      });
+      rockPackagePromises.set(key, promise);
+    }
+    return rockPackagePromises.get(key);
+  }
+
+  async function getRockShaderInput(assetOrId) {
+    assertActive();
+    const asset = await resolveAsset(assetOrId);
+    assertActive();
+    if (!asset.packageFiles?.materialConfigUrl) return null;
+    const key = asset.identity;
+    if (!rockShaderInputPromises.has(key)) {
+      const promise = (async () => {
+        const rockPackage = await getRockPackage(asset);
+        const options = rockTextureLoader ? { textureLoader: rockTextureLoader } : {};
+        const input = await loadRockShaderInput(rockPackage, options);
+        if (disposed) {
+          Object.values(input?.textures ?? {}).forEach((texture) => texture.dispose?.());
+          throw new Error('Official catalog asset runtime was disposed while loading rock textures.');
+        }
+        return input;
+      })().catch((error) => {
+        if (rockShaderInputPromises.get(key) === promise) rockShaderInputPromises.delete(key);
+        throw error;
+      });
+      rockShaderInputPromises.set(key, promise);
+    }
+    return rockShaderInputPromises.get(key);
+  }
+
   async function sourceFor(asset) {
     const key = asset.identity;
     if (!sourcePromises.has(key)) {
@@ -273,7 +331,26 @@ export function createOfficialCatalogAssetRuntime({
 
   function evict(assetOrId, { force = false } = {}) {
     const entry = findEntry(assetOrId);
-    if (!entry) return false;
+    const identity = entry?.asset.identity ?? String(assetOrId?.identity ?? '');
+    const id = entry?.asset.id ?? String(assetOrId?.id ?? assetOrId ?? '');
+    const packageKeys = [...rockPackagePromises.keys()].filter((key) => (
+      (identity && key.startsWith(`${identity}|`)) || (!identity && key.includes(`:${id}@`))
+    ));
+    const shaderKeys = [...rockShaderInputPromises.keys()].filter((key) => (
+      key === identity || (!identity && key.includes(`:${id}@`))
+    ));
+    if (!entry && packageKeys.length === 0 && shaderKeys.length === 0) return false;
+    if (!entry) {
+      packageKeys.forEach((key) => rockPackagePromises.delete(key));
+      for (const key of shaderKeys) {
+        rockShaderInputPromises.get(key)?.then((input) => {
+          Object.values(input?.textures ?? {}).forEach((texture) => texture.dispose?.());
+        }).catch(() => {});
+        rockShaderInputPromises.delete(key);
+      }
+      assetPromises.delete(id);
+      return true;
+    }
     if (entry.refs > 0 && !force) return false;
     if (force) {
       for (const handle of [...handles]) {
@@ -284,6 +361,13 @@ export function createOfficialCatalogAssetRuntime({
     sourceEntries.delete(entry.asset.identity);
     sourcePromises.delete(entry.asset.identity);
     assetPromises.delete(entry.asset.id);
+    packageKeys.forEach((key) => rockPackagePromises.delete(key));
+    for (const key of shaderKeys) {
+      rockShaderInputPromises.get(key)?.then((input) => {
+        Object.values(input?.textures ?? {}).forEach((texture) => texture.dispose?.());
+      }).catch(() => {});
+      rockShaderInputPromises.delete(key);
+    }
     return true;
   }
 
@@ -297,6 +381,8 @@ export function createOfficialCatalogAssetRuntime({
         refs: entry.refs,
       }))),
       pendingAssets: sourcePromises.size - sourceEntries.size,
+      pendingRockPackages: rockPackagePromises.size,
+      cachedRockShaderInputs: rockShaderInputPromises.size,
     });
   }
 
@@ -305,10 +391,18 @@ export function createOfficialCatalogAssetRuntime({
     disposed = true;
     for (const handle of [...handles]) handle.release();
     await Promise.allSettled(sourcePromises.values());
+    const shaderInputs = await Promise.allSettled(rockShaderInputPromises.values());
+    for (const result of shaderInputs) {
+      if (result.status === 'fulfilled') {
+        Object.values(result.value?.textures ?? {}).forEach((texture) => texture.dispose?.());
+      }
+    }
     for (const entry of sourceEntries.values()) disposeResources(entry.resources);
     sourceEntries.clear();
     sourcePromises.clear();
     assetPromises.clear();
+    rockPackagePromises.clear();
+    rockShaderInputPromises.clear();
     transcoderLease?.release();
     transcoderLease = null;
   }
@@ -317,6 +411,9 @@ export function createOfficialCatalogAssetRuntime({
     acquireAsset,
     dispose,
     evict,
+    getAsset,
+    getRockPackage,
+    getRockShaderInput,
     get disposed() { return disposed; },
     provider,
     stats,

package/src/catalog/officialCatalogLod.js

@@ -1,4 +1,4 @@
-import { Vector3 } from 'three';
+import { Box3, Sphere, Vector3 } from 'three';
 
 const DEFAULT_LOD_NAME_PATTERN = /(?:^|[_\s.-])LOD[_\s.-]?(\d+)(?:$|[_\s.-])/iu;
 
@@ -97,16 +97,118 @@ export function selectCatalogLodLevel({
   return selected;
 }
 
+function normalizePixelThresholds(thresholds, levelCount) {
+  const count = Math.max(Math.round(Number(levelCount) || 1), 1);
+  const source = Array.isArray(thresholds) ? thresholds : [];
+  const normalized = [];
+  for (let level = 0; level < count; level += 1) {
+    const fallback = level === 0 ? 240 : Math.max((normalized[level - 1] ?? 240) * 0.45, 1);
+    const value = Number(source[level]);
+    normalized.push(Number.isFinite(value) && value > 0 ? value : fallback);
+  }
+  for (let level = 1; level < normalized.length; level += 1) {
+    normalized[level] = Math.min(normalized[level], normalized[level - 1] - 0.001);
+  }
+  return Object.freeze(normalized);
+}
+
+/**
+ * Resolve an authored LOD from its projected on-screen diameter. A null result
+ * is an intentional cull decision, not a missing-asset failure.
+ */
+export function selectCatalogLodLevelByProjectedPixels({
+  availableLevels,
+  cullBelowPixels = 0,
+  currentLevel = null,
+  hysteresis = 0,
+  pixelThresholds,
+  projectedPixels,
+} = {}) {
+  const available = [...new Set((availableLevels ?? []).map(finiteLevel).filter((v) => v !== null))]
+    .sort((left, right) => left - right);
+  if (available.length === 0) return null;
+  const pixels = Number(projectedPixels);
+  if (!Number.isFinite(pixels) || pixels < 0) {
+    throw new RangeError('Projected LOD pixels must be a finite non-negative number.');
+  }
+  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 cull = Math.max(Number(cullBelowPixels) || 0, 0);
+  const thresholds = normalizePixelThresholds(pixelThresholds, available.at(-1) + 1);
+  const current = finiteLevel(currentLevel);
+
+  if (pixels < cull) {
+    if (current !== null && available.includes(current) && margin > 0
+      && pixels >= cull * (1 - margin)) return current;
+    return null;
+  }
+
+  let requested = thresholds.length - 1;
+  for (let level = 0; level < thresholds.length; level += 1) {
+    if (pixels >= thresholds[level]) {
+      requested = level;
+      break;
+    }
+  }
+  const selected = available.filter((level) => level <= requested).at(-1) ?? available[0];
+  if (current === null || !available.includes(current) || margin === 0 || selected === current) {
+    return selected;
+  }
+
+  if (selected > current) {
+    const boundary = thresholds[current] ?? cull;
+    if (pixels >= boundary * (1 - margin)) return current;
+  } else {
+    const boundary = thresholds[selected] ?? thresholds[0];
+    if (pixels <= boundary * (1 + margin)) return current;
+  }
+  return selected;
+}
+
+/** Estimate projected object diameter for perspective and orthographic cameras. */
+export function estimateCatalogProjectedPixels({
+  camera,
+  distance,
+  referenceDiameter,
+  viewportHeight,
+} = {}) {
+  const pixelsHigh = Number(viewportHeight);
+  const diameter = Number(referenceDiameter);
+  if (!camera?.isCamera) throw new TypeError('Projected LOD estimation requires a Three.js camera.');
+  if (!Number.isFinite(pixelsHigh) || pixelsHigh <= 0) {
+    throw new RangeError('Projected LOD estimation requires a positive viewportHeight.');
+  }
+  if (!Number.isFinite(diameter) || diameter <= 0) {
+    throw new RangeError('Projected LOD estimation requires a positive referenceDiameter.');
+  }
+  if (camera.isOrthographicCamera) {
+    const span = Math.abs(Number(camera.top) - Number(camera.bottom)) / Math.max(Number(camera.zoom) || 1, 0.001);
+    return span > 0 ? diameter / span * pixelsHigh : Number.POSITIVE_INFINITY;
+  }
+  if (!camera.isPerspectiveCamera) {
+    throw new TypeError('Projected LOD estimation supports perspective and orthographic cameras.');
+  }
+  const range = Math.max(Number(distance) || 0, 0.0001);
+  const zoom = Math.max(Number(camera.zoom) || 1, 0.001);
+  const halfFov = Math.atan(Math.tan((Number(camera.fov) || 50) * Math.PI / 360) / zoom);
+  return diameter / (2 * range * Math.tan(halfFov)) * pixelsHigh;
+}
+
 /**
  * Authored, renderer-independent LOD controller. The host calls update() with
  * either a direct distance or a camera. World scale is removed from camera
  * distance so a uniformly enlarged landmark changes LOD at proportional range.
  */
 export function createCatalogLodRuntime(root, {
+  cullBelowPixels = 0,
   distances = [0, 45, 120],
   hysteresis = 0,
   maxLevel = Number.POSITIVE_INFINITY,
   namePattern = DEFAULT_LOD_NAME_PATTERN,
+  pixelThresholds = null,
+  referenceDiameter = null,
 } = {}) {
   const bindings = collectCatalogLodBindings(root, { namePattern });
   const availableLevels = Object.freeze(
@@ -119,27 +221,41 @@ export function createCatalogLodRuntime(root, {
   }
   const worldPosition = new Vector3();
   const worldScale = new Vector3();
+  const bounds = new Box3();
+  const sphere = new Sphere();
+  const usesScreenSpace = Array.isArray(pixelThresholds);
+  let localReferenceDiameter = Number(referenceDiameter);
+  if (!Number.isFinite(localReferenceDiameter) || localReferenceDiameter <= 0) {
+    root.updateWorldMatrix?.(true, true);
+    bounds.setFromObject(root, true).getBoundingSphere(sphere);
+    root.getWorldScale(worldScale);
+    const scale = Math.max(Math.abs(worldScale.x), Math.abs(worldScale.y), Math.abs(worldScale.z), 0.001);
+    localReferenceDiameter = Math.max(sphere.radius * 2 / scale, 0.001);
+  }
+  const normalizedPixelThresholds = usesScreenSpace
+    ? normalizePixelThresholds(pixelThresholds, availableLevels.at(-1) + 1)
+    : null;
   let currentLevel = null;
   let disposed = false;
 
   function setLevel(level) {
-    if (disposed || level === null || !availableLevels.includes(level)) return false;
+    if (disposed || (level !== null && !availableLevels.includes(level))) return false;
     if (currentLevel === level) return false;
     bindings.forEach((binding) => {
-      binding.mesh.visible = binding.level === level;
+      binding.mesh.visible = level !== null && binding.level === level;
     });
     currentLevel = level;
     return true;
   }
 
   function resolveDistance({ camera = null, distance = null } = {}) {
+    root.updateWorldMatrix?.(true, false);
+    root.getWorldPosition(worldPosition);
+    root.getWorldScale(worldScale);
     if (Number.isFinite(distance)) return Math.max(distance, 0);
     if (!camera?.getWorldPosition && !camera?.position) {
       throw new TypeError('Catalog LOD update requires distance or camera.');
     }
-    root.updateWorldMatrix?.(true, false);
-    root.getWorldPosition(worldPosition);
-    root.getWorldScale(worldScale);
     const cameraPosition = camera.getWorldPosition
       ? camera.getWorldPosition(new Vector3())
       : camera.position;
@@ -149,17 +265,42 @@ export function createCatalogLodRuntime(root, {
 
   function update(options = {}) {
     if (disposed || availableLevels.length === 0) return null;
-    const distance = resolveDistance(options);
-    const level = selectCatalogLodLevel({
-      availableLevels,
-      distance,
-      distances: thresholds,
-      currentLevel,
-      hysteresis: hysteresisRatio,
-      maxLevel,
-    });
+    const hasDirectPixels = Number.isFinite(Number(options.projectedPixels));
+    const distance = hasDirectPixels && !Number.isFinite(options.distance) && !options.camera
+      ? null
+      : resolveDistance(options);
+    const projectedPixels = hasDirectPixels
+      ? Math.max(Number(options.projectedPixels), 0)
+      : usesScreenSpace
+        ? estimateCatalogProjectedPixels({
+          camera: options.camera,
+          distance,
+          referenceDiameter: localReferenceDiameter * Math.max(
+            Math.abs(worldScale.x), Math.abs(worldScale.y), Math.abs(worldScale.z), 0.001,
+          ),
+          viewportHeight: options.viewportHeight,
+        })
+        : null;
+    let level = usesScreenSpace
+      ? selectCatalogLodLevelByProjectedPixels({
+        availableLevels,
+        cullBelowPixels,
+        currentLevel,
+        hysteresis: hysteresisRatio,
+        pixelThresholds: normalizedPixelThresholds,
+        projectedPixels,
+      })
+      : selectCatalogLodLevel({
+        availableLevels,
+        distance,
+        distances: thresholds,
+        currentLevel,
+        hysteresis: hysteresisRatio,
+        maxLevel,
+      });
+    if (level !== null) level = Math.min(level, Math.max(Number(maxLevel) || 0, 0));
     const changed = setLevel(level);
-    return Object.freeze({ changed, distance, level });
+    return Object.freeze({ changed, culled: level === null, distance, level, projectedPixels });
   }
 
   if (availableLevels.length > 0) setLevel(availableLevels[0]);
@@ -176,6 +317,9 @@ export function createCatalogLodRuntime(root, {
     get disposed() { return disposed; },
     get level() { return currentLevel; },
     setLevel,
+    cullBelowPixels: Math.max(Number(cullBelowPixels) || 0, 0),
+    pixelThresholds: normalizedPixelThresholds,
+    referenceDiameter: localReferenceDiameter,
     thresholds,
     hysteresis: hysteresisRatio,
     update,