Wanted: render Uhura examples to static images without a browser

[softmarshmallow]

Wanted feature

Add first-party Uhura tooling that can render a checked static design or example directly to an image artifact such as PNG or JPEG.

An illustrative interface could look like:

uhura render path/to/project --example profile-card --output profile-card.png

The exact CLI and artifact schema are not decided by this issue.

This must not depend on every example having a dedicated web route, nor should it be implemented as browser screenshot automation. Uhura should be able to evaluate the selected example and produce a self-contained, renderer-ready package containing the concrete presentation inputs needed for offscreen rendering:

• evaluated HTML/structure;
• CSS;
• resolved assets;
• explicit frame or viewport size;
• any deterministic metadata needed by the renderer.

That package should be directly consumable by a browserless headless render engine.

Why this matters

Uhura examples do not each expose a dedicated route. That makes a route-driven screenshot workflow an awkward and incomplete way for an agent—or a person—to visually inspect a design.

A static render command gives agents a canonical visual artifact to perceive, compare, and report on without first understanding or operating the Editor UI. It is also broadly useful for:

• CI previews and visual regression tests;
• documentation and example thumbnails;
• catalog generation;
• design review artifacts;
• batch export and sharing; and
• deterministic debugging of renderer output.

This should be treated as a product capability, not merely a testing helper.

Product position

Many UI “frameworks” ultimately remain wrappers around a browser DOM. Uhura should have a first-party rendering path of its own: it can target the DOM for interactive browser use, but it can also render statically through a built-in engine without launching a browser.

The planned direction is to build the headless path on the future n0 renderer crate. Its concrete API, packaging, and integration are not yet settled.

Whether the Uhura Editor canvas itself is eventually powered by n0 is also intentionally undecided. Static rendering must be useful and shippable without requiring that decision first.

Architectural direction

The intended boundary is:

checked Uhura project + selected example/scenario
  -> deterministic semantic view
  -> portable render package (HTML/structure + CSS + assets + size)
  -> first-party headless renderer
  -> PNG/JPEG/etc.

Uhura Core should continue to own checking, example/scenario evaluation, state projection, and the renderer-neutral semantic view. The static renderer is a first-party renderer of that output; it must not turn layout or paint behavior into hidden language semantics.

The render package should be:

• versioned;
• deterministic for fixed inputs;
• self-contained or explicit about every external dependency;
• independent of a running Editor or application server;
• explicit about dimensions, scale, fonts, and asset resolution; and
• usable by both CLI tooling and future integrations.

Initial scope

The first useful slice should support:

• selecting one declared example and its initial or named static scenario;
• producing one image at an explicit size and scale;
• PNG output, with other formats added where the engine supports them;
• local project assets and styles;
• clear diagnostics for missing assets, fonts, unsupported styling, or invalid dimensions; and
• a machine-readable result that identifies the selected example, renderer/package version, dimensions, and output path.

Acceptance criteria

• A checked Uhura example can be rendered to PNG from the CLI or an equivalent public tooling API.
• Rendering does not launch or require a browser, the Editor, or a dedicated route.
• The intermediate render package includes evaluated structure/HTML, CSS, resolved assets, and explicit dimensions.
• Fixed source, scenario, assets, renderer version, size, and scale produce deterministic output.
• Missing or unsupported presentation inputs fail with actionable diagnostics.
• Reference fixtures exercise parity between the browser renderer and the headless renderer where the supported presentation subset overlaps.
• An agent can render and inspect an example using only the project plus the tooling contract.
• The package and image output can run in CI without ambient network access.

Non-goals

• Deciding whether the Editor canvas must use n0.
• Requiring a route per example.
• Implementing the feature through Chromium, WebKit, or another browser screenshot harness.
• Claiming full browser CSS compatibility in the first version.
• Defining interactive input, animation capture, or video export in the first slice.
• Collapsing the renderer-neutral semantic view into DOM-specific runtime semantics.