@call-me-sensei/toonlab 0.1.1 → 0.3.0

package/docs/debug-panel.md

@@ -0,0 +1,126 @@
+# Debug panel
+
+`@call-me-sensei/toonlab/debug` is an optional, DOM-dependent tuning GUI: it turns any
+settings module's group/field schema into live controls. One call gives you
+the same panel the labs use — ship it behind a debug flag, or not at all
+(nothing else imports it).
+
+The labs now expose one TSL renderer stack: native WebGPU by default and
+`?renderer=webgl` for the WebGL2 fallback. The panel writes the same settings
+surface on both backends.
+
+## createSettingsPanel
+
+```js
+import { createSettingsPanel } from '@call-me-sensei/toonlab/debug';
+import { readFieldValueFromSettings } from '@call-me-sensei/toonlab/debug';
+import {
+  TOON_SETTING_GROUPS,
+  TOON_SETTING_FIELD_SCHEMA,
+  applyToonSettingsToMaterial,
+} from '@call-me-sensei/toonlab/toon';
+
+const panel = createSettingsPanel({
+  container: document.getElementById('toonSettingGroups'),
+  groups: TOON_SETTING_GROUPS,
+  fieldSchema: TOON_SETTING_FIELD_SCHEMA,
+  getValue: (field) => readFieldValueFromSettings(settings, field),
+  onChange: (field, value) => {
+    settings[field.group][field.key] = value;
+    applyToonSettingsToMaterial(characterRoot, settings);
+  },
+});
+
+panel.refresh(); // re-pull every control value via getValue (e.g. after a preset switch)
+```
+
+(Inside this repo the labs import from `../../src/debug/...`.)
+
+The panel renders one collapsible `<details>` group per schema group, with a
+typed control per field — checkbox for `boolean`, `<select>` for `select`
+(using the schema's `options`/`optionLabels`), color input for `color`,
+range slider for `number` (using the schema's `range`), text input
+otherwise — each with a label, tooltip description, and live `<output>`
+readout.
+
+The host owns the settings state: the panel only reads through `getValue`
+and reports edits through `onChange`. It never mutates settings itself,
+which is what makes it schema-generic.
+
+### Options
+
+Beyond the required five, `createSettingsPanel` accepts:
+
+- `fieldFilter(field)` — hide fields (e.g. non-serializable texture slots).
+- `isDisabled(field)` — gray controls out (re-evaluated on `refresh()`).
+- `formatValue(value, field)` — custom `<output>` formatting.
+- `isGroupOpen(group)` — which groups start expanded.
+- `prepend` — DOM nodes to insert before the groups (preset pickers, etc.).
+- `dataAttribute`, `idPrefix`, `rowClassName`, `groupClassName`,
+  `fieldsClassName` — styling/data hooks.
+
+### It works with every schema
+
+Any module following the groups + field-schema convention plugs in — this is
+the full list (see the generated
+[settings reference](settings-reference.md) for their contents):
+
+| Module | groups / fieldSchema |
+|---|---|
+| `@call-me-sensei/toonlab/toon` | `TOON_SETTING_GROUPS` / `TOON_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/environment` | `ENVIRONMENT_SETTING_GROUPS` / `ENVIRONMENT_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/water` | `WATER_SETTING_GROUPS` / `WATER_SETTING_FIELD_SCHEMA_BY_GROUP` |
+| `@call-me-sensei/toonlab/post` | `POST_PROCESSING_SETTING_GROUPS` / `POST_PROCESSING_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/vegetation` (grass) | `GRASS_SETTING_GROUPS` / `GRASS_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/vegetation` (flowers) | `FLOWER_SETTING_GROUPS` / `FLOWER_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/vegetation` (trees) | `STYLIZED_TREE_SETTING_GROUPS` / `STYLIZED_TREE_SETTING_FIELD_SCHEMA` |
+| `@call-me-sensei/toonlab/sky` | `SKY_SETTING_GROUPS` / `SKY_SETTING_FIELD_SCHEMA` |
+
+Note the value-read difference: toon/environment/post/tree settings are
+nested (`settings[field.group][field.key]`), water/grass/flower/sky settings
+are flat (`settings[field.key]`). `readFieldValueFromSettings` handles the
+nested case; for flat settings pass
+`getValue: (field) => settings[field.key]`.
+
+## createSelectRow
+
+A plain labeled `<select>` row for the controls that live alongside the
+schema-generated groups (preset pickers, debug-view selectors):
+
+```js
+import { createSelectRow } from '@call-me-sensei/toonlab/debug';
+
+const row = createSelectRow({
+  id: 'toonPreset',
+  label: 'Preset',
+  options: getToonPresetOptions().map((p) => ({ value: p.id, label: p.label })),
+  value: currentPreset,
+  onChange: (value) => setLabParams({ toonPreset: value }),
+});
+panelHeader.append(row);
+```
+
+## Field value helpers (`fieldValues.js`)
+
+The coercion layer between schema-typed values and DOM control values, used
+by the panel and exported for custom UIs:
+
+- `readFieldValueFromSettings(settings, field)` — nested group/key read.
+- `readFieldValueFromControl(control, field)` — checkbox/range/color/select
+  → typed value (colors become `[r, g, b]` arrays, numbers parse, etc.).
+- `writeFieldControlValue(control, output, field, value)` — push a value
+  into a control and its `<output>`.
+- `formatFieldValue(value, field)` — display formatting.
+- `colorToHex(value)` / `hexToColorArray(value)` — `[r, g, b]` ↔ `#rrggbb`.
+- `vectorToArray(value)` — vector-ish → plain array.
+
+## How the labs use it
+
+Character Shader Lab and Environment Shader Lab consume their respective
+schemas independently. Each lab's panel is a thin consumer that wires
+`getValue`/`onChange` to its preset store and to
+`applyToonSettingsToMaterial` or `applyEnvironmentSettingsToMaterial` for
+live uniform-safe edits. Preset switching refreshes the controls from the
+normalized package settings. The same schema-consumer pattern drives Water,
+Sky, Grass, Tree, and Flower Labs; no lab keeps a private copy of its runtime
+parameter contract.

package/docs/docs.css

@@ -0,0 +1,589 @@
+/* ToonLab OSS docs — matches the labs home look (tokens duplicated per page,
+   same convention as home.css / settings.css). */
+
+:root {
+  --tl-bg-0: #0b0c0f;
+  --tl-bg-1: #111318;
+  --tl-bg-2: #191b21;
+  --tl-line: rgb(242 240 233 / 0.09);
+  --tl-line-bright: rgb(242 240 233 / 0.18);
+  --tl-ink-1: #f2f0e9;
+  --tl-ink-2: #a6a5a1;
+  --tl-ink-3: #62636b;
+  --tl-accent: #e8332e;
+  --tl-accent-hot: #ff4a42;
+  --tl-accent-deep: #b3201f;
+  --tl-ao: #3d7eff;
+  --tl-gold: #c9a24b;
+  --tl-font-display: "M PLUS 1", "Zen Kaku Gothic New", "Inter", system-ui, sans-serif;
+  --tl-font-jp: "Zen Kaku Gothic New", "M PLUS 1", sans-serif;
+  --tl-font-ui: "Inter", "M PLUS 1", system-ui, -apple-system, sans-serif;
+  --tl-font-mono: "JetBrains Mono", ui-monospace, monospace;
+  --tl-ease: cubic-bezier(0.22, 1, 0.36, 1);
+  --tl-dur-1: 120ms;
+  --tl-dur-2: 220ms;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+html {
+  scroll-behavior: smooth;
+}
+
+body {
+  background: var(--tl-bg-0);
+  color: var(--tl-ink-1);
+  font-family: var(--tl-font-ui);
+  -webkit-font-smoothing: antialiased;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+/* ---- Header (mirrors home-header) ---- */
+
+.docs-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 18px 28px;
+  border-bottom: 1px solid var(--tl-line);
+}
+
+.docs-brand {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.docs-brand-mark {
+  display: grid;
+  place-items: center;
+  width: 30px;
+  height: 30px;
+  background: var(--tl-accent);
+  color: #fff;
+  font-family: var(--tl-font-jp);
+  font-weight: 900;
+  font-size: 17px;
+  clip-path: polygon(0 0, 100% 0, 100% 78%, 78% 100%, 0 100%);
+}
+
+.docs-brand-word {
+  font-family: var(--tl-font-display);
+  font-weight: 800;
+  letter-spacing: 0.16em;
+  font-size: 15px;
+}
+
+.docs-brand-tag {
+  font-family: var(--tl-font-mono);
+  font-size: 10px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--tl-ink-3);
+  border: 1px solid var(--tl-line-bright);
+  padding: 3px 7px;
+  border-radius: 2px;
+}
+
+.docs-topnav {
+  display: flex;
+  align-items: center;
+  gap: 26px;
+}
+
+.docs-topnav a {
+  font-family: var(--tl-font-display);
+  font-size: 13px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--tl-ink-2);
+  transition: color var(--tl-dur-1) var(--tl-ease);
+}
+
+.docs-topnav a:hover,
+.docs-topnav a[aria-current="page"] {
+  color: var(--tl-ink-1);
+}
+
+/* ---- Frame ---- */
+
+.docs-frame {
+  display: grid;
+  grid-template-columns: 220px minmax(0, 1fr);
+  gap: 48px;
+  max-width: 1080px;
+  margin: 0 auto;
+  padding: 48px 24px 96px;
+}
+
+.docs-side {
+  position: sticky;
+  top: 24px;
+  align-self: start;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.docs-side-label {
+  font-family: var(--tl-font-mono);
+  font-size: 11px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--tl-accent);
+}
+
+.docs-nav {
+  display: flex;
+  flex-direction: column;
+  border-left: 1px solid var(--tl-line);
+}
+
+.docs-nav a {
+  padding: 8px 14px;
+  font-size: 14px;
+  color: var(--tl-ink-2);
+  border-left: 2px solid transparent;
+  margin-left: -1px;
+  transition: color var(--tl-dur-1) var(--tl-ease);
+}
+
+.docs-nav a:hover {
+  color: var(--tl-ink-1);
+}
+
+.docs-nav a.active {
+  color: var(--tl-ink-1);
+  border-left-color: var(--tl-accent);
+}
+
+.docs-side-foot {
+  display: flex;
+  gap: 14px;
+  padding-top: 6px;
+}
+
+.docs-side-foot a {
+  font-size: 12px;
+  color: var(--tl-ink-3);
+}
+
+.docs-side-foot a:hover {
+  color: var(--tl-ink-1);
+}
+
+/* ---- Content ---- */
+
+.docs-main {
+  min-width: 0;
+  max-width: 720px;
+}
+
+.docs-eyebrow {
+  font-family: var(--tl-font-mono);
+  font-size: 11px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--tl-accent);
+  margin-bottom: 14px;
+}
+
+.docs-main h1 {
+  font-family: var(--tl-font-display);
+  font-size: clamp(28px, 4vw, 38px);
+  font-weight: 800;
+  letter-spacing: -0.01em;
+  line-height: 1.15;
+  margin: 0 0 14px;
+}
+
+.docs-lede {
+  font-size: 16px;
+  line-height: 1.65;
+  color: var(--tl-ink-2);
+  margin: 0 0 36px;
+  max-width: 60ch;
+}
+
+.docs-main h2 {
+  font-family: var(--tl-font-display);
+  font-size: 21px;
+  font-weight: 700;
+  margin: 48px 0 12px;
+  padding-top: 24px;
+  border-top: 1px solid var(--tl-line);
+}
+
+.docs-main h3 {
+  font-size: 16px;
+  font-weight: 600;
+  margin: 28px 0 8px;
+}
+
+.docs-main p {
+  font-size: 14.5px;
+  line-height: 1.7;
+  color: var(--tl-ink-2);
+  margin: 0 0 14px;
+  max-width: 65ch;
+}
+
+.docs-main p strong,
+.docs-main li strong {
+  color: var(--tl-ink-1);
+}
+
+.docs-main a:not(.docs-card) {
+  /* Lightened from --tl-ao: the UI-link blue is too dim for 14.5px body
+     text on --tl-bg-0 (~4:1); this holds ~8:1 in dense paragraphs. */
+  color: #8fb3ff;
+}
+
+.docs-main a:not(.docs-card):hover {
+  text-decoration: underline;
+}
+
+.docs-main ul,
+.docs-main ol {
+  margin: 0 0 14px;
+  padding-left: 22px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.docs-main li {
+  font-size: 14.5px;
+  line-height: 1.65;
+  color: var(--tl-ink-2);
+}
+
+.docs-main code {
+  font-family: var(--tl-font-mono);
+  font-size: 0.92em;
+  background: var(--tl-bg-2);
+  border: 1px solid var(--tl-line);
+  border-radius: 2px;
+  padding: 1px 5px;
+}
+
+/* ---- Pro badge ---- */
+
+.docs-pro {
+  display: inline-flex;
+  align-items: center;
+  font-family: var(--tl-font-mono);
+  font-size: 10px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--tl-gold);
+  border: 1px solid rgb(201 162 75 / 0.45);
+  background: rgb(201 162 75 / 0.08);
+  padding: 2px 7px;
+  border-radius: 2px;
+  vertical-align: 2px;
+  margin-left: 8px;
+  white-space: nowrap;
+}
+
+/* ---- Code + prompt blocks ---- */
+
+.docs-codeblock {
+  position: relative;
+  margin: 16px 0 20px;
+  border: 1px solid var(--tl-line);
+  border-radius: 4px;
+  background: var(--tl-bg-1);
+  overflow: hidden;
+}
+
+.docs-codeblock-label {
+  font-family: var(--tl-font-mono);
+  font-size: 10.5px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--tl-ink-3);
+  padding: 8px 14px 0;
+}
+
+.docs-codeblock pre {
+  margin: 0;
+  padding: 14px;
+  overflow-x: auto;
+}
+
+.docs-codeblock code {
+  font-family: var(--tl-font-mono);
+  font-size: 12.5px;
+  line-height: 1.6;
+  color: var(--tl-ink-1);
+  background: none;
+  border: none;
+  padding: 0;
+  white-space: pre;
+}
+
+.docs-codeblock-copy {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-family: var(--tl-font-ui);
+  font-size: 11px;
+  padding: 4px 10px;
+  color: var(--tl-ink-2);
+  background: var(--tl-bg-2);
+  border: 1px solid var(--tl-line-bright);
+  border-radius: 3px;
+  cursor: pointer;
+  transition: color var(--tl-dur-1) var(--tl-ease), border-color var(--tl-dur-1) var(--tl-ease);
+}
+
+.docs-codeblock-copy:hover {
+  color: var(--tl-ink-1);
+  border-color: var(--tl-ink-3);
+}
+
+.docs-promptblock {
+  margin: 20px 0 28px;
+}
+
+.docs-promptblock-title {
+  font-weight: 600;
+  font-size: 14.5px;
+  color: var(--tl-ink-1);
+}
+
+.docs-promptblock .docs-codeblock {
+  margin-top: 10px;
+  margin-bottom: 8px;
+}
+
+.docs-promptblock .docs-codeblock code {
+  white-space: pre-wrap;
+  color: var(--tl-ink-2);
+}
+
+.docs-promptblock-note {
+  font-size: 13px;
+  color: var(--tl-ink-3);
+  margin: 0;
+}
+
+/* ---- Cards, callouts, tables ---- */
+
+.docs-cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 14px;
+  margin: 20px 0 8px;
+}
+
+.docs-card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 18px;
+  border: 1px solid var(--tl-line);
+  border-radius: 4px;
+  background: var(--tl-bg-1);
+  transition: border-color var(--tl-dur-1) var(--tl-ease);
+}
+
+.docs-card:hover {
+  border-color: var(--tl-line-bright);
+}
+
+.docs-card strong {
+  color: var(--tl-ink-1);
+  font-size: 15px;
+}
+
+.docs-card span {
+  font-size: 13px;
+  line-height: 1.55;
+  color: var(--tl-ink-2);
+}
+
+.docs-card svg {
+  color: var(--tl-accent);
+}
+
+.docs-callout {
+  display: flex;
+  gap: 12px;
+  padding: 14px 16px;
+  margin: 16px 0 20px;
+  border: 1px solid var(--tl-line);
+  border-left: 2px solid var(--tl-accent);
+  border-radius: 4px;
+  background: linear-gradient(120deg, rgb(232 51 46 / 0.12), rgb(232 51 46 / 0.03));
+  font-size: 13.5px;
+  line-height: 1.6;
+  color: var(--tl-ink-2);
+}
+
+.docs-callout--pro {
+  border-left-color: var(--tl-gold);
+  background: linear-gradient(120deg, rgb(201 162 75 / 0.1), rgb(201 162 75 / 0.02));
+}
+
+.docs-callout svg {
+  flex-shrink: 0;
+  margin-top: 2px;
+  color: var(--tl-accent);
+}
+
+.docs-callout--pro svg {
+  color: var(--tl-gold);
+}
+
+.docs-table-wrap {
+  overflow-x: auto;
+  margin: 16px 0 20px;
+  border: 1px solid var(--tl-line);
+  border-radius: 4px;
+}
+
+.docs-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 13.5px;
+}
+
+.docs-table th {
+  text-align: left;
+  font-family: var(--tl-font-mono);
+  font-size: 10.5px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--tl-ink-3);
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--tl-line);
+  background: var(--tl-bg-1);
+}
+
+.docs-table td {
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--tl-line);
+  color: var(--tl-ink-2);
+  vertical-align: top;
+  line-height: 1.55;
+}
+
+.docs-table tr:last-child td {
+  border-bottom: none;
+}
+
+.docs-table td:first-child {
+  font-family: var(--tl-font-mono);
+  font-size: 12.5px;
+  color: var(--tl-ink-1);
+  white-space: nowrap;
+}
+
+.docs-step-label {
+  display: inline-block;
+  font-family: var(--tl-font-mono);
+  font-size: 11px;
+  color: var(--tl-accent);
+  margin-right: 8px;
+}
+
+/* ---- Rendered markdown (settings reference) ---- */
+
+.docs-md table {
+  display: block;
+  overflow-x: auto;
+  border-collapse: collapse;
+  font-size: 13px;
+  margin: 14px 0 22px;
+  border: 1px solid var(--tl-line);
+  border-radius: 4px;
+}
+
+.docs-md th {
+  text-align: left;
+  font-family: var(--tl-font-mono);
+  font-size: 10.5px;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--tl-ink-3);
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--tl-line);
+  background: var(--tl-bg-1);
+  white-space: nowrap;
+}
+
+.docs-md td {
+  padding: 7px 12px;
+  border-bottom: 1px solid var(--tl-line);
+  color: var(--tl-ink-2);
+  vertical-align: top;
+  line-height: 1.5;
+  min-width: 60px;
+}
+
+.docs-md tr:last-child td {
+  border-bottom: none;
+}
+
+.docs-md td:first-child code {
+  color: var(--tl-ink-1);
+}
+
+.docs-md h2,
+.docs-md h3 {
+  scroll-margin-top: 24px;
+}
+
+.docs-md h3 {
+  font-family: var(--tl-font-mono);
+  font-size: 13px;
+  letter-spacing: 0.04em;
+  color: var(--tl-ink-1);
+}
+
+/* ---- Responsive ---- */
+
+@media (max-width: 860px) {
+  .docs-frame {
+    grid-template-columns: 1fr;
+    gap: 24px;
+    padding-top: 28px;
+  }
+
+  .docs-side {
+    position: static;
+  }
+
+  .docs-nav {
+    flex-direction: row;
+    flex-wrap: wrap;
+    border-left: none;
+    border-bottom: 1px solid var(--tl-line);
+    gap: 2px;
+  }
+
+  .docs-nav a {
+    border-left: none;
+    border-bottom: 2px solid transparent;
+    margin-left: 0;
+    margin-bottom: -1px;
+  }
+
+  .docs-nav a.active {
+    border-bottom-color: var(--tl-accent);
+  }
+}