---
title: Ambient Studio
description: Create, preview, version, package, and apply operator-owned WebGPU live wallpapers with layered V2 projects, typed nodes, restricted WGSL, and truthful runtime diagnostics.
audience: users and app developers
updated: 2026-08-27
---

# Ambient Studio

Ambient Studio is the built-in live wallpaper editor for WebGPU OS. It combines a typed node graph, restricted WGSL, a full-workspace GPU preview, a project library, revision history, asset import, and reversible desktop testing in one operator-scoped app. This page explains the editor and the current runtime boundary for users and app developers. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`, `webgpu-os/apps/ambient-studio/manifest.json`.)

## Create a wallpaper

Open **Ambient Studio** from the creative app group, then follow this workflow:

1. Choose a preset or open **Projects** and create a new layered wallpaper.
2. Build the wallpaper in **Nodes**. Connect only compatible typed ports.
3. Inspect generated evidence in **Code / Plan**. Restricted shader projects expose editable WGSL; compiled layered, particle, and scene projects expose a read-only plan.
4. Open **Preview** to use the complete authoring workspace for the live result.
5. Save a draft, commit an immutable revision, test temporarily on the desktop, or apply the verified plan as the active wallpaper.

The preset catalog contains ten maintained examples:

| Project family | Examples | Execution path |
| --- | --- | --- |
| Layered V2 | Spirit Convergence, Rain Garden Depth, Aurora Horizon, Quiet Nebula Canvas | Graph-driven composite compiler and runtime |
| Classic | Living Matter, Voxel Shrine | Existing particle and scene project compilers and runtimes |
| Restricted shader | Aurora Loom, Rain Garden, Quiet Nebula, Celestial Horizon | Existing bounded Paint shader compiler and program runtime |

The four layered examples compose curated shader fields through real `source.showcase`, `layer.compose`, and `output.wallpaper` nodes. The classic examples do not prove that particle or scene nodes execute inside the layered V2 composite runtime; they retain their own established project and runtime paths. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientStudioDocument.js`, `webgpu-os/factory/apps/ambient-studio/AmbientV2Examples.js`, `webgpu-os/factory/apps/ambient-studio/AmbientShowcaseShaders.js`.)

## Use the editor workspaces

| Workspace | What it provides |
| --- | --- |
| **Nodes** | Searchable node library, typed ports, drag-and-drop placement, connection validation, layout, layer controls, inspector, and timeline |
| **Code / Plan** | Editable restricted `paintShader(color, uv, depth, time)` WGSL for shader projects, or read-only generated compiler evidence for other project families |
| **Preview** | Full live wallpaper stage, pause and recompile controls, motion playback, a diagnostics and controls drawer, pointer interaction, and **Edit Nodes** navigation |
| **Projects** | Operator-scoped project cards, V2 verification status, new/open/duplicate/delete actions, import/export, revision history, and restore-as-new-revision |

The compact **Preview & Inspector** remains available while editing nodes. The **Preview** tab gives the live surface the full central workspace rather than confining it to the inspector. Opening and closing preview controls does not replace the project or intentionally recreate the renderer. (Source: `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`.)

The timeline records bounded numeric controls as keyframes. Published controls expose selected project parameters without exposing the complete authoring graph. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientProjectV2.js`, `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`.)

## Understand node and runtime support

Ambient Studio separates authoring vocabulary from installed runtime capability. The node library labels that difference instead of showing a successful compile badge for content the runtime cannot draw.

| Composite V2 support | Nodes | Current behavior |
| --- | --- | --- |
| Executable | `source.shader`, `source.showcase`, `effect.color-grade`, `effect.blur`, `effect.bloom`, `layer.compose`, `output.wallpaper` | Compiles into ordered procedural layers. Effects run only on one procedural source at a time and remain inside a bounded shader sample budget. |
| Implicit signals | `input.time`, `input.pointer` | Records the bounded runtime dependency. The procedural runtime owns the corresponding live signal contract. |
| Authored, runtime pending | `source.image`, `source.video` | Imports, verifies, stores, packages, and compiles the media descriptor. Composite runtime V2 reports the layer as not executable and does not claim that it rendered. |
| Runtime pending | `input.audio`, `effect.parallax`, all `particle.*`, `voxel.*`, and `scene.*` nodes | The required composite runtime ABI or compiler is not installed. A required unsupported node fails compilation before preview or desktop activation. |

The node library displays **AUTHORED** on declarative image and video sources. It displays **RUNTIME PENDING** on unsupported authoring nodes. The composite plan also carries warnings for valid but non-executable layer kinds. Classic Living Matter and Voxel Shrine still run through their dedicated particle and scene implementations. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientCompositeCompiler.js`, `webgpu-os/kernel/schema/CompositeAmbientContract.js`, `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`.)

## Project and runtime contracts

Ambient Studio separates editable projects, executable plans, and portable packages:

| Contract | Purpose | Important limits |
| --- | --- | --- |
| `particle-realms.ambient-project.v2` | Editable metadata, assets, layers, graph, timeline, published controls, quality, accessibility, audit fields, revision, and content hash | 8 MiB canonical JSON; 510 assets; 4,096 layers and nodes; 16,384 connections; 4,096 tracks; 65,536 keyframes |
| `particle-realms.ambient-composite-plan.v2` | Canonical kernel-owned plan emitted by the layered graph compiler | 512 KiB; 1–32 ordered layers; content-derived hash; procedural layers are the currently executable kind |
| `particle-realms.ambient-package.v1` | Portable `.ambient` ZIP containing one canonical V2 project and its declared project-owned assets | 512 entries; 512 MiB uncompressed total; 256 MiB per entry |
| `particle-realms.ambient-project.v1` and `particle-realms.ambient-plan.v1` | Compatibility project and executable plan for restricted shader examples | 256 KiB V1 project; pure Paint shader function and the existing 64-byte uniform ABI |

`compileAmbientCompositeProject()` validates the complete V2 project and typed graph, resolves only nodes reachable from `output.wallpaper`, compiles supported procedural effects, and emits `particle-realms.ambient-composite-plan.v2`. It fails closed on cycles, invalid ports, missing required inputs, missing assets, unsupported output-path nodes, ambiguous layer bindings, and budget violations. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientProjectV2.js`, `webgpu-os/factory/apps/ambient-studio/AmbientCompositeCompiler.js`, `webgpu-os/kernel/schema/CompositeAmbientContract.js`.)

## Save projects and revisions safely

Layered V2 projects use this operator-scoped layout:

```text
/user/Ambient Studio/projects/<project-id>/
├── project.ambient.json
├── draft.ambient.json
├── revisions/
│   └── 00000001.ambient.json
├── assets/
│   └── <64-hex-sha256>.<extension>
└── legacy-migration-receipt.json
```

`project.ambient.json` is the project head. `draft.ambient.json` is the current saved draft. Numbered revision files are immutable restore points. Imported assets use their complete SHA-256 digest in both the generated `asset-<64-hex-sha256>` record ID and content-addressed path. The repository verifies every asset again after writing and when reading it for export. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientStudioProjectRepository.js`, `webgpu-os/factory/apps/ambient-studio/AmbientAssetImporter.js`.)

Saving an existing V2 draft or revision requires both the expected project revision and expected project content hash. The repository compares that logical base with the stored head, then uses `storage.writeAtomic` with the observed storage hash. A concurrent change produces a conflict instead of overwriting newer work. Every successful write receives an exact readback check. (Source: `webgpu-os/factory/apps/ambient-studio/AmbientStudioProjectRepository.js`.)

The project library asks before leaving unsaved changes. It blocks deletion when the project owns the active desktop wallpaper. Restoring an old revision creates a new revision instead of overwriting history. Legacy drafts and revisions remain discoverable for explicit migration; the migration receipt records the source hash and leaves the legacy source undeleted. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`, `webgpu-os/factory/apps/ambient-studio/AmbientStudioProjectRepository.js`.)

## Import assets and portable packages

Layered V2 projects accept these local, self-contained assets:

- PNG, JPEG, WebP, and GIF images.
- MP4 and WebM video.
- Ogg, MP3, and WAV audio.
- Binary GLB models with no external texture or buffer references.

Import checks the declared type, file extension, magic bytes, decode metadata, size, dimensions, duration, and SHA-256 digest. It rejects active document and script formats. Importing an image or video creates and connects its source layer, but the **AUTHORED** runtime status remains visible until a media-capable composite runtime exists. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientAssetImporter.js`, `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`.)

A V2 export uses the `.ambient` extension and `application/vnd.particle-realms.ambient+zip` media type. The package contains `ambient-package.json`, `project.ambient.json`, and only declared content-addressed assets. Import verifies canonical JSON, project identity and content hash, asset hashes and sizes, entry counts, byte totals, archive paths, duplicate paths, undeclared entries, and external references before installation. A package must pass the real parser to receive the in-memory verification marker accepted by the repository. A user-authored `verified: true` field is not sufficient. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientPackage.js`, `webgpu-os/factory/apps/ambient-studio/AmbientStudioProjectRepository.js`.)

Legacy and classic projects continue to import and export `.ambient.json`. Package installation requires the complete operator project-storage capability surface and an unused destination project ID. (Source: `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`.)

## Preview and apply safely

The preview uses the same ordered composite driver as the desktop. Ambient Studio acquires an app-scoped surface and the active GPU-device generation through guarded GPU services. The kernel owns the device, canvas configuration, frame admission, and surface release. The preview reports success only after the driver publishes a running state for the expected plan hash and submits at least one frame. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientCompositePreviewRenderer.js`, `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`, `webgpu-os/kernel/drivers/WebGPUCompositeAmbientDriver.js`, `webgpu-os/kernel/SurfaceManager.js`.)

**Test on Desktop** previews the compiled plan without saving it. **Stop test** restores the wallpaper that was active before the test. Closing the app also restores that wallpaper unless the user chose **Use as Wallpaper**. A failed desktop activation attempts to restore the prior wallpaper before reporting the failure. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`, `webgpu-os/kernel/AmbientEngine.js`.)

An explicit wallpaper choice in Theme Manager replaces the authored wallpaper and persists that choice. Accent, contrast, motion, or transparency changes preserve the authored wallpaper when the wallpaper selection itself did not change. (Source: `webgpu-os/kernel/ThemeEngine.js`.)

## Shader authority boundary

Authored WGSL cannot own an entry point, bind group, binding, uniform or storage address space, workgroup state, extension, unbounded loop, or storage side effect. It can only define the existing pure Paint shader function. The shared contract rejects invalid source before persistence and before WebGPU compilation. (Source: `webgpu-os/kernel/schema/AmbientProgramContract.js`.)

Ambient packages cannot turn assets into code. The importer rejects HTML, JavaScript, ECMAScript, SVG, active filename extensions, external URL references, and undeclared ZIP entries. Package verification provides content integrity inside the operator's project library; it does not claim publisher identity or a package signature. (Source: `webgpu-os/factory/apps/ambient-studio/AmbientPackage.js`.)

## Accessibility and performance

The app uses semantic buttons, labeled tabs and dialogs, keyboard shortcuts, focus restoration, live status announcements, reduced-motion behavior, forced-color support, and container-based layouts down to the 560-pixel minimum app width. Each project also records a static color fallback. (Sources: `webgpu-os/factory/apps/ambient-studio/AmbientStudioApp.js`, `webgpu-os/factory/apps/ambient-studio/AmbientProjectV2.js`.)

The desktop drivers cap frame rate, device-pixel ratio, texture dimensions, and total pixels. They stop or suspend continuous frames when the runtime is hidden, paused, or subject to reduced-motion policy. Invalid recompiles retain the last known good plan or expose a truthful fallback and diagnostic. (Sources: `webgpu-os/kernel/drivers/WebGPUAmbientProgramDriver.js`, `webgpu-os/kernel/drivers/WebGPUCompositeAmbientDriver.js`.)

## Design inspiration

Ambient Studio combines proven interaction patterns without cloning another editor:

- Shadertoy's immediate full-screen feedback and small stable input vocabulary inform the live `color`, `uv`, `depth`, and `time` contract. The OS uses WGSL and normalized coordinates rather than accepting GLSL `mainImage`, global bindings, or arbitrary channels. [Shadertoy input reference](https://help.maxon.net/ag/en-us/Content/html/Modifier_image_shadertoy.html)
- Pixel Composer's typed junctions, procedural composition, direct property animation, and timeline inform node wiring and keyframes. Ambient Studio reuses OS graph and shader contracts instead of importing a second execution engine. [Pixel Composer](https://pixel-composer.com/), [Pixel Composer node workflow](https://pixel-composer-doc.readthedocs.io/en/latest/node/)
- Unity Shader Graph's separated Blackboard, Graph Inspector, and Main Preview inform the editor, inspector, and full preview split. [Unity Shader Graph window](https://docs.unity3d.com/Packages/com.unity.shadergraph@10.0/manual/Shader-Graph-Window.html)
- Blender's shader editor and reusable node-group model inform a possible reviewed subgraph phase. Recursive user groups and arbitrary multi-pass feedback are not part of the current execution contract. [Blender Shader Editor](https://docs.blender.org/manual/en/4.4/editors/shader_editor.html), [Blender node groups](https://docs.blender.org/manual/en/4.0/interface/controls/nodes/groups.html)

## See also

- [Shaders & WGSL](../engine/shaders.md)
- [Particle System](../engine/particles.md)
- [GPU Device Sharing](../concepts/gpu-device-sharing.md)
- [App Catalog](app-catalog.md)
- [Security & Trust Model](../concepts/security-model.md)