@react-x11/components 0.1.0 → 0.2.0

package/src/internal/heights.ts

@@ -0,0 +1,211 @@
+// Where every row starts, when rows are not all the same height.
+//
+// **Shared between `<Tree>` and `<Table>`** — the one piece of machinery
+// both virtualizers stand on, promoted here from the vendored copy the
+// table briefly carried (docs/prd-table.md records the decision). "No
+// component imports another component" holds: this is shared code, not a
+// component, and both import it.
+//
+// **Deliberately not a shared *module*.** The directory has no `index.ts`,
+// so it has no subpath, no docs page, and is not public API — the repo's
+// guards (`test/docs.test.ts`, `scripts/check-package.ts`) key on
+// `src/<name>/index.ts`, and that is the seam this uses. The day an app
+// outside this package needs a height index of its own, the promotion is
+// mechanical: give the directory an `index.ts` and the full shared-module
+// treatment (subpath, page, barrel), the way `richtext` has it.
+//
+// The id-keying earns its place twice: in the tree a measured height
+// survives a collapse and re-expand, and in the table it survives a
+// **re-sort** — the permutation rebuilds offsets without remeasuring a
+// single row.
+//
+// A fixed-height list needs no structure at all: row `i` is at `i * h`, and
+// the row at offset `y` is `y / h`. That one multiplication is the whole
+// reason fixed-height virtualization is easy, and it is what this file
+// replaces — because a tree row wraps, carries two lines, or is whatever a
+// render seam returned, and demanding that they all match would be the
+// component telling the application what its data may look like.
+//
+// What replaces it has to answer three questions on every scroll, over a
+// list that may be a hundred thousand rows long:
+//
+//   - where does row `i` start?           `offsetAt`
+//   - which row is at offset `y`?         `indexAt`
+//   - how tall is the whole thing?        `total`
+//
+// A prefix-sum array answers the first and third in O(1) but costs O(n) per
+// measurement, and measurements arrive in bursts — every row that scrolls
+// into view is one. A Fenwick tree (binary indexed tree) answers all three in
+// O(log n) and updates in O(log n), which is what makes "measure the rows
+// that just appeared, then re-render" affordable at any size.
+
+/** What a row is keyed by. `TreeItemId` and `TableRowId` are both this
+ *  type; keeping it structural here is what lets each component keep its
+ *  own vocabulary. */
+export type RowKey = string | number;
+
+/** All this needs of a row. Taking the rows themselves rather than an array
+ *  of ids is what keeps `sync` free on a re-render: the component already
+ *  memoizes the row list, so identity alone says "nothing moved". */
+interface Keyed {
+  id: RowKey;
+}
+
+/**
+ * The heights of the rows, and where each one starts.
+ *
+ * Mutable and long-lived: one of these belongs to a component for as long
+ * as it is mounted, and `sync` re-points it at the rows a render is about
+ * to draw. It is deliberately **not** React state — a measurement pass
+ * touches it once per rendered row and the component re-renders once, on a
+ * version counter, and only when something actually moved.
+ */
+export class RowHeights {
+  /** Measured heights, by row id. Survives `sync`. */
+  private readonly measured = new Map<RowKey, number>();
+  /** The rows currently indexed, in draw order. */
+  private rows: readonly Keyed[] = [];
+  /** Fenwick tree over the heights, 1-based. */
+  private tree: number[] = [0];
+  /** What an unmeasured row is assumed to be. */
+  private estimate = 1;
+  /** Largest power of two <= n, for the O(log n) descent in `indexAt`. */
+  private power = 0;
+  /** Set when a measurement could not be applied in place, so the next
+   *  `sync` must rebuild even though the row list did not change. */
+  private dirty = false;
+
+  constructor(estimate: number) {
+    this.estimate = Math.max(1, estimate);
+  }
+
+  private heightOf(index: number): number {
+    const measured = this.measured.get(this.rows[index].id);
+    return measured === undefined ? this.estimate : measured;
+  }
+
+  /**
+   * Point the index at the rows about to be drawn.
+   *
+   * Rebuilt rather than patched, and cheap to call on every render: the row
+   * list is memoized, so the common case is an identity check. When it does
+   * rebuild it is O(n) — the rows change when a branch opens, when items
+   * arrive, when a sort flips, when a filter runs, all O(n) events already.
+   */
+  sync(rows: readonly Keyed[], estimate: number): void {
+    const next = Math.max(1, estimate);
+    if (!this.dirty && this.rows === rows && next === this.estimate) return;
+    this.dirty = false;
+    this.rows = rows;
+    this.estimate = next;
+    const n = rows.length;
+    // Build in O(n): write each height at its own slot, then push every slot
+    // into its parent. The textbook loop of point-updates is O(n log n) and
+    // arrives at the same tree.
+    const tree = new Array<number>(n + 1).fill(0);
+    for (let i = 0; i < n; i++) tree[i + 1] = this.heightOf(i);
+    for (let i = 1; i <= n; i++) {
+      const parent = i + (i & -i);
+      if (parent <= n) tree[parent] += tree[i];
+    }
+    this.tree = tree;
+    this.power = n > 0 ? 1 << Math.floor(Math.log2(n)) : 0;
+  }
+
+  /**
+   * Record what a row actually laid out at. Returns whether this changed
+   * anything — which is what tells the component whether to re-render, and
+   * the reason a measurement pass that finds nothing new costs nothing.
+   */
+  measure(id: RowKey, index: number, height: number): boolean {
+    if (!(height > 0)) return false;
+    const before = this.measured.get(id);
+    if (before === height) return false;
+    this.measured.set(id, height);
+    if (this.rows[index]?.id !== id) {
+      // The caller's index is stale — the rows moved under a measurement
+      // that was already in flight. Applying a delta at the wrong slot would
+      // corrupt every offset after it, so the tree is rebuilt instead.
+      this.dirty = true;
+      return true;
+    }
+    const delta = height - (before === undefined ? this.estimate : before);
+    if (delta === 0) return false;
+    for (let i = index + 1; i < this.tree.length; i += i & -i) {
+      this.tree[i] += delta;
+    }
+    return true;
+  }
+
+  /** What a row measured, or the estimate if it has not been seen. */
+  heightAt(index: number): number {
+    return index >= 0 && index < this.rows.length ? this.heightOf(index) : 0;
+  }
+
+  /** Whether this row has a real measurement rather than an estimate. */
+  isMeasured(index: number): boolean {
+    const row = this.rows[index];
+    return row !== undefined && this.measured.has(row.id);
+  }
+
+  /** Where row `index` starts. `offsetAt(rowCount)` is the total. */
+  offsetAt(index: number): number {
+    let sum = 0;
+    for (
+      let i = Math.max(0, Math.min(index, this.rows.length));
+      i > 0;
+      i -= i & -i
+    ) {
+      sum += this.tree[i];
+    }
+    return sum;
+  }
+
+  /** How tall the whole list is — what the scrollbar measures. */
+  total(): number {
+    return this.offsetAt(this.rows.length);
+  }
+
+  /**
+   * The row containing `offset`, clamped into the list.
+   *
+   * A descent down the tree rather than a binary search over `offsetAt`,
+   * which would be O(log² n) — this is the operation every scroll performs,
+   * twice.
+   */
+  indexAt(offset: number): number {
+    const n = this.rows.length;
+    if (n === 0) return 0;
+    let index = 0;
+    let remaining = offset;
+    for (let step = this.power; step > 0; step >>= 1) {
+      const next = index + step;
+      if (next <= n && this.tree[next] <= remaining) {
+        index = next;
+        remaining -= this.tree[next];
+      }
+    }
+    return Math.max(0, Math.min(n - 1, index));
+  }
+
+  /** How many of the current rows have a real measurement. */
+  measuredCount(): number {
+    let count = 0;
+    for (const row of this.rows) if (this.measured.has(row.id)) count++;
+    return count;
+  }
+
+  /**
+   * Forget every measurement, keeping the row list.
+   *
+   * For a change that invalidates heights wholesale rather than row by row.
+   * Nothing calls it for new items — their ids are simply not in the map yet
+   * — and nothing calls it on a resize either: rows re-measure as they are
+   * drawn, and throwing away the heights of rows whose content does not
+   * depend on the width would make the scrollbar worse, not better.
+   */
+  reset(): void {
+    this.measured.clear();
+    this.dirty = true;
+  }
+}

package/src/internal/hx.ts

@@ -0,0 +1,53 @@
+// `React.createElement`, typed against react-x11's host elements.
+//
+// The library writes `h(...)` rather than JSX — a convention inherited from
+// core, and worth keeping so moving code between the two repos stays a
+// rename. Shared by every composed widget out here (`<Calendar>`,
+// `<DatePicker>`, `<ColorPicker>`, `<ColorField>`), which is why it sits in
+// `src/internal/` rather than in one of them. But `React.createElement`'s own overloads are `@types/react`'s, and
+// they describe the DOM: a `<box onKeyDown>` handler is checked against
+// React's `KeyboardEvent`, not react-x11's, and the whole props object is
+// measured against `DOMAttributes`. Everything interesting fails.
+//
+// So the element name is looked up in react-x11's own element table instead.
+// `hx('box', …)` gets `<box>`'s real props — `ev.keysym` on a key handler,
+// `onDraw` on a `<canvas>` — and `hx('div', …)` is an error, which is the
+// same guarantee the JSX namespace gives `examples/` and `test/types/`.
+import React from 'react';
+import type { Key, ReactElement, ReactNode } from 'react';
+import type { ReactX11Elements, Theme } from 'react-x11';
+
+/** The host elements, by name. */
+export type Host = ReactX11Elements;
+
+/**
+ * What every element takes on top of its own props.
+ *
+ * `theme` is honoured by **every** node — `Node.theme` merges `props.theme`
+ * over the inherited palette, whatever the kind — but react-x11's element
+ * declarations only put it on `<window>`. A widget re-declares the theme it
+ * read from context onto its own root so that `$token` values still resolve
+ * inside a `<popup>`, which is a separate window and does not inherit the
+ * trigger's node tree. So the prop is real; only the declaration is narrow.
+ */
+interface CommonProps {
+  key?: Key;
+  /** `Theme` is listed alongside the record because it is an interface, and
+   *  an interface has no implicit index signature — so the palette `useTheme`
+   *  hands back is not assignable to the record react-x11 declares. */
+  theme?: Theme | Record<string, string | number>;
+}
+
+export function hx<K extends keyof Host>(
+  type: K,
+  // `theme` is dropped from the element's own props before the merge:
+  // `<window>` and `<popup>` already declare it, narrower, and intersecting
+  // the two would demand a value satisfying both.
+  props?: (Omit<Host[K], 'theme'> & CommonProps) | null,
+  ...children: ReactNode[]
+): ReactElement {
+  // The cast is the whole point of the wrapper: `createElement`'s string
+  // overload insists on DOM props, and the signature above has already
+  // checked these against the element that will actually receive them.
+  return React.createElement(type as string, props as never, ...children);
+}

package/src/internal/text.ts

@@ -0,0 +1,44 @@
+// The bits `<richtext>` and `<Html>` need that react-x11 has but does not
+// export. Same situation, and the same shape, as `src/calendar/internal.ts` —
+// each is small and pure, and if core ever puts one on its exports map,
+// delete it from here and import it. `tint` was the first to go that way: it
+// is `react-x11/style`'s now, and the surfaces here import it from there.
+//
+// It sits in `src/internal/` rather than in `src/richtext/` because two
+// things share it now — the shared module and `src/html/`'s own layout — and
+// that is exactly what this directory is for (AGENTS.md, "the half-step below
+// a shared module").
+
+// --- code points vs code units ---------------------------------------------
+//
+// ntk's line runs report their extent in **code units** while its caret API
+// speaks **code points**, so anything reading run geometry has to translate.
+// Core has exactly these two functions in `src/textrange.js` (react-x11#291)
+// and its `<text>` uses them for the same purpose; they are copied rather
+// than imported because that module is not on core's exports map. Delete
+// them the day it is.
+
+/** Code point index -> UTF-16 offset, with one extra entry for the end. */
+export function codeUnitOffsets(text: string): number[] {
+  const offsets: number[] = [];
+  const s = text ?? '';
+  for (let i = 0; i < s.length;) {
+    offsets.push(i);
+    i += (s.codePointAt(i) ?? 0) > 0xffff ? 2 : 1;
+  }
+  offsets.push(s.length);
+  return offsets;
+}
+
+/** The code point index for a UTF-16 offset, rounded down to a whole
+ *  character. Binary search over `codeUnitOffsets`. */
+export function codePointAtOffset(offsets: number[], offset: number): number {
+  let lo = 0;
+  let hi = offsets.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (offsets[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}

package/src/internal/timers.ts

@@ -0,0 +1,44 @@
+// "Run this once layout has happened", reached through `globalThis`.
+//
+// **Shared between `<Tree>` and `<Table>`** — promoted here with the height
+// index beside it; see `./heights.ts` for why this directory is internal
+// rather than a shared module with a subpath.
+//
+// The build compiles `src/` with `types: []` on purpose — a Node global that
+// wanders in must fail the build rather than become an implicit
+// `@types/node` dependency (AGENTS.md) — so the one timer virtualization
+// needs is typed here, structurally, the way `../code-language/timers.ts`
+// does it.
+//
+// **Why a tick and not an effect.** react-x11 lays out on a frame flush, not
+// in the commit, so a `useLayoutEffect` or a `useEffect` reads the geometry of
+// the *previous* pass: on the render that created a row, `node.abs.height` is
+// still 0. A macrotask scheduled from an effect lands after the flush, which
+// is the first moment a row can be asked how tall it turned out to be.
+interface Deferred {
+  setImmediate?(fn: () => void): unknown;
+  clearImmediate?(id: unknown): void;
+  setTimeout?(fn: () => void, ms: number): unknown;
+  clearTimeout?(id: unknown): void;
+}
+
+const g = globalThis as Deferred;
+
+export type LayoutTick = { immediate: boolean; id: unknown } | null;
+
+/** Run `fn` after the layout pass this commit will cause. */
+export function afterLayout(fn: () => void): LayoutTick {
+  // `setImmediate` is the check-phase callback, which runs after the frame
+  // work node has already queued. `setTimeout(0)` is the fallback for a host
+  // that has no `setImmediate` — a browser-shaped global object, or a
+  // stripped-down runtime — and lands in the same place for this purpose.
+  if (g.setImmediate) return { immediate: true, id: g.setImmediate(fn) };
+  if (g.setTimeout) return { immediate: false, id: g.setTimeout(fn, 0) };
+  return null;
+}
+
+export function cancelAfterLayout(tick: LayoutTick): void {
+  if (!tick) return;
+  if (tick.immediate) g.clearImmediate?.(tick.id);
+  else g.clearTimeout?.(tick.id);
+}

package/src/internal/widget.ts

@@ -0,0 +1,92 @@
+// The bits of react-x11 that a value widget needs and react-x11 does not
+// export — the change event every one of them emits, and the dismiss-on-blur
+// subscription every popup one needs.
+//
+// It lived in `src/calendar/` while the calendar was the only widget out
+// here; `<ColorPicker>` is the second, which is exactly the promotion
+// `AGENTS.md` describes for `src/internal/`.
+//
+// Everything else these widgets stand on is public — `useTheme`,
+// `createStyles`, `useAnchor`/`useAnchorTracking`, the `XK_*` keysyms, the
+// host elements, and `tint` off `react-x11/style`, which used to be vendored
+// here and is not any more. These two are what is left, and they are
+// collected here rather than scattered so the list stays short and visible.
+// Each is small and pure; if core ever puts one on its exports map, delete it
+// from here and import it, the way `tint` was deleted.
+
+import { useEffect, useRef } from 'react';
+import type { RefObject } from 'react';
+
+/** The `target` a {@link WidgetChangeEvent} carries. */
+export interface ChangeTarget<T> {
+  type: string;
+  name: string | undefined;
+  value: T;
+}
+
+/**
+ * The change event the value widgets hand their `onChange`.
+ *
+ * One signature across react-x11's widgets, and this keeps to it so that
+ * `onChange={formik.handleChange}` works here too: a form library reads the
+ * field out of `ev.target`, and `{ type, name, value }` is exactly the shape
+ * formik's `handleChange` and react-hook-form's event reader destructure.
+ * `type` is what tells them a date from a text field, which is why it is set
+ * even though nothing in react-x11 reads it.
+ *
+ * `target` is a plain descriptor rather than a node: a widget is a composition
+ * of nodes with no single element holding its value, so there is nothing
+ * honest to point at. There is no `preventDefault` either — the value has
+ * already changed by the time the handler runs.
+ */
+export interface WidgetChangeEvent<T> {
+  type: 'change';
+  target: ChangeTarget<T>;
+  currentTarget: ChangeTarget<T>;
+  name: string | undefined;
+  value: T;
+}
+
+export function changeEvent<T>(
+  type: string,
+  name: string | undefined,
+  value: T,
+): WidgetChangeEvent<T> {
+  const target: ChangeTarget<T> = { type, name, value };
+  return { type: 'change', target, currentTarget: target, name, value };
+}
+
+/** The slice of the owning window a dismiss-on-blur subscription needs.
+ *  `DrawnNode` in react-x11's public types does not carry `root`, because a
+ *  ref's contract is geometry and focus rather than the window's own events. */
+interface NodeWithRoot {
+  root?: {
+    onWindowFocusChange?: (fn: (focused: boolean) => void) => () => void;
+  } | null;
+}
+
+/**
+ * Close a popup when the *window* loses focus.
+ *
+ * A trigger keeps its own focus while its override-redirect popup is up, so
+ * the trigger's `onBlur` never hears that the application went to the
+ * background — and a menu or a calendar left floating over another app's
+ * window is the bug that follows.
+ */
+export function useDismissOnWindowBlur(
+  ref: RefObject<unknown>,
+  active: boolean,
+  onDismiss: () => void,
+): void {
+  const onDismissRef = useRef(onDismiss);
+  onDismissRef.current = onDismiss;
+
+  useEffect(() => {
+    if (!active) return undefined;
+    const root = (ref.current as NodeWithRoot | null)?.root;
+    if (!root?.onWindowFocusChange) return undefined;
+    return root.onWindowFocusChange((focused: boolean) => {
+      if (!focused) onDismissRef.current?.();
+    });
+  }, [active, ref]);
+}

package/src/markdown/ast.ts

@@ -0,0 +1,163 @@
+// The markdown AST `parse.ts` produces and `index.ts` renders. Deliberately
+// small: it is the GFM constructs this component draws, not a general
+// mdast — but it is shaped so that growing it stays additive. In particular
+// `component` is reserved for the MDX direction: a parser extension can emit
+// one without the renderer, the selection model or the caches changing shape
+// (see "MDX" in index.ts).
+
+/** Inline content, inside a paragraph, heading, list item or table cell. */
+export type InlineNode =
+  | TextInline
+  | CodeInline
+  | EmphasisInline
+  | LinkInline
+  | BreakInline
+  | ComponentInline;
+
+/** A run of plain text. Softbreaks arrive collapsed to spaces. */
+export interface TextInline {
+  type: 'text';
+  text: string;
+}
+
+/** An inline code span. */
+export interface CodeInline {
+  type: 'code';
+  text: string;
+}
+
+/** `strong` is `**`, `em` is `*`, `del` is `~~`. */
+export interface EmphasisInline {
+  type: 'strong' | 'em' | 'del';
+  children: InlineNode[];
+}
+
+/**
+ * A link, or an image rendered as its alt text (this component draws no
+ * remote bitmaps — see index.ts). `href: null` is a link still streaming
+ * in: the text is styled as a link but there is nothing to navigate to yet.
+ */
+export interface LinkInline {
+  type: 'link';
+  href: string | null;
+  /** True when this was `![alt](src)` — the href is the image source. */
+  image: boolean;
+  children: InlineNode[];
+}
+
+/** A hard line break (two trailing spaces, or a trailing backslash). */
+export interface BreakInline {
+  type: 'break';
+}
+
+/**
+ * Reserved for MDX: `<Chart data={…} />` would parse to one of these. The
+ * current parser never emits it; the renderer maps unknown names to plain
+ * text so a future parser upgrade cannot crash an older renderer.
+ */
+export interface ComponentInline {
+  type: 'component';
+  name: string;
+  attributes: Record<string, string>;
+  children: InlineNode[];
+}
+
+/** Block-level content. */
+export type BlockNode =
+  | ParagraphBlock
+  | HeadingBlock
+  | CodeBlock
+  | QuoteBlock
+  | ListBlock
+  | TableBlock
+  | RuleBlock;
+
+export interface ParagraphBlock {
+  type: 'paragraph';
+  children: InlineNode[];
+}
+
+export interface HeadingBlock {
+  type: 'heading';
+  /** 1–6. Setext `===` is 1, `---` is 2. */
+  depth: number;
+  children: InlineNode[];
+}
+
+/** A fenced or indented code block. Text has no trailing newline. */
+export interface CodeBlock {
+  type: 'code';
+  /** First word of the info string, lowercased — `''` when absent. */
+  lang: string;
+  text: string;
+  /**
+   * False when the closing fence has not arrived. During streaming that is
+   * the normal state of the last block and not worth signalling to the
+   * user; a renderer could badge it if it wanted to.
+   */
+  closed: boolean;
+}
+
+export interface QuoteBlock {
+  type: 'quote';
+  children: BlockNode[];
+}
+
+export interface ListBlock {
+  type: 'list';
+  ordered: boolean;
+  /** Start number of an ordered list; 1 for bullet lists. */
+  start: number;
+  /**
+   * A tight list renders items without paragraph spacing between them —
+   * the CommonMark distinction, decided by blank lines in the source.
+   */
+  tight: boolean;
+  items: ListItem[];
+}
+
+export interface ListItem {
+  /** `null` for a plain item; true/false for a GFM task checkbox. */
+  checked: boolean | null;
+  children: BlockNode[];
+}
+
+export type TableAlign = 'left' | 'center' | 'right' | null;
+
+export interface TableBlock {
+  type: 'table';
+  /** One entry per column, from the delimiter row. */
+  align: TableAlign[];
+  /** Header cells. Always exactly `align.length` long. */
+  header: InlineNode[][];
+  /** Body rows, each padded or truncated to `align.length` cells. */
+  rows: InlineNode[][][];
+}
+
+export interface RuleBlock {
+  type: 'rule';
+}
+
+/** What `parse` returns. */
+export interface Document {
+  blocks: BlockNode[];
+  /**
+   * The raw source of each top-level block, index-aligned with `blocks`.
+   * This is the streaming cache key: a block whose raw text did not change
+   * between two parses produced an equal AST, so a renderer can reuse
+   * everything it derived from it (see index.ts).
+   */
+  raws: string[];
+}
+
+export interface ParseOptions {
+  /**
+   * Treat the end of input as "more is coming" (default true): unclosed
+   * emphasis, code spans and links that reach the end of the source are
+   * completed instead of falling back to literal text, half-arrived
+   * constructs (`![alt](…`, a lone trailing `**`, a bare `#`) are hidden,
+   * and an ambiguous final line (`---` that could still become a setext
+   * underline or a rule) is held back. Pass false for text that is final.
+   */
+  partial?: boolean;
+}

package/src/markdown/hx.ts

@@ -0,0 +1,51 @@
+// `React.createElement`, typed against react-x11's host elements.
+//
+// The library writes `h(...)` rather than JSX — a convention inherited from
+// core, and worth keeping so moving code between the two repos stays a
+// rename. But `React.createElement`'s own overloads are `@types/react`'s, and
+// they describe the DOM: a `<box onKeyDown>` handler is checked against
+// React's `KeyboardEvent`, not react-x11's, and the whole props object is
+// measured against `DOMAttributes`. Everything interesting fails.
+//
+// So the element name is looked up in react-x11's own element table instead.
+// `hx('box', …)` gets `<box>`'s real props — `ev.keysym` on a key handler,
+// `onDraw` on a `<canvas>` — and `hx('div', …)` is an error, which is the
+// same guarantee the JSX namespace gives `examples/` and `test/types/`.
+import React from 'react';
+import type { Key, ReactElement, ReactNode } from 'react';
+import type { ReactX11Elements, Theme } from 'react-x11';
+
+/** The host elements, by name. */
+export type Host = ReactX11Elements;
+
+/**
+ * What every element takes on top of its own props.
+ *
+ * `theme` is honoured by **every** node — `Node.theme` merges `props.theme`
+ * over the inherited palette, whatever the kind — but react-x11's element
+ * declarations only put it on `<window>`. A widget re-declares the theme it
+ * read from context onto its own root so that `$token` values still resolve
+ * inside a `<popup>`, which is a separate window and does not inherit the
+ * trigger's node tree. So the prop is real; only the declaration is narrow.
+ */
+interface CommonProps {
+  key?: Key;
+  /** `Theme` is listed alongside the record because it is an interface, and
+   *  an interface has no implicit index signature — so the palette `useTheme`
+   *  hands back is not assignable to the record react-x11 declares. */
+  theme?: Theme | Record<string, string | number>;
+}
+
+export function hx<K extends keyof Host>(
+  type: K,
+  // `theme` is dropped from the element's own props before the merge:
+  // `<window>` and `<popup>` already declare it, narrower, and intersecting
+  // the two would demand a value satisfying both.
+  props?: (Omit<Host[K], 'theme'> & CommonProps) | null,
+  ...children: ReactNode[]
+): ReactElement {
+  // The cast is the whole point of the wrapper: `createElement`'s string
+  // overload insists on DOM props, and the signature above has already
+  // checked these against the element that will actually receive them.
+  return React.createElement(type as string, props as never, ...children);
+}