From d34722d66d3682d31707d6dcb641755da7e6de69 Mon Sep 17 00:00:00 2001 From: Amp Date: Wed, 19 Aug 2026 14:20:59 +0000 Subject: [PATCH] Add tutorial docs and interactive playgrounds Amp-Thread-ID: https://ampcode.com/threads/T-01a01380-b478-77d0-84a0-102880a5c5ae Co-authored-by: Heaust Azure --- .amp/services.yaml | 4 +- .gitignore | 1 + AGENTS.md | 3 +- README.md | 12 +- docs/.vitepress/config.js | 67 + docs/.vitepress/theme/Playground.vue | 31 + docs/.vitepress/theme/custom.css | 90 + docs/.vitepress/theme/index.js | 10 + docs/guide/architecture.md | 40 + docs/guide/first-scene.md | 84 + docs/index.md | 35 + docs/packages/core.md | 66 + docs/packages/gltf-import.md | 55 + docs/packages/index.md | 26 + docs/packages/mesh-handles.md | 59 + docs/packages/render-graph.md | 78 + docs/recipes/graph-authoring.md | 82 + docs/recipes/index.md | 12 + docs/recipes/pipelines.md | 101 + docs/recipes/render-data.md | 54 + docs/recipes/runtime.md | 91 + examples/README.md | 13 +- examples/cookbook/01-canonical-ast.js | 27 - examples/cookbook/02-jso-graph.js | 18 - examples/cookbook/03-fluent-builder.js | 12 - examples/cookbook/04-fxnode-export.js | 19 - examples/cookbook/05-default-pipelines.js | 12 - .../cookbook/06-custom-render-pipeline.js | 31 - examples/cookbook/07-compute-pipeline.js | 18 - examples/cookbook/08-compile-and-switch.js | 13 - examples/cookbook/09-gltf-import-worker.js | 13 - examples/cookbook/10-mesh-instances.js | 14 - examples/cookbook/11-custom-soa-column.js | 14 - examples/cookbook/12-direct-sab-animation.js | 9 - examples/cookbook/13-bvh-picking.js | 7 - examples/cookbook/14-worker-to-worker.js | 13 - examples/cookbook/15-complete-scene.js | 10 - examples/cookbook/17-conventional-handles.js | 19 - examples/cookbook/README.md | 28 - examples/cookbook/index.js | 17 - examples/index.html | 197 +- examples/playground/index.html | 38 + examples/playground/index.js | 79 + examples/playground/recipes.js | 104 + examples/playground/runner.html | 21 + examples/playground/runner.js | 43 + examples/playground/runtime.js | 134 + examples/playground/styles.css | 72 + examples/render-graph-studio/index.js | 46 +- .../camera-controls.js} | 3 +- examples/shared/create-worker-transport.js | 42 + package-lock.json | 2479 ++++++++++++++++- package.json | 13 +- tests/cookbook-examples.test.js | 183 -- tests/docs-playground.test.js | 70 + vite.config.js | 29 +- yarn.lock | 969 ++++++- 57 files changed, 5063 insertions(+), 767 deletions(-) create mode 100644 docs/.vitepress/config.js create mode 100644 docs/.vitepress/theme/Playground.vue create mode 100644 docs/.vitepress/theme/custom.css create mode 100644 docs/.vitepress/theme/index.js create mode 100644 docs/guide/architecture.md create mode 100644 docs/guide/first-scene.md create mode 100644 docs/index.md create mode 100644 docs/packages/core.md create mode 100644 docs/packages/gltf-import.md create mode 100644 docs/packages/index.md create mode 100644 docs/packages/mesh-handles.md create mode 100644 docs/packages/render-graph.md create mode 100644 docs/recipes/graph-authoring.md create mode 100644 docs/recipes/index.md create mode 100644 docs/recipes/pipelines.md create mode 100644 docs/recipes/render-data.md create mode 100644 docs/recipes/runtime.md delete mode 100644 examples/cookbook/01-canonical-ast.js delete mode 100644 examples/cookbook/02-jso-graph.js delete mode 100644 examples/cookbook/03-fluent-builder.js delete mode 100644 examples/cookbook/04-fxnode-export.js delete mode 100644 examples/cookbook/05-default-pipelines.js delete mode 100644 examples/cookbook/06-custom-render-pipeline.js delete mode 100644 examples/cookbook/07-compute-pipeline.js delete mode 100644 examples/cookbook/08-compile-and-switch.js delete mode 100644 examples/cookbook/09-gltf-import-worker.js delete mode 100644 examples/cookbook/10-mesh-instances.js delete mode 100644 examples/cookbook/11-custom-soa-column.js delete mode 100644 examples/cookbook/12-direct-sab-animation.js delete mode 100644 examples/cookbook/13-bvh-picking.js delete mode 100644 examples/cookbook/14-worker-to-worker.js delete mode 100644 examples/cookbook/15-complete-scene.js delete mode 100644 examples/cookbook/17-conventional-handles.js delete mode 100644 examples/cookbook/README.md delete mode 100644 examples/cookbook/index.js create mode 100644 examples/playground/index.html create mode 100644 examples/playground/index.js create mode 100644 examples/playground/recipes.js create mode 100644 examples/playground/runner.html create mode 100644 examples/playground/runner.js create mode 100644 examples/playground/runtime.js create mode 100644 examples/playground/styles.css rename examples/{cookbook/16-camera-render-data.js => shared/camera-controls.js} (96%) create mode 100644 examples/shared/create-worker-transport.js delete mode 100644 tests/cookbook-examples.test.js create mode 100644 tests/docs-playground.test.js diff --git a/.amp/services.yaml b/.amp/services.yaml index 77bb035..2b4b0b9 100644 --- a/.amp/services.yaml +++ b/.amp/services.yaml @@ -2,5 +2,5 @@ services: yawn-examples: command: npm run examples portal: - title: Yawn examples - description: Example index and WebGPU render graph studio with hot reload. + title: Yawn docs and playgrounds + description: VitePress package tutorials and isolated WebGPU playgrounds with hot reload. diff --git a/.gitignore b/.gitignore index 7328621..887b670 100644 --- a/.gitignore +++ b/.gitignore @@ -46,6 +46,7 @@ target/ # WASM build artifacts .rsw/ static/level-editor/ +docs/.vitepress/cache/ # Amp runtime artifacts .amp/in/ diff --git a/AGENTS.md b/AGENTS.md index 28ada97..8d60415 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,6 @@ # Build, Lint, and Test Commands -- `npm run examples`: Start the examples index with Vite and WASM hot reload +- `npm run examples`: Start VitePress docs and WebGPU playgrounds with WASM hot reload +- `npm run docs:build`: Build the VitePress documentation into `dist/docs/` - `npm run build`: Build optimized WASM and JS in `dist/` for development - `npm run build-release`: Build optimized WASM and JS for production - `cargo check`: Validate Rust sources quickly before full builds diff --git a/README.md b/README.md index a4fda61..115cc3b 100644 --- a/README.md +++ b/README.md @@ -43,13 +43,11 @@ loadouts, lifecycle, and transient resource management; conveniences live outsid - `addons/gltf-import` — glTF worker that writes format-neutral render-data packets directly to a fixed SOA. - `addons/mesh-handles` — conventional mesh, instance, camera, and material objects plus optional BVH picking. -The integration example in `examples/render-graph-studio` consumes every package -through its public API; no example source or shader lives in core. - -The focused recipes in `examples/cookbook` show each addon independently, including -AST/JSO/FXNode authoring, external render and compute programs, graph activation, -shared glTF import, mesh instances, custom SOA columns, SAB animation, picking, and -worker-to-worker use. +The editable playground and Render Graph Studio under `examples/` consume the +packages through their public APIs; no example source or shader lives in core. +Tutorial-style package guides and all focused recipes live under `docs/`, including +AST/JSO/FXNode authoring, render and compute programs, graph activation, shared glTF +import, mesh instances, custom SOA columns, SAB animation, picking, and worker use. Example graph authoring: diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js new file mode 100644 index 0000000..9af5242 --- /dev/null +++ b/docs/.vitepress/config.js @@ -0,0 +1,67 @@ +import { defineConfig } from "vitepress"; + +export default defineConfig({ + title: "Yawn", + description: "Worker-native WebGPU rendering with shared render data.", + base: "/docs/", + outDir: "../dist/docs", + cleanUrls: true, + head: [ + ["meta", { name: "theme-color", content: "#0d1117" }], + ["link", { rel: "icon", href: "data:image/svg+xml," }], + ], + themeConfig: { + logo: { + light: "data:image/svg+xml,", + dark: "data:image/svg+xml,", + }, + nav: [ + { text: "Learn", link: "/guide/first-scene" }, + { text: "Packages", link: "/packages/" }, + { text: "Recipes", link: "/recipes/" }, + { text: "Playground", link: "/../playground/" }, + ], + sidebar: [ + { + text: "Get started", + items: [ + { text: "Your first scene", link: "/guide/first-scene" }, + { text: "How Yawn fits together", link: "/guide/architecture" }, + ], + }, + { + text: "Package tutorials", + items: [ + { text: "Package map", link: "/packages/" }, + { text: "Core and render data", link: "/packages/core" }, + { text: "Render graph frontends", link: "/packages/render-graph" }, + { text: "glTF import worker", link: "/packages/gltf-import" }, + { text: "Conventional handles", link: "/packages/mesh-handles" }, + ], + }, + { + text: "Recipes", + items: [ + { text: "All recipes", link: "/recipes/" }, + { text: "Graph authoring", link: "/recipes/graph-authoring" }, + { text: "Pipelines and loadouts", link: "/recipes/pipelines" }, + { text: "Assets and render data", link: "/recipes/render-data" }, + { text: "Runtime interaction", link: "/recipes/runtime" }, + ], + }, + ], + socialLinks: [ + { icon: "github", link: "https://github.com/heaust-ops/yawn" }, + ], + search: { provider: "local" }, + outline: { level: [2, 3] }, + editLink: { + pattern: "https://github.com/heaust-ops/yawn/edit/feat/core/docs/:path", + text: "Edit this page on GitHub", + }, + footer: { + message: "Core owns render data and render graphs. Addons own conveniences.", + copyright: "Yawn is pre-1.0 software.", + }, + }, +}); diff --git a/docs/.vitepress/theme/Playground.vue b/docs/.vitepress/theme/Playground.vue new file mode 100644 index 0000000..dc21d5d --- /dev/null +++ b/docs/.vitepress/theme/Playground.vue @@ -0,0 +1,31 @@ + + +