feat(playground): design system blocks with multi-file TSX samples and file tree (#272)

* feat(playground): add design system blocks with multi-file TSX samples and file tree

Overhaul the playground app to support multi-file editing with a new
FileTree component. Replace Vue SFC samples with TSX + Styleframe config
pairs covering Avatar, Badge, Button, Callout, Card, Checkbox, Input, and
Spinner. Introduce bundlePreview pipeline (replaces compileVueSfc), new
playground UI recipes (file tab, file tree, brand mark, editor shell), and
update state management and build config accordingly.

Also simplifies the field-group recipe to consolidate .input/.select/.textarea
flex-grow selectors into a single joined CSS selector.

* fix(ci): fix format and failing field-group test

- Format apps/playground/test/pipeline.test.ts with oxfmt
- Replace combined CSS selector key with individual selectors in
  useFieldGroupRecipe so the seam-selector test can find each child rule

* test(playground): expand bundlePreview, codemirror, and state tests

Author: alexgrozav

.changeset/playground-design-system-blocks.md

@@ -0,0 +1,5 @@
+---
+"@styleframe/theme": patch
+---
+
+Simplify field-group recipe selector: consolidate `.input`, `.select`, `.textarea` flex-grow rules into a single joined selector.

apps/playground/AGENTS.md

@@ -1,11 +1,12 @@
 # Styleframe Playground
 
-Interactive client-side playground for Styleframe. Users edit three files in CodeMirror; an iframe renders the live result.
+Interactive client-side playground for Styleframe. Users edit an arbitrary set of files (React `tsx` components + a `styleframe.config.ts`) in CodeMirror; an iframe renders the live result.
 
 ## Package
 
 - **Name:** `@styleframe/playground`
-- **Build tool:** Vite 7 + Vue 3
+- **Shell:** Vite + Vue 3 (the playground UI is a Vue app; it is invisible to users)
+- **Preview:** React 19 + `tsx`, bundled in the browser with `esbuild-wasm`
 - **Runs:** fully client-side — no server, no auth, no persistence.
 - **Not published to npm.**
 
@@ -14,42 +15,35 @@ Interactive client-side playground for Styleframe. Users edit three files in Cod
 ```
 apps/playground/
 ├── styleframe.config.ts         # shell: theme presets + #app / html selectors
-├── vite.config.ts               # Styleframe Vite plugin + vue()
+├── vite.config.ts               # Styleframe Vite plugin (minify:false) + vue() + React vendoring
 ├── index.html
 ├── src/
-│   ├── App.vue                  # playground shell root
+│   ├── App.vue                  # playground shell root (Editor │ Output │ Tree)
 │   ├── main.ts                  # imports virtual:styleframe.css, mounts App
-│   ├── recipes/                 # playground-local recipes (pg-*)
-│   │   ├── useTabRecipe.ts
-│   │   ├── useTabListRecipe.ts
-│   │   ├── useSplitPaneRecipe.ts
-│   │   ├── useEditorShellRecipe.ts
-│   │   ├── useErrorBannerRecipe.ts
-│   │   ├── useToolbarRecipe.ts
-│   │   ├── index.ts             # barrel
+│   ├── recipes/                 # playground-local recipes (pg-*), incl. useFileTreeRecipe
 │   │   └── playground.styleframe.ts  # registers recipes into the shell instance
 │   ├── components/
-│   │   ├── SplitPane.vue
-│   │   ├── TabList.vue
-│   │   ├── EditorPane.vue       # 3-tab editor (config, App, Component)
-│   │   ├── OutputPane.vue       # 3-tab output (Preview, CSS, JS)
-│   │   ├── CodeOutput.vue       # read-only CodeMirror
+│   │   ├── SplitPane.vue        # Editor │ Output split
+│   │   ├── FileTree.vue         # project tree (far right): create / rename / delete
+│   │   ├── EditorPane.vue       # dynamic, path-keyed CodeMirror editors + tabs
+│   │   ├── OutputPane.vue       # Preview / CSS / JS tabs
 │   │   ├── PreviewFrame.vue     # iframe + postMessage listener
 │   │   └── ErrorBanner.vue
 │   ├── editor/
-│   │   ├── codemirror.ts        # createEditor({parent, doc, language, onChange})
-│   │   └── theme.ts             # CodeMirror theme extension
+│   │   ├── codemirror.ts        # createEditor(...) + languageForPath() (ts / tsx / css)
+│   │   └── theme.ts
 │   ├── pipeline/
 │   │   ├── esbuild.ts           # lazy esbuild-wasm init (single instance)
-│   │   ├── transformTs.ts
-│   │   ├── evalUserConfig.ts    # rewrites imports, runs via new Function
+│   │   ├── transformTs.ts       # strips TS from the config before eval
+│   │   ├── evalUserConfig.ts    # rewrites imports, runs config via new Function
+│   │   ├── scanAndRegisterUtilities.ts
 │   │   ├── transpileStyleframe.ts
-│   │   ├── compileVueSfc.ts
-│   │   ├── buildSrcdoc.ts
+│   │   ├── bundlePreview.ts     # esbuild-wasm bundle of all user files → one ESM module
+│   │   ├── buildSrcdoc.ts       # CSS + React vendor + bundle → srcdoc
 │   │   └── pipeline.ts          # orchestrator + debounce + PipelineResult
-│   ├── samples/                 # default file contents, imported as ?raw
+│   ├── samples/                 # default file contents (.tsx + config), imported as ?raw
 │   └── state/
-│       └── playground.ts        # reactive { files, output, error, active* }
+│       └── playground.ts        # reactive { files, output, error, active* } + file actions
 └── test/                        # Vitest specs for pipeline units
 ```
 
@@ -60,36 +54,45 @@ apps/playground/
 | Context | Compiled by | Where CSS lives | Runtime |
 |---|---|---|---|
 | Shell UI | `@styleframe/plugin/vite` at dev/build time | `<style>` in parent document | `@styleframe/runtime` bundled into parent |
-| User-edited preview | `esbuild-wasm` + `@styleframe/transpiler` at runtime | `<style>` inside iframe `srcdoc` | `@styleframe/runtime` loaded via iframe importmap |
+| User-edited preview | `esbuild-wasm` + `@styleframe/transpiler` at runtime | `<style>` inside iframe `srcdoc` | React + `@styleframe/runtime` inlined into the preview bundle |
 
-The iframe has `sandbox="allow-scripts allow-same-origin"` so it can fetch blob URLs and use an importmap. Cross-file imports between user files are rewritten to blob URLs:
+The iframe has `sandbox="allow-scripts allow-same-origin"`. There is **no importmap**: `bundlePreview` resolves everything through an in-memory virtual-FS esbuild plugin and inlines it. React is the one exception — it is vendored once as an IIFE (`vite.config.ts` → `buildReactVendor`) that publishes `globalThis.PGReactVendor`, runs first as a classic `<script>`, and is read by thin shims in the bundle. This keeps a single React instance and the whole preview offline.
 
-- `./Component.vue` inside App.vue → blob URL of compiled Component
-- `./styleframe.config` inside Component.vue → blob URL of the compiled runtime TS module (which exports `card`, `cardHeader`, etc.)
+The virtual-FS plugin resolves:
+- relative imports (`./Card`, `../foo/Bar`) against the in-memory `files` map (trying `.tsx/.ts/.jsx/.js/.css` + `index.*`);
+- `virtual:styleframe` → the generated runtime TS module (recipe functions like `card`, `button`);
+- `virtual:styleframe.css` → empty (the CSS is injected separately);
+- `react` / `react-dom/client` / `react/jsx-runtime` / `@styleframe/runtime` → vendored shims/sources.
 
 ## Pipeline Stages
 
-`runPipeline(input)` runs these sequentially, and returns `{ ok: false, stage, error }` if any step throws:
+`runPipeline(input)` runs these sequentially, and returns `{ ok: false, stage, error }` if any step throws. `input` is `{ files, configPath, entryPath }`.
 
 | Stage | Input | Output |
 |---|---|---|
-| `config-transform` | user's `styleframe.config.ts` source | compiled JS |
+| `config-transform` | the `configPath` file's source | compiled JS |
 | `config-eval` | compiled JS | `Styleframe` instance |
+| `styleframe` | every `*.styleframe.ts` file (sorted) | recipes registered on the shared instance |
+| `scan` | every file except the config and `*.styleframe.ts` | utility classes registered on the instance |
 | `transpile` | `Styleframe` instance | `{ css, ts }` from `@styleframe/transpiler` |
-| `config-compile` | `ts` | compiled JS module for the iframe |
-| `vue` | App + Component SFC sources | compiled ESM modules |
-| `assemble` | all of the above + Vue/runtime URLs | `srcdoc` string |
+| `bundle` | all files + `entryPath` + generated runtime TS | one ESM preview module |
+| `assemble` | CSS + preview bundle + React vendor IIFE | `srcdoc` string |
+
+`*.styleframe.ts` extension files are evaluated like `@styleframe/plugin` loads them: `import { styleframe } from "virtual:styleframe"` returns the same instance the config created (`evalStyleframeFile` shims `styleframe()` to return it), so each file's recipe registrations mutate the shared instance. They are authoring-only — never scanned or bundled into the preview.
+
+`transpileStyleframe` runs with `treeshake: false` so the preview shows the **complete** generated CSS — the scanner cannot see runtime recipe calls, so tree-shaking would drop recipe/utility CSS the rendered components depend on.
 
 On success, the parent assigns `iframe.srcdoc = srcdoc` and revokes the previous run's blob URLs.
 
 ## Key Conventions
 
-1. **Shell styling is via Styleframe only.** No inline styles except for a handful of layout-critical resets in `App.vue`/`SplitPane.vue` (`flex: 1`, `min-height: 0`, etc.). All colors/spacing/borders come from the recipes in `src/recipes/`.
-2. **User file specifiers.** User code imports recipes from `"./styleframe.config"` (no extension). The pipeline rewrites that to a blob URL. User code imports `Component.vue` from `"./Component.vue"` — same treatment.
-3. **Sample files are in `src/samples/`**, imported via `?raw`. Edit these to change what the playground shows on first load.
-4. **CodeMirror 6 used directly.** No wrapper library. Language is selected per file via `@codemirror/lang-javascript` (`typescript: true`) or `@codemirror/lang-vue`.
-5. **Parent never evaluates untrusted code.** The user's config runs inside `new Function(...)` with a rewritten source; the Vue SFCs only run inside the iframe.
-6. **The last valid preview stays on screen.** The error banner overlays the affected tab; blob URLs from the previous successful run are only revoked when the next run succeeds.
+1. **Shell styling is via Styleframe only.** No inline styles except a handful of layout-critical resets in `App.vue` (`flex: 1`, `min-height: 0`). All chrome comes from the recipes in `src/recipes/`.
+2. **User code mirrors a real Styleframe app.** The default project lives under `src/`, with each component in `src/components/<Name>/` paired with a `<Name>.styleframe.ts` extension file that registers its recipe(s). Components import the compiled recipes from `"virtual:styleframe"`; `styleframe.config.ts` (root) holds presets only and exports the instance as default. `src/App.tsx` is the entry — its default export is the preview root.
+3. **Dynamic files and folders.** `state/playground.ts` keys files by path and exposes `createFile` / `createFolder` / `renameFile` / `deleteFile` / `deleteFolder` (the config and entry files, and any folder containing them, are protected). Empty folders are tracked in `state.folders`. `FileTree.vue` drives them.
+4. **Sample files are in `src/samples/`** (`.tsx`, `.styleframe.sample.ts`, config), imported via `?raw`, and excluded from the shell `tsconfig` (they target the user's `virtual:styleframe`, not the shell's). The `.styleframe.sample.ts` suffix keeps them from matching the shell plugin's `**/*.styleframe.ts` glob.
+5. **CodeMirror 6 used directly.** Language per file via `languageForPath` (`@codemirror/lang-javascript` with `jsx` for `.tsx`, plain `ts`, or `@codemirror/lang-css`).
+6. **Parent never evaluates untrusted code.** Only the config runs in `new Function(...)`; components run only inside the iframe.
+7. **The last valid preview stays on screen.** Blob URLs from the previous successful run are revoked only when the next run succeeds.
 
 ## Testing
 
@@ -98,11 +101,13 @@ pnpm test --filter @styleframe/playground     # Vitest unit tests (jsdom)
 pnpm typecheck --filter @styleframe/playground
 ```
 
-Manual verification: run `pnpm dev:playground`, edit each of the three files, confirm the three right-hand tabs update, and force a syntax error to see the banner behavior.
+> Adding a `pg-*` recipe requires running `pnpm dev:playground` (or `build`) once so the plugin regenerates `.styleframe/styleframe.d.ts` before `typecheck` passes.
+
+Manual verification: run `pnpm dev:playground`, create a file from the tree, import it into `App.tsx`, press Ctrl/Cmd+S, and confirm the preview, CSS, and JS tabs update.
 
 ## Related
 
-- `theme/src/recipes/card/` — recipes used by the default sample `Component.vue`.
-- `engine/transpiler/src/transpile.ts` — `transpile(instance)` API consumed by `src/pipeline/transpileStyleframe.ts`.
-- `engine/runtime/src/runtime.ts` — `createRecipe` consumed by the iframe's compiled config module.
+- `theme/src/recipes/card/`, `theme/src/recipes/button/` — recipes used by the default samples.
+- `engine/transpiler/src/transpile.ts` — `transpile(instance)` consumed by `src/pipeline/transpileStyleframe.ts`.
+- `engine/runtime/src/runtime.ts` — `createRecipe` consumed by the preview's generated runtime module.
 - `apps/storybook/` — mirror setup for Vite + Vue + `@styleframe/plugin`.