@exponential_app/eui-solid: the genUI SolidJS renderer

The SolidJS renderer of genUI (FEED-128): an A2UI surface in the core catalog (@exponential_app/eui) painted with the identical DOM of the React renderer (@exponential_app/eui-react), with the same compiled stylesheet and runtime themes. Overlays, menus, selects, tabs, accordions and the form controls paint Radix's DOM on plain elements, on a headless layer (src/behaviors/) that reproduces Radix's machinery: positioning on @floating-ui/dom, modality on aria-hidden. It depends on @exponential_app/eui (the shared web layer @exponential_app/eui/web), solid-js, @floating-ui/dom, aria-hidden and lucide-solid. It imports nothing from the React renderer and nothing from the Exponential app.

The invariant

For every surface the Solid painter produces exactly what React paints:

• the same elements and attribute set, with the same values: the class strings in the same order, data-xui-id, data-xui-part, data-xui-c, data-r-*/data-m-*, data-xs, aria-*;
• the same <style data-xui-style="theme"> (BASE_CSS + the compiled theme) and <style data-xui-style="nodes">;
• the same root (.xui-surface <scope> xui-s-<id>, data-xui-mode, dir, data-xq) and the same overlay, toast and live-region layers.

src/test/parity.ts (expectDomParity) renders one tree in both renderers in jsdom and compares the serialised DOM (attributes sorted, generated ids renamed). Every native port adds its cases to src/parity.test.ts. A browser-level web-parity suite also compares computed styles, frames and pixels at zero tolerance.

import { ExponentialSurface, createSurface } from "@exponential_app/eui-solid"

function Chat(props: { messages: A2uiMessage[] }) {
  const surface = createSurface({ surfaceId: "main" })
  createEffect(() => props.messages.forEach(surface.apply))   // A2UI v0.9 server messages
  return (
    <ExponentialSurface
      surface={surface}
      theme="exponential"                     // or "neutral" | "playful" | "orange" | a theme JSON | a ResolvedTheme
      mode="system"                           // light | dark | system
      locale="de-AT" timeZone="Europe/Vienna"
      host={{ icons, onAction, onInput }}     // the host plugin (lucide-solid icons)
      handleRef={(h) => (handle = h)}         // handle.run({ focus: { id } } | { announce } | { scrollIntoView } | { scrollToIndex })
    />
  )
}

The props are the same as React's ExponentialSurfaceProps, with these differences:

• class/style take Solid's form (kebab-case style keys).
• handleRef is a callback that receives the SurfaceHandle.
• The React hooks have Solid names: useSurface is createSurface, useHostOwnedValue is createHostOwnedValue, useParts is parts, useField is createField, useMediaSource is createMediaSource, useHostSurface is createHostSurface, and defineReactExtension is defineSolidExtension.
• React's useWriteEpoch(ctx) is the live getter ctx.writeEpoch: hand createHostOwnedValue epoch: () => ctx.writeEpoch so a programmatic write (an action set, ctx.assignData) wins over a focused field.

The QrScanner camera (qrScanner host option)

The camera is the host's (VAPP-162, docs/round-5-contract.md §7), the same hook as React's:

host={{
  qrScanner: {
    // Render the live feed into `feed` (an empty element filling the
    // viewfinder; append a <video>), decode codes of `formats` (default
    // ["qr"]) and call onValue per decoded string. Return the stop.
    start(feed: HTMLElement, formats: readonly string[], onValue: (value: string) => void): (() => void) | false | void
  },
}}

onValue dispatches scanned {value} once per distinct value (a code held in view reports once; a remount or re-enable reports it again) and announces it politely. The stop runs on unmount, on disabled and when formats change. No qrScanner, start returning false or throwing = the placeholder (ui-scan + Camera unavailable), no scan line.

Layout

Primitives

@exponential_app/eui-solid/primitives is the Solid twin of @exponential_app/eui-react/primitives (FEED-131): button, dialog, select, tabs, table, command, toast, calendar and the rest, with the same DOM and classes. The class strings come from ONE source, the recipes of @exponential_app/eui/web/primitives; neither set holds a class literal.

import "@exponential_app/eui-solid/styles.css"          // the compiled primitives sheet
import { globalsCss } from "@exponential_app/eui/web"
import { Button, Dialog, DialogContent, DialogTitle, DialogTrigger } from "@exponential_app/eui-solid/primitives"

• styles.css is dist/exponential-ui-solid.css, compiled by bun run build:css from the React package's tailwind.css: byte-identical to @exponential_app/eui-react/styles.css (src/primitives/styles.test.ts).

• Inside a surface the primitives wear its theme. Outside one, globalsCss(theme) writes the theme as shadcn variables (:root + .dark).

• The names follow Solid: class for className, as for asChild (the element or component the part paints as), create* for the use* hooks.

• React's SegmentedControl has no embedded arm either: the glass-group row is the Exponential app's (@exp/ui), like its other own components.

• The web-parity gate compares every specimen of @exponential_app/eui/fixtures/primitive-specimens.json with React's over the whole page body: bun run --filter @exponential_app/eui-solid test:parity:primitives.

• Round 6 (EXP-1495) adds Outline, Mosaic, CarouselCounter and CarouselThumbnails (React's API with class), specimens plain/outline, plain/mosaic, plain/carousel-extras; the natives' Carousel counter + thumbnails are React's markup (src/round6.test.tsx, media.parity).

State attributes: the porting rule

The theme CSS (STATE_SELECTORS) targets Radix's attribute names, so the Solid painters write the Radix-named attributes on the parts themselves. The package was first painted on Kobalte, which names the same states differently; the dependency is gone, and the Kobalte column stays as the map for porting code written against Kobalte (or any non-Radix library). The full rules are in src/natives/shared.tsx.

Commands

bun run --filter @exponential_app/eui-solid typecheck
bun run --filter @exponential_app/eui-solid test          # jsdom: surface, natives × catalog, DOM parity with React
bun run --filter @exponential_app/eui-solid dev:harness   # http://localhost:4182/?view=kitchen-sink&theme=orange
bun run --filter @exponential_app/eui-solid test:conformance  # the shared web runner → .conformance/exponential-ui-solid.json
bun run --filter @exponential_app/eui-solid test:parity       # web parity vs React → .conformance/exponential-ui-parity-react-solid.json
bun run --filter @exponential_app/eui-solid test:parity:primitives  # the primitive specimens only (seconds)
bun run --filter @exponential_app/eui-solid test:browser      # every headless-Chromium suite (overlays, inputs, tables…)
bun run --filter @exponential_app/eui-solid build:css         # dist/exponential-ui-solid.css (after ui-react's build:css)
bun run --filter @exponential_app/eui-solid shots             # the kitchen sink → /tmp/feed128/solid-shots/ (--theme, --mode, --out)

Hosted popups (VAPP-281)

As React: host.popupHost = { mount(popup), unmount?(popup) } hosts anchored Popovers and Menus outside the surface (docs/round-7-contract.md).