Supporting react-dom code on Zinc (research, 2026-10-18)

Audit of the repo plus web research. No code changed, nothing built. Tags: [repo] = read in this tree (path:line); URLs = fetched 2026-10-18; [measured] = measured here (method given); [general] = general knowledge, no source fetched; UNVERIFIED = not confirmed.

0. Answers to the direct questions

• Is real React (react, react-reconciler) used today? No. The React model is a re-implementation in Zinc strict, lib/std/react.ts (259 lines): Instance per component, hooks in an array, whole-component re-render scheduled with queueMicrotask, positional host-node reuse (lib/std/react.ts:1-3, :91-96). It is not on Solid signals either: Solid’s API is a second, separate re-implementation (lib/std/solid.ts, 336 lines, “Solid’s reactive API reimplemented”, :1). JSX is not React’s jsx() call: it is a compile-time lowering to _el/_rc/_text... helpers (src/frontend/jsx.cpp:1-5; docs/reports/zinc-quickjs-bundler.md:27-28).
• react / react-native imports are rewritten, not resolved. Under "ui": {"preset": "react-native"}, 'react' becomes zinc:ui/react and 'react-native' becomes zinc:react-native (src/frontend/jsx.cpp:1170-1176, docs/react-native.md:3-9,13-21). examples/rn-port/src/App.tsx:4-5 is a stock RN screen with import React, { useState } from 'react'; it runs on the re-implementation, not on npm React (docs/reports/rn-port-spike.md:3-8).
• The DOM does not exist on the native engines. docs/reports/zinc-next-webenv.md:1-6 says the QuickJS “web environment” “is not a DOM implementation” (opt-in, "web": true); it has elements, classList, simple selectors, events, but “Layout: none” (:57-60) and innerHTML with markup is kept as text.
• Real react + react-dom on the web export: only the element factory was tried. docs/targets/web-libraries.md:41: “react (createElement)… works… react-dom was not tried”. docs/targets/web.md:355-356 says React/Preact/react-dom “are not needed”.

1. Exists

2. Partial

3. Missing

• Context: no createContext, useContext, memo, forwardRef, Fragment (JSX fragment is lowered, not an API), Suspense, lazy, useId, useTransition, useDeferredValue, useSyncExternalStore, useImperativeHandle, createPortal, StrictMode, Children, cloneElement, createElement. Grep of lib/ for useContext|createContext hits only lib/std/gl.ts (WebGL contexts, unrelated). This is what breaks most npm React libraries (React Router, Radix, TanStack Query, Zustand’s hook, Redux’s hooks, Testing Library).
• Elements as values: JSX is statement-lowered into host calls during render; there is no element tree object, so children inspection, cloneElement, React.Children.map, render props returning elements stored in state, and createElement from a library cannot work. This is the structural reason real npm React cannot sit on zinc:ui/react.
• Lowercase intrinsic tags. Z0007 refuses <div>, so react-dom code cannot compile today (src/frontend/jsx.cpp:442-451). AGENTS.md: “never add a back door that accepts the old spelling”. Any react-dom mode needs an explicit, preset-scoped owner decision (section 7, item 1).
• CSS: no cascade, no selectors, no stylesheet, no <style>/.css for DOM tags; display: block/inline/inline-block/grid/table absent (only flex, none, contents, lib/std/ui.ts:292,1071; docs/reports/layout-engines.md:23 “Missing: grid, sticky”), no margin collapsing (same as RN, :66), no float, no position: sticky/fixed, no pseudo-classes beyond Tailwind-like variants.
• Document APIs on native: layout (getBoundingClientRect, offsetWidth), innerHTML parsing, DOMParser, FormData, Worker, cookies (docs/reports/zinc-next-webenv.md:57-60), getComputedStyle is a stub.
• Concurrent React, Suspense, use(), Actions, useOptimistic, useActionState, form action: none.
• react-reconciler host or any real-React bridge: none (grep react-reconciler|react-dom in repo finds only four docs: docs/targets/web.md, web-libraries.md, ui-rendering-architecture.md:113, zinc-next-open-questions.md).

4. Definitions and web research

4.1 react-reconciler (option C)

• Current: react-reconciler@0.34.0, MIT, peer react ^19.3.0, dep scheduler ^0.28.0, unpacked 1.85 MB (npm registry, https://registry.npmjs.org/react-reconciler/latest, fetched today).
• Host config README: you pass a host-config object to Reconciler(HostConfig). Mutation mode (supportsMutation: createInstance, appendChild, commitUpdate, removeChild, …) is what react-dom uses; persistent mode (clones) is what React Native Fabric uses. The README says the API “is not as stable as that of React”, “experimental”, “does not follow the common versioning scheme”, use “at your own risk” (https://github.com/facebook/react/blob/main/packages/react-reconciler/README.md). Consequence: a host config is pinned to one React minor; each React upgrade is a porting task (0.x versions break by design).
• Users: Ink calls itself “a React renderer” (https://github.com/vadimdemedes/ink); react-three-fiber “can render to a root, similar to how react-dom and all the other React renderers work” (https://r3f.docs.pmnd.rs/api/canvas); the RN Skia repo in this tree’s research uses a custom reconciler host (docs/reports/ui-rendering-architecture.md:113). react-pdf, react-blessed, NativeScript-React, Lynx (ReactLynx): [general], not fetched here; Lynx is believed Preact-based, UNVERIFIED.
• React 19 points for a host (https://react.dev/blog/2024/12/05/react-19): ref as a prop (function components receive it), ref callbacks may return a cleanup (the host must skip the null call when a cleanup exists), <Context> as a provider, use(), Actions in transitions, <form action={fn}>, useActionState, useOptimistic. Server Components are irrelevant here. Form action and requestFormReset are DOM-host features that a DOM-subset host must implement or reject.

4.2 react-native-web (the reverse mapping)

“A compatibility layer between React DOM and React Native”: renders RN components with React DOM, styles in JS compiled to CSS, gesture responder (https://necolas.github.io/react-native-web/docs/). Zinc’s web export DOM mode already does a similar thing from a different direction (Zinc styles -> generated atomic classes, docs/targets/web.md:99-104). The reverse of the owner’s goal is therefore half solved; what is missing is DOM-authored code.

4.3 Sizes (measured: esm.sh minified ES2022 bundles, 2026-10-18, gzip -9)

React + react-dom is about 190 KB min / 60 KB gz; React + a custom reconciler about 127 KB min / 41 KB gz. Preact alone is about 5 KB gz (the “3-4 KB” claim of its marketing is for a smaller build; preact/compat was not fetchable here). For scale: the web export of examples/hero is 380 KB / 118 KB br (docs/reports/zinc-web-export.md:141) (QuickJS startup numbers: docs/reports/zinc-quickjs-bundler.md:120-131, not React-specific).

Startup/memory of React on QuickJS: no source found (one search; QuickJS runtime life cycle under 300 us and Micro QuickJS ES5-only are the only data, https://linuxiac.com/qemu-and-ffmpeg-founder-introduces-micro-quickjs-javascript-engine/). Micro QuickJS cannot run React (ES5 subset). QuickJS-ng has no inline caches and is 3-6x slower than Zinc’s typed interpreter on numeric kernels (docs/reports/zinc-quickjs-bundler.md:20, docs/reports/zinc-next-quickjs.md:31). Must be measured before promising small devices (work item 3). On the ESP32 target Zinc already forbids the QuickJS engine (docs/reports/zinc-next-quickjs.md:30).

4.4 DOM implementations in JS (option B inside QuickJS)

jsdom vs happy-dom: happy-dom’s own benchmark: import 333 vs 45 ms, parse HTML 256 vs 26 ms, custom element render 214 vs 19 ms (jsdom vs happy-dom; same table in every README version, so possibly stale; https://cdn.jsdelivr.net/npm/happy-dom@20.14.0/README.md). No heap numbers found. Neither has layout (they return zeros for getBoundingClientRect). Both exist to run tests, not to paint, and need Node built-ins (fs, stream, url), which stop the link on QuickJS (docs/targets/web-libraries.md:65-70). Not recommended; Zinc’s own webenv (zinc-next-webenv.md) already decided “a thin environment of our own, 67, against a DOM library in JavaScript inside QuickJS, 43” (:5-6).

4.5 Browser engines without a browser

• Blitz (Dioxus Labs): native HTML/CSS renderer on Stylo (CSS), Taffy (box layout), Parley (text/inline layout), Vello/wgpu painting, AccessKit “coming soon”; omits WebRTC, WebSockets, localStorage; “experimental” in Dioxus 0.7 docs (https://gitee.com/mrlijing/blitz mirror of the README; https://dioxuslabs.com/learn/0.7/beyond/project_structure). Rust, GPU renderer. A secondary report says the Dioxus team joined Cognition (https://www.beri.net/article/cognition-dioxus-acquihire-blitz-taffy-crate-owners-kitesurf-dependency): UNVERIFIED.
• litehtml: CSS2/CSS3 subset layout engine in C++, host supplies drawing through a callback interface, gumbo-parser for HTML; distro packages 255 KB to 863 KB installed, not a stripped link size (search results from packages.msys2.org, pkgs.alpinelinux.org). The only candidate here that gives block/inline flow in a small C++ library. Licence BSD-3 [general]. It has no JS and no live DOM mutation API suited to React (a full re-layout API, UNVERIFIED).
• Servo / Ladybird / Flutter web HTML renderer: [general], not researched here; none fits a 100 KB-class target, and Flutter dropped its HTML renderer path [general].
• Takeaway: rendering real HTML+CSS needs Stylo-class CSS (cascade, selectors, media queries, custom properties) plus inline formatting; the smallest credible stack is megabytes and, in the Rust cases, a different language. RULES.md (proven libraries only) would permit litehtml or Blitz as vendored libraries, but neither is a drop-in for Zinc’s retained UiNode tree.

5. The gap between the browser model and Zinc’s flexbox

6. Feasibility of the options

Fidelity = share of typical react-dom component code that runs unchanged (author’s judgement, not measured).

7. Recommendation

1. Layers, in this order, with the existing typed engine kept as the small-device path.
   • Layer 0 (now, S): Web export option A. zinc export --target web --react-dom (or "web": {"framework": "react"}): app source is plain React + react-dom TSX built by esbuild (automatic JSX runtime, className already is real React JSX), Zinc supplies plugins, PWA, packaging and @zinc/vite. This delivers “React web code unchanged” on the one target where it is easy, and costs no engine work. Uses the existing bundler (docs/targets/web.md:358-385) and the pre-bundle (:372-376).
   • Layer 1 (M to L): option C for native. Real react + react-reconciler pinned to one version, bundled with zinc bundle, running on QuickJS-ng. A host config whose instances are zinc:ui node handles via the same host rows zinc:ui/react uses (lib/std/react.ts:136-168). This gives the RN-like API real Context, memo, Suspense, Fragment, key semantics, concurrent updates, and every npm hook library, with the React Native components of lib/std/react-native.tsx as host components (View, Text, …). zinc:ui/react stays as the typed-AOT fast path and for ESP32/PS1 (docs/reports/zinc-next-open-questions.md:121-123).
   • Layer 2 (M): a DOM-subset component set on top of Layer 1, not an emulated DOM: lowercase tags div span p h1..h6 button input textarea select option label a img ul ol li form section nav header footer main table registered as host types in the reconciler host (so no Z0007 conflict if the preset opts in; see risk 1), each with web defaults on Yoga (useWebDefaults), a style translator from React’s style={{...}} (camelCase CSS) to Zinc styles, and a build-time CSS translator for .css/CSS modules (class selectors, simple descendant, :hover/:focus/:disabled, media queries to breakpoints, custom properties, rem/em/vw/vh). Events: onClick -> tap, onChange/onInput, onKeyDown/Up, onFocus/onBlur, onSubmit, onMouseEnter/Leave, onPointer*, onScroll, onWheel; synthetic event with target, currentTarget, preventDefault, stopPropagation, bubbling on the existing bubble() machinery. Refs as host-instance objects with a small DOM-like surface (focus(), blur(), value, scrollTo, getBoundingClientRect from layout, style), portals as ui.openLayer.
   • Layer 3 (web export): with option A the same source runs on real react-dom; a project written for Layer 2 and exported to web uses react-dom directly (no host), so the host’s subset is exactly the intersection that also works in a browser.
2. Do not build option B. Reconfirmed by zinc-next-open-questions.md:110,128 and by the size of Blitz/litehtml-class projects (section 4.5).
3. Do not bet on Preact first. It is the cheapest runtime (5 KB gz) but needs a mini-DOM, and has no stable renderer API; it becomes interesting only if the QuickJS measurement (work item 3) shows React too heavy on a Pi-class board. Keep it as the fallback for layer 1 (same host, different engine).

8. What is unsupported and how it is reported

Unsupported in Layer 2 (explicit list, shown in docs and zinc explain):

• document/window APIs outside the existing webenv subset: document.querySelector on arbitrary selectors, getComputedStyle, MutationObserver effects, IntersectionObserver, contentEditable, execCommand, dangerouslySetInnerHTML (only inert text), <iframe>, <video> (use zinc:video), <canvas> via Canvas, drag and drop, selection API, clipboard events beyond copy/paste of text.
• CSS: display: grid | table | inline | inline-block | float, margin collapsing, position: sticky | fixed (fixed maps to a layer), pseudo-elements (::before/::after), attribute and sibling combinators beyond the supported set, @supports, @font-face (use assets), filters, clip-path, mix-blend-mode, vh on mobile semantics, calc() mixing units (supported where Yoga can resolve).
• Inline flow beyond text runs: inline-block images in a paragraph, floats, vertical-align, white-space combinations, text-overflow except single-line ellipsis and line clamp.

Reporting: reuse the existing channel, not a runtime failure.

• A lint pass at build time (like Z0006/Z0007, src/frontend/jsx.cpp:442-467, and zinc migrate) emits Zxxxx errors with a fix: display: grid is not supported on this target: use flexDirection/flexWrap, or build for web (react-dom); for the CSS translator, warnings with file:line of the rule.
• Runtime guard: ZnUnsupported already exists for web-only APIs (docs/targets/web.md:337-348, plugins/browser); a native build that touches a missing DOM global gets the same error naming the API and the Layer 0 escape (zinc export --target web).
• zinc check --target web vs native differences listed by zinc explain.

9. Conformance approach

1. Host contract tests. A small suite per host type that renders with the real reconciler and asserts the Zinc tree (ui.inspect() dump, as tests/t1/rn_port.sh does) and the layout facts. T0/T1, tests/<tier>/<name>.sh.
2. React’s own tests are not portable (they target react-dom + jsdom and internals). Take instead: (a) @testing-library/react’s query layer needs a DOM document (getByRole, getByText): not available natively. Plan: a thin @testing-library/dom-compatible query adapter over ui.inspect() (roles, labels) for Zinc-run tests, UNVERIFIED feasibility; (b) run the same test files against real react-dom in Chrome (tools/cdp.py exists, AGENTS.md) and against the Zinc host, and diff the resulting accessibility trees/text: this is the oracle idea Zinc already uses (tools/web-compare, tests/t1/web_dom_visual.sh, docs/reports/zinc-web-export.md:172).
3. Layout conformance reuses the 548 Chrome-generated Yoga cases (docs/reports/layout-engines.md:160) with web defaults, plus a CSS-translator corpus (rule -> expected Zinc style).
4. Library matrix, as in docs/targets/web-libraries.md: a pinned list of React libraries run natively (Layer 1/2) and in web (A): zustand, jotai, @tanstack/react-query, react-hook-form, react-router, clsx, zod resolvers, Radix primitives (headless), framer-motion (DOM-heavy: expected fail). Report works / works with note / does not, like the existing table.
5. Demo gate: port 2-3 existing React web examples (a todo, a form, a dashboard) unchanged; measure startup, RSS and per-update time on QuickJS vs the typed React model, record in docs/reports/zinc-next-perf.md.

10. Ordered work items

Risks to carry: (1) the capitalised-tag rule is the owner’s binding decision, so item 1 must be settled first; (2) QuickJS-ng speed on a JS-heavy reconciler is unmeasured (item 3 decides the cutoff between “desktop/Pi” and “typed engine only”); (3) the reconciler API breaks between minors, so pin and test on upgrade; (4) licences: React, react-dom, react-reconciler, scheduler are MIT (registry above); Preact MIT [general]; litehtml BSD-3 [general]; Blitz MIT/Apache [general].

Edit this page on GitHub ↗