Liquid Orb Editor: a WebGPU liquid-glass orb editor with SwiftUI/Metal export

What Liquid Orb Editor solves, and who reaches for it

The problem is narrow and concrete: you want a liquid-glass orb animation, and you want it in two places. A browser page and a native Apple app. Doing that by hand means writing the effect twice, once in WGSL for WebGPU and once in Metal for SwiftUI, then keeping the two in step as you tune color, speed, shape, refraction and outer glow. The README frames the project as a real-time liquid glass orb editor built with React, WebGPU/WGSL and Toolcraft UI, and the export features are the reason it exists rather than the shader alone. Thirteen editable animated presets ship with it, and the interface is available in Chinese and English with automatic browser-language detection and a manual switch. The audience is small: a developer or designer who needs an orb for a loading state, a voice assistant, a status indicator, or a product page, and who would rather tune parameters in a live editor than in a shader file. If you need a general shader authoring environment, this is not it. The editor exposes a fixed parameter set, not a graph.

How the editor maps parameters to GPU uniforms

The repository layout makes the data flow legible. src/presets.ts holds preset definitions and default parameters. src/orb-uniforms.ts is described as the single mapping from editor parameters to GPU uniforms, which is the load-bearing file: every control in the UI passes through one conversion before it reaches the GPU. src/orb-renderer.ts is the WebGPU renderer, and effect.wgsl is the browser shader. On the Apple side, effect.metal is the Metal shader used by SwiftUI exports. src/code-export.ts produces both the Web and SwiftUI output. The README states that the Web and SwiftUI exports use the same parameter snapshot, and that both orb preview mode and in-context scene preview mode export the same orb animation code. That single-mapping design is what keeps parity plausible: two shaders, one parameter source. It also means the parameter set is the ceiling. Anything the editor does not expose is not reachable from the exported code without editing the shader by hand.

Installing it and getting a first orb into a page

The README requires Node.js 22, pnpm 11, and a browser with WebGPU support. Install and start the dev server with the two commands the README gives. The dev script binds to 127.0.0.1 rather than exposing the server on your network, which is worth knowing if you expected to open it from another machine.

pnpm install
pnpm dev

For a production build and a local preview of the built output, the README lists these two commands. Note that build is not just a bundler call: package.json chains scripts/verify-exports.mjs, then scripts/verify-audio.mjs, then a TypeScript check with no emit, and only then vite build. A parity failure stops the build before any output is written.

pnpm build
pnpm preview

Once the editor is open, tune a preset and use the export feature to produce a standalone Web page. The exported page includes the orb animation and the audio mapping, but the README is explicit that exported pages do not request microphone access automatically and do not bundle the currently selected audio file. If your page needs audio response, you supply it. The exported Web code exposes a global function for pushing smoothed band values, and calling it with no argument stops the response.

window.liquidOrb.setAudioBands({ low: 0.5, mid: 0.3, high: 0.1, all: 0.4 });
window.liquidOrb.setAudioBands(); // Stop audio response

The SwiftUI export takes the same four values in a LiquidOrbAudio initializer, which is the shape of the parity claim in practice.

LiquidOrbView(
    state: .thinking,
    audio: LiquidOrbAudio(low: 0.5, mid: 0.3, high: 0.1, all: 0.4)
)

The README documents running node scripts/verify-audio.mjs to check preset support, silence behavior, invalid input handling and Web mapping parity. That script writes Swift parity fixtures to output/audio-qa/, and xcrun swift output/audio-qa/native-check.swift checks the Swift mapping. Running both is the cheapest way to confirm the parity claim on your own machine.

Audio response is modulation, not a fluid solver

Audio response is the feature most likely to be misread. It is available for six presets: Siri Wave, Voice Membrane, Aurora Veil, Neural Plasma, Prismatic Field and Violet Core. Other presets are unchanged, and switching to an unsupported preset stops the active audio input. That is a real constraint: if you build a design around an orb that reacts to a microphone, you are choosing from six shapes, not thirteen. The README also states plainly that the feature modulates the existing procedural animation and does not embed or reproduce the reference site's fluid solver. Treat it as a driver for parameters, not as a simulation. Low, mid, high and overall energy drive the contour, internal distortion, highlights and motion speed, and input is smoothed to prevent jitter. Pausing audio eases the orb back to its base appearance; stopping the input or setting sensitivity to 0 restores the original preset parameters. Audio modulation is applied after state transitions and does not overwrite presets, colors or URL parameters, so tuning while audio plays will not silently corrupt your saved configuration. Analysis happens locally in the browser, audio is never uploaded, and microphone input is not played back.

Share links, and what they do not carry

Configurations are stored in the URL hash, which makes a tuned orb a link you can paste to a colleague. The limitation is stated in the README: audio source and sensitivity are session-only editor settings and are not included in share links. So a link reproduces the visual parameters, not the audio setup. If you were expecting a share link to reproduce a demo exactly, including its audio reactivity, it will not. The same boundary shows up in export: exported pages do not bundle the selected audio file, and the host application supplies audio capture, frequency analysis, smoothing and sensitivity. The contract is that you pass smoothed values from 0 to 1 after applying sensitivity, and pass zero values when audio stops. That is a clean interface, but it moves real work to the integrating application. Budget for it.

Where Liquid Orb Editor is the wrong tool

Three cases stand out. First, if you need a shader you can restructure, the single-mapping design works against you: src/orb-uniforms.ts is one conversion path, and the parameter set is the interface. You can edit effect.wgsl or effect.metal directly, but then you own the parity problem the editor was built to avoid. Second, if your target environment lacks WebGPU, the editor itself will not run, and the README names WebGPU support as a requirement rather than a preference. Third, if you need a documented upgrade or rollback path, the README does not document rollback. There are no releases in the repository metadata, so there is no version history to pin to and no changelog describing what changed between states. The README says the project is under active development and that presets, motion models, editor stability and WebGPU/SwiftUI parity are continuously refined, with OpenAI Codex assisting implementation, regression testing and releases. Continuous refinement is a reasonable description of a young project, but it also means the shader and the parameter mapping can move. For a decorative orb on a marketing page that is fine. For a long-lived product surface, plan to vendor the exported code rather than track the editor.

The alternative approach: hand-written shaders or a general shader tool

The obvious alternative is writing the effect yourself, one WGSL shader for the browser and one Metal shader for the Apple app. That gives you full control over the math and no dependency on an editor's parameter set. The difference in approach is where the work sits. With Liquid Orb Editor, the shaders are fixed and the parameters are the interface; parity between Web and SwiftUI is maintained by generating both from one snapshot, and the build verifies it. Hand-writing means you own both shaders and any drift between them, and you re-derive the same values in two languages every time you tune the look. The second alternative is a general shader authoring environment, which trades the constrained parameter set for a graph you can extend. That is more capable and more work, and it gives you no export parity guarantee at all. The editor's bet is that a narrow, verified parameter set is worth more than an open graph for this specific effect.

Licence, maintenance and what an upgrade costs

Project code is MIT. Toolcraft UI code in src/toolcraft retains its original MIT copyright notice, and TOOLCRAFT_LICENSE.md covers it, so a fork has two notices to preserve rather than one. Both are permissive, and nothing in the README suggests a copyleft obligation, but read both files before you redistribute. On maintenance, the last push to the repository was on 2026-09-16, one day before this writing, and the repository is not archived. The README describes the project as under active development. The practical upgrade cost is not a version bump, because there are no releases to bump between. It is re-running the verification scripts against a newer checkout and confirming your exported code still matches. package.json wires scripts/verify-exports.mjs and scripts/verify-audio.mjs into build, so a plain pnpm build is already the parity check. If you vendor exported code into an application, that build-time check no longer guards you, and you will need to re-export and diff deliberately.

Editorial conclusion

Adopt it if you need a shader-driven orb animation and want the same parameters in a browser and in a SwiftUI app, and you are willing to run the export verification yourself. Do not adopt it if you need a general-purpose shader graph, a documented rollback path, or a project with a long release history; there are no releases in the repository metadata. Before you build on it, run pnpm verify and node scripts/verify-audio.mjs, confirm that a browser with WebGPU support is available on your target machines, and read TOOLCRAFT_LICENSE.md alongside LICENSE because src/toolcraft keeps its own MIT notice.

Frequently asked questions

Official sources

1. Issues
2. LerSent001/orb on GitHub
3. License: MIT
4. Project website
5. README