Layout

A retained UI engine for HUDs, virtual displays, and immersive WebGPU interfaces. Built for MetaFor.

Layout provides a WebGPU interface runtime. It owns one Engine renderer and retained Space, then coordinates surfaces, pointer and keyboard input, camera-locked HUDs, texture-target descriptors, and optional world-space displays without imposing a visual component library.

Why it exists

Most interface frameworks stop at a flat browser viewport. Layout is built for software that may run as a conventional 2D HUD today and move the same interface into glasses, headsets, spatial canvases, or multiple virtual displays tomorrow.

• one render-on-demand runtime instead of a second animation engine;
• retained surface identity and transform-only updates;
• logical UI pixels mapped to millimetre-based world coordinates;
• HUD and spatial-display targets, plus texture-target descriptors;
• mouse, touch, keyboard, IME, clipping, focus, and display navigation;
• a compact FlexBox planner for deterministic interface geometry.

Layout is infrastructure, not a theme. Visual Elements and Components live in zavx0z/ui; high-performance node editors live in zavx0z/node; GPU primitives come from zavx0z/engine.

The default TTF remains owned by Engine. A ready application declares its served URL once in HTML; UiRuntime fetches it lazily and shares the parsed font. Passing another font or fontUrl skips the default request entirely.

Storybook

The Layout Storybook uses the shared five-region Workbench, but its preview remains owned by @layout/core. Two exact pathname stories prove different real targets:

• ui-runtime/target/hud attaches the card through addHudSurface();
• ui-runtime/target/spatial-display attaches another card through addSurface() to the built-in UIDisplay.

The catalog runs without HMR on an OS-allocated port and emits its exact runtime origin. Agents use the global $storybook with @layout/storybook; no consumer port registry exists. Static Pages output uses the same /layout/ base and a schema-1 manifest with exact revisions, routes, lazy chunks, sizes and SHA-256 hashes. Deployment is manual and owner-gated; it is not triggered by every green main.

Workspace

packages/
  core/       @layout/core
  storybook/  @layout/storybook

Packages are internal build identities. Local development links them directly; they are not published to npm.

Development

cd ../engine/packages/core && bun link
cd ../../../layout
bun install
bun run check

Use $storybook ensure @layout/storybook for the local catalog and $storybook check @layout/storybook for its package gates.

See ARCHITECTURE.md for ownership and CONTRIBUTING.md for contribution workflow.

License

MIT