diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..3b66287
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,41 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  vitest:
+    name: vitest
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - run: npm test
+
+  build:
+    name: astro build
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+          cache: npm
+
+      - run: npm ci
+
+      - run: npm run build
diff --git a/README.md b/README.md
index 1a6992e..b3196ac 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ npm install
 npm run dev      # http://localhost:4321/docs/
 npm run build    # static output in ./dist
 npm run preview  # serve ./dist locally
+npm test         # vitest unit tests for the playground
 ```
 
 Requires Node 20+ (CI runs Node 22).
@@ -46,6 +47,16 @@ astro.config.mjs          Astro + Starlight configuration (sidebar, locales, the
 - English content lives at `/docs/en/...`.
 - Russian content lives at `/docs/ru/...`. Pages without a Russian translation fall back to English with a "translate this page" notice.
 
+## Playground
+
+`/docs/playground/` is a browser-side editor for HOCON menu configs (CodeMirror 6 + custom HOCON parser, no backend). It lives outside the Starlight content layout so it can use the full viewport.
+
+- Source: `src/lib/playground/`
+- Pages: `src/pages/playground.astro` (editor), `src/pages/playground/about.astro` (overview)
+- Styles: `src/styles/playground.css` (scoped via `<style is:global>` on the page; intentionally not registered in `astro.config.mjs > customCss` so the rest of the docs site is unaffected)
+- Tests: `npm test` (vitest + happy-dom)
+- Extend autocomplete data in `src/lib/playground/catalog/`, add lessons in `src/lib/playground/tutorial/lessons/`.
+
 ## Image paths
 
 `base` is set to `/docs/` because the site lives at `https://abstractmenus.github.io/docs/`. Astro does not auto-prefix `base` for raw URLs inside Markdown. Reference public assets with the base included:
diff --git a/astro.config.mjs b/astro.config.mjs
index d5cde5d..1c6f3b6 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -22,7 +22,9 @@ export default defineConfig({
     starlight({
       title: "AbstractMenus",
       description: "Documentation for the AbstractMenus Paper/Folia GUI plugin.",
-      favicon: "/favicon.ico",
+      // Astro 6 requires public-asset URLs to include the configured base.
+      // Starlight passes this through verbatim into <link rel="icon" href=...>.
+      favicon: BASE + "favicon.ico",
       logo: { src: "./src/assets/logo.png", alt: "AbstractMenus" },
       social: [
         { icon: "discord", label: "Discord", href: "https://discord.gg/4VGP3Gv" },
@@ -188,6 +190,15 @@ export default defineConfig({
             },
           ],
         },
+        {
+          label: 'Playground',
+          translations: { ru: 'Песочница' },
+          // Full URL because Starlight rewrites relative links per locale
+          // (would otherwise become /docs/en/playground/, which 404s).
+          link: SITE + BASE + 'playground/',
+          badge: { text: 'beta', variant: 'note' },
+          attrs: { 'data-playground-link': 'true' },
+        },
         {
           slug: "changelog",
           attrs: { "data-changelog-link": "true" },
@@ -257,6 +268,23 @@ export default defineConfig({
             "})();",
           ].join(""),
         },
+        {
+          // Sidebar's Playground entry has to be a full URL because Starlight
+          // would otherwise rewrite a relative path through the locale segment
+          // and 404. The static URL is a production fallback; this script
+          // rewrites it to the current origin on every load so the link works
+          // identically in dev (localhost), preview, and production.
+          tag: "script",
+          content: [
+            "(function(){",
+            "function fix(){",
+            "var as=document.querySelectorAll('a[data-playground-link]');",
+            "for(var i=0;i<as.length;i++){as[i].href=window.location.origin+'" + BASE + "playground/';}",
+            "}",
+            "if(document.readyState==='loading'){document.addEventListener('DOMContentLoaded',fix);}else{fix();}",
+            "})();",
+          ].join(""),
+        },
       ],
     }),
     mdx(),
diff --git a/package-lock.json b/package-lock.json
index a34dfcf..45aab9e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11,10 +11,25 @@
         "@astrojs/check": "^0.9.8",
         "@astrojs/mdx": "^5.0.4",
         "@astrojs/starlight": "^0.38.4",
+        "@codemirror/autocomplete": "^6.20.1",
+        "@codemirror/commands": "^6.10.3",
+        "@codemirror/language": "^6.12.3",
+        "@codemirror/lint": "^6.9.5",
+        "@codemirror/search": "^6.7.0",
+        "@codemirror/state": "^6.6.0",
+        "@codemirror/view": "^6.41.1",
+        "@lezer/highlight": "^1.2.3",
         "astro": "^6.1.9",
         "jszip": "^3.10.1",
+        "pako": "^2.1.0",
         "sharp": "^0.34.4",
         "typescript": "^5.7.3"
+      },
+      "devDependencies": {
+        "@types/node": "^22.19.17",
+        "@types/pako": "^2.0.4",
+        "happy-dom": "^15.11.7",
+        "vitest": "^2.1.9"
       }
     },
     "node_modules/@astrojs/check": {
@@ -324,6 +339,87 @@
         "sisteransi": "^1.0.5"
       }
     },
+    "node_modules/@codemirror/autocomplete": {
+      "version": "6.20.1",
+      "resolved": "https://registry.npmjs.org/@codemirror/autocomplete/-/autocomplete-6.20.1.tgz",
+      "integrity": "sha512-1cvg3Vz1dSSToCNlJfRA2WSI4ht3K+WplO0UMOgmUYPivCyy2oueZY6Lx7M9wThm7SDUBViRmuT+OG/i8+ON9A==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/language": "^6.0.0",
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.17.0",
+        "@lezer/common": "^1.0.0"
+      }
+    },
+    "node_modules/@codemirror/commands": {
+      "version": "6.10.3",
+      "resolved": "https://registry.npmjs.org/@codemirror/commands/-/commands-6.10.3.tgz",
+      "integrity": "sha512-JFRiqhKu+bvSkDLI+rUhJwSxQxYb759W5GBezE8Uc8mHLqC9aV/9aTC7yJSqCtB3F00pylrLCwnyS91Ap5ej4Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/language": "^6.0.0",
+        "@codemirror/state": "^6.6.0",
+        "@codemirror/view": "^6.27.0",
+        "@lezer/common": "^1.1.0"
+      }
+    },
+    "node_modules/@codemirror/language": {
+      "version": "6.12.3",
+      "resolved": "https://registry.npmjs.org/@codemirror/language/-/language-6.12.3.tgz",
+      "integrity": "sha512-QwCZW6Tt1siP37Jet9Tb02Zs81TQt6qQrZR2H+eGMcFsL1zMrk2/b9CLC7/9ieP1fjIUMgviLWMmgiHoJrj+ZA==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.23.0",
+        "@lezer/common": "^1.5.0",
+        "@lezer/highlight": "^1.0.0",
+        "@lezer/lr": "^1.0.0",
+        "style-mod": "^4.0.0"
+      }
+    },
+    "node_modules/@codemirror/lint": {
+      "version": "6.9.5",
+      "resolved": "https://registry.npmjs.org/@codemirror/lint/-/lint-6.9.5.tgz",
+      "integrity": "sha512-GElsbU9G7QT9xXhpUg1zWGmftA/7jamh+7+ydKRuT0ORpWS3wOSP0yT1FOlIZa7mIJjpVPipErsyvVqB9cfTFA==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.35.0",
+        "crelt": "^1.0.5"
+      }
+    },
+    "node_modules/@codemirror/search": {
+      "version": "6.7.0",
+      "resolved": "https://registry.npmjs.org/@codemirror/search/-/search-6.7.0.tgz",
+      "integrity": "sha512-ZvGm99wc/s2cITtMT15LFdn8aH/aS+V+DqyGq/N5ZlV5vWtH+nILvC2nw0zX7ByNoHHDZ2IxxdW38O0tc5nVHg==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/state": "^6.0.0",
+        "@codemirror/view": "^6.37.0",
+        "crelt": "^1.0.5"
+      }
+    },
+    "node_modules/@codemirror/state": {
+      "version": "6.6.0",
+      "resolved": "https://registry.npmjs.org/@codemirror/state/-/state-6.6.0.tgz",
+      "integrity": "sha512-4nbvra5R5EtiCzr9BTHiTLc+MLXK2QGiAVYMyi8PkQd3SR+6ixar/Q/01Fa21TBIDOZXgeWV4WppsQolSreAPQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@marijn/find-cluster-break": "^1.0.0"
+      }
+    },
+    "node_modules/@codemirror/view": {
+      "version": "6.41.1",
+      "resolved": "https://registry.npmjs.org/@codemirror/view/-/view-6.41.1.tgz",
+      "integrity": "sha512-ToDnWKbBnke+ZLrP6vgTTDScGi5H37YYuZGniQaBzxMVdtCxMrslsmtnOvbPZk4RX9bvkQqnWR/WS/35tJA0qg==",
+      "license": "MIT",
+      "dependencies": {
+        "@codemirror/state": "^6.6.0",
+        "crelt": "^1.0.6",
+        "style-mod": "^4.1.0",
+        "w3c-keyname": "^2.2.4"
+      }
+    },
     "node_modules/@ctrl/tinycolor": {
       "version": "4.2.0",
       "resolved": "https://registry.npmjs.org/@ctrl/tinycolor/-/tinycolor-4.2.0.tgz",
@@ -1407,6 +1503,36 @@
       "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
       "license": "MIT"
     },
+    "node_modules/@lezer/common": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@lezer/common/-/common-1.5.2.tgz",
+      "integrity": "sha512-sxQE460fPZyU3sdc8lafxiPwJHBzZRy/udNFynGQky1SePYBdhkBl1kOagA9uT3pxR8K09bOrmTUqA9wb/PjSQ==",
+      "license": "MIT"
+    },
+    "node_modules/@lezer/highlight": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@lezer/highlight/-/highlight-1.2.3.tgz",
+      "integrity": "sha512-qXdH7UqTvGfdVBINrgKhDsVTJTxactNNxLk7+UMwZhU13lMHaOBlJe9Vqp907ya56Y3+ed2tlqzys7jDkTmW0g==",
+      "license": "MIT",
+      "dependencies": {
+        "@lezer/common": "^1.3.0"
+      }
+    },
+    "node_modules/@lezer/lr": {
+      "version": "1.4.10",
+      "resolved": "https://registry.npmjs.org/@lezer/lr/-/lr-1.4.10.tgz",
+      "integrity": "sha512-rnCpTIBafOx4mRp43xOxDJbFipJm/c0cia/V5TiGlhmMa+wsSdoGmUN3w5Bqrks/09Q/D4tNAmWaT8p6NRi77A==",
+      "license": "MIT",
+      "dependencies": {
+        "@lezer/common": "^1.0.0"
+      }
+    },
+    "node_modules/@marijn/find-cluster-break": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@marijn/find-cluster-break/-/find-cluster-break-1.0.2.tgz",
+      "integrity": "sha512-l0h88YhZFyKdXIFNfSWpyjStDjGHwZ/U7iobcK1cQQD8sejsONdQtTVU+1wVN1PBw40PiiHB1vA5S7VTfQiP9g==",
+      "license": "MIT"
+    },
     "node_modules/@mdx-js/mdx": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/@mdx-js/mdx/-/mdx-3.1.1.tgz",
@@ -2070,14 +2196,21 @@
       }
     },
     "node_modules/@types/node": {
-      "version": "24.12.2",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.12.2.tgz",
-      "integrity": "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g==",
+      "version": "22.19.17",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.17.tgz",
+      "integrity": "sha512-wGdMcf+vPYM6jikpS/qhg6WiqSV/OhG+jeeHT/KlVqxYfD40iYJf9/AE1uQxVWFvU7MipKRkRv8NSHiCGgPr8Q==",
       "license": "MIT",
       "dependencies": {
-        "undici-types": "~7.16.0"
+        "undici-types": "~6.21.0"
       }
     },
+    "node_modules/@types/pako": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/@types/pako/-/pako-2.0.4.tgz",
+      "integrity": "sha512-VWDCbrLeVXJM9fihYodcLiIv0ku+AlOa/TQ1SvYOaBuyrSKgEcro95LJyIsJ4vSo6BXIxOKxiJAat04CmST9Fw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/sax": {
       "version": "1.2.7",
       "resolved": "https://registry.npmjs.org/@types/sax/-/sax-1.2.7.tgz",
@@ -2099,6 +2232,92 @@
       "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==",
       "license": "ISC"
     },
+    "node_modules/@vitest/expect": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-2.1.9.tgz",
+      "integrity": "sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "2.1.9",
+        "@vitest/utils": "2.1.9",
+        "chai": "^5.1.2",
+        "tinyrainbow": "^1.2.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-2.1.9.tgz",
+      "integrity": "sha512-KhRIdGV2U9HOUzxfiHmY8IFHTdqtOhIzCpd8WRdJiE7D/HUcZVD0EgQCVjm+Q9gkUXWgBvMmTtZgIG48wq7sOQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^1.2.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-2.1.9.tgz",
+      "integrity": "sha512-ZXSSqTFIrzduD63btIfEyOmNcBmQvgOVsPNPe0jYtESiXkhd8u2erDLnMxmGrDCwHCCHE7hxwRDCT3pt0esT4g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "2.1.9",
+        "pathe": "^1.1.2"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-2.1.9.tgz",
+      "integrity": "sha512-oBO82rEjsxLNJincVhLhaxxZdEtV0EFHMK5Kmx5sJ6H9L183dHECjiefOAdnqpIgT5eZwT04PoggUnW88vOBNQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "2.1.9",
+        "magic-string": "^0.30.12",
+        "pathe": "^1.1.2"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-2.1.9.tgz",
+      "integrity": "sha512-E1B35FwzXXTs9FHNK6bDszs7mtydNi5MIfUWpceJ8Xbfb1gBMscAnwLbEu+B44ed6W3XjL9/ehLPHR1fkf1KLQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyspy": "^3.0.2"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-2.1.9.tgz",
+      "integrity": "sha512-v0psaMSkNJ3A2NMrUEHFRzJtDPFn+/VWZ5WxImB21T9fjucJRmS7xCS3ppEnARb9y11OAzaD+P2Ps+b+BGX5iQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "2.1.9",
+        "loupe": "^3.1.2",
+        "tinyrainbow": "^1.2.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
     "node_modules/@volar/kit": {
       "version": "2.4.28",
       "resolved": "https://registry.npmjs.org/@volar/kit/-/kit-2.4.28.tgz",
@@ -2320,6 +2539,16 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/astring": {
       "version": "1.9.0",
       "resolved": "https://registry.npmjs.org/astring/-/astring-1.9.0.tgz",
@@ -2474,6 +2703,16 @@
       "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==",
       "license": "ISC"
     },
+    "node_modules/cac": {
+      "version": "6.7.14",
+      "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
+      "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/ccount": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz",
@@ -2484,6 +2723,23 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/chai": {
+      "version": "5.3.3",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz",
+      "integrity": "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "assertion-error": "^2.0.1",
+        "check-error": "^2.1.1",
+        "deep-eql": "^5.0.1",
+        "loupe": "^3.1.0",
+        "pathval": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/character-entities": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz",
@@ -2524,6 +2780,16 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/check-error": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz",
+      "integrity": "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 16"
+      }
+    },
     "node_modules/chokidar": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
@@ -2658,6 +2924,12 @@
       "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==",
       "license": "MIT"
     },
+    "node_modules/crelt": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/crelt/-/crelt-1.0.6.tgz",
+      "integrity": "sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==",
+      "license": "MIT"
+    },
     "node_modules/crossws": {
       "version": "0.3.5",
       "resolved": "https://registry.npmjs.org/crossws/-/crossws-0.3.5.tgz",
@@ -2799,6 +3071,16 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/deep-eql": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",
+      "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/defu": {
       "version": "6.1.7",
       "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.7.tgz",
@@ -3183,6 +3465,16 @@
       "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==",
       "license": "MIT"
     },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/expressive-code": {
       "version": "0.41.7",
       "resolved": "https://registry.npmjs.org/expressive-code/-/expressive-code-0.41.7.tgz",
@@ -3340,6 +3632,34 @@
         "uncrypto": "^0.1.3"
       }
     },
+    "node_modules/happy-dom": {
+      "version": "15.11.7",
+      "resolved": "https://registry.npmjs.org/happy-dom/-/happy-dom-15.11.7.tgz",
+      "integrity": "sha512-KyrFvnl+J9US63TEzwoiJOQzZBJY7KgBushJA8X61DMbNsH+2ONkDuLDnCnwUiPTF42tLoEmrPyoqbenVA5zrg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^4.5.0",
+        "webidl-conversions": "^7.0.0",
+        "whatwg-mimetype": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/happy-dom/node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/hast-util-embedded": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/hast-util-embedded/-/hast-util-embedded-3.0.0.tgz",
@@ -3957,6 +4277,12 @@
         "setimmediate": "^1.0.5"
       }
     },
+    "node_modules/jszip/node_modules/pako": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
+      "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
+      "license": "(MIT AND Zlib)"
+    },
     "node_modules/kleur": {
       "version": "4.1.5",
       "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz",
@@ -3994,6 +4320,13 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/loupe": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",
+      "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/lru-cache": {
       "version": "11.3.5",
       "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.5.tgz",
@@ -5316,9 +5649,9 @@
       }
     },
     "node_modules/pako": {
-      "version": "1.0.11",
-      "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz",
-      "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==",
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/pako/-/pako-2.1.0.tgz",
+      "integrity": "sha512-w+eufiZ1WuJYgPXbV/PO3NCMEc3xqylkKHzp8bxp1uW4qaSNQUkwmLLEc3kKsfz8lpV1F8Ht3U1Cm+9Srog2ug==",
       "license": "(MIT AND Zlib)"
     },
     "node_modules/parse-entities": {
@@ -5382,6 +5715,23 @@
       "integrity": "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==",
       "license": "MIT"
     },
+    "node_modules/pathe": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.2.tgz",
+      "integrity": "sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/pathval": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz",
+      "integrity": "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14.16"
+      }
+    },
     "node_modules/piccolore": {
       "version": "0.1.3",
       "resolved": "https://registry.npmjs.org/piccolore/-/piccolore-0.1.3.tgz",
@@ -6072,6 +6422,13 @@
         "node": ">=20"
       }
     },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/sisteransi": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
@@ -6097,6 +6454,21 @@
         "npm": ">=10.8.2"
       }
     },
+    "node_modules/sitemap/node_modules/@types/node": {
+      "version": "24.12.2",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.12.2.tgz",
+      "integrity": "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.16.0"
+      }
+    },
+    "node_modules/sitemap/node_modules/undici-types": {
+      "version": "7.16.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
+      "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
+      "license": "MIT"
+    },
     "node_modules/smol-toml": {
       "version": "1.6.1",
       "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.1.tgz",
@@ -6137,6 +6509,20 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/stream-replace-string": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/stream-replace-string/-/stream-replace-string-2.0.0.tgz",
@@ -6192,6 +6578,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/style-mod": {
+      "version": "4.1.3",
+      "resolved": "https://registry.npmjs.org/style-mod/-/style-mod-4.1.3.tgz",
+      "integrity": "sha512-i/n8VsZydrugj3Iuzll8+x/00GH2vnYsk1eomD8QiRrSAeW6ItbCQDtfXCeJHd0iwiNagqjQkvpvREEPtW3IoQ==",
+      "license": "MIT"
+    },
     "node_modules/style-to-js": {
       "version": "1.1.21",
       "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz",
@@ -6241,6 +6633,13 @@
       "integrity": "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==",
       "license": "MIT"
     },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/tinyclip": {
       "version": "0.1.12",
       "resolved": "https://registry.npmjs.org/tinyclip/-/tinyclip-0.1.12.tgz",
@@ -6275,6 +6674,36 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tinypool": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz",
+      "integrity": "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      }
+    },
+    "node_modules/tinyrainbow": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-1.2.0.tgz",
+      "integrity": "sha512-weEDEq7Z5eTHPDh4xjX789+fHfF+P8boiFB+0vbWzpbnbsEr/GRaohi/uMKxg8RZMXnl1ItAi/IUHWMsjDV7kQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tinyspy": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-3.0.2.tgz",
+      "integrity": "sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/trim-lines": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz",
@@ -6369,9 +6798,9 @@
       "license": "MIT"
     },
     "node_modules/undici-types": {
-      "version": "7.16.0",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
-      "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
       "license": "MIT"
     },
     "node_modules/unified": {
@@ -6786,57 +7215,1167 @@
         }
       }
     },
-    "node_modules/vitefu": {
-      "version": "1.1.3",
-      "resolved": "https://registry.npmjs.org/vitefu/-/vitefu-1.1.3.tgz",
-      "integrity": "sha512-ub4okH7Z5KLjb6hDyjqrGXqWtWvoYdU3IGm/NorpgHncKoLTCfRIbvlhBm7r0YstIaQRYlp4yEbFqDcKSzXSSg==",
-      "license": "MIT",
-      "workspaces": [
-        "tests/deps/*",
-        "tests/projects/*",
-        "tests/projects/workspace/packages/*"
-      ],
-      "peerDependencies": {
-        "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
-      },
-      "peerDependenciesMeta": {
-        "vite": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/volar-service-css": {
-      "version": "0.0.70",
-      "resolved": "https://registry.npmjs.org/volar-service-css/-/volar-service-css-0.0.70.tgz",
-      "integrity": "sha512-K1qyOvBpE3rzdAv3e4/6Rv5yizrYPy5R/ne3IWCAzLBuMO4qBMV3kSqWzj6KUVe6S0AnN6wxF7cRkiaKfYMYJw==",
+    "node_modules/vite-node": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/vite-node/-/vite-node-2.1.9.tgz",
+      "integrity": "sha512-AM9aQ/IPrW/6ENLQg3AGY4K1N2TGZdR5e4gu/MmmR2xR3Ll1+dib+nook92g4TV3PXVyeyxdWwtaCAiUL0hMxA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
-        "vscode-css-languageservice": "^6.3.0",
-        "vscode-languageserver-textdocument": "^1.0.11",
-        "vscode-uri": "^3.0.8"
+        "cac": "^6.7.14",
+        "debug": "^4.3.7",
+        "es-module-lexer": "^1.5.4",
+        "pathe": "^1.1.2",
+        "vite": "^5.0.0"
       },
-      "peerDependencies": {
-        "@volar/language-service": "~2.4.0"
+      "bin": {
+        "vite-node": "vite-node.mjs"
       },
-      "peerDependenciesMeta": {
-        "@volar/language-service": {
-          "optional": true
-        }
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
       }
     },
-    "node_modules/volar-service-emmet": {
-      "version": "0.0.70",
-      "resolved": "https://registry.npmjs.org/volar-service-emmet/-/volar-service-emmet-0.0.70.tgz",
-      "integrity": "sha512-xi5bC4m/VyE3zy/n2CXspKeDZs3qA41tHLTw275/7dNWM/RqE2z3BnDICQybHIVp/6G1iOQj5c1qXMgQC08TNg==",
+    "node_modules/vite-node/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@emmetio/css-parser": "^0.4.1",
-        "@emmetio/html-matcher": "^1.3.0",
-        "@vscode/emmet-helper": "^2.9.3",
-        "vscode-uri": "^3.0.8"
-      },
-      "peerDependencies": {
-        "@volar/language-service": "~2.4.0"
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/android-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz",
+      "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/android-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz",
+      "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/android-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz",
+      "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz",
+      "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/darwin-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz",
+      "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz",
+      "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz",
+      "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz",
+      "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz",
+      "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz",
+      "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-loong64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz",
+      "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz",
+      "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz",
+      "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-s390x": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz",
+      "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/linux-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz",
+      "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/sunos-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
+      "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/win32-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz",
+      "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/win32-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz",
+      "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/@esbuild/win32-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz",
+      "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vite-node/node_modules/es-module-lexer": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
+      "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/vite-node/node_modules/esbuild": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz",
+      "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.21.5",
+        "@esbuild/android-arm": "0.21.5",
+        "@esbuild/android-arm64": "0.21.5",
+        "@esbuild/android-x64": "0.21.5",
+        "@esbuild/darwin-arm64": "0.21.5",
+        "@esbuild/darwin-x64": "0.21.5",
+        "@esbuild/freebsd-arm64": "0.21.5",
+        "@esbuild/freebsd-x64": "0.21.5",
+        "@esbuild/linux-arm": "0.21.5",
+        "@esbuild/linux-arm64": "0.21.5",
+        "@esbuild/linux-ia32": "0.21.5",
+        "@esbuild/linux-loong64": "0.21.5",
+        "@esbuild/linux-mips64el": "0.21.5",
+        "@esbuild/linux-ppc64": "0.21.5",
+        "@esbuild/linux-riscv64": "0.21.5",
+        "@esbuild/linux-s390x": "0.21.5",
+        "@esbuild/linux-x64": "0.21.5",
+        "@esbuild/netbsd-x64": "0.21.5",
+        "@esbuild/openbsd-x64": "0.21.5",
+        "@esbuild/sunos-x64": "0.21.5",
+        "@esbuild/win32-arm64": "0.21.5",
+        "@esbuild/win32-ia32": "0.21.5",
+        "@esbuild/win32-x64": "0.21.5"
+      }
+    },
+    "node_modules/vite-node/node_modules/vite": {
+      "version": "5.4.21",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
+      "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.21.3",
+        "postcss": "^8.4.43",
+        "rollup": "^4.20.0"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.4.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vitefu": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/vitefu/-/vitefu-1.1.3.tgz",
+      "integrity": "sha512-ub4okH7Z5KLjb6hDyjqrGXqWtWvoYdU3IGm/NorpgHncKoLTCfRIbvlhBm7r0YstIaQRYlp4yEbFqDcKSzXSSg==",
+      "license": "MIT",
+      "workspaces": [
+        "tests/deps/*",
+        "tests/projects/*",
+        "tests/projects/workspace/packages/*"
+      ],
+      "peerDependencies": {
+        "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vitest": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-2.1.9.tgz",
+      "integrity": "sha512-MSmPM9REYqDGBI8439mA4mWhV5sKmDlBKWIYbA3lRb2PTHACE0mgKwA8yQ2xq9vxDTuk4iPrECBAEW2aoFXY0Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "2.1.9",
+        "@vitest/mocker": "2.1.9",
+        "@vitest/pretty-format": "^2.1.9",
+        "@vitest/runner": "2.1.9",
+        "@vitest/snapshot": "2.1.9",
+        "@vitest/spy": "2.1.9",
+        "@vitest/utils": "2.1.9",
+        "chai": "^5.1.2",
+        "debug": "^4.3.7",
+        "expect-type": "^1.1.0",
+        "magic-string": "^0.30.12",
+        "pathe": "^1.1.2",
+        "std-env": "^3.8.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^0.3.1",
+        "tinypool": "^1.0.1",
+        "tinyrainbow": "^1.2.0",
+        "vite": "^5.0.0",
+        "vite-node": "2.1.9",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "@vitest/browser": "2.1.9",
+        "@vitest/ui": "2.1.9",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/android-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz",
+      "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/android-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz",
+      "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/android-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz",
+      "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz",
+      "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/darwin-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz",
+      "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz",
+      "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz",
+      "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz",
+      "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz",
+      "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz",
+      "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-loong64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz",
+      "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz",
+      "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz",
+      "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-s390x": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz",
+      "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/linux-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz",
+      "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/sunos-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
+      "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/win32-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz",
+      "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/win32-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz",
+      "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@esbuild/win32-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz",
+      "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/vitest/node_modules/@vitest/mocker": {
+      "version": "2.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-2.1.9.tgz",
+      "integrity": "sha512-tVL6uJgoUdi6icpxmdrn5YNo3g3Dxv+IHJBr0GXHaEdTcw3F+cPKnsXFhli6nO+f/6SDKPHEK1UN+k+TQv0Ehg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "2.1.9",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.12"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^5.0.0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vitest/node_modules/esbuild": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz",
+      "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.21.5",
+        "@esbuild/android-arm": "0.21.5",
+        "@esbuild/android-arm64": "0.21.5",
+        "@esbuild/android-x64": "0.21.5",
+        "@esbuild/darwin-arm64": "0.21.5",
+        "@esbuild/darwin-x64": "0.21.5",
+        "@esbuild/freebsd-arm64": "0.21.5",
+        "@esbuild/freebsd-x64": "0.21.5",
+        "@esbuild/linux-arm": "0.21.5",
+        "@esbuild/linux-arm64": "0.21.5",
+        "@esbuild/linux-ia32": "0.21.5",
+        "@esbuild/linux-loong64": "0.21.5",
+        "@esbuild/linux-mips64el": "0.21.5",
+        "@esbuild/linux-ppc64": "0.21.5",
+        "@esbuild/linux-riscv64": "0.21.5",
+        "@esbuild/linux-s390x": "0.21.5",
+        "@esbuild/linux-x64": "0.21.5",
+        "@esbuild/netbsd-x64": "0.21.5",
+        "@esbuild/openbsd-x64": "0.21.5",
+        "@esbuild/sunos-x64": "0.21.5",
+        "@esbuild/win32-arm64": "0.21.5",
+        "@esbuild/win32-ia32": "0.21.5",
+        "@esbuild/win32-x64": "0.21.5"
+      }
+    },
+    "node_modules/vitest/node_modules/tinyexec": {
+      "version": "0.3.2",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz",
+      "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/vitest/node_modules/vite": {
+      "version": "5.4.21",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
+      "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.21.3",
+        "postcss": "^8.4.43",
+        "rollup": "^4.20.0"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.4.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/volar-service-css": {
+      "version": "0.0.70",
+      "resolved": "https://registry.npmjs.org/volar-service-css/-/volar-service-css-0.0.70.tgz",
+      "integrity": "sha512-K1qyOvBpE3rzdAv3e4/6Rv5yizrYPy5R/ne3IWCAzLBuMO4qBMV3kSqWzj6KUVe6S0AnN6wxF7cRkiaKfYMYJw==",
+      "license": "MIT",
+      "dependencies": {
+        "vscode-css-languageservice": "^6.3.0",
+        "vscode-languageserver-textdocument": "^1.0.11",
+        "vscode-uri": "^3.0.8"
+      },
+      "peerDependencies": {
+        "@volar/language-service": "~2.4.0"
+      },
+      "peerDependenciesMeta": {
+        "@volar/language-service": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/volar-service-emmet": {
+      "version": "0.0.70",
+      "resolved": "https://registry.npmjs.org/volar-service-emmet/-/volar-service-emmet-0.0.70.tgz",
+      "integrity": "sha512-xi5bC4m/VyE3zy/n2CXspKeDZs3qA41tHLTw275/7dNWM/RqE2z3BnDICQybHIVp/6G1iOQj5c1qXMgQC08TNg==",
+      "license": "MIT",
+      "dependencies": {
+        "@emmetio/css-parser": "^0.4.1",
+        "@emmetio/html-matcher": "^1.3.0",
+        "@vscode/emmet-helper": "^2.9.3",
+        "vscode-uri": "^3.0.8"
+      },
+      "peerDependencies": {
+        "@volar/language-service": "~2.4.0"
       },
       "peerDependenciesMeta": {
         "@volar/language-service": {
@@ -7042,6 +8581,12 @@
       "integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==",
       "license": "MIT"
     },
+    "node_modules/w3c-keyname": {
+      "version": "2.2.8",
+      "resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",
+      "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==",
+      "license": "MIT"
+    },
     "node_modules/web-namespaces": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
@@ -7052,6 +8597,26 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/webidl-conversions": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-7.0.0.tgz",
+      "integrity": "sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-3.0.0.tgz",
+      "integrity": "sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/which-pm-runs": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/which-pm-runs/-/which-pm-runs-1.1.0.tgz",
@@ -7061,6 +8626,23 @@
         "node": ">=4"
       }
     },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/wrap-ansi": {
       "version": "7.0.0",
       "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
diff --git a/package.json b/package.json
index 2fd8bce..51180a2 100644
--- a/package.json
+++ b/package.json
@@ -8,15 +8,32 @@
     "start": "astro dev",
     "build": "astro check && astro build",
     "preview": "astro preview",
-    "astro": "astro"
+    "astro": "astro",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@astrojs/check": "^0.9.8",
     "@astrojs/mdx": "^5.0.4",
     "@astrojs/starlight": "^0.38.4",
+    "@codemirror/autocomplete": "^6.20.1",
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/lint": "^6.9.5",
+    "@codemirror/search": "^6.7.0",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.41.1",
+    "@lezer/highlight": "^1.2.3",
     "astro": "^6.1.9",
     "jszip": "^3.10.1",
+    "pako": "^2.1.0",
     "sharp": "^0.34.4",
     "typescript": "^5.7.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "@types/pako": "^2.0.4",
+    "happy-dom": "^15.11.7",
+    "vitest": "^2.1.9"
   }
 }
diff --git a/src/lib/playground/Divider.test.ts b/src/lib/playground/Divider.test.ts
new file mode 100644
index 0000000..4fd0c63
--- /dev/null
+++ b/src/lib/playground/Divider.test.ts
@@ -0,0 +1,65 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { createDivider } from './Divider';
+
+function setupDom(): { main: HTMLElement; divider: HTMLElement } {
+  document.body.innerHTML = `
+    <div class="pg-main" style="display:grid;grid-template-columns:1fr 6px 1fr;width:1000px;">
+      <section class="pg-pane pg-pane-editor"></section>
+      <div class="pg-divider" data-pg-divider></div>
+      <section class="pg-pane pg-pane-output"></section>
+    </div>`;
+  const main = document.querySelector<HTMLElement>('.pg-main')!;
+  const divider = document.querySelector<HTMLElement>('[data-pg-divider]')!;
+  return { main, divider };
+}
+
+function stubRect(el: HTMLElement, width: number, height: number): void {
+  Object.defineProperty(el, 'getBoundingClientRect', {
+    value: () => ({
+      left: 0, top: 0, width, height, right: width, bottom: height, x: 0, y: 0,
+      toJSON() { return {}; },
+    }),
+  });
+}
+
+describe('Divider', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  test('drag updates grid-template-columns horizontally', () => {
+    const { main, divider } = setupDom();
+    stubRect(main, 1000, 600);
+    createDivider({ main, divider, axis: 'horizontal', minPct: 10, maxPct: 90 });
+
+    divider.dispatchEvent(new MouseEvent('mousedown', { clientX: 500, clientY: 300, bubbles: true }));
+    window.dispatchEvent(new MouseEvent('mousemove', { clientX: 700, clientY: 300, bubbles: true }));
+    window.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+
+    expect(main.style.gridTemplateColumns).toMatch(/70%/);
+  });
+
+  test('clamps to minPct/maxPct', () => {
+    const { main, divider } = setupDom();
+    stubRect(main, 1000, 600);
+    createDivider({ main, divider, axis: 'horizontal', minPct: 20, maxPct: 80 });
+
+    divider.dispatchEvent(new MouseEvent('mousedown', { clientX: 500, clientY: 300, bubbles: true }));
+    window.dispatchEvent(new MouseEvent('mousemove', { clientX: 50, clientY: 300, bubbles: true }));
+    window.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+
+    expect(main.style.gridTemplateColumns).toMatch(/20%/);
+  });
+
+  test('vertical axis updates grid-template-rows', () => {
+    const { main, divider } = setupDom();
+    stubRect(main, 600, 1000);
+    createDivider({ main, divider, axis: 'vertical', minPct: 10, maxPct: 90 });
+
+    divider.dispatchEvent(new MouseEvent('mousedown', { clientX: 300, clientY: 500, bubbles: true }));
+    window.dispatchEvent(new MouseEvent('mousemove', { clientX: 300, clientY: 300, bubbles: true }));
+    window.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+
+    expect(main.style.gridTemplateRows).toMatch(/30%/);
+  });
+});
diff --git a/src/lib/playground/Divider.ts b/src/lib/playground/Divider.ts
new file mode 100644
index 0000000..6e8c209
--- /dev/null
+++ b/src/lib/playground/Divider.ts
@@ -0,0 +1,57 @@
+export interface DividerOptions {
+  main: HTMLElement;
+  divider: HTMLElement;
+  axis: 'horizontal' | 'vertical';
+  minPct: number;
+  maxPct: number;
+  dividerSize?: number;
+}
+
+export function createDivider(opts: DividerOptions): { destroy(): void } {
+  const dividerSize = opts.dividerSize ?? 6;
+  let dragging = false;
+
+  function setLayout(pct: number): void {
+    const clamped = Math.min(opts.maxPct, Math.max(opts.minPct, pct));
+    if (opts.axis === 'horizontal') {
+      opts.main.style.gridTemplateColumns = `${clamped}% ${dividerSize}px ${100 - clamped}%`;
+    } else {
+      opts.main.style.gridTemplateRows = `${clamped}% ${dividerSize}px ${100 - clamped}%`;
+    }
+  }
+
+  function onMove(e: MouseEvent): void {
+    if (!dragging) return;
+    const rect = opts.main.getBoundingClientRect();
+    const pct = opts.axis === 'horizontal'
+      ? ((e.clientX - rect.left) / rect.width) * 100
+      : ((e.clientY - rect.top) / rect.height) * 100;
+    setLayout(pct);
+  }
+
+  function onUp(): void {
+    if (!dragging) return;
+    dragging = false;
+    document.body.style.cursor = '';
+    document.body.style.userSelect = '';
+  }
+
+  function onDown(e: MouseEvent): void {
+    e.preventDefault();
+    dragging = true;
+    document.body.style.cursor = opts.axis === 'horizontal' ? 'col-resize' : 'row-resize';
+    document.body.style.userSelect = 'none';
+  }
+
+  opts.divider.addEventListener('mousedown', onDown);
+  window.addEventListener('mousemove', onMove);
+  window.addEventListener('mouseup', onUp);
+
+  return {
+    destroy(): void {
+      opts.divider.removeEventListener('mousedown', onDown);
+      window.removeEventListener('mousemove', onMove);
+      window.removeEventListener('mouseup', onUp);
+    },
+  };
+}
diff --git a/src/lib/playground/Editor.ts b/src/lib/playground/Editor.ts
new file mode 100644
index 0000000..b4909ae
--- /dev/null
+++ b/src/lib/playground/Editor.ts
@@ -0,0 +1,140 @@
+import { EditorState, Prec, type Extension } from '@codemirror/state';
+import { EditorView, keymap, lineNumbers, highlightActiveLine, highlightActiveLineGutter } from '@codemirror/view';
+import { defaultKeymap, history, historyKeymap, indentWithTab } from '@codemirror/commands';
+import { bracketMatching, indentOnInput, foldGutter, foldKeymap } from '@codemirror/language';
+import { searchKeymap, highlightSelectionMatches } from '@codemirror/search';
+import { closeBrackets, closeBracketsKeymap, completionKeymap, completionStatus, startCompletion } from '@codemirror/autocomplete';
+import { colorSwatches } from './cm/color-widget';
+import { stripStringsAndComments } from './cm/text-utils';
+
+const PAIRS: Record<string, string> = { '{': '}', '[': ']', '(': ')' };
+
+function scheduleCompletion(view: EditorView): void {
+  // Defer past the current dispatch so the autocomplete plugin sees the
+  // updated doc state.
+  setTimeout(() => startCompletion(view), 0);
+}
+
+/**
+ * Custom Enter handler. Replaces the default insertNewlineAndIndent for HOCON
+ * to give predictable behavior on every line:
+ *
+ * - if an autocomplete popup is open, defer (popup accepts the completion)
+ * - if cursor sits between empty bracket pair `{│}`, expand into
+ *     {
+ *       │
+ *     }
+ *   with cursor indented one level deeper than the opener
+ * - if line text before cursor (ignoring strings/comments) ends with `{` or `[`,
+ *   insert newline + (current line indent + 2 spaces)
+ * - otherwise, insert newline + (current line indent)
+ *
+ * This avoids relying on the indent service, which was getting overridden by
+ * autocomplete keymap on the first Enter and producing inconsistent indents
+ * on lines deep inside a block.
+ */
+const smartEnter = keymap.of([
+  {
+    key: 'Enter',
+    run: (view) => {
+      const { state } = view;
+      if (completionStatus(state) === 'active') return false;
+      const sel = state.selection.main;
+      if (sel.from !== sel.to) return false;
+
+      const line = state.doc.lineAt(sel.from);
+      const baseIndent = /^[ \t]*/.exec(line.text)![0];
+      const before = state.doc.sliceString(Math.max(0, sel.from - 1), sel.from);
+      const after = state.doc.sliceString(sel.from, Math.min(state.doc.length, sel.from + 1));
+      const closing = PAIRS[before];
+
+      if (closing && after === closing) {
+        const inner = baseIndent + '  ';
+        view.dispatch({
+          changes: { from: sel.from, to: sel.from, insert: '\n' + inner + '\n' + baseIndent },
+          selection: { anchor: sel.from + 1 + inner.length },
+          userEvent: 'input',
+        });
+        // Brand-new empty body of a block - perfect spot for "what keys can I put here?"
+        scheduleCompletion(view);
+        return true;
+      }
+
+      const lineUpToCursor = state.doc.sliceString(line.from, sel.from);
+      const trimmedBefore = stripStringsAndComments(lineUpToCursor).trimEnd();
+      const opensBlock = /[{[]$/.test(trimmedBefore);
+      const newIndent = opensBlock ? baseIndent + '  ' : baseIndent;
+
+      view.dispatch({
+        changes: { from: sel.from, to: sel.from, insert: '\n' + newIndent },
+        selection: { anchor: sel.from + 1 + newIndent.length },
+        userEvent: 'input',
+      });
+      if (opensBlock) scheduleCompletion(view);
+      return true;
+    },
+  },
+]);
+
+export interface EditorApi {
+  view: EditorView;
+  getValue(): string;
+  setValue(text: string): void;
+  destroy(): void;
+}
+
+export interface CreateEditorOptions {
+  parent: HTMLElement;
+  initialContent?: string;
+  onChange?: (text: string) => void;
+  extensions?: Extension[];
+}
+
+export function createEditor(opts: CreateEditorOptions): EditorApi {
+  const baseExtensions: Extension[] = [
+    lineNumbers(),
+    foldGutter(),
+    highlightActiveLine(),
+    highlightActiveLineGutter(),
+    highlightSelectionMatches(),
+    history(),
+    bracketMatching(),
+    indentOnInput(),
+    closeBrackets(),
+    colorSwatches(),
+    Prec.highest(smartEnter),
+    keymap.of([
+      ...closeBracketsKeymap,
+      ...defaultKeymap,
+      ...historyKeymap,
+      ...searchKeymap,
+      ...foldKeymap,
+      ...completionKeymap, // Ctrl-Space, Esc, Enter to accept, etc.
+      indentWithTab,
+    ]),
+    EditorView.lineWrapping,
+    EditorView.updateListener.of((u) => {
+      if (u.docChanged && opts.onChange) {
+        opts.onChange(u.state.doc.toString());
+      }
+    }),
+  ];
+
+  const state = EditorState.create({
+    doc: opts.initialContent ?? '',
+    extensions: [...baseExtensions, ...(opts.extensions ?? [])],
+  });
+
+  const view = new EditorView({ state, parent: opts.parent });
+
+  return {
+    view,
+    getValue: () => view.state.doc.toString(),
+    setValue: (text) => {
+      view.dispatch({
+        changes: { from: 0, to: view.state.doc.length, insert: text },
+      });
+    },
+    destroy: () => view.destroy(),
+  };
+}
diff --git a/src/lib/playground/HistoryDropdown.test.ts b/src/lib/playground/HistoryDropdown.test.ts
new file mode 100644
index 0000000..f6fad56
--- /dev/null
+++ b/src/lib/playground/HistoryDropdown.test.ts
@@ -0,0 +1,41 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { createHistoryDropdown } from './HistoryDropdown';
+import type { HistoryEntry } from './sharing/history';
+
+function dom(): HTMLElement {
+  document.body.innerHTML = '<div data-pg-history></div>';
+  return document.querySelector<HTMLElement>('[data-pg-history]')!;
+}
+
+const SAMPLE: HistoryEntry[] = [
+  { ts: 1000, content: 'a = 1', preview: 'a = 1' },
+  { ts: 2000, content: 'b = 2', preview: 'b = 2' },
+];
+
+describe('HistoryDropdown', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  test('renders entries with previews', () => {
+    const dd = createHistoryDropdown(dom());
+    dd.update(SAMPLE);
+    const items = document.querySelectorAll('.pg-history-item');
+    expect(items.length).toBe(2);
+    expect(document.body.textContent).toContain('a = 1');
+    expect(document.body.textContent).toContain('b = 2');
+  });
+
+  test('empty state when no entries', () => {
+    const dd = createHistoryDropdown(dom());
+    dd.update([]);
+    expect(document.body.textContent?.toLowerCase()).toContain('no history');
+  });
+
+  test('click fires onSelect with content', () => {
+    const dd = createHistoryDropdown(dom());
+    let picked: string | null = null;
+    dd.onSelect((c) => { picked = c; });
+    dd.update(SAMPLE);
+    document.querySelectorAll<HTMLButtonElement>('.pg-history-item')[1].click();
+    expect(picked).toBe('b = 2');
+  });
+});
diff --git a/src/lib/playground/HistoryDropdown.ts b/src/lib/playground/HistoryDropdown.ts
new file mode 100644
index 0000000..e989f46
--- /dev/null
+++ b/src/lib/playground/HistoryDropdown.ts
@@ -0,0 +1,62 @@
+import type { HistoryEntry } from './sharing/history';
+import { t } from './i18n';
+
+type SelectListener = (content: string) => void;
+
+export interface HistoryDropdownApi {
+  update(entries: HistoryEntry[]): void;
+  onSelect(fn: SelectListener): void;
+}
+
+export function createHistoryDropdown(host: HTMLElement): HistoryDropdownApi {
+  const listeners: SelectListener[] = [];
+
+  function update(entries: HistoryEntry[]): void {
+    if (entries.length === 0) {
+      const span = document.createElement('span');
+      span.className = 'pg-empty';
+      span.textContent = t('empty.history');
+      host.replaceChildren(span);
+      return;
+    }
+    const list = document.createElement('ul');
+    list.className = 'pg-history-list';
+    for (const e of entries) {
+      const li = document.createElement('li');
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'pg-history-item';
+      const preview = document.createElement('span');
+      preview.className = 'pg-history-preview';
+      preview.textContent = e.preview || t('history.empty');
+      const ts = document.createElement('span');
+      ts.className = 'pg-history-ts';
+      ts.textContent = formatRelative(e.ts);
+      btn.appendChild(preview);
+      btn.appendChild(ts);
+      btn.addEventListener('click', () => {
+        for (const fn of listeners) fn(e.content);
+      });
+      li.appendChild(btn);
+      list.appendChild(li);
+    }
+    host.replaceChildren(list);
+  }
+
+  function onSelect(fn: SelectListener): void {
+    listeners.push(fn);
+  }
+
+  return { update, onSelect };
+}
+
+function formatRelative(ts: number): string {
+  const diff = Math.max(0, Date.now() - ts);
+  const mins = Math.round(diff / 60_000);
+  if (mins < 1) return t('history.justNow');
+  if (mins < 60) return t('history.minutes', { n: mins });
+  const hours = Math.round(mins / 60);
+  if (hours < 24) return t('history.hours', { n: hours });
+  const days = Math.round(hours / 24);
+  return t('history.days', { n: days });
+}
diff --git a/src/lib/playground/Panels.test.ts b/src/lib/playground/Panels.test.ts
new file mode 100644
index 0000000..96db591
--- /dev/null
+++ b/src/lib/playground/Panels.test.ts
@@ -0,0 +1,76 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { createPanels } from './Panels';
+import type { TabId } from './types';
+
+function setupDom(): HTMLElement {
+  document.body.innerHTML = `
+    <div data-pg-root>
+      <button class="pg-tab is-active" data-tab="errors" aria-selected="true"></button>
+      <button class="pg-tab" data-tab="json" aria-selected="false"></button>
+      <button class="pg-tab is-hidden" data-tab="tutorial" aria-selected="false"></button>
+      <div class="pg-tab-panel is-active" data-panel="errors"></div>
+      <div class="pg-tab-panel" data-panel="json"></div>
+      <div class="pg-tab-panel" data-panel="tutorial"></div>
+    </div>`;
+  return document.querySelector<HTMLElement>('[data-pg-root]')!;
+}
+
+describe('Panels', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  test('activate switches active tab and panel', () => {
+    const root = setupDom();
+    const panels = createPanels(root);
+    panels.activate('json');
+    expect(root.querySelector('.pg-tab.is-active')!.getAttribute('data-tab')).toBe('json');
+    expect(root.querySelector('.pg-tab-panel.is-active')!.getAttribute('data-panel')).toBe('json');
+  });
+
+  test('activate sets aria-selected on tabs', () => {
+    const root = setupDom();
+    const panels = createPanels(root);
+    panels.activate('json');
+    const tabs = Array.from(root.querySelectorAll<HTMLButtonElement>('.pg-tab'));
+    const selected: Record<string, string> = {};
+    for (const t of tabs) selected[t.dataset.tab!] = t.getAttribute('aria-selected') ?? '';
+    expect(selected.json).toBe('true');
+    expect(selected.errors).toBe('false');
+    expect(selected.tutorial).toBe('false');
+  });
+
+  test('showTab unhides a hidden tab button', () => {
+    const root = setupDom();
+    const panels = createPanels(root);
+    panels.showTab('tutorial');
+    const btn = root.querySelector<HTMLButtonElement>('.pg-tab[data-tab="tutorial"]')!;
+    expect(btn.classList.contains('is-hidden')).toBe(false);
+  });
+
+  test('hideTab hides a tab button', () => {
+    const root = setupDom();
+    const panels = createPanels(root);
+    panels.hideTab('json');
+    const btn = root.querySelector<HTMLButtonElement>('.pg-tab[data-tab="json"]')!;
+    expect(btn.classList.contains('is-hidden')).toBe(true);
+  });
+
+  test('clicking a tab activates it', () => {
+    const root = setupDom();
+    const panels = createPanels(root);
+    panels.bindClicks();
+    const jsonBtn = root.querySelector<HTMLButtonElement>('.pg-tab[data-tab="json"]')!;
+    jsonBtn.click();
+    expect(root.querySelector('.pg-tab.is-active')!.getAttribute('data-tab')).toBe('json');
+  });
+
+  test('onChange callback fires on activate', () => {
+    const root = setupDom();
+    const panels = createPanels(root);
+    let captured: TabId | null = null;
+    panels.onChange((id) => { captured = id; });
+    panels.activate('tutorial');
+    expect(captured).toBe('tutorial');
+  });
+});
diff --git a/src/lib/playground/Panels.ts b/src/lib/playground/Panels.ts
new file mode 100644
index 0000000..6809eb0
--- /dev/null
+++ b/src/lib/playground/Panels.ts
@@ -0,0 +1,51 @@
+import type { TabId } from './types';
+
+type ChangeListener = (id: TabId) => void;
+
+export interface PanelsApi {
+  activate(id: TabId): void;
+  showTab(id: TabId): void;
+  hideTab(id: TabId): void;
+  bindClicks(): void;
+  onChange(fn: ChangeListener): void;
+}
+
+export function createPanels(root: HTMLElement): PanelsApi {
+  const tabs = (): NodeListOf<HTMLButtonElement> => root.querySelectorAll<HTMLButtonElement>('.pg-tab');
+  const panels = (): NodeListOf<HTMLElement> => root.querySelectorAll<HTMLElement>('.pg-tab-panel');
+  const listeners: ChangeListener[] = [];
+
+  function activate(id: TabId): void {
+    for (const t of tabs()) {
+      const isActive = t.dataset.tab === id;
+      t.classList.toggle('is-active', isActive);
+      t.setAttribute('aria-selected', String(isActive));
+    }
+    for (const p of panels()) {
+      p.classList.toggle('is-active', p.dataset.panel === id);
+    }
+    for (const fn of listeners) fn(id);
+  }
+
+  function showTab(id: TabId): void {
+    const btn = root.querySelector<HTMLButtonElement>(`.pg-tab[data-tab="${id}"]`);
+    if (btn) btn.classList.remove('is-hidden');
+  }
+
+  function hideTab(id: TabId): void {
+    const btn = root.querySelector<HTMLButtonElement>(`.pg-tab[data-tab="${id}"]`);
+    if (btn) btn.classList.add('is-hidden');
+  }
+
+  function bindClicks(): void {
+    for (const t of tabs()) {
+      t.addEventListener('click', () => activate(t.dataset.tab as TabId));
+    }
+  }
+
+  function onChange(fn: ChangeListener): void {
+    listeners.push(fn);
+  }
+
+  return { activate, showTab, hideTab, bindClicks, onChange };
+}
diff --git a/src/lib/playground/PlaygroundApp.ts b/src/lib/playground/PlaygroundApp.ts
new file mode 100644
index 0000000..bf9c4b2
--- /dev/null
+++ b/src/lib/playground/PlaygroundApp.ts
@@ -0,0 +1,458 @@
+import { autocompletion, startCompletion } from '@codemirror/autocomplete';
+import { EditorView, keymap } from '@codemirror/view';
+import type { EditorState } from '@codemirror/state';
+import { detectScope } from './cm/scope';
+import { getKeysForScope } from './catalog';
+import { createEditor, type EditorApi } from './Editor';
+import { createPanels, type PanelsApi } from './Panels';
+import { hoconLanguage } from './cm/hocon-language';
+import { hoconLinter } from './cm/hocon-lint';
+import { snippetCompletions } from './cm/snippets';
+import { createCatalogSource } from './cm/catalog-source';
+import { hoverDocs } from './cm/hover-docs';
+import { formatHocon } from './cm/format';
+import { tokenizeText } from './hocon/tokenize';
+import { parse } from './hocon/parser';
+import { resolve } from './hocon/resolve';
+import { validateUnknownKeys } from './hocon/unknown-keys';
+import { createValidationPanel, type ValidationPanelApi } from './ValidationPanel';
+import { createResolvedJsonPanel, type ResolvedJsonPanelApi } from './ResolvedJsonPanel';
+import { createHistoryDropdown, type HistoryDropdownApi } from './HistoryDropdown';
+import { decodeShare } from './sharing/share-url';
+import { loadHistory } from './sharing/history';
+import { createTutorialPanel, type TutorialPanelApi } from './TutorialPanel';
+import { TutorialController } from './controllers/TutorialController';
+import { HistoryController } from './controllers/HistoryController';
+import { ToolbarController } from './controllers/ToolbarController';
+import type { PlaygroundMode, TabId } from './types';
+import { initLang, t, pluralForm, getLang, setLang, availableLangs } from './i18n';
+import { hydrateI18n } from './i18n/dom';
+
+const SCOPE_SHORTCUT = 'Ctrl+space';
+const ANALYSIS_DEBOUNCE_MS = 300;
+
+const DEFAULT_CONTENT = `# Welcome to the AbstractMenus HOCON Playground.
+# Edit below to see live validation and resolved JSON on the right.
+
+title = "Example Menu"
+size = 3
+
+defaults {
+  cooldown = 5s
+}
+
+items = [
+  { slot = 0, material = STONE, name = "Stone" }
+  { slot = 4, material = DIAMOND, name = \${title} }
+]
+`;
+
+interface DomRefs {
+  root: HTMLElement;
+  editorHost: HTMLElement;
+  status: HTMLElement | null;
+  scopeHint: HTMLElement | null;
+  errorsPanel: HTMLElement | null;
+  warningsPanel: HTMLElement | null;
+  jsonPanel: HTMLElement | null;
+  tutorialPanel: HTMLElement | null;
+  historyHost: HTMLElement | null;
+  errorsCount: HTMLElement | null;
+  warningsCount: HTMLElement | null;
+}
+
+/**
+ * Top-level playground orchestrator. Owns:
+ *  - DOM resolution (cached refs)
+ *  - the editor and the tabbed right-pane (panels)
+ *  - the debounced analysis pipeline (parse / resolve / validate -> panels)
+ *  - mode switching (because it cross-cuts toolbar + tutorial controller)
+ *
+ * Per-feature wiring lives in dedicated controllers under `./controllers/`:
+ *  - TutorialController - lesson state machine + tutorial panel handlers
+ *  - HistoryController  - share button, history dropdown, snapshot scheduler
+ *  - ToolbarController  - theme, divider, format, warning-squiggle toggle
+ *
+ * Adding a new toolbar item / panel / mode should land in the right
+ * controller (or warrant a new one), not bloat this class.
+ */
+export class PlaygroundApp {
+  private readonly dom: DomRefs;
+  private editor!: EditorApi;
+  private panels!: PanelsApi;
+
+  private validation: { errors: ValidationPanelApi | null; warnings: ValidationPanelApi | null } = { errors: null, warnings: null };
+  private resolvedPanel: ResolvedJsonPanelApi | null = null;
+  private historyDropdown: HistoryDropdownApi | null = null;
+  private tutorialPanelApi: TutorialPanelApi | null = null;
+
+  private tutorial: TutorialController | null = null;
+  private history: HistoryController | null = null;
+
+  private analysisTimer: ReturnType<typeof setTimeout> | undefined;
+
+  /**
+   * In-flight document for editor mode. Captured when switching to tutorial
+   * mode so toggling back doesn't silently overwrite the user's edits with
+   * the lesson's content. Initialized to the first content shown in the
+   * editor (default template, share hash, or last history snapshot) so the
+   * first switch tutorial -> editor restores the right thing.
+   */
+  private editorDraft: string | null = null;
+  private currentMode: PlaygroundMode = 'editor';
+
+  constructor(root: HTMLElement) {
+    this.dom = resolveDom(root);
+  }
+
+  /**
+   * Order is load-bearing:
+   *  - setupPanels constructs right-pane API objects that setupAnalysis wires
+   *    its callbacks into.
+   *  - setupEditor must run before any controller that touches `this.editor`.
+   *  - bindModeSwitch must attach before applyInitialUrlMode triggers
+   *    switchMode().
+   */
+  start(): void {
+    initLang();
+    document.documentElement.lang = getLang();
+    hydrateI18n(this.dom.root);
+    this.setupPanels();
+    this.setupEditor();
+    this.setupAnalysis();
+    this.setupControllers();
+    this.bindModeSwitch();
+    this.bindLangSelector();
+    this.applyInitialUrlMode();
+
+    (window as unknown as { __pg?: unknown }).__pg = { editor: this.editor, panels: this.panels };
+  }
+
+  // ---------- DOM-derived UI factories ----------
+
+  private setupPanels(): void {
+    this.validation.errors = this.dom.errorsPanel ? createValidationPanel(this.dom.errorsPanel, 'empty.errors') : null;
+    this.validation.warnings = this.dom.warningsPanel ? createValidationPanel(this.dom.warningsPanel, 'empty.warnings') : null;
+    this.resolvedPanel = this.dom.jsonPanel ? createResolvedJsonPanel(this.dom.jsonPanel) : null;
+    this.historyDropdown = this.dom.historyHost ? createHistoryDropdown(this.dom.historyHost) : null;
+    this.tutorialPanelApi = this.dom.tutorialPanel ? createTutorialPanel(this.dom.tutorialPanel) : null;
+
+    this.panels = createPanels(this.dom.root);
+    this.panels.bindClicks();
+    this.panels.hideTab('tutorial');
+  }
+
+  private setupEditor(): void {
+    const SNIPPETS = snippetCompletions();
+    const catalogSource = createCatalogSource({ fallbackSnippets: SNIPPETS });
+    const initialContent = this.pickInitialContent();
+    // Seed the editor-mode draft so a tutorial->editor switch (without prior
+    // editor edits) restores what the user originally saw, not "" or
+    // DEFAULT_CONTENT.
+    this.editorDraft = initialContent;
+
+    this.editor = createEditor({
+      parent: this.dom.editorHost,
+      initialContent,
+      extensions: [
+        ...hoconLanguage(),
+        hoconLinter(),
+        hoverDocs(),
+        autocompletion({ override: [catalogSource] }),
+        EditorView.updateListener.of((u) => {
+          if (u.selectionSet || u.docChanged) this.updateScopeHint(u.state);
+        }),
+        keymap.of([
+          {
+            key: 'Mod-Shift-f',
+            run: (view) => {
+              const before = view.state.doc.toString();
+              const after = formatHocon(before);
+              if (after === before) return true;
+              view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: after } });
+              return true;
+            },
+          },
+        ]),
+      ],
+      onChange: () => {
+        this.scheduleAnalysis();
+        this.history?.scheduleSnapshot();
+        this.tutorial?.refresh();
+      },
+    });
+  }
+
+  private pickInitialContent(): string {
+    const m = /^#config=(.+)$/.exec(window.location.hash);
+    if (m) {
+      const decoded = decodeShare(m[1]);
+      if (decoded !== null) return decoded;
+    }
+    const history = loadHistory();
+    if (history.length > 0) return history[0].content;
+    return DEFAULT_CONTENT;
+  }
+
+  // ---------- Analysis (parse/resolve/validate -> panels) ----------
+
+  private setupAnalysis(): void {
+    this.scheduleAnalysis();
+    this.updateScopeHint(this.editor.view.state);
+
+    const jumpTo = (line: number, column: number) => this.jumpTo(line, column);
+    this.validation.errors?.onJump(jumpTo);
+    this.validation.warnings?.onJump(jumpTo);
+
+    if (this.dom.scopeHint) {
+      this.dom.scopeHint.addEventListener('click', () => {
+        this.editor.view.focus();
+        startCompletion(this.editor.view);
+      });
+    }
+  }
+
+  private scheduleAnalysis(): void {
+    if (this.analysisTimer) clearTimeout(this.analysisTimer);
+    this.analysisTimer = setTimeout(() => this.runAnalysis(), ANALYSIS_DEBOUNCE_MS);
+  }
+
+  private runAnalysis(): void {
+    const text = this.editor.getValue();
+    const r = parse(tokenizeText(text));
+    const res = resolve(r.ast);
+    const unknown = validateUnknownKeys(r.ast);
+    const all = [...r.diagnostics, ...res.warnings, ...unknown];
+    const errors = all.filter((d) => d.severity === 'error');
+    const warnings = all.filter((d) => d.severity === 'warning');
+
+    this.validation.errors?.update(errors);
+    this.validation.warnings?.update(warnings);
+    this.resolvedPanel?.update(res.resolved);
+
+    setTabCount(this.dom.errorsCount, errors.length, 'has-error');
+    setTabCount(this.dom.warningsCount, warnings.length, 'has-warning');
+
+    if (this.dom.status) {
+      const s = this.dom.status;
+      if (errors.length > 0) s.textContent = formatCount('errors', errors.length);
+      else if (warnings.length > 0) s.textContent = formatCount('warnings', warnings.length);
+      else s.textContent = t('status.ok');
+    }
+  }
+
+  private updateScopeHint(state: EditorState): void {
+    if (!this.dom.scopeHint) return;
+    const text = state.doc.toString();
+    const pos = state.selection.main.head;
+    const scope = detectScope(text, pos);
+    const count = getKeysForScope(scope).length;
+    // Locale plural suffixes for "key": en two-form, ru three-form.
+    const plural = getLang() === 'ru'
+      ? pluralForm(count, ['', 'а', 'ей'])
+      : pluralForm(count, ['', 's']);
+    this.dom.scopeHint.textContent = t('scope.hint.body', {
+      scope,
+      count,
+      plural,
+      shortcut: SCOPE_SHORTCUT,
+    });
+  }
+
+  private jumpTo(line: number, column: number): void {
+    const doc = this.editor.view.state.doc;
+    const lineNo = Math.max(1, Math.min(doc.lines, line));
+    const docLine = doc.line(lineNo);
+    const pos = docLine.from + Math.max(0, column - 1);
+    this.editor.view.dispatch({
+      selection: { anchor: pos },
+      effects: EditorView.scrollIntoView(pos, { y: 'center' }),
+    });
+    this.editor.view.focus();
+  }
+
+  // ---------- Controllers ----------
+
+  private setupControllers(): void {
+    if (this.tutorialPanelApi) {
+      this.tutorial = new TutorialController(
+        this.editor,
+        this.tutorialPanelApi,
+        (id) => setUrlForLesson(id),
+      );
+    }
+    this.history = new HistoryController(this.dom.root, this.editor, this.historyDropdown);
+    new ToolbarController(this.dom.root, this.editor, {
+      onResetEditor: () => this.resetEditorToDefault(),
+    });
+    // Initial mode is editor; sync visibility of mode-only chrome up front.
+    this.applyModeVisibility('editor');
+  }
+
+  /**
+   * Replace the editor content with the canonical default template, drop
+   * the editor draft, and clear any share hash so the URL no longer points
+   * at someone else's snippet. Confirmation lives in the toolbar callback.
+   */
+  private resetEditorToDefault(): void {
+    this.editorDraft = DEFAULT_CONTENT;
+    this.editor.setValue(DEFAULT_CONTENT);
+    if (window.location.hash) history.replaceState(null, '', window.location.pathname + window.location.search);
+    this.editor.view.focus();
+  }
+
+  /**
+   * Toggle visibility of any element marked `data-mode-only="<mode>"` based
+   * on the current mode. Lets us hide the editor-only Reset button (and any
+   * future mode-scoped chrome) without coupling each controller to mode
+   * state.
+   */
+  private applyModeVisibility(mode: PlaygroundMode): void {
+    for (const el of this.dom.root.querySelectorAll<HTMLElement>('[data-mode-only]')) {
+      el.classList.toggle('is-hidden', el.dataset.modeOnly !== mode);
+    }
+  }
+
+  // ---------- Mode switching ----------
+
+  private bindModeSwitch(): void {
+    const buttons = this.dom.root.querySelectorAll<HTMLButtonElement>('.pg-mode-btn');
+    for (const btn of buttons) {
+      btn.addEventListener('click', () => this.switchMode(btn.dataset.mode as PlaygroundMode));
+    }
+  }
+
+  /**
+   * Single source of truth for mode switching - both user clicks and
+   * URL-driven init come through here, so toolbar-button semantics never
+   * diverge from programmatic init.
+   *
+   * Each mode owns its own document buffer:
+   *  - Switching FROM editor: snapshot editor.getValue() into editorDraft.
+   *  - Switching TO editor:   restore editorDraft into the editor.
+   *  - Tutorial side is symmetric and lives in TutorialController.
+   *
+   * No-op when the requested mode equals the current one (avoids losing a
+   * draft to a redundant click on the active tab button).
+   */
+  private switchMode(mode: PlaygroundMode): void {
+    if (mode === this.currentMode) return;
+    const buttons = this.dom.root.querySelectorAll<HTMLButtonElement>('.pg-mode-btn');
+    for (const b of buttons) {
+      const isActive = b.dataset.mode === mode;
+      b.classList.toggle('is-active', isActive);
+      b.setAttribute('aria-selected', String(isActive));
+    }
+    if (mode === 'tutorial') {
+      // Snapshot editor content before tutorial overwrites the doc.
+      this.editorDraft = this.editor.getValue();
+      this.panels.showTab('tutorial');
+      this.panels.activate('tutorial');
+      const lessonId = new URL(window.location.href).searchParams.get('lesson');
+      this.tutorial?.enter(lessonId);
+      setUrlForMode('tutorial');
+    } else {
+      // Let TutorialController snapshot its lesson draft, then restore the
+      // editor draft (or DEFAULT_CONTENT if there's somehow nothing saved).
+      this.tutorial?.leave();
+      this.editor.setValue(this.editorDraft ?? DEFAULT_CONTENT);
+      this.panels.hideTab('tutorial');
+      this.panels.activate('errors' as TabId);
+      setUrlForMode('editor');
+    }
+    this.currentMode = mode;
+    this.applyModeVisibility(mode);
+  }
+
+  private applyInitialUrlMode(): void {
+    const urlMode = new URL(window.location.href).searchParams.get('mode');
+    if (urlMode === 'tutorial') this.switchMode('tutorial');
+  }
+
+  // ---------- Language selector ----------
+
+  /**
+   * Populate the `<select data-pg-lang>` with available locales (auto-loaded
+   * via `import.meta.glob` in i18n/index.ts) and reload the page on change.
+   * Reload over reactive re-render because every panel caches translated
+   * strings on construction; a hard reload is one line and never drifts.
+   */
+  private bindLangSelector(): void {
+    const select = this.dom.root.querySelector<HTMLSelectElement>('[data-pg-lang]');
+    if (!select) return;
+    select.innerHTML = '';
+    for (const code of availableLangs()) {
+      const opt = document.createElement('option');
+      opt.value = code;
+      opt.textContent = LANG_LABELS[code] ?? code.toUpperCase();
+      if (code === getLang()) opt.selected = true;
+      select.appendChild(opt);
+    }
+    select.addEventListener('change', () => {
+      setLang(select.value);
+      window.location.reload();
+    });
+  }
+}
+
+const LANG_LABELS: Record<string, string> = {
+  en: 'English',
+  ru: 'Русский',
+};
+
+function formatCount(kind: 'errors' | 'warnings', n: number): string {
+  // English plural collapses to "" / "s". Russian needs three forms.
+  // Falls through to English-style "s" suffix for any other locale until
+  // a community contributor wires plural rules for it.
+  let plural: string;
+  if (getLang() === 'ru') {
+    plural = kind === 'errors'
+      ? pluralForm(n, ['а', 'и', 'ок'])  // 1 ошибка / 2 ошибки / 5 ошибок
+      : pluralForm(n, ['е', 'я', 'й']);  // 1 предупреждение / 2 предупреждения / 5 предупреждений
+  } else {
+    plural = pluralForm(n, ['', 's']);
+  }
+  return t(kind === 'errors' ? 'status.errors' : 'status.warnings', { count: n, plural });
+}
+
+function resolveDom(root: HTMLElement): DomRefs {
+  const editorHost = root.querySelector<HTMLElement>('[data-pg-editor]');
+  if (!editorHost) throw new Error('[playground] editor host not found');
+  return {
+    root,
+    editorHost,
+    status: root.querySelector<HTMLElement>('[data-pg-status]'),
+    scopeHint: root.querySelector<HTMLElement>('[data-pg-scope-hint]'),
+    errorsPanel: root.querySelector<HTMLElement>('[data-panel="errors"]'),
+    warningsPanel: root.querySelector<HTMLElement>('[data-panel="warnings"]'),
+    jsonPanel: root.querySelector<HTMLElement>('[data-panel="json"]'),
+    tutorialPanel: root.querySelector<HTMLElement>('[data-panel="tutorial"]'),
+    historyHost: root.querySelector<HTMLElement>('[data-pg-history]'),
+    errorsCount: root.querySelector<HTMLElement>('[data-tab-count="errors"]'),
+    warningsCount: root.querySelector<HTMLElement>('[data-tab-count="warnings"]'),
+  };
+}
+
+function setTabCount(el: HTMLElement | null, count: number, klass: 'has-error' | 'has-warning'): void {
+  if (!el) return;
+  el.textContent = count > 0 ? String(count) : '';
+  el.classList.toggle(klass, count > 0);
+}
+
+function setUrlForMode(mode: PlaygroundMode): void {
+  const url = new URL(window.location.href);
+  if (mode === 'tutorial') {
+    url.searchParams.set('mode', 'tutorial');
+  } else {
+    url.searchParams.delete('mode');
+    url.searchParams.delete('lesson');
+  }
+  history.replaceState(null, '', url.toString());
+}
+
+function setUrlForLesson(id: string): void {
+  const url = new URL(window.location.href);
+  url.searchParams.set('mode', 'tutorial');
+  url.searchParams.set('lesson', id);
+  history.replaceState(null, '', url.toString());
+}
diff --git a/src/lib/playground/ResolvedJsonPanel.test.ts b/src/lib/playground/ResolvedJsonPanel.test.ts
new file mode 100644
index 0000000..15ac2e0
--- /dev/null
+++ b/src/lib/playground/ResolvedJsonPanel.test.ts
@@ -0,0 +1,58 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { createResolvedJsonPanel, highlightJson } from './ResolvedJsonPanel';
+
+function dom(): HTMLElement {
+  document.body.innerHTML = '<div data-panel="json"></div>';
+  return document.querySelector<HTMLElement>('[data-panel="json"]')!;
+}
+
+describe('ResolvedJsonPanel', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  test('renders pretty-printed JSON', () => {
+    const panel = createResolvedJsonPanel(dom());
+    panel.update({ a: 1, b: [2, 3] });
+    const pre = document.querySelector<HTMLElement>('.pg-json')!;
+    expect(pre.textContent).toContain('"a": 1');
+    expect(pre.textContent).toContain('"b": [\n');
+  });
+
+  test('copy button exists', () => {
+    const panel = createResolvedJsonPanel(dom());
+    panel.update({ a: 1 });
+    const btn = document.querySelector('[data-action="copy-json"]');
+    expect(btn).not.toBeNull();
+  });
+
+  test('null value renders as null', () => {
+    const panel = createResolvedJsonPanel(dom());
+    panel.update(null);
+    expect(document.querySelector('.pg-json')!.textContent).toBe('null');
+  });
+});
+
+describe('highlightJson', () => {
+  test('wraps keys', () => {
+    expect(highlightJson('"a": 1')).toContain('<span class="pg-json-key">"a"</span>');
+  });
+
+  test('wraps strings, numbers, booleans, null', () => {
+    const out = highlightJson('{"x": "v", "n": 5, "b": true, "z": null}');
+    expect(out).toContain('<span class="pg-json-str">"v"</span>');
+    expect(out).toContain('<span class="pg-json-num">5</span>');
+    expect(out).toContain('<span class="pg-json-bool">true</span>');
+    expect(out).toContain('<span class="pg-json-null">null</span>');
+  });
+
+  test('escapes HTML in string values', () => {
+    expect(highlightJson('"a": "<script>"')).toContain('&lt;script&gt;');
+    expect(highlightJson('"a": "<script>"')).not.toContain('<script>');
+  });
+
+  test('preserves textContent on round-trip', () => {
+    const json = '{"a": 1, "b": [true, null]}';
+    const div = document.createElement('div');
+    div.innerHTML = highlightJson(json);
+    expect(div.textContent).toBe(json);
+  });
+});
diff --git a/src/lib/playground/ResolvedJsonPanel.ts b/src/lib/playground/ResolvedJsonPanel.ts
new file mode 100644
index 0000000..4fa4118
--- /dev/null
+++ b/src/lib/playground/ResolvedJsonPanel.ts
@@ -0,0 +1,60 @@
+import { t } from './i18n';
+
+export interface ResolvedJsonPanelApi {
+  update(value: unknown): void;
+}
+
+export function createResolvedJsonPanel(panel: HTMLElement): ResolvedJsonPanelApi {
+  function update(value: unknown): void {
+    const json = value === undefined ? 'undefined' : JSON.stringify(value, null, 2);
+    const wrap = document.createElement('div');
+    wrap.className = 'pg-json-wrap';
+
+    const desc = document.createElement('div');
+    desc.className = 'pg-json-desc';
+    desc.textContent = t('json.desc');
+    wrap.appendChild(desc);
+
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'pg-btn pg-btn-secondary pg-json-copy';
+    btn.textContent = t('btn.copy');
+    btn.dataset.action = 'copy-json';
+    btn.addEventListener('click', () => {
+      navigator.clipboard?.writeText(json).catch(() => {});
+    });
+    const pre = document.createElement('pre');
+    pre.className = 'pg-json';
+    pre.innerHTML = highlightJson(json);
+    wrap.appendChild(btn);
+    wrap.appendChild(pre);
+    panel.replaceChildren(wrap);
+  }
+  return { update };
+}
+
+/**
+ * Cheap regex-based JSON syntax highlighter. Wraps strings/numbers/keywords
+ * into span classes consistent with the editor token palette.
+ * HTML-escapes input first so it's safe to inject as innerHTML.
+ */
+export function highlightJson(json: string): string {
+  const escaped = json
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+
+  // Order matters: keys (string before colon) first, then plain strings,
+  // then keywords/numbers.
+  return escaped.replace(
+    /("(?:\\.|[^"\\])*"(?=\s*:))|("(?:\\.|[^"\\])*")|\b(true|false)\b|\b(null)\b|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g,
+    (_m, key, str, bool, nul, num) => {
+      if (key !== undefined) return `<span class="pg-json-key">${key}</span>`;
+      if (str !== undefined) return `<span class="pg-json-str">${str}</span>`;
+      if (bool !== undefined) return `<span class="pg-json-bool">${bool}</span>`;
+      if (nul !== undefined) return `<span class="pg-json-null">${nul}</span>`;
+      if (num !== undefined) return `<span class="pg-json-num">${num}</span>`;
+      return _m;
+    },
+  );
+}
diff --git a/src/lib/playground/Toast.ts b/src/lib/playground/Toast.ts
new file mode 100644
index 0000000..dd93117
--- /dev/null
+++ b/src/lib/playground/Toast.ts
@@ -0,0 +1,16 @@
+let activeTimer: ReturnType<typeof setTimeout> | undefined;
+
+export function showToast(message: string, duration = 1500): void {
+  let el = document.querySelector<HTMLDivElement>('.pg-toast');
+  if (!el) {
+    el = document.createElement('div');
+    el.className = 'pg-toast';
+    document.body.appendChild(el);
+  }
+  el.textContent = message;
+  el.classList.add('is-visible');
+  if (activeTimer) clearTimeout(activeTimer);
+  activeTimer = setTimeout(() => {
+    el!.classList.remove('is-visible');
+  }, duration);
+}
diff --git a/src/lib/playground/TutorialPanel.test.ts b/src/lib/playground/TutorialPanel.test.ts
new file mode 100644
index 0000000..57dc11a
--- /dev/null
+++ b/src/lib/playground/TutorialPanel.test.ts
@@ -0,0 +1,144 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { createTutorialPanel, type ShowLessonOpts } from './TutorialPanel';
+import type { Lesson } from './tutorial/types';
+
+const LESSON: Lesson = {
+  id: '00-introduction',
+  title: 'Introduction',
+  topic: 'basics',
+  intro: 'Welcome',
+  starter: 'title = ""',
+  goal: 'Set title',
+  check: { type: 'regex', pattern: 'title' },
+  hints: ['hint1', 'hint2', 'hint3'],
+  next: '01-comments',
+};
+
+function dom(): HTMLElement {
+  document.body.innerHTML = '<div data-panel="tutorial"></div>';
+  return document.querySelector<HTMLElement>('[data-panel="tutorial"]')!;
+}
+
+function mkOpts(overrides: Partial<ShowLessonOpts> = {}): ShowLessonOpts {
+  return {
+    hintsUsed: 0,
+    passed: false,
+    position: 1,
+    total: 1,
+    allLessons: [LESSON],
+    progress: { completed: new Set(), skipped: new Set() },
+    hasPrev: false,
+    ...overrides,
+  };
+}
+
+describe('TutorialPanel', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  test('renders title, intro, goal', () => {
+    const p = createTutorialPanel(dom());
+    p.showLesson(LESSON, mkOpts());
+    expect(document.body.textContent).toContain('Introduction');
+    expect(document.body.textContent).toContain('Welcome');
+    expect(document.body.textContent).toContain('Set title');
+  });
+
+  test('hint button triggers callback', () => {
+    const p = createTutorialPanel(dom());
+    let clicked = false;
+    p.onHint(() => { clicked = true; });
+    p.showLesson(LESSON, mkOpts());
+    document.querySelector<HTMLButtonElement>('[data-action="hint"]')!.click();
+    expect(clicked).toBe(true);
+  });
+
+  test('reveals progressively more hints based on hintsUsed', () => {
+    const p = createTutorialPanel(dom());
+    p.showLesson(LESSON, mkOpts({ hintsUsed: 2 }));
+    expect(document.body.textContent).toContain('hint1');
+    expect(document.body.textContent).toContain('hint2');
+    expect(document.body.textContent).not.toContain('hint3');
+  });
+
+  test('next button disabled until passed', () => {
+    const p = createTutorialPanel(dom());
+    p.showLesson(LESSON, mkOpts());
+    const next = document.querySelector<HTMLButtonElement>('[data-action="next"]')!;
+    expect(next.disabled).toBe(true);
+    p.setPassed(true);
+    expect(next.disabled).toBe(false);
+  });
+
+  test('passed state shows goal-reached banner', () => {
+    const p = createTutorialPanel(dom());
+    p.showLesson(LESSON, mkOpts({ passed: true }));
+    const banner = document.querySelector<HTMLElement>('.pg-tutorial-passed');
+    expect(banner).not.toBeNull();
+    expect(banner!.style.display).not.toBe('none');
+  });
+
+  test('breadcrumb shows topic + counter', () => {
+    const p = createTutorialPanel(dom());
+    p.showLesson(LESSON, mkOpts({ position: 3, total: 12 }));
+    expect(document.body.textContent).toMatch(/Basics/);
+    expect(document.body.textContent).toMatch(/3.*12|3 \/ 12/);
+  });
+
+  test('Prev disabled when no previous lesson', () => {
+    const p = createTutorialPanel(dom());
+    p.showLesson(LESSON, mkOpts({ hasPrev: false }));
+    const prev = document.querySelector<HTMLButtonElement>('[data-action="prev"]')!;
+    expect(prev.disabled).toBe(true);
+  });
+
+  test('Prev fires callback when enabled', () => {
+    const p = createTutorialPanel(dom());
+    let fired = false;
+    p.onPrev(() => { fired = true; });
+    p.showLesson(LESSON, mkOpts({ hasPrev: true }));
+    document.querySelector<HTMLButtonElement>('[data-action="prev"]')!.click();
+    expect(fired).toBe(true);
+  });
+
+  test('lessons popup renders all lessons grouped by topic, fires onJump', () => {
+    const second: Lesson = {
+      ...LESSON,
+      id: '01-comments',
+      title: 'Comments',
+      topic: 'basics',
+    };
+    const p = createTutorialPanel(dom());
+    let jumped: string | null = null;
+    p.onJump((id) => { jumped = id; });
+    p.showLesson(LESSON, mkOpts({
+      position: 1,
+      total: 2,
+      allLessons: [LESSON, second],
+      progress: { completed: new Set(['01-comments']), skipped: new Set() },
+    }));
+
+    // Open popup, then click the second lesson row
+    document.querySelector<HTMLButtonElement>('[data-action="all-lessons"]')!.click();
+    const items = document.querySelectorAll<HTMLButtonElement>('.pg-tutorial-popup-item');
+    expect(items.length).toBe(2);
+    // Completed marker is on the second lesson
+    expect(items[1].classList.contains('is-completed')).toBe(true);
+    // Current marker on the first
+    expect(items[0].classList.contains('is-current')).toBe(true);
+    items[1].click();
+    expect(jumped).toBe('01-comments');
+  });
+
+  test('lessons popup prefixes each row with its 1-based position', () => {
+    const second: Lesson = { ...LESSON, id: '01-comments', title: 'Comments', topic: 'basics' };
+    const p = createTutorialPanel(dom());
+    p.showLesson(LESSON, mkOpts({
+      position: 1,
+      total: 2,
+      allLessons: [LESSON, second],
+    }));
+    document.querySelector<HTMLButtonElement>('[data-action="all-lessons"]')!.click();
+    const nums = document.querySelectorAll<HTMLElement>('.pg-tutorial-popup-num');
+    expect(Array.from(nums).map((n) => n.textContent)).toEqual(['1.', '2.']);
+  });
+});
diff --git a/src/lib/playground/TutorialPanel.ts b/src/lib/playground/TutorialPanel.ts
new file mode 100644
index 0000000..2b6324f
--- /dev/null
+++ b/src/lib/playground/TutorialPanel.ts
@@ -0,0 +1,366 @@
+import type { Lesson } from './tutorial/types';
+import { renderMd, renderInlineMd } from './tutorial/markdown';
+import { groupLessons, type TopicGroup } from './tutorial/lessons';
+import { t, type TranslationKey } from './i18n';
+
+type Listener = () => void;
+type IdListener = (id: string) => void;
+
+/**
+ * Read-only snapshot of progress used to decorate the lesson list. The
+ * controller passes this in on every render so the popup never reads
+ * progress directly.
+ */
+export interface LessonProgressView {
+  completed: Set<string>;
+  skipped: Set<string>;
+}
+
+export interface ShowLessonOpts {
+  hintsUsed: number;
+  passed: boolean;
+  /** 1-based global position of this lesson in the sorted list. */
+  position: number;
+  /** Total lesson count. */
+  total: number;
+  /** All lessons (post-translation) for the popup tree. */
+  allLessons: Lesson[];
+  progress: LessonProgressView;
+  /** True when this lesson has a previous lesson in the global order. */
+  hasPrev: boolean;
+}
+
+export interface TutorialPanelApi {
+  showLesson(lesson: Lesson, opts: ShowLessonOpts): void;
+  showCompleted(text: string): void;
+  setPassed(passed: boolean): void;
+  onHint(fn: Listener): void;
+  onReset(fn: Listener): void;
+  onSkip(fn: Listener): void;
+  onNext(fn: Listener): void;
+  onPrev(fn: Listener): void;
+  onJump(fn: IdListener): void;
+}
+
+export function createTutorialPanel(host: HTMLElement): TutorialPanelApi {
+  const onHintFns: Listener[] = [];
+  const onResetFns: Listener[] = [];
+  const onSkipFns: Listener[] = [];
+  const onNextFns: Listener[] = [];
+  const onPrevFns: Listener[] = [];
+  const onJumpFns: IdListener[] = [];
+
+  function showLesson(lesson: Lesson, opts: ShowLessonOpts): void {
+    const wrap = document.createElement('div');
+    wrap.className = 'pg-tutorial';
+
+    wrap.appendChild(buildBreadcrumb(lesson, opts));
+    wrap.appendChild(buildHead(lesson, opts.passed));
+
+    const intro = document.createElement('div');
+    intro.className = 'pg-tutorial-intro';
+    intro.innerHTML = renderMd(lesson.intro);
+    wrap.appendChild(intro);
+
+    const goal = document.createElement('div');
+    goal.className = 'pg-tutorial-goal';
+    const goalLabel = document.createElement('strong');
+    goalLabel.textContent = t('tutorial.goalLabel');
+    goal.appendChild(goalLabel);
+    // The goal often references HOCON keys/snippets via backticks; render
+    // them through the inline markdown pipeline so they show as <code>
+    // (and any link/bold) instead of literal characters.
+    const goalText = document.createElement('span');
+    goalText.innerHTML = renderInlineMd(lesson.goal);
+    goal.appendChild(goalText);
+    wrap.appendChild(goal);
+
+    if (opts.hintsUsed > 0) {
+      const hintList = document.createElement('div');
+      hintList.className = 'pg-tutorial-hints';
+      const revealed = Math.min(opts.hintsUsed, lesson.hints.length);
+      for (let i = 0; i < revealed; i++) {
+        const item = document.createElement('div');
+        item.className = 'pg-tutorial-hint';
+        item.innerHTML = renderMd(lesson.hints[i]);
+        hintList.appendChild(item);
+      }
+      wrap.appendChild(hintList);
+    }
+
+    wrap.appendChild(buildActions(lesson, opts));
+
+    host.replaceChildren(wrap);
+  }
+
+  /**
+   * Top strip: breadcrumb (Topic / Subtopic), counter (Lesson N / Total),
+   * Prev arrow, and the All-lessons trigger which toggles the popup.
+   */
+  function buildBreadcrumb(lesson: Lesson, opts: ShowLessonOpts): HTMLElement {
+    const bar = document.createElement('div');
+    bar.className = 'pg-tutorial-bar';
+
+    const crumbs = document.createElement('div');
+    crumbs.className = 'pg-tutorial-crumbs';
+    const topic = document.createElement('span');
+    topic.className = 'pg-tutorial-crumb';
+    topic.textContent = topicLabel(lesson.topic);
+    crumbs.appendChild(topic);
+    if (lesson.subtopic) {
+      const sep = document.createElement('span');
+      sep.className = 'pg-tutorial-crumb-sep';
+      sep.textContent = '/';
+      crumbs.appendChild(sep);
+      const sub = document.createElement('span');
+      sub.className = 'pg-tutorial-crumb';
+      sub.textContent = subtopicLabel(lesson.subtopic);
+      crumbs.appendChild(sub);
+    }
+    const counter = document.createElement('span');
+    counter.className = 'pg-tutorial-counter';
+    counter.textContent = ' · ' + t('tutorial.counter', { n: opts.position, total: opts.total });
+    crumbs.appendChild(counter);
+    bar.appendChild(crumbs);
+
+    const prevBtn = mkBtn(t('tutorial.btn.prev'), 'prev');
+    prevBtn.classList.add('pg-tutorial-nav');
+    prevBtn.disabled = !opts.hasPrev;
+    prevBtn.addEventListener('click', () => onPrevFns.forEach((fn) => fn()));
+    bar.appendChild(prevBtn);
+
+    const listBtn = mkBtn(t('tutorial.btn.allLessons'), 'all-lessons');
+    listBtn.classList.add('pg-tutorial-nav');
+    listBtn.title = t('tutorial.btn.allLessons.title');
+    bar.appendChild(listBtn);
+
+    const popup = buildLessonsPopup(lesson, opts);
+    bar.appendChild(popup);
+
+    listBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      popup.hidden = !popup.hidden;
+    });
+    document.addEventListener('click', (e) => {
+      const within = (e.target as Element)?.closest?.('.pg-tutorial-bar');
+      if (!within) popup.hidden = true;
+    });
+
+    return bar;
+  }
+
+  function buildHead(lesson: Lesson, passed: boolean): HTMLElement {
+    const head = document.createElement('header');
+    head.className = 'pg-tutorial-head';
+    const h = document.createElement('h2');
+    h.className = 'pg-tutorial-title';
+    h.textContent = lesson.title;
+    head.appendChild(h);
+
+    const banner = document.createElement('div');
+    banner.className = 'pg-tutorial-passed';
+    banner.textContent = t('tutorial.passed');
+    if (!passed) banner.style.display = 'none';
+    head.appendChild(banner);
+    return head;
+  }
+
+  function buildActions(lesson: Lesson, opts: ShowLessonOpts): HTMLElement {
+    const actions = document.createElement('div');
+    actions.className = 'pg-tutorial-actions';
+
+    const hintBtn = mkBtn(t('tutorial.btn.hint'), 'hint');
+    if (opts.hintsUsed >= lesson.hints.length) hintBtn.disabled = true;
+    hintBtn.addEventListener('click', () => onHintFns.forEach((fn) => fn()));
+    actions.appendChild(hintBtn);
+
+    const resetBtn = mkBtn(t('tutorial.btn.reset'), 'reset');
+    resetBtn.addEventListener('click', () => onResetFns.forEach((fn) => fn()));
+    actions.appendChild(resetBtn);
+
+    const skipBtn = mkBtn(t('tutorial.btn.skip'), 'skip');
+    skipBtn.addEventListener('click', () => onSkipFns.forEach((fn) => fn()));
+    actions.appendChild(skipBtn);
+
+    const nextBtn = mkBtn(t('tutorial.btn.next'), 'next');
+    nextBtn.classList.add('pg-btn-primary');
+    nextBtn.disabled = !opts.passed;
+    nextBtn.addEventListener('click', () => onNextFns.forEach((fn) => fn()));
+    actions.appendChild(nextBtn);
+    return actions;
+  }
+
+  /**
+   * Popup tree of lessons grouped by topic -> subtopic, with progress
+   * markers next to each lesson. Anchored to the All-lessons button via
+   * absolute positioning in CSS; click-outside closes via a delegated
+   * handler in buildBreadcrumb().
+   */
+  function buildLessonsPopup(currentLesson: Lesson, opts: ShowLessonOpts): HTMLElement {
+    const popup = document.createElement('div');
+    popup.className = 'pg-tutorial-popup';
+    popup.hidden = true;
+
+    if (opts.allLessons.length === 0) {
+      const empty = document.createElement('div');
+      empty.className = 'pg-empty';
+      empty.textContent = t('tutorial.popup.empty');
+      popup.appendChild(empty);
+      return popup;
+    }
+
+    // Pre-compute the global 1-based position for each lesson once so the
+    // grouped render can prefix each row with its number without repeated
+    // indexOf lookups.
+    const positions = new Map<string, number>();
+    opts.allLessons.forEach((l, i) => positions.set(l.id, i + 1));
+
+    const groups: TopicGroup[] = groupLessons(opts.allLessons);
+    for (const g of groups) {
+      const topicEl = document.createElement('div');
+      topicEl.className = 'pg-tutorial-popup-topic';
+      const topicHead = document.createElement('div');
+      topicHead.className = 'pg-tutorial-popup-topic-head';
+      topicHead.textContent = topicLabel(g.topic);
+      topicEl.appendChild(topicHead);
+
+      for (const sub of g.subtopics) {
+        if (sub.subtopic) {
+          const subHead = document.createElement('div');
+          subHead.className = 'pg-tutorial-popup-subtopic';
+          subHead.textContent = subtopicLabel(sub.subtopic);
+          topicEl.appendChild(subHead);
+        }
+        const ul = document.createElement('ul');
+        ul.className = 'pg-tutorial-popup-list';
+        for (const ls of sub.lessons) {
+          const pos = positions.get(ls.id) ?? 0;
+          ul.appendChild(buildLessonRow(ls, currentLesson, opts.progress, popup, pos));
+        }
+        topicEl.appendChild(ul);
+      }
+      popup.appendChild(topicEl);
+    }
+    return popup;
+  }
+
+  function buildLessonRow(
+    lesson: Lesson,
+    current: Lesson,
+    progress: LessonProgressView,
+    popup: HTMLElement,
+    position: number,
+  ): HTMLLIElement {
+    const li = document.createElement('li');
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'pg-tutorial-popup-item';
+
+    const isCurrent = lesson.id === current.id;
+    const isCompleted = progress.completed.has(lesson.id);
+    const isSkipped = progress.skipped.has(lesson.id);
+
+    if (isCurrent) btn.classList.add('is-current');
+    if (isCompleted) btn.classList.add('is-completed');
+    if (isSkipped) btn.classList.add('is-skipped');
+
+    const marker = document.createElement('span');
+    marker.className = 'pg-tutorial-popup-marker';
+    if (isCurrent) {
+      marker.textContent = '●';
+      marker.title = t('tutorial.marker.current');
+    } else if (isCompleted) {
+      marker.textContent = '✓';
+      marker.title = t('tutorial.marker.completed');
+    } else if (isSkipped) {
+      marker.textContent = '→';
+      marker.title = t('tutorial.marker.skipped');
+    } else {
+      marker.textContent = '·';
+    }
+    btn.appendChild(marker);
+
+    // Number prefix - global 1-based index, e.g. "1. Introduction".
+    const num = document.createElement('span');
+    num.className = 'pg-tutorial-popup-num';
+    num.textContent = `${position}.`;
+    btn.appendChild(num);
+
+    const title = document.createElement('span');
+    title.className = 'pg-tutorial-popup-title';
+    title.textContent = lesson.title;
+    btn.appendChild(title);
+
+    btn.addEventListener('click', () => {
+      popup.hidden = true;
+      onJumpFns.forEach((fn) => fn(lesson.id));
+    });
+
+    li.appendChild(btn);
+    return li;
+  }
+
+  function showCompleted(text: string): void {
+    const wrap = document.createElement('div');
+    wrap.className = 'pg-tutorial pg-tutorial-done';
+    const h = document.createElement('h2');
+    h.textContent = t('tutorial.done.title');
+    const p = document.createElement('p');
+    p.textContent = text;
+    wrap.appendChild(h);
+    wrap.appendChild(p);
+    host.replaceChildren(wrap);
+  }
+
+  function setPassed(passed: boolean): void {
+    const banner = host.querySelector<HTMLElement>('.pg-tutorial-passed');
+    if (banner) banner.style.display = passed ? '' : 'none';
+    const next = host.querySelector<HTMLButtonElement>('[data-action="next"]');
+    if (next) next.disabled = !passed;
+  }
+
+  return {
+    showLesson, showCompleted, setPassed,
+    onHint(fn) { onHintFns.push(fn); },
+    onReset(fn) { onResetFns.push(fn); },
+    onSkip(fn) { onSkipFns.push(fn); },
+    onNext(fn) { onNextFns.push(fn); },
+    onPrev(fn) { onPrevFns.push(fn); },
+    onJump(fn) { onJumpFns.push(fn); },
+  };
+}
+
+function mkBtn(label: string, action: string): HTMLButtonElement {
+  const b = document.createElement('button');
+  b.type = 'button';
+  b.className = 'pg-btn pg-btn-secondary';
+  b.dataset.action = action;
+  b.textContent = label;
+  return b;
+}
+
+/**
+ * Resolve a topic slug to a localized label. Falls back to a humanized
+ * version of the slug when the corresponding `topic.<slug>` key is missing
+ * (so a brand-new topic added by a community PR shows something readable
+ * even before the translation is in place).
+ */
+function topicLabel(slug: string): string {
+  const key = `topic.${slug}` as TranslationKey;
+  const v = t(key);
+  return v === key ? humanize(slug) : v;
+}
+
+function subtopicLabel(slug: string): string {
+  const key = `subtopic.${slug}` as TranslationKey;
+  const v = t(key);
+  return v === key ? humanize(slug) : v;
+}
+
+function humanize(slug: string): string {
+  return slug
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join(' ');
+}
diff --git a/src/lib/playground/ValidationPanel.test.ts b/src/lib/playground/ValidationPanel.test.ts
new file mode 100644
index 0000000..803fe58
--- /dev/null
+++ b/src/lib/playground/ValidationPanel.test.ts
@@ -0,0 +1,41 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { createValidationPanel } from './ValidationPanel';
+
+function dom(): HTMLElement {
+  document.body.innerHTML = '<div data-panel="errors"></div>';
+  return document.querySelector<HTMLElement>('[data-panel="errors"]')!;
+}
+
+describe('ValidationPanel', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  test('empty state when no diagnostics', () => {
+    const panel = createValidationPanel(dom());
+    panel.update([]);
+    const root = document.querySelector<HTMLElement>('[data-panel="errors"]')!;
+    expect(root.querySelector('.pg-empty')).not.toBeNull();
+  });
+
+  test('renders errors and warnings (rendered via t() per code)', () => {
+    const panel = createValidationPanel(dom());
+    panel.update([
+      // unknown-key code with params -> en text "Unknown key `foo` in menu-root scope"
+      { severity: 'error', code: 'validate.unknown-key', params: { key: 'foo', scope: 'menu-root' }, message: '', line: 2, column: 3 },
+      { severity: 'warning', code: 'parser.expected-closing-brace', message: '', line: 5, column: 1 },
+    ]);
+    const root = document.querySelector<HTMLElement>('[data-panel="errors"]')!;
+    expect(root.querySelectorAll('.pg-diag-error').length).toBe(1);
+    expect(root.querySelectorAll('.pg-diag-warning').length).toBe(1);
+    expect(root.textContent).toContain('Unknown key `foo`');
+    expect(root.textContent).toContain('2:3');
+  });
+
+  test('click fires onJump with line/col', () => {
+    const panel = createValidationPanel(dom());
+    let jumped: { line: number; column: number } | null = null;
+    panel.onJump((line, column) => { jumped = { line, column }; });
+    panel.update([{ severity: 'error', code: 'parser.expected-closing-brace', message: '', line: 7, column: 4 }]);
+    document.querySelector<HTMLButtonElement>('.pg-diag')!.click();
+    expect(jumped).toEqual({ line: 7, column: 4 });
+  });
+});
diff --git a/src/lib/playground/ValidationPanel.ts b/src/lib/playground/ValidationPanel.ts
new file mode 100644
index 0000000..b42d520
--- /dev/null
+++ b/src/lib/playground/ValidationPanel.ts
@@ -0,0 +1,58 @@
+import type { Diagnostic } from './hocon/types';
+import { formatDiagMessage } from './hocon/diag';
+import { t, type TranslationKey } from './i18n';
+
+type JumpListener = (line: number, column: number) => void;
+
+export interface ValidationPanelApi {
+  update(diagnostics: Diagnostic[]): void;
+  onJump(fn: JumpListener): void;
+}
+
+export function createValidationPanel(
+  panel: HTMLElement,
+  emptyKey: TranslationKey = 'empty.errors',
+): ValidationPanelApi {
+  const listeners: JumpListener[] = [];
+
+  function update(diags: Diagnostic[]): void {
+    if (diags.length === 0) {
+      const p = document.createElement('p');
+      p.className = 'pg-empty';
+      p.textContent = t(emptyKey);
+      panel.replaceChildren(p);
+      return;
+    }
+    const list = document.createElement('ul');
+    list.className = 'pg-diag-list';
+    for (const d of diags) {
+      const li = document.createElement('li');
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = `pg-diag pg-diag-${d.severity}`;
+      const loc = document.createElement('span');
+      loc.className = 'pg-diag-loc';
+      loc.textContent = `${d.line}:${d.column}`;
+      const msg = document.createElement('span');
+      msg.className = 'pg-diag-msg';
+      // Re-render via the active locale every time. Diagnostics carry the
+      // pre-formatted English message too, but the locale may have changed
+      // since emit time (rare in practice - lang switch reloads the page -
+      // but cheap to do right).
+      msg.textContent = formatDiagMessage(d.code, d.params);
+      btn.appendChild(loc);
+      btn.appendChild(document.createTextNode(' '));
+      btn.appendChild(msg);
+      btn.addEventListener('click', () => {
+        for (const fn of listeners) fn(d.line, d.column);
+      });
+      li.appendChild(btn);
+      list.appendChild(li);
+    }
+    panel.replaceChildren(list);
+  }
+
+  function onJump(fn: JumpListener): void { listeners.push(fn); }
+
+  return { update, onJump };
+}
diff --git a/src/lib/playground/catalog/actions.ts b/src/lib/playground/catalog/actions.ts
new file mode 100644
index 0000000..8a4b303
--- /dev/null
+++ b/src/lib/playground/catalog/actions.ts
@@ -0,0 +1,38 @@
+import type { KeyDef } from './types';
+
+export const ACTION_KEYS: KeyDef[] = [
+  { name: 'message', scope: 'actions', valueType: 'string', description: 'Send a chat message to the player.' },
+  { name: 'command', scope: 'actions', valueType: 'any', description: 'Run a console or player command. String or { cmd, as }.' },
+  { name: 'chatInput', scope: 'actions', valueType: 'object', description: 'Prompt the player for chat input.' },
+  { name: 'teleport', scope: 'actions', valueType: 'any', description: 'Teleport the player. Coordinates or named location.' },
+  { name: 'itemAdd', scope: 'actions', valueType: 'object', description: 'Give an item to the player.' },
+  { name: 'itemRemove', scope: 'actions', valueType: 'object', description: 'Remove an item from the player inventory.' },
+  { name: 'sound', scope: 'actions', valueType: 'enum', enumRef: 'sounds', description: 'Play a Bukkit sound.' },
+  { name: 'customSound', scope: 'actions', valueType: 'object', description: 'Play a custom (resource pack) sound.' },
+  { name: 'addPotionEffect', scope: 'actions', valueType: 'object', description: 'Apply a potion effect.' },
+  { name: 'removePotionEffect', scope: 'actions', valueType: 'string', description: 'Remove a potion effect by type.' },
+  { name: 'openBook', scope: 'actions', valueType: 'object', description: 'Open a written book to the player.' },
+  { name: 'openMenu', scope: 'actions', valueType: 'string', description: 'Open another menu by id.' },
+  { name: 'closeMenu', scope: 'actions', valueType: 'any', description: 'Close the currently open menu.' },
+  { name: 'refreshMenu', scope: 'actions', valueType: 'any', description: 'Refresh the current menu (re-render dynamic items).' },
+  { name: 'refreshItem', scope: 'actions', valueType: 'object', description: 'Refresh a specific item by slot or id.' },
+  { name: 'lpMetaSet', scope: 'actions', valueType: 'object', description: 'LuckPerms: set a meta key.' },
+  { name: 'lpMetaRemove', scope: 'actions', valueType: 'object', description: 'LuckPerms: remove a meta key.' },
+  { name: 'setVar', scope: 'actions', valueType: 'object', description: 'Set a personal player variable.' },
+  { name: 'setVarp', scope: 'actions', valueType: 'object', description: 'Set a global (persistent) variable.' },
+  { name: 'removeVar', scope: 'actions', valueType: 'string', description: 'Remove a personal variable.' },
+  { name: 'removeVarp', scope: 'actions', valueType: 'string', description: 'Remove a global variable.' },
+  { name: 'delay', scope: 'actions', valueType: 'object', description: 'Delay following actions by a duration.' },
+  { name: 'bulk', scope: 'actions', valueType: 'object', description: 'Bulk container - groups actions and applies common modifiers.' },
+  { name: 'randActions', scope: 'actions', valueType: 'list', description: 'Pick one of the listed action sets at random.' },
+  { name: 'setSkin', scope: 'actions', valueType: 'object', description: 'Apply a skin via SkinsRestorer.' },
+  { name: 'addRecipe', scope: 'actions', valueType: 'string', description: 'Discover a crafting recipe for the player.' },
+  { name: 'setItemProperty', scope: 'actions', valueType: 'object', description: 'Override an item property at runtime.' },
+  { name: 'removeItemProperty', scope: 'actions', valueType: 'object', description: 'Clear a runtime property override.' },
+  { name: 'setButton', scope: 'actions', valueType: 'object', description: 'Replace a menu button definition at runtime.' },
+  { name: 'removeButton', scope: 'actions', valueType: 'object', description: 'Remove a menu button at runtime.' },
+  { name: 'giveMoney', scope: 'actions', valueType: 'any', description: 'Give Vault money to the player.' },
+  { name: 'takeMoney', scope: 'actions', valueType: 'any', description: 'Take Vault money from the player.' },
+  { name: 'setGamemode', scope: 'actions', valueType: 'string', description: 'Set the player gamemode (CREATIVE/SURVIVAL/...).' },
+  { name: 'bungeeConnect', scope: 'actions', valueType: 'string', description: 'Send the player to a BungeeCord server.' },
+];
diff --git a/src/lib/playground/catalog/activators.ts b/src/lib/playground/catalog/activators.ts
new file mode 100644
index 0000000..3b7aa4a
--- /dev/null
+++ b/src/lib/playground/catalog/activators.ts
@@ -0,0 +1,19 @@
+import type { KeyDef } from './types';
+
+export const ACTIVATOR_KEYS: KeyDef[] = [
+  { name: 'command', scope: 'activators', valueType: 'any', description: 'Open via /command. String, list, or { command, aliases }.' },
+  { name: 'chat', scope: 'activators', valueType: 'any', description: 'Open via chat trigger (full word, partial, or symbol).' },
+  { name: 'regionJoin', scope: 'activators', valueType: 'string', description: 'WorldGuard: open when entering this region.' },
+  { name: 'regionLeave', scope: 'activators', valueType: 'string', description: 'WorldGuard: open when leaving this region.' },
+  { name: 'clickItem', scope: 'activators', valueType: 'object', description: 'Open when clicking a specific item.' },
+  { name: 'clickNPC', scope: 'activators', valueType: 'string', description: 'Citizens NPC click trigger.' },
+  { name: 'clickEntity', scope: 'activators', valueType: 'object', description: 'Open when clicking a specific entity type.' },
+  { name: 'shiftClickEntity', scope: 'activators', valueType: 'object', description: 'Open on shift-click on an entity.' },
+  { name: 'clickBlock', scope: 'activators', valueType: 'object', description: 'Open on click of a block at coordinates.' },
+  { name: 'clickBlockType', scope: 'activators', valueType: 'string', description: 'Open on click of any block of this material.' },
+  { name: 'button', scope: 'activators', valueType: 'object', description: 'Open on button press.' },
+  { name: 'lever', scope: 'activators', valueType: 'object', description: 'Open on lever toggle.' },
+  { name: 'plate', scope: 'activators', valueType: 'object', description: 'Open on pressure-plate step.' },
+  { name: 'table', scope: 'activators', valueType: 'object', description: 'Open on sign click.' },
+  { name: 'swapItems', scope: 'activators', valueType: 'object', description: 'Open on hotbar swap (F key).' },
+];
diff --git a/src/lib/playground/catalog/i18n.test.ts b/src/lib/playground/catalog/i18n.test.ts
new file mode 100644
index 0000000..29f249a
--- /dev/null
+++ b/src/lib/playground/catalog/i18n.test.ts
@@ -0,0 +1,44 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { describeKeyDef } from './i18n';
+import { setLang, _resetForTests } from '../i18n';
+import type { KeyDef } from './types';
+
+const TITLE: KeyDef = {
+  name: 'title',
+  scope: 'menu-root',
+  valueType: 'string',
+  description: 'Menu title shown at the top of the inventory.',
+};
+
+const UNSEEDED: KeyDef = {
+  name: 'completelyMadeUpKey',
+  scope: 'menu-root',
+  valueType: 'string',
+  description: 'English fallback only.',
+};
+
+beforeEach(() => {
+  _resetForTests();
+});
+
+describe('describeKeyDef', () => {
+  test('returns canonical English description by default', () => {
+    expect(describeKeyDef(TITLE)).toBe('Menu title shown at the top of the inventory.');
+  });
+
+  test('returns ru translation when active lang is ru', () => {
+    setLang('ru');
+    expect(describeKeyDef(TITLE)).toContain('Заголовок меню');
+  });
+
+  test('falls back to English when ru lacks the key', () => {
+    setLang('ru');
+    expect(describeKeyDef(UNSEEDED)).toBe('English fallback only.');
+  });
+
+  test('switching back to en uses English again', () => {
+    setLang('ru');
+    setLang('en');
+    expect(describeKeyDef(TITLE)).toBe('Menu title shown at the top of the inventory.');
+  });
+});
diff --git a/src/lib/playground/catalog/i18n.ts b/src/lib/playground/catalog/i18n.ts
new file mode 100644
index 0000000..d907ff9
--- /dev/null
+++ b/src/lib/playground/catalog/i18n.ts
@@ -0,0 +1,41 @@
+import { getLang } from '../i18n';
+import type { KeyDef } from './types';
+
+/**
+ * Per-locale overrides for catalog `description` text. Keys are
+ * `<scope>.<name>` (e.g. `menu-root.title`); values are the translated
+ * description.
+ *
+ * Translation files live in `./translations/<lang>.ts` and are auto-loaded
+ * via import.meta.glob - dropping a new file there registers the locale.
+ * Each file exports either a default object or a named export matching
+ * the file basename. A locale is free to translate only a subset; missing
+ * keys fall back to the canonical English `description` on the KeyDef.
+ */
+const modules = import.meta.glob<Record<string, unknown>>('./translations/*.ts', { eager: true });
+const registry = new Map<string, Record<string, string>>();
+
+for (const [path, mod] of Object.entries(modules)) {
+  const code = /\/([^/]+)\.ts$/.exec(path)?.[1];
+  if (!code) continue;
+  const dict = pickDict(mod, code);
+  if (dict) registry.set(code, dict);
+}
+
+function pickDict(mod: Record<string, unknown>, code: string): Record<string, string> | null {
+  for (const candidate of [mod[code], mod.default]) {
+    if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
+      return candidate as Record<string, string>;
+    }
+  }
+  return null;
+}
+
+export function describeKeyDef(def: KeyDef): string {
+  const dict = registry.get(getLang());
+  if (dict) {
+    const translated = dict[`${def.scope}.${def.name}`];
+    if (translated) return translated;
+  }
+  return def.description;
+}
diff --git a/src/lib/playground/catalog/index.ts b/src/lib/playground/catalog/index.ts
new file mode 100644
index 0000000..e0a2bdc
--- /dev/null
+++ b/src/lib/playground/catalog/index.ts
@@ -0,0 +1,102 @@
+import type { KeyDef, Scope } from './types';
+import { MENU_ROOT_KEYS, ITEM_KEYS, CLICK_KEYS } from './keys';
+import { ACTION_KEYS } from './actions';
+import { RULE_KEYS } from './rules';
+import { ACTIVATOR_KEYS } from './activators';
+import { MATERIALS } from './materials';
+import { SOUNDS } from './sounds';
+import {
+  SLOT_FIELDS,
+  ENCHANTMENT_FIELDS,
+  FIREWORK_FIELDS,
+  FIREWORK_EFFECT_FIELDS,
+  POTION_EFFECT_FIELDS,
+  BINDING_FIELDS,
+} from './sub-scopes';
+
+// List-context scopes (e.g. cursor inside `items = [│]`) intentionally have
+// no key set - the completion source maps them to a single skeleton snippet
+// instead. Keeping them here as empty arrays satisfies Record<Scope, ...>
+// exhaustiveness, and any drive-by call to getKeysForScope returns [].
+const ALL_KEYS_BY_SCOPE: Record<Scope, KeyDef[]> = {
+  'menu-root': MENU_ROOT_KEYS,
+  'item': ITEM_KEYS,
+  'click': CLICK_KEYS,
+  'actions': ACTION_KEYS,
+  'rules': RULE_KEYS,
+  'activators': ACTIVATOR_KEYS,
+  'slot': SLOT_FIELDS,
+  'enchantments': ENCHANTMENT_FIELDS,
+  'firework': FIREWORK_FIELDS,
+  'firework-effect': FIREWORK_EFFECT_FIELDS,
+  'potion-effect': POTION_EFFECT_FIELDS,
+  'binding': BINDING_FIELDS,
+  'item-list': [],
+  'binding-list': [],
+  'firework-effect-list': [],
+  'unknown': [],
+};
+
+let unknownFallback: KeyDef[] | null = null;
+function getAllUniqueKeys(): KeyDef[] {
+  if (unknownFallback) return unknownFallback;
+  const seen = new Set<string>();
+  const out: KeyDef[] = [];
+  for (const list of Object.values(ALL_KEYS_BY_SCOPE)) {
+    for (const k of list) {
+      if (!seen.has(k.name)) { seen.add(k.name); out.push(k); }
+    }
+  }
+  unknownFallback = out;
+  return out;
+}
+
+export function getKeysForScope(scope: Scope): KeyDef[] {
+  const list = ALL_KEYS_BY_SCOPE[scope];
+  if (list && list.length > 0) return list;
+  if (scope === 'unknown') return getAllUniqueKeys();
+  return [];
+}
+
+export function getEnumValues(name: 'materials' | 'sounds'): readonly string[] {
+  return name === 'materials' ? MATERIALS : SOUNDS;
+}
+
+const KEY_BY_NAME: Map<string, KeyDef> = new Map();
+for (const list of Object.values(ALL_KEYS_BY_SCOPE)) {
+  for (const k of list) if (!KEY_BY_NAME.has(k.name)) KEY_BY_NAME.set(k.name, k);
+}
+
+export function findKeyDef(name: string): KeyDef | undefined {
+  return KEY_BY_NAME.get(name);
+}
+
+/**
+ * Resolve the scope that applies INSIDE a `{...}` opened by the given key.
+ * If the key isn't in the catalog (or has no childrenScope), the body is
+ * an `unknown` block: validators and autocomplete should not assume any
+ * particular shape there.
+ *
+ * Single source of truth so the autocomplete (`cm/scope.ts`), the AST-walking
+ * validator (`hocon/unknown-keys.ts`), and the position-indexed range builder
+ * (`hocon/scope-ranges.ts`) all agree on the rule.
+ */
+export function childScopeOf(keyName: string): Scope {
+  return findKeyDef(keyName)?.childrenScope ?? 'unknown';
+}
+
+/**
+ * When the cursor sits inside an array context (`items = [│]`), the relevant
+ * scope is the *list* variant - we offer a skeleton snippet for the element
+ * shape, not the keys that go inside that element.
+ */
+export function arrayPositionScope(elementScope: Scope): Scope {
+  switch (elementScope) {
+    case 'item': return 'item-list';
+    case 'binding': return 'binding-list';
+    case 'firework-effect': return 'firework-effect-list';
+    default: return elementScope;
+  }
+}
+
+export type { KeyDef, Scope } from './types';
diff --git a/src/lib/playground/catalog/item-props.ts b/src/lib/playground/catalog/item-props.ts
new file mode 100644
index 0000000..d37ab0a
--- /dev/null
+++ b/src/lib/playground/catalog/item-props.ts
@@ -0,0 +1 @@
+export { ITEM_KEYS } from './keys';
diff --git a/src/lib/playground/catalog/keys.ts b/src/lib/playground/catalog/keys.ts
new file mode 100644
index 0000000..d8dcab7
--- /dev/null
+++ b/src/lib/playground/catalog/keys.ts
@@ -0,0 +1,57 @@
+import type { KeyDef } from './types';
+
+export const MENU_ROOT_KEYS: KeyDef[] = [
+  { name: 'title', scope: 'menu-root', valueType: 'string', description: 'Menu title shown at the top of the inventory.' },
+  { name: 'size', scope: 'menu-root', valueType: 'integer', description: 'Number of inventory rows (1-6).' },
+  { name: 'activators', scope: 'menu-root', valueType: 'object', childrenScope: 'activators', description: 'How players open this menu (commands, clicks, regions, etc.).' },
+  { name: 'items', scope: 'menu-root', valueType: 'list', childrenScope: 'item', description: 'List of items rendered in the menu.' },
+  { name: 'denyActions', scope: 'menu-root', valueType: 'object', childrenScope: 'actions', description: 'Default deny-actions block when click rules fail.' },
+  { name: 'updateInterval', scope: 'menu-root', valueType: 'duration', description: 'How often the menu re-renders dynamic items (e.g. 20t, 1s).' },
+  { name: 'requirements', scope: 'menu-root', valueType: 'object', childrenScope: 'rules', description: 'Open-time requirements (rules that must pass to open the menu).' },
+  { name: 'pages', scope: 'menu-root', valueType: 'integer', description: 'For paginated menus: number of pages.' },
+  { name: 'menus', scope: 'menu-root', valueType: 'list', childrenScope: 'item', description: 'For animated menus: list of frame definitions.' },
+  { name: 'metaList', scope: 'menu-root', valueType: 'list', description: 'Initial player-meta values to set on open.' },
+  { name: 'closeActions', scope: 'menu-root', valueType: 'object', childrenScope: 'actions', description: 'Actions to fire when the menu closes.' },
+  { name: 'matrix', scope: 'menu-root', valueType: 'list', description: 'Layout matrix for generated menus (each row a string of slot codes).' },
+  // `defaults` is a community convention rather than a hard AbstractMenus
+  // field: it's the canonical name for "shared item template I substitute
+  // into each item via ${defaults}". Recognising it here keeps the DRY
+  // pattern lessons (05-dotted-keys, 22-object-merge, 23-defaults-merge)
+  // free of spurious unknown-key warnings.
+  { name: 'defaults', scope: 'menu-root', valueType: 'object', childrenScope: 'item', description: 'Shared item template; reused via ${defaults} substitution.' },
+];
+
+export const ITEM_KEYS: KeyDef[] = [
+  { name: 'slot', scope: 'item', valueType: 'any', childrenScope: 'slot', description: 'Inventory slot. Single (0), range "0-8", coordinates "1,2", or matrix (object).' },
+  { name: 'material', scope: 'item', valueType: 'enum', enumRef: 'materials', description: 'Bukkit material name. Type "IRON" for IRON_INGOT, IRON_BLOCK, ...' },
+  { name: 'name', scope: 'item', valueType: 'string', description: 'Item display name (legacy color codes & supported).' },
+  { name: 'lore', scope: 'item', valueType: 'list', description: 'Lore lines.' },
+  { name: 'count', scope: 'item', valueType: 'integer', description: 'Stack size (1-64).' },
+  { name: 'click', scope: 'item', valueType: 'object', childrenScope: 'click', description: 'Click handler: which buttons fire which actions.' },
+  { name: 'rules', scope: 'item', valueType: 'object', childrenScope: 'rules', description: 'Visibility/click rules attached to this item.' },
+  { name: 'sound', scope: 'item', valueType: 'enum', enumRef: 'sounds', description: 'Sound to play when interacting with the item.' },
+  { name: 'texture', scope: 'item', valueType: 'string', description: 'Custom head texture (URL, hash, or base64).' },
+  { name: 'skullOwner', scope: 'item', valueType: 'string', description: 'Player name whose skin to use for PLAYER_HEAD.' },
+  { name: 'flags', scope: 'item', valueType: 'list', description: 'ItemFlag list (HIDE_ENCHANTS, HIDE_ATTRIBUTES, ...).' },
+  { name: 'enchantments', scope: 'item', valueType: 'object', childrenScope: 'enchantments', description: 'Map of enchantment name to level (e.g. { SHARPNESS = 5 }).' },
+  { name: 'color', scope: 'item', valueType: 'any', description: 'Color (RGB list, named, or HEX) for leather armor / potions.' },
+  { name: 'cooldown', scope: 'item', valueType: 'duration', description: 'Click cooldown for this item (e.g. 5s).' },
+  { name: 'placedItem', scope: 'item', valueType: 'object', childrenScope: 'item', description: 'Item placed into anvil/crafting slot (input mode menus).' },
+  { name: 'updateInterval', scope: 'item', valueType: 'duration', description: 'Per-item update interval (overrides menu-level).' },
+  { name: 'bindings', scope: 'item', valueType: 'list', childrenScope: 'binding', description: 'Rules-gated property overrides.' },
+  { name: 'item', scope: 'item', valueType: 'object', childrenScope: 'item', description: 'Override an existing item template by reference.' },
+  { name: 'effect', scope: 'item', valueType: 'object', childrenScope: 'potion-effect', description: 'Potion effect data (POTION/SPLASH_POTION items).' },
+  { name: 'firework', scope: 'item', valueType: 'object', childrenScope: 'firework', description: 'Firework explosion data.' },
+];
+
+export const CLICK_KEYS: KeyDef[] = [
+  { name: 'left', scope: 'click', valueType: 'object', childrenScope: 'click', description: 'Left-click handler (actions/rules/denyActions).' },
+  { name: 'right', scope: 'click', valueType: 'object', childrenScope: 'click', description: 'Right-click handler.' },
+  { name: 'middle', scope: 'click', valueType: 'object', childrenScope: 'click', description: 'Middle-click handler.' },
+  { name: 'drop', scope: 'click', valueType: 'object', childrenScope: 'click', description: 'Drop-key (Q) handler.' },
+  { name: 'shiftLeft', scope: 'click', valueType: 'object', childrenScope: 'click', description: 'Shift+Left click handler.' },
+  { name: 'shiftRight', scope: 'click', valueType: 'object', childrenScope: 'click', description: 'Shift+Right click handler.' },
+  { name: 'actions', scope: 'click', valueType: 'object', childrenScope: 'actions', description: 'Actions fired on this click (when rules pass).' },
+  { name: 'rules', scope: 'click', valueType: 'object', childrenScope: 'rules', description: 'Rules that gate the actions.' },
+  { name: 'denyActions', scope: 'click', valueType: 'object', childrenScope: 'actions', description: 'Actions fired when rules fail.' },
+];
diff --git a/src/lib/playground/catalog/materials.ts b/src/lib/playground/catalog/materials.ts
new file mode 100644
index 0000000..c461722
--- /dev/null
+++ b/src/lib/playground/catalog/materials.ts
@@ -0,0 +1,39 @@
+export const MATERIALS: readonly string[] = [
+  'AIR', 'STONE', 'GRASS_BLOCK', 'DIRT', 'COBBLESTONE', 'OAK_PLANKS', 'SPRUCE_PLANKS', 'BIRCH_PLANKS',
+  'JUNGLE_PLANKS', 'ACACIA_PLANKS', 'DARK_OAK_PLANKS', 'CRIMSON_PLANKS', 'WARPED_PLANKS',
+  'SAND', 'GRAVEL', 'GOLD_ORE', 'IRON_ORE', 'COAL_ORE', 'NETHERITE_INGOT', 'NETHERITE_BLOCK',
+  'DIAMOND', 'DIAMOND_BLOCK', 'IRON_INGOT', 'IRON_BLOCK', 'GOLD_INGOT', 'GOLD_BLOCK', 'EMERALD',
+  'EMERALD_BLOCK', 'COAL', 'COAL_BLOCK', 'REDSTONE', 'REDSTONE_BLOCK', 'LAPIS_LAZULI', 'LAPIS_BLOCK',
+  'OAK_LOG', 'SPRUCE_LOG', 'BIRCH_LOG', 'JUNGLE_LOG', 'ACACIA_LOG', 'DARK_OAK_LOG',
+  'OAK_LEAVES', 'SPRUCE_LEAVES', 'BIRCH_LEAVES',
+  'GLASS', 'WHITE_STAINED_GLASS', 'ORANGE_STAINED_GLASS', 'YELLOW_STAINED_GLASS', 'GREEN_STAINED_GLASS',
+  'LIME_STAINED_GLASS', 'BLUE_STAINED_GLASS', 'CYAN_STAINED_GLASS', 'PURPLE_STAINED_GLASS',
+  'MAGENTA_STAINED_GLASS', 'PINK_STAINED_GLASS', 'BROWN_STAINED_GLASS', 'GRAY_STAINED_GLASS',
+  'LIGHT_GRAY_STAINED_GLASS', 'BLACK_STAINED_GLASS', 'RED_STAINED_GLASS',
+  'WHITE_STAINED_GLASS_PANE', 'BLACK_STAINED_GLASS_PANE', 'GRAY_STAINED_GLASS_PANE', 'RED_STAINED_GLASS_PANE',
+  'GREEN_STAINED_GLASS_PANE', 'BLUE_STAINED_GLASS_PANE', 'YELLOW_STAINED_GLASS_PANE',
+  'WHITE_WOOL', 'BLACK_WOOL', 'GRAY_WOOL', 'LIGHT_GRAY_WOOL', 'RED_WOOL', 'ORANGE_WOOL', 'YELLOW_WOOL',
+  'LIME_WOOL', 'GREEN_WOOL', 'CYAN_WOOL', 'BLUE_WOOL', 'PURPLE_WOOL', 'MAGENTA_WOOL', 'PINK_WOOL',
+  'BROWN_WOOL',
+  'WOODEN_SWORD', 'STONE_SWORD', 'IRON_SWORD', 'GOLDEN_SWORD', 'DIAMOND_SWORD', 'NETHERITE_SWORD',
+  'WOODEN_PICKAXE', 'STONE_PICKAXE', 'IRON_PICKAXE', 'GOLDEN_PICKAXE', 'DIAMOND_PICKAXE', 'NETHERITE_PICKAXE',
+  'WOODEN_AXE', 'STONE_AXE', 'IRON_AXE', 'GOLDEN_AXE', 'DIAMOND_AXE', 'NETHERITE_AXE',
+  'WOODEN_SHOVEL', 'IRON_SHOVEL', 'DIAMOND_SHOVEL',
+  'BOW', 'CROSSBOW', 'ARROW', 'TIPPED_ARROW', 'TRIDENT', 'SHIELD',
+  'LEATHER_HELMET', 'LEATHER_CHESTPLATE', 'LEATHER_LEGGINGS', 'LEATHER_BOOTS',
+  'IRON_HELMET', 'IRON_CHESTPLATE', 'IRON_LEGGINGS', 'IRON_BOOTS',
+  'DIAMOND_HELMET', 'DIAMOND_CHESTPLATE', 'DIAMOND_LEGGINGS', 'DIAMOND_BOOTS',
+  'NETHERITE_HELMET', 'NETHERITE_CHESTPLATE', 'NETHERITE_LEGGINGS', 'NETHERITE_BOOTS',
+  'BREAD', 'APPLE', 'GOLDEN_APPLE', 'ENCHANTED_GOLDEN_APPLE', 'CARROT', 'POTATO', 'BAKED_POTATO',
+  'COOKED_BEEF', 'BEEF', 'COOKED_PORKCHOP', 'PORKCHOP', 'COOKED_CHICKEN', 'CHICKEN', 'COOKED_FISH',
+  'COD', 'SALMON', 'CAKE', 'COOKIE', 'PUMPKIN_PIE', 'CHORUS_FRUIT', 'BEETROOT_SOUP',
+  'POTION', 'SPLASH_POTION', 'LINGERING_POTION',
+  'PLAYER_HEAD', 'ZOMBIE_HEAD', 'SKELETON_SKULL', 'CREEPER_HEAD', 'DRAGON_HEAD', 'WITHER_SKELETON_SKULL',
+  'BOOK', 'WRITTEN_BOOK', 'WRITABLE_BOOK', 'ENCHANTED_BOOK', 'KNOWLEDGE_BOOK',
+  'COMPASS', 'CLOCK', 'MAP', 'PAPER', 'NAME_TAG',
+  'CHEST', 'TRAPPED_CHEST', 'ENDER_CHEST', 'BARREL', 'SHULKER_BOX',
+  'TORCH', 'LANTERN', 'SOUL_LANTERN', 'BEACON', 'CONDUIT', 'GLOWSTONE', 'SEA_LANTERN',
+  'EXPERIENCE_BOTTLE', 'TOTEM_OF_UNDYING', 'NETHER_STAR', 'DRAGON_EGG',
+  'ENDER_PEARL', 'ENDER_EYE', 'BLAZE_ROD', 'FEATHER', 'STRING', 'SLIME_BALL', 'GUNPOWDER',
+  'BARRIER', 'STRUCTURE_VOID', 'COMMAND_BLOCK',
+];
diff --git a/src/lib/playground/catalog/rules.ts b/src/lib/playground/catalog/rules.ts
new file mode 100644
index 0000000..7494580
--- /dev/null
+++ b/src/lib/playground/catalog/rules.ts
@@ -0,0 +1,19 @@
+import type { KeyDef } from './types';
+
+export const RULE_KEYS: KeyDef[] = [
+  { name: 'permission', scope: 'rules', valueType: 'string', description: 'Player must have this permission.' },
+  { name: 'money', scope: 'rules', valueType: 'integer', description: 'Player must have at least this Vault balance.' },
+  { name: 'levels', scope: 'rules', valueType: 'integer', description: 'Player must have at least this XP level.' },
+  { name: 'gamemode', scope: 'rules', valueType: 'string', description: 'Player must be in this gamemode.' },
+  { name: 'world', scope: 'rules', valueType: 'string', description: 'Player must be in this world.' },
+  { name: 'region', scope: 'rules', valueType: 'string', description: 'WorldGuard: player must be in this region.' },
+  { name: 'inventoryItems', scope: 'rules', valueType: 'object', description: 'Player must have these items in inventory.' },
+  { name: 'heldItem', scope: 'rules', valueType: 'object', description: 'Player must hold this item.' },
+  { name: 'varExisting', scope: 'rules', valueType: 'object', description: 'Variable must exist with given value.' },
+  { name: 'bungeeOnline', scope: 'rules', valueType: 'string', description: 'BungeeCord server must be online.' },
+  { name: 'if', scope: 'rules', valueType: 'object', description: 'Conditional rule: { left, op, right }.' },
+  { name: 'js', scope: 'rules', valueType: 'string', description: 'JavaScript predicate (returns truthy to pass).' },
+  { name: 'placeholder', scope: 'rules', valueType: 'object', description: 'PlaceholderAPI value comparison.' },
+  { name: 'time', scope: 'rules', valueType: 'object', description: 'In-world time of day comparison.' },
+  { name: 'cooldown', scope: 'rules', valueType: 'duration', description: 'Per-player cooldown gate.' },
+];
diff --git a/src/lib/playground/catalog/sounds.ts b/src/lib/playground/catalog/sounds.ts
new file mode 100644
index 0000000..da87c29
--- /dev/null
+++ b/src/lib/playground/catalog/sounds.ts
@@ -0,0 +1,82 @@
+export const SOUNDS: readonly string[] = [
+  'UI_BUTTON_CLICK',
+  'BLOCK_NOTE_BLOCK_PLING',
+  'BLOCK_NOTE_BLOCK_HARP',
+  'BLOCK_NOTE_BLOCK_BELL',
+  'BLOCK_NOTE_BLOCK_CHIME',
+  'BLOCK_NOTE_BLOCK_HAT',
+  'BLOCK_NOTE_BLOCK_BASS',
+  'BLOCK_ANVIL_USE',
+  'BLOCK_ANVIL_LAND',
+  'BLOCK_CHEST_OPEN',
+  'BLOCK_CHEST_CLOSE',
+  'BLOCK_BARREL_OPEN',
+  'BLOCK_BARREL_CLOSE',
+  'BLOCK_BEACON_ACTIVATE',
+  'BLOCK_BEACON_DEACTIVATE',
+  'BLOCK_END_PORTAL_SPAWN',
+  'BLOCK_PORTAL_AMBIENT',
+  'BLOCK_PORTAL_TRIGGER',
+  'BLOCK_PORTAL_TRAVEL',
+  'BLOCK_FIRE_EXTINGUISH',
+  'BLOCK_GRINDSTONE_USE',
+  'BLOCK_LEVER_CLICK',
+  'BLOCK_GLASS_BREAK',
+  'BLOCK_WOOD_BREAK',
+  'BLOCK_STONE_BREAK',
+  'BLOCK_METAL_BREAK',
+  'ENTITY_EXPERIENCE_ORB_PICKUP',
+  'ENTITY_PLAYER_LEVELUP',
+  'ENTITY_PLAYER_HURT',
+  'ENTITY_PLAYER_DEATH',
+  'ENTITY_PLAYER_BURP',
+  'ENTITY_VILLAGER_TRADE',
+  'ENTITY_VILLAGER_NO',
+  'ENTITY_VILLAGER_YES',
+  'ENTITY_VILLAGER_AMBIENT',
+  'ENTITY_VILLAGER_CELEBRATE',
+  'ENTITY_ENDER_DRAGON_AMBIENT',
+  'ENTITY_ENDER_DRAGON_GROWL',
+  'ENTITY_ENDER_DRAGON_DEATH',
+  'ENTITY_WITHER_SPAWN',
+  'ENTITY_WITHER_DEATH',
+  'ENTITY_LIGHTNING_BOLT_THUNDER',
+  'ENTITY_LIGHTNING_BOLT_IMPACT',
+  'ENTITY_GENERIC_EXPLODE',
+  'ENTITY_GENERIC_EAT',
+  'ENTITY_GENERIC_DRINK',
+  'ENTITY_ITEM_PICKUP',
+  'ENTITY_ITEM_BREAK',
+  'ENTITY_ARROW_HIT',
+  'ENTITY_ARROW_HIT_PLAYER',
+  'ENTITY_ARROW_SHOOT',
+  'ENTITY_FIREWORK_ROCKET_LAUNCH',
+  'ENTITY_FIREWORK_ROCKET_BLAST',
+  'ENTITY_TOTEM_USE',
+  'ENTITY_ENDERMAN_TELEPORT',
+  'ENTITY_BAT_TAKEOFF',
+  'ENTITY_CAT_PURR',
+  'ENTITY_CAT_PURREOW',
+  'ENTITY_WOLF_HOWL',
+  'ENTITY_HORSE_AMBIENT',
+  'ENTITY_PIG_AMBIENT',
+  'ENTITY_COW_AMBIENT',
+  'ENTITY_CHICKEN_AMBIENT',
+  'ENTITY_SHEEP_AMBIENT',
+  'ENTITY_FOX_AMBIENT',
+  'MUSIC_DISC_13',
+  'MUSIC_DISC_CAT',
+  'MUSIC_DISC_BLOCKS',
+  'MUSIC_DISC_FAR',
+  'MUSIC_MENU',
+  'MUSIC_GAME',
+  'AMBIENT_CAVE',
+  'AMBIENT_UNDERWATER_ENTER',
+  'AMBIENT_UNDERWATER_EXIT',
+  'WEATHER_RAIN',
+  'WEATHER_RAIN_ABOVE',
+  'ITEM_BOOK_PAGE_TURN',
+  'ITEM_BUCKET_FILL',
+  'ITEM_BUCKET_EMPTY',
+  'ITEM_FLINTANDSTEEL_USE',
+];
diff --git a/src/lib/playground/catalog/sub-scopes.ts b/src/lib/playground/catalog/sub-scopes.ts
new file mode 100644
index 0000000..4e003aa
--- /dev/null
+++ b/src/lib/playground/catalog/sub-scopes.ts
@@ -0,0 +1,53 @@
+import type { KeyDef } from './types';
+
+export const SLOT_FIELDS: KeyDef[] = [
+  { name: 'matrix', scope: 'slot', valueType: 'list', description: 'List of strings, one per menu row. Non-"-" characters mark selected cells.' },
+  { name: 'symbol', scope: 'slot', valueType: 'string', description: 'Character used in the matrix to mark a selected cell.' },
+];
+
+export const FIREWORK_FIELDS: KeyDef[] = [
+  { name: 'power', scope: 'firework', valueType: 'integer', description: 'Firework flight duration (1-3 typical).' },
+  { name: 'effects', scope: 'firework', valueType: 'list', childrenScope: 'firework-effect', description: 'List of firework effects.' },
+];
+
+export const FIREWORK_EFFECT_FIELDS: KeyDef[] = [
+  { name: 'type', scope: 'firework-effect', valueType: 'string', description: 'Effect shape: BALL, BURST, BALL_LARGE, STAR, CREEPER.' },
+  { name: 'colors', scope: 'firework-effect', valueType: 'list', description: 'Primary colors (list of RGB lists or color names).' },
+  { name: 'fadeColors', scope: 'firework-effect', valueType: 'list', description: 'Fade colors.' },
+  { name: 'flicker', scope: 'firework-effect', valueType: 'boolean', description: 'Add flicker effect.' },
+  { name: 'trail', scope: 'firework-effect', valueType: 'boolean', description: 'Add trail effect.' },
+];
+
+export const POTION_EFFECT_FIELDS: KeyDef[] = [
+  { name: 'type', scope: 'potion-effect', valueType: 'string', description: 'Effect type (SPEED, REGENERATION, NIGHT_VISION, ...).' },
+  { name: 'duration', scope: 'potion-effect', valueType: 'duration', description: 'Effect duration (e.g. 30s).' },
+  { name: 'amplifier', scope: 'potion-effect', valueType: 'integer', description: 'Amplifier level (0 = level I).' },
+  { name: 'ambient', scope: 'potion-effect', valueType: 'boolean', description: 'Reduce particle alpha (beacon-style).' },
+  { name: 'particles', scope: 'potion-effect', valueType: 'boolean', description: 'Show particles around player.' },
+  { name: 'icon', scope: 'potion-effect', valueType: 'boolean', description: 'Show effect icon in HUD.' },
+];
+
+export const BINDING_FIELDS: KeyDef[] = [
+  { name: 'rules', scope: 'binding', valueType: 'object', childrenScope: 'rules', description: 'Rules that gate this binding (must pass for props to apply).' },
+  { name: 'props', scope: 'binding', valueType: 'object', childrenScope: 'item', description: 'Item properties to apply when rules pass (any item-scope key).' },
+];
+
+const ENCHANT_NAMES = [
+  'SHARPNESS', 'SMITE', 'BANE_OF_ARTHROPODS', 'KNOCKBACK', 'FIRE_ASPECT', 'LOOTING', 'SWEEPING_EDGE',
+  'EFFICIENCY', 'SILK_TOUCH', 'UNBREAKING', 'FORTUNE',
+  'POWER', 'PUNCH', 'FLAME', 'INFINITY',
+  'LUCK_OF_THE_SEA', 'LURE',
+  'AQUA_AFFINITY', 'RESPIRATION', 'DEPTH_STRIDER', 'FROST_WALKER',
+  'PROTECTION', 'FIRE_PROTECTION', 'BLAST_PROTECTION', 'PROJECTILE_PROTECTION', 'FEATHER_FALLING',
+  'THORNS', 'SOUL_SPEED', 'SWIFT_SNEAK',
+  'MULTISHOT', 'QUICK_CHARGE', 'PIERCING',
+  'MENDING', 'CURSE_OF_VANISHING', 'CURSE_OF_BINDING',
+  'RIPTIDE', 'LOYALTY', 'IMPALING', 'CHANNELING',
+];
+
+export const ENCHANTMENT_FIELDS: KeyDef[] = ENCHANT_NAMES.map((name) => ({
+  name,
+  scope: 'enchantments' as const,
+  valueType: 'integer' as const,
+  description: `${name.toLowerCase().replace(/_/g, ' ')} enchantment level.`,
+}));
diff --git a/src/lib/playground/catalog/translations/ru.ts b/src/lib/playground/catalog/translations/ru.ts
new file mode 100644
index 0000000..f7b8657
--- /dev/null
+++ b/src/lib/playground/catalog/translations/ru.ts
@@ -0,0 +1,87 @@
+/**
+ * Russian translations for catalog key descriptions.
+ *
+ * Keys: `<scope>.<name>` (matches what the playground uses to look up a
+ * KeyDef). Missing keys fall back to the canonical English description on
+ * the KeyDef, so partial translations are fine - extend incrementally.
+ */
+export const ru: Record<string, string> = {
+  // menu-root
+  'menu-root.title': 'Заголовок меню над инвентарём.',
+  'menu-root.size': 'Количество рядов инвентаря (1-6).',
+  'menu-root.activators': 'Как игроки открывают меню (команды, клики, регионы и т.д.).',
+  'menu-root.items': 'Список items, отображаемых в меню.',
+  'menu-root.denyActions': 'Действия по умолчанию когда click rules не прошли.',
+  'menu-root.updateInterval': 'Как часто меню пере-рендерит динамические items (например 20t, 1s).',
+  'menu-root.requirements': 'Требования при открытии (rules которые должны пройти).',
+  'menu-root.pages': 'Для постраничных меню: число страниц.',
+  'menu-root.menus': 'Для анимированных меню: список фрейм-определений.',
+  'menu-root.metaList': 'Начальные значения player-meta при открытии.',
+  'menu-root.closeActions': 'Действия при закрытии меню.',
+  'menu-root.matrix': 'Layout-матрица для генерируемых меню (каждый ряд - строка slot-кодов).',
+  'menu-root.defaults': 'Общий item-шаблон; переиспользуется через подстановку ${defaults}.',
+
+  // item
+  'item.slot': 'Слот в инвентаре. Один номер (0), диапазон "0-8", координаты "1,2", или матрица (объект).',
+  'item.material': 'Bukkit material. Печатай "IRON" - получишь IRON_INGOT, IRON_BLOCK, ...',
+  'item.name': 'Отображаемое имя предмета (поддерживает legacy-цвета через &).',
+  'item.lore': 'Строки lore.',
+  'item.count': 'Размер стака (1-64).',
+  'item.click': 'Click-обработчик: какие кнопки запускают какие действия.',
+  'item.rules': 'Rules видимости/клика для этого item.',
+  'item.sound': 'Звук при взаимодействии с item.',
+  'item.texture': 'Кастомная текстура головы (URL, hash или base64).',
+  'item.skullOwner': 'Имя игрока, чей скин использовать для PLAYER_HEAD.',
+  'item.flags': 'Список ItemFlag (HIDE_ENCHANTS, HIDE_ATTRIBUTES, ...).',
+  'item.enchantments': 'Карта зачарование→уровень (например { SHARPNESS = 5 }).',
+  'item.color': 'Цвет (RGB-список, имя или HEX) для кожаной брони / зелий.',
+  'item.cooldown': 'Cooldown клика для этого item (например 5s).',
+  'item.placedItem': 'Item в anvil/crafting слоте (для input-меню).',
+  'item.updateInterval': 'Per-item интервал обновления (перекрывает menu-level).',
+  'item.bindings': 'Rules-гейтированные перекрытия свойств.',
+  'item.item': 'Перекрыть существующий item-шаблон по ссылке.',
+  'item.effect': 'Данные потионного эффекта (для POTION/SPLASH_POTION).',
+  'item.firework': 'Данные взрыва фейерверка.',
+
+  // click
+  'click.left': 'Обработчик левого клика (actions/rules/denyActions).',
+  'click.right': 'Обработчик правого клика.',
+  'click.middle': 'Обработчик среднего клика.',
+  'click.drop': 'Обработчик drop-кнопки (Q).',
+  'click.shiftLeft': 'Обработчик Shift+левый клик.',
+  'click.shiftRight': 'Обработчик Shift+правый клик.',
+  'click.actions': 'Действия запускаемые на этот клик (когда rules прошли).',
+  'click.rules': 'Rules гейтящие действия.',
+  'click.denyActions': 'Действия запускаемые когда rules не прошли.',
+
+  // actions (most common)
+  'actions.message': 'Отправить чат-сообщение игроку.',
+  'actions.command': 'Запустить console- или player-команду. Строка или { cmd, as }.',
+  'actions.sound': 'Воспроизвести Bukkit-звук.',
+  'actions.openMenu': 'Открыть другое меню по id.',
+  'actions.closeMenu': 'Закрыть текущее открытое меню.',
+  'actions.refreshMenu': 'Обновить текущее меню (перерендерить динамические items).',
+  'actions.itemAdd': 'Выдать item игроку.',
+  'actions.itemRemove': 'Забрать item из инвентаря игрока.',
+  'actions.teleport': 'Телепортировать игрока. Координаты или именованная локация.',
+  'actions.giveMoney': 'Выдать Vault-валюту игроку.',
+  'actions.takeMoney': 'Забрать Vault-валюту у игрока.',
+  'actions.setGamemode': 'Задать gamemode (CREATIVE/SURVIVAL/...).',
+
+  // rules
+  'rules.permission': 'У игрока должен быть этот permission.',
+  'rules.money': 'У игрока должен быть как минимум такой Vault-баланс.',
+  'rules.levels': 'У игрока должно быть как минимум столько XP-уровней.',
+  'rules.gamemode': 'Игрок должен быть в этом gamemode.',
+  'rules.world': 'Игрок должен быть в этом мире.',
+  'rules.region': 'WorldGuard: игрок должен быть в этом регионе.',
+  'rules.cooldown': 'Per-player cooldown гейт.',
+
+  // binding
+  'binding.rules': 'Rules гейтящие этот binding (должны пройти чтобы props применились).',
+  'binding.props': 'Свойства item для применения когда rules прошли (любой item-scope ключ).',
+
+  // activators
+  'activators.command': 'Открывать через /команда. Строка, список или { command, aliases }.',
+  'activators.chat': 'Открывать через chat-триггер (полное слово, частичное или символ).',
+};
diff --git a/src/lib/playground/catalog/types.ts b/src/lib/playground/catalog/types.ts
new file mode 100644
index 0000000..04f9158
--- /dev/null
+++ b/src/lib/playground/catalog/types.ts
@@ -0,0 +1,33 @@
+export type Scope =
+  | 'menu-root'
+  | 'item'
+  | 'click'
+  | 'actions'
+  | 'rules'
+  | 'activators'
+  | 'slot'
+  | 'enchantments'
+  | 'firework'
+  | 'firework-effect'
+  | 'potion-effect'
+  | 'binding'
+  | 'item-list'
+  | 'binding-list'
+  | 'firework-effect-list'
+  | 'unknown';
+
+export interface KeyDef {
+  name: string;
+  scope: Scope;
+  valueType: 'string' | 'integer' | 'boolean' | 'list' | 'object' | 'enum' | 'duration' | 'any';
+  enumRef?: 'materials' | 'sounds';
+  /** When this key opens a `{...}` or `[{...}]`, suggestions inside switch to this scope. */
+  childrenScope?: Scope;
+  description: string;
+  example?: string;
+}
+
+export interface EnumDef {
+  name: string;
+  description?: string;
+}
diff --git a/src/lib/playground/cm/catalog-source.test.ts b/src/lib/playground/cm/catalog-source.test.ts
new file mode 100644
index 0000000..f6b6abc
--- /dev/null
+++ b/src/lib/playground/cm/catalog-source.test.ts
@@ -0,0 +1,37 @@
+import { describe, test, expect } from 'vitest';
+import { findEnumContextAtCursor } from './catalog-source';
+
+describe('findEnumContextAtCursor', () => {
+  test('material with no partial', () => {
+    const text = 'material = ';
+    expect(findEnumContextAtCursor(text, text.length)).toEqual({
+      enumName: 'materials',
+      from: text.length,
+      to: text.length,
+    });
+  });
+
+  test('material with partial', () => {
+    const text = 'material = IRO';
+    const r = findEnumContextAtCursor(text, text.length);
+    expect(r?.enumName).toBe('materials');
+    expect(text.slice(r!.from, r!.to)).toBe('IRO');
+  });
+
+  test('sound key', () => {
+    const text = 'sound = UI';
+    const r = findEnumContextAtCursor(text, text.length);
+    expect(r?.enumName).toBe('sounds');
+  });
+
+  test('non-enum key returns null', () => {
+    expect(findEnumContextAtCursor('title = ', 8)).toBeNull();
+  });
+
+  test('quoted enum value', () => {
+    const text = 'material = "DIA';
+    const r = findEnumContextAtCursor(text, text.length);
+    expect(r?.enumName).toBe('materials');
+    expect(text.slice(r!.from, r!.to)).toBe('DIA');
+  });
+});
diff --git a/src/lib/playground/cm/catalog-source.ts b/src/lib/playground/cm/catalog-source.ts
new file mode 100644
index 0000000..12d1cc6
--- /dev/null
+++ b/src/lib/playground/cm/catalog-source.ts
@@ -0,0 +1,101 @@
+import { snippetCompletion, type Completion, type CompletionContext, type CompletionResult } from '@codemirror/autocomplete';
+import { getKeysForScope, getEnumValues, findKeyDef, type KeyDef } from '../catalog';
+import { describeKeyDef } from '../catalog/i18n';
+import { detectScope } from './scope';
+import { hoconSnippets } from './snippets';
+
+export interface CatalogSourceOptions {
+  fallbackSnippets?: Completion[];
+}
+
+/**
+ * In an array context (cursor inside `items = [│]`) the only legal element
+ * is an object literal of the matching shape - dumping all object fields
+ * here would just generate invalid HOCON. Map list-scopes to the snippet
+ * that inserts a skeleton.
+ */
+const LIST_SCOPE_TO_SNIPPET: Record<string, string> = {
+  'item-list': 'item',
+  'binding-list': 'binding',
+  'firework-effect-list': 'fireworkEffect',
+};
+
+export function createCatalogSource(opts: CatalogSourceOptions = {}) {
+  return function catalogSource(context: CompletionContext): CompletionResult | null {
+    const text = context.state.doc.toString();
+    const pos = context.pos;
+
+    const enumComps = enumCompletionsForCursor(text, pos);
+    if (enumComps) return enumComps;
+
+    const word = context.matchBefore(/[\w-]*/);
+    if (!word || (word.from === word.to && !context.explicit)) return null;
+
+    const scope = detectScope(text, pos);
+
+    const skeletonName = LIST_SCOPE_TO_SNIPPET[scope];
+    if (skeletonName) {
+      const snip = hoconSnippets.find((s) => s.label === skeletonName);
+      if (snip) {
+        return {
+          from: word.from,
+          options: [snippetCompletion(snip.template, { label: snip.label, info: snip.info, type: 'snippet' })],
+          validFor: /^[\w-]*$/,
+        };
+      }
+      return null;
+    }
+
+    const keyDefs = getKeysForScope(scope);
+    const keyComps = keyDefs.map(keyToCompletion);
+
+    return {
+      from: word.from,
+      options: [...keyComps, ...(opts.fallbackSnippets ?? [])],
+      validFor: /^[\w-]*$/,
+    };
+  };
+}
+
+function keyToCompletion(k: KeyDef): Completion {
+  const detail = k.valueType === 'enum' ? `enum:${k.enumRef}` : k.valueType;
+  return {
+    label: k.name,
+    type: 'property',
+    detail,
+    info: describeKeyDef(k),
+    apply: k.name,
+    boost: k.valueType === 'enum' ? 2 : 1,
+  };
+}
+
+interface EnumContext {
+  enumName: 'materials' | 'sounds';
+  from: number;
+  to: number;
+}
+
+export function findEnumContextAtCursor(text: string, pos: number): EnumContext | null {
+  const lineStart = text.lastIndexOf('\n', pos - 1) + 1;
+  const linePrefix = text.slice(lineStart, pos);
+  const m = /([A-Za-z_][\w-]*)\s*[=:]\s*"?([A-Za-z_][\w_]*)?$/.exec(linePrefix);
+  if (!m) return null;
+  const keyName = m[1];
+  const partial = m[2] ?? '';
+  const def = findKeyDef(keyName);
+  if (!def || def.valueType !== 'enum' || !def.enumRef) return null;
+  const partialStart = lineStart + linePrefix.length - partial.length;
+  return { enumName: def.enumRef, from: partialStart, to: pos };
+}
+
+function enumCompletionsForCursor(text: string, pos: number): CompletionResult | null {
+  const ctx = findEnumContextAtCursor(text, pos);
+  if (!ctx) return null;
+  const values = getEnumValues(ctx.enumName);
+  return {
+    from: ctx.from,
+    to: ctx.to,
+    options: values.map((v) => ({ label: v, type: 'enum', boost: 1 })),
+    validFor: /^[A-Z_0-9]*$/i,
+  };
+}
diff --git a/src/lib/playground/cm/color-widget.test.ts b/src/lib/playground/cm/color-widget.test.ts
new file mode 100644
index 0000000..ee1cf3c
--- /dev/null
+++ b/src/lib/playground/cm/color-widget.test.ts
@@ -0,0 +1,102 @@
+import { describe, test, expect } from 'vitest';
+import { findColorMatches, parseColorValue, formatColorValue } from './color-widget';
+
+describe('parseColorValue', () => {
+  test('hex string', () => {
+    expect(parseColorValue('"#ff6432"')).toEqual({ hex: '#ff6432', kind: 'hex-quoted' });
+  });
+
+  test('hex uppercase normalises to lower', () => {
+    expect(parseColorValue('"#FF6432"')).toEqual({ hex: '#ff6432', kind: 'hex-quoted' });
+  });
+
+  test('rgb list', () => {
+    expect(parseColorValue('[255, 100, 50]')).toEqual({ hex: '#ff6432', kind: 'rgb-list' });
+  });
+
+  test('rgb list clamps overflow', () => {
+    expect(parseColorValue('[300, 100, 50]')).toEqual({ hex: '#ff6432', kind: 'rgb-list' });
+  });
+
+  test('returns null for unparseable', () => {
+    expect(parseColorValue('RED')).toBeNull();
+  });
+});
+
+describe('formatColorValue', () => {
+  test('hex-quoted round-trip', () => {
+    expect(formatColorValue('#abcdef', 'hex-quoted')).toBe('"#abcdef"');
+  });
+
+  test('rgb-list round-trip', () => {
+    expect(formatColorValue('#ff6432', 'rgb-list')).toBe('[255, 100, 50]');
+  });
+});
+
+describe('findColorMatches', () => {
+  test('quoted hex on item', () => {
+    const matches = findColorMatches('color = "#ff6432"');
+    expect(matches).toHaveLength(1);
+    expect(matches[0].hex).toBe('#ff6432');
+    expect(matches[0].kind).toBe('hex-quoted');
+  });
+
+  test('rgb list', () => {
+    const matches = findColorMatches('color: [10, 20, 30]');
+    expect(matches).toHaveLength(1);
+    expect(matches[0].hex).toBe('#0a141e');
+    expect(matches[0].kind).toBe('rgb-list');
+  });
+
+  test('multiple colors in same buffer', () => {
+    const m = findColorMatches('color = "#ffffff"\ncolor = [0, 0, 0]');
+    expect(m).toHaveLength(2);
+  });
+
+  test('match offsets correspond to value, not key', () => {
+    const text = 'color = "#ff6432"';
+    const m = findColorMatches(text)[0];
+    expect(text.slice(m.from, m.to)).toBe('"#ff6432"');
+  });
+
+  test('shorthand hex still skipped (only 6-char supported)', () => {
+    expect(findColorMatches('color = "#fff"')).toHaveLength(0);
+  });
+
+  test('named color leaves no swatch', () => {
+    expect(findColorMatches('color = RED')).toHaveLength(0);
+  });
+
+  test('empty value emits placeholder swatch with from === to', () => {
+    const text = 'color = ';
+    const m = findColorMatches(text);
+    expect(m).toHaveLength(1);
+    expect(m[0].kind).toBe('empty');
+    expect(m[0].from).toBe(m[0].to);
+    expect(m[0].hex).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  test('value followed by inline comment treated as empty', () => {
+    const m = findColorMatches('color = # not yet');
+    expect(m).toHaveLength(1);
+    expect(m[0].kind).toBe('empty');
+  });
+
+  test('formatColorValue empty kind writes hex (priority)', () => {
+    expect(formatColorValue('#abcdef', 'empty')).toBe('"#abcdef"');
+  });
+
+  test('baseOffset added to from/to', () => {
+    const m = findColorMatches('color = "#ff6432"', 100);
+    expect(m[0].from).toBeGreaterThan(100);
+  });
+
+  test('color = inside a string literal is ignored', () => {
+    const text = 'lore = "click for color = pink"\nmaterial = STONE';
+    expect(findColorMatches(text)).toHaveLength(0);
+  });
+
+  test('color = on a commented-out line is ignored', () => {
+    expect(findColorMatches('# color = "#ff0000"\nname = "x"')).toHaveLength(0);
+  });
+});
diff --git a/src/lib/playground/cm/color-widget.ts b/src/lib/playground/cm/color-widget.ts
new file mode 100644
index 0000000..dff2c2c
--- /dev/null
+++ b/src/lib/playground/cm/color-widget.ts
@@ -0,0 +1,198 @@
+import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate, WidgetType } from '@codemirror/view';
+import { RangeSetBuilder } from '@codemirror/state';
+import { stripStringsAndComments } from './text-utils';
+
+type ColorKind = 'hex-quoted' | 'rgb-list' | 'empty';
+
+interface ColorMatch {
+  /** start of the value (inclusive); equal to `to` when value is empty */
+  from: number;
+  /** end of the value (exclusive) */
+  to: number;
+  hex: string;
+  kind: ColorKind;
+}
+
+const COLOR_PREFIX_RE = /\bcolor\s*[=:]\s*/g;
+const HEX_QUOTED_RE = /^"#([0-9A-Fa-f]{6})"$/;
+const RGB_LIST_RE = /^\[\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\]$/;
+const EMPTY_VALUE_RE = /^[ \t]*(?:#|\/\/|$)/;
+const DEFAULT_HEX = '#ffffff';
+
+export function findColorMatches(text: string, baseOffset = 0): ColorMatch[] {
+  const out: ColorMatch[] = [];
+  // Run the regex on the raw text (we need the actual value characters), but
+  // confirm the `color` keyword wasn't itself inside a string/comment by
+  // checking the stripped copy. stripStringsAndComments preserves positions.
+  const safe = stripStringsAndComments(text);
+  COLOR_PREFIX_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = COLOR_PREFIX_RE.exec(text)) !== null) {
+    if (safe.slice(m.index, m.index + 5) !== 'color') continue;
+    const valueStart = m.index + m[0].length;
+    const lineEnd = nextLineBreak(text, valueStart);
+    const rest = text.slice(valueStart, lineEnd);
+
+    const hexM = /^"#[0-9A-Fa-f]{6}"/.exec(rest);
+    if (hexM) {
+      const parsed = parseColorValue(hexM[0])!;
+      out.push({
+        from: baseOffset + valueStart,
+        to: baseOffset + valueStart + hexM[0].length,
+        hex: parsed.hex,
+        kind: parsed.kind,
+      });
+      continue;
+    }
+
+    const rgbM = /^\[\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\]/.exec(rest);
+    if (rgbM) {
+      const parsed = parseColorValue(rgbM[0])!;
+      out.push({
+        from: baseOffset + valueStart,
+        to: baseOffset + valueStart + rgbM[0].length,
+        hex: parsed.hex,
+        kind: parsed.kind,
+      });
+      continue;
+    }
+
+    if (EMPTY_VALUE_RE.test(rest)) {
+      // No value yet, or only whitespace before a comment / newline.
+      // Show a swatch anyway so the user can pick one and we'll insert a hex.
+      out.push({
+        from: baseOffset + valueStart,
+        to: baseOffset + valueStart,
+        hex: DEFAULT_HEX,
+        kind: 'empty',
+      });
+      continue;
+    }
+
+    // Otherwise the value is something else (named color, substitution, etc.)
+    // - leave it alone, no swatch.
+  }
+  return out;
+}
+
+function nextLineBreak(text: string, from: number): number {
+  const i = text.indexOf('\n', from);
+  return i === -1 ? text.length : i;
+}
+
+export function parseColorValue(value: string): { hex: string; kind: ColorKind } | null {
+  const hexM = HEX_QUOTED_RE.exec(value);
+  if (hexM) return { hex: '#' + hexM[1].toLowerCase(), kind: 'hex-quoted' };
+  const rgbM = RGB_LIST_RE.exec(value);
+  if (rgbM) {
+    const r = clamp(+rgbM[1]);
+    const g = clamp(+rgbM[2]);
+    const b = clamp(+rgbM[3]);
+    return { hex: rgbToHex(r, g, b), kind: 'rgb-list' };
+  }
+  return null;
+}
+
+export function formatColorValue(hex: string, kind: ColorKind): string {
+  if (kind === 'rgb-list') {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return `[${r}, ${g}, ${b}]`;
+  }
+  // 'hex-quoted' and 'empty' both write hex form; hex is the priority/default.
+  return `"${hex}"`;
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  return '#' + [r, g, b].map((n) => n.toString(16).padStart(2, '0')).join('');
+}
+
+function clamp(n: number): number {
+  return Math.max(0, Math.min(255, n));
+}
+
+class ColorSwatchWidget extends WidgetType {
+  constructor(
+    readonly hex: string,
+    readonly from: number,
+    readonly to: number,
+    readonly kind: ColorKind,
+  ) {
+    super();
+  }
+
+  eq(other: ColorSwatchWidget): boolean {
+    return other.hex === this.hex && other.from === this.from && other.to === this.to;
+  }
+
+  toDOM(view: EditorView): HTMLElement {
+    const el = document.createElement('span');
+    el.className = 'pg-color-swatch';
+    if (this.kind === 'empty') el.classList.add('is-empty');
+    el.style.background = this.hex;
+    el.title = this.kind === 'empty' ? 'Click to pick a color' : `${this.hex} - click to change`;
+    el.addEventListener('mousedown', (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      const input = document.createElement('input');
+      input.type = 'color';
+      input.value = this.hex;
+      input.style.position = 'fixed';
+      input.style.left = '-9999px';
+      document.body.appendChild(input);
+      input.addEventListener('change', () => {
+        const newHex = input.value;
+        const replacement = formatColorValue(newHex, this.kind);
+        view.dispatch({
+          changes: { from: this.from, to: this.to, insert: replacement },
+        });
+        document.body.removeChild(input);
+      });
+      input.addEventListener('blur', () => {
+        if (input.parentNode) document.body.removeChild(input);
+      }, { once: true });
+      input.click();
+    });
+    return el;
+  }
+
+  ignoreEvent(): boolean {
+    return false;
+  }
+}
+
+function buildDecorations(view: EditorView): DecorationSet {
+  const builder = new RangeSetBuilder<Decoration>();
+  for (const { from, to } of view.visibleRanges) {
+    const text = view.state.doc.sliceString(from, to);
+    const matches = findColorMatches(text, from);
+    for (const m of matches) {
+      const widget = Decoration.widget({
+        widget: new ColorSwatchWidget(m.hex, m.from, m.to, m.kind),
+        side: 1,
+      });
+      builder.add(m.to, m.to, widget);
+    }
+  }
+  return builder.finish();
+}
+
+export function colorSwatches() {
+  return ViewPlugin.fromClass(
+    class {
+      decorations: DecorationSet;
+      constructor(view: EditorView) {
+        this.decorations = buildDecorations(view);
+      }
+      update(u: ViewUpdate): void {
+        if (u.docChanged || u.viewportChanged) {
+          this.decorations = buildDecorations(u.view);
+        }
+      }
+    },
+    {
+      decorations: (v) => v.decorations,
+    },
+  );
+}
diff --git a/src/lib/playground/cm/format.test.ts b/src/lib/playground/cm/format.test.ts
new file mode 100644
index 0000000..ef7bc12
--- /dev/null
+++ b/src/lib/playground/cm/format.test.ts
@@ -0,0 +1,44 @@
+import { describe, test, expect } from 'vitest';
+import { formatHocon } from './format';
+
+describe('formatHocon', () => {
+  test('top-level keys not indented', () => {
+    expect(formatHocon('a = 1\nb = 2')).toBe('a = 1\nb = 2');
+  });
+
+  test('object body indented two spaces', () => {
+    const input = 'a {\nb = 1\n}';
+    expect(formatHocon(input)).toBe('a {\n  b = 1\n}');
+  });
+
+  test('nested object', () => {
+    const input = 'a {\nb {\nc = 1\n}\n}';
+    expect(formatHocon(input)).toBe('a {\n  b {\n    c = 1\n  }\n}');
+  });
+
+  test('list body indented', () => {
+    const input = 'xs = [\n1\n2\n]';
+    expect(formatHocon(input)).toBe('xs = [\n  1\n  2\n]');
+  });
+
+  test('preserves blank lines', () => {
+    const input = 'a = 1\n\nb = 2';
+    expect(formatHocon(input)).toBe('a = 1\n\nb = 2');
+  });
+
+  test('preserves comments and adjusts their indent', () => {
+    const input = 'a {\n# inner comment\nb = 1\n}';
+    expect(formatHocon(input)).toBe('a {\n  # inner comment\n  b = 1\n}');
+  });
+
+  test('strings with braces are not counted as brackets', () => {
+    const input = 'a = "{nope}"\nb = 1';
+    expect(formatHocon(input)).toBe('a = "{nope}"\nb = 1');
+  });
+
+  test('idempotent (formatting twice = once)', () => {
+    const a = formatHocon('items = [\n  {\n    slot = 0\n  }\n]');
+    const b = formatHocon(a);
+    expect(b).toBe(a);
+  });
+});
diff --git a/src/lib/playground/cm/format.ts b/src/lib/playground/cm/format.ts
new file mode 100644
index 0000000..1be7b41
--- /dev/null
+++ b/src/lib/playground/cm/format.ts
@@ -0,0 +1,49 @@
+import { stripStringsAndComments } from './text-utils';
+
+const INDENT = '  ';
+
+export function formatHocon(input: string): string {
+  const lines = input.split('\n');
+  const out: string[] = [];
+  let depth = 0;
+  let inTriple = false;
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line === '') { out.push(''); continue; }
+
+    if (inTriple) {
+      out.push(raw);
+      if (hasOddTripleQuotes(raw)) inTriple = false;
+      continue;
+    }
+
+    const opensTripleStart = hasOddTripleQuotes(line);
+
+    let lineDepth = depth;
+    if (line.startsWith('}') || line.startsWith(']')) lineDepth = Math.max(0, depth - 1);
+
+    out.push(INDENT.repeat(lineDepth) + line);
+
+    if (opensTripleStart) { inTriple = true; continue; }
+
+    depth += netDepthChange(line);
+    if (depth < 0) depth = 0;
+  }
+
+  return out.join('\n');
+}
+
+function netDepthChange(line: string): number {
+  let n = 0;
+  for (const c of stripStringsAndComments(line)) {
+    if (c === '{' || c === '[') n++;
+    else if (c === '}' || c === ']') n--;
+  }
+  return n;
+}
+
+function hasOddTripleQuotes(line: string): boolean {
+  const opens = (line.match(/"""/g) ?? []).length;
+  return opens % 2 === 1;
+}
diff --git a/src/lib/playground/cm/hocon-language.ts b/src/lib/playground/cm/hocon-language.ts
new file mode 100644
index 0000000..5974dc0
--- /dev/null
+++ b/src/lib/playground/cm/hocon-language.ts
@@ -0,0 +1,81 @@
+import { StreamLanguage, HighlightStyle, syntaxHighlighting, type StreamParser } from '@codemirror/language';
+import { tags, type Tag } from '@lezer/highlight';
+import { tokenizeLine, createState, type TokenType, type TokenState } from './hocon-tokenizer';
+
+const TAG_TABLE: Record<TokenType, Tag> = {
+  comment: tags.lineComment,
+  string: tags.string,
+  substitution: tags.special(tags.string),
+  key: tags.propertyName,
+  operator: tags.operator,
+  bracket: tags.bracket,
+  punctuation: tags.punctuation,
+  bool: tags.bool,
+  null: tags.null,
+  keyword: tags.keyword,
+  includeFn: tags.function(tags.keyword),
+  number: tags.number,
+  duration: tags.unit,
+  value: tags.atom,
+};
+
+const hoconParser: StreamParser<TokenState> = {
+  name: 'hocon',
+
+  startState(): TokenState {
+    return createState();
+  },
+
+  token(stream, state) {
+    if (stream.eatSpace()) return null;
+    const rest = stream.string.slice(stream.pos);
+    if (rest.length === 0) return null;
+
+    const tokens = tokenizeLine(rest, state);
+    if (tokens.length === 0) {
+      stream.next();
+      return null;
+    }
+
+    const first = tokens[0];
+    stream.pos += first.text.length;
+    if (first.token === null) return null;
+    return first.token;
+  },
+
+  tokenTable: TAG_TABLE,
+
+  // Enter behavior is fully owned by smartEnter in Editor.ts; we don't
+  // implement an indent callback here since IndentContext.pos was inconsistent
+  // and the custom handler gives more predictable results anyway.
+
+  languageData: {
+    commentTokens: { line: '#' },
+    closeBrackets: { brackets: ['(', '[', '{', '"'] },
+    indentOnInput: /^\s*[}\]]$/,
+  },
+};
+
+const highlightStyle = HighlightStyle.define([
+  { tag: tags.lineComment, class: 'cm-tk-comment' },
+  { tag: tags.string, class: 'cm-tk-string' },
+  { tag: tags.special(tags.string), class: 'cm-tk-substitution' },
+  { tag: tags.propertyName, class: 'cm-tk-key' },
+  { tag: tags.operator, class: 'cm-tk-operator' },
+  { tag: tags.bracket, class: 'cm-tk-bracket' },
+  { tag: tags.punctuation, class: 'cm-tk-punctuation' },
+  { tag: tags.bool, class: 'cm-tk-bool' },
+  { tag: tags.null, class: 'cm-tk-null' },
+  { tag: tags.keyword, class: 'cm-tk-keyword' },
+  { tag: tags.function(tags.keyword), class: 'cm-tk-include-fn' },
+  { tag: tags.number, class: 'cm-tk-number' },
+  { tag: tags.unit, class: 'cm-tk-duration' },
+  { tag: tags.atom, class: 'cm-tk-value' },
+]);
+
+export function hoconLanguage() {
+  return [
+    StreamLanguage.define(hoconParser),
+    syntaxHighlighting(highlightStyle),
+  ];
+}
diff --git a/src/lib/playground/cm/hocon-lint.ts b/src/lib/playground/cm/hocon-lint.ts
new file mode 100644
index 0000000..80f8222
--- /dev/null
+++ b/src/lib/playground/cm/hocon-lint.ts
@@ -0,0 +1,85 @@
+import type { EditorView } from '@codemirror/view';
+import { Facet, type EditorState, StateEffect, StateField } from '@codemirror/state';
+import { linter, forceLinting, type Diagnostic as CMDiagnostic } from '@codemirror/lint';
+import { tokenizeText } from '../hocon/tokenize';
+import { parse } from '../hocon/parser';
+import { resolve } from '../hocon/resolve';
+import { validateUnknownKeys } from '../hocon/unknown-keys';
+import type { Diagnostic } from '../hocon/types';
+
+/**
+ * Per-editor toggle for the warning subset of diagnostics. Stored as a
+ * StateField so a transaction can flip it; a Facet then exposes the current
+ * value to the linter callback. Result: toggling re-runs the linter
+ * reactively, no manual setDiagnostics dispatch from the toolbar code.
+ */
+export const setWarningSquigglesEffect = StateEffect.define<boolean>();
+
+// Declared before the StateField that references it - StateField.provide is
+// evaluated at module-init, which means the Facet must already exist or we
+// hit a `Cannot access ... before initialization` TDZ error.
+const warningSquigglesFacet = Facet.define<boolean, boolean>({
+  // Only the StateField below feeds this facet today. If a future extension
+  // also writes the facet, treat any opt-out as authoritative (any `false`
+  // wins) so explicit "hide" preferences aren't silently overridden by
+  // late-loaded extensions defaulting to `true`.
+  combine: (values) => values.every((v) => v),
+});
+
+const warningSquigglesField = StateField.define<boolean>({
+  create: () => true,
+  update(value, tr) {
+    for (const e of tr.effects) {
+      if (e.is(setWarningSquigglesEffect)) return e.value;
+    }
+    return value;
+  },
+  provide: (f) => warningSquigglesFacet.from(f),
+});
+
+export function isWarningSquigglesEnabled(state: EditorState): boolean {
+  return state.facet(warningSquigglesFacet);
+}
+
+export function setWarningSquigglesEnabled(view: EditorView, enabled: boolean): void {
+  // Order matters: dispatch must commit the new facet value before
+  // forceLinting reads it, otherwise the linter callback sees the old value.
+  view.dispatch({ effects: setWarningSquigglesEffect.of(enabled) });
+  forceLinting(view);
+}
+
+export function hoconLinter() {
+  return [
+    warningSquigglesField,
+    linter(
+      (view) => {
+        const text = view.state.doc.toString();
+        const r = parse(tokenizeText(text));
+        const res = resolve(r.ast);
+        const unknown = validateUnknownKeys(r.ast);
+        const all = [...r.diagnostics, ...res.warnings, ...unknown];
+        const showWarnings = view.state.facet(warningSquigglesFacet);
+        const filtered = showWarnings ? all : all.filter((d) => d.severity !== 'warning');
+        return filtered.map((d) => toCm(view, d, text.length));
+      },
+      { delay: 300 },
+    ),
+  ];
+}
+
+function toCm(view: EditorView, d: Diagnostic, docLen: number): CMDiagnostic {
+  const doc = view.state.doc;
+  const lineNo = Math.max(1, Math.min(doc.lines, d.line));
+  const docLine = doc.line(lineNo);
+  const baseFrom = (d.offset !== undefined && d.offset >= 0)
+    ? Math.min(d.offset, docLen)
+    : docLine.from + Math.max(0, d.column - 1);
+  const length = d.length ?? 1;
+  const to = Math.min(docLen, baseFrom + length);
+  return {
+    from: Math.min(baseFrom, to),
+    to,
+    severity: d.severity,
+    message: d.message,
+  };
+}
diff --git a/src/lib/playground/cm/hocon-tokenizer.test.ts b/src/lib/playground/cm/hocon-tokenizer.test.ts
new file mode 100644
index 0000000..d6bcfb8
--- /dev/null
+++ b/src/lib/playground/cm/hocon-tokenizer.test.ts
@@ -0,0 +1,177 @@
+import { describe, test, expect } from 'vitest';
+import { tokenizeLine } from './hocon-tokenizer';
+
+describe('HOCON tokenizer', () => {
+  describe('comments', () => {
+    test('hash comment to end of line', () => {
+      expect(tokenizeLine('# this is a comment')).toEqual([
+        { token: 'comment', text: '# this is a comment' },
+      ]);
+    });
+
+    test('double-slash comment', () => {
+      expect(tokenizeLine('// comment')).toEqual([
+        { token: 'comment', text: '// comment' },
+      ]);
+    });
+
+    test('comment after value', () => {
+      expect(tokenizeLine('size = 3 # rows')).toEqual([
+        { token: 'key', text: 'size' },
+        { token: null, text: ' ' },
+        { token: 'operator', text: '=' },
+        { token: null, text: ' ' },
+        { token: 'number', text: '3' },
+        { token: null, text: ' ' },
+        { token: 'comment', text: '# rows' },
+      ]);
+    });
+  });
+
+  describe('strings', () => {
+    test('basic double-quoted string', () => {
+      expect(tokenizeLine('title = "Hello"')).toEqual([
+        { token: 'key', text: 'title' },
+        { token: null, text: ' ' },
+        { token: 'operator', text: '=' },
+        { token: null, text: ' ' },
+        { token: 'string', text: '"Hello"' },
+      ]);
+    });
+
+    test('string with escape', () => {
+      expect(tokenizeLine('x = "a\\nb"')).toEqual([
+        { token: 'key', text: 'x' },
+        { token: null, text: ' ' },
+        { token: 'operator', text: '=' },
+        { token: null, text: ' ' },
+        { token: 'string', text: '"a\\nb"' },
+      ]);
+    });
+
+    test('triple-quoted string', () => {
+      const tokens = tokenizeLine('s = """multi"""');
+      expect(tokens.find((t) => t.token === 'string')).toEqual({
+        token: 'string',
+        text: '"""multi"""',
+      });
+    });
+  });
+
+  describe('substitutions', () => {
+    test('plain substitution', () => {
+      expect(tokenizeLine('x = ${a.b}')).toEqual([
+        { token: 'key', text: 'x' },
+        { token: null, text: ' ' },
+        { token: 'operator', text: '=' },
+        { token: null, text: ' ' },
+        { token: 'substitution', text: '${a.b}' },
+      ]);
+    });
+
+    test('optional substitution', () => {
+      expect(tokenizeLine('x = ${?a.b}')).toEqual([
+        { token: 'key', text: 'x' },
+        { token: null, text: ' ' },
+        { token: 'operator', text: '=' },
+        { token: null, text: ' ' },
+        { token: 'substitution', text: '${?a.b}' },
+      ]);
+    });
+  });
+
+  describe('numbers and constants', () => {
+    test('integer', () => {
+      expect(tokenizeLine('size = 3')[4]).toEqual({ token: 'number', text: '3' });
+    });
+    test('negative float', () => {
+      expect(tokenizeLine('x = -1.5')[4]).toEqual({ token: 'number', text: '-1.5' });
+    });
+    test('boolean true', () => {
+      expect(tokenizeLine('enabled = true')[4]).toEqual({ token: 'bool', text: 'true' });
+    });
+    test('boolean yes', () => {
+      expect(tokenizeLine('flag = yes')[4]).toEqual({ token: 'bool', text: 'yes' });
+    });
+    test('null', () => {
+      expect(tokenizeLine('x = null')[4]).toEqual({ token: 'null', text: 'null' });
+    });
+  });
+
+  describe('brackets and lists', () => {
+    test('object literal', () => {
+      const tokens = tokenizeLine('items = [{ id = 1 }]');
+      const types = tokens.map((t) => t.token).filter((t) => t !== null);
+      expect(types).toEqual([
+        'key', 'operator', 'bracket', 'bracket', 'key', 'operator', 'number', 'bracket', 'bracket',
+      ]);
+    });
+  });
+
+  describe('operators', () => {
+    test('plus-equals', () => {
+      const tokens = tokenizeLine('list += "a"');
+      expect(tokens[2]).toEqual({ token: 'operator', text: '+=' });
+    });
+    test('colon', () => {
+      const tokens = tokenizeLine('a: 1');
+      expect(tokens[1]).toEqual({ token: 'operator', text: ':' });
+    });
+  });
+
+  describe('includes', () => {
+    test('include with file()', () => {
+      const tokens = tokenizeLine('include file("a.conf")');
+      const types = tokens.map((t) => t.token).filter((t) => t !== null);
+      expect(types[0]).toBe('keyword');
+      expect(types[1]).toBe('includeFn');
+      expect(types).toContain('string');
+    });
+    test('include with classpath', () => {
+      const tokens = tokenizeLine('include classpath("base.conf")');
+      const types = tokens.map((t) => t.token).filter((t) => t !== null);
+      expect(types[0]).toBe('keyword');
+      expect(types[1]).toBe('includeFn');
+    });
+  });
+
+  describe('durations', () => {
+    test('seconds shorthand', () => {
+      const tokens = tokenizeLine('cooldown = 5s');
+      expect(tokens.find((t) => t.token === 'duration')).toEqual({
+        token: 'duration',
+        text: '5s',
+      });
+    });
+    test('megabytes', () => {
+      const tokens = tokenizeLine('size = 10MB');
+      expect(tokens.find((t) => t.token === 'duration')).toEqual({
+        token: 'duration',
+        text: '10MB',
+      });
+    });
+    test('seconds with space', () => {
+      const tokens = tokenizeLine('t = 5 seconds');
+      expect(tokens.find((t) => t.token === 'duration')).toEqual({
+        token: 'duration',
+        text: '5 seconds',
+      });
+    });
+  });
+
+  describe('keys vs values', () => {
+    test('unquoted value after =', () => {
+      const tokens = tokenizeLine('material = STONE');
+      expect(tokens[0]).toEqual({ token: 'key', text: 'material' });
+      expect(tokens[4]).toEqual({ token: 'value', text: 'STONE' });
+    });
+    test('key followed by `{` is still a key', () => {
+      const tokens = tokenizeLine('items {');
+      expect(tokens[0]).toEqual({ token: 'key', text: 'items' });
+    });
+    test('dotted key', () => {
+      const tokens = tokenizeLine('a.b.c = 1');
+      expect(tokens[0]).toEqual({ token: 'key', text: 'a.b.c' });
+    });
+  });
+});
diff --git a/src/lib/playground/cm/hocon-tokenizer.ts b/src/lib/playground/cm/hocon-tokenizer.ts
new file mode 100644
index 0000000..e5d1462
--- /dev/null
+++ b/src/lib/playground/cm/hocon-tokenizer.ts
@@ -0,0 +1,171 @@
+export type TokenType =
+  | 'comment'
+  | 'string'
+  | 'substitution'
+  | 'key'
+  | 'operator'
+  | 'bracket'
+  | 'punctuation'
+  | 'bool'
+  | 'null'
+  | 'keyword'
+  | 'includeFn'
+  | 'number'
+  | 'duration'
+  | 'value';
+
+export interface Token {
+  token: TokenType | null;
+  text: string;
+}
+
+export interface TokenState {
+  inMultilineString: boolean;
+  expectKey: boolean;
+}
+
+const BOOLS = new Set(['true', 'false', 'yes', 'no', 'on', 'off']);
+const INCLUDE_FNS = new Set(['url', 'file', 'classpath', 'required']);
+const DURATION_UNITS = /^(?:nanoseconds?|microseconds?|milliseconds?|seconds?|minutes?|hours?|days?|kilobytes?|megabytes?|gigabytes?|terabytes?|bytes?|ns|us|ms|kB|MB|GB|TB|KiB|MiB|GiB|TiB|s|m|h|d)\b/;
+
+export function createState(): TokenState {
+  return { inMultilineString: false, expectKey: true };
+}
+
+export function tokenizeLine(line: string, initialState?: TokenState): Token[] {
+  const tokens: Token[] = [];
+  const state = initialState ?? createState();
+  let i = 0;
+  state.expectKey = true;
+
+  while (i < line.length) {
+    const ch = line[i];
+
+    if (ch === ' ' || ch === '\t') {
+      const start = i;
+      while (i < line.length && (line[i] === ' ' || line[i] === '\t')) i++;
+      tokens.push({ token: null, text: line.slice(start, i) });
+      continue;
+    }
+
+    if (ch === '#' || (ch === '/' && line[i + 1] === '/')) {
+      tokens.push({ token: 'comment', text: line.slice(i) });
+      i = line.length;
+      continue;
+    }
+
+    if (ch === '$' && line[i + 1] === '{') {
+      const start = i;
+      i += 2;
+      while (i < line.length && line[i] !== '}') i++;
+      if (i < line.length) i++;
+      tokens.push({ token: 'substitution', text: line.slice(start, i) });
+      state.expectKey = false;
+      continue;
+    }
+
+    if (ch === '"' && line[i + 1] === '"' && line[i + 2] === '"') {
+      const start = i;
+      i += 3;
+      while (i < line.length && !(line[i] === '"' && line[i + 1] === '"' && line[i + 2] === '"')) i++;
+      if (i < line.length) i += 3;
+      tokens.push({ token: 'string', text: line.slice(start, i) });
+      state.expectKey = false;
+      continue;
+    }
+    if (ch === '"') {
+      const start = i;
+      i++;
+      while (i < line.length && line[i] !== '"') {
+        if (line[i] === '\\' && i + 1 < line.length) i++;
+        i++;
+      }
+      if (i < line.length) i++;
+      tokens.push({ token: 'string', text: line.slice(start, i) });
+      state.expectKey = false;
+      continue;
+    }
+
+    if (ch === '+' && line[i + 1] === '=') {
+      tokens.push({ token: 'operator', text: '+=' });
+      i += 2;
+      state.expectKey = false;
+      continue;
+    }
+    if (ch === '=' || ch === ':') {
+      tokens.push({ token: 'operator', text: ch });
+      i++;
+      state.expectKey = false;
+      continue;
+    }
+
+    if (ch === '{' || ch === '}' || ch === '[' || ch === ']') {
+      tokens.push({ token: 'bracket', text: ch });
+      i++;
+      state.expectKey = ch === '{' || ch === '}';
+      continue;
+    }
+    if (ch === ',') {
+      tokens.push({ token: 'punctuation', text: ',' });
+      i++;
+      state.expectKey = true;
+      continue;
+    }
+
+    const numMatch = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(line.slice(i));
+    if (numMatch) {
+      const numText = numMatch[0];
+      const after = line.slice(i + numText.length);
+      const wsMatch = /^[ \t]*/.exec(after)!;
+      const wsLen = wsMatch[0].length;
+      const unitMatch = DURATION_UNITS.exec(after.slice(wsLen));
+      if (unitMatch) {
+        const totalLen = numText.length + wsLen + unitMatch[0].length;
+        tokens.push({ token: 'duration', text: line.slice(i, i + totalLen) });
+        i += totalLen;
+        state.expectKey = false;
+        continue;
+      }
+      tokens.push({ token: 'number', text: numText });
+      i += numText.length;
+      state.expectKey = false;
+      continue;
+    }
+
+    const idMatch = /^[A-Za-z_][\w\-.]*/.exec(line.slice(i));
+    if (idMatch) {
+      const id = idMatch[0];
+      let token: TokenType;
+
+      if (id === 'include') {
+        token = 'keyword';
+      } else if (INCLUDE_FNS.has(id)) {
+        token = 'includeFn';
+      } else if (BOOLS.has(id)) {
+        token = 'bool';
+        state.expectKey = false;
+      } else if (id === 'null') {
+        token = 'null';
+        state.expectKey = false;
+      } else {
+        const tail = line.slice(i + id.length).replace(/^[ \t]+/, '');
+        const isKey = state.expectKey && (
+          tail.startsWith(':') ||
+          tail.startsWith('=') ||
+          tail.startsWith('+=') ||
+          tail.startsWith('{')
+        );
+        token = isKey ? 'key' : 'value';
+        if (!isKey) state.expectKey = false;
+      }
+      tokens.push({ token, text: id });
+      i += id.length;
+      continue;
+    }
+
+    tokens.push({ token: null, text: ch });
+    i++;
+  }
+
+  return tokens;
+}
diff --git a/src/lib/playground/cm/hover-docs.ts b/src/lib/playground/cm/hover-docs.ts
new file mode 100644
index 0000000..277e426
--- /dev/null
+++ b/src/lib/playground/cm/hover-docs.ts
@@ -0,0 +1,36 @@
+import { hoverTooltip } from '@codemirror/view';
+import { findKeyDef } from '../catalog';
+import { describeKeyDef } from '../catalog/i18n';
+
+export function hoverDocs() {
+  return hoverTooltip((view, pos) => {
+    const text = view.state.doc.toString();
+    const wordRe = /[A-Za-z_][\w-]*/;
+    let start = pos;
+    while (start > 0 && wordRe.test(text[start - 1] ?? '')) start--;
+    let end = pos;
+    while (end < text.length && wordRe.test(text[end] ?? '')) end++;
+    if (start === end) return null;
+    const word = text.slice(start, end);
+    const def = findKeyDef(word);
+    if (!def) return null;
+    return {
+      pos: start,
+      end,
+      above: true,
+      create() {
+        const dom = document.createElement('div');
+        dom.className = 'pg-hover';
+        const head = document.createElement('div');
+        head.className = 'pg-hover-head';
+        head.textContent = `${def.name} : ${def.valueType === 'enum' ? `enum<${def.enumRef}>` : def.valueType}`;
+        const body = document.createElement('div');
+        body.className = 'pg-hover-body';
+        body.textContent = describeKeyDef(def);
+        dom.appendChild(head);
+        dom.appendChild(body);
+        return { dom };
+      },
+    };
+  });
+}
diff --git a/src/lib/playground/cm/scope.test.ts b/src/lib/playground/cm/scope.test.ts
new file mode 100644
index 0000000..6d993f2
--- /dev/null
+++ b/src/lib/playground/cm/scope.test.ts
@@ -0,0 +1,119 @@
+import { describe, test, expect } from 'vitest';
+import { detectScope } from './scope';
+
+describe('detectScope', () => {
+  test('empty input → menu-root', () => {
+    expect(detectScope('', 0)).toBe('menu-root');
+  });
+
+  test('top level → menu-root', () => {
+    expect(detectScope('title = "x"\n', 12)).toBe('menu-root');
+  });
+
+  test('inside items[]/{} → item', () => {
+    const text = 'items = [\n  {\n    ';
+    expect(detectScope(text, text.length)).toBe('item');
+  });
+
+  test('inside click {} → click', () => {
+    const text = 'items = [\n  {\n    click {\n      ';
+    expect(detectScope(text, text.length)).toBe('click');
+  });
+
+  test('inside actions {} → actions', () => {
+    const text = 'click {\n  actions {\n    ';
+    expect(detectScope(text, text.length)).toBe('actions');
+  });
+
+  test('inside rules {} → rules', () => {
+    const text = 'click {\n  rules {\n    ';
+    expect(detectScope(text, text.length)).toBe('rules');
+  });
+
+  test('inside activators {} → activators', () => {
+    const text = 'activators {\n  ';
+    expect(detectScope(text, text.length)).toBe('activators');
+  });
+
+  test('left {} inside click is click-like (children are actions/rules)', () => {
+    const text = 'click {\n  left {\n    ';
+    expect(detectScope(text, text.length)).toBe('click');
+  });
+
+  test('after closing inner block, scope returns to outer', () => {
+    const text = 'items = [\n  { click { actions { message = "x" } } }\n]\n';
+    expect(detectScope(text, text.length)).toBe('menu-root');
+  });
+
+  test('strings with braces are ignored', () => {
+    const text = 'a = "{ not a block }"\n';
+    expect(detectScope(text, text.length)).toBe('menu-root');
+  });
+
+  test('comments with braces are ignored', () => {
+    const text = '# {{{ comment\nactivators {\n  ';
+    expect(detectScope(text, text.length)).toBe('activators');
+  });
+
+  test('inside enchantments {} → enchantments', () => {
+    const text = 'enchantments {\n  ';
+    expect(detectScope(text, text.length)).toBe('enchantments');
+  });
+
+  test('inside slot {} → slot', () => {
+    const text = 'slot {\n  ';
+    expect(detectScope(text, text.length)).toBe('slot');
+  });
+
+  test('inside firework {} → firework', () => {
+    const text = 'firework {\n  ';
+    expect(detectScope(text, text.length)).toBe('firework');
+  });
+
+  test('inside firework.effects [{}] → firework-effect', () => {
+    const text = 'firework {\n  effects = [\n    {\n      ';
+    expect(detectScope(text, text.length)).toBe('firework-effect');
+  });
+
+  test('inside bindings [{}] → binding', () => {
+    const text = 'bindings = [\n  {\n    ';
+    expect(detectScope(text, text.length)).toBe('binding');
+  });
+
+  test('inside items array but outside any object → item-list', () => {
+    const text = 'items = [\n  ';
+    expect(detectScope(text, text.length)).toBe('item-list');
+  });
+
+  test('inside bindings array but outside any object → binding-list', () => {
+    const text = 'bindings = [\n  ';
+    expect(detectScope(text, text.length)).toBe('binding-list');
+  });
+
+  test('inside binding.props {} → item', () => {
+    const text = 'bindings = [\n  {\n    props {\n      ';
+    expect(detectScope(text, text.length)).toBe('item');
+  });
+
+  test('unknown parent key → unknown (fallback to all keys)', () => {
+    const text = 'myCustomBlock {\n  ';
+    expect(detectScope(text, text.length)).toBe('unknown');
+  });
+
+  test('cursor inside triple-quoted string returns outer scope', () => {
+    // The string body, including the `{` inside, should not open a frame.
+    const text = 'items = [{ name = """has { brace""" }]';
+    const cursorInString = text.indexOf('has') + 1;
+    expect(detectScope(text, cursorInString)).toBe('item');
+  });
+
+  test('cursor inside line comment ignores comment text', () => {
+    const text = 'activators {\n  # inside { brace and = colon\n  ';
+    expect(detectScope(text, text.length)).toBe('activators');
+  });
+
+  test('escaped quote inside string does not break tracking', () => {
+    const text = 'name = "she said \\"go\\"" \nactivators {\n  ';
+    expect(detectScope(text, text.length)).toBe('activators');
+  });
+});
diff --git a/src/lib/playground/cm/scope.ts b/src/lib/playground/cm/scope.ts
new file mode 100644
index 0000000..d122e50
--- /dev/null
+++ b/src/lib/playground/cm/scope.ts
@@ -0,0 +1,81 @@
+import { childScopeOf, arrayPositionScope } from '../catalog';
+import type { Scope } from '../catalog/types';
+import { stripStringsAndComments } from './text-utils';
+
+interface Frame {
+  bracket: '{' | '[';
+  key?: string;
+}
+
+/**
+ * Determine which set of keys is meaningful at the given cursor position.
+ *
+ * Strip strings/comments first (so brackets nested in `"..."` or after `#`
+ * don't open frames), then walk the safe copy: push a stack frame on every
+ * `{`/`[`, remembering the last seen identifier-followed-by-separator (the
+ * key that opened this block). On `}`/`]` pop.
+ *
+ * Resolution rules:
+ *  - The innermost open `{` whose key has a `childrenScope` defined wins.
+ *  - For `[` (arrays of objects, e.g. `items = [{...}]`), an inner `{`
+ *    inherits the parent array's `childrenScope`.
+ *  - A frame whose key is unknown (or known but without `childrenScope`)
+ *    yields `unknown` - the autocomplete falls back to all keys.
+ *  - Empty stack means top-level: `menu-root`.
+ */
+export function detectScope(text: string, pos: number): Scope {
+  const safe = stripStringsAndComments(text);
+  const end = Math.min(pos, safe.length);
+  const stack: Frame[] = [];
+  let lastKey: string | undefined;
+  let i = 0;
+
+  while (i < end) {
+    const ch = safe[i];
+
+    if (ch === '{' || ch === '[') {
+      stack.push({ bracket: ch as '{' | '[', key: lastKey });
+      lastKey = undefined;
+      i++; continue;
+    }
+    if (ch === '}' || ch === ']') {
+      stack.pop();
+      lastKey = undefined;
+      i++; continue;
+    }
+
+    const idMatch = /^[A-Za-z_][\w-]*/.exec(safe.slice(i));
+    if (idMatch) {
+      const id = idMatch[0];
+      const after = safe.slice(i + id.length).replace(/^[ \t]+/, '');
+      if (after.startsWith('=') || after.startsWith(':') || after.startsWith('+=') || after.startsWith('{') || after.startsWith('[')) {
+        lastKey = id;
+      }
+      i += id.length;
+      continue;
+    }
+
+    i++;
+  }
+
+  for (let j = stack.length - 1; j >= 0; j--) {
+    const frame = stack[j];
+
+    if (frame.bracket === '[' && frame.key) {
+      return arrayPositionScope(childScopeOf(frame.key));
+    }
+
+    if (frame.bracket === '{') {
+      // If parent is an array of objects, e.g. items = [{...}], inherit
+      // the array key's childrenScope.
+      const parent = stack[j - 1];
+      if (parent && parent.bracket === '[' && parent.key) {
+        return childScopeOf(parent.key);
+      }
+      if (frame.key) return childScopeOf(frame.key);
+      return 'unknown';
+    }
+  }
+
+  return 'menu-root';
+}
diff --git a/src/lib/playground/cm/snippets.test.ts b/src/lib/playground/cm/snippets.test.ts
new file mode 100644
index 0000000..634c385
--- /dev/null
+++ b/src/lib/playground/cm/snippets.test.ts
@@ -0,0 +1,38 @@
+import { describe, test, expect } from 'vitest';
+import { hoconSnippets } from './snippets';
+
+describe('HOCON snippets', () => {
+  test('exposes the snippet set', () => {
+    expect(hoconSnippets.length).toBeGreaterThanOrEqual(10);
+  });
+
+  test('includes list-skeleton snippets used by catalog-source', () => {
+    const labels = hoconSnippets.map((s) => s.label);
+    expect(labels).toContain('item');
+    expect(labels).toContain('binding');
+    expect(labels).toContain('fireworkEffect');
+  });
+
+  test('each snippet has label, info, and template', () => {
+    for (const s of hoconSnippets) {
+      expect(typeof s.label).toBe('string');
+      expect(s.label.length).toBeGreaterThan(0);
+      expect(typeof s.template).toBe('string');
+      expect(s.template.length).toBeGreaterThan(0);
+    }
+  });
+
+  test('includes core menu skeletons', () => {
+    const labels = hoconSnippets.map((s) => s.label);
+    expect(labels).toContain('menu');
+    expect(labels).toContain('item');
+    expect(labels).toContain('clickaction');
+    expect(labels).toContain('commandact');
+  });
+
+  test('labels are unique', () => {
+    const labels = hoconSnippets.map((s) => s.label);
+    const set = new Set(labels);
+    expect(set.size).toBe(labels.length);
+  });
+});
diff --git a/src/lib/playground/cm/snippets.ts b/src/lib/playground/cm/snippets.ts
new file mode 100644
index 0000000..5143e57
--- /dev/null
+++ b/src/lib/playground/cm/snippets.ts
@@ -0,0 +1,80 @@
+import { snippetCompletion, type Completion } from '@codemirror/autocomplete';
+
+export interface SnippetDef {
+  label: string;
+  info: string;
+  template: string;
+}
+
+export const hoconSnippets: SnippetDef[] = [
+  {
+    label: 'menu',
+    info: 'Menu skeleton',
+    template: 'title = "${1:My Menu}"\nsize = ${2:3}\n\nactivators {\n  command ${3:open} {\n    command = "${3:open}"\n  }\n}\n\nitems = [\n  ${0}\n]\n',
+  },
+  {
+    label: 'item',
+    info: 'Item entry',
+    template: '{\n  slot = ${1:0}\n  material = ${2:STONE}\n  name = "${3:Item Name}"\n  lore = [\n    "${4:Description}"\n  ]\n  ${0}\n}',
+  },
+  {
+    label: 'clickaction',
+    info: 'Click action block on an item',
+    template: 'click {\n  left = [\n    { type = sound, sound = "ENTITY_EXPERIENCE_ORB_PICKUP" }\n  ]\n  ${0}\n}',
+  },
+  {
+    label: 'commandact',
+    info: 'Run a command as an action',
+    template: '{\n  type = command\n  command = "${1:say hi}"\n  as = ${2:player}\n}',
+  },
+  {
+    label: 'opensub',
+    info: 'Open another menu',
+    template: '{\n  type = openMenu\n  menu = "${1:other-menu}"\n}',
+  },
+  {
+    label: 'permrule',
+    info: 'Permission rule',
+    template: '{\n  type = permission\n  permission = "${1:my.perm}"\n}',
+  },
+  {
+    label: 'moneyrule',
+    info: 'Money rule (Vault)',
+    template: '{\n  type = money\n  amount = ${1:100}\n}',
+  },
+  {
+    label: 'texturehead',
+    info: 'Custom textured player head',
+    template: '{\n  material = PLAYER_HEAD\n  texture = "${1:base64-texture-hash}"\n}',
+  },
+  {
+    label: 'cmdactivator',
+    info: 'Command activator block',
+    template: 'activators {\n  command ${1:open} {\n    command = "${1:open}"\n    aliases = [${2}]\n  }\n}',
+  },
+  {
+    label: 'closeact',
+    info: 'Close-menu action',
+    template: '{ type = closeMenu }',
+  },
+  {
+    label: 'binding',
+    info: 'Rules-gated property override (binding entry)',
+    template: '{\n  rules {\n    ${1:permission} = "${2:my.perm}"\n  }\n  props {\n    ${3:material} = ${4:DIAMOND}\n  }\n}',
+  },
+  {
+    label: 'fireworkEffect',
+    info: 'Firework effect descriptor',
+    template: '{\n  type = ${1:BALL}\n  colors = [${2:[255, 0, 0]}]\n  flicker = ${3:false}\n  trail = ${4:false}\n}',
+  },
+];
+
+export function snippetCompletions(): Completion[] {
+  return hoconSnippets.map((s) =>
+    snippetCompletion(s.template, {
+      label: s.label,
+      info: s.info,
+      type: 'snippet',
+    }),
+  );
+}
diff --git a/src/lib/playground/cm/text-utils.test.ts b/src/lib/playground/cm/text-utils.test.ts
new file mode 100644
index 0000000..6de832e
--- /dev/null
+++ b/src/lib/playground/cm/text-utils.test.ts
@@ -0,0 +1,46 @@
+import { describe, test, expect } from 'vitest';
+import { stripStringsAndComments } from './text-utils';
+
+describe('stripStringsAndComments', () => {
+  test('preserves length', () => {
+    const input = 'a = "hello" # tail';
+    expect(stripStringsAndComments(input).length).toBe(input.length);
+  });
+
+  test('strips string contents', () => {
+    expect(stripStringsAndComments('a = "{x}" b')).toBe('a =       b');
+  });
+
+  test('strips line comment with #', () => {
+    expect(stripStringsAndComments('a = 1 # nope')).toBe('a = 1       ');
+  });
+
+  test('strips line comment with //', () => {
+    expect(stripStringsAndComments('a = 1 // nope')).toBe('a = 1        ');
+  });
+
+  test('preserves newlines', () => {
+    expect(stripStringsAndComments('a\n"x"\nb')).toBe('a\n   \nb');
+  });
+
+  test('triple-quoted spans multiple lines', () => {
+    const input = '"""multi\nline"""x';
+    expect(stripStringsAndComments(input)).toBe('        \n       x');
+  });
+
+  test('escaped quote inside string is also stripped', () => {
+    expect(stripStringsAndComments('"a\\"b"')).toBe('      ');
+  });
+
+  test('hash inside string is preserved as part of the strip, not a comment', () => {
+    expect(stripStringsAndComments('"# not a comment"')).toBe('                 ');
+  });
+
+  test('brackets inside string vanish', () => {
+    expect(stripStringsAndComments('a = "{ }" b')).toBe('a =       b');
+  });
+
+  test('non-string non-comment passes through unchanged', () => {
+    expect(stripStringsAndComments('items = [{ slot = 0 }]')).toBe('items = [{ slot = 0 }]');
+  });
+});
diff --git a/src/lib/playground/cm/text-utils.ts b/src/lib/playground/cm/text-utils.ts
new file mode 100644
index 0000000..f2a5877
--- /dev/null
+++ b/src/lib/playground/cm/text-utils.ts
@@ -0,0 +1,71 @@
+/**
+ * Replace every character that sits inside a string literal (single or
+ * triple-quoted) or a comment (`#` / `//`) with a space, preserving overall
+ * length and newline positions. Lets naive regex / bracket-balance scans
+ * ignore HOCON syntax that is nested in strings or commented out, without
+ * each consumer reimplementing its own state machine.
+ *
+ * Newlines are kept verbatim so per-line offsets stay valid.
+ */
+export function stripStringsAndComments(text: string): string {
+  const out: string[] = [];
+  let inString = false;
+  let inTriple = false;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+
+    if (inTriple) {
+      if (ch === '"' && text[i + 1] === '"' && text[i + 2] === '"') {
+        out.push(' ', ' ', ' ');
+        inTriple = false;
+        i += 3;
+        continue;
+      }
+      out.push(ch === '\n' ? '\n' : ' ');
+      i++;
+      continue;
+    }
+
+    if (inString) {
+      if (ch === '\\' && i + 1 < text.length) {
+        out.push(' ', ' ');
+        i += 2;
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+        out.push(' ');
+        i++;
+        continue;
+      }
+      out.push(ch === '\n' ? '\n' : ' ');
+      i++;
+      continue;
+    }
+
+    if (ch === '"' && text[i + 1] === '"' && text[i + 2] === '"') {
+      out.push(' ', ' ', ' ');
+      inTriple = true;
+      i += 3;
+      continue;
+    }
+    if (ch === '"') {
+      out.push(' ');
+      inString = true;
+      i++;
+      continue;
+    }
+    if (ch === '#' || (ch === '/' && text[i + 1] === '/')) {
+      while (i < text.length && text[i] !== '\n') {
+        out.push(' ');
+        i++;
+      }
+      continue;
+    }
+
+    out.push(ch);
+    i++;
+  }
+  return out.join('');
+}
diff --git a/src/lib/playground/controllers/HistoryController.ts b/src/lib/playground/controllers/HistoryController.ts
new file mode 100644
index 0000000..8570129
--- /dev/null
+++ b/src/lib/playground/controllers/HistoryController.ts
@@ -0,0 +1,77 @@
+import type { EditorApi } from '../Editor';
+import type { HistoryDropdownApi } from '../HistoryDropdown';
+import { showToast } from '../Toast';
+import { encodeShare } from '../sharing/share-url';
+import { loadHistory, pushSnapshot } from '../sharing/history';
+import { t } from '../i18n';
+
+const SNAPSHOT_DEBOUNCE_MS = 5000;
+
+/**
+ * Owns share-by-URL flow + LocalStorage history snapshots + the history
+ * dropdown popover. Wires its own buttons; the host only triggers
+ * `scheduleSnapshot()` on doc change.
+ */
+export class HistoryController {
+  private snapshotTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(
+    private readonly root: HTMLElement,
+    private readonly editor: EditorApi,
+    private readonly dropdown: HistoryDropdownApi | null,
+  ) {
+    this.dropdown?.update(loadHistory());
+    this.dropdown?.onSelect((content) => {
+      this.editor.setValue(content);
+      this.closePopover();
+    });
+    this.bindToggleButton();
+    this.bindShareButton();
+  }
+
+  scheduleSnapshot(): void {
+    if (this.snapshotTimer) clearTimeout(this.snapshotTimer);
+    this.snapshotTimer = setTimeout(() => {
+      pushSnapshot(this.editor.getValue());
+      this.dropdown?.update(loadHistory());
+    }, SNAPSHOT_DEBOUNCE_MS);
+  }
+
+  private bindToggleButton(): void {
+    const btn = this.root.querySelector<HTMLButtonElement>('[data-action="history-toggle"]');
+    const pop = this.root.querySelector<HTMLElement>('[data-pg-history]');
+    if (!btn || !pop) return;
+    btn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      pop.hidden = !pop.hidden;
+    });
+    document.addEventListener('click', (e) => {
+      const within = (e.target as Element)?.closest?.('[data-pg-history-wrap]');
+      if (!within) pop.hidden = true;
+    });
+  }
+
+  private closePopover(): void {
+    const pop = this.root.querySelector<HTMLElement>('[data-pg-history]');
+    if (pop) pop.hidden = true;
+  }
+
+  private bindShareButton(): void {
+    const btn = this.root.querySelector<HTMLButtonElement>('[data-action="share"]');
+    if (!btn) return;
+    btn.addEventListener('click', async () => {
+      const text = this.editor.getValue();
+      const enc = encodeShare(text);
+      const url = `${window.location.origin}${window.location.pathname}#config=${enc}`;
+      history.replaceState(null, '', `#config=${enc}`);
+      try {
+        await navigator.clipboard.writeText(url);
+        showToast(t('toast.linkCopied'));
+      } catch {
+        showToast(t('toast.copyFailed'));
+      }
+      pushSnapshot(text);
+      this.dropdown?.update(loadHistory());
+    });
+  }
+}
diff --git a/src/lib/playground/controllers/ToolbarController.ts b/src/lib/playground/controllers/ToolbarController.ts
new file mode 100644
index 0000000..96e1e0f
--- /dev/null
+++ b/src/lib/playground/controllers/ToolbarController.ts
@@ -0,0 +1,115 @@
+import type { EditorApi } from '../Editor';
+import { createDivider } from '../Divider';
+import { formatHocon } from '../cm/format';
+import { setWarningSquigglesEnabled, isWarningSquigglesEnabled } from '../cm/hocon-lint';
+import { t } from '../i18n';
+
+/**
+ * Owns the buttons and widgets in the page chrome that don't belong to a
+ * single right-pane: theme toggle, the resizable split divider, the format
+ * button, and the warning-squiggle visibility toggle.
+ *
+ * Mode switching stays in the host (PlaygroundApp) because it has to
+ * coordinate the tutorial controller; this class would otherwise need a
+ * back-reference.
+ */
+export interface ToolbarControllerOptions {
+  /**
+   * Called when the user confirms "Reset" in editor mode. The controller
+   * only owns the button + the confirmation dialog; what "reset" actually
+   * means (DEFAULT_CONTENT, hash clearing, draft clearing) lives in the
+   * host so this class doesn't need to know about app-wide state.
+   */
+  onResetEditor: () => void;
+}
+
+export class ToolbarController {
+  constructor(
+    private readonly root: HTMLElement,
+    private readonly editor: EditorApi,
+    private readonly opts: ToolbarControllerOptions,
+  ) {
+    this.bindThemeToggle();
+    this.bindDivider();
+    this.bindFormatButton();
+    this.bindWarningToggle();
+    this.bindResetEditorButton();
+  }
+
+  private bindThemeToggle(): void {
+    const btn = this.root.querySelector<HTMLButtonElement>('[data-action="theme-toggle"]');
+    if (!btn) return;
+    btn.addEventListener('click', () => {
+      const html = document.documentElement;
+      const next = html.dataset.theme === 'light' ? 'dark' : 'light';
+      html.dataset.theme = next;
+      try { localStorage.setItem('pg-theme', next); } catch { /* ignore */ }
+    });
+    try {
+      const saved = localStorage.getItem('pg-theme');
+      if (saved === 'light' || saved === 'dark') document.documentElement.dataset.theme = saved;
+    } catch { /* ignore */ }
+  }
+
+  private bindDivider(): void {
+    const main = this.root.querySelector<HTMLElement>('.pg-main');
+    const divider = this.root.querySelector<HTMLElement>('[data-pg-divider]');
+    if (!main || !divider) return;
+    const isMobile = window.matchMedia('(max-width: 768px)').matches;
+    createDivider({
+      main,
+      divider,
+      axis: isMobile ? 'vertical' : 'horizontal',
+      minPct: 20,
+      maxPct: 80,
+    });
+  }
+
+  private bindFormatButton(): void {
+    const btn = this.root.querySelector<HTMLButtonElement>('[data-action="format"]');
+    if (!btn) return;
+    btn.disabled = false;
+    btn.title = t('btn.format.title');
+    btn.addEventListener('click', () => {
+      const before = this.editor.getValue();
+      const after = formatHocon(before);
+      if (after !== before) this.editor.setValue(after);
+      this.editor.view.focus();
+    });
+  }
+
+  private bindWarningToggle(): void {
+    const btn = this.root.querySelector<HTMLButtonElement>('[data-action="toggle-warning-squiggles"]');
+    if (!btn) return;
+    try {
+      const stored = localStorage.getItem('pg-warning-squiggles');
+      if (stored === '0') setWarningSquigglesEnabled(this.editor.view, false);
+    } catch { /* ignore */ }
+
+    const sync = (): void => {
+      const on = isWarningSquigglesEnabled(this.editor.view.state);
+      btn.dataset.state = on ? 'on' : 'off';
+      btn.textContent = on ? t('btn.warnings.on') : t('btn.warnings.off');
+      btn.title = on ? t('btn.warnings.title.on') : t('btn.warnings.title.off');
+    };
+    sync();
+
+    btn.addEventListener('click', () => {
+      const next = !isWarningSquigglesEnabled(this.editor.view.state);
+      setWarningSquigglesEnabled(this.editor.view, next);
+      try { localStorage.setItem('pg-warning-squiggles', next ? '1' : '0'); } catch { /* ignore */ }
+      sync();
+    });
+  }
+
+  private bindResetEditorButton(): void {
+    const btn = this.root.querySelector<HTMLButtonElement>('[data-action="reset-editor"]');
+    if (!btn) return;
+    btn.title = t('btn.reset.title');
+    btn.addEventListener('click', () => {
+      // Native confirm is good enough here: it's modal, accessible, and
+      // doesn't introduce a custom-modal dependency. The string is i18n'd.
+      if (window.confirm(t('confirm.reset.editor'))) this.opts.onResetEditor();
+    });
+  }
+}
diff --git a/src/lib/playground/controllers/TutorialController.test.ts b/src/lib/playground/controllers/TutorialController.test.ts
new file mode 100644
index 0000000..2bb57f8
--- /dev/null
+++ b/src/lib/playground/controllers/TutorialController.test.ts
@@ -0,0 +1,203 @@
+import { describe, test, expect, beforeEach, vi } from 'vitest';
+import { TutorialController } from './TutorialController';
+import type { EditorApi } from '../Editor';
+import type { TutorialPanelApi } from '../TutorialPanel';
+import type { Lesson } from '../tutorial/types';
+
+/**
+ * The controller wires the tutorial UI to the editor; we mock both sides
+ * and assert the state-machine behavior. We focus on draft preservation
+ * and reset confirmation - everything else (engine progress, hint counter)
+ * is covered by tutorial/engine.test.ts.
+ */
+
+function fakeEditor(initial = ''): EditorApi & { __doc: string } {
+  let doc = initial;
+  return {
+    view: {} as EditorApi['view'],
+    getValue: () => doc,
+    setValue: (t: string) => { doc = t; },
+    destroy: () => {},
+    get __doc() { return doc; },
+  };
+}
+
+function fakePanel(): TutorialPanelApi & { __passed: boolean } {
+  return {
+    showLesson: vi.fn(),
+    showCompleted: vi.fn(),
+    setPassed: vi.fn(function (this: { __passed: boolean }, p: boolean) { this.__passed = p; }),
+    onHint: vi.fn(),
+    onReset: vi.fn(),
+    onSkip: vi.fn(),
+    onNext: vi.fn(),
+    onPrev: vi.fn(),
+    onJump: vi.fn(),
+    __passed: false,
+  } as unknown as TutorialPanelApi & { __passed: boolean };
+}
+
+beforeEach(() => {
+  try { localStorage.clear(); } catch { /* ignore */ }
+});
+
+describe('TutorialController draft preservation', () => {
+  test('leave + enter on the SAME lesson restores in-flight edits', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    ctl.enter('01-introduction');
+    expect(editor.__doc).toMatch(/title/); // starter loaded
+
+    editor.setValue('title = "MY EDITED VALUE"');
+    ctl.leave();
+
+    // Simulate user round-tripping through editor mode
+    editor.setValue('something completely different');
+
+    ctl.enter('01-introduction');
+    expect(editor.__doc).toBe('title = "MY EDITED VALUE"');
+  });
+
+  test('leave + enter on a DIFFERENT lesson loads its starter (drops draft)', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    ctl.enter('01-introduction');
+    editor.setValue('drafted lesson 0');
+    ctl.leave();
+
+    ctl.enter('02-comments');
+    // 02-comments starter contains `title = "My menu"` and `size = 3`
+    expect(editor.__doc).toContain('My menu');
+    expect(editor.__doc).not.toContain('drafted lesson 0');
+  });
+
+  test('reset asks for confirm and only clears on yes', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    let onReset!: () => void;
+    panel.onReset = vi.fn((fn: () => void) => { onReset = fn; });
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    ctl.enter('01-introduction');
+    editor.setValue('user edits');
+
+    // confirm denied -> editor untouched
+    const spy = vi.spyOn(window, 'confirm').mockReturnValue(false);
+    onReset();
+    expect(editor.__doc).toBe('user edits');
+
+    // confirm accepted -> back to starter, draft cleared
+    spy.mockReturnValue(true);
+    onReset();
+    expect(editor.__doc).toMatch(/title = ""/);
+
+    // verify draft is actually cleared: a leave/re-enter must NOT bring back 'user edits'
+    ctl.leave();
+    editor.setValue('intermediate');
+    ctl.enter('01-introduction');
+    expect(editor.__doc).not.toBe('user edits');
+
+    spy.mockRestore();
+  });
+
+  test('refresh is a no-op outside tutorial mode', () => {
+    const editor = fakeEditor('anything');
+    const panel = fakePanel();
+    const ctl = new TutorialController(editor, panel, () => {});
+    // Never entered -> no current lesson
+    ctl.refresh();
+    expect(panel.setPassed).not.toHaveBeenCalled();
+  });
+});
+
+describe('TutorialController navigation (Prev / Jump)', () => {
+  test('Prev navigates to previous lesson without marking progress', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    let onPrev!: () => void;
+    panel.onPrev = vi.fn((fn: () => void) => { onPrev = fn; });
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    ctl.enter('02-comments');
+    expect(editor.__doc).toContain('My menu'); // 01 starter
+
+    onPrev();
+    expect(editor.__doc).toMatch(/title = ""/); // 00 starter
+    // Progress not mutated by Prev: localStorage progress should not list 01 as completed
+    const progress = JSON.parse(localStorage.getItem('am_playground_progress') ?? '{}');
+    expect(progress.completed ?? []).not.toContain('02-comments');
+    expect(progress.skipped ?? []).not.toContain('02-comments');
+  });
+
+  test('Prev is a no-op at the first lesson', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    let onPrev!: () => void;
+    panel.onPrev = vi.fn((fn: () => void) => { onPrev = fn; });
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    ctl.enter('01-introduction');
+    const before = editor.__doc;
+    onPrev();
+    expect(editor.__doc).toBe(before);
+  });
+
+  test('Jump loads target lesson without marking progress', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    let onJump!: (id: string) => void;
+    panel.onJump = vi.fn((fn: (id: string) => void) => { onJump = fn; });
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    ctl.enter('01-introduction');
+    onJump('02-comments');
+    expect(editor.__doc).toContain('My menu');
+
+    const progress = JSON.parse(localStorage.getItem('am_playground_progress') ?? '{}');
+    expect(progress.completed ?? []).not.toContain('01-introduction');
+  });
+
+  test('Jump to current lesson is a no-op', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    let onJump!: (id: string) => void;
+    panel.onJump = vi.fn((fn: (id: string) => void) => { onJump = fn; });
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    ctl.enter('01-introduction');
+    editor.setValue('user changes');
+    onJump('01-introduction');
+    expect(editor.__doc).toBe('user changes'); // not reloaded
+  });
+
+  test('enter() falls back to first lesson when saved id is stale', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    // Simulate a leftover progress entry pointing at a removed lesson.
+    localStorage.setItem('am_playground_progress', JSON.stringify({
+      current: '99-was-removed', completed: [], skipped: [], hintsUsed: {},
+    }));
+    ctl.enter();
+
+    // Should land on the first real lesson (01-introduction starter), NOT
+    // show the "course complete" screen.
+    expect(panel.showCompleted).not.toHaveBeenCalled();
+    expect(editor.__doc).toMatch(/title = ""/); // 01-introduction starter
+  });
+
+  test('enter() with explicit unknown id also falls back', () => {
+    const editor = fakeEditor();
+    const panel = fakePanel();
+    const ctl = new TutorialController(editor, panel, () => {});
+
+    ctl.enter('does-not-exist');
+    expect(panel.showCompleted).not.toHaveBeenCalled();
+    expect(editor.__doc).toMatch(/title = ""/);
+  });
+});
diff --git a/src/lib/playground/controllers/TutorialController.ts b/src/lib/playground/controllers/TutorialController.ts
new file mode 100644
index 0000000..11cb37b
--- /dev/null
+++ b/src/lib/playground/controllers/TutorialController.ts
@@ -0,0 +1,172 @@
+import type { EditorApi } from '../Editor';
+import type { TutorialPanelApi } from '../TutorialPanel';
+import { listLessons, getLesson, firstLessonId, prevLessonId, lessonPosition, lessonCount } from '../tutorial/lessons';
+import { runCheck, loadProgress, saveProgress, markCompleted, markSkipped, bumpHint } from '../tutorial/engine';
+import type { Lesson } from '../tutorial/types';
+import { t } from '../i18n';
+
+/**
+ * Owns "tutorial mode" state and wires the lesson-runner UI to the editor.
+ * The host calls `enter()` / `leave()` based on UI mode switching, and
+ * `refresh()` whenever the editor doc changes so the "goal reached"
+ * indicator stays in sync.
+ *
+ * In-flight edits to the current lesson are preserved in `currentDraft`
+ * across mode switches (editor <-> tutorial), so toggling mode never
+ * silently throws away work. Drafts are NOT persisted to localStorage -
+ * a page reload still re-loads the lesson starter.
+ */
+export class TutorialController {
+  private currentLesson: Lesson | null = null;
+  /**
+   * Draft of the most recently active lesson (id + content). Stored as a
+   * pair so the draft is only restored when re-entering THAT lesson - going
+   * to a different lesson always loads its starter, never another lesson's
+   * leftovers. At most one draft is held at any time.
+   */
+  private lastDraft: { id: string; content: string } | null = null;
+
+  constructor(
+    private readonly editor: EditorApi,
+    private readonly panel: TutorialPanelApi,
+    private readonly onLessonOpened: (id: string) => void,
+  ) {
+    panel.onHint(() => this.handleHint());
+    panel.onReset(() => this.handleReset());
+    panel.onSkip(() => this.handleSkip());
+    panel.onNext(() => this.handleNext());
+    panel.onPrev(() => this.handlePrev());
+    panel.onJump((id) => this.handleJump(id));
+  }
+
+  isActive(): boolean {
+    return this.currentLesson !== null;
+  }
+
+  enter(initialLessonId?: string | null): void {
+    const requested = initialLessonId ?? loadProgress().current ?? firstLessonId();
+    // If the saved/url id no longer exists (lesson was renamed or removed in
+    // a content refactor), fall back to the first lesson rather than show
+    // "Course complete" - that screen is for actual completion, not for
+    // stale state.
+    const id = (requested && getLesson(requested)) ? requested : firstLessonId();
+    this.loadLesson(id);
+  }
+
+  leave(): void {
+    // Snapshot the editor for the lesson so re-entering tutorial mode
+    // (without a lesson swap) restores the user's in-flight edits instead
+    // of resetting them to the starter.
+    if (this.currentLesson) {
+      this.lastDraft = { id: this.currentLesson.id, content: this.editor.getValue() };
+    }
+    this.currentLesson = null;
+  }
+
+  /** Re-run the current lesson's check against editor content. No-op outside tutorial mode. */
+  refresh(): void {
+    if (!this.currentLesson) return;
+    const passed = runCheck(this.editor.getValue(), this.currentLesson.check);
+    this.panel.setPassed(passed);
+  }
+
+  private loadLesson(id: string): void {
+    const lesson = getLesson(id);
+    if (!lesson) {
+      this.panel.showCompleted(t('tutorial.done.body'));
+      this.currentLesson = null;
+      this.lastDraft = null;
+      return;
+    }
+    this.currentLesson = lesson;
+    const progress = loadProgress();
+    saveProgress({ ...progress, current: id });
+    const hintsUsed = progress.hintsUsed[id] ?? 0;
+    // Restore the draft only if it belongs to THIS lesson; otherwise it's
+    // leftovers from a different lesson the user was working on.
+    const draftMatches = this.lastDraft && this.lastDraft.id === id;
+    const initialContent = draftMatches ? this.lastDraft!.content : lesson.starter;
+    if (!draftMatches) this.lastDraft = null;
+    const passed = runCheck(initialContent, lesson.check);
+    this.panel.showLesson(lesson, {
+      hintsUsed,
+      passed,
+      position: lessonPosition(id),
+      total: lessonCount(),
+      allLessons: listLessons(),
+      progress: {
+        completed: new Set(progress.completed),
+        skipped: new Set(progress.skipped),
+      },
+      hasPrev: prevLessonId(id) !== null,
+    });
+    this.editor.setValue(initialContent);
+    this.onLessonOpened(id);
+  }
+
+  private advanceAfter(currentId: string): void {
+    // Advancing leaves the current lesson behind - drop its draft.
+    this.lastDraft = null;
+    const lessons = listLessons();
+    const idx = lessons.findIndex((l) => l.id === currentId);
+    const next = lessons[idx + 1];
+    if (next) this.loadLesson(next.id);
+    else this.panel.showCompleted(t('tutorial.done.body'));
+  }
+
+  private handleHint(): void {
+    if (!this.currentLesson) return;
+    saveProgress(bumpHint(loadProgress(), this.currentLesson.id));
+    // Preserve the user's edits when re-rendering the panel for the new hint.
+    this.lastDraft = { id: this.currentLesson.id, content: this.editor.getValue() };
+    this.loadLesson(this.currentLesson.id);
+  }
+
+  private handleReset(): void {
+    if (!this.currentLesson) return;
+    if (!window.confirm(t('confirm.reset.tutorial'))) return;
+    this.lastDraft = null;
+    this.editor.setValue(this.currentLesson.starter);
+    // Re-run check so the "Next" button state reflects the fresh starter.
+    const passed = runCheck(this.currentLesson.starter, this.currentLesson.check);
+    this.panel.setPassed(passed);
+  }
+
+  private handleSkip(): void {
+    if (!this.currentLesson) return;
+    saveProgress(markSkipped(loadProgress(), this.currentLesson.id));
+    this.advanceAfter(this.currentLesson.id);
+  }
+
+  private handleNext(): void {
+    if (!this.currentLesson) return;
+    saveProgress(markCompleted(loadProgress(), this.currentLesson.id));
+    this.advanceAfter(this.currentLesson.id);
+  }
+
+  /**
+   * Navigate to the previous lesson WITHOUT mutating progress. Unlike Skip
+   * (which marks the current lesson as skipped) or Next (which marks it
+   * completed), Prev is pure navigation - the user is just paging back.
+   * No-op at the first lesson.
+   */
+  private handlePrev(): void {
+    if (!this.currentLesson) return;
+    const prev = prevLessonId(this.currentLesson.id);
+    if (!prev) return;
+    this.lastDraft = null; // discard current lesson's draft on navigation
+    this.loadLesson(prev);
+  }
+
+  /**
+   * Jump directly to any lesson by id (called from the lessons popup).
+   * Same semantics as Prev: pure navigation, no progress mutation. The
+   * destination lesson loads its starter (drafts only survive on the
+   * exact lesson they belong to).
+   */
+  private handleJump(id: string): void {
+    if (!id || (this.currentLesson && this.currentLesson.id === id)) return;
+    this.lastDraft = null;
+    this.loadLesson(id);
+  }
+}
diff --git a/src/lib/playground/hocon/diag.test.ts b/src/lib/playground/hocon/diag.test.ts
new file mode 100644
index 0000000..d13d413
--- /dev/null
+++ b/src/lib/playground/hocon/diag.test.ts
@@ -0,0 +1,48 @@
+import { describe, test, expect } from 'vitest';
+import { formatDiagMessage } from './diag';
+import type { DiagCode } from './types';
+import { en } from '../i18n/translations/en';
+
+/**
+ * The DiagCode union and the en translation table must stay in sync. If
+ * this test fails, you either added a new code without translating it, or
+ * removed a code without dropping its translation key.
+ */
+const ALL_CODES: DiagCode[] = [
+  'parser.include-not-supported',
+  'parser.unexpected-token',
+  'parser.expected-value-after-sep',
+  'parser.expected-key-separator',
+  'parser.expected-closing-brace',
+  'parser.unexpected-after-array-element',
+  'parser.unexpected-in-array',
+  'parser.expected-closing-bracket',
+  'resolve.circular-substitution',
+  'resolve.unresolved-substitution',
+  'validate.unknown-key',
+  'validate.expected-list-of-objects',
+];
+
+describe('diag.ts', () => {
+  test('every DiagCode has an en translation', () => {
+    const missing = ALL_CODES.filter((code) => !(`diag.${code}` in en));
+    expect(missing).toEqual([]);
+  });
+
+  test('en table has no orphan diag.* keys (all keys are reachable from DiagCode)', () => {
+    const expected = new Set(ALL_CODES.map((c) => `diag.${c}`));
+    const orphans = Object.keys(en).filter((k) => k.startsWith('diag.') && !expected.has(k));
+    expect(orphans).toEqual([]);
+  });
+
+  test('formatDiagMessage interpolates params', () => {
+    expect(formatDiagMessage('validate.unknown-key', { key: 'foo', scope: 'menu-root' }))
+      .toBe('Unknown key `foo` in menu-root scope');
+  });
+
+  test('formatDiagMessage falls back to the key for unknown codes', () => {
+    // Cast through unknown to simulate runtime drift between code and table.
+    const result = formatDiagMessage('does.not.exist' as DiagCode);
+    expect(result).toBe('diag.does.not.exist');
+  });
+});
diff --git a/src/lib/playground/hocon/diag.ts b/src/lib/playground/hocon/diag.ts
new file mode 100644
index 0000000..0a77009
--- /dev/null
+++ b/src/lib/playground/hocon/diag.ts
@@ -0,0 +1,12 @@
+import type { DiagCode, DiagParams } from './types';
+import { t, type TranslationKey } from '../i18n';
+
+/**
+ * Render the localized message for a diagnostic code in the active locale.
+ * Centralized so emitters and external consumers (linter overlay,
+ * ValidationPanel) share the same lookup, and so a future move to a
+ * different i18n backend touches one function.
+ */
+export function formatDiagMessage(code: DiagCode, params?: DiagParams): string {
+  return t(`diag.${code}` as TranslationKey, params);
+}
diff --git a/src/lib/playground/hocon/parser.test.ts b/src/lib/playground/hocon/parser.test.ts
new file mode 100644
index 0000000..2e4ae3e
--- /dev/null
+++ b/src/lib/playground/hocon/parser.test.ts
@@ -0,0 +1,191 @@
+import { describe, test, expect } from 'vitest';
+import { parse } from './parser';
+import { tokenizeText } from './tokenize';
+import type { Node, Entry } from './types';
+
+function parseString(input: string) {
+  return parse(tokenizeText(input));
+}
+
+function getEntries(root: Node): Entry[] {
+  if (root.kind !== 'object') throw new Error('root not object');
+  return root.entries;
+}
+
+describe('parser - happy path', () => {
+  test('single key=value', () => {
+    const r = parseString('size = 3');
+    expect(r.diagnostics).toEqual([]);
+    const e = getEntries(r.ast);
+    expect(e).toHaveLength(1);
+    expect(e[0].path).toEqual(['size']);
+    expect(e[0].value).toMatchObject({ kind: 'number', value: 3 });
+  });
+
+  test('colon separator', () => {
+    const r = parseString('a: 1');
+    expect(r.diagnostics).toEqual([]);
+    expect(getEntries(r.ast)[0].value).toMatchObject({ kind: 'number', value: 1 });
+  });
+
+  test('string value', () => {
+    const r = parseString('title = "Hello"');
+    expect(r.diagnostics).toEqual([]);
+    expect(getEntries(r.ast)[0].value).toMatchObject({ kind: 'string', value: 'Hello' });
+  });
+
+  test('boolean and null', () => {
+    const r = parseString('a = true\nb = null');
+    expect(r.diagnostics).toEqual([]);
+    const entries = getEntries(r.ast);
+    expect(entries[0].value).toMatchObject({ kind: 'bool', value: true });
+    expect(entries[1].value).toMatchObject({ kind: 'null' });
+  });
+
+  test('object value with `=`', () => {
+    const r = parseString('outer = { a = 1 }');
+    expect(r.diagnostics).toEqual([]);
+    expect(getEntries(r.ast)[0].value.kind).toBe('object');
+  });
+
+  test('object value without separator', () => {
+    const r = parseString('outer { a = 1 }');
+    expect(r.diagnostics).toEqual([]);
+    expect(getEntries(r.ast)[0].value.kind).toBe('object');
+  });
+
+  test('array value', () => {
+    const r = parseString('xs = [1, 2, 3]');
+    expect(r.diagnostics).toEqual([]);
+    const v = getEntries(r.ast)[0].value;
+    expect(v.kind).toBe('array');
+    if (v.kind === 'array') expect(v.items).toHaveLength(3);
+  });
+
+  test('dotted key path', () => {
+    const r = parseString('a.b.c = 1');
+    expect(r.diagnostics).toEqual([]);
+    expect(getEntries(r.ast)[0].path).toEqual(['a', 'b', 'c']);
+  });
+
+  test('substitution value', () => {
+    const r = parseString('x = ${a.b}');
+    expect(r.diagnostics).toEqual([]);
+    const v = getEntries(r.ast)[0].value;
+    expect(v.kind).toBe('substitution');
+    if (v.kind === 'substitution') {
+      expect(v.path).toEqual(['a', 'b']);
+      expect(v.optional).toBe(false);
+    }
+  });
+
+  test('optional substitution', () => {
+    const r = parseString('x = ${?a}');
+    const v = getEntries(r.ast)[0].value;
+    if (v.kind === 'substitution') expect(v.optional).toBe(true);
+  });
+
+  test('multiple entries on multiple lines', () => {
+    const r = parseString('a = 1\nb = 2\nc = 3');
+    expect(r.diagnostics).toEqual([]);
+    expect(getEntries(r.ast)).toHaveLength(3);
+  });
+
+  test('nested object', () => {
+    const r = parseString('a {\n  b = 1\n  c = 2\n}');
+    expect(r.diagnostics).toEqual([]);
+    const v = getEntries(r.ast)[0].value;
+    expect(v.kind).toBe('object');
+    if (v.kind === 'object') expect(v.entries).toHaveLength(2);
+  });
+
+  test('comments are ignored', () => {
+    const r = parseString('# header comment\na = 1 # inline\n# trailing');
+    expect(r.diagnostics).toEqual([]);
+    expect(getEntries(r.ast)).toHaveLength(1);
+  });
+
+  test('+= append marker', () => {
+    const r = parseString('xs += 1');
+    expect(r.diagnostics).toEqual([]);
+    expect(getEntries(r.ast)[0].append).toBe(true);
+  });
+
+  test('include emitted as warning, parse continues', () => {
+    const r = parseString('include file("a.conf")\na = 1');
+    expect(r.diagnostics.some((d) => d.severity === 'warning' && /include/i.test(d.message))).toBe(true);
+    expect(getEntries(r.ast)).toHaveLength(1);
+  });
+});
+
+describe('parser - errors', () => {
+  test('missing value after `=`', () => {
+    const r = parseString('a =');
+    expect(r.diagnostics.some((d) => d.severity === 'error' && /value/i.test(d.message))).toBe(true);
+  });
+
+  test('unmatched `{`', () => {
+    const r = parseString('a {\n  b = 1');
+    expect(r.diagnostics.some((d) => d.severity === 'error' && /\}/.test(d.message))).toBe(true);
+  });
+
+  test('unmatched `[`', () => {
+    const r = parseString('xs = [1, 2');
+    expect(r.diagnostics.some((d) => d.severity === 'error' && /\]/.test(d.message))).toBe(true);
+  });
+
+  test('error has line and column', () => {
+    const r = parseString('a = ');
+    const err = r.diagnostics.find((d) => d.severity === 'error');
+    expect(err).toBeDefined();
+    expect(err!.line).toBeGreaterThanOrEqual(1);
+    expect(err!.column).toBeGreaterThanOrEqual(1);
+  });
+
+  test('object-field syntax inside array errors', () => {
+    // `slot: 5` is a key:value pair, only valid in objects. In an array
+    // context HOCON wants either a value or a wrapped `{ slot: 5 }`.
+    const r = parseString('items = [\n  slot: 5\n  { slot = 0 }\n]');
+    expect(r.diagnostics.some((d) => d.severity === 'error' && /array/i.test(d.message))).toBe(true);
+  });
+
+  test('value followed by `:` inside array errors', () => {
+    // After parsing `5` as a number, the next `:` is illegal here.
+    const r = parseString('xs = [5 : 10]');
+    expect(r.diagnostics.some((d) => d.severity === 'error' && /after array element/i.test(d.message))).toBe(true);
+  });
+
+  test('quoted dotted key is a single literal key, not a path', () => {
+    const r = parseString('"a.b" = 1');
+    expect(r.diagnostics).toEqual([]);
+    const e = getEntries(r.ast);
+    expect(e[0].path).toEqual(['a.b']);
+  });
+
+  test('triple-quoted string value parses', () => {
+    const r = parseString('s = """multi"""');
+    expect(r.diagnostics).toEqual([]);
+    const e = getEntries(r.ast);
+    expect(e[0].value.kind).toBe('string');
+    if (e[0].value.kind === 'string') {
+      expect(e[0].value.value).toBe('multi');
+    }
+  });
+
+  test('trailing comma in array is harmless', () => {
+    const r = parseString('xs = [1, 2, 3,]');
+    expect(r.diagnostics.filter((d) => d.severity === 'error')).toEqual([]);
+  });
+
+  test('self-referential substitution parses', () => {
+    const r = parseString('a = ${a}');
+    expect(r.diagnostics).toEqual([]);
+    const v = getEntries(r.ast)[0].value;
+    expect(v.kind).toBe('substitution');
+  });
+
+  test('plain numbers list passes (no false-positive)', () => {
+    const r = parseString('xs = [1, 2, 3]');
+    expect(r.diagnostics.filter((d) => d.severity === 'error')).toEqual([]);
+  });
+});
diff --git a/src/lib/playground/hocon/parser.ts b/src/lib/playground/hocon/parser.ts
new file mode 100644
index 0000000..bc7ac22
--- /dev/null
+++ b/src/lib/playground/hocon/parser.ts
@@ -0,0 +1,312 @@
+import type { TokenWithPos, Node, Entry, Loc, Diagnostic, DiagCode, DiagParams, ParseResult } from './types';
+import { formatDiagMessage } from './diag';
+
+export function parse(tokens: TokenWithPos[]): ParseResult {
+  const meaningful = tokens.filter((t) => t.type !== 'comment');
+  const p = new Parser(meaningful);
+  const root = p.parseRoot();
+  return { ast: root, diagnostics: p.diagnostics };
+}
+
+class Parser {
+  pos = 0;
+  diagnostics: Diagnostic[] = [];
+
+  constructor(private toks: TokenWithPos[]) {}
+
+  peek(offset = 0): TokenWithPos | null {
+    return this.toks[this.pos + offset] ?? null;
+  }
+
+  consume(): TokenWithPos | null {
+    return this.toks[this.pos++] ?? null;
+  }
+
+  skipSeparators(): void {
+    while (this.peek()) {
+      const t = this.peek()!;
+      if (t.type === 'newline') { this.pos++; continue; }
+      if (t.type === 'punctuation' && t.text === ',') { this.pos++; continue; }
+      break;
+    }
+  }
+
+  emitError(code: DiagCode, params: DiagParams | undefined, t: TokenWithPos | null): void {
+    const loc = t ?? this.toks[this.toks.length - 1] ?? this.makeFakeToken();
+    this.diagnostics.push({
+      severity: 'error',
+      code,
+      params,
+      message: formatDiagMessage(code, params),
+      line: loc.line,
+      column: loc.column,
+      offset: loc.offset,
+      length: loc.text?.length ?? 1,
+    });
+  }
+
+  emitWarning(code: DiagCode, params: DiagParams | undefined, t: TokenWithPos | null): void {
+    const loc = t ?? this.makeFakeToken();
+    this.diagnostics.push({
+      severity: 'warning',
+      code,
+      params,
+      message: formatDiagMessage(code, params),
+      line: loc.line,
+      column: loc.column,
+      offset: loc.offset,
+      length: loc.text?.length ?? 1,
+    });
+  }
+
+  parseRoot(): Node {
+    const start = this.peek() ?? this.makeFakeToken();
+    const entries: Entry[] = [];
+    this.skipSeparators();
+    while (this.peek() !== null) {
+      const before = this.pos;
+      const e = this.parseEntry();
+      if (e) entries.push(e);
+      if (this.pos === before) this.pos++;
+      this.skipSeparators();
+    }
+    const last = this.toks[this.toks.length - 1] ?? start;
+    return {
+      kind: 'object',
+      entries,
+      loc: this.locFromTo(start, last),
+    };
+  }
+
+  parseEntry(): Entry | null {
+    const first = this.peek();
+    if (!first) return null;
+
+    if (first.type === 'keyword' && first.text === 'include') {
+      this.pos++;
+      while (this.peek() && this.peek()!.type !== 'newline') {
+        this.consume();
+      }
+      this.emitWarning('parser.include-not-supported', undefined, first);
+      return null;
+    }
+
+    // Inline spread: `${ref}` at entry position (instead of `key = value`).
+    // Consumed as a substitution Node and stored as a spread Entry; the
+    // resolver merges the referenced object's fields into the enclosing
+    // object. Own keys override spread fields (see resolve.ts).
+    if (first.type === 'substitution') {
+      const sub = this.parseValue();
+      if (!sub || sub.kind !== 'substitution') return null;
+      return { path: [], value: sub, loc: this.tokLoc(first), append: false, spread: true };
+    }
+
+    const path = this.parseKeyPath();
+    if (path.length === 0) {
+      this.emitError('parser.unexpected-token', { text: first.text }, first);
+      this.pos++;
+      return null;
+    }
+
+    const sep = this.peek();
+    let append = false;
+    let value: Node;
+
+    if (sep?.type === 'operator' && (sep.text === '=' || sep.text === ':' || sep.text === '+=')) {
+      append = sep.text === '+=';
+      this.pos++;
+      const v = this.parseValue();
+      if (!v) {
+        this.emitError('parser.expected-value-after-sep', { sep: sep.text }, sep);
+        return null;
+      }
+      value = v;
+    } else if (sep?.type === 'bracket' && sep.text === '{') {
+      const obj = this.parseObject();
+      if (!obj) return null;
+      value = obj;
+    } else {
+      this.emitError('parser.expected-key-separator', undefined, sep ?? first);
+      return null;
+    }
+
+    return {
+      path,
+      value,
+      append,
+      loc: this.locFromTo(first, this.toks[this.pos - 1] ?? first),
+    };
+  }
+
+  parseKeyPath(): string[] {
+    const t = this.peek();
+    if (!t) return [];
+    // Quoted string acts as a single literal key, dots inside are NOT split.
+    // Per HOCON spec: `"a.b" = 1` is a top-level key named "a.b". We strip
+    // the surrounding quotes only - escape sequences like \n stay literal so
+    // downstream consumers (catalog lookup, validateUnknownKeys) compare
+    // against the actual identifier characters the author typed.
+    if (t.type === 'string') {
+      this.pos++;
+      return [this.stripQuotesOnly(t.text)];
+    }
+    if (t.type !== 'key') return [];
+    this.pos++;
+    return t.text.split('.');
+  }
+
+  stripQuotesOnly(raw: string): string {
+    if (raw.startsWith('"""') && raw.endsWith('"""')) return raw.slice(3, -3);
+    if (raw.startsWith('"') && raw.endsWith('"')) return raw.slice(1, -1);
+    return raw;
+  }
+
+  parseValue(): Node | null {
+    const t = this.peek();
+    if (!t) return null;
+
+    if (t.type === 'string') {
+      this.pos++;
+      return { kind: 'string', value: this.unquoteString(t.text), loc: this.tokLoc(t) };
+    }
+    if (t.type === 'number') {
+      this.pos++;
+      return { kind: 'number', value: Number(t.text), loc: this.tokLoc(t) };
+    }
+    if (t.type === 'bool') {
+      this.pos++;
+      const v = t.text === 'true' || t.text === 'yes' || t.text === 'on';
+      return { kind: 'bool', value: v, loc: this.tokLoc(t) };
+    }
+    if (t.type === 'null') {
+      this.pos++;
+      return { kind: 'null', loc: this.tokLoc(t) };
+    }
+    if (t.type === 'duration') {
+      this.pos++;
+      return { kind: 'duration', raw: t.text, loc: this.tokLoc(t) };
+    }
+    if (t.type === 'value') {
+      this.pos++;
+      return { kind: 'value', value: t.text, loc: this.tokLoc(t) };
+    }
+    if (t.type === 'substitution') {
+      this.pos++;
+      const inner = t.text.replace(/^\$\{\??/, '').replace(/\}$/, '');
+      const optional = t.text.startsWith('${?');
+      return { kind: 'substitution', path: inner.split('.'), optional, loc: this.tokLoc(t) };
+    }
+    if (t.type === 'bracket' && t.text === '{') return this.parseObject();
+    if (t.type === 'bracket' && t.text === '[') return this.parseArray();
+
+    return null;
+  }
+
+  parseObject(): Node | null {
+    const open = this.peek();
+    if (!open || open.text !== '{') return null;
+    this.pos++;
+    const entries: Entry[] = [];
+    this.skipSeparators();
+    while (this.peek() && this.peek()!.text !== '}') {
+      const before = this.pos;
+      const e = this.parseEntry();
+      if (e) entries.push(e);
+      if (this.pos === before) this.pos++;
+      this.skipSeparators();
+    }
+    const close = this.peek();
+    if (!close || close.text !== '}') {
+      this.emitError('parser.expected-closing-brace', undefined, open);
+      return { kind: 'object', entries, loc: this.locFromTo(open, this.toks[this.pos - 1] ?? open) };
+    }
+    this.pos++;
+    return { kind: 'object', entries, loc: this.locFromTo(open, close) };
+  }
+
+  parseArray(): Node | null {
+    const open = this.peek();
+    if (!open || open.text !== '[') return null;
+    this.pos++;
+    const items: Node[] = [];
+    this.skipSeparators();
+    while (this.peek() && this.peek()!.text !== ']') {
+      const before = this.pos;
+      const v = this.parseValue();
+      if (v) {
+        items.push(v);
+        // After a value, the only legal continuations are `,`/`;`/newline/`]`.
+        const next = this.peek();
+        if (next && next.text !== ',' && next.text !== ';' && next.text !== ']' && next.type !== 'newline') {
+          this.emitError(
+            'parser.unexpected-after-array-element',
+            { text: next.text },
+            next,
+          );
+          this.pos++;
+        }
+      } else if (this.pos === before) {
+        // parseValue couldn't recognise the token (e.g. it's a `key`-typed
+        // identifier that belongs in an object). Emit an error and skip.
+        const t = this.peek()!;
+        this.emitError(
+          'parser.unexpected-in-array',
+          { text: t.text },
+          t,
+        );
+        this.pos++;
+      }
+      this.skipSeparators();
+    }
+    const close = this.peek();
+    if (!close || close.text !== ']') {
+      this.emitError('parser.expected-closing-bracket', undefined, open);
+      return { kind: 'array', items, loc: this.locFromTo(open, this.toks[this.pos - 1] ?? open) };
+    }
+    this.pos++;
+    return { kind: 'array', items, loc: this.locFromTo(open, close) };
+  }
+
+  unquoteString(raw: string): string {
+    if (raw.startsWith('"""') && raw.endsWith('"""')) return raw.slice(3, -3);
+    if (raw.startsWith('"') && raw.endsWith('"')) {
+      return raw.slice(1, -1).replace(/\\(.)/g, (_, c) => {
+        switch (c) {
+          case 'n': return '\n';
+          case 't': return '\t';
+          case 'r': return '\r';
+          case '"': return '"';
+          case '\\': return '\\';
+          default: return c;
+        }
+      });
+    }
+    return raw;
+  }
+
+  tokLoc(t: TokenWithPos): Loc {
+    return {
+      line: t.line,
+      column: t.column,
+      endLine: t.line,
+      endColumn: t.column + t.text.length,
+      offset: t.offset,
+      length: t.text.length,
+    };
+  }
+
+  locFromTo(a: TokenWithPos, b: TokenWithPos): Loc {
+    return {
+      line: a.line,
+      column: a.column,
+      endLine: b.line,
+      endColumn: b.column + b.text.length,
+      offset: a.offset,
+      length: (b.offset - a.offset) + b.text.length,
+    };
+  }
+
+  makeFakeToken(): TokenWithPos {
+    return { type: 'value', text: '', line: 1, column: 1, offset: 0 };
+  }
+}
diff --git a/src/lib/playground/hocon/resolve.test.ts b/src/lib/playground/hocon/resolve.test.ts
new file mode 100644
index 0000000..229ce82
--- /dev/null
+++ b/src/lib/playground/hocon/resolve.test.ts
@@ -0,0 +1,184 @@
+import { describe, test, expect } from 'vitest';
+import { tokenizeText } from './tokenize';
+import { parse } from './parser';
+import { resolve } from './resolve';
+
+function run(input: string) {
+  const r = parse(tokenizeText(input));
+  return resolve(r.ast);
+}
+
+describe('resolve', () => {
+  test('flat values to plain object', () => {
+    expect(run('a = 1\nb = 2').resolved).toEqual({ a: 1, b: 2 });
+  });
+
+  test('strings + booleans + null', () => {
+    const r = run('a = "x"\nb = true\nc = null');
+    expect(r.resolved).toEqual({ a: 'x', b: true, c: null });
+  });
+
+  test('nested object via dotted key', () => {
+    expect(run('a.b.c = 1').resolved).toEqual({ a: { b: { c: 1 } } });
+  });
+
+  test('object value', () => {
+    expect(run('a = { x = 1, y = 2 }').resolved).toEqual({ a: { x: 1, y: 2 } });
+  });
+
+  test('array value', () => {
+    expect(run('xs = [1, 2, 3]').resolved).toEqual({ xs: [1, 2, 3] });
+  });
+
+  test('substitution resolves to referenced value', () => {
+    expect(run('a = 1\nb = ${a}').resolved).toEqual({ a: 1, b: 1 });
+  });
+
+  test('substitution dotted', () => {
+    expect(run('a = { x = 5 }\nb = ${a.x}').resolved).toEqual({ a: { x: 5 }, b: 5 });
+  });
+
+  test('unresolved required substitution emits warning', () => {
+    const r = run('b = ${missing}');
+    expect(r.warnings.some((w) => /unresolved/i.test(w.message))).toBe(true);
+  });
+
+  test('unresolved optional substitution stays null without warning', () => {
+    const r = run('b = ${?missing}');
+    expect(r.warnings.length).toBe(0);
+    expect(r.resolved).toEqual({ b: null });
+  });
+
+  test('duration kept as string for MVP', () => {
+    expect(run('t = 5s').resolved).toEqual({ t: '5s' });
+  });
+
+  test('later entry overrides earlier', () => {
+    expect(run('a = 1\na = 2').resolved).toEqual({ a: 2 });
+  });
+
+  test('cycle detection emits warning', () => {
+    const r = run('a = ${b}\nb = ${a}');
+    expect(r.warnings.some((w) => /circular/i.test(w.message))).toBe(true);
+  });
+});
+
+describe('duplicate-key object merge', () => {
+  test('two object blocks at the same path merge', () => {
+    const r = run('defaults { a = 1 }\ndefaults { b = 2 }');
+    expect(r.resolved).toEqual({ defaults: { a: 1, b: 2 } });
+  });
+
+  test('three blocks all merge', () => {
+    const r = run('o { a = 1 }\no { b = 2 }\no { c = 3 }');
+    expect(r.resolved).toEqual({ o: { a: 1, b: 2, c: 3 } });
+  });
+
+  test('overlapping field within merge: last wins', () => {
+    const r = run('o { a = 1, b = 2 }\no { b = 99 }');
+    expect(r.resolved).toEqual({ o: { a: 1, b: 99 } });
+  });
+
+  test('merge is recursive on nested objects', () => {
+    const r = run('o { sub { a = 1 } }\no { sub { b = 2 } }');
+    expect(r.resolved).toEqual({ o: { sub: { a: 1, b: 2 } } });
+  });
+
+  test('non-object overwrites existing object (last wins)', () => {
+    const r = run('a { b = 1 }\na = 7');
+    expect(r.resolved).toEqual({ a: 7 });
+  });
+
+  test('object overwrites existing scalar (last wins)', () => {
+    const r = run('a = 7\na { b = 1 }');
+    expect(r.resolved).toEqual({ a: { b: 1 } });
+  });
+
+  test('scalar duplicate still last-wins (not changed by this fix)', () => {
+    const r = run('size = 3\nsize = 5');
+    expect(r.resolved).toEqual({ size: 5 });
+  });
+
+  test('dotted-key path also merges', () => {
+    const r = run('o.a = 1\no.b = 2');
+    expect(r.resolved).toEqual({ o: { a: 1, b: 2 } });
+  });
+});
+
+describe('+= array append', () => {
+  test('append to existing array concatenates', () => {
+    const r = run('items = [{ slot = 0 }]\nitems += [{ slot = 8 }]');
+    expect(r.resolved).toEqual({ items: [{ slot: 0 }, { slot: 8 }] });
+  });
+
+  test('append when key undefined treats as first assignment', () => {
+    const r = run('items += [{ slot = 0 }]');
+    expect(r.resolved).toEqual({ items: [{ slot: 0 }] });
+  });
+
+  test('multiple appends chain', () => {
+    const r = run('xs = [1]\nxs += [2]\nxs += [3]');
+    expect(r.resolved).toEqual({ xs: [1, 2, 3] });
+  });
+
+  test('append preserves item order', () => {
+    const r = run('xs = [1, 2]\nxs += [3, 4]');
+    expect(r.resolved).toEqual({ xs: [1, 2, 3, 4] });
+  });
+
+  test('append with non-array value falls back to overwrite', () => {
+    // Rare/error case; spec would dictate string concat for strings, but
+    // for menu configs you only += arrays. Keep behavior predictable.
+    const r = run('xs = [1]\nxs += "oops"');
+    expect(r.resolved).toEqual({ xs: 'oops' });
+  });
+
+  test('regular = still overwrites (not changed by this fix)', () => {
+    const r = run('xs = [1]\nxs = [2]');
+    expect(r.resolved).toEqual({ xs: [2] });
+  });
+});
+
+describe('inline spread `${ref}` in object', () => {
+  test('spread merges referenced object fields into enclosing object', () => {
+    const r = run('defaults { material = STONE }\nitem { ${defaults} }');
+    expect(r.resolved).toEqual({
+      defaults: { material: 'STONE' },
+      item: { material: 'STONE' },
+    });
+  });
+
+  test('spread alongside explicit fields - explicit fields win on collision', () => {
+    const r = run('defaults { material = STONE, slot = 0 }\nitem { ${defaults}, slot = 4 }');
+    expect((r.resolved as Record<string, unknown>).item).toEqual({ material: 'STONE', slot: 4 });
+  });
+
+  test('spread inside array of items (DRY pattern)', () => {
+    const r = run('defaults { material = STONE }\nitems = [{ slot = 0, ${defaults} }, { slot = 8, ${defaults} }]');
+    expect((r.resolved as { items: unknown[] }).items).toEqual([
+      { slot: 0, material: 'STONE' },
+      { slot: 8, material: 'STONE' },
+    ]);
+  });
+
+  test('multiple spreads in same object compose left-to-right', () => {
+    const r = run('a { x = 1 }\nb { y = 2 }\nc { ${a}, ${b} }');
+    expect((r.resolved as Record<string, unknown>).c).toEqual({ x: 1, y: 2 });
+  });
+
+  test('spread referencing non-object resolves but contributes nothing', () => {
+    const r = run('scalar = 7\no { ${scalar}, real = "field" }');
+    expect((r.resolved as Record<string, unknown>).o).toEqual({ real: 'field' });
+  });
+
+  test('spread of unknown reference still allows surrounding fields to resolve', () => {
+    const r = run('o { ${missing}, real = "field" }');
+    expect((r.resolved as Record<string, unknown>).o).toEqual({ real: 'field' });
+  });
+
+  test('spread does not produce an unknown-key warning for the spread token', () => {
+    // Sanity: parsing+resolving shouldn't raise spread-related parse errors.
+    const r = run('defaults { a = 1 }\nx { ${defaults} }');
+    expect(r.warnings.filter((w) => w.severity === 'error')).toEqual([]);
+  });
+});
diff --git a/src/lib/playground/hocon/resolve.ts b/src/lib/playground/hocon/resolve.ts
new file mode 100644
index 0000000..f2bc958
--- /dev/null
+++ b/src/lib/playground/hocon/resolve.ts
@@ -0,0 +1,217 @@
+import type { Node, Entry, Diagnostic, ResolveResult } from './types';
+import { formatDiagMessage } from './diag';
+
+export function resolve(root: Node): ResolveResult {
+  const warnings: Diagnostic[] = [];
+  if (root.kind !== 'object') {
+    return { resolved: nodeToValueNoSubs(root), warnings };
+  }
+  const tree = buildTree(root.entries, warnings);
+  const visiting = new Set<string>();
+  const resolved = resolveSubsDeep(tree, tree, visiting, warnings);
+  return { resolved, warnings };
+}
+
+type Tree = { [k: string]: Tree | Node };
+
+/**
+ * Symbol-keyed slot on a Tree that holds inline-spread substitutions
+ * collected from `${ref}` entries. Symbol so it doesn't collide with any
+ * user key and isn't enumerated by Object.keys() in resolveSubsDeep.
+ */
+const SPREADS = Symbol('hocon-spreads');
+type TreeWithSpreads = Tree & { [SPREADS]?: Node[] };
+
+function isLeaf(v: Tree | Node): v is Node {
+  return v !== null && typeof v === 'object' && 'kind' in v;
+}
+
+function buildTree(entries: Entry[], warnings: Diagnostic[]): Tree {
+  const tree: TreeWithSpreads = {};
+  for (const e of entries) {
+    if (e.spread) {
+      const list = tree[SPREADS] ?? [];
+      list.push(e.value);
+      tree[SPREADS] = list;
+    } else {
+      setPath(tree, e.path, e.value, e.append, warnings);
+    }
+  }
+  return tree;
+}
+
+function setPath(tree: Tree, path: string[], value: Node, append: boolean, warnings: Diagnostic[]): void {
+  let cur: Tree = tree;
+  for (let i = 0; i < path.length - 1; i++) {
+    const k = path[i];
+    if (!(k in cur) || isLeaf(cur[k])) cur[k] = {};
+    cur = cur[k] as Tree;
+  }
+  const lastKey = path[path.length - 1];
+  if (append) {
+    // `key += value` per HOCON spec. Equivalent to `key = ${?key} [value]`
+    // when value is an array. We implement the common case (value is an
+    // array literal) directly at build time. Substitution-valued appends
+    // (`items += ${shared}`) fall back to overwrite.
+    if (value.kind !== 'array') {
+      cur[lastKey] = value;
+      return;
+    }
+    const existing = cur[lastKey];
+    if (existing === undefined) {
+      cur[lastKey] = value;
+      return;
+    }
+    if (isLeaf(existing) && existing.kind === 'array') {
+      cur[lastKey] = { ...existing, items: [...existing.items, ...value.items] };
+      return;
+    }
+    // existing is an object tree or a non-array leaf - fall back to overwrite.
+    cur[lastKey] = value;
+    return;
+  }
+  if (value.kind === 'object') {
+    const incoming = buildTree(value.entries, warnings);
+    const existing = cur[lastKey];
+    // HOCON spec: when both the previous and the new value at a path are
+    // objects, merge them recursively. When either is non-object, the new
+    // value replaces the old (last-wins for scalars).
+    if (existing !== undefined && !isLeaf(existing)) {
+      cur[lastKey] = mergeTrees(existing as Tree, incoming, warnings);
+    } else {
+      cur[lastKey] = incoming;
+    }
+  } else {
+    cur[lastKey] = value;
+  }
+}
+
+/**
+ * Recursively merge two object trees, last-wins for any non-object collision.
+ * Mutates neither input - returns a fresh tree.
+ */
+function mergeTrees(a: Tree, b: Tree, warnings: Diagnostic[]): Tree {
+  const out: Tree = { ...a };
+  for (const k of Object.keys(b)) {
+    const av = out[k];
+    const bv = b[k];
+    if (av !== undefined && !isLeaf(av) && !isLeaf(bv)) {
+      out[k] = mergeTrees(av as Tree, bv as Tree, warnings);
+    } else {
+      out[k] = bv;
+    }
+  }
+  return out;
+}
+
+function resolveSubsDeep(
+  tree: Tree,
+  root: Tree,
+  visiting: Set<string>,
+  warnings: Diagnostic[],
+): unknown {
+  const out: Record<string, unknown> = {};
+  // Spread substitutions are resolved FIRST so explicit own keys (set
+  // below) win on collision. Matches the typical "defaults + overrides"
+  // intent rather than HOCON's strict declaration-order semantics; trade
+  // documented for lesson-friendliness.
+  const spreads = (tree as TreeWithSpreads)[SPREADS];
+  if (spreads) {
+    for (const sub of spreads) {
+      const resolved = resolveNode(sub, root, visiting, warnings);
+      if (resolved && typeof resolved === 'object' && !Array.isArray(resolved)) {
+        Object.assign(out, resolved);
+      }
+    }
+  }
+  for (const k of Object.keys(tree)) {
+    const v = tree[k];
+    out[k] = isLeaf(v)
+      ? resolveNode(v, root, visiting, warnings)
+      : resolveSubsDeep(v as Tree, root, visiting, warnings);
+  }
+  return out;
+}
+
+function resolveNode(
+  n: Node,
+  root: Tree,
+  visiting: Set<string>,
+  warnings: Diagnostic[],
+): unknown {
+  switch (n.kind) {
+    case 'string': return n.value;
+    case 'number': return n.value;
+    case 'bool': return n.value;
+    case 'null': return null;
+    case 'duration': return n.raw;
+    case 'value': return n.value;
+    case 'array': return n.items.map((it) => resolveNode(it, root, visiting, warnings));
+    case 'object': {
+      const sub = buildTree(n.entries, warnings);
+      return resolveSubsDeep(sub, root, visiting, warnings);
+    }
+    case 'include': return null;
+    case 'substitution': {
+      const key = n.path.join('.');
+      if (visiting.has(key)) {
+        warnings.push({
+          severity: 'warning',
+          code: 'resolve.circular-substitution',
+          params: { ref: '${' + key + '}' },
+          message: formatDiagMessage('resolve.circular-substitution', { ref: '${' + key + '}' }),
+          line: n.loc.line,
+          column: n.loc.column,
+          offset: n.loc.offset,
+          length: n.loc.length,
+        });
+        return null;
+      }
+      const target = lookup(root, n.path);
+      if (target === undefined) {
+        if (!n.optional) {
+          warnings.push({
+            severity: 'warning',
+            code: 'resolve.unresolved-substitution',
+            params: { ref: '${' + key + '}' },
+            message: formatDiagMessage('resolve.unresolved-substitution', { ref: '${' + key + '}' }),
+            line: n.loc.line,
+            column: n.loc.column,
+            offset: n.loc.offset,
+            length: n.loc.length,
+          });
+        }
+        return null;
+      }
+      visiting.add(key);
+      try {
+        if (isLeaf(target)) return resolveNode(target, root, visiting, warnings);
+        return resolveSubsDeep(target as Tree, root, visiting, warnings);
+      } finally {
+        visiting.delete(key);
+      }
+    }
+  }
+}
+
+function lookup(tree: Tree, path: string[]): Tree | Node | undefined {
+  let cur: Tree | Node = tree;
+  for (const k of path) {
+    if (isLeaf(cur)) return undefined;
+    if (!(k in (cur as Tree))) return undefined;
+    cur = (cur as Tree)[k];
+  }
+  return cur;
+}
+
+function nodeToValueNoSubs(n: Node): unknown {
+  switch (n.kind) {
+    case 'string': return n.value;
+    case 'value': return n.value;
+    case 'duration': return n.raw;
+    case 'number': return n.value;
+    case 'bool': return n.value;
+    case 'null': return null;
+    default: return null;
+  }
+}
diff --git a/src/lib/playground/hocon/scope-ranges.test.ts b/src/lib/playground/hocon/scope-ranges.test.ts
new file mode 100644
index 0000000..ea7ed12
--- /dev/null
+++ b/src/lib/playground/hocon/scope-ranges.test.ts
@@ -0,0 +1,80 @@
+import { describe, test, expect } from 'vitest';
+import { tokenizeText } from './tokenize';
+import { parse } from './parser';
+import { buildScopeRanges, scopeAt } from './scope-ranges';
+
+function rangesFor(input: string) {
+  const r = parse(tokenizeText(input));
+  return buildScopeRanges(r.ast);
+}
+
+describe('buildScopeRanges', () => {
+  test('root menu-root range covers entire doc', () => {
+    const r = rangesFor('title = "x"');
+    expect(r[0].scope).toBe('menu-root');
+    expect(r[0].from).toBe(0);
+  });
+
+  test('items array yields item-list scope', () => {
+    const r = rangesFor('items = [\n  { slot = 0 }\n]');
+    expect(r.some((x) => x.scope === 'item-list')).toBe(true);
+  });
+
+  test('item object inside items array yields item scope', () => {
+    const r = rangesFor('items = [\n  { slot = 0 }\n]');
+    expect(r.some((x) => x.scope === 'item')).toBe(true);
+  });
+
+  test('enchantments object yields enchantments scope', () => {
+    const r = rangesFor('items = [{ enchantments { SHARPNESS = 5 } }]');
+    expect(r.some((x) => x.scope === 'enchantments')).toBe(true);
+  });
+
+  test('unknown parent key yields unknown scope', () => {
+    const r = rangesFor('myCustom { foo = 1 }');
+    expect(r.some((x) => x.scope === 'unknown')).toBe(true);
+  });
+
+  test('path is recorded for inner ranges', () => {
+    const r = rangesFor('items = [{ click { left { } } }]');
+    const click = r.find((x) => x.scope === 'click');
+    expect(click).toBeDefined();
+    expect(click!.path).toContain('click');
+  });
+});
+
+describe('scopeAt', () => {
+  test('top-level cursor returns menu-root', () => {
+    const text = 'title = "x"';
+    const r = rangesFor(text);
+    expect(scopeAt(r, 0).scope).toBe('menu-root');
+  });
+
+  test('cursor inside item object returns item', () => {
+    const text = 'items = [\n  {\n    slot = 0\n  }\n]';
+    const r = rangesFor(text);
+    const cursorInsideItem = text.indexOf('slot');
+    expect(scopeAt(r, cursorInsideItem).scope).toBe('item');
+  });
+
+  test('cursor in items array but outside any object returns item-list', () => {
+    const text = 'items = [\n  \n  { slot = 0 }\n]';
+    const r = rangesFor(text);
+    const cursorBeforeItem = text.indexOf('\n  \n') + 3;
+    expect(scopeAt(r, cursorBeforeItem).scope).toBe('item-list');
+  });
+
+  test('cursor inside enchantments returns enchantments', () => {
+    const text = 'items = [{ enchantments {\n  SHARPNESS\n} }]';
+    const r = rangesFor(text);
+    const cursorInEnch = text.indexOf('SHARPNESS');
+    expect(scopeAt(r, cursorInEnch).scope).toBe('enchantments');
+  });
+
+  test('innermost wins when ranges nest', () => {
+    const text = 'items = [{ click { actions { message = "x" } } }]';
+    const r = rangesFor(text);
+    const cursorInActions = text.indexOf('message');
+    expect(scopeAt(r, cursorInActions).scope).toBe('actions');
+  });
+});
diff --git a/src/lib/playground/hocon/scope-ranges.ts b/src/lib/playground/hocon/scope-ranges.ts
new file mode 100644
index 0000000..009488a
--- /dev/null
+++ b/src/lib/playground/hocon/scope-ranges.ts
@@ -0,0 +1,102 @@
+import type { Node, Entry } from './types';
+import { childScopeOf, arrayPositionScope } from '../catalog';
+import type { Scope } from '../catalog/types';
+
+/**
+ * A single block (`{...}` object literal or element-position inside `[...]`)
+ * with the scope that applies to its body.
+ */
+export interface ScopeRange {
+  /** offset of the opening bracket (or 0 for root) */
+  from: number;
+  /** offset just past the closing bracket */
+  to: number;
+  scope: Scope;
+  /** dotted key path that opened this scope (empty for root) */
+  path: string[];
+}
+
+/**
+ * Walk the parser AST once and emit a (from, to, scope, path) range for the
+ * root, every `{ ... }`, and every list-context inside `[ ... ]`. Lets a
+ * cursor-position lookup return the scope in O(n) over the ranges (already
+ * sorted by depth) without re-walking the source text or duplicating the
+ * bracket-balance logic.
+ *
+ * Exposed as a public API so future linter rules / hover-on-`{` previews /
+ * cross-scope substitution checkers can share the same precomputed view of
+ * the AST.
+ */
+export function buildScopeRanges(root: Node): ScopeRange[] {
+  const out: ScopeRange[] = [];
+  if (root.kind === 'object') {
+    out.push({
+      from: root.loc.offset,
+      to: root.loc.offset + root.loc.length,
+      scope: 'menu-root',
+      path: [],
+    });
+    walkEntries(root.entries, 'menu-root', [], out);
+  }
+  return out;
+}
+
+function walkEntries(entries: Entry[], parentScope: Scope, parentPath: string[], out: ScopeRange[]): void {
+  for (const entry of entries) {
+    // Spread entries don't add a key path of their own - skip indexing.
+    if (entry.spread) continue;
+    const path = [...parentPath, ...entry.path];
+    visitValue(entry, parentScope, path, out);
+  }
+}
+
+function visitValue(entry: Entry, parentScope: Scope, fullPath: string[], out: ScopeRange[]): void {
+  void parentScope;
+  const v = entry.value;
+  const keyName = entry.path[entry.path.length - 1];
+  const childScope = childScopeOf(keyName);
+
+  if (v.kind === 'object') {
+    out.push({
+      from: v.loc.offset,
+      to: v.loc.offset + v.loc.length,
+      scope: childScope,
+      path: fullPath,
+    });
+    walkEntries(v.entries, childScope, fullPath, out);
+    return;
+  }
+
+  if (v.kind === 'array') {
+    out.push({
+      from: v.loc.offset,
+      to: v.loc.offset + v.loc.length,
+      scope: arrayPositionScope(childScope),
+      path: fullPath,
+    });
+    for (const item of v.items) {
+      if (item.kind === 'object') {
+        out.push({
+          from: item.loc.offset,
+          to: item.loc.offset + item.loc.length,
+          scope: childScope,
+          path: fullPath,
+        });
+        walkEntries(item.entries, childScope, fullPath, out);
+      }
+    }
+  }
+}
+
+/**
+ * Find the innermost range that contains `pos`. Ranges from buildScopeRanges
+ * are emitted in walk order: nested ranges always come after their parent,
+ * so iterating from the end yields the innermost match first.
+ */
+export function scopeAt(ranges: ScopeRange[], pos: number): { scope: Scope; path: string[] } {
+  for (let i = ranges.length - 1; i >= 0; i--) {
+    const r = ranges[i];
+    if (r.from <= pos && pos <= r.to) return { scope: r.scope, path: r.path };
+  }
+  return { scope: 'menu-root', path: [] };
+}
diff --git a/src/lib/playground/hocon/tokenize.test.ts b/src/lib/playground/hocon/tokenize.test.ts
new file mode 100644
index 0000000..1255b33
--- /dev/null
+++ b/src/lib/playground/hocon/tokenize.test.ts
@@ -0,0 +1,48 @@
+import { describe, test, expect } from 'vitest';
+import { tokenizeText } from './tokenize';
+
+describe('tokenizeText', () => {
+  test('single line', () => {
+    const tokens = tokenizeText('size = 3');
+    const sigs = tokens
+      .filter((t) => t.type !== null)
+      .map((t) => `${t.type}:${t.text}@${t.line}:${t.column}`);
+    expect(sigs).toEqual(['key:size@1:1', 'operator:=@1:6', 'number:3@1:8']);
+  });
+
+  test('two lines have correct line numbers', () => {
+    const tokens = tokenizeText('a = 1\nb = 2');
+    const lineByText: Record<string, number> = {};
+    for (const t of tokens) lineByText[t.text] = t.line;
+    expect(lineByText.a).toBe(1);
+    expect(lineByText.b).toBe(2);
+    expect(lineByText['1']).toBe(1);
+    expect(lineByText['2']).toBe(2);
+  });
+
+  test('emits newline tokens', () => {
+    const tokens = tokenizeText('a = 1\nb = 2');
+    const newlines = tokens.filter((t) => t.type === 'newline');
+    expect(newlines.length).toBe(1);
+    expect(newlines[0].line).toBe(1);
+  });
+
+  test('offset matches input slice for strings', () => {
+    const input = 'foo = "bar"';
+    const tokens = tokenizeText(input);
+    const stringTok = tokens.find((t) => t.type === 'string')!;
+    expect(input.slice(stringTok.offset, stringTok.offset + stringTok.text.length)).toBe('"bar"');
+  });
+
+  test('whitespace-only tokens not emitted', () => {
+    const tokens = tokenizeText('a = 1');
+    const nullCount = tokens.filter((t) => t.type === null).length;
+    expect(nullCount).toBe(0);
+  });
+
+  test('column for second token on same line', () => {
+    const tokens = tokenizeText('xy = 7');
+    const eq = tokens.find((t) => t.text === '=')!;
+    expect(eq.column).toBe(4);
+  });
+});
diff --git a/src/lib/playground/hocon/tokenize.ts b/src/lib/playground/hocon/tokenize.ts
new file mode 100644
index 0000000..3b3ec8a
--- /dev/null
+++ b/src/lib/playground/hocon/tokenize.ts
@@ -0,0 +1,43 @@
+import { tokenizeLine, createState } from '../cm/hocon-tokenizer';
+import type { TokenWithPos } from './types';
+
+export function tokenizeText(input: string): TokenWithPos[] {
+  const lines = input.split('\n');
+  const out: TokenWithPos[] = [];
+  const state = createState();
+  let offset = 0;
+
+  for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+    const line = lines[lineIdx];
+    const tokens = tokenizeLine(line, state);
+    let col = 0;
+
+    for (const t of tokens) {
+      if (t.token !== null) {
+        out.push({
+          type: t.token,
+          text: t.text,
+          line: lineIdx + 1,
+          column: col + 1,
+          offset: offset + col,
+        });
+      }
+      col += t.text.length;
+    }
+
+    if (lineIdx < lines.length - 1) {
+      out.push({
+        type: 'newline',
+        text: '\n',
+        line: lineIdx + 1,
+        column: line.length + 1,
+        offset: offset + line.length,
+      });
+      offset += line.length + 1;
+    } else {
+      offset += line.length;
+    }
+  }
+
+  return out;
+}
diff --git a/src/lib/playground/hocon/types.ts b/src/lib/playground/hocon/types.ts
new file mode 100644
index 0000000..438e7e2
--- /dev/null
+++ b/src/lib/playground/hocon/types.ts
@@ -0,0 +1,105 @@
+import type { TokenType } from '../cm/hocon-tokenizer';
+
+export interface TokenWithPos {
+  type: TokenType | 'newline';
+  text: string;
+  line: number;
+  column: number;
+  offset: number;
+}
+
+export interface Loc {
+  line: number;
+  column: number;
+  endLine: number;
+  endColumn: number;
+  offset: number;
+  length: number;
+}
+
+/**
+ * Stable identifier for a diagnostic kind. The localized message lives in
+ * the translation table under `diag.<code>`. Adding a new emitter site
+ * means: add a member here + add the matching key to all translation files
+ * (a unit test asserts the en table has every code).
+ */
+export type DiagCode =
+  // parser.ts
+  | 'parser.include-not-supported'
+  | 'parser.unexpected-token'
+  | 'parser.expected-value-after-sep'
+  | 'parser.expected-key-separator'
+  | 'parser.expected-closing-brace'
+  | 'parser.unexpected-after-array-element'
+  | 'parser.unexpected-in-array'
+  | 'parser.expected-closing-bracket'
+  // resolve.ts
+  | 'resolve.circular-substitution'
+  | 'resolve.unresolved-substitution'
+  // unknown-keys.ts
+  | 'validate.unknown-key'
+  | 'validate.expected-list-of-objects';
+
+export type DiagParams = Record<string, string | number>;
+
+/**
+ * `code` is the canonical identifier; `params` are the named values
+ * interpolated into the localized template. `message` is the pre-formatted
+ * string in the active locale - emitted at construction time so consumers
+ * that don't know about i18n (like the CodeMirror linter overlay) can keep
+ * reading it directly. ValidationPanel re-renders via `t()` on every
+ * analysis tick, so locale changes still flow through.
+ */
+export interface Diagnostic {
+  severity: 'error' | 'warning';
+  code: DiagCode;
+  params?: DiagParams;
+  message: string;
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+  offset?: number;
+  length?: number;
+}
+
+export type Node =
+  | { kind: 'object'; entries: Entry[]; loc: Loc }
+  | { kind: 'array'; items: Node[]; loc: Loc }
+  | { kind: 'string'; value: string; loc: Loc }
+  | { kind: 'number'; value: number; loc: Loc }
+  | { kind: 'bool'; value: boolean; loc: Loc }
+  | { kind: 'null'; loc: Loc }
+  | { kind: 'substitution'; path: string[]; optional: boolean; loc: Loc }
+  | { kind: 'duration'; raw: string; loc: Loc }
+  | { kind: 'value'; value: string; loc: Loc }
+  | { kind: 'include'; raw: string; loc: Loc };
+
+export interface Entry {
+  /**
+   * Key path segments. Empty `[]` for spread entries (where `value` is a
+   * substitution to be merged into the enclosing object).
+   */
+  path: string[];
+  value: Node;
+  loc: Loc;
+  /** `true` for `+=` entries; resolver concatenates instead of overwriting. */
+  append: boolean;
+  /**
+   * Inline-spread marker. When true, `value` is a substitution Node whose
+   * resolved object is merged into the enclosing object's fields. The
+   * `path` field is `[]`. Consumers iterating entries should skip spreads
+   * if they're indexing by key.
+   */
+  spread?: boolean;
+}
+
+export interface ParseResult {
+  ast: Node;
+  diagnostics: Diagnostic[];
+}
+
+export interface ResolveResult {
+  resolved: unknown;
+  warnings: Diagnostic[];
+}
diff --git a/src/lib/playground/hocon/unknown-keys.test.ts b/src/lib/playground/hocon/unknown-keys.test.ts
new file mode 100644
index 0000000..db0f59f
--- /dev/null
+++ b/src/lib/playground/hocon/unknown-keys.test.ts
@@ -0,0 +1,91 @@
+import { describe, test, expect } from 'vitest';
+import { tokenizeText } from './tokenize';
+import { parse } from './parser';
+import { validateUnknownKeys } from './unknown-keys';
+
+function check(input: string) {
+  const r = parse(tokenizeText(input));
+  return validateUnknownKeys(r.ast);
+}
+
+describe('validateUnknownKeys', () => {
+  test('clean menu-root passes', () => {
+    expect(check('title = "x"\nsize = 3')).toEqual([]);
+  });
+
+  test('unknown top-level key warns', () => {
+    const w = check('blubber = 1');
+    expect(w).toHaveLength(1);
+    expect(w[0].severity).toBe('warning');
+    expect(w[0].message).toContain('blubber');
+    expect(w[0].message).toContain('menu-root');
+  });
+
+  test('unknown key inside enchantments warns', () => {
+    const w = check('items = [{ enchantments { AQUA_AFFINITY = 1, slot = 1 } }]');
+    const slotWarn = w.find((d) => d.message.includes('slot'));
+    expect(slotWarn).toBeDefined();
+    expect(slotWarn!.message).toContain('enchantments');
+  });
+
+  test('known enchantment passes', () => {
+    const w = check('items = [{ enchantments { SHARPNESS = 5 } }]');
+    expect(w.filter((d) => d.message.includes('SHARPNESS'))).toEqual([]);
+  });
+
+  test('valid item inside items array passes', () => {
+    expect(check('items = [\n  { slot = 0, material = STONE }\n]')).toEqual([]);
+  });
+
+  test('unknown key inside item warns', () => {
+    const w = check('items = [\n  { fooBar = 1 }\n]');
+    expect(w.some((d) => d.message.includes('fooBar') && d.message.includes('item'))).toBe(true);
+  });
+
+  test('unknown parent key skips its body (no cascade)', () => {
+    const w = check('myCustom {\n  whatever = 1\n  another = 2\n}');
+    expect(w.some((d) => d.message.includes('myCustom'))).toBe(true);
+    expect(w.some((d) => d.message.includes('whatever'))).toBe(false);
+    expect(w.some((d) => d.message.includes('another'))).toBe(false);
+  });
+
+  test('warning carries line and column', () => {
+    const w = check('title = "x"\nblubber = 1');
+    const d = w[0];
+    expect(d.line).toBe(2);
+    expect(d.column).toBe(1);
+  });
+
+  test('binding rules + props are scope-validated', () => {
+    const w = check('bindings = [\n  { rules { permission = "x" }, props { material = STONE, badKey = 1 } }\n]');
+    expect(w.some((d) => d.message.includes('badKey'))).toBe(true);
+  });
+
+  test('items list rejects bare value (semantic warning)', () => {
+    // Wrap raw value `5` as a single number element (no `slot:` prefix; that
+    // would be a parser error). We verify that even a syntactically valid
+    // bare value triggers a "list of objects" warning.
+    const w = check('items = [\n  5\n  { slot = 0, material = STONE }\n]');
+    expect(w.some((d) => /items.*list of objects.*number/i.test(d.message))).toBe(true);
+  });
+
+  test('items list with all objects passes', () => {
+    const w = check('items = [\n  { slot = 0, material = STONE }\n  { slot = 4, material = DIAMOND }\n]');
+    expect(w.filter((d) => /list of objects/i.test(d.message))).toEqual([]);
+  });
+
+  test('substitution in items list is allowed (template expansion)', () => {
+    const w = check('items = [\n  ${borderTop}\n  { slot = 0 }\n]');
+    expect(w.filter((d) => /list of objects/i.test(d.message))).toEqual([]);
+  });
+
+  test('list of strings (lore) does NOT trigger list-of-objects warning', () => {
+    const w = check('items = [{ slot = 0, lore = ["one", "two"] }]');
+    expect(w.filter((d) => /list of objects/i.test(d.message))).toEqual([]);
+  });
+
+  test('list of strings (flags) does NOT trigger list-of-objects warning', () => {
+    const w = check('items = [{ slot = 0, flags = ["HIDE_ENCHANTS"] }]');
+    expect(w.filter((d) => /list of objects/i.test(d.message))).toEqual([]);
+  });
+});
diff --git a/src/lib/playground/hocon/unknown-keys.ts b/src/lib/playground/hocon/unknown-keys.ts
new file mode 100644
index 0000000..6d11f8d
--- /dev/null
+++ b/src/lib/playground/hocon/unknown-keys.ts
@@ -0,0 +1,96 @@
+import type { Node, Diagnostic } from './types';
+import type { Scope } from '../catalog/types';
+import { getKeysForScope, findKeyDef, childScopeOf } from '../catalog';
+import { formatDiagMessage } from './diag';
+
+/**
+ * Walk the AST and emit a warning for every entry whose key is not in the
+ * catalog for its enclosing scope. Skips entries inside an `unknown` scope
+ * (custom user-defined blocks where we have no schema).
+ */
+export function validateUnknownKeys(root: Node): Diagnostic[] {
+  const warnings: Diagnostic[] = [];
+  if (root.kind === 'object') walkObject(root, 'menu-root', warnings);
+  return warnings;
+}
+
+function walkObject(
+  obj: Extract<Node, { kind: 'object' }>,
+  scope: Scope,
+  warnings: Diagnostic[],
+): void {
+  const skipCheck = scope === 'unknown';
+  const known = skipCheck ? null : new Set(getKeysForScope(scope).map((k) => k.name));
+
+  for (const entry of obj.entries) {
+    const firstKey = entry.path[0];
+    if (!firstKey) continue;
+
+    if (known && !known.has(firstKey)) {
+      const params = { key: firstKey, scope };
+      warnings.push({
+        severity: 'warning',
+        code: 'validate.unknown-key',
+        params,
+        message: formatDiagMessage('validate.unknown-key', params),
+        line: entry.loc.line,
+        column: entry.loc.column,
+        offset: entry.loc.offset,
+        length: firstKey.length,
+      });
+    }
+
+    const childScope = childScopeFor(firstKey, scope);
+    if (childScope) {
+      const def = findKeyDef(firstKey);
+      // Only flag "expects a list of objects" when the key actually targets
+      // a structured element scope (childrenScope set). Lists of primitives
+      // like `lore` (strings) or `flags` (string enum) are valueType: 'list'
+      // too but legitimately hold non-objects.
+      const expectsListOfObjects = def?.valueType === 'list' && !!def.childrenScope;
+      visitValue(entry.value, childScope, warnings, firstKey, expectsListOfObjects);
+    }
+  }
+}
+
+function childScopeFor(keyName: string, parentScope: Scope): Scope | null {
+  const def = findKeyDef(keyName);
+  if (def?.childrenScope) return def.childrenScope;
+  // Unknown key in a known scope still walks its body as `unknown` so we
+  // don't cascade noise into it. Once we're already in `unknown`, stop
+  // descending - we have no schema to validate against.
+  if (parentScope !== 'unknown') return childScopeOf(keyName); // 'unknown'
+  return null;
+}
+
+function visitValue(
+  v: Node,
+  scope: Scope,
+  warnings: Diagnostic[],
+  parentKey: string,
+  expectListOfObjects: boolean,
+): void {
+  if (v.kind === 'object') {
+    walkObject(v, scope, warnings);
+    return;
+  }
+  if (v.kind === 'array') {
+    for (const item of v.items) {
+      if (item.kind === 'object') {
+        walkObject(item, scope, warnings);
+      } else if (expectListOfObjects && item.kind !== 'substitution' && item.kind !== 'include') {
+        const params = { parentKey, itemKind: item.kind };
+        warnings.push({
+          severity: 'warning',
+          code: 'validate.expected-list-of-objects',
+          params,
+          message: formatDiagMessage('validate.expected-list-of-objects', params),
+          line: item.loc.line,
+          column: item.loc.column,
+          offset: item.loc.offset,
+          length: item.loc.length,
+        });
+      }
+    }
+  }
+}
diff --git a/src/lib/playground/i18n/dom.ts b/src/lib/playground/i18n/dom.ts
new file mode 100644
index 0000000..b038354
--- /dev/null
+++ b/src/lib/playground/i18n/dom.ts
@@ -0,0 +1,27 @@
+import { t, type TranslationKey } from './index';
+
+/**
+ * Walk the subtree and apply translations declared via data attributes:
+ *
+ *   <button data-i18n="btn.format">Format</button>          // textContent
+ *   <button data-i18n-title="btn.format.title">...</button> // title attr
+ *   <button data-i18n-aria="theme.toggle.aria">...</button> // aria-label
+ *
+ * Initial English text in the markup serves as a no-JS fallback; this
+ * function overwrites it once the active language is known. Safe to run
+ * multiple times - it always reads fresh translations from `t()`.
+ */
+export function hydrateI18n(root: ParentNode = document): void {
+  for (const el of root.querySelectorAll<HTMLElement>('[data-i18n]')) {
+    const key = el.dataset.i18n as TranslationKey | undefined;
+    if (key) el.textContent = t(key);
+  }
+  for (const el of root.querySelectorAll<HTMLElement>('[data-i18n-title]')) {
+    const key = el.dataset.i18nTitle as TranslationKey | undefined;
+    if (key) el.title = t(key);
+  }
+  for (const el of root.querySelectorAll<HTMLElement>('[data-i18n-aria]')) {
+    const key = el.dataset.i18nAria as TranslationKey | undefined;
+    if (key) el.setAttribute('aria-label', t(key));
+  }
+}
diff --git a/src/lib/playground/i18n/index.test.ts b/src/lib/playground/i18n/index.test.ts
new file mode 100644
index 0000000..2f84792
--- /dev/null
+++ b/src/lib/playground/i18n/index.test.ts
@@ -0,0 +1,137 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import {
+  t,
+  setLang,
+  getLang,
+  detectLang,
+  initLang,
+  availableLangs,
+  plural,
+  pluralForm,
+  _registerForTests,
+  _resetForTests,
+} from './index';
+
+beforeEach(() => {
+  _resetForTests();
+  try { localStorage.removeItem('pg-lang'); } catch { /* ignore */ }
+});
+
+describe('availableLangs', () => {
+  test('includes en and ru (shipped locales)', () => {
+    const langs = availableLangs();
+    expect(langs).toContain('en');
+    expect(langs).toContain('ru');
+  });
+
+  test('result is sorted', () => {
+    const langs = availableLangs();
+    const sorted = [...langs].sort();
+    expect(langs).toEqual(sorted);
+  });
+});
+
+describe('t() basics', () => {
+  test('returns english by default', () => {
+    expect(t('btn.format')).toBe('Format');
+  });
+
+  test('returns ru after setLang(ru)', () => {
+    setLang('ru');
+    expect(t('btn.format')).toBe('Формат');
+  });
+
+  test('falls back to english when ru lacks the key', () => {
+    _registerForTests('xx', { 'btn.format': 'XXX' });
+    setLang('xx');
+    // tab.errors not in xx -> fallback to english
+    expect(t('tab.errors')).toBe('Errors');
+    expect(t('btn.format')).toBe('XXX');
+  });
+
+  test('interpolates ${var} params', () => {
+    expect(t('status.errors', { count: 3, plural: 's' })).toBe('3 errors');
+    expect(t('status.errors', { count: 1, plural: '' })).toBe('1 error');
+  });
+
+  test('missing param keeps literal placeholder (so json.desc ${vars} survives)', () => {
+    // status.errors = "${count} error${plural}"; passing only count leaves ${plural} literal.
+    expect(t('status.errors', { count: 1 })).toBe('1 error${plural}');
+    // No params at all -> raw returned untouched.
+    expect(t('json.desc')).toContain('${vars}');
+  });
+});
+
+describe('setLang / getLang', () => {
+  test('getLang returns active', () => {
+    setLang('ru');
+    expect(getLang()).toBe('ru');
+  });
+
+  test('setLang ignores unknown code', () => {
+    setLang('en');
+    setLang('zz-not-real');
+    expect(getLang()).toBe('en');
+  });
+
+  test('setLang persists to localStorage', () => {
+    setLang('ru');
+    expect(localStorage.getItem('pg-lang')).toBe('ru');
+  });
+});
+
+describe('detectLang', () => {
+  test('honors localStorage', () => {
+    localStorage.setItem('pg-lang', 'ru');
+    expect(detectLang()).toBe('ru');
+  });
+
+  test('honors URL ?lang= over localStorage', () => {
+    localStorage.setItem('pg-lang', 'en');
+    const orig = window.location.href;
+    history.replaceState(null, '', '?lang=ru');
+    try {
+      expect(detectLang()).toBe('ru');
+    } finally {
+      history.replaceState(null, '', orig);
+    }
+  });
+
+  test('falls back to en for unknown locale', () => {
+    localStorage.setItem('pg-lang', 'klingon');
+    expect(detectLang()).toBe('en');
+  });
+
+  test('initLang sets active', () => {
+    localStorage.setItem('pg-lang', 'ru');
+    initLang();
+    expect(getLang()).toBe('ru');
+  });
+});
+
+describe('plural / pluralForm', () => {
+  test('english plural', () => {
+    expect(plural(0)).toBe('s');
+    expect(plural(1)).toBe('');
+    expect(plural(2)).toBe('s');
+  });
+
+  test('pluralForm english two-form', () => {
+    expect(pluralForm(1, ['error', 'errors'])).toBe('error');
+    expect(pluralForm(5, ['error', 'errors'])).toBe('errors');
+  });
+
+  test('pluralForm russian three-form', () => {
+    setLang('ru');
+    const forms = ['а', 'и', ''];
+    expect(pluralForm(1, forms)).toBe('а');   // 1 ошибка
+    expect(pluralForm(2, forms)).toBe('и');   // 2 ошибки
+    expect(pluralForm(5, forms)).toBe('');    // 5 ошибок
+    expect(pluralForm(11, forms)).toBe('');   // 11 ошибок (special)
+    expect(pluralForm(21, forms)).toBe('а');  // 21 ошибка
+    expect(pluralForm(22, forms)).toBe('и');  // 22 ошибки
+    expect(pluralForm(100, forms)).toBe('');  // 100 ошибок
+    expect(pluralForm(101, forms)).toBe('а'); // 101 ошибка
+    expect(pluralForm(112, forms)).toBe('');  // 112 ошибок
+  });
+});
diff --git a/src/lib/playground/i18n/index.ts b/src/lib/playground/i18n/index.ts
new file mode 100644
index 0000000..b6fc5a4
--- /dev/null
+++ b/src/lib/playground/i18n/index.ts
@@ -0,0 +1,171 @@
+import { en, type Dict, type TranslationKey } from './translations/en';
+
+export type { Dict, TranslationKey };
+export type LangCode = string;
+export type LangDict = Partial<Dict>;
+
+const STORAGE_KEY = 'pg-lang';
+const DEFAULT_LANG: LangCode = 'en';
+
+/**
+ * Auto-discovered locale registry. Every `*.ts` file under `./translations/`
+ * is loaded eagerly and its single named export (or `default`) is registered
+ * by file basename - so dropping `translations/de.ts` exporting
+ * `Partial<Dict>` is enough to add German.
+ *
+ * Files must export the dict either as a named export matching the file
+ * basename (e.g. `export const ru: Partial<Dict> = ...` in `ru.ts`) or as
+ * the default export.
+ */
+const registry: Map<LangCode, LangDict> = new Map();
+
+registry.set('en', en);
+loadCommunityLocales();
+
+function loadCommunityLocales(): void {
+  // Vite-only API. Module objects are inlined at build time, so this is a
+  // zero-runtime-cost lookup, not a glob hitting the filesystem.
+  const modules = import.meta.glob<Record<string, unknown>>('./translations/*.ts', {
+    eager: true,
+  });
+  for (const [path, mod] of Object.entries(modules)) {
+    const m = /\/([^/]+)\.ts$/.exec(path);
+    const code = m?.[1];
+    if (!code || code === 'en') continue;
+    const dict = pickDict(mod, code);
+    if (dict) registry.set(code, dict);
+    else console.warn(`[playground i18n] could not extract dict from ${path}`);
+  }
+}
+
+function pickDict(mod: Record<string, unknown>, code: string): LangDict | null {
+  // Prefer named export matching the file basename (idiomatic), fall back
+  // to default. Reject anything that's not a plain object.
+  const candidates: unknown[] = [mod[code], mod.default];
+  for (const c of candidates) {
+    if (c && typeof c === 'object' && !Array.isArray(c)) return c as LangDict;
+  }
+  return null;
+}
+
+let activeLang: LangCode = DEFAULT_LANG;
+
+/** Returns sorted list of available locale codes (always includes 'en'). */
+export function availableLangs(): LangCode[] {
+  return Array.from(registry.keys()).sort();
+}
+
+export function getLang(): LangCode {
+  return activeLang;
+}
+
+/**
+ * Set active language. No-op + warning if unknown. Caller is responsible
+ * for re-rendering or reloading - this function does not touch the DOM.
+ */
+export function setLang(code: LangCode): void {
+  if (!registry.has(code)) {
+    console.warn(`[playground i18n] unknown lang \`${code}\`, ignored`);
+    return;
+  }
+  activeLang = code;
+  try { localStorage.setItem(STORAGE_KEY, code); } catch { /* ignore */ }
+}
+
+/**
+ * Resolve initial language using a cascade. SSR-safe: if `window` is
+ * undefined (build time), returns the default.
+ *
+ *   1. URL ?lang=xx
+ *   2. localStorage `pg-lang`
+ *   3. <html lang="..."> attribute
+ *   4. navigator.language
+ *   5. fallback 'en'
+ *
+ * Each step only matches if the candidate code is in the registry, so a
+ * stale localStorage value or unsupported browser language gracefully
+ * falls through.
+ */
+export function detectLang(): LangCode {
+  if (typeof window === 'undefined') return DEFAULT_LANG;
+  const tries: (string | null | undefined)[] = [];
+  try {
+    const url = new URL(window.location.href);
+    tries.push(url.searchParams.get('lang'));
+  } catch { /* ignore */ }
+  try { tries.push(localStorage.getItem(STORAGE_KEY)); } catch { /* ignore */ }
+  if (typeof document !== 'undefined') tries.push(document.documentElement.lang);
+  if (typeof navigator !== 'undefined') tries.push(navigator.language?.split('-')[0]);
+  for (const raw of tries) {
+    if (!raw) continue;
+    const code = raw.toLowerCase();
+    if (registry.has(code)) return code;
+  }
+  return DEFAULT_LANG;
+}
+
+/** Initialize the active language on boot. Idempotent. */
+export function initLang(): LangCode {
+  activeLang = detectLang();
+  return activeLang;
+}
+
+/**
+ * Translate a key with optional `${var}` interpolation. Falls back to the
+ * canonical English string if the active locale doesn't define the key,
+ * and to the raw key if even English is missing (which would be a bug).
+ *
+ *   t('status.errors', { count: 3, plural: 's' })  // "3 errors"
+ *
+ * Parameter values are inserted verbatim (no HTML escaping). Callers that
+ * inject results as innerHTML are responsible for escaping.
+ */
+export function t(key: TranslationKey, params?: Record<string, string | number>): string {
+  const dict = registry.get(activeLang) ?? {};
+  const raw = dict[key] ?? en[key] ?? key;
+  if (!params) return raw;
+  return raw.replace(/\$\{(\w+)\}/g, (whole, name: string) => {
+    const v = params[name];
+    // Leave `${unknown}` placeholders as-is so translation strings can
+    // legitimately contain literal `${vars}` text (e.g. json.desc).
+    return v === undefined || v === null ? whole : String(v);
+  });
+}
+
+/**
+ * Helper for English plural endings: `plural(n, 's')` -> '' or 's'.
+ * For locales with more complex rules (Russian: 0/1/few/many) use the
+ * dedicated helper below.
+ */
+export function plural(n: number, suffix = 's'): string {
+  return n === 1 ? '' : suffix;
+}
+
+/**
+ * Resolve a plural form per active locale. Forms are passed in the order:
+ *   [one, few, many]    (Russian needs all three)
+ *   [one, other]        (English-style, two forms)
+ *
+ * For English this collapses to [one, other]. Used by status.errors etc.
+ * where English picks 's' / '' but Russian wants 'а' / 'и' / '' style endings.
+ */
+export function pluralForm(n: number, forms: string[]): string {
+  if (activeLang === 'ru' && forms.length >= 3) {
+    const mod10 = n % 10;
+    const mod100 = n % 100;
+    if (mod10 === 1 && mod100 !== 11) return forms[0];
+    if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) return forms[1];
+    return forms[2];
+  }
+  return n === 1 ? forms[0] : forms[forms.length - 1];
+}
+
+/** Test-only seam to register an additional locale at runtime. */
+export function _registerForTests(code: LangCode, dict: LangDict): void {
+  registry.set(code, dict);
+}
+
+/** Test-only seam to reset the active lang to default. */
+export function _resetForTests(): void {
+  activeLang = DEFAULT_LANG;
+}
diff --git a/src/lib/playground/i18n/translations/en.ts b/src/lib/playground/i18n/translations/en.ts
new file mode 100644
index 0000000..e8a125f
--- /dev/null
+++ b/src/lib/playground/i18n/translations/en.ts
@@ -0,0 +1,131 @@
+/**
+ * Canonical English dictionary. Source of truth for translation keys -
+ * every other locale is `Partial<typeof en>` and falls back here on missing
+ * keys, so the UI is never empty even if a community translation drifts.
+ *
+ * Keys use dot-namespaces by feature area (tab.*, btn.*, tutorial.*, etc.).
+ * `${var}` placeholders are interpolated by `t(key, params)`.
+ */
+export const en = {
+  // Brand / shell
+  'brand.sub': 'Playground',
+
+  // Mode switch
+  'mode.editor': 'Editor',
+  'mode.tutorial': 'Tutorial',
+  'mode.aria': 'Playground mode',
+
+  // Theme + lang
+  'theme.toggle.aria': 'Toggle theme',
+  'lang.select.aria': 'Language',
+
+  // Tabs
+  'tab.errors': 'Errors',
+  'tab.warnings': 'Warnings',
+  'tab.json': 'Resolved JSON',
+  'tab.tutorial': 'Tutorial',
+
+  // Empty states
+  'empty.errors': 'No errors.',
+  'empty.warnings':
+    'No warnings. Warnings flag suspicious but valid configs (unknown keys, unresolved substitutions). They do not stop the menu from loading.',
+  'empty.json': 'Resolved JSON appears here once the parser is wired up.',
+  'empty.tutorial': 'Tutorial mode lands at M.6.',
+  'empty.history': 'No history yet.',
+
+  // Footer / status
+  'status.ready': 'ready',
+  'status.ok': 'ok',
+  'status.errors': '${count} error${plural}',
+  'status.warnings': '${count} warning${plural}',
+  'scope.hint.placeholder': '- keys -',
+  'scope.hint.title': 'Show suggestions for the current scope',
+  'scope.hint.body': '${scope} · ${count} key${plural} · ${shortcut}',
+
+  // Buttons
+  'btn.history': 'History',
+  'btn.format': 'Format',
+  'btn.format.title': 'Format (Cmd+Shift+F)',
+  'btn.share': 'Share',
+  'btn.copy': 'Copy',
+  'btn.reset': 'Reset',
+  'btn.reset.title': 'Reset the playground to the default template',
+  'confirm.reset.editor': 'Reset the playground to the default template? Your current edits will be lost.',
+  'confirm.reset.tutorial': 'Reset this lesson to its starter? Your progress on the lesson will be lost.',
+  'btn.warnings.on': 'warnings: on',
+  'btn.warnings.off': 'warnings: off',
+  'btn.warnings.title.on': 'Hide warning squiggles in the editor (Warnings tab stays)',
+  'btn.warnings.title.off': 'Show warning squiggles in the editor',
+
+  // Toasts
+  'toast.linkCopied': 'Link copied',
+  'toast.copyFailed': 'Copy failed',
+
+  // Resolved JSON description
+  'json.desc':
+    'How AbstractMenus sees your config after HOCON resolves substitutions, dotted keys, and overrides. Use this to verify that ${vars} expand correctly and that nested objects flatten the way you expect.',
+
+  // Tutorial
+  'tutorial.goalLabel': 'Goal: ',
+  'tutorial.passed': '✓ Goal reached',
+  'tutorial.btn.hint': 'Hint',
+  'tutorial.btn.reset': 'Reset',
+  'tutorial.btn.skip': 'Skip',
+  'tutorial.btn.next': 'Next',
+  'tutorial.btn.prev': 'Prev',
+  'tutorial.btn.allLessons': 'All lessons',
+  'tutorial.btn.allLessons.title': 'Open the lesson list',
+  'tutorial.counter': 'Lesson ${n} / ${total}',
+  'tutorial.popup.empty': 'No lessons.',
+  'tutorial.marker.completed': 'completed',
+  'tutorial.marker.skipped': 'skipped',
+  'tutorial.marker.current': 'current lesson',
+  'tutorial.done.title': '🎉 Course complete',
+  'tutorial.done.body': "You've finished every lesson. Try the editor mode now.",
+
+  // Topic / subtopic labels (one per shipped slug). Community contributors
+  // adding new topic slugs add a matching key here so the navigation popup
+  // shows a localized header instead of the raw slug.
+  'topic.basics': 'Basics',
+
+  // Diagnostic messages. Keys mirror DiagCode in hocon/types.ts. `${name}`
+  // placeholders are interpolated with the params the emitter passes.
+  // Identifier-like values (scope, kind) stay in English by design - they're
+  // technical tokens, like type names in TS errors.
+  'diag.parser.include-not-supported': 'include is not supported in playground',
+  'diag.parser.unexpected-token': 'Unexpected token `${text}`',
+  'diag.parser.expected-value-after-sep': 'Expected a value after `${sep}`',
+  'diag.parser.expected-key-separator': 'Expected `=`, `:`, or `{` after key',
+  'diag.parser.expected-closing-brace': 'Expected closing `}`',
+  'diag.parser.unexpected-after-array-element':
+    'Unexpected `${text}` after array element. Use `,` or newline between items, and wrap key/value pairs in `{ ... }`.',
+  'diag.parser.unexpected-in-array':
+    'Unexpected `${text}` in array. Expected a value or `{ ... }` object literal.',
+  'diag.parser.expected-closing-bracket': 'Expected closing `]`',
+
+  'diag.resolve.circular-substitution': 'Circular substitution `${ref}`',
+  'diag.resolve.unresolved-substitution': 'Unresolved substitution `${ref}`',
+
+  'diag.validate.unknown-key': 'Unknown key `${key}` in ${scope} scope',
+  'diag.validate.expected-list-of-objects': '`${parentKey}` expects a list of objects, found ${itemKind}',
+
+  // History
+  'history.empty': '(empty)',
+  'history.justNow': 'just now',
+  'history.minutes': '${n}m ago',
+  'history.hours': '${n}h ago',
+  'history.days': '${n}d ago',
+
+  // Page meta (only used if astro page is rendered server-side in this lang)
+  'page.title': 'HOCON Playground - AbstractMenus',
+  'page.description':
+    'Browser playground for AbstractMenus HOCON menu configs. Validate, share, learn.',
+} as const;
+
+/**
+ * `typeof en` infers literal types per value (e.g. 'Editor' instead of
+ * `string`), which would force every locale's value to equal the English
+ * string. Re-cast to a plain `Record<key, string>` for the public types.
+ */
+export type TranslationKey = keyof typeof en;
+export type Dict = Record<TranslationKey, string>;
diff --git a/src/lib/playground/i18n/translations/ru.ts b/src/lib/playground/i18n/translations/ru.ts
new file mode 100644
index 0000000..5d42cc6
--- /dev/null
+++ b/src/lib/playground/i18n/translations/ru.ts
@@ -0,0 +1,104 @@
+import type { Dict } from './en';
+
+/**
+ * Russian translation. Partial - any missing key falls back to the English
+ * canonical dict at runtime, so a community contributor shipping a half-done
+ * locale never blanks the UI.
+ */
+export const ru: Partial<Dict> = {
+  'brand.sub': 'Песочница',
+
+  'mode.editor': 'Редактор',
+  'mode.tutorial': 'Уроки',
+  'mode.aria': 'Режим песочницы',
+
+  'theme.toggle.aria': 'Переключить тему',
+  'lang.select.aria': 'Язык',
+
+  'tab.errors': 'Ошибки',
+  'tab.warnings': 'Предупреждения',
+  'tab.json': 'Результирующий JSON',
+  'tab.tutorial': 'Урок',
+
+  'empty.errors': 'Ошибок нет.',
+  'empty.warnings':
+    'Предупреждений нет. Они помечают подозрительные, но валидные конфиги (неизвестные ключи, неразрешённые подстановки) и не мешают меню загрузиться.',
+  'empty.json': 'Здесь появится результирующий JSON, как только парсер заработает.',
+  'empty.tutorial': 'Режим уроков появится в M.6.',
+  'empty.history': 'История пока пуста.',
+
+  'status.ready': 'готов',
+  'status.ok': 'ок',
+  'status.errors': '${count} ошибк${plural}',
+  'status.warnings': '${count} предупреждени${plural}',
+  'scope.hint.placeholder': '- ключи -',
+  'scope.hint.title': 'Показать подсказки для текущей области',
+  'scope.hint.body': '${scope} · ${count} ключ${plural} · ${shortcut}',
+
+  'btn.history': 'История',
+  'btn.format': 'Формат',
+  'btn.format.title': 'Форматировать (Cmd+Shift+F)',
+  'btn.share': 'Поделиться',
+  'btn.copy': 'Копировать',
+  'btn.reset': 'Сброс',
+  'btn.reset.title': 'Сбросить песочницу до шаблона по умолчанию',
+  'confirm.reset.editor': 'Сбросить песочницу до шаблона по умолчанию? Текущие правки будут потеряны.',
+  'confirm.reset.tutorial': 'Сбросить урок до стартового состояния? Прогресс по уроку будет потерян.',
+  'btn.warnings.on': 'предупреждения: вкл',
+  'btn.warnings.off': 'предупреждения: выкл',
+  'btn.warnings.title.on':
+    'Скрыть подчёркивание предупреждений в редакторе (вкладка остаётся)',
+  'btn.warnings.title.off': 'Показать подчёркивание предупреждений в редакторе',
+
+  'toast.linkCopied': 'Ссылка скопирована',
+  'toast.copyFailed': 'Не удалось скопировать',
+
+  'json.desc':
+    'Так AbstractMenus видит ваш конфиг после раскрытия подстановок, точечных ключей и наложений. Используйте, чтобы убедиться, что ${vars} разворачиваются правильно и вложенные объекты схлопываются как нужно.',
+
+  'tutorial.goalLabel': 'Цель: ',
+  'tutorial.passed': '✓ Цель достигнута',
+  'tutorial.btn.hint': 'Подсказка',
+  'tutorial.btn.reset': 'Сброс',
+  'tutorial.btn.skip': 'Пропустить',
+  'tutorial.btn.next': 'Дальше',
+  'tutorial.btn.prev': 'Назад',
+  'tutorial.btn.allLessons': 'Все уроки',
+  'tutorial.btn.allLessons.title': 'Открыть список уроков',
+  'tutorial.counter': 'Урок ${n} / ${total}',
+  'tutorial.popup.empty': 'Уроков нет.',
+  'tutorial.marker.completed': 'пройдено',
+  'tutorial.marker.skipped': 'пропущено',
+  'tutorial.marker.current': 'текущий урок',
+  'tutorial.done.title': '🎉 Курс пройден',
+  'tutorial.done.body': 'Вы прошли все уроки. Теперь попробуйте режим редактора.',
+
+  'topic.basics': 'Основы',
+
+  'diag.parser.include-not-supported': 'Директива include не поддерживается в песочнице',
+  'diag.parser.unexpected-token': 'Неожиданный токен `${text}`',
+  'diag.parser.expected-value-after-sep': 'Ожидалось значение после `${sep}`',
+  'diag.parser.expected-key-separator': 'Ожидался `=`, `:` или `{` после ключа',
+  'diag.parser.expected-closing-brace': 'Ожидалась закрывающая `}`',
+  'diag.parser.unexpected-after-array-element':
+    'Неожиданный `${text}` после элемента массива. Используйте `,` или перенос строки между элементами, а пары ключ/значение оборачивайте в `{ ... }`.',
+  'diag.parser.unexpected-in-array':
+    'Неожиданный `${text}` в массиве. Ожидалось значение или объект `{ ... }`.',
+  'diag.parser.expected-closing-bracket': 'Ожидалась закрывающая `]`',
+
+  'diag.resolve.circular-substitution': 'Циклическая подстановка `${ref}`',
+  'diag.resolve.unresolved-substitution': 'Неразрешённая подстановка `${ref}`',
+
+  'diag.validate.unknown-key': 'Неизвестный ключ `${key}` в области ${scope}',
+  'diag.validate.expected-list-of-objects': '`${parentKey}` ожидает список объектов, получено ${itemKind}',
+
+  'history.empty': '(пусто)',
+  'history.justNow': 'только что',
+  'history.minutes': '${n} мин назад',
+  'history.hours': '${n} ч назад',
+  'history.days': '${n} дн назад',
+
+  'page.title': 'HOCON Песочница - AbstractMenus',
+  'page.description':
+    'Браузерная песочница для HOCON-конфигов меню AbstractMenus. Валидируйте, делитесь, учитесь.',
+};
diff --git a/src/lib/playground/main.ts b/src/lib/playground/main.ts
new file mode 100644
index 0000000..c91bb86
--- /dev/null
+++ b/src/lib/playground/main.ts
@@ -0,0 +1,14 @@
+import { PlaygroundApp } from './PlaygroundApp';
+
+export function boot(): void {
+  const root = document.querySelector<HTMLElement>('[data-pg-root]');
+  if (!root) {
+    console.warn('[playground] root not found');
+    return;
+  }
+  try {
+    new PlaygroundApp(root).start();
+  } catch (e) {
+    console.error('[playground] failed to start', e);
+  }
+}
diff --git a/src/lib/playground/sharing/history.test.ts b/src/lib/playground/sharing/history.test.ts
new file mode 100644
index 0000000..1d1dee7
--- /dev/null
+++ b/src/lib/playground/sharing/history.test.ts
@@ -0,0 +1,51 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { loadHistory, pushSnapshot, MAX_HISTORY_SIZE } from './history';
+
+describe('history', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  test('empty by default', () => {
+    expect(loadHistory()).toEqual([]);
+  });
+
+  test('push adds entry to front', () => {
+    pushSnapshot('foo');
+    const h = loadHistory();
+    expect(h).toHaveLength(1);
+    expect(h[0].content).toBe('foo');
+    expect(typeof h[0].ts).toBe('number');
+  });
+
+  test('FIFO: caps at MAX_HISTORY_SIZE', () => {
+    for (let i = 0; i < MAX_HISTORY_SIZE + 3; i++) {
+      pushSnapshot(`v${i}-` + 'x'.repeat(60));
+    }
+    const h = loadHistory();
+    expect(h).toHaveLength(MAX_HISTORY_SIZE);
+    expect(h[0].content).toContain(`v${MAX_HISTORY_SIZE + 2}`);
+  });
+
+  test('skips push when identical to previous snapshot', () => {
+    pushSnapshot('foo');
+    pushSnapshot('foo');
+    expect(loadHistory()).toHaveLength(1);
+  });
+
+  test('different content of same length still pushed', () => {
+    pushSnapshot('aaaa');
+    pushSnapshot('bbbb');
+    expect(loadHistory()).toHaveLength(2);
+  });
+
+  test('preview is first 60 chars of first non-empty line', () => {
+    pushSnapshot('first line\nsecond line\nthird');
+    expect(loadHistory()[0].preview.length).toBeLessThanOrEqual(60);
+  });
+
+  test('skips empty content', () => {
+    pushSnapshot('');
+    expect(loadHistory()).toEqual([]);
+  });
+});
diff --git a/src/lib/playground/sharing/history.ts b/src/lib/playground/sharing/history.ts
new file mode 100644
index 0000000..0e6e015
--- /dev/null
+++ b/src/lib/playground/sharing/history.ts
@@ -0,0 +1,50 @@
+const KEY = 'am_playground_history';
+export const MAX_HISTORY_SIZE = 5;
+const PREVIEW_LEN = 60;
+
+export interface HistoryEntry {
+  ts: number;
+  content: string;
+  preview: string;
+}
+
+export function loadHistory(): HistoryEntry[] {
+  try {
+    const raw = localStorage.getItem(KEY);
+    if (!raw) return [];
+    const parsed: unknown = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter(isEntry) : [];
+  } catch {
+    return [];
+  }
+}
+
+function isEntry(x: unknown): x is HistoryEntry {
+  return typeof x === 'object' && x !== null && 'ts' in x && 'content' in x;
+}
+
+export function pushSnapshot(content: string): void {
+  if (!content) return;
+  const list = loadHistory();
+  const prev = list[0];
+  if (prev && prev.content === content) return;
+  const entry: HistoryEntry = {
+    ts: Date.now(),
+    content,
+    preview: makePreview(content),
+  };
+  const next = [entry, ...list].slice(0, MAX_HISTORY_SIZE);
+  try {
+    localStorage.setItem(KEY, JSON.stringify(next));
+  } catch {
+    // quota / private mode - ignore
+  }
+}
+
+function makePreview(content: string): string {
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed) return trimmed.slice(0, PREVIEW_LEN);
+  }
+  return '';
+}
diff --git a/src/lib/playground/sharing/share-url.test.ts b/src/lib/playground/sharing/share-url.test.ts
new file mode 100644
index 0000000..2d69da6
--- /dev/null
+++ b/src/lib/playground/sharing/share-url.test.ts
@@ -0,0 +1,35 @@
+import { describe, test, expect } from 'vitest';
+import { encodeShare, decodeShare } from './share-url';
+
+describe('share-url round-trip', () => {
+  test('empty string', () => {
+    const enc = encodeShare('');
+    expect(decodeShare(enc)).toBe('');
+  });
+
+  test('simple ASCII', () => {
+    const text = 'title = "Hello"';
+    expect(decodeShare(encodeShare(text))).toBe(text);
+  });
+
+  test('multi-byte (Russian)', () => {
+    const text = 'title = "Привет мир"';
+    expect(decodeShare(encodeShare(text))).toBe(text);
+  });
+
+  test('large config compresses smaller than raw', () => {
+    const text = ('item = { material = STONE }\n').repeat(200);
+    const enc = encodeShare(text);
+    expect(decodeShare(enc)).toBe(text);
+    expect(enc.length).toBeLessThan(text.length);
+  });
+
+  test('encoded uses URL-safe alphabet only', () => {
+    const enc = encodeShare('a = 1\nb = 2');
+    expect(/[+/=]/.test(enc)).toBe(false);
+  });
+
+  test('decode returns null on garbage', () => {
+    expect(decodeShare('not-base64!!!')).toBeNull();
+  });
+});
diff --git a/src/lib/playground/sharing/share-url.ts b/src/lib/playground/sharing/share-url.ts
new file mode 100644
index 0000000..d46941b
--- /dev/null
+++ b/src/lib/playground/sharing/share-url.ts
@@ -0,0 +1,32 @@
+import { deflate, inflate } from 'pako';
+
+export function encodeShare(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  const deflated = deflate(bytes);
+  return urlSafeBase64Encode(deflated);
+}
+
+export function decodeShare(encoded: string): string | null {
+  try {
+    const bytes = urlSafeBase64Decode(encoded);
+    const inflated = inflate(bytes);
+    return new TextDecoder().decode(inflated);
+  } catch {
+    return null;
+  }
+}
+
+function urlSafeBase64Encode(bytes: Uint8Array): string {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  const b64 = btoa(bin);
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '~');
+}
+
+function urlSafeBase64Decode(s: string): Uint8Array {
+  const b64 = s.replace(/-/g, '+').replace(/_/g, '/').replace(/~/g, '=');
+  const bin = atob(b64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+}
diff --git a/src/lib/playground/tutorial/engine.test.ts b/src/lib/playground/tutorial/engine.test.ts
new file mode 100644
index 0000000..6383de0
--- /dev/null
+++ b/src/lib/playground/tutorial/engine.test.ts
@@ -0,0 +1,197 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { runCheck, loadProgress, saveProgress, markCompleted, markSkipped, bumpHint, EMPTY_PROGRESS, getByPath } from './engine';
+
+describe('runCheck', () => {
+  test('regex check passes', () => {
+    expect(runCheck('hello world', { type: 'regex', pattern: 'world' })).toBe(true);
+  });
+
+  test('regex check fails', () => {
+    expect(runCheck('hello', { type: 'regex', pattern: 'nope' })).toBe(false);
+  });
+
+  test('regex with flags', () => {
+    expect(runCheck('FOO', { type: 'regex', pattern: 'foo', flags: 'i' })).toBe(true);
+  });
+
+  test('multiline regex with m flag', () => {
+    const text = 'line1\n# comment\nline3';
+    expect(runCheck(text, { type: 'regex', pattern: '^#', flags: 'm' })).toBe(true);
+  });
+
+  test('invalid regex returns false (does not throw)', () => {
+    expect(runCheck('x', { type: 'regex', pattern: '(' })).toBe(false);
+  });
+});
+
+describe('runCheck shape', () => {
+  test('has - top-level key present', () => {
+    const ok = runCheck('title = "x"', {
+      type: 'shape',
+      asserts: [{ kind: 'has', path: 'title' }],
+    });
+    expect(ok).toBe(true);
+  });
+
+  test('has - missing key', () => {
+    const ok = runCheck('size = 3', {
+      type: 'shape',
+      asserts: [{ kind: 'has', path: 'title' }],
+    });
+    expect(ok).toBe(false);
+  });
+
+  test('eq - string value', () => {
+    const ok = runCheck('title = "Shop"', {
+      type: 'shape',
+      asserts: [{ kind: 'eq', path: 'title', value: 'Shop' }],
+    });
+    expect(ok).toBe(true);
+  });
+
+  test('eq - number value', () => {
+    const ok = runCheck('size = 6', {
+      type: 'shape',
+      asserts: [{ kind: 'eq', path: 'size', value: 6 }],
+    });
+    expect(ok).toBe(true);
+  });
+
+  test('matches - regex against string at path', () => {
+    const ok = runCheck('title = "Hello world"', {
+      type: 'shape',
+      asserts: [{ kind: 'matches', path: 'title', pattern: '^Hello' }],
+    });
+    expect(ok).toBe(true);
+  });
+
+  test('matches against non-string returns false', () => {
+    const ok = runCheck('size = 3', {
+      type: 'shape',
+      asserts: [{ kind: 'matches', path: 'size', pattern: '\\d' }],
+    });
+    expect(ok).toBe(false);
+  });
+
+  test('nested object path', () => {
+    const txt = 'enchantments { SHARPNESS = 5 }';
+    const ok = runCheck(txt, {
+      type: 'shape',
+      asserts: [{ kind: 'eq', path: 'enchantments.SHARPNESS', value: 5 }],
+    });
+    expect(ok).toBe(true);
+  });
+
+  test('array index path', () => {
+    const txt = 'items = [{ slot = 0, material = STONE }]';
+    const ok = runCheck(txt, {
+      type: 'shape',
+      asserts: [
+        { kind: 'eq', path: 'items[0].slot', value: 0 },
+        { kind: 'eq', path: 'items[0].material', value: 'STONE' },
+      ],
+    });
+    expect(ok).toBe(true);
+  });
+
+  test('all asserts must pass (and-semantics)', () => {
+    const txt = 'title = "x"';
+    const ok = runCheck(txt, {
+      type: 'shape',
+      asserts: [
+        { kind: 'has', path: 'title' },
+        { kind: 'has', path: 'size' },
+      ],
+    });
+    expect(ok).toBe(false);
+  });
+
+  test('substitution-resolved value satisfies assert', () => {
+    const txt = 'prefix = "[Shop]"\nname = ${prefix}';
+    const ok = runCheck(txt, {
+      type: 'shape',
+      asserts: [{ kind: 'eq', path: 'name', value: '[Shop]' }],
+    });
+    expect(ok).toBe(true);
+  });
+
+  test('shape with malformed input returns false (does not throw)', () => {
+    const ok = runCheck('totally broken {{{', {
+      type: 'shape',
+      asserts: [{ kind: 'has', path: 'title' }],
+    });
+    expect(ok).toBe(false);
+  });
+});
+
+describe('getByPath', () => {
+  const root = {
+    title: 'x',
+    size: 3,
+    items: [
+      { slot: 0, material: 'STONE' },
+      { slot: 4, material: 'DIAMOND' },
+    ],
+    nested: { a: { b: { c: 42 } } },
+  };
+
+  test('returns root for empty path', () => {
+    expect(getByPath(root, '')).toBe(root);
+  });
+
+  test('top-level key', () => {
+    expect(getByPath(root, 'size')).toBe(3);
+  });
+
+  test('nested object', () => {
+    expect(getByPath(root, 'nested.a.b.c')).toBe(42);
+  });
+
+  test('array index', () => {
+    expect(getByPath(root, 'items[1].material')).toBe('DIAMOND');
+  });
+
+  test('missing key returns undefined', () => {
+    expect(getByPath(root, 'missing')).toBeUndefined();
+  });
+
+  test('dive into primitive returns undefined', () => {
+    expect(getByPath(root, 'size.foo')).toBeUndefined();
+  });
+
+  test('non-numeric array index returns undefined', () => {
+    expect(getByPath(root, 'items[abc]')).toBeUndefined();
+  });
+});
+
+describe('progress storage', () => {
+  beforeEach(() => localStorage.clear());
+
+  test('empty by default', () => {
+    expect(loadProgress()).toEqual(EMPTY_PROGRESS);
+  });
+
+  test('saveProgress round-trip', () => {
+    const p = { current: 'l1', completed: ['l0'], skipped: [], hintsUsed: { l1: 2 } };
+    saveProgress(p);
+    expect(loadProgress()).toEqual(p);
+  });
+
+  test('markCompleted adds id and dedupes', () => {
+    const p = markCompleted(EMPTY_PROGRESS, 'l0');
+    expect(p.completed).toEqual(['l0']);
+    const p2 = markCompleted(p, 'l0');
+    expect(p2.completed).toEqual(['l0']);
+  });
+
+  test('markSkipped adds id', () => {
+    const p = markSkipped(EMPTY_PROGRESS, 'l5');
+    expect(p.skipped).toEqual(['l5']);
+  });
+
+  test('bumpHint increments count', () => {
+    const p1 = bumpHint(EMPTY_PROGRESS, 'l0');
+    const p2 = bumpHint(p1, 'l0');
+    expect(p2.hintsUsed.l0).toBe(2);
+  });
+});
diff --git a/src/lib/playground/tutorial/engine.ts b/src/lib/playground/tutorial/engine.ts
new file mode 100644
index 0000000..0322b0d
--- /dev/null
+++ b/src/lib/playground/tutorial/engine.ts
@@ -0,0 +1,152 @@
+import type { CheckSpec, Progress, ShapeAssert } from './types';
+import { EMPTY_PROGRESS } from './types';
+import { tokenizeText } from '../hocon/tokenize';
+import { parse } from '../hocon/parser';
+import { resolve } from '../hocon/resolve';
+
+export { EMPTY_PROGRESS } from './types';
+
+const KEY = 'am_playground_progress';
+
+export function runCheck(text: string, check: CheckSpec): boolean {
+  if (check.type === 'regex') {
+    try {
+      const re = new RegExp(check.pattern, check.flags ?? '');
+      return re.test(text);
+    } catch {
+      return false;
+    }
+  }
+  if (check.type === 'shape') {
+    let resolved: unknown;
+    try {
+      const parsed = parse(tokenizeText(text));
+      // A parse error doesn't fail the check immediately - the resolver is
+      // best-effort and the user might still satisfy the shape with the
+      // partial AST. But if the resolved value isn't a plain object/array,
+      // there's nothing to walk.
+      resolved = resolve(parsed.ast).resolved;
+    } catch {
+      return false;
+    }
+    return check.asserts.every((a) => evalAssert(resolved, a));
+  }
+  return false;
+}
+
+function evalAssert(root: unknown, a: ShapeAssert): boolean {
+  const v = getByPath(root, a.path);
+  if (a.kind === 'has') return v !== undefined;
+  if (a.kind === 'eq') return deepEqual(v, a.value);
+  if (a.kind === 'matches') {
+    if (typeof v !== 'string') return false;
+    try {
+      return new RegExp(a.pattern, a.flags ?? '').test(v);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/**
+ * Resolve a dotted/bracket path against a value tree.
+ *   "items[0].click.message" -> root.items[0].click.message
+ * Numeric segments inside `[]` index into arrays; bare identifiers are
+ * object keys. Returns `undefined` for any miss along the way.
+ */
+export function getByPath(root: unknown, path: string): unknown {
+  if (!path) return root;
+  // Split on `.` and `[` to get tokens; strip trailing `]` from bracket parts.
+  const parts: string[] = [];
+  let buf = '';
+  let inBracket = false;
+  for (const ch of path) {
+    if (ch === '.' && !inBracket) {
+      if (buf) { parts.push(buf); buf = ''; }
+    } else if (ch === '[') {
+      if (buf) { parts.push(buf); buf = ''; }
+      inBracket = true;
+    } else if (ch === ']') {
+      if (buf) { parts.push(buf); buf = ''; }
+      inBracket = false;
+    } else {
+      buf += ch;
+    }
+  }
+  if (buf) parts.push(buf);
+
+  let cur: unknown = root;
+  for (const p of parts) {
+    if (cur === null || cur === undefined) return undefined;
+    if (Array.isArray(cur)) {
+      const idx = Number(p);
+      if (!Number.isInteger(idx)) return undefined;
+      cur = cur[idx];
+    } else if (typeof cur === 'object') {
+      cur = (cur as Record<string, unknown>)[p];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== typeof b) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a === 'object') {
+    const ao = a as Record<string, unknown>;
+    const bo = b as Record<string, unknown>;
+    const ak = Object.keys(ao);
+    const bk = Object.keys(bo);
+    if (ak.length !== bk.length) return false;
+    return ak.every((k) => deepEqual(ao[k], bo[k]));
+  }
+  return false;
+}
+
+export function loadProgress(): Progress {
+  try {
+    const raw = localStorage.getItem(KEY);
+    if (!raw) return { ...EMPTY_PROGRESS };
+    const parsed: unknown = JSON.parse(raw);
+    if (!isProgress(parsed)) return { ...EMPTY_PROGRESS };
+    return parsed;
+  } catch {
+    return { ...EMPTY_PROGRESS };
+  }
+}
+
+export function saveProgress(p: Progress): void {
+  try {
+    localStorage.setItem(KEY, JSON.stringify(p));
+  } catch {
+    // ignore quota / private mode
+  }
+}
+
+function isProgress(x: unknown): x is Progress {
+  return typeof x === 'object' && x !== null
+    && 'completed' in x && Array.isArray((x as Progress).completed)
+    && 'hintsUsed' in x;
+}
+
+export function markCompleted(p: Progress, id: string): Progress {
+  if (p.completed.includes(id)) return p;
+  return { ...p, completed: [...p.completed, id] };
+}
+
+export function markSkipped(p: Progress, id: string): Progress {
+  if (p.skipped.includes(id)) return p;
+  return { ...p, skipped: [...p.skipped, id] };
+}
+
+export function bumpHint(p: Progress, id: string): Progress {
+  const used = p.hintsUsed[id] ?? 0;
+  return { ...p, hintsUsed: { ...p.hintsUsed, [id]: used + 1 } };
+}
diff --git a/src/lib/playground/tutorial/highlight-hocon.test.ts b/src/lib/playground/tutorial/highlight-hocon.test.ts
new file mode 100644
index 0000000..20d4119
--- /dev/null
+++ b/src/lib/playground/tutorial/highlight-hocon.test.ts
@@ -0,0 +1,32 @@
+import { describe, test, expect } from 'vitest';
+import { highlightHocon } from './highlight-hocon';
+
+describe('highlightHocon', () => {
+  test('wraps each token in a class span', () => {
+    const out = highlightHocon('title = "x"');
+    expect(out).toContain('cm-tk-key');
+    expect(out).toContain('cm-tk-operator');
+    expect(out).toContain('cm-tk-string');
+  });
+
+  test('preserves newlines between lines', () => {
+    const out = highlightHocon('a = 1\nb = 2');
+    expect(out).toMatch(/\n/);
+  });
+
+  test('escapes HTML in token text', () => {
+    const out = highlightHocon('title = "<script>"');
+    expect(out).toContain('&lt;script&gt;');
+    expect(out).not.toContain('<script>');
+  });
+
+  test('comments get their own class', () => {
+    const out = highlightHocon('# hello\nsize = 3');
+    expect(out).toContain('cm-tk-comment');
+  });
+
+  test('substitutions get their own class', () => {
+    const out = highlightHocon('name = ${prefix}');
+    expect(out).toContain('cm-tk-substitution');
+  });
+});
diff --git a/src/lib/playground/tutorial/highlight-hocon.ts b/src/lib/playground/tutorial/highlight-hocon.ts
new file mode 100644
index 0000000..5e7c878
--- /dev/null
+++ b/src/lib/playground/tutorial/highlight-hocon.ts
@@ -0,0 +1,35 @@
+import { tokenizeLine, createState } from '../cm/hocon-tokenizer';
+
+/**
+ * Render a HOCON snippet as syntax-highlighted HTML using the same token
+ * classes the editor uses (`cm-tk-comment`, `cm-tk-string`, etc.). Output
+ * goes inside a `<pre><code>` produced by the markdown renderer; CSS in
+ * playground.css scopes the colours for `.pg-tutorial pre`.
+ *
+ * Always HTML-escapes; safe to drop into innerHTML.
+ */
+export function highlightHocon(code: string): string {
+  const lines = code.split('\n');
+  const state = createState();
+  const out: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const tokens = tokenizeLine(lines[i], state);
+    for (const t of tokens) {
+      const escaped = escapeHtml(t.text);
+      if (t.token === null) {
+        out.push(escaped);
+      } else {
+        out.push(`<span class="cm-tk-${t.token}">${escaped}</span>`);
+      }
+    }
+    if (i < lines.length - 1) out.push('\n');
+  }
+  return out.join('');
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
diff --git a/src/lib/playground/tutorial/lessons.test.ts b/src/lib/playground/tutorial/lessons.test.ts
new file mode 100644
index 0000000..c9fc75d
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons.test.ts
@@ -0,0 +1,254 @@
+import { describe, test, expect } from 'vitest';
+import {
+  listLessons,
+  getLesson,
+  firstLessonId,
+  validateLesson,
+  applyTranslation,
+  groupLessons,
+  prevLessonId,
+  lessonPosition,
+  lessonCount,
+} from './lessons';
+import { runCheck } from './engine';
+import type { Lesson } from './types';
+
+describe('lessons loader', () => {
+  test('finds at least 2 lessons', () => {
+    expect(listLessons().length).toBeGreaterThanOrEqual(2);
+  });
+
+  test('lessons are sorted by id', () => {
+    const ids = listLessons().map((l) => l.id);
+    const sorted = [...ids].sort();
+    expect(ids).toEqual(sorted);
+  });
+
+  test('01-introduction is first', () => {
+    expect(firstLessonId()).toBe('01-introduction');
+  });
+
+  test('getLesson returns matching lesson', () => {
+    expect(getLesson('01-introduction')?.title).toBe('Introduction');
+  });
+
+  test('getLesson returns undefined for unknown id', () => {
+    expect(getLesson('999-nope')).toBeUndefined();
+  });
+});
+
+describe('validateLesson', () => {
+  const valid = {
+    id: 'x',
+    title: 'X',
+    topic: 'basics',
+    intro: 'i',
+    starter: 's',
+    goal: 'g',
+    hints: ['a', 'b'],
+    check: { type: 'regex', pattern: 'foo' },
+  };
+
+  test('valid lesson passes', () => {
+    const r = validateLesson(valid);
+    expect(r.ok).toBe(true);
+  });
+
+  test('missing field fails', () => {
+    const { id, ...rest } = valid;
+    void id;
+    expect(validateLesson(rest).ok).toBe(false);
+  });
+
+  test('unknown check.type fails', () => {
+    const r = validateLesson({ ...valid, check: { type: 'ast', pattern: 'x' } });
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toMatch(/regex/);
+  });
+
+  test('invalid regex pattern fails', () => {
+    const r = validateLesson({ ...valid, check: { type: 'regex', pattern: '(' } });
+    expect(r.ok).toBe(false);
+  });
+
+  test('null next is allowed (terminal lesson)', () => {
+    expect(validateLesson({ ...valid, next: null }).ok).toBe(true);
+  });
+
+  test('numeric next is rejected', () => {
+    expect(validateLesson({ ...valid, next: 5 }).ok).toBe(false);
+  });
+
+  test('hints must be string[]', () => {
+    expect(validateLesson({ ...valid, hints: ['ok', 7] }).ok).toBe(false);
+  });
+
+  test('translations object is allowed', () => {
+    const r = validateLesson({
+      ...valid,
+      translations: { ru: { title: 'X-ru', hints: ['a-ru'] } },
+    });
+    expect(r.ok).toBe(true);
+  });
+
+  test('translations as array is rejected', () => {
+    expect(validateLesson({ ...valid, translations: [] }).ok).toBe(false);
+  });
+
+  test('translations.<lang>.title non-string is rejected', () => {
+    expect(validateLesson({ ...valid, translations: { ru: { title: 5 } } }).ok).toBe(false);
+  });
+
+  test('translations.<lang>.hints non-string[] is rejected', () => {
+    expect(validateLesson({ ...valid, translations: { ru: { hints: [1] } } }).ok).toBe(false);
+  });
+
+  test('missing topic is rejected', () => {
+    const { topic, ...rest } = valid;
+    void topic;
+    expect(validateLesson(rest).ok).toBe(false);
+  });
+
+  test('empty topic is rejected', () => {
+    expect(validateLesson({ ...valid, topic: '' }).ok).toBe(false);
+  });
+
+  test('subtopic when present must be non-empty string', () => {
+    expect(validateLesson({ ...valid, subtopic: 'syntax' }).ok).toBe(true);
+    expect(validateLesson({ ...valid, subtopic: '' }).ok).toBe(false);
+    expect(validateLesson({ ...valid, subtopic: 5 }).ok).toBe(false);
+  });
+
+  test('shape check is accepted', () => {
+    const r = validateLesson({
+      ...valid,
+      check: { type: 'shape', asserts: [{ kind: 'has', path: 'title' }] },
+    });
+    expect(r.ok).toBe(true);
+  });
+
+  test('shape check requires asserts array', () => {
+    expect(validateLesson({
+      ...valid,
+      check: { type: 'shape', asserts: 'nope' },
+    }).ok).toBe(false);
+  });
+
+  test('shape check rejects unknown assert kind', () => {
+    expect(validateLesson({
+      ...valid,
+      check: { type: 'shape', asserts: [{ kind: 'whatever', path: 'x' }] },
+    }).ok).toBe(false);
+  });
+
+  test('shape eq requires value field', () => {
+    expect(validateLesson({
+      ...valid,
+      check: { type: 'shape', asserts: [{ kind: 'eq', path: 'x' }] },
+    }).ok).toBe(false);
+  });
+
+  test('shape matches validates pattern as regex', () => {
+    expect(validateLesson({
+      ...valid,
+      check: { type: 'shape', asserts: [{ kind: 'matches', path: 'x', pattern: '(' }] },
+    }).ok).toBe(false);
+  });
+
+  test('unknown check.type rejected', () => {
+    expect(validateLesson({
+      ...valid,
+      check: { type: 'whatever' },
+    }).ok).toBe(false);
+  });
+});
+
+describe('groupLessons / position helpers', () => {
+  const lessons: Lesson[] = [
+    { id: 'a', title: 'A', topic: 'basics', intro: '', starter: '', goal: '', hints: [], check: { type: 'regex', pattern: 'x' } },
+    { id: 'b', title: 'B', topic: 'basics', subtopic: 'syntax', intro: '', starter: '', goal: '', hints: [], check: { type: 'regex', pattern: 'x' } },
+    { id: 'c', title: 'C', topic: 'advanced', intro: '', starter: '', goal: '', hints: [], check: { type: 'regex', pattern: 'x' } },
+    { id: 'd', title: 'D', topic: 'basics', subtopic: 'syntax', intro: '', starter: '', goal: '', hints: [], check: { type: 'regex', pattern: 'x' } },
+  ];
+
+  test('groups by topic preserving first-seen order', () => {
+    const groups = groupLessons(lessons);
+    expect(groups.map((g) => g.topic)).toEqual(['basics', 'advanced']);
+  });
+
+  test('groups subtopics within a topic, anonymous bucket goes first', () => {
+    const groups = groupLessons(lessons);
+    const basics = groups.find((g) => g.topic === 'basics')!;
+    expect(basics.subtopics.map((s) => s.subtopic)).toEqual([null, 'syntax']);
+    expect(basics.subtopics[0].lessons.map((l) => l.id)).toEqual(['a']);
+    expect(basics.subtopics[1].lessons.map((l) => l.id)).toEqual(['b', 'd']);
+  });
+
+  test('lessonPosition is 1-based, 0 for unknown', () => {
+    expect(lessonPosition('01-introduction')).toBe(1);
+    expect(lessonPosition('02-comments')).toBe(2);
+    expect(lessonPosition('999-nope')).toBe(0);
+  });
+
+  test('lessonCount matches shipped count', () => {
+    expect(lessonCount()).toBe(listLessons().length);
+  });
+
+  test('prevLessonId returns previous or null at the boundary', () => {
+    expect(prevLessonId('01-introduction')).toBeNull();
+    expect(prevLessonId('02-comments')).toBe('01-introduction');
+    expect(prevLessonId('999-nope')).toBeNull();
+  });
+});
+
+describe('applyTranslation', () => {
+  const base: Lesson = {
+    id: 'demo',
+    title: 'Title',
+    topic: 'basics',
+    intro: 'Intro',
+    starter: 'starter',
+    goal: 'Goal',
+    hints: ['h1', 'h2'],
+    check: { type: 'regex', pattern: 'x' },
+    translations: {
+      ru: { title: 'Заголовок', goal: 'Цель' },
+    },
+  };
+
+  test('overlays known fields, keeps the rest from base', () => {
+    const r = applyTranslation(base, 'ru');
+    expect(r.title).toBe('Заголовок');
+    expect(r.goal).toBe('Цель');
+    expect(r.intro).toBe('Intro');     // not translated -> base
+    expect(r.hints).toEqual(['h1', 'h2']);
+    expect(r.starter).toBe('starter'); // never translated
+  });
+
+  test('returns base when no translation exists', () => {
+    const r = applyTranslation(base, 'de');
+    expect(r).toBe(base);
+  });
+
+  test('returns base when lesson has no translations field', () => {
+    const noTr: Lesson = { ...base, translations: undefined };
+    expect(applyTranslation(noTr, 'ru')).toBe(noTr);
+  });
+});
+
+describe('shipped lessons sanity', () => {
+  test('every shipped lesson has a usable starter and check', () => {
+    for (const lesson of listLessons()) {
+      expect(typeof runCheck(lesson.starter, lesson.check)).toBe('boolean');
+    }
+  });
+
+  test('next references either exist or are null', () => {
+    const ids = new Set(listLessons().map((l) => l.id));
+    for (const lesson of listLessons()) {
+      if (lesson.next != null) {
+        expect(ids.has(lesson.next)).toBe(true);
+      }
+    }
+  });
+});
diff --git a/src/lib/playground/tutorial/lessons.ts b/src/lib/playground/tutorial/lessons.ts
new file mode 100644
index 0000000..f7b94b6
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons.ts
@@ -0,0 +1,197 @@
+import type { Lesson } from './types';
+import { getLang } from '../i18n';
+
+const lessonModules = import.meta.glob<unknown>('./lessons/*.json', {
+  import: 'default',
+  eager: true,
+});
+
+const ALL: Lesson[] = Object.entries(lessonModules)
+  .sort(([a], [b]) => a.localeCompare(b))
+  .flatMap(([path, raw]) => {
+    const v = validateLesson(raw, path);
+    if (!v.ok) {
+      console.warn(`[playground] skipping malformed lesson ${path}: ${v.error}`);
+      return [];
+    }
+    return [v.lesson];
+  });
+
+export function listLessons(): Lesson[] {
+  const lang = getLang();
+  return ALL.map((l) => applyTranslation(l, lang));
+}
+
+export function getLesson(id: string): Lesson | undefined {
+  const base = ALL.find((l) => l.id === id);
+  return base ? applyTranslation(base, getLang()) : undefined;
+}
+
+export function firstLessonId(): string {
+  return ALL[0]?.id ?? '';
+}
+
+/**
+ * Overlay a per-locale translation onto a lesson. Missing fields fall back
+ * to the canonical (typically English) lesson, so partial translations are
+ * fine. Returns the original lesson when no translation exists for the
+ * active language.
+ */
+export function applyTranslation(lesson: Lesson, lang: string): Lesson {
+  const tr = lesson.translations?.[lang];
+  if (!tr) return lesson;
+  return {
+    ...lesson,
+    title: tr.title ?? lesson.title,
+    intro: tr.intro ?? lesson.intro,
+    goal: tr.goal ?? lesson.goal,
+    hints: tr.hints ?? lesson.hints,
+  };
+}
+
+export interface SubtopicGroup {
+  /** null when the parent topic has lessons without a subtopic. */
+  subtopic: string | null;
+  lessons: Lesson[];
+}
+
+export interface TopicGroup {
+  topic: string;
+  subtopics: SubtopicGroup[];
+}
+
+/**
+ * Group a flat lesson list into Topic -> Subtopic -> [Lesson] for rendering
+ * the navigation popup. Topic order follows the first occurrence of each
+ * topic in the input (which is sorted by id), so `00-introduction` belongs
+ * under whatever its topic is and that topic appears first.
+ *
+ * Lessons without a subtopic are collected into a single anonymous bucket
+ * (`subtopic: null`) at the top of their topic.
+ */
+export function groupLessons(lessons: Lesson[]): TopicGroup[] {
+  const topics = new Map<string, Map<string | null, Lesson[]>>();
+  for (const l of lessons) {
+    const t = topics.get(l.topic) ?? new Map<string | null, Lesson[]>();
+    if (!topics.has(l.topic)) topics.set(l.topic, t);
+    const sub = l.subtopic ?? null;
+    const bucket = t.get(sub) ?? [];
+    if (!t.has(sub)) t.set(sub, bucket);
+    bucket.push(l);
+  }
+  return Array.from(topics.entries()).map(([topic, subMap]) => ({
+    topic,
+    subtopics: Array.from(subMap.entries()).map(([subtopic, ls]) => ({ subtopic, lessons: ls })),
+  }));
+}
+
+/** 1-based position of `id` in the global lesson order. 0 if not found. */
+export function lessonPosition(id: string): number {
+  const lessons = listLessons();
+  return lessons.findIndex((l) => l.id === id) + 1;
+}
+
+/** Total lesson count (post-translation, but count is locale-invariant). */
+export function lessonCount(): number {
+  return ALL.length;
+}
+
+/**
+ * Returns the previous lesson id by global order, or null if `id` is the
+ * first lesson (or unknown). Mirrors the implicit "next via order" used by
+ * advanceAfter() in the controller.
+ */
+export function prevLessonId(id: string): string | null {
+  const lessons = listLessons();
+  const idx = lessons.findIndex((l) => l.id === id);
+  if (idx <= 0) return null;
+  return lessons[idx - 1].id;
+}
+
+type Validation = { ok: true; lesson: Lesson } | { ok: false; error: string };
+
+/**
+ * Strict structural check. Bad lessons are dropped at load time so a typo
+ * in one JSON can't crash the tutorial mid-course. Build-time test exercises
+ * every shipped lesson through this same function.
+ */
+export function validateLesson(raw: unknown, source = '<inline>'): Validation {
+  if (!raw || typeof raw !== 'object') return fail('lesson is not an object');
+  const r = raw as Record<string, unknown>;
+  if (typeof r.id !== 'string' || !r.id) return fail('missing string field `id`');
+  if (typeof r.title !== 'string' || !r.title) return fail('missing string field `title`');
+  if (typeof r.topic !== 'string' || !r.topic) return fail('missing string field `topic`');
+  if (r.subtopic !== undefined && (typeof r.subtopic !== 'string' || !r.subtopic)) {
+    return fail('`subtopic` must be a non-empty string when present');
+  }
+  if (typeof r.intro !== 'string') return fail('missing string field `intro`');
+  if (typeof r.starter !== 'string') return fail('missing string field `starter`');
+  if (typeof r.goal !== 'string') return fail('missing string field `goal`');
+  if (!Array.isArray(r.hints) || r.hints.some((h) => typeof h !== 'string')) {
+    return fail('`hints` must be string[]');
+  }
+  const c = r.check;
+  if (!c || typeof c !== 'object') return fail('missing `check` object');
+  const ck = c as Record<string, unknown>;
+  if (ck.type === 'regex') {
+    if (typeof ck.pattern !== 'string') return fail('`check.pattern` must be a string');
+    try {
+      new RegExp(ck.pattern, typeof ck.flags === 'string' ? ck.flags : '');
+    } catch (e) {
+      return fail(`check.pattern is not a valid regex: ${(e as Error).message}`);
+    }
+  } else if (ck.type === 'shape') {
+    if (!Array.isArray(ck.asserts)) return fail('`check.asserts` must be an array');
+    for (let i = 0; i < ck.asserts.length; i++) {
+      const a = ck.asserts[i];
+      if (!a || typeof a !== 'object' || Array.isArray(a)) return fail(`check.asserts[${i}] must be an object`);
+      const aa = a as Record<string, unknown>;
+      if (typeof aa.path !== 'string' || !aa.path) return fail(`check.asserts[${i}].path must be a non-empty string`);
+      if (aa.kind === 'has') {
+        // no extra fields
+      } else if (aa.kind === 'eq') {
+        if (!('value' in aa)) return fail(`check.asserts[${i}] (eq) requires \`value\``);
+      } else if (aa.kind === 'matches') {
+        if (typeof aa.pattern !== 'string') return fail(`check.asserts[${i}] (matches) requires string \`pattern\``);
+        try {
+          new RegExp(aa.pattern, typeof aa.flags === 'string' ? aa.flags : '');
+        } catch (e) {
+          return fail(`check.asserts[${i}].pattern is not a valid regex: ${(e as Error).message}`);
+        }
+      } else {
+        return fail(`check.asserts[${i}].kind must be "has", "eq", or "matches" (got \`${String(aa.kind)}\`)`);
+      }
+    }
+  } else {
+    return fail(`unsupported check.type \`${String(ck.type)}\` (expected "regex" or "shape")`);
+  }
+  if (r.next !== undefined && r.next !== null && typeof r.next !== 'string') {
+    return fail('`next` must be string, null, or omitted');
+  }
+  if (r.translations !== undefined) {
+    if (!r.translations || typeof r.translations !== 'object' || Array.isArray(r.translations)) {
+      return fail('`translations` must be an object keyed by lang code');
+    }
+    for (const [code, tr] of Object.entries(r.translations as Record<string, unknown>)) {
+      if (!tr || typeof tr !== 'object' || Array.isArray(tr)) {
+        return fail(`translations.${code} must be an object`);
+      }
+      const t = tr as Record<string, unknown>;
+      for (const k of ['title', 'intro', 'goal'] as const) {
+        if (t[k] !== undefined && typeof t[k] !== 'string') {
+          return fail(`translations.${code}.${k} must be a string`);
+        }
+      }
+      if (t.hints !== undefined) {
+        if (!Array.isArray(t.hints) || t.hints.some((h) => typeof h !== 'string')) {
+          return fail(`translations.${code}.hints must be string[]`);
+        }
+      }
+    }
+  }
+  return { ok: true, lesson: raw as Lesson };
+
+  function fail(error: string): Validation {
+    return { ok: false, error: `${source}: ${error}` };
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/01-introduction.json b/src/lib/playground/tutorial/lessons/01-introduction.json
new file mode 100644
index 0000000..8536045
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/01-introduction.json
@@ -0,0 +1,30 @@
+{
+  "id": "01-introduction",
+  "title": "Introduction",
+  "topic": "basics",
+  "intro": "Welcome to the **AbstractMenus** HOCON tutorial.\n\nHOCON is the menu config format. Every menu file is a HOCON document. In each lesson you will edit the editor on the left to match the **goal** below.\n\nTo finish this lesson, set the `title` key to anything you want.",
+  "starter": "# Hello! Try editing the line below.\ntitle = \"\"\n",
+  "goal": "Set `title` to a non-empty string.",
+  "check": {
+    "type": "regex",
+    "pattern": "title\\s*=\\s*\"[^\"]+\""
+  },
+  "hints": [
+    "Pick any name and put it between the quotes after `title =`.",
+    "Try `title = \"My first menu\"` for example.",
+    "`title = \"My first menu\"`"
+  ],
+  "next": "02-comments",
+  "translations": {
+    "ru": {
+      "title": "Введение",
+      "intro": "Добро пожаловать в HOCON-туториал **AbstractMenus**.\n\nHOCON - это формат конфигов меню. Каждый файл меню - это HOCON-документ. В каждом уроке вы правите редактор слева, чтобы выполнить **цель** снизу.\n\nЧтобы пройти урок, задайте ключу `title` любое значение.",
+      "goal": "Задайте `title` непустую строку.",
+      "hints": [
+        "Придумайте имя и впишите его в кавычки после `title =`.",
+        "Например: `title = \"Моё первое меню\"`.",
+        "`title = \"Моё первое меню\"`"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/02-comments.json b/src/lib/playground/tutorial/lessons/02-comments.json
new file mode 100644
index 0000000..feb892d
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/02-comments.json
@@ -0,0 +1,31 @@
+{
+  "id": "02-comments",
+  "title": "Comments",
+  "topic": "basics",
+  "intro": "HOCON supports two comment styles:\n\n- `# this is a hash comment`\n- `// this is a slash comment`\n\nBoth run from the marker to the end of the line. Use comments to document menus or temporarily disable a line.\n\n**Goal:** add a comment to the file (any line that starts with `#` or `//`).",
+  "starter": "title = \"My menu\"\nsize = 3\n",
+  "goal": "Add at least one `#` or `//` comment line.",
+  "check": {
+    "type": "regex",
+    "pattern": "^[\\t ]*(#|//).*$",
+    "flags": "m"
+  },
+  "hints": [
+    "Add a new line and start it with `#` or `//`.",
+    "Try `# this menu shows my shop` above the title line.",
+    "`# this menu shows my shop`"
+  ],
+  "next": "03-separators",
+  "translations": {
+    "ru": {
+      "title": "Комментарии",
+      "intro": "HOCON поддерживает два стиля комментариев:\n\n- `# это hash-комментарий`\n- `// это slash-комментарий`\n\nОба идут от маркера до конца строки. Комментарии нужны, чтобы пояснить меню или временно отключить строку.\n\n**Цель:** добавьте в файл комментарий (любую строку, начинающуюся с `#` или `//`).",
+      "goal": "Добавьте хотя бы одну строку-комментарий с `#` или `//`.",
+      "hints": [
+        "Допишите новую строку и начните её с `#` или `//`.",
+        "Например, `# это меню моего магазина` над строкой с title.",
+        "`# это меню моего магазина`"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/03-separators.json b/src/lib/playground/tutorial/lessons/03-separators.json
new file mode 100644
index 0000000..75a125a
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/03-separators.json
@@ -0,0 +1,31 @@
+{
+  "id": "03-separators",
+  "title": "Key/value separators",
+  "topic": "basics",
+  "intro": "HOCON has three ways to write a key-value pair:\n\n- `key = value` - traditional\n- `key : value` - JSON-style colon\n- `key { ... }` - **the `=` is optional** when the value is an object\n\nAll three are equivalent. The third form is the trick: when the value is an object, the separator can be omitted. You'll see it constantly in real menu configs - it makes nested blocks read cleaner.\n\n**Goal:** rewrite `closeActions` without the `=` between the key and the `{`.",
+  "starter": "title = \"Demo\"\ncloseActions = { message = \"Bye!\" }\n",
+  "goal": "Drop the `=` between `closeActions` and `{` (form: `closeActions { ... }`).",
+  "check": {
+    "type": "regex",
+    "pattern": "closeActions\\s*\\{",
+    "flags": ""
+  },
+  "hints": [
+    "The `=` (or `:`) before `{` is optional.",
+    "Try: `closeActions { message = \"Bye!\" }`.",
+    "```\ncloseActions { message = \"Bye!\" }\n```"
+  ],
+  "next": "04-values",
+  "translations": {
+    "ru": {
+      "title": "Разделители ключ/значение",
+      "intro": "В HOCON пары ключ-значение можно писать тремя способами:\n\n- `key = value` - традиционно\n- `key : value` - JSON-стиль\n- `key { ... }` - **`=` необязателен** когда значение это объект\n\nВсе три варианта эквивалентны. Третья форма - фишка: для объекта разделитель можно опустить. Увидишь её постоянно в реальных конфигах меню - вложенные блоки читаются чище.\n\n**Цель:** перепиши `closeActions` без `=` между ключом и `{`.",
+      "goal": "Убери `=` между `closeActions` и `{` (форма: `closeActions { ... }`).",
+      "hints": [
+        "`=` (или `:`) перед `{` необязателен.",
+        "Попробуй: `closeActions { message = \"Bye!\" }`.",
+        "```\ncloseActions { message = \"Bye!\" }\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/04-values.json b/src/lib/playground/tutorial/lessons/04-values.json
new file mode 100644
index 0000000..dae8253
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/04-values.json
@@ -0,0 +1,41 @@
+{
+  "id": "04-values",
+  "title": "Numbers, booleans, durations",
+  "topic": "basics",
+  "intro": "HOCON values aren't only strings. The most common typed values you'll write in menus:\n\n- **Number**: `5`, `3.14`, `-2` - integers and floats. No quotes.\n- **Boolean**: `true` / `false` - unquoted, lowercase. You'll meet booleans inside nested blocks like `firework { flicker = true }` or `bindings`.\n- **Duration**: `5s`, `1m`, `2h`, `500ms` - HOCON's own [duration format](https://github.com/lightbend/config/blob/main/HOCON.md#duration-format) (not ISO 8601). Unit suffix is case-sensitive lowercase: `ns`, `us`, `ms`, `s`, `m`, `h`, `d` (long forms `nanos`, `seconds`, ... also work).\n\nQuoting matters: `\"5\"` is a string, `5` is a number. AbstractMenus is strict here - a duration set to `\"5s\"` won't behave the same as `5s`.\n\n**Goal:** add a `size` key (number 3) and an `updateInterval` key (duration 5s). Both are real menu-level fields - `size` is rows of the menu, `updateInterval` is how often dynamic items re-render.",
+  "starter": "title = \"Demo\"\n",
+  "goal": "Add `size = 3` (number) and `updateInterval = 5s` (duration).",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "size",
+        "value": 3
+      },
+      {
+        "kind": "eq",
+        "path": "updateInterval",
+        "value": "5s"
+      }
+    ]
+  },
+  "hints": [
+    "Numbers don't need quotes: `size = 3`.",
+    "Duration is a number with a unit suffix, also unquoted: `updateInterval = 5s`.",
+    "```\nsize = 3\nupdateInterval = 5s\n```"
+  ],
+  "next": "05-lists-vs-objects",
+  "translations": {
+    "ru": {
+      "title": "Числа, булевы, длительности",
+      "intro": "В HOCON значения бывают не только строками. В меню чаще всего встречаются:\n\n- **Число**: `5`, `3.14`, `-2` - целые и дробные. Без кавычек.\n- **Булево**: `true` / `false` - без кавычек, lowercase. Булевы тебе встретятся внутри вложенных блоков типа `firework { flicker = true }` или `bindings`.\n- **Длительность**: `5s`, `1m`, `2h`, `500ms` - собственный [duration format](https://github.com/lightbend/config/blob/main/HOCON.md#duration-format) HOCON (не ISO 8601). Суффикс единицы регистро-зависимый, lowercase: `ns`, `us`, `ms`, `s`, `m`, `h`, `d` (длинные формы `nanos`, `seconds`, ... тоже работают).\n\nКавычки важны: `\"5\"` - это строка, `5` - число. AbstractMenus строг к типам - длительность заданная как `\"5s\"` поведёт себя не так же как `5s`.\n\n**Цель:** добавь ключ `size` (число 3) и `updateInterval` (длительность 5s). Оба - реальные menu-level поля: `size` это число рядов меню, `updateInterval` это как часто динамические items пере-рендерятся.",
+      "goal": "Добавь `size = 3` (число) и `updateInterval = 5s` (длительность).",
+      "hints": [
+        "Числа без кавычек: `size = 3`.",
+        "Длительность это число с суффиксом единицы, тоже без кавычек: `updateInterval = 5s`.",
+        "```\nsize = 3\nupdateInterval = 5s\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/05-lists-vs-objects.json b/src/lib/playground/tutorial/lessons/05-lists-vs-objects.json
new file mode 100644
index 0000000..7b00bb3
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/05-lists-vs-objects.json
@@ -0,0 +1,40 @@
+{
+  "id": "05-lists-vs-objects",
+  "title": "Lists vs objects",
+  "topic": "basics",
+  "intro": "HOCON has two structural shapes:\n\n- **Object** `{ key = value, ... }` - unordered collection of named fields. Used for menus, items, click actions, rules - anything with a known schema.\n- **Array** `[ value, value, ... ]` - ordered collection. Used for `items` (multiple slots in a menu), `lore` (a list of text lines), `actions` (a sequence to run on click).\n\nKey difference: objects have **names** for each field, arrays have **positions**. Use the right one or the parser will reject your config.\n\n**Goal:** add `metaList` as a list of strings AND `activators` as an object with a `command` field. Both are real menu-level keys - `metaList` seeds player meta values, `activators` configures how the menu opens.",
+  "starter": "title = \"Demo\"\n",
+  "goal": "Add `metaList = [\"a\", \"b\"]` (list) and `activators { command = \"/shop\" }` (object).",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "has",
+        "path": "metaList[1]"
+      },
+      {
+        "kind": "eq",
+        "path": "activators.command",
+        "value": "/shop"
+      }
+    ]
+  },
+  "hints": [
+    "Arrays go in `[...]`: `metaList = [\"a\", \"b\"]`. Elements separated by comma OR newline.",
+    "Objects go in `{...}`: `activators { command = \"/shop\" }`. Same separator rules. Recall `=` before `{` is optional.",
+    "```\nmetaList = [\"a\", \"b\"]\nactivators { command = \"/shop\" }\n```"
+  ],
+  "next": "06-dotted-keys",
+  "translations": {
+    "ru": {
+      "title": "Списки и объекты",
+      "intro": "У HOCON две структурные формы:\n\n- **Объект** `{ key = value, ... }` - неупорядоченный набор именованных полей. Используется для меню, items, click-действий, rules - всего где есть схема.\n- **Массив** `[ value, value, ... ]` - упорядоченный набор. Используется для `items` (несколько slot'ов в меню), `lore` (список строк текста), `actions` (последовательность действий на клик).\n\nКлючевая разница: у объектов поля **именованные**, у массивов - **по позиции**. Используй правильную форму - иначе парсер ругнётся.\n\n**Цель:** добавь `metaList` как список строк И `activators` как объект с полем `command`. Оба - реальные menu-level ключи: `metaList` инициализирует player-meta значения, `activators` настраивает как меню открывается.",
+      "goal": "Добавь `metaList = [\"a\", \"b\"]` (список) и `activators { command = \"/shop\" }` (объект).",
+      "hints": [
+        "Массивы оборачиваются в `[...]`: `metaList = [\"a\", \"b\"]`. Элементы разделяются запятой ИЛИ переносом строки.",
+        "Объекты оборачиваются в `{...}`: `activators { command = \"/shop\" }`. Те же правила. `=` перед `{` опционален.",
+        "```\nmetaList = [\"a\", \"b\"]\nactivators { command = \"/shop\" }\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/06-dotted-keys.json b/src/lib/playground/tutorial/lessons/06-dotted-keys.json
new file mode 100644
index 0000000..2f01947
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/06-dotted-keys.json
@@ -0,0 +1,36 @@
+{
+  "id": "06-dotted-keys",
+  "title": "Dotted keys",
+  "topic": "basics",
+  "intro": "A dot inside a key automatically creates a nested object. These two forms are **identical**:\n\n```\n# Verbose\ndefaults { material = STONE }\n\n# Dotted\ndefaults.material = STONE\n```\n\nUseful for setting one field deep in a nested object without all the braces, and for keeping configs narrow when menus grow.\n\nDots also work inside arbitrary depths: `theme.colors.primary = \"&a\"` is the same as `theme { colors { primary = \"&a\" } }`.\n\n**Goal:** add `defaults.material = STONE` using dotted-key syntax (no braces).",
+  "starter": "title = \"Shop\"\n",
+  "goal": "Add `defaults.material = STONE` using dotted-key syntax (no braces).",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "defaults.material",
+        "value": "STONE"
+      }
+    ]
+  },
+  "hints": [
+    "A dot in the key creates nesting: `a.b = 1` is the same as `a { b = 1 }`.",
+    "Just write `defaults.material = STONE` on a new line.",
+    "```\ndefaults.material = STONE\n```"
+  ],
+  "next": "07-variables-inline",
+  "translations": {
+    "ru": {
+      "title": "Точечные ключи",
+      "intro": "Точка внутри ключа автоматически создаёт вложенный объект. Эти две формы **идентичны**:\n\n```\n# Развёрнутый\ndefaults { material = STONE }\n\n# Точечный\ndefaults.material = STONE\n```\n\nУдобно когда нужно задать одно поле глубоко вложенного объекта без лишних скобок. И конфиг не разрастается вширь когда меню обрастает деталями.\n\nТочки работают на любой глубине: `theme.colors.primary = \"&a\"` это то же что `theme { colors { primary = \"&a\" } }`.\n\n**Цель:** добавь `defaults.material = STONE` через точечный синтаксис (без скобок).",
+      "goal": "Добавь `defaults.material = STONE` через точечный синтаксис (без скобок).",
+      "hints": [
+        "Точка в ключе создаёт вложенность: `a.b = 1` это то же что `a { b = 1 }`.",
+        "Просто напиши `defaults.material = STONE` на новой строке.",
+        "```\ndefaults.material = STONE\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/07-variables-inline.json b/src/lib/playground/tutorial/lessons/07-variables-inline.json
new file mode 100644
index 0000000..23216ee
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/07-variables-inline.json
@@ -0,0 +1,41 @@
+{
+  "id": "07-variables-inline",
+  "title": "Custom variables (inline)",
+  "topic": "basics",
+  "intro": "HOCON lets you define your own keys and reference them elsewhere via `${name}` substitution. Useful for any value that repeats across the config.\n\n```\nitemName = \"Diamond Sword\"\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = ${itemName}\n  }\n]\n# items[0].name resolves to \"Diamond Sword\"\n```\n\nThe variable is just a regular key. Substitutions are resolved before AbstractMenus sees the config. The custom key (`itemName`) sits at the top of the file and AbstractMenus ignores it after substitution - any nicely-readable name will do.\n\n**Gotcha:** if you assign the same scalar key twice, **the last one wins**:\n```\nsize = 3\nsize = 5      # final size is 5\n```\nObject values merge instead of overwriting - that's a separate lesson (`23-object-merge`).\n\n**Goal:** define `itemName = \"Diamond Sword\"` and use it for `items[0].name`.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n  }\n]\n",
+  "goal": "Define `itemName = \"Diamond Sword\"` at the top, then set `items[0].name = ${itemName}`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "itemName",
+        "value": "Diamond Sword"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].name",
+        "value": "Diamond Sword"
+      }
+    ]
+  },
+  "hints": [
+    "Define a variable like any other key: `itemName = \"Diamond Sword\"` (any name works).",
+    "Reference it without quotes inside the item: `name = ${itemName}`.",
+    "```\nitemName = \"Diamond Sword\"\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = ${itemName}\n  }\n]\n```"
+  ],
+  "next": "08-variables-object",
+  "translations": {
+    "ru": {
+      "title": "Кастомные переменные (inline)",
+      "intro": "HOCON позволяет объявить свои ключи и ссылаться на них через `${name}`. Удобно для любых значений которые повторяются в конфиге.\n\n```\nitemName = \"Алмазный меч\"\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = ${itemName}\n  }\n]\n# items[0].name резолвится в \"Алмазный меч\"\n```\n\nПеременная это обычный ключ. Подстановки раскрываются до того как конфиг попадёт в AbstractMenus. Кастомный ключ (`itemName`) лежит наверху файла и AbstractMenus его игнорирует после подстановки - имя можно выбрать любое читаемое.\n\n**Подводный камень:** если присвоить тот же скалярный ключ дважды - **последнее значение побеждает**:\n```\nsize = 3\nsize = 5      # итоговое size равно 5\n```\nДля объектов работает merge (а не перезапись) - это отдельный урок (`23-object-merge`).\n\n**Цель:** объяви `itemName = \"Diamond Sword\"` и используй для `items[0].name`.",
+      "goal": "Объяви `itemName = \"Diamond Sword\"` сверху, потом присвой `items[0].name = ${itemName}`.",
+      "hints": [
+        "Объяви переменную как обычный ключ: `itemName = \"Diamond Sword\"` (имя любое).",
+        "Сошлись на неё без кавычек внутри item'а: `name = ${itemName}`.",
+        "```\nitemName = \"Diamond Sword\"\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = ${itemName}\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/08-variables-object.json b/src/lib/playground/tutorial/lessons/08-variables-object.json
new file mode 100644
index 0000000..7ad3076
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/08-variables-object.json
@@ -0,0 +1,41 @@
+{
+  "id": "08-variables-object",
+  "title": "Custom variables (object)",
+  "topic": "basics",
+  "intro": "Variables aren't limited to strings and numbers. You can stash a whole **object** in a variable and reuse it.\n\nThis is the foundation of every DRY pattern in AbstractMenus configs - shared click actions, repeating styles, common item shapes. Define once, reference many times.\n\n```\ncloseBtnAction { closeMenu = true }\n\nitems = [\n  {\n    slot = 8\n    material = BARRIER\n    name = \"&cClose\"\n    click { actions = ${closeBtnAction} }\n  }\n]\n# items[0].click.actions resolves to { closeMenu = true }\n```\n\nWhen `${closeBtnAction}` resolves to an object, the whole object lands at that position. Same mechanic as the scalar variable from the previous lesson, just a bigger payload.\n\nThe custom key (`closeBtnAction`) sits at the top of the file as a reusable definition; AbstractMenus ignores it after substitution.\n\n**Goal:** define `closeBtnAction` as an object with `closeMenu = true`, then assign it to the existing item's `click.actions`.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 8\n    material = BARRIER\n    name = \"&cClose\"\n  }\n]\n",
+  "goal": "Define `closeBtnAction { closeMenu = true }` at the top, then set the item's `click.actions = ${closeBtnAction}`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "closeBtnAction.closeMenu",
+        "value": true
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].click.actions.closeMenu",
+        "value": true
+      }
+    ]
+  },
+  "hints": [
+    "Define the object at the top: `closeBtnAction { closeMenu = true }` (no `=` needed before `{`).",
+    "Inside the item, reference the whole object: `click { actions = ${closeBtnAction} }`.",
+    "```\ncloseBtnAction { closeMenu = true }\nitems = [\n  {\n    slot = 8\n    material = BARRIER\n    name = \"&cClose\"\n    click { actions = ${closeBtnAction} }\n  }\n]\n```"
+  ],
+  "next": "09-size",
+  "translations": {
+    "ru": {
+      "title": "Кастомные переменные (объект)",
+      "intro": "Переменные не ограничены строками и числами. Можно закинуть в переменную **целый объект** и переиспользовать.\n\nЭто фундамент любого DRY-паттерна в конфигах AbstractMenus - общие click-действия, повторяющиеся стили, типовые формы предметов. Объяви раз - используй много.\n\n```\ncloseBtnAction { closeMenu = true }\n\nitems = [\n  {\n    slot = 8\n    material = BARRIER\n    name = \"&cClose\"\n    click { actions = ${closeBtnAction} }\n  }\n]\n# items[0].click.actions резолвится в { closeMenu = true }\n```\n\nКогда `${closeBtnAction}` ссылается на объект - весь объект встаёт на это место. Механика та же что у скалярной переменной из прошлого урока, просто пэйлоад больше.\n\nКастомный ключ (`closeBtnAction`) лежит наверху файла как переиспользуемое определение; AbstractMenus его игнорирует после подстановки.\n\n**Цель:** объяви `closeBtnAction` как объект с `closeMenu = true`, затем присвой существующему item'у `click.actions`.",
+      "goal": "Объяви `closeBtnAction { closeMenu = true }` сверху, потом присвой `items[0].click.actions = ${closeBtnAction}`.",
+      "hints": [
+        "Объяви объект сверху: `closeBtnAction { closeMenu = true }` (`=` перед `{` не нужен).",
+        "Внутри item'а сошлись на весь объект: `click { actions = ${closeBtnAction} }`.",
+        "```\ncloseBtnAction { closeMenu = true }\nitems = [\n  {\n    slot = 8\n    material = BARRIER\n    name = \"&cClose\"\n    click { actions = ${closeBtnAction} }\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/09-size.json b/src/lib/playground/tutorial/lessons/09-size.json
new file mode 100644
index 0000000..52fc540
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/09-size.json
@@ -0,0 +1,36 @@
+{
+  "id": "09-size",
+  "title": "Menu size",
+  "topic": "menu",
+  "intro": "Time to start a real menu. The first key any [menu](wiki:size) needs is `size` - the number of **rows** (not slots). Vanilla Minecraft inventories are 1-6 rows tall, so valid values are 1-6.\n\n```\nsize = 3   # 3 rows = 27 slots\nsize = 6   # 6 rows = 54 slots (max)\n```\n\nSlots are numbered 0-based row by row: row 0 is slots 0-8, row 1 is 9-17, row 2 is 18-26.\n\n**Goal:** add `size = 3` to the menu.",
+  "starter": "title = \"Shop\"\n",
+  "goal": "Add `size = 3`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "size",
+        "value": 3
+      }
+    ]
+  },
+  "hints": [
+    "Just one line: `size = 3`.",
+    "It's a plain number - no quotes, no units.",
+    "```\nsize = 3\n```"
+  ],
+  "next": "10-items-array",
+  "translations": {
+    "ru": {
+      "title": "Размер меню",
+      "intro": "Пора собрать настоящее меню. Первое что должно быть у любого [меню](wiki:size) - `size` - число **рядов** (не слотов). Стандартные инвентари в Minecraft 1-6 рядов в высоту, так что валидные значения 1-6.\n\n```\nsize = 3   # 3 ряда = 27 слотов\nsize = 6   # 6 рядов = 54 слота (максимум)\n```\n\nСлоты нумеруются с 0 по рядам: ряд 0 это слоты 0-8, ряд 1 это 9-17, ряд 2 это 18-26.\n\n**Цель:** добавь `size = 3`.",
+      "goal": "Добавь `size = 3`.",
+      "hints": [
+        "Одна строка: `size = 3`.",
+        "Это просто число - без кавычек и единиц.",
+        "```\nsize = 3\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/10-items-array.json b/src/lib/playground/tutorial/lessons/10-items-array.json
new file mode 100644
index 0000000..a33a9b9
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/10-items-array.json
@@ -0,0 +1,41 @@
+{
+  "id": "10-items-array",
+  "title": "The items array",
+  "topic": "menu",
+  "intro": "[`items`](wiki:items) is a **list of objects** - one per slot you want to fill. Empty slots are just left out. Each item needs at minimum a `slot` (where it goes) and a `material` (what it looks like).\n\n```\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n  {\n    slot = 4\n    material = DIAMOND\n  }\n]\n```\n\nNotice: items are separated by **newlines** (commas optional in HOCON). This is the same pattern you'll see across `lore`, `bindings`, `actions` - any place where order matters.\n\n**Tip:** press `Ctrl+Space` inside an item's `{...}` to see what other keys are available there (the editor knows the schema).\n\n**Goal:** put a single item in slot 4 with material `DIAMOND`.",
+  "starter": "title = \"Shop\"\nsize = 3\n",
+  "goal": "Add `items` with one entry: `slot = 4`, `material = DIAMOND`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].slot",
+        "value": 4
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].material",
+        "value": "DIAMOND"
+      }
+    ]
+  },
+  "hints": [
+    "`items` is an array - wrap in `[...]`. Each entry is an object - wrap in `{...}`.",
+    "Inside the object you need two keys: `slot = 4` and `material = DIAMOND`.",
+    "```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND\n  }\n]\n```"
+  ],
+  "next": "11-slots",
+  "translations": {
+    "ru": {
+      "title": "Массив items",
+      "intro": "[`items`](wiki:items) это **список объектов** - по одному на каждый слот который хочешь заполнить. Пустые слоты просто опускаются. Каждый item обязательно имеет `slot` (куда поставить) и `material` (как выглядит).\n\n```\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n  {\n    slot = 4\n    material = DIAMOND\n  }\n]\n```\n\nЗаметь: items разделяются **переносами строки** (запятые в HOCON опциональны). Тот же паттерн будет в `lore`, `bindings`, `actions` - везде где важен порядок.\n\n**Совет:** нажми `Ctrl+Space` внутри `{...}` item'а - редактор покажет какие ключи доступны (знает схему).\n\n**Цель:** положи один item в слот 4 с материалом `DIAMOND`.",
+      "goal": "Добавь `items` с одной записью: `slot = 4`, `material = DIAMOND`.",
+      "hints": [
+        "`items` это массив - оборачивай в `[...]`. Каждая запись это объект - оборачивай в `{...}`.",
+        "Внутри объекта два ключа: `slot = 4` и `material = DIAMOND`.",
+        "```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/11-slots.json b/src/lib/playground/tutorial/lessons/11-slots.json
new file mode 100644
index 0000000..4ddd6ed
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/11-slots.json
@@ -0,0 +1,46 @@
+{
+  "id": "11-slots",
+  "title": "Slot positions",
+  "topic": "menu",
+  "intro": "[Slots](wiki:slot) are 0-indexed and run **left-to-right, top-to-bottom**. For a 3-row menu (27 slots) the layout is:\n\n```\nrow 0:   0  1  2  3  4  5  6  7  8\nrow 1:   9 10 11 12 13 14 15 16 17\nrow 2:  18 19 20 21 22 23 24 25 26\n```\n\n![Slot ID layout reference](/docs/img/items_slots_id.png)\n\nFormula: `slot = row * 9 + column`. Slot 4 is the center of the top row, slot 13 is the center of a 3-row menu, slot 22 is the bottom row's center.\n\nYou can place multiple items in one menu by adding more entries to the `items` array.\n\n**Goal:** add a second item at slot 8 (top-right corner) with material `EMERALD`. Keep the first item.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n]\n",
+  "goal": "Add a second entry to `items`: `slot = 8`, `material = EMERALD`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].slot",
+        "value": 0
+      },
+      {
+        "kind": "eq",
+        "path": "items[1].slot",
+        "value": 8
+      },
+      {
+        "kind": "eq",
+        "path": "items[1].material",
+        "value": "EMERALD"
+      }
+    ]
+  },
+  "hints": [
+    "Add a second `{ ... }` inside the existing `[...]`. New line = new array element.",
+    "The new item: `{ slot = 8, material = EMERALD }`.",
+    "```\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n  {\n    slot = 8\n    material = EMERALD\n  }\n]\n```"
+  ],
+  "next": "12-name-and-material",
+  "translations": {
+    "ru": {
+      "title": "Позиции слотов",
+      "intro": "[Слоты](wiki:slot) нумеруются с 0 **слева-направо, сверху-вниз**. Для меню в 3 ряда (27 слотов) раскладка:\n\n```\nряд 0:   0  1  2  3  4  5  6  7  8\nряд 1:   9 10 11 12 13 14 15 16 17\nряд 2:  18 19 20 21 22 23 24 25 26\n```\n\n![Раскладка ID слотов](/docs/img/items_slots_id.png)\n\nФормула: `slot = ряд * 9 + колонка`. Слот 4 - центр верхнего ряда, слот 13 - центр меню в 3 ряда, слот 22 - центр нижнего.\n\nНесколько предметов в меню = больше записей в массиве `items`.\n\n**Цель:** добавь второй item в слот 8 (правый верхний угол) с материалом `EMERALD`. Первый item сохрани.",
+      "goal": "Добавь вторую запись в `items`: `slot = 8`, `material = EMERALD`.",
+      "hints": [
+        "Допиши второй `{ ... }` внутри существующего `[...]`. Новая строка = новый элемент массива.",
+        "Новый item: `{ slot = 8, material = EMERALD }`.",
+        "```\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n  {\n    slot = 8\n    material = EMERALD\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/12-name-and-material.json b/src/lib/playground/tutorial/lessons/12-name-and-material.json
new file mode 100644
index 0000000..9edbb01
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/12-name-and-material.json
@@ -0,0 +1,41 @@
+{
+  "id": "12-name-and-material",
+  "title": "Name + material",
+  "topic": "menu",
+  "intro": "Two keys you'll set on almost every [item](wiki:item-format):\n\n- **`material`** - what the item looks like in the slot. It's a Bukkit material name (uppercase enum, like `DIAMOND_SWORD`, `OAK_LOG`, `BARRIER`).\n- **`name`** - the display name shown when the player hovers over the item. Just a string. Use Minecraft color codes with `&` like `&aGreen` or `&l` for bold.\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n  }\n]\n```\n\n**Tip:** type `material = ` and press `Ctrl+Space` - the editor offers a list of common materials.\n\n**Goal:** change the existing item to `material = DIAMOND_SWORD` and add `name = \"&aBuy Sword\"`.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = STONE\n  }\n]\n",
+  "goal": "Set the item's material to `DIAMOND_SWORD` and add `name = \"&aBuy Sword\"`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].material",
+        "value": "DIAMOND_SWORD"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].name",
+        "value": "&aBuy Sword"
+      }
+    ]
+  },
+  "hints": [
+    "Replace `STONE` with `DIAMOND_SWORD`. Material names are uppercase enum values, no quotes needed.",
+    "Add `name = \"&aBuy Sword\"` inside the same `{ ... }`. The `&a` is Minecraft's green color code.",
+    "```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n  }\n]\n```"
+  ],
+  "next": "13-lore",
+  "translations": {
+    "ru": {
+      "title": "Имя и материал",
+      "intro": "Два ключа которые ставятся почти на каждом [item](wiki:item-format):\n\n- **`material`** - как item выглядит в слоте. Bukkit-имя материала (uppercase enum, например `DIAMOND_SWORD`, `OAK_LOG`, `BARRIER`).\n- **`name`** - отображаемое имя при наведении. Просто строка. Цвета Minecraft через `&`: `&aGreen`, `&l` для жирного.\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n  }\n]\n```\n\n**Совет:** напечатай `material = ` и нажми `Ctrl+Space` - редактор предложит список популярных материалов.\n\n**Цель:** поменяй существующий item на `material = DIAMOND_SWORD` и добавь `name = \"&aBuy Sword\"`.",
+      "goal": "Поставь item'у материал `DIAMOND_SWORD` и добавь `name = \"&aBuy Sword\"`.",
+      "hints": [
+        "Замени `STONE` на `DIAMOND_SWORD`. Материалы это uppercase enum, кавычки не нужны.",
+        "Добавь `name = \"&aBuy Sword\"` внутри того же `{ ... }`. `&a` - код зелёного цвета Minecraft.",
+        "```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/13-lore.json b/src/lib/playground/tutorial/lessons/13-lore.json
new file mode 100644
index 0000000..ead52c3
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/13-lore.json
@@ -0,0 +1,41 @@
+{
+  "id": "13-lore",
+  "title": "Lore (multi-line tooltip)",
+  "topic": "items",
+  "intro": "[`lore`](wiki:display) is the multi-line description shown below the item's name when the player hovers over it. It's a **list of strings** - one entry per line.\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n    lore = [\n      \"&7Click to buy\"\n      \"&7Costs 10 emeralds\"\n    ]\n  }\n]\n```\n\nMinecraft color codes (`&7` for grey, `&a` green, `&l` bold, etc.) work inside lore lines too.\n\n**Goal:** add `lore` to the existing item with the two lines `\"&7Click to buy\"` and `\"&7Costs 10 emeralds\"`.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n  }\n]\n",
+  "goal": "Add `lore = [\"&7Click to buy\", \"&7Costs 10 emeralds\"]` to the item.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].lore[0]",
+        "value": "&7Click to buy"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].lore[1]",
+        "value": "&7Costs 10 emeralds"
+      }
+    ]
+  },
+  "hints": [
+    "`lore` is a list, like `items` itself - wrap in `[...]`. Each line is a string in the array.",
+    "You can put it on one line or break across lines - both work. Strings separated by comma or newline.",
+    "```\nlore = [\n  \"&7Click to buy\"\n  \"&7Costs 10 emeralds\"\n]\n```"
+  ],
+  "next": "14-enchantments",
+  "translations": {
+    "ru": {
+      "title": "Lore (многострочный tooltip)",
+      "intro": "[`lore`](wiki:display) это многострочное описание которое показывается под именем item'а при наведении. Это **список строк** - по одной на строку tooltip'а.\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n    lore = [\n      \"&7Click to buy\"\n      \"&7Costs 10 emeralds\"\n    ]\n  }\n]\n```\n\nЦвета Minecraft (`&7` серый, `&a` зелёный, `&l` жирный и т.д.) работают и внутри lore.\n\n**Цель:** добавь `lore` к существующему item с двумя строками `\"&7Click to buy\"` и `\"&7Costs 10 emeralds\"`.",
+      "goal": "Добавь `lore = [\"&7Click to buy\", \"&7Costs 10 emeralds\"]` в item.",
+      "hints": [
+        "`lore` это список как и сам `items` - оборачивай в `[...]`. Каждая строка - элемент массива.",
+        "Можно в одну строку или разбить - оба работают. Разделители - запятая или перенос.",
+        "```\nlore = [\n  \"&7Click to buy\"\n  \"&7Costs 10 emeralds\"\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/14-enchantments.json b/src/lib/playground/tutorial/lessons/14-enchantments.json
new file mode 100644
index 0000000..776332d
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/14-enchantments.json
@@ -0,0 +1,36 @@
+{
+  "id": "14-enchantments",
+  "title": "Enchantments",
+  "topic": "items",
+  "intro": "[`enchantments`](wiki:mechanics) is an **object** mapping enchantment name to level. Each key is a Bukkit enchantment enum (uppercase), each value is the level.\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    enchantments {\n      SHARPNESS = 5\n      UNBREAKING = 3\n    }\n  }\n]\n```\n\nNote: this is the only place in `items` where the children aren't a fixed AbstractMenus schema - the keys are Bukkit's `Enchantment` enum names (`SHARPNESS`, `EFFICIENCY`, `MENDING`, `LOOTING`, `UNBREAKING`, ...). Use `Ctrl+Space` after `enchantments {` to see common ones.\n\nLooks more impressive in-game with `flags = [\"HIDE_ENCHANTS\"]` to keep the tooltip clean - that's the next lesson.\n\n**Goal:** enchant the sword with `SHARPNESS = 5`.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n  }\n]\n",
+  "goal": "Add `enchantments { SHARPNESS = 5 }` to the item.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].enchantments.SHARPNESS",
+        "value": 5
+      }
+    ]
+  },
+  "hints": [
+    "`enchantments` is an object - use `{...}`. No `=` needed before `{` (you learned that in 03-separators).",
+    "Inside, write `SHARPNESS = 5`. Enchantment names are uppercase enum values.",
+    "```\nenchantments { SHARPNESS = 5 }\n```"
+  ],
+  "next": "15-flags",
+  "translations": {
+    "ru": {
+      "title": "Зачарования",
+      "intro": "[`enchantments`](wiki:mechanics) это **объект** с маппингом имя-зачарования → уровень. Каждый ключ - Bukkit-enum зачарования (uppercase), значение - уровень.\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    enchantments {\n      SHARPNESS = 5\n      UNBREAKING = 3\n    }\n  }\n]\n```\n\nЗаметь: это единственное место в `items` где дети - не фиксированная схема AbstractMenus, а enum Bukkit'а: `SHARPNESS`, `EFFICIENCY`, `MENDING`, `LOOTING`, `UNBREAKING` и т.д. Жми `Ctrl+Space` после `enchantments {` чтобы увидеть популярные.\n\nВыглядит эффектнее в игре с `flags = [\"HIDE_ENCHANTS\"]` чтобы tooltip был чистым - это следующий урок.\n\n**Цель:** зачаруй меч `SHARPNESS = 5`.",
+      "goal": "Добавь `enchantments { SHARPNESS = 5 }` в item.",
+      "hints": [
+        "`enchantments` это объект - используй `{...}`. `=` перед `{` не нужен (видели в 03-separators).",
+        "Внутри: `SHARPNESS = 5`. Имена зачарований - uppercase enum.",
+        "```\nenchantments { SHARPNESS = 5 }\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/15-flags.json b/src/lib/playground/tutorial/lessons/15-flags.json
new file mode 100644
index 0000000..5dfa71d
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/15-flags.json
@@ -0,0 +1,36 @@
+{
+  "id": "15-flags",
+  "title": "Item flags",
+  "topic": "items",
+  "intro": "[`flags`](wiki:display) is a **list of strings** that hide parts of the item's tooltip. Useful for keeping the menu visually clean - by default, an enchanted item shows the enchantment list and an attribute-modified item shows attribute lines.\n\nCommon flags:\n\n- `HIDE_ENCHANTS` - hide the enchant list\n- `HIDE_ATTRIBUTES` - hide attribute modifiers (damage, speed)\n- `HIDE_UNBREAKABLE` - hide the \"unbreakable\" line\n- `HIDE_DESTROYS`, `HIDE_PLACED_ON` - hide block-restriction lines\n- `HIDE_POTION_EFFECTS` - hide potion effect details\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    enchantments { SHARPNESS = 5 }\n    flags = [\"HIDE_ENCHANTS\"]\n  }\n]\n```\n\n**Goal:** the sword from previous lesson now has SHARPNESS visible. Add `flags = [\"HIDE_ENCHANTS\"]` to clean it up.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n    enchantments { SHARPNESS = 5 }\n  }\n]\n",
+  "goal": "Add `flags = [\"HIDE_ENCHANTS\"]` to the item.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].flags[0]",
+        "value": "HIDE_ENCHANTS"
+      }
+    ]
+  },
+  "hints": [
+    "`flags` is a list of strings - just like `lore`, but with enum values inside the strings.",
+    "Single-line form is fine: `flags = [\"HIDE_ENCHANTS\"]`.",
+    "```\nflags = [\"HIDE_ENCHANTS\"]\n```"
+  ],
+  "next": "16-count-cooldown",
+  "translations": {
+    "ru": {
+      "title": "Item flags",
+      "intro": "[`flags`](wiki:display) это **список строк** скрывающих части tooltip'а. Полезно для визуальной чистоты меню - по умолчанию у зачарованного item видны зачарования, у item'а с модификаторами - строки атрибутов.\n\nПопулярные флаги:\n\n- `HIDE_ENCHANTS` - скрыть зачарования\n- `HIDE_ATTRIBUTES` - скрыть модификаторы (урон, скорость)\n- `HIDE_UNBREAKABLE` - скрыть \"unbreakable\"\n- `HIDE_DESTROYS`, `HIDE_PLACED_ON` - скрыть блочные ограничения\n- `HIDE_POTION_EFFECTS` - скрыть детали зелий\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    enchantments { SHARPNESS = 5 }\n    flags = [\"HIDE_ENCHANTS\"]\n  }\n]\n```\n\n**Цель:** меч из прошлого урока теперь показывает SHARPNESS в tooltip'е. Добавь `flags = [\"HIDE_ENCHANTS\"]` чтобы убрать.",
+      "goal": "Добавь `flags = [\"HIDE_ENCHANTS\"]` в item.",
+      "hints": [
+        "`flags` это список строк - как `lore`, только внутри enum-значения.",
+        "Однострочно тоже ок: `flags = [\"HIDE_ENCHANTS\"]`.",
+        "```\nflags = [\"HIDE_ENCHANTS\"]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/16-count-cooldown.json b/src/lib/playground/tutorial/lessons/16-count-cooldown.json
new file mode 100644
index 0000000..bf765d5
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/16-count-cooldown.json
@@ -0,0 +1,41 @@
+{
+  "id": "16-count-cooldown",
+  "title": "Count & cooldown",
+  "topic": "items",
+  "intro": "Two practical [item](wiki:cooldown) fields:\n\n- **`count`** - stack size shown on the item icon (1-64). Default is 1. Set higher for visual emphasis or to display a quantity.\n- **`cooldown`** - per-item click cooldown (a duration like `5s`, `500ms`, `1m`). Prevents click spam when the action is expensive (gives item, runs command).\n\n```\nitems = [\n  {\n    slot = 4\n    material = EMERALD\n    name = \"&a10 Emeralds\"\n    count = 10\n    cooldown = 3s\n  }\n]\n```\n\nNote: `count` is the AbstractMenus name; you might see `amount` in other plugins or in vanilla Bukkit API - they refer to the same thing.\n\n**Goal:** add `count = 16` and `cooldown = 5s` to the item.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND\n    name = \"&aBuy\"\n  }\n]\n",
+  "goal": "Add `count = 16` and `cooldown = 5s` to the item.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].count",
+        "value": 16
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].cooldown",
+        "value": "5s"
+      }
+    ]
+  },
+  "hints": [
+    "`count` is a number, no quotes: `count = 16`.",
+    "`cooldown` is a duration with a unit suffix: `cooldown = 5s` (also `1m`, `500ms`).",
+    "```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND\n    name = \"&aBuy\"\n    count = 16\n    cooldown = 5s\n  }\n]\n```"
+  ],
+  "next": "17-click-message",
+  "translations": {
+    "ru": {
+      "title": "Count и cooldown",
+      "intro": "Два практичных [item](wiki:cooldown)-поля:\n\n- **`count`** - размер стака, показывается на иконке item'а (1-64). По умолчанию 1. Ставь больше для визуального акцента или чтобы показать количество.\n- **`cooldown`** - задержка между кликами на item (длительность типа `5s`, `500ms`, `1m`). Защита от спам-кликов когда действие дорогое (выдать предмет, запустить команду).\n\n```\nitems = [\n  {\n    slot = 4\n    material = EMERALD\n    name = \"&a10 Emeralds\"\n    count = 10\n    cooldown = 3s\n  }\n]\n```\n\nЗаметь: `count` это имя в AbstractMenus; в других плагинах или vanilla Bukkit API можно встретить `amount` - это про то же самое.\n\n**Цель:** добавь `count = 16` и `cooldown = 5s` в item.",
+      "goal": "Добавь `count = 16` и `cooldown = 5s` в item.",
+      "hints": [
+        "`count` это число, без кавычек: `count = 16`.",
+        "`cooldown` это длительность с суффиксом единицы: `cooldown = 5s` (есть `1m`, `500ms`).",
+        "```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND\n    name = \"&aBuy\"\n    count = 16\n    cooldown = 5s\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/17-click-message.json b/src/lib/playground/tutorial/lessons/17-click-message.json
new file mode 100644
index 0000000..3dd63b7
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/17-click-message.json
@@ -0,0 +1,36 @@
+{
+  "id": "17-click-message",
+  "title": "Click: send a message",
+  "topic": "actions",
+  "intro": "Time to make the menu **do** something. The simplest reaction to a click is sending the player a chat message.\n\n[Click handlers](wiki:click) live under `click.actions`. Each key inside `actions` is an **[action type](wiki:actions)** (one of [message](wiki:action.message), [command](wiki:action.command), [sound](wiki:action.sound), openMenu, closeMenu, ...) and the value is the data for that action.\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n    click { actions { message = \"Welcome to the shop!\" } }\n  }\n]\n```\n\nClicking the sword in-game now shows `Welcome to the shop!` in the player's chat.\n\n**Tip:** type `click { actions {` and press `Ctrl+Space` to see the full list of action types AbstractMenus supports.\n\n**Goal:** add a `click.actions.message` to the existing item that sends `\"Welcome to the shop!\"`.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n  }\n]\n",
+  "goal": "Wire up `click.actions.message = \"Welcome to the shop!\"` on the item.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].click.actions.message",
+        "value": "Welcome to the shop!"
+      }
+    ]
+  },
+  "hints": [
+    "Three nested objects: `click { actions { message = ... } }`. Remember `=` before `{` is optional.",
+    "The message is just a string in double quotes.",
+    "```\nclick { actions { message = \"Welcome to the shop!\" } }\n```"
+  ],
+  "next": "18-click-command",
+  "translations": {
+    "ru": {
+      "title": "Click: отправка сообщения",
+      "intro": "Пора заставить меню что-то **делать**. Самая простая реакция на клик - отправить игроку сообщение в чат.\n\n[Click-обработчики](wiki:click) живут в `click.actions`. Каждый ключ внутри `actions` - это **[тип действия](wiki:actions)** ([message](wiki:action.message), [command](wiki:action.command), [sound](wiki:action.sound), openMenu, closeMenu, ...) а значение - данные для этого действия.\n\n```\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n    click { actions { message = \"Добро пожаловать в магазин!\" } }\n  }\n]\n```\n\nКлик по мечу в игре теперь покажет `Добро пожаловать в магазин!` в чате игрока.\n\n**Совет:** напиши `click { actions {` и нажми `Ctrl+Space` - увидишь полный список action-типов которые поддерживает AbstractMenus.\n\n**Цель:** добавь `click.actions.message` к существующему item с текстом `\"Welcome to the shop!\"`.",
+      "goal": "Подключи `click.actions.message = \"Welcome to the shop!\"` на item.",
+      "hints": [
+        "Три вложенных объекта: `click { actions { message = ... } }`. Помни - `=` перед `{` опционален.",
+        "Message - просто строка в двойных кавычках.",
+        "```\nclick { actions { message = \"Welcome to the shop!\" } }\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/18-click-command.json b/src/lib/playground/tutorial/lessons/18-click-command.json
new file mode 100644
index 0000000..8fab6c5
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/18-click-command.json
@@ -0,0 +1,36 @@
+{
+  "id": "18-click-command",
+  "title": "Click: run a command",
+  "topic": "actions",
+  "intro": "Sending a message is fine, but you usually want the menu to actually **change game state** - give items, teleport, set permissions. The standard way is running a command.\n\nThe [`command` action](wiki:action.command) takes a string. By default it runs as **console** so the player doesn't need permissions.\n\n```\nclick { actions { command = \"give @p diamond_sword 1\" } }\n```\n\nUse `@p` to refer to the clicking player (vanilla selector). Or use the AbstractMenus placeholder `%player_name%` (covered in lesson 25).\n\nFor a player-side command (run as the player, with their permissions), use the long form:\n```\ncommand {\n  cmd = \"warp spawn\"\n  as = PLAYER\n}\n```\n\n**Goal:** replace the message handler with a command that gives the player a diamond sword.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n    click { actions { message = \"Welcome to the shop!\" } }\n  }\n]\n",
+  "goal": "Replace the `message` action with `command = \"give @p diamond_sword 1\"`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].click.actions.command",
+        "value": "give @p diamond_sword 1"
+      }
+    ]
+  },
+  "hints": [
+    "Same nesting as last lesson; just swap `message` for `command`.",
+    "The command goes in double quotes - it's just a string.",
+    "```\nclick { actions { command = \"give @p diamond_sword 1\" } }\n```"
+  ],
+  "next": "19-multiple-actions",
+  "translations": {
+    "ru": {
+      "title": "Click: запуск команды",
+      "intro": "Сообщение это хорошо, но обычно меню должно **менять состояние игры** - выдать предмет, телепортировать, выдать доступ. Стандартный способ - запустить команду.\n\nДействие [`command`](wiki:action.command) принимает строку. По умолчанию запускается от **консоли** - игроку не нужны пермишены.\n\n```\nclick { actions { command = \"give @p diamond_sword 1\" } }\n```\n\nИспользуй `@p` для ссылки на кликнувшего игрока (vanilla селектор). Или плейсхолдер AbstractMenus `%player_name%` (урок 25).\n\nДля команды от игрока (с его пермишенами), длинная форма:\n```\ncommand {\n  cmd = \"warp spawn\"\n  as = PLAYER\n}\n```\n\n**Цель:** замени message-обработчик на команду которая выдаёт игроку алмазный меч.",
+      "goal": "Замени `message` на `command = \"give @p diamond_sword 1\"`.",
+      "hints": [
+        "Та же вложенность что и в прошлом уроке; просто поменяй `message` на `command`.",
+        "Команда в двойных кавычках - это просто строка.",
+        "```\nclick { actions { command = \"give @p diamond_sword 1\" } }\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/19-multiple-actions.json b/src/lib/playground/tutorial/lessons/19-multiple-actions.json
new file mode 100644
index 0000000..b1c23a0
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/19-multiple-actions.json
@@ -0,0 +1,46 @@
+{
+  "id": "19-multiple-actions",
+  "title": "Multiple actions in one click",
+  "topic": "actions",
+  "intro": "[`actions`](wiki:actions) is an **object**, so you can stack multiple action types - they all fire on the same click in the order they appear.\n\n```\nclick {\n  actions {\n    message = \"Bought a sword!\"\n    command = \"give @p diamond_sword 1\"\n    sound = ENTITY_VILLAGER_YES\n    closeMenu = true\n  }\n}\n```\n\nThis sends a confirmation message, gives the item, plays a sound, and closes the menu - one click, four side-effects, declared inline.\n\n**Note on duplicates:** since `actions` is an object you can have at most one of each action type. To send two messages or run two commands, put a newline-separated string in `message`/`command`, or use the `bulk` grouping action (advanced).\n\n**Goal:** stack `message` + `command` + `sound = ENTITY_EXPERIENCE_ORB_PICKUP` so all three fire when the sword is clicked.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n    click { actions { command = \"give @p diamond_sword 1\" } }\n  }\n]\n",
+  "goal": "Add `message = \"Bought!\"` and `sound = ENTITY_EXPERIENCE_ORB_PICKUP` alongside the existing `command`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].click.actions.command",
+        "value": "give @p diamond_sword 1"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].click.actions.message",
+        "value": "Bought!"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].click.actions.sound",
+        "value": "ENTITY_EXPERIENCE_ORB_PICKUP"
+      }
+    ]
+  },
+  "hints": [
+    "Just add two more lines inside the existing `actions { ... }` block.",
+    "`sound` value is an enum (uppercase), no quotes; `message` is a string in double quotes.",
+    "```\nactions {\n  command = \"give @p diamond_sword 1\"\n  message = \"Bought!\"\n  sound = ENTITY_EXPERIENCE_ORB_PICKUP\n}\n```"
+  ],
+  "next": "20-click-types",
+  "translations": {
+    "ru": {
+      "title": "Несколько действий в одном клике",
+      "intro": "[`actions`](wiki:actions) это **объект**, так что можно стекать несколько типов действий - все сработают на один клик в порядке записи.\n\n```\nclick {\n  actions {\n    message = \"Купил меч!\"\n    command = \"give @p diamond_sword 1\"\n    sound = ENTITY_VILLAGER_YES\n    closeMenu = true\n  }\n}\n```\n\nПри клике: отправляется сообщение, выдаётся предмет, проигрывается звук, закрывается меню - один клик, четыре сайд-эффекта, всё декларативно.\n\n**О дубликатах:** так как `actions` это объект, каждого типа может быть максимум по одному. Чтобы отправить два сообщения или запустить две команды - кладёшь несколько строк через перенос в `message`/`command`, либо используешь `bulk` (продвинутое).\n\n**Цель:** добавь `message` + `sound = ENTITY_EXPERIENCE_ORB_PICKUP` к существующему `command` чтобы все три срабатывали на клик.",
+      "goal": "Добавь `message = \"Bought!\"` и `sound = ENTITY_EXPERIENCE_ORB_PICKUP` рядом с существующим `command`.",
+      "hints": [
+        "Просто допиши две строки внутри существующего `actions { ... }`.",
+        "`sound` это enum (uppercase), без кавычек; `message` - строка в двойных кавычках.",
+        "```\nactions {\n  command = \"give @p diamond_sword 1\"\n  message = \"Bought!\"\n  sound = ENTITY_EXPERIENCE_ORB_PICKUP\n}\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/20-click-types.json b/src/lib/playground/tutorial/lessons/20-click-types.json
new file mode 100644
index 0000000..cb28d20
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/20-click-types.json
@@ -0,0 +1,41 @@
+{
+  "id": "20-click-types",
+  "title": "Click types: left vs right",
+  "topic": "actions",
+  "intro": "Until now `click.actions` fired on **any** click. To react differently to different mouse buttons, nest under [`left`, `right`, `middle`, `drop`, `shiftLeft`, `shiftRight`](wiki:click):\n\n```\nclick {\n  left { actions { message = \"Left clicked!\" } }\n  right { actions { message = \"Right clicked!\" } }\n}\n```\n\nClassic shop pattern: left-click to buy, right-click to inspect.\n\n```\nclick {\n  left  { actions { command = \"give @p diamond_sword 1\" } }\n  right { actions { message = \"Costs 10 emeralds\" } }\n}\n```\n\nIf you also have a top-level `click.actions` and a `click.left.actions`, both fire on a left click - the top-level one is the catch-all.\n\n**Goal:** split the existing `click.actions` into two distinct handlers - `left` runs the `command`, `right` shows a `message = \"Costs 10 emeralds\"`.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = DIAMOND_SWORD\n    name = \"&aBuy Sword\"\n    click { actions { command = \"give @p diamond_sword 1\" } }\n  }\n]\n",
+  "goal": "Restructure so left-click runs the give command and right-click shows `message = \"Costs 10 emeralds\"`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].click.left.actions.command",
+        "value": "give @p diamond_sword 1"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].click.right.actions.message",
+        "value": "Costs 10 emeralds"
+      }
+    ]
+  },
+  "hints": [
+    "Drop the top-level `actions {...}` and put two siblings under `click`: `left { ... }` and `right { ... }`.",
+    "Each has its own `actions { ... }` with its own keys.",
+    "```\nclick {\n  left { actions { command = \"give @p diamond_sword 1\" } }\n  right { actions { message = \"Costs 10 emeralds\" } }\n}\n```"
+  ],
+  "next": "21-include",
+  "translations": {
+    "ru": {
+      "title": "Типы кликов: left vs right",
+      "intro": "До сих пор `click.actions` срабатывал на **любой** клик. Чтобы реагировать по-разному на разные кнопки мыши, кладёшь под [`left`, `right`, `middle`, `drop`, `shiftLeft`, `shiftRight`](wiki:click):\n\n```\nclick {\n  left { actions { message = \"Left click!\" } }\n  right { actions { message = \"Right click!\" } }\n}\n```\n\nКлассический шоп-паттерн: левый клик - купить, правый - посмотреть детали.\n\n```\nclick {\n  left  { actions { command = \"give @p diamond_sword 1\" } }\n  right { actions { message = \"Стоит 10 изумрудов\" } }\n}\n```\n\nЕсли есть и top-level `click.actions` и `click.left.actions` - оба сработают на левый клик. Top-level это catch-all.\n\n**Цель:** раздели существующий `click.actions` на два разных обработчика - `left` запускает `command`, `right` показывает `message = \"Costs 10 emeralds\"`.",
+      "goal": "Перестрой так чтобы left-click запускал команду give, а right-click показывал `message = \"Costs 10 emeralds\"`.",
+      "hints": [
+        "Убери top-level `actions {...}` и положи два sibling'а под `click`: `left { ... }` и `right { ... }`.",
+        "У каждого свой `actions { ... }` со своими ключами.",
+        "```\nclick {\n  left { actions { command = \"give @p diamond_sword 1\" } }\n  right { actions { message = \"Costs 10 emeralds\" } }\n}\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/21-include.json b/src/lib/playground/tutorial/lessons/21-include.json
new file mode 100644
index 0000000..616eacc
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/21-include.json
@@ -0,0 +1,31 @@
+{
+  "id": "21-include",
+  "title": "Include shared templates",
+  "topic": "templates",
+  "intro": "When several menus share fields (button styles, common click actions, color palette), don't copy them - put them in a separate file and **[include](wiki:templates.include)** it.\n\n```\ninclude \"defaults.conf\"\ninclude classpath(\"defaults.conf\")\ninclude required(\"defaults.conf\")\n```\n\nThe most common form is the simple string: `include \"path/to/file.conf\"`. AbstractMenus resolves the path relative to the menu file. Other forms (`classpath(...)`, `required(...)`) are for advanced cases (jar resources, fail-loudly).\n\nThe included file is parsed as if its contents were inlined where the `include` line stands. Any keys in the including file then override the included ones (last-wins / object-merge per the rules you've seen).\n\n**Caveat:** The playground shows a yellow warning on `include` lines because there are no other files here to load. The syntax check still passes - this lesson is about learning the form. In a real plugin install the include resolves normally.\n\n**Goal:** add an `include \"defaults.conf\"` line above the existing `title`.",
+  "starter": "title = \"Shop\"\nsize = 3\n",
+  "goal": "Add `include \"defaults.conf\"` (the warning on this line is expected in playground).",
+  "check": {
+    "type": "regex",
+    "pattern": "include\\s+\"[^\"]+\\.conf\"",
+    "flags": ""
+  },
+  "hints": [
+    "Just one line: `include \"defaults.conf\"`. Note the bare `include` keyword (no `=`).",
+    "The yellow warning is fine - playground has no real `defaults.conf` to load.",
+    "```\ninclude \"defaults.conf\"\ntitle = \"Shop\"\n```"
+  ],
+  "next": "22-array-append",
+  "translations": {
+    "ru": {
+      "title": "Include - подключение файла-шаблона",
+      "intro": "Когда несколько меню разделяют общие поля (стили кнопок, общие click-действия, палитру цветов), не копируй их - вынеси в отдельный файл и **[подключи](wiki:templates.include)** через include.\n\n```\ninclude \"defaults.conf\"\ninclude classpath(\"defaults.conf\")\ninclude required(\"defaults.conf\")\n```\n\nСамая частая форма - просто строка: `include \"path/to/file.conf\"`. AbstractMenus резолвит путь относительно файла меню. Другие формы (`classpath(...)`, `required(...)`) для продвинутых случаев (ресурсы из jar, падать-если-нет).\n\nПодключённый файл парсится как если бы его содержимое было встроено вместо `include`. Ключи из подключающего файла потом перекрывают подключённые (last-wins / object-merge по правилам которые ты уже видел).\n\n**Внимание:** Playground показывает жёлтое предупреждение на строке `include` потому что других файлов здесь нет. Проверка урока всё равно проходит - этот урок про форму. В реальном плагине include резолвится нормально.\n\n**Цель:** добавь `include \"defaults.conf\"` над существующим `title`.",
+      "goal": "Добавь `include \"defaults.conf\"` (warning на этой строке ожидаем в playground).",
+      "hints": [
+        "Одна строка: `include \"defaults.conf\"`. Заметь - голое слово `include` (без `=`).",
+        "Жёлтое предупреждение это норм - в playground нет реального `defaults.conf`.",
+        "```\ninclude \"defaults.conf\"\ntitle = \"Shop\"\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/22-array-append.json b/src/lib/playground/tutorial/lessons/22-array-append.json
new file mode 100644
index 0000000..edbd00c
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/22-array-append.json
@@ -0,0 +1,46 @@
+{
+  "id": "22-array-append",
+  "title": "Array append +=",
+  "topic": "templates",
+  "intro": "The `+=` operator concatenates onto an existing array instead of overwriting it. Useful when an included file (or a base block) defines some items and you want to add more without losing the originals.\n\n```\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n]\n\nitems += [\n  {\n    slot = 8\n    material = DIAMOND\n  }\n]\n\n# resolves to a 2-element items array\n```\n\nWithout `+=`, the second `items =` would replace the first - last-wins for scalars, and the array is treated as a scalar value (not an object). With `+=`, the new items are appended in declaration order.\n\nReal-world pattern: include a base file with default items, then `+=` to add menu-specific extras.\n\n**Goal:** the starter has one item at slot 0. **Append** a second item at slot 8 (`material = EMERALD`) using `+=`, **without** removing the first.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n]\n",
+  "goal": "Use `items += [{ slot = 8, material = EMERALD }]` to append; the resolved `items` should have both entries.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].slot",
+        "value": 0
+      },
+      {
+        "kind": "eq",
+        "path": "items[1].slot",
+        "value": 8
+      },
+      {
+        "kind": "eq",
+        "path": "items[1].material",
+        "value": "EMERALD"
+      }
+    ]
+  },
+  "hints": [
+    "Don't touch the first `items = [...]`. Add a new `items += [...]` line below it.",
+    "The right side is still a normal array literal - `[{ slot = 8, material = EMERALD }]`.",
+    "```\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n]\nitems += [\n  {\n    slot = 8\n    material = EMERALD\n  }\n]\n```"
+  ],
+  "next": "23-object-merge",
+  "translations": {
+    "ru": {
+      "title": "Array append +=",
+      "intro": "Оператор `+=` дописывает в существующий массив вместо перезаписи. Полезно когда подключённый файл (или базовый блок) объявляет какие-то items, а ты хочешь добавить ещё без потери оригиналов.\n\n```\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n]\n\nitems += [\n  {\n    slot = 8\n    material = DIAMOND\n  }\n]\n\n# резолвится в массив items из 2 элементов\n```\n\nБез `+=` второй `items =` заменил бы первый - last-wins для скаляров, а массив трактуется как скалярное значение (не объект). С `+=` новые items добавляются в порядке объявления.\n\nРеальный паттерн: include базового файла с дефолтными items, потом `+=` для меню-специфичных доп.\n\n**Цель:** в стартере один item в слоте 0. **Допиши** второй в слот 8 (`material = EMERALD`) через `+=`, **не удаляя** первый.",
+      "goal": "Используй `items += [{ slot = 8, material = EMERALD }]`; в результирующем `items` должно быть обе записи.",
+      "hints": [
+        "Не трогай первый `items = [...]`. Допиши под ним новую строку `items += [...]`.",
+        "Справа обычный массив - `[{ slot = 8, material = EMERALD }]`.",
+        "```\nitems = [\n  {\n    slot = 0\n    material = STONE\n  }\n]\nitems += [\n  {\n    slot = 8\n    material = EMERALD\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/23-object-merge.json b/src/lib/playground/tutorial/lessons/23-object-merge.json
new file mode 100644
index 0000000..e14c328
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/23-object-merge.json
@@ -0,0 +1,41 @@
+{
+  "id": "23-object-merge",
+  "title": "Object merge on duplicate keys",
+  "topic": "templates",
+  "intro": "When you assign the same key twice and **both values are objects**, HOCON merges them - the second block adds/overrides fields in the first instead of replacing it.\n\n```\ndefaults {\n  material = STONE\n  name = \"Default\"\n}\ndefaults {\n  name = \"Override\"\n  lore = [\"line\"]\n}\n# resolves to:\n# defaults: { material = STONE, name = \"Override\", lore = [\"line\"] }\n```\n\nThis is the same rule that fires when you `include` a file: keys after the include override (or merge into) keys from the include. It's also what makes a base+override pattern work without `+=` or spreads:\n\n```\n# base.conf\ndefaults {\n  material = STONE\n  count = 1\n}\n\n# menu.conf\ninclude \"base.conf\"\ndefaults { count = 16 }   # bumps count, keeps material\n```\n\n**Gotcha vs scalars:** if either side is a scalar (or one is an object and the other isn't), it's still last-wins. Merge is **only** when both are objects.\n\n**Goal:** add a second `defaults { ... }` block that contributes `count = 16` while leaving `material = STONE` from the first block intact.",
+  "starter": "title = \"Shop\"\ndefaults { material = STONE }\n",
+  "goal": "Add a second `defaults { count = 16 }` block; resolved `defaults` should have both `material` and `count`.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "defaults.material",
+        "value": "STONE"
+      },
+      {
+        "kind": "eq",
+        "path": "defaults.count",
+        "value": 16
+      }
+    ]
+  },
+  "hints": [
+    "Just write a second `defaults { ... }` line below the first. Both objects = merge.",
+    "Inside: `count = 16`. Don't repeat `material` - it's already there.",
+    "```\ndefaults { material = STONE }\ndefaults { count = 16 }\n```"
+  ],
+  "next": "24-defaults-merge",
+  "translations": {
+    "ru": {
+      "title": "Object merge на дубликатах ключей",
+      "intro": "Когда присваиваешь один и тот же ключ дважды и **оба значения - объекты**, HOCON их сливает - второй блок добавляет/переопределяет поля в первом, а не заменяет его целиком.\n\n```\ndefaults {\n  material = STONE\n  name = \"Default\"\n}\ndefaults {\n  name = \"Override\"\n  lore = [\"line\"]\n}\n# резолвится в:\n# defaults: { material = STONE, name = \"Override\", lore = [\"line\"] }\n```\n\nЭто то же правило что срабатывает при `include`: ключи после include перекрывают (или сливаются с) ключами из include. И именно это делает base+override паттерн возможным без `+=` или spread:\n\n```\n# base.conf\ndefaults {\n  material = STONE\n  count = 1\n}\n\n# menu.conf\ninclude \"base.conf\"\ndefaults { count = 16 }   # бампит count, material остаётся\n```\n\n**Подвох vs скаляры:** если хоть с одной стороны скаляр (или один объект а другой нет) - last-wins. Merge **только** когда оба объекты.\n\n**Цель:** добавь второй блок `defaults { ... }` который добавит `count = 16`, оставив `material = STONE` из первого блока.",
+      "goal": "Добавь второй блок `defaults { count = 16 }`; в результирующем `defaults` должны быть и `material`, и `count`.",
+      "hints": [
+        "Просто допиши второй `defaults { ... }` под первым. Оба объекта = merge.",
+        "Внутри: `count = 16`. `material` повторять не надо - он уже там.",
+        "```\ndefaults { material = STONE }\ndefaults { count = 16 }\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/24-defaults-merge.json b/src/lib/playground/tutorial/lessons/24-defaults-merge.json
new file mode 100644
index 0000000..5382676
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/24-defaults-merge.json
@@ -0,0 +1,61 @@
+{
+  "id": "24-defaults-merge",
+  "title": "Defaults pattern (${ref} spread)",
+  "topic": "templates",
+  "intro": "The classic [DRY trick](wiki:templates) in AbstractMenus configs: define a `defaults` object once, **spread** it into each item via `${defaults}`. Item-specific fields override the defaults on collision.\n\n```\ndefaults {\n  material = STONE\n  name = \"&aGeneric\"\n}\nitems = [\n  {\n    slot = 0\n    ${defaults}\n  }\n  {\n    slot = 4\n    ${defaults}\n    name = \"&bSpecial\"\n  }\n]\n# resolves to:\n# items[0]: { slot = 0, material = STONE, name = \"&aGeneric\" }\n# items[1]: { slot = 4, material = STONE, name = \"&bSpecial\" }\n```\n\nThe spread substitution drops every field of the referenced object into the surrounding `{...}`. Anything you write **alongside** `${defaults}` overrides it (own keys win).\n\nUseful for: shared button styles, repeating item shapes, common click handlers.\n\n**Goal:** spread `${defaults}` into both items so they pick up `material = STONE` from the defaults block. The first item keeps its slot only; the second gets a custom `name`.",
+  "starter": "title = \"Shop\"\nsize = 3\ndefaults {\n  material = STONE\n  name = \"&aDefault\"\n}\nitems = [\n  { slot = 0 }\n  {\n    slot = 4\n    name = \"&bSpecial\"\n  }\n]\n",
+  "goal": "Insert `${defaults}` into both items so they inherit `material`. The second item's own `name` should still win over the default.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].slot",
+        "value": 0
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].material",
+        "value": "STONE"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].name",
+        "value": "&aDefault"
+      },
+      {
+        "kind": "eq",
+        "path": "items[1].slot",
+        "value": 4
+      },
+      {
+        "kind": "eq",
+        "path": "items[1].material",
+        "value": "STONE"
+      },
+      {
+        "kind": "eq",
+        "path": "items[1].name",
+        "value": "&bSpecial"
+      }
+    ]
+  },
+  "hints": [
+    "Inside each item's `{...}`, just drop in `${defaults}` next to the existing fields.",
+    "Order doesn't matter for the merge; explicit fields always win on collision.",
+    "```\nitems = [\n  {\n    slot = 0\n    ${defaults}\n  }\n  {\n    slot = 4\n    ${defaults}\n    name = \"&bSpecial\"\n  }\n]\n```"
+  ],
+  "next": "25-optional-subs",
+  "translations": {
+    "ru": {
+      "title": "Defaults паттерн (${ref} спред)",
+      "intro": "Классический [DRY-приём](wiki:templates) в конфигах AbstractMenus: один раз объяви объект `defaults`, **раскидай** его в каждый item через `${defaults}`. Item-специфичные поля перекрывают defaults при коллизии.\n\n```\ndefaults {\n  material = STONE\n  name = \"&aGeneric\"\n}\nitems = [\n  {\n    slot = 0\n    ${defaults}\n  }\n  {\n    slot = 4\n    ${defaults}\n    name = \"&bSpecial\"\n  }\n]\n# резолвится в:\n# items[0]: { slot = 0, material = STONE, name = \"&aGeneric\" }\n# items[1]: { slot = 4, material = STONE, name = \"&bSpecial\" }\n```\n\nSpread-подстановка вкладывает каждое поле referenced объекта прямо в окружающий `{...}`. Всё что написано **рядом** с `${defaults}` перекрывает его (own keys win).\n\nНужно для: общих стилей кнопок, повторяющихся форм item'ов, общих click-обработчиков.\n\n**Цель:** вставь `${defaults}` в оба item'а чтобы они подобрали `material = STONE` из defaults. У второго item собственный `name` должен победить.",
+      "goal": "Вставь `${defaults}` в оба item'а чтобы они унаследовали `material`. Собственный `name` второго item'а должен победить дефолтный.",
+      "hints": [
+        "Внутри каждого `{...}` item'а просто добавь `${defaults}` рядом с существующими полями.",
+        "Порядок не важен для merge; явные поля всегда побеждают на коллизии.",
+        "```\nitems = [\n  {\n    slot = 0\n    ${defaults}\n  }\n  {\n    slot = 4\n    ${defaults}\n    name = \"&bSpecial\"\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/25-optional-subs.json b/src/lib/playground/tutorial/lessons/25-optional-subs.json
new file mode 100644
index 0000000..661b12e
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/25-optional-subs.json
@@ -0,0 +1,31 @@
+{
+  "id": "25-optional-subs",
+  "title": "Optional substitutions ${?var}",
+  "topic": "templates",
+  "intro": "By default [`${name}`](wiki:variables) **must** resolve - if the variable doesn't exist, you get an `Unresolved substitution` warning and the value falls back to null.\n\nThe `${?name}` form (note the `?`) marks the substitution as **optional**: missing variable is silent, no warning, value just resolves to absent / null.\n\n```\ntitle = ${?customTitle}     # quiet if customTitle isn't set\n```\n\nReal-world use: a shared template file that **maybe** sets some fields, where each menu using `include` decides whether to set them.\n\n```\n# template.conf\ntitle = ${?customTitle}\n\n# menu.conf\ninclude \"template.conf\"\ncustomTitle = \"Diamond Shop\"   # picked up by ${?customTitle}\n```\n\n**Goal:** assign `title = ${?customTitle}`. Since `customTitle` isn't defined, the `?` form keeps it quiet (a plain `${customTitle}` would warn).",
+  "starter": "size = 3\n",
+  "goal": "Set `title = ${?customTitle}` (the `?` form so no warning fires for the missing variable).",
+  "check": {
+    "type": "regex",
+    "pattern": "title\\s*=\\s*\\$\\{\\?[a-zA-Z_]\\w*\\}",
+    "flags": ""
+  },
+  "hints": [
+    "Same as `${name}` but with a `?` right after the opening brace: `${?name}`.",
+    "The variable doesn't have to exist anywhere - that's the whole point.",
+    "```\ntitle = ${?customTitle}\n```"
+  ],
+  "next": "26-placeholders",
+  "translations": {
+    "ru": {
+      "title": "Опциональные подстановки ${?var}",
+      "intro": "По умолчанию [`${name}`](wiki:variables) **обязан** разрешиться - если переменной нет, получишь warning `Unresolved substitution` и значение схлопнется в null.\n\nФорма `${?name}` (заметь `?`) помечает подстановку как **опциональную**: отсутствующая переменная - молчком, без warning'а, значение резолвится в absent / null.\n\n```\ntitle = ${?customTitle}     # тихо если customTitle не задан\n```\n\nРеальный случай использования: общий template-файл который **может быть** задаёт какие-то поля, а каждое меню через `include` решает - задавать их или нет.\n\n```\n# template.conf\ntitle = ${?customTitle}\n\n# menu.conf\ninclude \"template.conf\"\ncustomTitle = \"Магазин алмазов\"   # подхватывается через ${?customTitle}\n```\n\n**Цель:** присвой `title = ${?customTitle}`. `customTitle` нигде не задан - форма с `?` оставит это тихо (без `?` был бы warning).",
+      "goal": "Присвой `title = ${?customTitle}` (форма с `?` - warning не сработает на отсутствующую переменную).",
+      "hints": [
+        "Так же как `${name}` но с `?` сразу после открывающей скобки: `${?name}`.",
+        "Переменной может не существовать вообще - в этом и весь смысл.",
+        "```\ntitle = ${?customTitle}\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/26-placeholders.json b/src/lib/playground/tutorial/lessons/26-placeholders.json
new file mode 100644
index 0000000..a0be833
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/26-placeholders.json
@@ -0,0 +1,36 @@
+{
+  "id": "26-placeholders",
+  "title": "Player placeholders %player_name%",
+  "topic": "templates",
+  "intro": "Two different things look similar but happen at totally different times:\n\n- **`${var}`** - HOCON substitution. Resolved when the config is **loaded** by AbstractMenus. The reference must point at another key in the same config.\n- **`%player_name%`** - [PlaceholderAPI placeholder](wiki:placeholders) (and similar). Resolved at **runtime**, every time the menu is rendered for a specific player. The HOCON parser doesn't touch it - the literal `%...%` text passes through into the value.\n\n```\nitems = [\n  {\n    slot = 4\n    material = PLAYER_HEAD\n    name = \"&aHello %player_name%!\"\n    lore = [\n      \"&7Balance: %vault_eco_balance%\"\n      \"&7Rank: %luckperms_prefix%\"\n    ]\n  }\n]\n```\n\nUse `%...%` placeholders for anything **per-player**: their name, their balance, their permissions, their location. Use `${var}` for **structural** reuse (defaults, color palette, button templates).\n\nAvailable placeholders depend on which plugins you have installed - any PlaceholderAPI extension contributes its own.\n\n**Goal:** add a `name` to the existing item that greets the player by their name using `%player_name%`.",
+  "starter": "title = \"Welcome\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = PLAYER_HEAD\n  }\n]\n",
+  "goal": "Set `items[0].name` to a string that contains `%player_name%` (e.g. `\"&aHello %player_name%!\"`).",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "matches",
+        "path": "items[0].name",
+        "pattern": "%player_name%"
+      }
+    ]
+  },
+  "hints": [
+    "It's just a string with `%player_name%` somewhere inside the quotes - the parser leaves it alone.",
+    "Color codes work too: `\"&aHello %player_name%!\"`.",
+    "```\nitems = [\n  {\n    slot = 4\n    material = PLAYER_HEAD\n    name = \"&aHello %player_name%!\"\n  }\n]\n```"
+  ],
+  "next": "27-rules-permission",
+  "translations": {
+    "ru": {
+      "title": "Player-плейсхолдеры %player_name%",
+      "intro": "Две вещи выглядят похоже но происходят в совершенно разное время:\n\n- **`${var}`** - HOCON-подстановка. Резолвится когда конфиг **загружается** AbstractMenus'ом. Ссылка должна указывать на другой ключ того же конфига.\n- **`%player_name%`** - [плейсхолдер из PlaceholderAPI](wiki:placeholders) (и подобных). Резолвится **в рантайме**, каждый раз при отрисовке меню для конкретного игрока. HOCON-парсер их не трогает - текст `%...%` проходит насквозь в значение.\n\n```\nitems = [\n  {\n    slot = 4\n    material = PLAYER_HEAD\n    name = \"&aПривет %player_name%!\"\n    lore = [\n      \"&7Баланс: %vault_eco_balance%\"\n      \"&7Ранг: %luckperms_prefix%\"\n    ]\n  }\n]\n```\n\nИспользуй `%...%` плейсхолдеры для всего **per-player**: имя, баланс, права, локация. `${var}` - для **структурного** реюза (defaults, палитра цветов, шаблоны кнопок).\n\nДоступные плейсхолдеры зависят от установленных плагинов - любой PlaceholderAPI extension добавляет свои.\n\n**Цель:** добавь существующему item'у `name` который приветствует игрока по имени через `%player_name%`.",
+      "goal": "Поставь `items[0].name` на строку содержащую `%player_name%` (например `\"&aПривет %player_name%!\"`).",
+      "hints": [
+        "Это просто строка с `%player_name%` где-то внутри кавычек - парсер не трогает.",
+        "Цвета тоже работают: `\"&aПривет %player_name%!\"`.",
+        "```\nitems = [\n  {\n    slot = 4\n    material = PLAYER_HEAD\n    name = \"&aHello %player_name%!\"\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/27-rules-permission.json b/src/lib/playground/tutorial/lessons/27-rules-permission.json
new file mode 100644
index 0000000..2d97da2
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/27-rules-permission.json
@@ -0,0 +1,41 @@
+{
+  "id": "27-rules-permission",
+  "title": "Permission rule",
+  "topic": "conditions",
+  "intro": "Most click handlers shouldn't fire for everyone. The [`rules`](wiki:rules) block gates an action: when any rule fails, the action is silently skipped.\n\n```\nclick {\n  rules { permission = \"menu.admin\" }\n  actions { command = \"op @p\" }\n}\n```\n\nA rule attached to a `click` block gates **that click's actions**. The same `rules` syntax also works on `items` (gates visibility) and on `bindings` (the next lesson).\n\nMost common rule keys:\n\n- `permission = \"shop.use\"` - player must hold the permission\n- `money = 100` - player must have at least N Vault balance\n- `levels = 30` - player must have at least N XP levels\n- `gamemode = \"SURVIVAL\"` - gamemode match\n- `world = \"lobby\"` - world match\n\nMultiple rules in the same block are **AND**-ed: all must pass.\n\n**Goal:** add a `rules { permission = \"menu.admin\" }` block to the click so only admins can fire the command.",
+  "starter": "title = \"Admin\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = COMMAND_BLOCK\n    name = \"&cAdmin Panel\"\n    click { actions { command = \"op @p\" } }\n  }\n]\n",
+  "goal": "Add `rules { permission = \"menu.admin\" }` to the click handler.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].click.rules.permission",
+        "value": "menu.admin"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].click.actions.command",
+        "value": "op @p"
+      }
+    ]
+  },
+  "hints": [
+    "`rules` is a sibling of `actions` inside the `click` block, not nested under it.",
+    "Inside `rules`, just one key for now: `permission = \"menu.admin\"`.",
+    "```\nclick {\n  rules { permission = \"menu.admin\" }\n  actions { command = \"op @p\" }\n}\n```"
+  ],
+  "next": "28-bindings",
+  "translations": {
+    "ru": {
+      "title": "Permission rule",
+      "intro": "Большинство click-обработчиков не должны срабатывать для всех. Блок [`rules`](wiki:rules) гейтит действие: если хоть одно правило не прошло - action молча пропускается.\n\n```\nclick {\n  rules { permission = \"menu.admin\" }\n  actions { command = \"op @p\" }\n}\n```\n\nПравило на `click` гейтит **actions этого клика**. Тот же `rules` синтаксис работает на `items` (гейт видимости) и на `bindings` (следующий урок).\n\nСамые частые ключи rules:\n\n- `permission = \"shop.use\"` - у игрока должен быть пермишен\n- `money = 100` - у игрока должно быть хотя бы N Vault-баланса\n- `levels = 30` - хотя бы N уровней XP\n- `gamemode = \"SURVIVAL\"` - совпадение gamemode\n- `world = \"lobby\"` - совпадение мира\n\nНесколько правил в одном блоке - **AND**: должны пройти все.\n\n**Цель:** добавь `rules { permission = \"menu.admin\" }` в click - только админы смогут запустить команду.",
+      "goal": "Добавь `rules { permission = \"menu.admin\" }` в click.",
+      "hints": [
+        "`rules` - это sibling `actions` внутри `click`, а не вложен в него.",
+        "Внутри `rules` пока один ключ: `permission = \"menu.admin\"`.",
+        "```\nclick {\n  rules { permission = \"menu.admin\" }\n  actions { command = \"op @p\" }\n}\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/28-bindings.json b/src/lib/playground/tutorial/lessons/28-bindings.json
new file mode 100644
index 0000000..11f341c
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/28-bindings.json
@@ -0,0 +1,46 @@
+{
+  "id": "28-bindings",
+  "title": "Bindings (rules + props)",
+  "topic": "conditions",
+  "intro": "What if you don't want to **hide** an item per-player but **change** how it looks? That's [bindings](wiki:bindings).\n\nA binding is a `(rules, props)` pair attached to an item. When the rules pass, the props **override** the item's normal fields. Different players see different versions of the same slot - same item, different material, name, lore, click handler.\n\n```\nitems = [\n  {\n    slot = 4\n    material = STONE\n    name = \"&7Standard\"\n    bindings = [\n      {\n        rules { permission = \"vip\" }\n        props {\n          material = DIAMOND\n          name = \"&aVIP exclusive\"\n        }\n      }\n    ]\n  }\n]\n```\n\nNo permission -> sees STONE \"Standard\". With `vip` permission -> sees DIAMOND \"VIP exclusive\". Same slot, two faces.\n\nBindings are checked in array order, **first match wins**. Multiple bindings = a tier system:\n\n```\nbindings = [\n  {\n    rules { permission = \"admin\" }\n    props { name = \"&cAdmin\" }\n  }\n  {\n    rules { permission = \"vip\" }\n    props { name = \"&aVIP\" }\n  }\n]\n```\n\n`props` accepts any item-scope key (material, name, lore, click, count, ...) - it's a partial item override.\n\n**Goal:** add a `bindings` array on the item with one binding that swaps `material` to `DIAMOND` for players with the `vip` permission.",
+  "starter": "title = \"Shop\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = STONE\n    name = \"&7Standard\"\n  }\n]\n",
+  "goal": "Add `bindings = [{ rules { permission = \"vip\" }, props { material = DIAMOND } }]` on the item.",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].material",
+        "value": "STONE"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].bindings[0].rules.permission",
+        "value": "vip"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].bindings[0].props.material",
+        "value": "DIAMOND"
+      }
+    ]
+  },
+  "hints": [
+    "`bindings` is a list (`[...]`) of binding objects. Each binding has `rules` and `props`.",
+    "Inside `props`, write any item-scope key you want to override - here just `material = DIAMOND`.",
+    "```\nbindings = [\n  {\n    rules { permission = \"vip\" }\n    props { material = DIAMOND }\n  }\n]\n```"
+  ],
+  "next": "29-rules-world",
+  "translations": {
+    "ru": {
+      "title": "Bindings (rules + props)",
+      "intro": "А если ты хочешь не **скрыть** item для конкретного игрока, а **изменить** как он выглядит? Это [bindings](wiki:bindings).\n\nBinding это пара `(rules, props)` прикреплённая к item'у. Когда rules проходят - props **перекрывают** обычные поля item'а. Разные игроки видят разные версии одного слота - один item, разные material, name, lore, click.\n\n```\nitems = [\n  {\n    slot = 4\n    material = STONE\n    name = \"&7Standard\"\n    bindings = [\n      {\n        rules { permission = \"vip\" }\n        props {\n          material = DIAMOND\n          name = \"&aVIP exclusive\"\n        }\n      }\n    ]\n  }\n]\n```\n\nБез пермишена - видит STONE \"Standard\". С `vip` - DIAMOND \"VIP exclusive\". Один слот, два лица.\n\nBindings проверяются по порядку в массиве, **первое совпадение побеждает**. Несколько bindings = tier-система:\n\n```\nbindings = [\n  {\n    rules { permission = \"admin\" }\n    props { name = \"&cAdmin\" }\n  }\n  {\n    rules { permission = \"vip\" }\n    props { name = \"&aVIP\" }\n  }\n]\n```\n\n`props` принимает любой item-scope ключ (material, name, lore, click, count, ...) - это частичный override item'а.\n\n**Цель:** добавь массив `bindings` на item с одним binding'ом который меняет `material` на `DIAMOND` для игроков с пермишеном `vip`.",
+      "goal": "Добавь `bindings = [{ rules { permission = \"vip\" }, props { material = DIAMOND } }]` на item.",
+      "hints": [
+        "`bindings` это список (`[...]`) объектов-binding'ов. У каждого binding'а - `rules` и `props`.",
+        "Внутри `props` пиши любой item-scope ключ который хочешь перекрыть - здесь просто `material = DIAMOND`.",
+        "```\nbindings = [\n  {\n    rules { permission = \"vip\" }\n    props { material = DIAMOND }\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/lessons/29-rules-world.json b/src/lib/playground/tutorial/lessons/29-rules-world.json
new file mode 100644
index 0000000..5189dc4
--- /dev/null
+++ b/src/lib/playground/tutorial/lessons/29-rules-world.json
@@ -0,0 +1,41 @@
+{
+  "id": "29-rules-world",
+  "title": "World/gamemode rules + multi-rule blocks",
+  "topic": "conditions",
+  "intro": "[`rules`](wiki:rules) works in three places, each with slightly different meaning:\n\n- on a **`click`** - gates the actions (lesson 26)\n- inside a **`binding`** - gates the props swap (lesson 27)\n- on an **`item`** itself - gates the **[visibility](wiki:display-rules)** of the slot (this lesson)\n\nWhen rules on an item fail, the slot is just not rendered - the player sees an empty inventory cell.\n\nMultiple rule keys in one block are **AND**-ed:\n\n```\nitems = [\n  {\n    slot = 4\n    material = ENDER_PEARL\n    name = \"&aLobby teleport\"\n    rules {\n      world = \"lobby\"\n      gamemode = \"SURVIVAL\"\n    }\n    click { actions { command = \"warp spawn\" } }\n  }\n]\n```\n\nThe pearl shows up only for survival players in the `lobby` world. Anyone else sees an empty slot.\n\nFor **OR** logic, write multiple bindings (each its own rule set) or use the more advanced `if`/`js` rule kinds.\n\n**Goal:** put the existing item under `rules { world = \"lobby\" }` so it only shows in the lobby world.",
+  "starter": "title = \"Lobby\"\nsize = 3\nitems = [\n  {\n    slot = 4\n    material = ENDER_PEARL\n    name = \"&aSpawn\"\n    click { actions { command = \"warp spawn\" } }\n  }\n]\n",
+  "goal": "Add `rules { world = \"lobby\" }` directly inside the item (sibling of `click`).",
+  "check": {
+    "type": "shape",
+    "asserts": [
+      {
+        "kind": "eq",
+        "path": "items[0].rules.world",
+        "value": "lobby"
+      },
+      {
+        "kind": "eq",
+        "path": "items[0].click.actions.command",
+        "value": "warp spawn"
+      }
+    ]
+  },
+  "hints": [
+    "On the **item** (not on click), add `rules { world = \"lobby\" }` next to the `click` block.",
+    "It's the same `rules` shape as on click, just one level higher in the structure.",
+    "```\nitems = [\n  {\n    slot = 4\n    material = ENDER_PEARL\n    name = \"&aSpawn\"\n    rules { world = \"lobby\" }\n    click { actions { command = \"warp spawn\" } }\n  }\n]\n```"
+  ],
+  "next": null,
+  "translations": {
+    "ru": {
+      "title": "Rules world/gamemode + multi-rule блоки",
+      "intro": "[`rules`](wiki:rules) работает в трёх местах, в каждом немного другой смысл:\n\n- на **`click`** - гейтит actions (урок 26)\n- внутри **`binding`** - гейтит swap props (урок 27)\n- на **`item`** - гейтит **[видимость](wiki:display-rules)** слота (этот урок)\n\nКогда rules на item не прошли - слот просто не рендерится, игрок видит пустую ячейку инвентаря.\n\nНесколько правил в одном блоке - **AND**:\n\n```\nitems = [\n  {\n    slot = 4\n    material = ENDER_PEARL\n    name = \"&aLobby teleport\"\n    rules {\n      world = \"lobby\"\n      gamemode = \"SURVIVAL\"\n    }\n    click { actions { command = \"warp spawn\" } }\n  }\n]\n```\n\nЖемчуг показывается только survival-игрокам в мире `lobby`. Остальные видят пустой слот.\n\nДля **OR** логики используй несколько bindings (каждый со своим набором правил) или продвинутые `if`/`js` rules.\n\n**Цель:** оберни существующий item в `rules { world = \"lobby\" }` чтобы он показывался только в мире lobby.",
+      "goal": "Добавь `rules { world = \"lobby\" }` прямо внутри item (sibling `click`).",
+      "hints": [
+        "На **item** (не на click) добавь `rules { world = \"lobby\" }` рядом с блоком `click`.",
+        "Тот же `rules` что и на click, просто на уровень выше.",
+        "```\nitems = [\n  {\n    slot = 4\n    material = ENDER_PEARL\n    name = \"&aSpawn\"\n    rules { world = \"lobby\" }\n    click { actions { command = \"warp spawn\" } }\n  }\n]\n```"
+      ]
+    }
+  }
+}
diff --git a/src/lib/playground/tutorial/markdown.test.ts b/src/lib/playground/tutorial/markdown.test.ts
new file mode 100644
index 0000000..09b803f
--- /dev/null
+++ b/src/lib/playground/tutorial/markdown.test.ts
@@ -0,0 +1,167 @@
+import { describe, test, expect } from 'vitest';
+import { renderMd, renderInlineMd } from './markdown';
+
+describe('renderMd', () => {
+  test('paragraph wraps in <p>', () => {
+    expect(renderMd('hello')).toBe('<p>hello</p>');
+  });
+
+  test('two paragraphs', () => {
+    expect(renderMd('first\n\nsecond')).toBe('<p>first</p>\n<p>second</p>');
+  });
+
+  test('bold', () => {
+    expect(renderMd('a **bold** word')).toBe('<p>a <strong>bold</strong> word</p>');
+  });
+
+  test('inline code', () => {
+    expect(renderMd('use `title = "x"`')).toBe('<p>use <code>title = "x"</code></p>');
+  });
+
+  test('list block', () => {
+    expect(renderMd('- one\n- two')).toBe('<ul><li>one</li><li>two</li></ul>');
+  });
+
+  test('escapes html', () => {
+    expect(renderMd('<script>')).toBe('<p>&lt;script&gt;</p>');
+  });
+
+  test('http link renders as anchor with safe attrs', () => {
+    expect(renderMd('see [the spec](https://example.com/foo) here')).toBe(
+      '<p>see <a href="https://example.com/foo" target="_blank" rel="noopener noreferrer">the spec</a> here</p>',
+    );
+  });
+
+  test('http (non-https) link is allowed', () => {
+    const out = renderMd('[old](http://example.com)');
+    expect(out).toContain('href="http://example.com"');
+  });
+
+  test('non-http scheme is neutralised to #', () => {
+    const out = renderMd('[evil](javascript:alert(1))');
+    expect(out).toContain('href="#"');
+    expect(out).not.toContain('javascript:');
+  });
+
+  test('same-origin path is allowed for links', () => {
+    const out = renderMd('[docs](/docs/start/)');
+    expect(out).toContain('href="/docs/start/"');
+  });
+
+  test('schemeless relative path (no leading /) is neutralised', () => {
+    const out = renderMd('[oops](relative/path)');
+    expect(out).toContain('href="#"');
+  });
+
+  test('link inside code is left alone', () => {
+    const out = renderMd('use `[label](url)` syntax');
+    // Code wraps first, so the brackets+parens stay literal inside the
+    // <code> tag and the link regex never matches.
+    expect(out).toBe('<p>use <code>[label](url)</code> syntax</p>');
+  });
+});
+
+describe('fenced code blocks', () => {
+  // Use `text` lang to opt out of HOCON highlighting where the test is
+  // about structural rendering (escaping, blank-line preservation, etc.).
+  test('single fenced block (text) renders as <pre><code>', () => {
+    const out = renderMd('```text\nfoo\n```');
+    expect(out).toBe('<pre><code>foo</code></pre>');
+  });
+
+  test('default lang highlights as HOCON', () => {
+    // The string token should be wrapped in cm-tk-string regardless of how
+    // the rest of the line is split.
+    const out = renderMd('```\ntitle = "x"\n```');
+    expect(out).toContain('cm-tk-string');
+    expect(out).toContain('"x"');
+  });
+
+  test('explicit hocon lang highlights too', () => {
+    const out = renderMd('```hocon\nsize = 3\n```');
+    expect(out).toContain('cm-tk-number');
+  });
+
+  test('non-hocon lang skips highlighting', () => {
+    const out = renderMd('```bash\nls -la\n```');
+    expect(out).toBe('<pre><code>ls -la</code></pre>');
+  });
+
+  test('fence preserves blank lines inside content', () => {
+    const out = renderMd('```text\nline1\n\nline2\n```');
+    expect(out).toBe('<pre><code>line1\n\nline2</code></pre>');
+  });
+
+  test('html inside fence is escaped', () => {
+    const out = renderMd('```text\n<script>\n```');
+    expect(out).toBe('<pre><code>&lt;script&gt;</code></pre>');
+  });
+
+  test('paragraph + fence + paragraph all render in order', () => {
+    const out = renderMd('intro text\n\n```text\ncode\n```\n\noutro text');
+    expect(out).toBe('<p>intro text</p>\n<pre><code>code</code></pre>\n<p>outro text</p>');
+  });
+
+  test('fence content is not run through inline transforms', () => {
+    // **bold** and `inline-code` syntax inside the fence stays literal.
+    const out = renderMd('```text\n**not bold** `not code`\n```');
+    expect(out).toBe('<pre><code>**not bold** `not code`</code></pre>');
+  });
+});
+
+describe('renderInlineMd', () => {
+  test('renders code without paragraph wrap', () => {
+    expect(renderInlineMd('set `size = 3`')).toBe('set <code>size = 3</code>');
+  });
+
+  test('bold + code combine', () => {
+    expect(renderInlineMd('**Set** `key`')).toBe('<strong>Set</strong> <code>key</code>');
+  });
+
+  test('link works inline', () => {
+    expect(renderInlineMd('see [docs](https://example.com)')).toBe(
+      'see <a href="https://example.com" target="_blank" rel="noopener noreferrer">docs</a>',
+    );
+  });
+
+  test('escapes raw html', () => {
+    expect(renderInlineMd('<script>')).toBe('&lt;script&gt;');
+  });
+
+  test('image renders as <img> with alt and lazy loading', () => {
+    expect(renderInlineMd('see ![diagram](/img/foo.png)')).toBe(
+      'see <img src="/img/foo.png" alt="diagram" loading="lazy">',
+    );
+  });
+
+  test('image with https url is allowed', () => {
+    const out = renderInlineMd('![pic](https://example.com/x.png)');
+    expect(out).toContain('src="https://example.com/x.png"');
+  });
+
+  test('image with javascript: url is dropped', () => {
+    // Markdown image syntax doesn't allow `)` inside the URL, so we use a
+    // simpler payload; the safety check rejects any non-http(s)/non-/ url.
+    expect(renderInlineMd('![oops](javascript:alert)')).toBe('');
+  });
+
+  test('image is matched before link (no leftover `!`)', () => {
+    expect(renderInlineMd('![alt](/p.png)')).toBe('<img src="/p.png" alt="alt" loading="lazy">');
+  });
+
+  test('link with same-origin path is allowed', () => {
+    const out = renderInlineMd('see [docs](/docs/start/)');
+    expect(out).toContain('href="/docs/start/"');
+  });
+
+  test('wiki: scheme resolves to a docs URL', () => {
+    const out = renderInlineMd('learn about [click](wiki:click)');
+    expect(out).toContain('href="/docs/en/general/menu-structure/');
+    expect(out).toContain('target="_blank"');
+  });
+
+  test('wiki: with unknown concept becomes a # link', () => {
+    const out = renderInlineMd('[broken](wiki:does-not-exist)');
+    expect(out).toContain('href="#"');
+  });
+});
diff --git a/src/lib/playground/tutorial/markdown.ts b/src/lib/playground/tutorial/markdown.ts
new file mode 100644
index 0000000..aeab4e8
--- /dev/null
+++ b/src/lib/playground/tutorial/markdown.ts
@@ -0,0 +1,135 @@
+import { highlightHocon } from './highlight-hocon';
+import { resolveWikiUrl } from './wiki-links';
+
+/**
+ * Tiny markdown renderer for lesson intros. Supports paragraphs (blank-line
+ * separated), `**bold**`, `` `code` ``, `[text](https://...)` links,
+ * `![alt](url)` images, `- list` lines, and triple-backtick fenced code
+ * blocks. No headings. Swap to marked/remark if richer markup is needed
+ * (~30KB bundle).
+ *
+ * Fenced blocks with the default language (no tag) or an explicit `hocon`
+ * tag are syntax-highlighted using the same tokeniser the editor uses;
+ * other lang tags fall through to plain text.
+ *
+ * URL safety: only http(s) URLs and same-origin paths starting with `/`
+ * are accepted for links and images; anything else (e.g. `javascript:`)
+ * collapses to `#`. Links open in a new tab with `noopener noreferrer`.
+ */
+// 0x03 (ETX) - never appears in lesson sources; used as a placeholder
+// sentinel so blank lines inside fenced code blocks don't get mistaken for
+// paragraph breaks during the split below.
+const FENCE_MARK = String.fromCharCode(3);
+
+interface Fence {
+  lang: string;
+  content: string;
+}
+
+export function renderMd(input: string): string {
+  // Stash fenced code blocks first so blank lines INSIDE them don't split
+  // them when we paragraph-split below. Each fence becomes a single token
+  // that we recognise after splitting and render as <pre><code>.
+  const fences: Fence[] = [];
+  const stashed = input.replace(/```([^\n]*)\n([\s\S]*?)\n```/g, (_m, lang, content) => {
+    fences.push({ lang: lang.trim(), content });
+    return `\n\n${FENCE_MARK}${fences.length - 1}${FENCE_MARK}\n\n`;
+  });
+
+  // Drop empty blocks introduced by the fence-stash padding (`\n\n...\n\n`)
+  // so the output doesn't get sprinkled with `<p></p>` around fences.
+  const blocks = stashed.split(/\n{2,}/).filter((b) => b.trim().length > 0);
+  return blocks.map((b) => {
+    const m = b.trim().match(new RegExp(`^${FENCE_MARK}(\\d+)${FENCE_MARK}$`));
+    if (m) {
+      const fence = fences[Number(m[1])];
+      const isHocon = fence.lang === '' || fence.lang === 'hocon';
+      const inner = isHocon ? highlightHocon(fence.content) : escapeHtml(fence.content);
+      return `<pre><code>${inner}</code></pre>`;
+    }
+    return renderBlock(b);
+  }).join('\n');
+}
+
+function renderBlock(block: string): string {
+  const lines = block.split('\n');
+  const allList = lines.length > 0 && lines.every((l) => /^\s*-\s+/.test(l));
+  if (allList) {
+    const items = lines
+      .map((l) => `<li>${renderInline(l.replace(/^\s*-\s+/, ''))}</li>`)
+      .join('');
+    return `<ul>${items}</ul>`;
+  }
+  return `<p>${renderInline(block)}</p>`;
+}
+
+// Control-char placeholders used to stash code-span contents out of band
+// while link/bold/escape transforms run. SOH/STX (0x01/0x02) are not valid
+// in any reasonable lesson source - collisions aren't a real concern.
+const STASH_OPEN = '
';
+const STASH_CLOSE = '';
+const STASH_RE = new RegExp(`${STASH_OPEN}(\\d+)${STASH_CLOSE}`, 'g');
+
+/**
+ * Inline-only variant of renderMd for one-liners (lesson goal text, etc.).
+ * Same code/bold/link pipeline as paragraphs, but doesn't wrap in `<p>` so
+ * the result drops cleanly into a host element with its own layout.
+ */
+export function renderInlineMd(s: string): string {
+  return renderInline(s);
+}
+
+function renderInline(s: string): string {
+  // Pull code spans out first so other transforms don't rewrite them.
+  // Restored at the end with their original text intact (and HTML-escaped).
+  const codeStash: string[] = [];
+  const withoutCode = s.replace(/`([^`]+)`/g, (_m, code) => {
+    codeStash.push(code);
+    return `${STASH_OPEN}${codeStash.length - 1}${STASH_CLOSE}`;
+  });
+
+  const transformed = escapeHtml(withoutCode)
+    // Image must come before link: `![alt](url)` would otherwise match the
+    // link regex with the literal `!` left dangling outside the anchor.
+    .replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (_m, alt, url) => {
+      const safe = isSafeUrl(url) ? url : '';
+      if (!safe) return '';
+      return `<img src="${safe}" alt="${alt}" loading="lazy">`;
+    })
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, label, url) => {
+      // Custom `wiki:concept` scheme - resolve to a per-locale docs URL.
+      // Unknown concepts collapse to `#` so the broken link is visible.
+      if (url.startsWith('wiki:')) {
+        const resolved = resolveWikiUrl(url.slice(5));
+        const safe = resolved && isSafeUrl(resolved) ? resolved : '#';
+        return `<a href="${safe}" target="_blank" rel="noopener noreferrer">${label}</a>`;
+      }
+      const safe = isSafeUrl(url) ? url : '#';
+      return `<a href="${safe}" target="_blank" rel="noopener noreferrer">${label}</a>`;
+    })
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/\n/g, '<br>');
+
+  return transformed.replace(
+    STASH_RE,
+    (_m, idx) => `<code>${escapeHtml(codeStash[Number(idx)])}</code>`,
+  );
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Allow http(s) absolute URLs and same-origin paths starting with `/`.
+ * Anything else (javascript:, data:, vbscript:, relative `./`, ...) is
+ * rejected so an untrusted lesson contributor can't inject an XSS vector.
+ */
+function isSafeUrl(url: string): boolean {
+  if (/^https?:\/\/[^\s"<>]+$/.test(url)) return true;
+  if (/^\/[^\s"<>]*$/.test(url)) return true;
+  return false;
+}
diff --git a/src/lib/playground/tutorial/types.ts b/src/lib/playground/tutorial/types.ts
new file mode 100644
index 0000000..bde4faf
--- /dev/null
+++ b/src/lib/playground/tutorial/types.ts
@@ -0,0 +1,93 @@
+export interface RegexCheck {
+  type: 'regex';
+  pattern: string;
+  flags?: string;
+}
+
+/**
+ * Path-based assertion against the resolved JSON. Cleaner than regex once
+ * lessons start asking for nested structure - the engine parses + resolves
+ * the editor content the same way the analysis pipeline does, then walks
+ * each assert against the produced tree.
+ *
+ * Supported assert kinds:
+ *   - `has`     : path resolves to a non-undefined value
+ *   - `eq`      : path equals literal value (deep equality for objects/arrays)
+ *   - `matches` : path is a string and matches the regex pattern
+ *
+ * Path syntax is dot+bracket: `items[0].click.message`, `defaults.material`.
+ * Numeric segments inside `[]` index arrays; everything else is an object key.
+ */
+export interface ShapeAssertHas {
+  kind: 'has';
+  path: string;
+}
+export interface ShapeAssertEq {
+  kind: 'eq';
+  path: string;
+  value: unknown;
+}
+export interface ShapeAssertMatches {
+  kind: 'matches';
+  path: string;
+  pattern: string;
+  flags?: string;
+}
+export type ShapeAssert = ShapeAssertHas | ShapeAssertEq | ShapeAssertMatches;
+
+export interface ShapeCheck {
+  type: 'shape';
+  asserts: ShapeAssert[];
+}
+
+export type CheckSpec = RegexCheck | ShapeCheck;
+
+/**
+ * Per-locale overrides for the human-readable parts of a lesson. `starter`
+ * and `check` stay in the base lesson because they're code/regex, not prose.
+ * Community contributors add a translation by dropping a new key into
+ * `translations` - no loader change required.
+ */
+export interface LessonTranslation {
+  title?: string;
+  intro?: string;
+  goal?: string;
+  hints?: string[];
+}
+
+export interface Lesson {
+  id: string;
+  title: string;
+  /**
+   * Topic slug (required). Used to group lessons in the navigation popup
+   * and as a translation-key suffix: `topic.<slug>` is rendered to the
+   * user-facing label. Keep slugs ascii-kebab-case (e.g. "basics").
+   */
+  topic: string;
+  /**
+   * Optional sub-grouping within a topic. Same conventions as `topic`.
+   * Lessons without a subtopic appear directly under their topic.
+   */
+  subtopic?: string;
+  intro: string;
+  starter: string;
+  goal: string;
+  check: CheckSpec;
+  hints: string[];
+  next?: string | null;
+  translations?: Record<string, LessonTranslation>;
+}
+
+export interface Progress {
+  current: string;
+  completed: string[];
+  skipped: string[];
+  hintsUsed: Record<string, number>;
+}
+
+export const EMPTY_PROGRESS: Progress = {
+  current: '',
+  completed: [],
+  skipped: [],
+  hintsUsed: {},
+};
diff --git a/src/lib/playground/tutorial/wiki-links.test.ts b/src/lib/playground/tutorial/wiki-links.test.ts
new file mode 100644
index 0000000..ddac1ba
--- /dev/null
+++ b/src/lib/playground/tutorial/wiki-links.test.ts
@@ -0,0 +1,55 @@
+import { describe, test, expect, beforeEach } from 'vitest';
+import { resolveWikiUrl, hasWikiConcept } from './wiki-links';
+import { setLang, _resetForTests } from '../i18n';
+
+beforeEach(() => { _resetForTests(); });
+
+describe('resolveWikiUrl', () => {
+  test('returns en URL by default', () => {
+    expect(resolveWikiUrl('click')).toContain('/docs/en/');
+  });
+
+  test('returns ru URL when active lang is ru', () => {
+    setLang('ru');
+    expect(resolveWikiUrl('click')).toContain('/docs/ru/');
+  });
+
+  test('falls back to en if ru entry missing', () => {
+    setLang('ru');
+    // `items` may not have a ru-specific entry distinct from en, but it
+    // should still return a URL (either ru fallback to en path).
+    const url = resolveWikiUrl('items');
+    expect(url).not.toBeNull();
+    expect(url).toContain('/docs/');
+  });
+
+  test('returns null for unknown concept', () => {
+    expect(resolveWikiUrl('does-not-exist')).toBeNull();
+  });
+
+  test('cyrillic anchor is percent-encoded in href', () => {
+    setLang('ru');
+    const url = resolveWikiUrl('click')!;
+    // Russian anchor "обработка-кликов" should appear as %D0%BE...
+    expect(url).toContain('%D0%BE');
+    expect(url).not.toContain('обработка');
+  });
+
+  test('hasWikiConcept reflects registry membership', () => {
+    expect(hasWikiConcept('click')).toBe(true);
+    expect(hasWikiConcept('not-a-thing')).toBe(false);
+  });
+
+  test('every wiki: ref in shipped lessons resolves to a registered concept', async () => {
+    const { listLessons } = await import('./lessons');
+    const refs = new Set<string>();
+    for (const l of listLessons()) {
+      const texts: string[] = [l.intro, ...l.hints];
+      for (const t of texts) {
+        for (const m of t.matchAll(/wiki:([\w.-]+)/g)) refs.add(m[1]);
+      }
+    }
+    const orphans = [...refs].filter((c) => !hasWikiConcept(c));
+    expect(orphans).toEqual([]);
+  });
+});
diff --git a/src/lib/playground/tutorial/wiki-links.ts b/src/lib/playground/tutorial/wiki-links.ts
new file mode 100644
index 0000000..69bf62d
--- /dev/null
+++ b/src/lib/playground/tutorial/wiki-links.ts
@@ -0,0 +1,164 @@
+import { getLang } from '../i18n';
+
+/**
+ * Concept -> per-locale documentation URL. Used by lesson markdown via the
+ * `[label](wiki:concept)` syntax, resolved at render time against the
+ * active language so a Russian-locale user lands on the Russian doc page,
+ * etc.
+ *
+ * URLs include the `/docs/<lang>/` base. Anchor fragments are encoded
+ * (Cyrillic anchors must be percent-encoded for href correctness).
+ *
+ * Add a new entry here whenever a lesson wants to deep-link to a wiki
+ * concept; missing locale variants gracefully fall back to `en`.
+ */
+export interface WikiEntry {
+  en: string;
+  ru?: string;
+}
+
+const PERCENT_ENCODE_ANCHOR = (s: string): string =>
+  s.replace(/#(.+)$/, (_, anchor) => '#' + encodeURIComponent(anchor));
+
+const RAW: Record<string, WikiEntry> = {
+  // --- menu-structure.md sections ---
+  // Click handling (item.click block, scope: click)
+  click: {
+    en: '/docs/en/general/menu-structure/#click-processing',
+    ru: '/docs/ru/general/menu-structure/#обработка-кликов',
+  },
+  // Items array (top-level "buttons" section)
+  items: {
+    en: '/docs/en/general/menu-structure/#buttons',
+    ru: '/docs/ru/general/menu-structure/#кнопки',
+  },
+  // Menu-level properties (size, title, updateInterval, ...)
+  size: {
+    en: '/docs/en/general/menu-structure/#menu-properties',
+    ru: '/docs/ru/general/menu-structure/#свойства-меню',
+  },
+  // Per-item display rules (visibility gating)
+  'display-rules': {
+    en: '/docs/en/general/menu-structure/#display-rules',
+    ru: '/docs/ru/general/menu-structure/#правила-отображения',
+  },
+  // Bindings: per-player property swap based on rules
+  bindings: {
+    en: '/docs/en/general/menu-structure/#binding-button-properties-to-rules',
+    ru: '/docs/ru/general/menu-structure/#привязка-свойств-кнопки-к-правилам',
+  },
+
+  // --- item-format.md sections ---
+  // Item format root (all per-item fields)
+  'item-format': {
+    en: '/docs/en/general/item-format/',
+    ru: '/docs/ru/general/item-format/',
+  },
+  // Slot positions (4 forms - index, range, x/y, matrix)
+  slot: {
+    en: '/docs/en/general/item-format/#slot',
+    ru: '/docs/ru/general/item-format/#слот',
+  },
+  // count + cooldown (and other slot-adjacent fields)
+  cooldown: {
+    en: '/docs/en/general/item-format/#slot-and-cooldown',
+    ru: '/docs/ru/general/item-format/#слот-и-кулдаун',
+  },
+  // Display section: name, lore, material, flags
+  display: {
+    en: '/docs/en/general/item-format/#display',
+    ru: '/docs/ru/general/item-format/#отображение',
+  },
+  // Mechanics: enchantments, effects, firework, etc.
+  mechanics: {
+    en: '/docs/en/general/item-format/#mechanics',
+    ru: '/docs/ru/general/item-format/#механики',
+  },
+
+  // --- standalone reference pages ---
+  actions: {
+    en: '/docs/en/general/actions/#all-actions',
+    ru: '/docs/ru/general/actions/#все-действия',
+  },
+  // Per-action anchors. Headings in actions.md are English in both
+  // locales (## Message / ## Command / ...), so slugs are identical.
+  'action.message': {
+    en: '/docs/en/general/actions/#message',
+    ru: '/docs/ru/general/actions/#message',
+  },
+  'action.command': {
+    en: '/docs/en/general/actions/#command',
+    ru: '/docs/ru/general/actions/#command',
+  },
+  'action.sound': {
+    en: '/docs/en/general/actions/#sound',
+    ru: '/docs/ru/general/actions/#sound',
+  },
+  'action.teleport': {
+    en: '/docs/en/general/actions/#teleport',
+    ru: '/docs/ru/general/actions/#teleport',
+  },
+  'action.delay': {
+    en: '/docs/en/general/actions/#delay',
+    ru: '/docs/ru/general/actions/#delay',
+  },
+  'action.bulk': {
+    en: '/docs/en/general/actions/#bulk',
+    ru: '/docs/ru/general/actions/#bulk',
+  },
+  rules: {
+    en: '/docs/en/general/rules/#all-rules',
+    ru: '/docs/ru/general/rules/#все-правила',
+  },
+  variables: {
+    en: '/docs/en/general/variables/',
+    ru: '/docs/ru/general/variables/',
+  },
+  placeholders: {
+    en: '/docs/en/general/placeholders/#built-in-placeholders',
+    ru: '/docs/ru/general/placeholders/#встроенные-плейсхолдеры',
+  },
+  activators: {
+    en: '/docs/en/general/activators/#all-activators',
+    ru: '/docs/ru/general/activators/#все-активаторы',
+  },
+  // HOCON syntax overview (covers include, value types, etc.)
+  hocon: {
+    en: '/docs/en/start/hocon/#basic-hocon-syntax',
+    ru: '/docs/ru/start/hocon/#базовый-синтаксис-hocon',
+  },
+  // Templates / DRY patterns (defaults, includes)
+  templates: {
+    en: '/docs/en/advanced/templates/#templates-basics',
+    ru: '/docs/ru/advanced/templates/#основы-шаблонов',
+  },
+  // Templates pulled from a separate include file (the "include" pattern)
+  'templates.include': {
+    en: '/docs/en/advanced/templates/#templates-in-separate-file',
+    ru: '/docs/ru/advanced/templates/#шаблоны-в-отдельном-файле',
+  },
+};
+
+const REGISTRY: Record<string, WikiEntry> = Object.fromEntries(
+  Object.entries(RAW).map(([k, v]) => [k, {
+    en: PERCENT_ENCODE_ANCHOR(v.en),
+    ru: v.ru ? PERCENT_ENCODE_ANCHOR(v.ru) : undefined,
+  }]),
+);
+
+/**
+ * Look up a concept and return the URL for the active language. Falls back
+ * to English if the locale-specific URL isn't seeded. Returns null for
+ * unknown concepts (lesson author probably typo'd).
+ */
+export function resolveWikiUrl(concept: string): string | null {
+  const entry = REGISTRY[concept];
+  if (!entry) return null;
+  const lang = getLang() as keyof WikiEntry;
+  return entry[lang] ?? entry.en;
+}
+
+/** Whether a concept exists in the registry (for tests / sanity checks). */
+export function hasWikiConcept(concept: string): boolean {
+  return concept in REGISTRY;
+}
diff --git a/src/lib/playground/types.ts b/src/lib/playground/types.ts
new file mode 100644
index 0000000..554b0ab
--- /dev/null
+++ b/src/lib/playground/types.ts
@@ -0,0 +1,12 @@
+export type PlaygroundMode = 'editor' | 'tutorial';
+export type TabId = 'errors' | 'warnings' | 'json' | 'tutorial';
+
+export interface PlaygroundState {
+  mode: PlaygroundMode;
+  activeTab: TabId;
+}
+
+export interface BootOptions {
+  initialContent?: string;
+  initialMode?: PlaygroundMode;
+}
diff --git a/src/pages/playground.astro b/src/pages/playground.astro
new file mode 100644
index 0000000..364e198
--- /dev/null
+++ b/src/pages/playground.astro
@@ -0,0 +1,114 @@
+---
+// Standalone playground page. Lives outside Starlight content layout to use
+// the full viewport. Loads main.ts via <script> for client-side editor init.
+const BASE = import.meta.env.BASE_URL;
+---
+
+<!doctype html>
+<html lang="en" data-theme="dark">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>HOCON Playground — AbstractMenus</title>
+    <meta
+      name="description"
+      content="Browser playground for AbstractMenus HOCON menu configs. Validate, share, learn."
+    />
+    <link rel="icon" href={`${BASE}favicon.ico`} />
+  </head>
+  <body>
+    <div class="pg-app" data-pg-root>
+      <header class="pg-header">
+        <a class="pg-brand" href={`${BASE}en/`}>
+          <span class="pg-brand-text">AbstractMenus</span>
+          <span class="pg-brand-sub" data-i18n="brand.sub">Playground</span>
+        </a>
+        <nav class="pg-mode-switch" role="tablist" data-i18n-aria="mode.aria" aria-label="Playground mode">
+          <button type="button" class="pg-mode-btn is-active" data-mode="editor" role="tab" aria-selected="true" data-i18n="mode.editor">Editor</button>
+          <button type="button" class="pg-mode-btn" data-mode="tutorial" role="tab" aria-selected="false" data-i18n="mode.tutorial">Tutorial</button>
+        </nav>
+        <div class="pg-header-actions">
+          <select class="pg-lang-select" data-pg-lang data-i18n-aria="lang.select.aria" aria-label="Language"></select>
+          <button type="button" class="pg-icon-btn" data-action="theme-toggle" data-i18n-aria="theme.toggle.aria" aria-label="Toggle theme">
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+              <circle cx="12" cy="12" r="5"></circle>
+              <line x1="12" y1="1" x2="12" y2="3"></line>
+              <line x1="12" y1="21" x2="12" y2="23"></line>
+              <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+              <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+              <line x1="1" y1="12" x2="3" y2="12"></line>
+              <line x1="21" y1="12" x2="23" y2="12"></line>
+              <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+              <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+            </svg>
+          </button>
+        </div>
+      </header>
+
+      <main class="pg-main">
+        <section class="pg-pane pg-pane-editor" aria-label="Editor">
+          <div class="pg-editor-host" data-pg-editor></div>
+        </section>
+
+        <div class="pg-divider" data-pg-divider role="separator" aria-orientation="vertical"></div>
+
+        <section class="pg-pane pg-pane-output" aria-label="Output">
+          <nav class="pg-tabs" role="tablist">
+            <button type="button" class="pg-tab is-active" data-tab="errors" role="tab" aria-selected="true">
+              <span data-i18n="tab.errors">Errors</span><span class="pg-tab-count" data-tab-count="errors"></span>
+            </button>
+            <button type="button" class="pg-tab" data-tab="warnings" role="tab" aria-selected="false">
+              <span data-i18n="tab.warnings">Warnings</span><span class="pg-tab-count" data-tab-count="warnings"></span>
+            </button>
+            <button type="button" class="pg-tab" data-tab="json" role="tab" aria-selected="false" data-i18n="tab.json">Resolved JSON</button>
+            <button type="button" class="pg-tab is-hidden" data-tab="tutorial" role="tab" aria-selected="false" data-i18n="tab.tutorial">Tutorial</button>
+          </nav>
+          <div class="pg-tab-panels">
+            <div class="pg-tab-panel is-active" data-panel="errors" role="tabpanel">
+              <p class="pg-empty" data-i18n="empty.errors">No errors.</p>
+            </div>
+            <div class="pg-tab-panel" data-panel="warnings" role="tabpanel">
+              <p class="pg-empty" data-i18n="empty.warnings">No warnings. Warnings flag suspicious but valid configs (unknown keys, unresolved substitutions). They do not stop the menu from loading.</p>
+            </div>
+            <div class="pg-tab-panel" data-panel="json" role="tabpanel">
+              <p class="pg-empty" data-i18n="empty.json">Resolved JSON appears here once the parser is wired up.</p>
+            </div>
+            <div class="pg-tab-panel" data-panel="tutorial" role="tabpanel">
+              <p class="pg-empty" data-i18n="empty.tutorial">Tutorial mode lands at M.6.</p>
+            </div>
+          </div>
+        </section>
+      </main>
+
+      <footer class="pg-footer">
+        <span class="pg-footer-status" data-pg-status data-i18n="status.ready">ready</span>
+        <button type="button" class="pg-footer-scope" data-pg-scope-hint data-i18n-title="scope.hint.title" title="Show suggestions for the current scope">
+          <span data-i18n="scope.hint.placeholder">- keys -</span>
+        </button>
+        <div class="pg-footer-actions">
+          <div class="pg-history-wrap" data-pg-history-wrap>
+            <button type="button" class="pg-btn pg-btn-secondary" data-action="history-toggle" data-i18n="btn.history">
+              History
+            </button>
+            <div class="pg-history-pop" data-pg-history hidden></div>
+          </div>
+          <button type="button" class="pg-btn pg-btn-secondary" data-action="toggle-warning-squiggles" data-state="on" data-i18n-title="btn.warnings.title.on" title="Hide warning squiggles in the editor (Warnings tab stays)" data-i18n="btn.warnings.on">
+            warnings: on
+          </button>
+          <button type="button" class="pg-btn pg-btn-secondary" data-action="format" data-i18n="btn.format" disabled>Format</button>
+          <button type="button" class="pg-btn pg-btn-secondary pg-btn-danger" data-action="reset-editor" data-mode-only="editor" data-i18n="btn.reset" data-i18n-title="btn.reset.title" title="Reset the playground to the default template">Reset</button>
+          <button type="button" class="pg-btn pg-btn-secondary" data-action="share" data-i18n="btn.share">Share</button>
+        </div>
+      </footer>
+    </div>
+
+    <script>
+      import { boot } from '../lib/playground/main';
+      boot();
+    </script>
+
+    <style is:global>
+      @import '../styles/playground.css';
+    </style>
+  </body>
+</html>
diff --git a/src/pages/playground/about.astro b/src/pages/playground/about.astro
new file mode 100644
index 0000000..6a32bb5
--- /dev/null
+++ b/src/pages/playground/about.astro
@@ -0,0 +1,72 @@
+---
+const BASE = import.meta.env.BASE_URL;
+---
+
+<!doctype html>
+<html lang="en" data-theme="dark">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>About - HOCON Playground - AbstractMenus</title>
+    <meta name="description" content="What the AbstractMenus HOCON Playground is and how to use it." />
+    <link rel="icon" href={`${BASE}favicon.ico`} />
+  </head>
+  <body>
+    <div class="pg-app pg-app-narrow">
+      <header class="pg-header">
+        <a class="pg-brand" href={`${BASE}playground/`}>
+          <span class="pg-brand-text">AbstractMenus</span>
+          <span class="pg-brand-sub">Playground</span>
+        </a>
+        <div class="pg-header-actions">
+          <a class="pg-btn pg-btn-secondary" href={`${BASE}playground/`}>Open editor</a>
+          <a class="pg-btn pg-btn-primary" href={`${BASE}playground/?mode=tutorial`}>Start tutorial</a>
+        </div>
+      </header>
+
+      <main class="pg-about">
+        <h1>HOCON Playground</h1>
+        <p>Browser-side editor for AbstractMenus menu configs. No server, no install. Edit, validate, share.</p>
+
+        <h2>Two modes</h2>
+        <ul>
+          <li><strong>Editor</strong> - paste your <code>menu.conf</code>, see parse errors with line:col, view the resolved JSON after substitutions, share a deep-link with another author for a second pair of eyes.</li>
+          <li><strong>Tutorial</strong> - short lessons on HOCON syntax. Each lesson has a goal, progressive hints, and a check that fires as you type. Progress is saved in your browser.</li>
+        </ul>
+
+        <h2>What it does</h2>
+        <ul>
+          <li>HOCON syntax highlighting (comments, keys, strings, substitutions, durations, includes)</li>
+          <li>Live parse + diagnostics with squiggles in the editor and a list of errors on the right</li>
+          <li>Resolved JSON view after <code>{`\${var}`}</code> substitutions and override merges</li>
+          <li>Scope-aware autocomplete - inside <code>actions {`{}`}</code> it suggests action types, inside <code>rules {`{}`}</code> it suggests rules, etc.</li>
+          <li>Enum value completion for <code>material:</code> and <code>sound:</code> (~150 popular Bukkit materials, ~80 sounds)</li>
+          <li>Hover docs on known keys</li>
+          <li>10 starter snippets for common blocks (<code>menu</code>, <code>item</code>, <code>clickaction</code>, ...)</li>
+          <li>Format command (<kbd>Cmd+Shift+F</kbd> / <kbd>Ctrl+Shift+F</kbd>)</li>
+          <li>Shareable URL via <code>#config=...</code> (deflate + base64-url)</li>
+          <li>LocalStorage history (last 5 versions)</li>
+          <li>Light / dark themes</li>
+        </ul>
+
+        <h2>Limitations (MVP)</h2>
+        <ul>
+          <li>No semantic schema validation yet (only HOCON syntax + warnings for unknown substitutions)</li>
+          <li>No inventory preview - the playground does not render the resulting Minecraft menu</li>
+          <li><code>include</code> directives produce a warning and are otherwise ignored (no virtual filesystem)</li>
+          <li>Material / sound autocomplete is a curated subset, not the full Bukkit enums</li>
+        </ul>
+
+        <h2>Open it</h2>
+        <p>
+          <a class="pg-btn pg-btn-primary" href={`${BASE}playground/`}>Open editor</a>
+          <a class="pg-btn pg-btn-secondary" href={`${BASE}playground/?mode=tutorial`}>Start tutorial</a>
+        </p>
+      </main>
+    </div>
+
+    <style is:global>
+      @import '../../styles/playground.css';
+    </style>
+  </body>
+</html>
diff --git a/src/styles/playground.css b/src/styles/playground.css
new file mode 100644
index 0000000..0b85f2f
--- /dev/null
+++ b/src/styles/playground.css
@@ -0,0 +1,989 @@
+/* Standalone playground page styles. Scoped via the page <style is:global>
+   import in playground.astro. Not included in astro.config.mjs customCss
+   so they don't leak to the rest of the docs site. */
+
+:root {
+  --pg-bg: #0d1117;
+  --pg-bg-elev: #161b22;
+  --pg-bg-elev-2: #1f2630;
+  --pg-fg: #e6edf3;
+  --pg-fg-muted: #8b949e;
+  --pg-border: #30363d;
+  --pg-accent: #f05454;
+  --pg-accent-soft: rgba(240, 84, 84, 0.15);
+  --pg-shadow: 0 1px 0 rgba(255, 255, 255, 0.04) inset, 0 0 0 1px var(--pg-border);
+  --pg-header-h: 56px;
+  --pg-footer-h: 36px;
+  --pg-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+  --pg-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+}
+
+:root[data-theme="light"] {
+  --pg-bg: #ffffff;
+  --pg-bg-elev: #f6f8fa;
+  --pg-bg-elev-2: #eaeef2;
+  --pg-fg: #1f2328;
+  --pg-fg-muted: #59636e;
+  --pg-border: #d1d9e0;
+  --pg-accent: #d63b3b;
+  --pg-accent-soft: rgba(214, 59, 59, 0.12);
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  padding: 0;
+  height: 100%;
+  background: var(--pg-bg);
+  color: var(--pg-fg);
+  font-family: var(--pg-sans);
+  -webkit-font-smoothing: antialiased;
+}
+
+.pg-app {
+  display: grid;
+  grid-template-rows: var(--pg-header-h) 1fr var(--pg-footer-h);
+  height: 100vh;
+}
+
+/* Header */
+.pg-header {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 0 1rem;
+  background: var(--pg-bg-elev);
+  border-bottom: 1px solid var(--pg-border);
+}
+.pg-brand {
+  display: flex;
+  align-items: baseline;
+  gap: 0.5rem;
+  text-decoration: none;
+  color: var(--pg-fg);
+}
+.pg-brand-text {
+  font-weight: 700;
+  letter-spacing: -0.01em;
+}
+.pg-brand-sub {
+  font-size: 0.8rem;
+  color: var(--pg-fg-muted);
+  padding: 0.1rem 0.5rem;
+  border: 1px solid var(--pg-border);
+  border-radius: 4px;
+}
+.pg-mode-switch {
+  display: flex;
+  gap: 0.25rem;
+  padding: 0.2rem;
+  background: var(--pg-bg-elev-2);
+  border: 1px solid var(--pg-border);
+  border-radius: 6px;
+}
+.pg-mode-btn {
+  font: inherit;
+  font-size: 0.85rem;
+  padding: 0.3rem 0.75rem;
+  border: 0;
+  background: transparent;
+  color: var(--pg-fg-muted);
+  border-radius: 4px;
+  cursor: pointer;
+}
+.pg-mode-btn.is-active {
+  background: var(--pg-accent);
+  color: white;
+}
+.pg-header-actions {
+  margin-left: auto;
+  display: flex;
+  gap: 0.5rem;
+}
+.pg-icon-btn {
+  width: 32px;
+  height: 32px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: 1px solid var(--pg-border);
+  color: var(--pg-fg);
+  border-radius: 6px;
+  cursor: pointer;
+}
+.pg-icon-btn:hover {
+  background: var(--pg-bg-elev-2);
+}
+.pg-lang-select {
+  height: 32px;
+  padding: 0 0.5rem;
+  background: transparent;
+  border: 1px solid var(--pg-border);
+  color: var(--pg-fg);
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 0.85rem;
+  font-family: inherit;
+}
+.pg-lang-select:hover {
+  background: var(--pg-bg-elev-2);
+}
+.pg-lang-select option {
+  background: var(--pg-bg);
+  color: var(--pg-fg);
+}
+
+/* Main two-pane */
+.pg-main {
+  display: grid;
+  grid-template-columns: 1fr 6px 1fr;
+  min-height: 0;
+}
+.pg-pane {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  background: var(--pg-bg);
+}
+.pg-divider {
+  background: var(--pg-border);
+  cursor: col-resize;
+}
+.pg-editor-host {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+.pg-editor-host .cm-editor {
+  height: 100%;
+  font-family: var(--pg-mono);
+  font-size: 13px;
+  background: var(--pg-bg);
+  color: var(--pg-fg);
+}
+.pg-editor-host .cm-scroller {
+  font-family: var(--pg-mono);
+}
+.pg-editor-host .cm-content { caret-color: var(--pg-fg); }
+.pg-editor-host .cm-cursor,
+.pg-editor-host .cm-dropCursor {
+  border-left-color: var(--pg-fg);
+}
+
+/* Gutter (line numbers, fold markers) */
+.pg-editor-host .cm-gutters {
+  background-color: var(--pg-bg);
+  color: var(--pg-fg-muted);
+  border-right: 1px solid var(--pg-border);
+}
+.pg-editor-host .cm-activeLineGutter {
+  background-color: var(--pg-bg-elev-2);
+  color: var(--pg-fg);
+}
+.pg-editor-host .cm-activeLine {
+  background-color: color-mix(in srgb, var(--pg-fg) 6%, transparent);
+}
+.pg-editor-host .cm-foldPlaceholder {
+  background-color: var(--pg-bg-elev-2);
+  color: var(--pg-fg-muted);
+  border: 1px solid var(--pg-border);
+}
+
+/* Selection */
+.pg-editor-host .cm-editor .cm-selectionBackground,
+.pg-editor-host .cm-editor.cm-focused .cm-selectionBackground,
+.pg-editor-host .cm-editor ::selection {
+  background-color: var(--pg-accent-soft) !important;
+}
+.pg-editor-host .cm-selectionMatch {
+  background-color: color-mix(in srgb, var(--pg-fg) 10%, transparent);
+}
+
+/* Search panel + autocomplete tooltips */
+.cm-tooltip,
+.cm-panels {
+  background-color: var(--pg-bg-elev) !important;
+  color: var(--pg-fg) !important;
+  border: 1px solid var(--pg-border) !important;
+}
+.cm-tooltip.cm-tooltip-autocomplete > ul > li {
+  color: var(--pg-fg);
+  padding: 0.15rem 0.5rem;
+}
+.cm-tooltip.cm-tooltip-autocomplete > ul > li[aria-selected] {
+  background-color: var(--pg-accent);
+  color: white;
+}
+.cm-tooltip.cm-tooltip-autocomplete > ul > li[aria-selected] .cm-completionDetail,
+.cm-tooltip.cm-tooltip-autocomplete > ul > li[aria-selected] .cm-completionMatchedText {
+  color: white;
+}
+.cm-completionDetail {
+  color: var(--pg-fg-muted);
+  font-style: normal;
+  margin-left: 0.5rem;
+  font-size: 0.78rem;
+}
+.cm-completionLabel { font-family: var(--pg-mono); }
+.cm-completionMatchedText {
+  color: var(--pg-accent);
+  text-decoration: none;
+  font-weight: 600;
+}
+.cm-tooltip.cm-completionInfo {
+  background-color: var(--pg-bg-elev) !important;
+  color: var(--pg-fg) !important;
+  border: 1px solid var(--pg-border) !important;
+  padding: 0.4rem 0.6rem;
+  max-width: 280px;
+  font-family: var(--pg-sans);
+  font-size: 0.78rem;
+  line-height: 1.4;
+}
+
+/* Search panel inputs */
+.cm-panel.cm-search input,
+.cm-panel.cm-search button {
+  background: var(--pg-bg-elev-2);
+  color: var(--pg-fg);
+  border: 1px solid var(--pg-border);
+}
+.cm-panel.cm-search label { color: var(--pg-fg-muted); }
+
+/* Lint diagnostics popup */
+.cm-diagnostic {
+  border-left: 3px solid var(--pg-accent);
+  padding: 0.25rem 0.5rem;
+}
+.cm-diagnostic-error { border-left-color: #f85149; }
+.cm-diagnostic-warning { border-left-color: #d29922; }
+:root[data-theme="light"] .cm-diagnostic-error { border-left-color: #cf222e; }
+:root[data-theme="light"] .cm-diagnostic-warning { border-left-color: #9a6700; }
+
+/* Squiggle underline color override (CM default uses orange-ish red even for warnings) */
+.pg-editor-host .cm-lintRange-error {
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='6' height='3'%3E%3Cpath fill='none' stroke='%23f85149' stroke-width='1' d='m0 3 l2 -2 l1 0 l2 2 l1 0'/%3E%3C/svg%3E") !important;
+  background-repeat: repeat-x !important;
+  background-position: left bottom !important;
+}
+.pg-editor-host .cm-lintRange-warning {
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='6' height='3'%3E%3Cpath fill='none' stroke='%23d29922' stroke-width='1' d='m0 3 l2 -2 l1 0 l2 2 l1 0'/%3E%3C/svg%3E") !important;
+  background-repeat: repeat-x !important;
+  background-position: left bottom !important;
+}
+:root[data-theme="light"] .pg-editor-host .cm-lintRange-error {
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='6' height='3'%3E%3Cpath fill='none' stroke='%23cf222e' stroke-width='1' d='m0 3 l2 -2 l1 0 l2 2 l1 0'/%3E%3C/svg%3E") !important;
+}
+:root[data-theme="light"] .pg-editor-host .cm-lintRange-warning {
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='6' height='3'%3E%3Cpath fill='none' stroke='%239a6700' stroke-width='1' d='m0 3 l2 -2 l1 0 l2 2 l1 0'/%3E%3C/svg%3E") !important;
+}
+
+/* Output pane */
+.pg-pane-output {
+  background: var(--pg-bg-elev);
+  border-left: 1px solid var(--pg-border);
+}
+.pg-tabs {
+  display: flex;
+  gap: 0;
+  background: var(--pg-bg-elev);
+  border-bottom: 1px solid var(--pg-border);
+}
+.pg-tab {
+  font: inherit;
+  font-size: 0.85rem;
+  padding: 0.6rem 1rem;
+  border: 0;
+  background: transparent;
+  color: var(--pg-fg-muted);
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+}
+.pg-tab.is-active {
+  color: var(--pg-fg);
+  border-bottom-color: var(--pg-accent);
+}
+.pg-tab.is-hidden {
+  display: none;
+}
+.pg-tab-count {
+  display: none;
+  margin-left: 0.35rem;
+  background: var(--pg-bg-elev-2);
+  color: var(--pg-fg-muted);
+  font-size: 0.7rem;
+  font-family: var(--pg-mono);
+  padding: 0 0.35rem;
+  border-radius: 8px;
+  min-width: 1.1rem;
+  text-align: center;
+  vertical-align: baseline;
+}
+.pg-tab-count.has-error {
+  display: inline-block;
+  background: color-mix(in srgb, #f85149 25%, transparent);
+  color: #f85149;
+}
+.pg-tab-count.has-warning {
+  display: inline-block;
+  background: color-mix(in srgb, #d29922 25%, transparent);
+  color: #d29922;
+}
+:root[data-theme="light"] .pg-tab-count.has-error { color: #cf222e; background: color-mix(in srgb, #cf222e 18%, transparent); }
+:root[data-theme="light"] .pg-tab-count.has-warning { color: #9a6700; background: color-mix(in srgb, #9a6700 18%, transparent); }
+.pg-tab-panels {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+.pg-tab-panel {
+  display: none;
+  padding: 1rem;
+  font-size: 0.875rem;
+  line-height: 1.5;
+}
+.pg-tab-panel.is-active {
+  display: block;
+}
+.pg-empty {
+  color: var(--pg-fg-muted);
+  margin: 0;
+}
+
+/* Footer */
+.pg-footer {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0 1rem;
+  background: var(--pg-bg-elev);
+  border-top: 1px solid var(--pg-border);
+  font-size: 0.8rem;
+  color: var(--pg-fg-muted);
+}
+.pg-footer-status {
+  font-family: var(--pg-mono);
+}
+.pg-footer-scope {
+  font: inherit;
+  font-size: 0.78rem;
+  font-family: var(--pg-mono);
+  color: var(--pg-fg-muted);
+  background: transparent;
+  border: 0;
+  padding: 0.15rem 0.5rem;
+  cursor: pointer;
+  border-radius: 3px;
+}
+.pg-footer-scope:hover {
+  background: var(--pg-bg-elev-2);
+  color: var(--pg-fg);
+}
+.pg-footer-scope kbd {
+  background: var(--pg-bg-elev-2);
+  border: 1px solid var(--pg-border);
+  border-radius: 3px;
+  padding: 0 0.25rem;
+  font-size: 0.7rem;
+  margin-left: 0.3rem;
+}
+.pg-footer-actions {
+  margin-left: auto;
+  display: flex;
+  gap: 0.4rem;
+}
+.pg-btn {
+  font: inherit;
+  font-size: 0.8rem;
+  padding: 0.3rem 0.7rem;
+  border: 1px solid var(--pg-border);
+  background: var(--pg-bg-elev-2);
+  color: var(--pg-fg);
+  border-radius: 4px;
+  cursor: pointer;
+}
+.pg-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.pg-btn-secondary { background: var(--pg-bg-elev-2); }
+.pg-btn-danger {
+  color: #f0a8a8;
+  border-color: #5d2a2a;
+}
+.pg-btn-danger:hover {
+  background: #4a1f1f;
+  color: #ffd0d0;
+}
+[data-theme="light"] .pg-btn-danger {
+  color: #b03030;
+  border-color: #e8b0b0;
+}
+[data-theme="light"] .pg-btn-danger:hover {
+  background: #fae0e0;
+  color: #8b1f1f;
+}
+.pg-btn[data-state="off"] {
+  opacity: 0.6;
+}
+[data-mode-only].is-hidden { display: none !important; }
+
+/* HOCON syntax highlighting (CM6 highlightStyle classes) */
+.cm-editor .cm-tk-comment      { color: #8b949e; font-style: italic; }
+.cm-editor .cm-tk-string       { color: #a5d6ff; }
+.cm-editor .cm-tk-substitution { color: #f0b070; }
+.cm-editor .cm-tk-key          { color: #79c0ff; }
+.cm-editor .cm-tk-operator     { color: #ff7b72; }
+.cm-editor .cm-tk-bracket      { color: #c9d1d9; }
+.cm-editor .cm-tk-punctuation  { color: #c9d1d9; }
+.cm-editor .cm-tk-bool         { color: #d2a8ff; }
+.cm-editor .cm-tk-null         { color: #d2a8ff; }
+.cm-editor .cm-tk-keyword      { color: #ff7b72; font-weight: 600; }
+.cm-editor .cm-tk-include-fn   { color: #f0b070; }
+.cm-editor .cm-tk-number       { color: #79c0ff; }
+.cm-editor .cm-tk-duration     { color: #79c0ff; }
+.cm-editor .cm-tk-value        { color: #c9d1d9; }
+
+:root[data-theme="light"] .cm-editor .cm-tk-comment      { color: #6e7781; }
+:root[data-theme="light"] .cm-editor .cm-tk-string       { color: #0a3069; }
+:root[data-theme="light"] .cm-editor .cm-tk-substitution { color: #953800; }
+:root[data-theme="light"] .cm-editor .cm-tk-key          { color: #0550ae; }
+:root[data-theme="light"] .cm-editor .cm-tk-operator     { color: #cf222e; }
+:root[data-theme="light"] .cm-editor .cm-tk-bool         { color: #8250df; }
+:root[data-theme="light"] .cm-editor .cm-tk-null         { color: #8250df; }
+:root[data-theme="light"] .cm-editor .cm-tk-keyword      { color: #cf222e; font-weight: 600; }
+:root[data-theme="light"] .cm-editor .cm-tk-include-fn   { color: #953800; }
+:root[data-theme="light"] .cm-editor .cm-tk-number       { color: #0550ae; }
+:root[data-theme="light"] .cm-editor .cm-tk-duration     { color: #0550ae; }
+:root[data-theme="light"] .cm-editor .cm-tk-value        { color: #1f2328; }
+
+/* Validation diagnostic list */
+.pg-diag-list { list-style: none; padding: 0; margin: 0; }
+.pg-diag-list li { margin: 0; }
+.pg-diag {
+  font: inherit;
+  display: block;
+  width: 100%;
+  text-align: left;
+  background: transparent;
+  color: var(--pg-fg);
+  border: 0;
+  border-bottom: 1px solid var(--pg-border);
+  padding: 0.5rem 0.75rem;
+  cursor: pointer;
+  font-size: 0.85rem;
+}
+.pg-diag:hover { background: var(--pg-bg-elev-2); }
+.pg-diag-loc {
+  display: inline-block;
+  min-width: 3rem;
+  font-family: var(--pg-mono);
+  font-size: 0.75rem;
+  margin-right: 0.5rem;
+  opacity: 0.7;
+}
+.pg-diag-error .pg-diag-loc { color: #f85149; }
+.pg-diag-warning .pg-diag-loc { color: #d29922; }
+:root[data-theme="light"] .pg-diag-error .pg-diag-loc { color: #cf222e; }
+:root[data-theme="light"] .pg-diag-warning .pg-diag-loc { color: #9a6700; }
+
+/* Resolved JSON panel */
+.pg-tab-panel[data-panel="json"] { padding: 0; }
+.pg-json-wrap { position: relative; }
+.pg-json-desc {
+  padding: 0.6rem 0.75rem;
+  background: var(--pg-bg-elev-2);
+  border-bottom: 1px solid var(--pg-border);
+  color: var(--pg-fg-muted);
+  font-size: 0.78rem;
+  line-height: 1.45;
+}
+.pg-json-copy {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  z-index: 1;
+}
+.pg-json {
+  font-family: var(--pg-mono);
+  font-size: 12px;
+  margin: 0;
+  padding: 0.5rem 0.75rem;
+  white-space: pre;
+  color: var(--pg-fg);
+}
+.pg-json-key  { color: #79c0ff; }
+.pg-json-str  { color: #a5d6ff; }
+.pg-json-num  { color: #79c0ff; }
+.pg-json-bool { color: #d2a8ff; }
+.pg-json-null { color: #d2a8ff; }
+:root[data-theme="light"] .pg-json-key  { color: #0550ae; }
+:root[data-theme="light"] .pg-json-str  { color: #0a3069; }
+:root[data-theme="light"] .pg-json-num  { color: #0550ae; }
+:root[data-theme="light"] .pg-json-bool { color: #8250df; }
+:root[data-theme="light"] .pg-json-null { color: #8250df; }
+
+/* About page (narrow layout) */
+.pg-app-narrow {
+  display: grid;
+  grid-template-rows: var(--pg-header-h) 1fr;
+  height: 100vh;
+}
+.pg-about {
+  max-width: 760px;
+  margin: 0 auto;
+  padding: 2rem 1.25rem 4rem;
+  font-family: var(--pg-sans);
+  color: var(--pg-fg);
+  line-height: 1.55;
+  overflow-y: auto;
+}
+.pg-about h1 { font-size: 1.6rem; margin: 0 0 0.5rem 0; }
+.pg-about h2 { font-size: 1.1rem; margin: 1.6rem 0 0.5rem 0; }
+.pg-about p { margin: 0 0 0.75rem 0; }
+.pg-about ul { margin: 0 0 1rem 1.25rem; padding: 0; }
+.pg-about li { margin: 0 0 0.35rem 0; }
+.pg-about code {
+  background: var(--pg-bg-elev-2);
+  padding: 0.05rem 0.3rem;
+  border-radius: 3px;
+  font-family: var(--pg-mono);
+  font-size: 0.88em;
+}
+.pg-about kbd {
+  background: var(--pg-bg-elev-2);
+  border: 1px solid var(--pg-border);
+  border-bottom-width: 2px;
+  border-radius: 3px;
+  padding: 0.05rem 0.35rem;
+  font-family: var(--pg-mono);
+  font-size: 0.78em;
+}
+.pg-about .pg-btn {
+  display: inline-block;
+  margin-right: 0.4rem;
+  text-decoration: none;
+}
+.pg-header-actions a.pg-btn { text-decoration: none; }
+
+/* Toast */
+.pg-toast {
+  position: fixed;
+  bottom: 64px;
+  left: 50%;
+  transform: translateX(-50%) translateY(8px);
+  padding: 0.5rem 0.9rem;
+  background: var(--pg-bg-elev-2);
+  color: var(--pg-fg);
+  border: 1px solid var(--pg-border);
+  border-radius: 6px;
+  font-size: 0.85rem;
+  font-family: var(--pg-sans);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity .15s ease, transform .15s ease;
+  z-index: 1000;
+}
+.pg-toast.is-visible {
+  opacity: 1;
+  transform: translateX(-50%) translateY(0);
+}
+
+/* History dropdown */
+.pg-history-wrap { position: relative; }
+.pg-history-pop {
+  position: absolute;
+  bottom: calc(100% + 6px);
+  right: 0;
+  min-width: 240px;
+  max-width: 360px;
+  background: var(--pg-bg-elev);
+  border: 1px solid var(--pg-border);
+  border-radius: 6px;
+  padding: 0.25rem 0;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.25);
+  z-index: 50;
+}
+.pg-history-pop[hidden] { display: none; }
+.pg-history-list { list-style: none; padding: 0; margin: 0; }
+.pg-history-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+  text-align: left;
+  background: transparent;
+  border: 0;
+  color: var(--pg-fg);
+  font: inherit;
+  font-size: 0.8rem;
+  padding: 0.4rem 0.6rem;
+  cursor: pointer;
+  gap: 0.5rem;
+}
+.pg-history-item:hover { background: var(--pg-bg-elev-2); }
+.pg-history-preview {
+  font-family: var(--pg-mono);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  flex: 1;
+}
+.pg-history-ts {
+  color: var(--pg-fg-muted);
+  font-size: 0.7rem;
+  white-space: nowrap;
+}
+
+/* Inline color swatch (clickable to open native color picker) */
+.pg-color-swatch {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  margin-left: 4px;
+  border-radius: 3px;
+  border: 1px solid var(--pg-border);
+  cursor: pointer;
+  vertical-align: middle;
+  box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.2) inset;
+}
+.pg-color-swatch:hover {
+  outline: 1px solid var(--pg-accent);
+  outline-offset: 1px;
+}
+.pg-color-swatch.is-empty {
+  background:
+    linear-gradient(45deg, var(--pg-bg-elev-2) 25%, transparent 25%),
+    linear-gradient(-45deg, var(--pg-bg-elev-2) 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, var(--pg-bg-elev-2) 75%),
+    linear-gradient(-45deg, transparent 75%, var(--pg-bg-elev-2) 75%);
+  background-size: 6px 6px;
+  background-position: 0 0, 0 3px, 3px -3px, -3px 0;
+}
+
+/* Hover tooltip */
+.cm-tooltip.cm-tooltip-hover .pg-hover {
+  background: var(--pg-bg-elev);
+  color: var(--pg-fg);
+  border: 1px solid var(--pg-border);
+  border-radius: 4px;
+  padding: 0.4rem 0.6rem;
+  font-family: var(--pg-sans);
+  font-size: 0.78rem;
+  max-width: 320px;
+}
+.pg-hover-head {
+  font-family: var(--pg-mono);
+  font-size: 0.75rem;
+  color: var(--pg-accent);
+  margin-bottom: 0.25rem;
+}
+.pg-hover-body { color: var(--pg-fg-muted); line-height: 1.4; }
+
+/* Tutorial panel */
+.pg-tutorial {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  padding: 1rem;
+  font-size: 0.875rem;
+}
+.pg-tutorial-head {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  justify-content: space-between;
+}
+.pg-tutorial-title {
+  margin: 0;
+  font-size: 1.05rem;
+  font-weight: 600;
+}
+.pg-tutorial-passed {
+  color: #3fb950;
+  font-weight: 600;
+  font-size: 0.85rem;
+}
+:root[data-theme="light"] .pg-tutorial-passed { color: #1a7f37; }
+.pg-tutorial-intro,
+.pg-tutorial-intro p,
+.pg-tutorial-intro ul {
+  color: var(--pg-fg);
+  line-height: 1.5;
+}
+.pg-tutorial-intro p { margin: 0 0 0.5rem 0; }
+.pg-tutorial-intro ul { margin: 0 0 0.5rem 1.25rem; padding: 0; }
+/* Hyperlinks inside lesson markdown - sky blue (GitHub-style), not the
+   browser-default vivid blue. Subtle dotted underline becomes solid on
+   hover; keeps the prose calm but still visibly clickable. */
+.pg-tutorial a {
+  color: #79c0ff;
+  text-decoration: underline;
+  text-decoration-color: rgba(121, 192, 255, 0.4);
+  text-underline-offset: 2px;
+  text-decoration-thickness: 1px;
+}
+.pg-tutorial a:hover {
+  text-decoration-color: currentColor;
+}
+[data-theme="light"] .pg-tutorial a {
+  color: #0969da;
+  text-decoration-color: rgba(9, 105, 218, 0.4);
+}
+.pg-tutorial-intro code,
+.pg-tutorial-hint code,
+.pg-tutorial-goal code {
+  background: var(--pg-bg-elev-2);
+  padding: 0.05rem 0.3rem;
+  border-radius: 3px;
+  font-family: var(--pg-mono);
+  font-size: 0.85em;
+}
+/* Fenced code blocks (```...```) - separate styling from inline code so
+   the block has its own padding/scroll behaviour without inheriting the
+   tight inline pill look. */
+.pg-tutorial pre {
+  background: var(--pg-bg-elev-2);
+  margin: 0 0 0.5rem 0;
+  padding: 0.5rem 0.75rem;
+  border-radius: 4px;
+  overflow-x: auto;
+}
+.pg-tutorial pre code {
+  background: transparent;
+  padding: 0;
+  font-family: var(--pg-mono);
+  font-size: 0.85em;
+  white-space: pre;
+}
+/* Inline images in lesson markdown - constrained to the panel width with
+   subtle border + corner so they sit cleanly inside paragraphs. */
+.pg-tutorial img {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin: 0.5rem 0;
+  border: 1px solid var(--pg-border);
+  border-radius: 4px;
+}
+
+/* HOCON syntax highlighting for fenced code blocks in lesson markdown.
+   Reuses the same palette as the editor's `.cm-tk-*` classes (defined
+   below for `.cm-editor`); we just respec the colours here so they apply
+   inside the tutorial panel where the editor styles don't. */
+.pg-tutorial pre .cm-tk-comment      { color: #8b949e; font-style: italic; }
+.pg-tutorial pre .cm-tk-string       { color: #a5d6ff; }
+.pg-tutorial pre .cm-tk-substitution { color: #f0b070; }
+.pg-tutorial pre .cm-tk-key          { color: #79c0ff; }
+.pg-tutorial pre .cm-tk-operator     { color: #ff7b72; }
+.pg-tutorial pre .cm-tk-bracket      { color: #c9d1d9; }
+.pg-tutorial pre .cm-tk-punctuation  { color: #c9d1d9; }
+.pg-tutorial pre .cm-tk-bool         { color: #d2a8ff; }
+.pg-tutorial pre .cm-tk-null         { color: #d2a8ff; }
+.pg-tutorial pre .cm-tk-keyword      { color: #ff7b72; font-weight: 600; }
+.pg-tutorial pre .cm-tk-includeFn    { color: #f0b070; }
+.pg-tutorial pre .cm-tk-number       { color: #79c0ff; }
+.pg-tutorial pre .cm-tk-duration     { color: #79c0ff; }
+.pg-tutorial pre .cm-tk-value        { color: #c9d1d9; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-comment      { color: #6e7781; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-string       { color: #0a3069; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-substitution { color: #953800; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-key          { color: #0550ae; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-operator     { color: #cf222e; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-bool         { color: #8250df; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-keyword      { color: #cf222e; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-includeFn    { color: #953800; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-number       { color: #0550ae; }
+[data-theme="light"] .pg-tutorial pre .cm-tk-duration     { color: #0550ae; }
+.pg-tutorial-goal {
+  background: var(--pg-bg-elev-2);
+  border-left: 3px solid var(--pg-accent);
+  padding: 0.5rem 0.75rem;
+  border-radius: 3px;
+}
+.pg-tutorial-hints { display: flex; flex-direction: column; gap: 0.5rem; }
+.pg-tutorial-hint {
+  background: var(--pg-bg-elev-2);
+  padding: 0.5rem 0.75rem;
+  border-radius: 4px;
+  font-size: 0.85rem;
+}
+.pg-tutorial-hint p { margin: 0; }
+.pg-tutorial-actions {
+  display: flex;
+  gap: 0.4rem;
+  margin-top: auto;
+  padding-top: 0.5rem;
+  border-top: 1px solid var(--pg-border);
+}
+.pg-btn-primary {
+  background: var(--pg-accent);
+  color: white;
+  border-color: var(--pg-accent);
+}
+.pg-btn-primary:disabled {
+  background: var(--pg-bg-elev-2);
+  color: var(--pg-fg-muted);
+  border-color: var(--pg-border);
+}
+.pg-tutorial-done {
+  text-align: center;
+  padding: 2rem 1rem;
+}
+.pg-tutorial-done h2 {
+  margin: 0 0 0.5rem 0;
+  font-size: 1.2rem;
+}
+
+/* Tutorial: navigation bar (breadcrumb + counter + Prev / All lessons) */
+.pg-tutorial-bar {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--pg-border);
+}
+.pg-tutorial-crumbs {
+  flex: 1 1 auto;
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  font-size: 0.8rem;
+  color: var(--pg-fg-muted);
+  min-width: 0;
+}
+.pg-tutorial-crumb {
+  font-weight: 500;
+  color: var(--pg-fg);
+}
+.pg-tutorial-crumb-sep {
+  opacity: 0.5;
+}
+.pg-tutorial-counter {
+  margin-left: 0.25rem;
+  white-space: nowrap;
+  color: var(--pg-fg-muted);
+}
+.pg-tutorial-nav {
+  font-size: 0.8rem;
+  padding: 0.25rem 0.55rem;
+}
+.pg-tutorial-nav:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* Tutorial: lessons popup (anchored to All-lessons button) */
+.pg-tutorial-popup {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  margin-top: 0.4rem;
+  z-index: 20;
+  min-width: 18rem;
+  max-width: 26rem;
+  max-height: 60vh;
+  overflow-y: auto;
+  background: var(--pg-bg-elev);
+  border: 1px solid var(--pg-border);
+  border-radius: 6px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+  padding: 0.5rem;
+  font-size: 0.85rem;
+}
+[data-theme="light"] .pg-tutorial-popup {
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
+}
+.pg-tutorial-popup-topic + .pg-tutorial-popup-topic {
+  margin-top: 0.5rem;
+  padding-top: 0.5rem;
+  border-top: 1px solid var(--pg-border);
+}
+.pg-tutorial-popup-topic-head {
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--pg-fg-muted);
+  padding: 0.25rem 0.4rem;
+  font-weight: 600;
+}
+.pg-tutorial-popup-subtopic {
+  font-size: 0.75rem;
+  color: var(--pg-fg-muted);
+  padding: 0.25rem 0.4rem 0.1rem 0.8rem;
+  font-style: italic;
+}
+.pg-tutorial-popup-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.pg-tutorial-popup-item {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.35rem 0.5rem;
+  background: transparent;
+  border: 0;
+  border-radius: 4px;
+  color: var(--pg-fg);
+  text-align: left;
+  font: inherit;
+  cursor: pointer;
+}
+.pg-tutorial-popup-item:hover {
+  background: var(--pg-bg-elev-2);
+}
+.pg-tutorial-popup-item.is-current {
+  background: var(--pg-bg-elev-2);
+  font-weight: 600;
+}
+.pg-tutorial-popup-item.is-completed .pg-tutorial-popup-marker {
+  color: #3fb950;
+}
+.pg-tutorial-popup-item.is-skipped .pg-tutorial-popup-marker {
+  color: var(--pg-fg-muted);
+}
+.pg-tutorial-popup-item.is-current .pg-tutorial-popup-marker {
+  color: var(--pg-accent);
+}
+.pg-tutorial-popup-marker {
+  width: 1rem;
+  text-align: center;
+  font-size: 0.85rem;
+  color: var(--pg-fg-muted);
+}
+.pg-tutorial-popup-num {
+  min-width: 1.75rem;
+  text-align: right;
+  color: var(--pg-fg-muted);
+  font-variant-numeric: tabular-nums;
+}
+.pg-tutorial-popup-title {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/* Mobile: stack panes vertically */
+@media (max-width: 768px) {
+  .pg-main {
+    grid-template-columns: 1fr;
+    grid-template-rows: 1fr 6px 1fr;
+  }
+  .pg-divider {
+    cursor: row-resize;
+  }
+  .pg-pane-output {
+    border-left: 0;
+    border-top: 1px solid var(--pg-border);
+  }
+  .pg-brand-sub {
+    display: none;
+  }
+}
diff --git a/src/test/setup.ts b/src/test/setup.ts
new file mode 100644
index 0000000..4c55974
--- /dev/null
+++ b/src/test/setup.ts
@@ -0,0 +1,2 @@
+// happy-dom setup placeholder. Phase M.2+ adds polyfills if needed.
+export {};
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..bb24af4
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+import path from 'node:path';
+
+export default defineConfig({
+  test: {
+    environment: 'happy-dom',
+    globals: false,
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/**/*.{test,spec}.ts'],
+  },
+  resolve: {
+    alias: {
+      '@components': path.resolve('./src/components'),
+      '@playground': path.resolve('./src/lib/playground'),
+    },
+  },
+});