@call-me-sensei/toonlab 0.2.0 → 0.3.1

package/docs/mcp.md

@@ -0,0 +1,97 @@
+# Local MCP and `.toonlab` workspace
+
+The open-source ToonLab server is a local [Model Context Protocol](https://modelcontextprotocol.io/)
+server that lets coding agents use the same assets and recipes as the browser
+labs. It uses the stdio transport and does not require a ToonLab account,
+OAuth, or a hosted service.
+
+## Start and connect
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://localhost:5175/settings/` and copy the generated JSON into your
+client's local MCP configuration. The paths are absolute so the client can
+start the server from any working directory.
+
+You can also start the server directly:
+
+```bash
+npm run mcp -- --workspace /absolute/path/to/project/.toonlab
+```
+
+When installed from npm, the package exposes the `toonlab-mcp` binary:
+
+```bash
+npx -y @call-me-sensei/toonlab@latest --workspace /absolute/path/to/project/.toonlab
+```
+
+## Workspace layout
+
+`.toonlab/` is the local source of truth and is ignored by Git by default.
+
+```text
+.toonlab/
+  assets/           # project-owned asset files
+  creations/        # MCP-created recipes and documents
+  exports/          # copies of files exported from browser labs
+  imports/          # downloaded CC0 bundles and attribution manifests
+  library/entries/  # catalog entries saved from any lab
+  presets/          # portable preset files
+  storage/          # browser lab documents mirrored as JSON
+  toonlab.json      # workspace version and migration markers
+```
+
+Existing ToonLab `localStorage` and IndexedDB catalog data is imported the
+first time the local Vite server sees it. After that, disk wins at startup and
+browser changes are mirrored back to disk. The current synchronous lab stores
+therefore keep working without hiding data from MCP.
+
+Provider API keys are intentionally excluded from the workspace. They remain
+in browser storage and are never made available to MCP.
+
+## Tools
+
+The OSS server currently exposes:
+
+- `get_workspace_info` — workspace path, version, and migration status.
+- `search_assets` / `get_asset` — built-in procedural catalog, saved library,
+  lab documents, presets, imports, and exports.
+- `list_my_creations` / `get_my_creation` / `save_creation` — direct local
+  project persistence.
+- `generate_asset` — deterministic seeded recipes from built-in catalog
+  entries, saved into `.toonlab/creations` by default.
+- `search_cc0_assets` / `get_cc0_asset` / `import_cc0_asset` — public CC0
+  models, textures, and HDRIs from Poly Haven and ambientCG, including source
+  and attribution metadata.
+- `get_generation_capabilities` — a machine-readable description of what is
+  local versus hosted-Pro functionality.
+- `list_style_labs` — the seven open-ended style generators, browser paths,
+  npm runtime imports, extension families, and generation capabilities.
+- `create_style_recipe` — create and optionally save a portable Post, Camera,
+  Motion, UI Theme, Biome, Soundscape, or Game Feel generator recipe.
+- `generate_style_presets` — resolve and validate one to 64 deterministic
+  runtime presets from any style recipe; consecutive seeds make large design
+  searches efficient without a fixed catalog.
+- `validate_style_document` — validate a generator recipe or resolved preset
+  against the selected lab schema.
+
+The server also exposes assets as `toonlab://asset/...` MCP resources. Small
+JSON/text files and binaries can be read inline; every disk file includes an
+absolute path so local development tools can consume larger files directly.
+
+Style generation is a design-time workflow. Labs and MCP author recipes and
+resolve candidates; the `@call-me-sensei/toonlab/*` npm subpaths own the
+shipping runtime that applies the selected flat preset. See
+[Generative style labs](style-labs.md) for the shared recipe contract and all
+seven runtime APIs.
+
+## OSS and Pro boundary
+
+Open source owns the local workflow: disk persistence, procedural generation,
+CC0 discovery/import, and stdio MCP. ToonLab Pro can use the same conceptual
+tool schemas with cloud adapters, adding remote Streamable HTTP + OAuth,
+private cloud libraries, cross-device/team sync, and managed image/3D
+generation providers.

package/docs/post-processing.md

@@ -0,0 +1,98 @@
+# Post-processing
+
+An optional single-pipeline compositor (`@call-me-sensei/toonlab/post`). Disabled by
+default — the character shader stays responsible for face quality, and raw
+shader output remains easy to evaluate. When disabled, the pipeline renders
+the scene straight through with zero overhead.
+
+The compositor targets the TSL renderer stack. Native WebGPU is the default;
+`?renderer=webgl` exercises the WebGL2 fallback through the same node graph.
+
+## Pipeline
+
+```js
+import { createPostProcessingPipeline } from '@call-me-sensei/toonlab/post';
+
+const post = createPostProcessingPipeline({
+  renderer, scene, camera,
+  settings: { preset: 'softAnime' },
+});
+
+// render loop — replaces renderer.render(scene, camera):
+post.render(delta);
+
+// on resize:
+post.setSize(window.innerWidth, window.innerHeight, window.devicePixelRatio);
+
+// live re-tune:
+post.setSettings({ features: { bloom: true }, parameters: { bloomStrength: 0.35 } });
+
+// character-aware bloom (mask from createCharacterRenderPasses):
+post.setCharacterMask(passes.characterMaskTexture);
+```
+
+(Inside this repo the labs import from `../../src/post/...`.)
+
+The pipeline renders the scene into a color+depth target and composites in
+one screen pass. `post.enabled` and `post.settings` are live getters;
+`isPostProcessingEnabled(settings)` answers the same question for a plain
+settings object.
+
+## Features and parameters
+
+Settings are `{ preset, features, parameters }`, normalized by
+`createPostProcessingSettings(options)`. Features (all `false` by default):
+
+| Feature | Parameters |
+|---|---|
+| `bloom` | `bloomStrength/Threshold/Radius`, `bloomMode` (`'single'` one-pass 9-tap, or `'pyramid'` dual-filter mip chain + `bloomLevels`), character-aware `bloomCharacterBoost` / `bloomBackgroundSuppress` |
+| `colorGrade` | `exposure`, `contrast`, `saturation`, `warmth`, plus the LUT: `lutMap` (2D-strip texture), `lutSize`, `lutStrength` |
+| `verticalGrade` | `topLight`, `bottomDark` |
+| `vignette` | `vignetteStrength/Radius/Softness` |
+| `screenOutline` | `outlineStrength`, `outlineDepthStrength`, `outlineLumaStrength`, `outlineColor` |
+| `depthCue` | `depthCueStrength/Near/Far`, `depthCueColor` — distance haze tint |
+| `motionBlur` | `motionBlurStrength` — camera-reprojection blur (camera movement only; there is no per-bone velocity buffer) |
+| `enabled` | master switch; `strength` scales the whole composite |
+
+All 37 fields with ranges and defaults:
+[settings reference](settings-reference.md#post-processing)
+(`POST_PROCESSING_SETTING_GROUPS` / `POST_PROCESSING_SETTING_FIELD_SCHEMA`).
+`lutMap` is a runtime texture object and is not JSON-serializable.
+
+## Presets and preset documents
+
+Built-ins in `POST_PROCESSING_PRESETS`: `off`, `custom`, `softAnime` (subtle
+presentation grade), `call_me_sensei` (studio-managed signature grade,
+updated over releases), `showcase` (feature tour with demo values), and
+`debugEdges` (outline diagnosis). Select with
+`createPostProcessingSettings({ preset: 'softAnime' })`, or in the labs
+`?post=1&postPreset=softAnime` (`?postAdvanced=1` exposes the raw controls).
+
+Register your own, in code or as a versioned JSON document
+(`toonlab/post-processing-preset`), matching the toon/water/environment
+preset document pattern:
+
+```js
+import {
+  registerPostProcessingPreset,
+  createPostProcessingPresetDocument,
+  validatePostProcessingPresetDocument,
+  getPostProcessingPresetOptions,
+} from '@call-me-sensei/toonlab/post';
+
+registerPostProcessingPreset('filmicNight', {
+  label: 'Filmic Night',
+  features: { bloom: true, colorGrade: true, vignette: true },
+  parameters: { bloomStrength: 0.4, warmth: -0.08, vignetteStrength: 0.3 },
+});
+
+const document = createPostProcessingPresetDocument('filmicNight');
+// share JSON.stringify(document); load elsewhere:
+const result = validatePostProcessingPresetDocument(document);
+if (result.ok) registerPostProcessingPreset(result.value.id, result.value, { overwrite: true });
+
+getPostProcessingPresetOptions(); // [{ id, label, description }] for HUDs
+```
+
+`sanitizePostProcessingPresetSettings` clamps and filters a raw settings
+object against the schema.