# shooosh

> WGSL-first site GPU engine. WebGPU when available, WebGL2 fallback. Documentation and tasks are written for coding agents.

**No magic.** The package is composition primitives + shader contracts. Looks (bloom, FXAA, grain, PBR, fluids) live as copyable WGSL/GLSL in `examples/`. Do not ingest `node_modules/` or `dist/`.

## Start here

| Goal | Read |
| --- | --- |
| **Ship a look** | This file → [examples/README.md](https://github.com/vallafederico/shooosh/blob/main/examples/README.md) → [agent copy guide](https://github.com/vallafederico/shooosh/blob/main/examples/agent-guide.md) → copy the selected demo and helpers |
| **Mirror DOM / fix SVG or SDF/MSDF rendering** | [Agent rendering workflow](https://github.com/vallafederico/shooosh/blob/main/docs/agent-dom-rendering.md) → [DOM API](https://github.com/vallafederico/shooosh/blob/main/docs/dom.md) / [asset generation](https://github.com/vallafederico/shooosh/blob/main/docs/msdf.md) |
| **Import/edit/optimize models or textures** | [Agent entry guide](https://github.com/vallafederico/shooosh/blob/main/docs/agent-usage.md) → [model reference](https://github.com/vallafederico/shooosh/blob/main/packages/model/README.md) |
| **Use bones, rigs or animations** | [Agent entry guide](https://github.com/vallafederico/shooosh/blob/main/docs/agent-usage.md) → [rig API](https://github.com/vallafederico/shooosh/blob/main/docs/rig.md) → [rig example](https://github.com/vallafederico/shooosh/blob/main/examples/rig-bones.md) |
| **Change the engine** | This file → [agents.md](https://github.com/vallafederico/shooosh/blob/main/agents.md) → next [docs/agent-tasks/](https://github.com/vallafederico/shooosh/blob/main/docs/agent-tasks) with `status: todo` |
| **Mount on a site** | Skill [shooosh-site](https://github.com/vallafederico/shooosh/blob/main/.cursor/skills/shooosh-site/SKILL.md) → [docs/site-patterns.md](https://github.com/vallafederico/shooosh/blob/main/docs/site-patterns.md) if needed |

Humans on GitHub: [readme.md](https://github.com/vallafederico/shooosh/blob/main/readme.md) → [docs/README.md](https://github.com/vallafederico/shooosh/blob/main/docs/README.md) → [docs/getting-started.md](https://github.com/vallafederico/shooosh/blob/main/docs/getting-started.md).

## Model, texture and rig entry points

These additions are unreleased; verify installed exports and CLI help. See the
[agent entry guide](https://github.com/vallafederico/shooosh/blob/main/docs/agent-usage.md) for copyable workflows and limits.
`shooosh-model/node` owns conversion/optimization/verification on Node.
`shooosh-model` is a controller contract; `/shooosh` is the opt-in rigid browser
adapter. `shooosh/rig` is a separate CPU utility entry, not automatic skinned
rendering. No Node codecs or rig code leak into core browser imports.

- [Model machine index](https://github.com/vallafederico/shooosh/blob/main/packages/model/llms.txt) · [model agent guide](https://github.com/vallafederico/shooosh/blob/main/packages/model/agents.md)
- [Rig · bones & sockets](https://github.com/vallafederico/shooosh/blob/main/examples/rig-bones.md): built-in arm or imported car; no mesh deformation.
- [Car PBR studio](https://github.com/vallafederico/shooosh/blob/main/examples/car-pbr.md): static textured model and material controls.
- [Tree-shaking verification](https://github.com/vallafederico/shooosh/blob/main/docs/audits/2026-09-09-final-tree-shaking.md): exact unused-import and baseline size checks.

## When to use shooosh

- Fullscreen shader, page-behind layer, or DOM-tracked quads
- Authored language is WGSL; same code on WebGPU or WebGL2
- Agents compose primitives — they do not invent a scene API or named effect presets

## Public API (composition)

Source in a checkout: [`package/index.ts`](https://github.com/vallafederico/shooosh/blob/main/package/index.ts),
[`package/dom/index.ts`](https://github.com/vallafederico/shooosh/blob/main/package/dom/index.ts), and
[`package/utility/index.ts`](https://github.com/vallafederico/shooosh/blob/main/package/utility/index.ts). An npm installation ships
declarations and runtime builds; examples and skills require the source checkout.
Use source matching your installed version; unreleased recipes can require new APIs.

- `probeRenderer()` → `"webgpu" | "webgl2" | null`
- `createEngine` / `initEngine` / `getDefaultEngine` — `{ backend?: "auto"|"webgpu"|"webgl2" }`
- `createCanvasScene` — lightweight owned canvas + `retain(resource)` cleanup; full `createScene` retains convenience features. See [bundle setups](https://github.com/vallafederico/shooosh/blob/main/docs/bundle-setup.md).
- `createScene` / `parseSceneDataset`
- `acquireLayer` / `releaseLayer`
- `shooosh/dom`: `createDomLayer({ canvas, root, fonts })` → cached `bind` / `media` / `box` / `text`, optional `scan()` for marked descendants (`img[data-sh-media]`, `[data-sh-bind]`, `[data-sh-box]`, `[data-sh-text]`), native fallback, explicit cleanup. See [docs/dom.md](https://github.com/vallafederico/shooosh/blob/main/docs/dom.md) for the supported subset.
- `createItem` / `createScreen` / `createObject` / `createParticles` / `createMsdfGlyphs`
- `createPostProcessor().addFragmentEffect({ fragmentShader, fragmentShaderWgsl })` — no named bloom/bw/noise; copy [`examples/post-shaders.ts`](https://github.com/vallafederico/shooosh/blob/main/examples/post-shaders.ts)
- `effects.custom` — thin sugar for `createScene({ post })` (author shaders only)
- `createCompute` — WebGPU; fluids = copy `examples/fluid-sim.ts` + `fluid-shaders.ts`
- `loadTexture` (+ `fitUv` / `textureFit` / `{ flipY: false }` for env) / `loadGlb`
- `shooosh/webgl2` / `shooosh/webgpu` and matching `/dom`: backend-only builds; default root remains both.
- `shooosh/build`: build-time `.wgsl` plugin / CLI — [shader pipeline](https://github.com/vallafederico/shooosh/blob/main/docs/shader-build.md)
- `shooosh/compiler`: optional `compileShader`, `convertWgslFragmentToGlsl` / `convertGlslFragmentToWgsl` (removed from root)
- `createMouseMonad` / `createMouseTrail`
- `shooosh/utility`: `createSpinner({ element })` → drag rotation + release inertia; see [docs/utility.md](https://github.com/vallafederico/shooosh/blob/main/docs/utility.md).

- `shooosh/rig`: optional bone references, poses, TRS clip sampling, skin matrices and sockets. No renderer or clock; [rig guide](https://github.com/vallafederico/shooosh/blob/main/docs/rig.md). Node extraction: `shooosh-model rig`.
- `shooosh/utils`: optional quaternion composition, vector rotation and pose mapping; see [docs/utils.md](https://github.com/vallafederico/shooosh/blob/main/docs/utils.md). No renderer imports.

Node/Bun only (`shooosh/msdf`): `generateMsdf` / `generateFontAtlas` / `generateIconSdf` / `alphaToSdf` · CLI `pnpm msdf`

## Shader contract (short)

See [docs/shader-contract.md](https://github.com/vallafederico/shooosh/blob/main/docs/shader-contract.md).

- Author `fn fsMain() -> vec4f`. `vUv` is top-origin. WebGL2 requires a generated `fragmentGlsl` alongside WGSL; the browser runtime does not translate.
- Textures: sample `fitUv(vUv)` when using `uTexture` + cover/contain.
- `setUni({ value1 })` → `uUni.values0.x` / `uUni[0].x` (16 floats).
- Post is `applyEffect`, not `fsMain` — both GLSL + WGSL for dual backends.
- Failed compile keeps the last good program; never blank the page.

## Work queue

- [01](https://github.com/vallafederico/shooosh/blob/main/docs/agent-tasks/01-webgpu-renderer.md) … [08](https://github.com/vallafederico/shooosh/blob/main/docs/agent-tasks/08-webgpu-remaining-ports.md) (`08` done). Next unfinished: lowest `status: todo`.
- User-selected DOM roadmap: [gap specification and agent plan](https://github.com/vallafederico/shooosh/blob/main/docs/proposals/dom-mirroring-delivery-plan.md); next bounded stage [11](https://github.com/vallafederico/shooosh/blob/main/docs/agent-tasks/11-dom-mirroring-hardening.md). Tasks 02–07 remain unchanged.
- Lightweightness audit: [measured bundle/runtime findings](https://github.com/vallafederico/shooosh/blob/main/docs/audits/2026-09-08-lightweight-performance.md); bounded bundle task [12](https://github.com/vallafederico/shooosh/blob/main/docs/agent-tasks/12-bundle-tree-shaking.md). Audit tools: `bun run bin/audit-bundle.ts` and harness `/perf.html`.

## Skills

- [shooosh-examples](https://github.com/vallafederico/shooosh/blob/main/.cursor/skills/shooosh-examples/SKILL.md) — copy from `examples/`
- [shooosh-site](https://github.com/vallafederico/shooosh/blob/main/.cursor/skills/shooosh-site/SKILL.md) / [shooosh-item](https://github.com/vallafederico/shooosh/blob/main/.cursor/skills/shooosh-item/SKILL.md) / [shooosh-post](https://github.com/vallafederico/shooosh/blob/main/.cursor/skills/shooosh-post/SKILL.md)
- [shooosh-msdf](https://github.com/vallafederico/shooosh/blob/main/.cursor/skills/shooosh-msdf/SKILL.md) — bake atlases (Node/Bun)
- [wgsl-to-glsl](https://github.com/vallafederico/shooosh/blob/main/.cursor/skills/wgsl-to-glsl/SKILL.md) / [glsl-to-wgsl](https://github.com/vallafederico/shooosh/blob/main/.cursor/skills/glsl-to-wgsl/SKILL.md)

## Optional

- [Rapier physics recipes](https://github.com/vallafederico/shooosh/blob/main/examples/physics.md): falling blocks, jointed pendulum and true 3D tumbling cubes, lazy example-only WASM dependency.

- [docs/api.md](https://github.com/vallafederico/shooosh/blob/main/docs/api.md) · [docs/shader-translation.md](https://github.com/vallafederico/shooosh/blob/main/docs/shader-translation.md) · [ROADMAP.md](https://github.com/vallafederico/shooosh/blob/main/ROADMAP.md)
- [Source](https://github.com/vallafederico/shooosh) · [vgpu llms.txt](https://vgpu.sh/llms.txt) (inspiration only)

- [Physics/utils performance audit](https://github.com/vallafederico/shooosh/blob/main/docs/audits/2026-09-09-physics-utils-performance.md): package footprint, 58 tree-shaking checks, active/idle browser measurements, limits and next opportunities.

Hosted docs: [agent manifest](https://shooosh-web.vercel.app/agents.md) · [machine index](https://shooosh-web.vercel.app/llms.txt) · [interactive examples](https://shooosh-web.vercel.app/examples).

- [GPGPU mouse particles](https://github.com/vallafederico/shooosh/blob/main/examples/gpgpu-particles.md): GPU storage-buffer integration and instanced rendering, pointer forces, lifecycle and WebGPU requirements.

- [GPGPU curl sphere](https://github.com/vallafederico/shooosh/blob/main/examples/gpgpu-sphere.md): analytic 3D curl noise, GPU particle integration, pointer disturbance and depth-tested rendering.

- [GPU simulation fallbacks and agent skills](https://github.com/vallafederico/shooosh/blob/main/docs/gpgpu-fallbacks.md): WebGPU compute to WebGL2 transform feedback or render-target GPGPU, with validation guidance.

- [Text benchmark harness](https://github.com/vallafederico/shooosh/blob/main/docs/text-benchmark.md): matched-font SDF/MSDF vs free Slug reference on WebGL2, GPU timer queries and A/B captures; private experiment workspace only.