Proposal: make HTML the UI baseline and keep only a minimal intrinsic core

[softmarshmallow]

Status

Focused design proposal. No implementation is authorized by this issue.

Related prior study: #19. That issue keeps the wider widget landscape open; this issue proposes only the smaller architectural boundary below.

Proposal

Uhura's Web UI profile should be HTML-standard-first, with a deliberately tiny additive set of Uhura-owned intrinsic capabilities.

Uhura machine language
  + explicit `ui` Web profile
      + version-pinned HTML vocabulary
      + checked machine-event bindings
      + minimal privileged Uhura intrinsics
      + later ordinary components and packages

This is not a second markup ontology that happens to compile to HTML. Lowercase standard elements retain their HTML identity and semantics. Uhura adds a non-HTML capability only when HTML plus ordinary checked composition cannot express it faithfully.

Web Components are precedent only for the additive mental model. Uhura intrinsics do not inherit custom-element registration, Shadow DOM, JavaScript lifecycle callbacks, or ambient DOM authority.

Why change the current boundary

The 0.4 incubation catalogue treats every admitted tag as a finite Uhura catalogue entry. That was a useful way to bound the language rewrite, but it produces an arbitrary Web surface:

• <p> checks while <pre> does not;
• <h1> and <h2> check while <h3> through <h6> do not;
• <dl> checks while <ul> and <ol> do not; and
• a harmless semantic HTML addition requires checker, catalogue, documentation, and test changes even though the renderer already creates unadapted HTML generically.

For a Web-only ui profile, that boundary creates a false friend: the source deliberately reads like HTML and Svelte, but ordinary HTML unexpectedly fails. It also conflates three different things:

1. platform-owned HTML elements;
2. Uhura-owned privileged rendering capabilities; and
3. compound widgets that should eventually be ordinary reusable components.

The correct invariant is not “every tag is an Uhura primitive.” It is:

Close behavior and authority; reuse inert platform vocabulary.

1. HTML is the baseline

use uhura::ui; activates the checked Web presentation profile. Within that profile:

• known standard HTML body elements use their lowercase standard names;
• standard elements lower to the same HTML element rather than an Uhura imitation;
• the checker uses a version-pinned, data-driven HTML schema for element names, content models, global attributes, element attributes, and voidness;
• the browser renderer realizes ordinary admitted HTML through its generic element path; and
• Editor provenance, stable node identity, annotations, static examples, and reconciliation continue to apply to those nodes.

Therefore this should be ordinary valid source:

<pre>
  <code>{view.source}</code>
</pre>

HTML-first does not mean unchecked raw markup:

• unknown names and custom elements remain rejected unless a later explicit integration admits them;
• raw on* JavaScript attributes and script execution remain rejected;
• machine interaction still uses checked on event -> Input(...) bindings;
• elements that request host authority, navigation, embedding, or execution may require a stricter checked contract or an explicit capability; and
• Uhura may add accessibility and state-flow checks to a standard element without changing that element's HTML identity.

<button>, <input>, <img>, <video>, <progress>, and similar names therefore remain HTML elements. Uhura may refine their accepted attributes, accessible-name requirements, resource admission, or semantic machine events where justified; refinement does not make them a new widget ontology.

2. Primitive admission rule

An Uhura-owned intrinsic belongs in the minimal UI core only when all of these hold:

1. HTML does not already provide the semantic capability.
2. Privileged coordination is unavoidable. Correct realization needs renderer, Editor, resource, or host support unavailable to ordinary UI composition.
3. The contract is theme-independent. It describes semantic or physical capability, not a visual design system.
4. Ordinary composition is insufficient. HTML, machine state, CSS, and the public component model cannot reproduce it faithfully.
5. The contract is small and stable. It can be checked, previewed, lowered, and tested without absorbing an application pattern.

A missing component feature is not evidence that a construct is primitive. If a widget is compiler-known only because reusable UI calls do not exist yet, the correct prerequisite is the component model.

3. Initial minimal intrinsic set

Scroll

Scroll earns an intrinsic capability because HTML has scrolling mechanics but no semantic scroll element or declarative contract for Uhura's additional requirements:

• the renderer owns physical offset, momentum, layout measurement, and interruption;
• static Editor examples can request a normalized exact position in the inclusive 0..1 range;
• semantic viewport observations such as near-end can return through a checked event without exposing raw DOM scroll callbacks; and
• Editor and Play need the same stable node and capability contract even though static preview never simulates physical scrolling.

The intrinsic must remain a viewport capability, not grow carousel controls, indicators, selection state, pagination policy, or theme.

Whether its final source form is an element or an attached behavior may still be evaluated, but the underlying capability is justified.

Icon

Icon earns an intrinsic capability because the semantic source is a logical glyph token, while the renderer and project resources own its physical font realization:

• family and glyph names resolve against a finite checked registry;
• missing families and names fail before Editor or Play rendering;
• font/resource admission is shared across checker, host, Editor, and Play;
• source does not embed engine-owned SVG geometry or opaque Unicode code points; and
• the intrinsic itself is unthemed: icon packs, sizing, color, and surrounding controls remain separate concerns.

The initial implementation may remain font-backed. Supporting SVG registries or other icon resource forms is outside this issue.

Source shape

The conceptual source should remain compact:

use uhura::ui;
use uhura::ui::{Scroll, Icon};

pub ui SourcePreview for App(view) {
  <main>
    <pre><code>{view.source}</code></pre>

    <Scroll position={0.5}>
      <button on press -> Favorite>
        <Icon name="heart" />
        Favorite
      </button>
    </Scroll>
  </main>
}

The exact grouping syntax can be tuned with the module design. A public uhura::ui::core namespace is not required: “core” should continue to mean the standalone machine/kernel in architectural discussion. The important contract is that the intrinsic set is finite, explicit, and much smaller than the HTML vocabulary.

4. Current non-core elements

Current element	Proposed disposition	Rationale
<view>	Use HTML such as <div>, <section>, <nav>, or lists	A neutral HTML container or semantic HTML element already owns this role
<text>	Use <p>, <span>, headings, and other HTML text semantics	The current adapter maps to an HTML paragraph and adds no irreducible capability
<pager>	Later component(s), not a primitive	Carousel, tabs, pagination, and swipe view have different semantics; indicators and snap layout are compound policy
<textfield>	HTML <input>/<textarea> plus a later compound TextField component	Label, help, validation, error, and styling anatomy are composable widget concerns
<region>	Native <button>/<a> or a later headless Pressable component	A div made clickable should not outrank native HTML interaction
<Link>	Explicit routing/framework capability	Typed location and browser-history authority are not UI-core concerns
<Surface>	Explicit surface/orchestration capability, reviewed separately	Portal placement, stacking, focus containment, inertness, and return are privileged, but a Surface is not an ordinary element-tree primitive

Pager must not simply be renamed to Tabs. A carousel viewport, an accessible tab set, data pagination, and swipe navigation are separate contracts. A later component system may implement each over HTML, machine state, Scroll, CSS, and any narrowly justified behavior capability.

Styling and component systems are deferred

This issue does not design shadcn-style distribution, Nova, a headless widget library, Tailwind integration, or another theme.

Because the baseline is real HTML with ordinary class output, CSS and utility-class toolchains can remain host/build concerns rather than language primitives. A future themed system should use the same public component ABI as application code. It must not require another compiler switch for every component name.

A shadcn-like source-copy workflow, an independently versioned themed package, and a headless accessibility package remain possible later. None belong in the minimal UI core proposed here.

Required language boundary

Making compound widgets non-primitive requires a reusable checked UI component contract. That future work must define props/values, children or slots, semantic outputs, identity, expansion, styles/resources, provenance, and any state ownership. This issue does not select that contract.

Until it exists, the inability to express a package-level Tabs or TextField is an implementation limitation, not justification for promoting those widgets into the intrinsic catalogue.

Non-goals

• designing or adopting a themed component system;
• defining shadcn/Nova/Tailwind packaging;
• designing the reusable component ABI;
• admitting arbitrary custom elements or raw JavaScript;
• redesigning routing, surfaces, or the meta-framework;
• adding animation, gesture, media-controller, form, or provider integrations;
• preserving the 0.4 element set for compatibility; or
• deciding every candidate recorded in Prior study: Uhura element and widget candidate landscape #19.

Conformance consequences

A later implementation should prove at minimum:

1. standard passive HTML such as <pre>, <code>, headings, lists, and tables checks and renders through the generic HTML path;
2. misspelled, unknown, custom, script, and raw event-handler forms fail with precise diagnostics;
3. standard interactive/resource elements retain their HTML identity while Uhura-specific checks remain enforceable;
4. Scroll preserves normalized static preview pose and checked viewport events without exposing raw DOM state;
5. Icon preserves finite resource validation and Editor/Play parity;
6. HTML schema data and Uhura intrinsic contracts are separate implementation owners;
7. adding ordinary passive HTML support does not require a new renderer adapter; and
8. no removed compound widget is retained through a legacy parser, alias, or compatibility runtime.

Exit criterion

This issue is ready to become implementation or a bounded RFC when the project agrees on:

• HTML as the lowercase platform vocabulary;
• the primitive admission rule;
• Scroll and Icon as the initial minimal intrinsic capabilities;
• the separate status of routing and surfaces;
• the non-core disposition of the current composite/alias elements; and
• the checker/renderer ownership split between the HTML schema and intrinsic adapters.

Anything beyond that small boundary should evolve through ordinary components, explicit integrations, or later focused proposals.

[k08200]

Agree with the boundary — #28's enumeration covers exactly the vocabulary this proposal disposes, and the pager row matches what #25 found (key-based current page, at-rest event — carries over to the later component).

Two gaps worth closing in this issue:

1. The admission rule covers elements but not events. With HTML as the baseline, what may on event -> bind to? "May refine semantic machine events where justified" names per-element refinement, but without an event-admission rule the replay surface is either open-ended or silently tiny.
2. Demoting textfield to raw <input> re-opens the draft-ownership question from the feat!: replace Uhura with the 0.4 machine-first language #24 discussion for every stateful HTML element (input, textarea, details, dialog). Worth restating the state-ownership rule for the generic path, plus a day-one list of kept accessibility refinements — the current checker enforces labels on textfield/video/pager/region and alt-or-decorative on img, and HTML-first shouldn't quietly drop that.

[softmarshmallow]

The separately reviewed Surface capability now has its dedicated RFD at #41. This issue remains scoped to the HTML baseline and minimal-intrinsic boundary; #41 owns Modal/Dialog/Sheet semantics, modality scope, dismissal, focus, and renderer-owned presence.