@call-me-sensei/toonlab 0.4.21 → 0.4.22

package/NPM-LIBRARY.md

@@ -1,7 +1,7 @@
 # ToonLab npm library guide
 
 This guide is included in `@call-me-sensei/toonlab`. It is the package-first
-reference for version 0.4.21 and does not require access to the source
+reference for version 0.4.22 and does not require access to the source
 repository.
 
 ## Install
@@ -124,6 +124,55 @@ The host application still owns renderer creation, geometry and XZ layout,
 cameras, controls, gameplay, dynamic physics, navigation, persistence, and the
 frame loop. ToonLab does not turn a prompt into a finished world.
 
+## Load Nature Reference Rocks
+
+Version 0.4.22 understands both the original `rock-0001`–`rock-0480`
+identities and the `rock-c8-*` Nature Reference Rocks. Acquiring an asset
+directly returns its realistic PBR GLB. The one-call placement path additionally
+loads that asset's reviewed geology maps and `call_me_sensei` material settings
+before applying the selected style bundle.
+
+```js
+import {
+  createOfficialCatalogAssetRuntime,
+  createOfficialCatalogProvider,
+  createOfficialCatalogRockEditorDescriptor,
+  loadOfficialCatalogAsset,
+} from '@call-me-sensei/toonlab/official-catalog';
+import { CALL_ME_SENSEI_STYLE_BUNDLE } from '@call-me-sensei/toonlab/styles';
+
+const provider = createOfficialCatalogProvider({
+  baseUrl: 'https://toonlab.io/',
+  transport: 'public-rock',
+});
+const assets = createOfficialCatalogAssetRuntime({ provider, renderer });
+
+// Raw acquisition keeps the realistic PBR model.
+const realistic = await assets.acquireAsset('rock-c8-arch-sandstone');
+scene.add(realistic.root);
+
+// Placement loads the same rock's geology maps and applies Call Me Sensei.
+const stylized = await loadOfficialCatalogAsset({
+  assetId: 'rock-c8-arch-sandstone',
+  assetRuntime: assets,
+  parent: scene,
+  styleBundle: CALL_ME_SENSEI_STYLE_BUNDLE,
+});
+
+// Rock Lab/editor integrations receive the non-destructive authoring contract.
+const rockPackage = await assets.getRockPackage('rock-c8-arch-sandstone');
+const editorSource = createOfficialCatalogRockEditorDescriptor(
+  rockPackage.asset,
+  rockPackage,
+);
+```
+
+`editorSource` exposes `control.glb`, retained high detail, LOD0–LOD4,
+collision, recipe, material configuration, and the required post-sculpt
+reprojection/rebake/rebuild flags. These are immutable R2 URLs; the package
+does not embed any rock media. Release acquired handles and dispose the runtime
+when their scene lifetime ends.
+
 ## Install the agent guidance
 
 Everything in this section is present in the installed npm package.
@@ -169,7 +218,7 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
       "command": "npx",
       "args": [
         "-y",
-        "@call-me-sensei/toonlab@0.4.21",
+        "@call-me-sensei/toonlab@0.4.22",
         "--workspace",
         "/absolute/path/to/your-game/.toonlab"
       ],

package/README.md

@@ -19,7 +19,7 @@ Use ToonLab as a focused runtime library (`@call-me-sensei/toonlab` on npm), as
 an asset/preset authoring workspace, or as an asset-discovery service—not as a
 one-shot world generator.
 
-## Versioned expectation: 0.4.21
+## Versioned expectation: 0.4.22
 
 For a correctly constructed and semantically labeled scene, one strict Call Me
 Sensei bundle application is expected to establish the supported visual
@@ -277,8 +277,9 @@ Catalog data therefore does **not** use a separate downloadable “current
 seed,” and new datasets are **not** schema migrations. Keeping every released
 batch in the repository gives fresh and upgraded installations the same final
 catalog while preserving a simple, auditable upgrade path. The checked-in
-catalog currently contains 8,163 official assets: 480 first-party ToonLab
-rocks plus 7,683 verified open assets.
+catalog includes the original 480 first-party Stylized rocks, the 100-item
+Nature Reference Rocks by ToonLab collection, and the verified open-asset
+release. The two ToonLab rock collections keep distinct searchable identities.
 
 Applied filenames and SHA-256 digests are recorded in `schema_migrations` and
 `catalog_seed_batches`. Never edit, rename, or replace a released migration or

package/agents/PROMPTS.md

@@ -1,7 +1,7 @@
 # ToonLab agent prompts
 
 These prompts are included with the npm package. They use only the supported
-0.4.21 runtime, agent skills, and MCP workflows.
+0.4.22 runtime, agent skills, and MCP workflows.
 
 ## Existing-scene integration
 

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();
+}