@call-me-sensei/toonlab 0.2.0 → 0.3.0

package/src/soundscape/soundscapeSettings.js

@@ -0,0 +1,292 @@
+import { cloneSerializable, deepMerge, stableStringify } from '../core/generation.js';
+import { parsePresetDocument } from '../core/presetDocuments.js';
+
+export const SOUNDSCAPE_PRESET_TYPE = 'toonlab/soundscape-preset';
+export const SOUNDSCAPE_PRESET_VERSION = 1;
+
+export const SOUNDSCAPE_QUALITY_BUDGETS = Object.freeze({
+  mobile: Object.freeze({ maxLayers: 4, maxNodes: 32, maxVoices: 10 }),
+  balanced: Object.freeze({ maxLayers: 8, maxNodes: 64, maxVoices: 24 }),
+  cinematic: Object.freeze({ maxLayers: 16, maxNodes: 128, maxVoices: 48 }),
+});
+
+const DEFAULT_SETTINGS = Object.freeze({
+  adaptive: Object.freeze({
+    mappings: Object.freeze({
+      intensity: Object.freeze([
+        Object.freeze({ from: 0.62, mode: 'multiply', path: 'layers.air.gain', to: 1.18 }),
+        Object.freeze({ from: 0.35, mode: 'multiply', path: 'layers.wildlife.gain', to: 1.3 }),
+      ]),
+      tension: Object.freeze([
+        Object.freeze({ from: 0.72, mode: 'multiply', path: 'layers.drone.gain', to: 1.22 }),
+      ]),
+    }),
+    smoothing: 0.35,
+    values: Object.freeze({ intensity: 0.45, tension: 0.15, weather: 0.25 }),
+  }),
+  // The source preset carries the largest supported envelope. The resolver
+  // applies mobile/balanced/cinematic caps, so raising quality can actually
+  // make additional graph budget available without mutating the recipe.
+  budget: Object.freeze({ maxLayers: 16, maxNodes: 128, maxVoices: 48 }),
+  buses: Object.freeze({
+    ambience: Object.freeze({ gain: 0.78, mute: false }),
+    detail: Object.freeze({ gain: 0.62, mute: false }),
+    music: Object.freeze({ gain: 0.4, mute: false }),
+  }),
+  layers: Object.freeze({
+    air: Object.freeze({
+      bus: 'ambience',
+      enabled: true,
+      gain: 0.26,
+      pan: -0.08,
+      params: Object.freeze({ color: 'brown', highpass: 72, lowpass: 2800, movement: 0.18 }),
+      type: 'noise',
+      voiceLimit: 1,
+    }),
+    drone: Object.freeze({
+      bus: 'music',
+      enabled: true,
+      gain: 0.08,
+      pan: 0.04,
+      params: Object.freeze({ detune: 4, frequency: 82.41, movement: 0.05, waveform: 'sine' }),
+      type: 'oscillator',
+      voiceLimit: 1,
+    }),
+    rustle: Object.freeze({
+      bus: 'detail',
+      enabled: true,
+      gain: 0.11,
+      pan: 0.2,
+      params: Object.freeze({ color: 'pink', highpass: 900, lowpass: 6200, movement: 0.5 }),
+      type: 'noise',
+      voiceLimit: 1,
+    }),
+    wildlife: Object.freeze({
+      bus: 'detail',
+      enabled: true,
+      gain: 0.12,
+      pan: -0.16,
+      params: Object.freeze({ density: 0.22, duration: 0.18, frequency: 1550, pitchSpread: 0.38, waveform: 'sine' }),
+      type: 'procedural-events',
+      voiceLimit: 4,
+    }),
+  }),
+  master: Object.freeze({ gain: 0.72, limiter: true, transitionSeconds: 1.8 }),
+  snapshots: Object.freeze({
+    calm: Object.freeze({
+      buses: Object.freeze({ detail: Object.freeze({ gain: 0.42 }), music: Object.freeze({ gain: 0.28 }) }),
+      layers: Object.freeze({ drone: Object.freeze({ gain: 0.055 }), wildlife: Object.freeze({ gain: 0.08 }) }),
+    }),
+    dramatic: Object.freeze({
+      buses: Object.freeze({ detail: Object.freeze({ gain: 0.76 }), music: Object.freeze({ gain: 0.62 }) }),
+      layers: Object.freeze({ drone: Object.freeze({ gain: 0.16 }), wildlife: Object.freeze({ gain: 0.18 }) }),
+    }),
+  }),
+  transport: Object.freeze({ bpm: 88 }),
+});
+
+const BASE_PRESETS = new Map();
+
+function clamp(value, min, max, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.min(Math.max(number, min), max) : fallback;
+}
+
+function integer(value, min, max, fallback) {
+  return Math.round(clamp(value, min, max, fallback));
+}
+
+function plain(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function normalizeId(value) {
+  return String(value ?? '').trim().replace(/[^a-zA-Z0-9._/-]+/g, '_');
+}
+
+function sanitizeBus(input = {}) {
+  const source = plain(input);
+  return {
+    ...cloneSerializable(source),
+    gain: clamp(source.gain, 0, 2, 1),
+    mute: Boolean(source.mute),
+  };
+}
+
+function sanitizeLayer(input = {}, id = 'layer') {
+  const source = plain(input);
+  return {
+    ...cloneSerializable(source),
+    bus: String(source.bus || 'ambience'),
+    enabled: source.enabled !== false,
+    gain: clamp(source.gain, 0, 2, 0.25),
+    id,
+    pan: clamp(source.pan, -1, 1, 0),
+    params: cloneSerializable(plain(source.params)),
+    playbackRate: clamp(source.playbackRate, 0.05, 8, 1),
+    type: String(source.type || 'noise'),
+    voiceLimit: integer(source.voiceLimit, 1, 128, 1),
+  };
+}
+
+function sanitizeAdaptive(input = {}) {
+  const source = plain(input);
+  const values = Object.fromEntries(Object.entries(plain(source.values)).map(([id, value]) => (
+    [id, clamp(value, 0, 1, 0)]
+  )));
+  const mappings = {};
+  for (const [parameter, entries] of Object.entries(plain(source.mappings))) {
+    if (!Array.isArray(entries)) continue;
+    mappings[parameter] = entries
+      .filter((entry) => plain(entry).path)
+      .map((entry) => ({
+        curve: clamp(entry.curve, 0.05, 8, 1),
+        from: clamp(entry.from, -16, 16, 0),
+        mode: ['add', 'multiply', 'replace'].includes(entry.mode) ? entry.mode : 'replace',
+        path: String(entry.path),
+        to: clamp(entry.to, -16, 16, 1),
+      }));
+  }
+  return {
+    ...cloneSerializable(source),
+    mappings,
+    smoothing: clamp(source.smoothing, 0, 10, 0.35),
+    values,
+  };
+}
+
+export function applySoundscapeQualityBudget(settings, quality = 'balanced', override = {}) {
+  const tier = SOUNDSCAPE_QUALITY_BUDGETS[quality] ?? SOUNDSCAPE_QUALITY_BUDGETS.balanced;
+  const requested = plain(settings?.budget);
+  const explicit = plain(override);
+  const maxLayers = Math.min(integer(requested.maxLayers, 1, 1024, tier.maxLayers), tier.maxLayers, integer(explicit.maxLayers, 1, 1024, tier.maxLayers));
+  const maxNodes = Math.min(integer(requested.maxNodes, 2, 8192, tier.maxNodes), tier.maxNodes, integer(explicit.maxNodes, 2, 8192, tier.maxNodes));
+  const maxVoices = Math.min(integer(requested.maxVoices, 1, 2048, tier.maxVoices), tier.maxVoices, integer(explicit.maxVoices, 1, 2048, tier.maxVoices));
+  const layers = {};
+  let accepted = 0;
+  for (const [id, layer] of Object.entries(plain(settings?.layers))) {
+    if (accepted >= maxLayers) break;
+    layers[id] = { ...layer, voiceLimit: Math.min(layer.voiceLimit, maxVoices) };
+    accepted += 1;
+  }
+  return {
+    ...settings,
+    budget: { maxLayers, maxNodes, maxVoices },
+    layers,
+    quality: SOUNDSCAPE_QUALITY_BUDGETS[quality] ? quality : 'balanced',
+  };
+}
+
+export function sanitizeSoundscapeSettings(input = {}, { budget, quality } = {}) {
+  const source = input?.settings ? plain(input.settings) : plain(input);
+  const buses = Object.fromEntries(Object.entries(plain(source.buses)).map(([id, value]) => [id, sanitizeBus(value)]));
+  const layers = Object.fromEntries(Object.entries(plain(source.layers)).map(([id, value]) => [id, sanitizeLayer(value, id)]));
+  const settings = {
+    ...cloneSerializable(source),
+    adaptive: sanitizeAdaptive(source.adaptive),
+    budget: {
+      maxLayers: integer(source.budget?.maxLayers, 1, 1024, 8),
+      maxNodes: integer(source.budget?.maxNodes, 2, 8192, 64),
+      maxVoices: integer(source.budget?.maxVoices, 1, 2048, 24),
+    },
+    buses,
+    layers,
+    master: {
+      ...cloneSerializable(plain(source.master)),
+      gain: clamp(source.master?.gain, 0, 2, 0.72),
+      limiter: source.master?.limiter !== false,
+      transitionSeconds: clamp(source.master?.transitionSeconds, 0, 60, 1.8),
+    },
+    snapshots: cloneSerializable(plain(source.snapshots)),
+    transport: {
+      ...cloneSerializable(plain(source.transport)),
+      bpm: clamp(source.transport?.bpm, 20, 400, 88),
+    },
+  };
+  return quality || budget ? applySoundscapeQualityBudget(settings, quality ?? 'balanced', budget) : settings;
+}
+
+export function registerSoundscapeBasePreset(id, settings, { overwrite = false } = {}) {
+  const key = normalizeId(id);
+  if (!key) throw new Error('Soundscape base preset id is required.');
+  if (!overwrite && BASE_PRESETS.has(key)) throw new Error(`Soundscape base preset "${key}" already exists.`);
+  BASE_PRESETS.set(key, sanitizeSoundscapeSettings(deepMerge(DEFAULT_SETTINGS, settings)));
+  return key;
+}
+
+export function getSoundscapeBasePresetOptions() {
+  return [...BASE_PRESETS.keys()];
+}
+
+export function createSoundscapeSettings(input = {}, options = {}) {
+  const source = typeof input === 'string' ? { preset: input } : plain(input);
+  const presetId = source.preset ?? source.basePreset ?? 'living-landscape';
+  const base = BASE_PRESETS.get(presetId) ?? BASE_PRESETS.get('living-landscape') ?? DEFAULT_SETTINGS;
+  const override = source.settings ? source.settings : source;
+  const merged = deepMerge(base, override);
+  delete merged.preset;
+  delete merged.basePreset;
+  return sanitizeSoundscapeSettings(merged, options);
+}
+
+export function validateSoundscapePresetDocument(input) {
+  const errors = [];
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { errors: ['Soundscape preset must be a JSON object.'], ok: false, value: null, warnings: [] };
+  }
+  if (input.type !== SOUNDSCAPE_PRESET_TYPE) errors.push(`Soundscape preset type must be "${SOUNDSCAPE_PRESET_TYPE}".`);
+  const version = Number(input.version ?? 1);
+  if (!Number.isInteger(version) || version < 1 || version > SOUNDSCAPE_PRESET_VERSION) errors.push(`Unsupported soundscape preset version ${input.version}.`);
+  const id = normalizeId(input.id);
+  if (!id) errors.push('Soundscape preset id is required.');
+  return {
+    errors,
+    ok: errors.length === 0,
+    value: errors.length ? null : {
+      description: String(input.description ?? ''),
+      id,
+      label: String(input.label || id),
+      settings: sanitizeSoundscapeSettings(input.settings),
+      type: SOUNDSCAPE_PRESET_TYPE,
+      version: SOUNDSCAPE_PRESET_VERSION,
+    },
+    warnings: [],
+  };
+}
+
+export function createSoundscapePresetDocument(id, definition = {}) {
+  const result = validateSoundscapePresetDocument({
+    description: definition.description ?? '',
+    id,
+    label: definition.label ?? id,
+    settings: definition.settings ?? definition,
+    type: SOUNDSCAPE_PRESET_TYPE,
+    version: SOUNDSCAPE_PRESET_VERSION,
+  });
+  if (!result.ok) throw new Error(result.errors.join(' '));
+  return result.value;
+}
+
+export function parseSoundscapePresetDocument(input) {
+  return parsePresetDocument(input, validateSoundscapePresetDocument, { invalidJsonLabel: 'soundscape preset' });
+}
+
+export function serializeSoundscapePresetDocument(idOrDocument, definition = {}, { pretty = true } = {}) {
+  const document = idOrDocument && typeof idOrDocument === 'object'
+    ? createSoundscapePresetDocument(idOrDocument.id, idOrDocument)
+    : createSoundscapePresetDocument(idOrDocument, definition);
+  return stableStringify(document, pretty ? 2 : 0);
+}
+
+registerSoundscapeBasePreset('living-landscape', DEFAULT_SETTINGS);
+registerSoundscapeBasePreset('minimal-focus', deepMerge(DEFAULT_SETTINGS, {
+  adaptive: { values: { intensity: 0.25, tension: 0.05, weather: 0 } },
+  buses: { detail: { gain: 0.24 }, music: { gain: 0.2 } },
+  layers: {
+    air: { gain: 0.16 },
+    drone: { gain: 0.035 },
+    rustle: { enabled: false },
+    wildlife: { gain: 0.035, params: { density: 0.08 } },
+  },
+  master: { gain: 0.58 },
+}));

package/src/styles/index.js

@@ -0,0 +1,13 @@
+export {
+  createStyleBundleDocument,
+  DEFAULT_STYLE_BUNDLE_BASE_URL,
+  fetchStyleBundle,
+  parseStyleBundleDocument,
+  resolveStyleBundleSettings,
+  serializeStyleBundle,
+  STYLE_BUNDLE_DOCUMENT_TYPE,
+  STYLE_BUNDLE_SCHEMA_VERSION,
+  STYLE_BUNDLE_SLOT_IDS,
+  STYLE_BUNDLE_SLOTS,
+  validateStyleBundleDocument,
+} from './styleBundle.js';

package/src/styles/styleBundle.js

@@ -0,0 +1,325 @@
+// Style bundles — ONE named document that mixes and matches a preset per
+// system ("slot"): the toon look from one author, trees, grass, flowers and
+// water from others, sky, weather, environment, lighting and post on top.
+// Labs and games reference a bundle
+// (a local JSON or a published toonlab.io slug) and get every system's
+// resolved settings in one call:
+//
+//   import { fetchStyleBundle } from '@call-me-sensei/toonlab/styles';
+//   const { settings } = await fetchStyleBundle('sakura-dusk');
+//   applyToonShader(character, { settings: settings.toon });
+//   createWaterSurface({ settings: settings.water, ... });
+//
+// Each slot holds either { preset: '<built-in id>' } or { document: {…} } (a
+// full inline preset document of that system, self-contained). Publishing on
+// toonlab.io resolves any by-reference slots into inline documents, so a
+// fetched bundle always "has all the right ones" with zero further lookups.
+
+import {
+  createToonSettings,
+  parseToonPresetDocument,
+  TOON_PRESET_DOCUMENT_TYPE,
+} from '../toon/toonSettings.js';
+import {
+  createWaterSettings,
+  parseWaterPresetDocument,
+  WATER_PRESET_DOCUMENT_TYPE,
+} from '../water/waterSettings.js';
+import { createWeatherSettings } from '../weather/weatherSettings.js';
+import {
+  parseWeatherPresetDocument,
+  WEATHER_PRESET_DOCUMENT_TYPE,
+} from '../weather/weatherPresets.js';
+import { createEnvironmentSettings } from '../environment/environmentMaterialAdapter.js';
+import {
+  ENVIRONMENT_PRESET_DOCUMENT_TYPE,
+  resolveEnvironmentPreset,
+  validateEnvironmentPresetDocument,
+} from '../environment/environmentPresets.js';
+import { createPostProcessingSettings } from '../post/postProcessing.js';
+import {
+  createSkySettings,
+  parseSkyPresetDocument,
+  SKY_PRESET_DOCUMENT_TYPE,
+} from '../sky/stylizedSky.js';
+import {
+  createGrassSettings,
+  GRASS_PRESET_DOCUMENT_TYPE,
+  parseGrassPresetDocument,
+} from '../vegetation/stylizedGrass.js';
+import { createFlowerSettings } from '../vegetation/stylizedFlowers.js';
+import {
+  createVegetationShaderSettings,
+  parseVegetationShaderPresetDocument,
+  VEGETATION_SHADER_DOCUMENT_TYPE,
+} from '../vegetation/vegetationShaders.js';
+import {
+  TREE_RECIPE_SCHEMA,
+  validateTreeRecipeDocument,
+} from '../vegetation/treeRecipe.js';
+import { resolveLightingLookPreset } from '../lighting/lightingPresets.js';
+
+export const STYLE_BUNDLE_DOCUMENT_TYPE = 'toonlab/style-bundle';
+export const STYLE_BUNDLE_SCHEMA_VERSION = 1;
+export const DEFAULT_STYLE_BUNDLE_BASE_URL = 'https://toonlab.io';
+
+/**
+ * The bundle's slots: one per system, each resolving to that system's
+ * settings object. `documentType` is the inline preset document type the
+ * slot accepts (null = preset-id only), `resolve` turns the slot payload
+ * into ready settings.
+ */
+export const STYLE_BUNDLE_SLOTS = Object.freeze({
+  toon: Object.freeze({
+    documentType: TOON_PRESET_DOCUMENT_TYPE,
+    label: 'Character toon shading',
+    parseDocument: parseToonPresetDocument,
+    resolve: (payload) => createToonSettings(payload),
+  }),
+  tree: Object.freeze({
+    documentType: TREE_RECIPE_SCHEMA,
+    label: 'Trees',
+    // Tree recipes carry { type, options } (not .settings) and resolve to
+    // the recipe document itself — hand it to createPlantFromRecipe(
+    // settings.tree). No built-in preset ids: fill by document or creation.
+    parseDocument: validateTreeRecipeDocument,
+    resolve: (payload) => {
+      if (payload.document) return payload.document;
+      throw new Error(
+        `Style bundle slot "tree" has no built-in preset "${payload.preset}" — inline a tree recipe document or reference a saved recipe.`,
+      );
+    },
+  }),
+  grass: Object.freeze({
+    documentType: GRASS_PRESET_DOCUMENT_TYPE,
+    label: 'Grass',
+    parseDocument: parseGrassPresetDocument,
+    resolve: (payload) => createGrassSettings(payload.document?.settings ?? payload),
+  }),
+  flowers: Object.freeze({
+    documentType: null,
+    label: 'Flowers',
+    parseDocument: null,
+    resolve: (payload) => createFlowerSettings(payload),
+  }),
+  vegetationShader: Object.freeze({
+    documentType: VEGETATION_SHADER_DOCUMENT_TYPE,
+    label: 'Vegetation shader',
+    parseDocument: parseVegetationShaderPresetDocument,
+    resolve: (payload) => createVegetationShaderSettings(
+      payload.document?.settings ?? payload,
+    ),
+  }),
+  water: Object.freeze({
+    documentType: WATER_PRESET_DOCUMENT_TYPE,
+    label: 'Water',
+    parseDocument: parseWaterPresetDocument,
+    resolve: (payload) => createWaterSettings(payload.document?.settings ?? payload),
+  }),
+  sky: Object.freeze({
+    documentType: SKY_PRESET_DOCUMENT_TYPE,
+    label: 'Sky',
+    parseDocument: parseSkyPresetDocument,
+    resolve: (payload) => createSkySettings(payload.document?.settings ?? payload),
+  }),
+  weather: Object.freeze({
+    documentType: WEATHER_PRESET_DOCUMENT_TYPE,
+    label: 'Weather',
+    parseDocument: parseWeatherPresetDocument,
+    resolve: (payload) => createWeatherSettings(payload.document?.settings ?? payload),
+  }),
+  environment: Object.freeze({
+    documentType: ENVIRONMENT_PRESET_DOCUMENT_TYPE,
+    label: 'Environment',
+    // Environment preset documents carry { features, parameters } at the
+    // validated top level (not .settings like toon/water/weather).
+    parseDocument: (input) => validateEnvironmentPresetDocument(input),
+    resolve: (payload) => {
+      if (payload.document) {
+        const parsed = validateEnvironmentPresetDocument(payload.document);
+        if (!parsed.ok) throw new Error(parsed.errors.join(' '));
+        return createEnvironmentSettings({
+          features: parsed.value.features,
+          parameters: parsed.value.parameters,
+        });
+      }
+      const preset = resolveEnvironmentPreset(payload.preset);
+      return createEnvironmentSettings({ features: preset.features, parameters: preset.parameters });
+    },
+  }),
+  lighting: Object.freeze({
+    documentType: null,
+    label: 'Lighting',
+    parseDocument: null,
+    // Resolves to a lighting-look document (rig recipe + quality +
+    // environment/post hints) — apply through the lighting runtime.
+    resolve: (payload) => resolveLightingLookPreset(payload.preset),
+  }),
+  post: Object.freeze({
+    documentType: null,
+    label: 'Post processing',
+    parseDocument: null,
+    resolve: (payload) => createPostProcessingSettings(payload),
+  }),
+});
+
+export const STYLE_BUNDLE_SLOT_IDS = Object.freeze(Object.keys(STYLE_BUNDLE_SLOTS));
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Validate a style-bundle document. Returns { ok: true, value } with a
+ * normalized copy (unknown slots dropped, empty slots removed) or
+ * { ok: false, errors }.
+ */
+export function validateStyleBundleDocument(input) {
+  const errors = [];
+  const document = typeof input === 'string' ? tryParseJson(input, errors) : input;
+  if (!isPlainObject(document)) {
+    return { errors: errors.length ? errors : ['Style bundle must be a JSON object.'], ok: false };
+  }
+  if (document.schema !== STYLE_BUNDLE_DOCUMENT_TYPE) {
+    errors.push(`Expected schema "${STYLE_BUNDLE_DOCUMENT_TYPE}".`);
+  }
+  if (document.version !== STYLE_BUNDLE_SCHEMA_VERSION) {
+    errors.push(`Unsupported style bundle version ${document.version}.`);
+  }
+  const label = typeof document.label === 'string' ? document.label.trim() : '';
+  if (!label) errors.push('Style bundle needs a label.');
+
+  const slots = {};
+  const slotsInput = isPlainObject(document.slots) ? document.slots : {};
+  for (const [slotId, payload] of Object.entries(slotsInput)) {
+    const slot = STYLE_BUNDLE_SLOTS[slotId];
+    if (!slot) continue; // forward compatibility: ignore unknown slots
+    if (payload == null) continue;
+    if (!isPlainObject(payload)) {
+      errors.push(`Slot "${slotId}" must be an object.`);
+      continue;
+    }
+    const hasPreset = typeof payload.preset === 'string' && payload.preset.trim() !== '';
+    const hasDocument = isPlainObject(payload.document);
+    const hasCreation = typeof payload.creation === 'string' && payload.creation.trim() !== '';
+    if (!hasPreset && !hasDocument && !hasCreation) {
+      errors.push(`Slot "${slotId}" needs { preset }, { document } or { creation }.`);
+      continue;
+    }
+    if (hasDocument && slot.parseDocument) {
+      const parsed = slot.parseDocument(payload.document);
+      if (!parsed.ok) {
+        errors.push(`Slot "${slotId}" document: ${parsed.errors.join(' ')}`);
+        continue;
+      }
+      // Keep the RAW document — validation stays idempotent and serialized
+      // bundles round-trip byte-identical slot payloads.
+      slots[slotId] = { document: payload.document };
+      continue;
+    }
+    if (hasDocument && !slot.parseDocument) {
+      errors.push(`Slot "${slotId}" only accepts { preset } payloads.`);
+      continue;
+    }
+    slots[slotId] = hasPreset
+      ? { preset: payload.preset.trim() }
+      : { creation: payload.creation.trim() };
+  }
+
+  if (errors.length) return { errors, ok: false };
+  return {
+    ok: true,
+    value: {
+      description: typeof document.description === 'string' ? document.description : '',
+      id: typeof document.id === 'string' && document.id ? document.id : slugify(label),
+      label,
+      schema: STYLE_BUNDLE_DOCUMENT_TYPE,
+      slots,
+      version: STYLE_BUNDLE_SCHEMA_VERSION,
+    },
+  };
+}
+
+function tryParseJson(text, errors) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    errors.push('Style bundle is not valid JSON.');
+    return null;
+  }
+}
+
+function slugify(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'style-bundle';
+}
+
+export function createStyleBundleDocument(id, { description = '', label, slots = {} } = {}) {
+  const result = validateStyleBundleDocument({
+    description,
+    id,
+    label: label ?? id,
+    schema: STYLE_BUNDLE_DOCUMENT_TYPE,
+    slots,
+    version: STYLE_BUNDLE_SCHEMA_VERSION,
+  });
+  if (!result.ok) throw new Error(result.errors.join(' '));
+  return result.value;
+}
+
+export function serializeStyleBundle(document, { pretty = true } = {}) {
+  const result = validateStyleBundleDocument(document);
+  if (!result.ok) throw new Error(result.errors.join(' '));
+  return JSON.stringify(result.value, null, pretty ? 2 : 0);
+}
+
+export function parseStyleBundleDocument(input) {
+  return validateStyleBundleDocument(input);
+}
+
+/**
+ * Resolve a validated bundle into per-system settings objects:
+ * { toon?, tree?, grass?, flowers?, vegetationShader?, water?, sky?, weather?,
+ * environment?, lighting?, post? } — each ready to hand to the matching apply/create call
+ * (settings.tree is a recipe for createPlantFromRecipe, settings.lighting a
+ * lighting-look document). Unresolved by-reference slots
+ * ({ creation }) throw: fetch the bundle from toonlab.io (which inlines
+ * references) or inline the documents first.
+ */
+export function resolveStyleBundleSettings(document) {
+  const result = validateStyleBundleDocument(document);
+  if (!result.ok) throw new Error(result.errors.join(' '));
+  const settings = {};
+  for (const [slotId, payload] of Object.entries(result.value.slots)) {
+    const slot = STYLE_BUNDLE_SLOTS[slotId];
+    if (payload.creation) {
+      throw new Error(
+        `Style bundle slot "${slotId}" references creation "${payload.creation}" — fetch the published bundle (references resolve server-side) or inline the document.`,
+      );
+    }
+    settings[slotId] = slot.resolve(payload);
+  }
+  return settings;
+}
+
+/**
+ * Load a bundle by published slug (toonlab.io) or URL and resolve it.
+ *   const { document, settings } = await fetchStyleBundle('sakura-dusk');
+ */
+export async function fetchStyleBundle(ref, {
+  baseUrl = DEFAULT_STYLE_BUNDLE_BASE_URL,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const url = /^https?:\/\//.test(ref)
+    ? ref
+    : `${baseUrl.replace(/\/+$/, '')}/api/v1/bundles/${encodeURIComponent(ref)}`;
+  const response = await fetchImpl(url, { headers: { accept: 'application/json' } });
+  if (!response.ok) throw new Error(`Style bundle "${ref}" → HTTP ${response.status}`);
+  const body = await response.json();
+  const documentInput = body.bundle ?? body;
+  const result = validateStyleBundleDocument(documentInput);
+  if (!result.ok) throw new Error(`Style bundle "${ref}": ${result.errors.join(' ')}`);
+  return { document: result.value, settings: resolveStyleBundleSettings(result.value) };
+}

package/src/stylizedTerrain.js

@@ -1,5 +1,7 @@
 import * as THREE from 'three';
 
+import { deepMerge } from './core/generation.js';
+
 // Seeded stylized-terrain generator. Import from '@call-me-sensei/toonlab'.
 //
 // The randomization contract: ANY seed yields a valid, playable world.
@@ -104,6 +106,27 @@ export function getTerrainArchetypeOptions() {
   return Array.from(TERRAIN_ARCHETYPES.entries()).map(([id, a]) => ({ id, label: a.label }));
 }
 
+/**
+ * Registers an extensible terrain starting point. The definition is merged
+ * over `options.extends` (rollingPlains by default), so plugins can add new
+ * morphology families without modifying ToonLab or choosing from a fixed
+ * built-in catalog.
+ */
+export function registerTerrainArchetype(id, definition = {}, options = {}) {
+  const key = String(id ?? '').trim();
+  if (!key) throw new Error('Terrain archetype id is required.');
+  if (!options.overwrite && TERRAIN_ARCHETYPES.has(key)) {
+    throw new Error(`Terrain archetype "${key}" already exists.`);
+  }
+  const parentId = options.extends ?? 'rollingPlains';
+  const parent = TERRAIN_ARCHETYPES.get(parentId);
+  if (!parent) throw new Error(`Unknown parent terrain archetype "${parentId}".`);
+  const next = deepMerge(parent, definition);
+  next.label = String(definition.label || key);
+  TERRAIN_ARCHETYPES.set(key, next);
+  return { id: key, label: next.label };
+}
+
 const DEFAULT_PALETTE = {
   golden: 0xd2b24c,
   haze: 0xa9c6e8,
@@ -206,6 +229,10 @@ export function createStylizedTerrain({
   seed = 1,
   size = 1000,
   archetype = 'terracedKarst',
+  // Continuous morphology overrides turn archetypes into starting points,
+  // not a closed catalog. Any nested continent/mountains/rolling/rim/
+  // terraces value may be replaced by a generated biome recipe.
+  morphology = null,
   waterCoverage = null,           // 0..0.6; default from the archetype
   height = null,                  // H: mountain amplitude override (m)
   depth = null,                   // D: basin depth below the ground datum (m)
@@ -220,9 +247,12 @@ export function createStylizedTerrain({
   if (!base) {
     throw new Error(`Unknown terrain archetype "${archetype}" (have: ${[...TERRAIN_ARCHETYPES.keys()].join(', ')}).`);
   }
-  const spec = Number.isFinite(height)
-    ? { ...base, mountains: { ...base.mountains, amp: Math.max(height, 1) } }
+  const customized = morphology && typeof morphology === 'object'
+    ? deepMerge(base, morphology)
     : base;
+  const spec = Number.isFinite(height)
+    ? { ...customized, mountains: { ...customized.mountains, amp: Math.max(height, 1) } }
+    : customized;
   const coverage = Math.min(Math.max(
     Number.isFinite(waterCoverage) ? waterCoverage : spec.waterCoverage, 0), 0.6);
   const sizeX = Number.isFinite(size?.x) ? size.x : Number(size) || 1000;