@threenative/core 0.1.0 → 0.3.0

package/dist/react.d.ts

@@ -0,0 +1,175 @@
+import { ReactNode } from 'react';
+import { C as CanvasLayer } from './canvas-layer-CtrZHgIh.js';
+import 'three';
+import 'three/webgpu';
+
+/**
+ * Every character this glyph set can draw, for error messages and for the templates' AGENTS.md.
+ * @situation discover which characters a native React HUD can draw
+ * @example supportedGlyphs().includes("A")
+ */
+declare function supportedGlyphs(): string;
+
+/**
+ * The layout model behind the native React overlay: pure TypeScript, no WASM, no Yoga, no CSS
+ * parser. `TN_NATIVE_WASM_ON_MOBILE` refuses WebAssembly in mobile bundles, which rules out Yoga;
+ * writing a CSS engine here would be writing a browser, one ticket at a time.
+ *
+ * That last clause used to read "which is the thing this whole path exists to avoid", and PRD-217
+ * corrected it: the thing to avoid is *shipping* a browser, and every platform already provides
+ * one at the composition layer for free. So `ui.renderer: "web"` is now the default — the same
+ * React DOM, Tailwind, CSS and SVG on every target — and this renderer is the opt-in for a UI that
+ * is part of the rendered frame, a target with no web view, or zero extra processes. Growing this
+ * vocabulary toward CSS is still the wrong move; a game that needs CSS should ask for the web
+ * renderer instead.
+ *
+ * **The supported subset is exactly the fields on {@link IOverlayStyle} and nothing else.** A style
+ * key that is not on that interface is not "ignored for now" — {@link assertKnownStyle} throws
+ * `TN_REACT_UNKNOWN_STYLE` naming the key, because a convention discovered by failure is worse than
+ * one that does not exist.
+ *
+ * Units are screen pixels throughout, matching `CanvasLayer`'s orthographic camera. The origin is
+ * the top-left of the parent's content box, y increasing downwards, like a screen and unlike Three.
+ */
+/** `#rrggbb`, `#rgb`, or a packed `0xrrggbb` number. Alpha is `opacity`, kept separate on purpose. */
+type OverlayColor = string | number;
+interface IOverlayStyle {
+    /** Distance from the parent's left content edge. Ignored when the parent lays out in flow. */
+    left?: number;
+    /** Distance from the parent's right content edge. Applied only when `left` is absent. */
+    right?: number;
+    /** Distance from the parent's top content edge. Ignored when the parent lays out in flow. */
+    top?: number;
+    /** Distance from the parent's bottom content edge. Applied only when `top` is absent. */
+    bottom?: number;
+    /** Centre horizontally in the parent's content box. Wins over `left`/`right`. */
+    centerX?: boolean;
+    /** Centre vertically in the parent's content box. Wins over `top`/`bottom`. */
+    centerY?: boolean;
+    /** Fixed width. Without one, a box shrink-wraps its children and text measures its glyphs. */
+    width?: number;
+    /** Fixed height. Without one, a box shrink-wraps its children and text is one line tall. */
+    height?: number;
+    /** Uniform inset between this box's edges and its content box. */
+    padding?: number;
+    /** Lay children out in flow along this axis. Absent means children are placed absolutely. */
+    direction?: "row" | "column";
+    /** Space between flow children, in pixels. Only meaningful with `direction`. */
+    gap?: number;
+    /** Cross-axis placement of flow children. */
+    align?: "start" | "center" | "end";
+    /** Fill colour. Absent means the box draws nothing and only positions its children. */
+    background?: OverlayColor;
+    /** Glyph colour on a `text` element. */
+    color?: OverlayColor;
+    /** 0-1, multiplied into whatever this element draws. Children carry their own. */
+    opacity?: number;
+    /** Cell height of one glyph in pixels; the 5x7 grid scales to it. Inherited by descendants. */
+    fontSize?: number;
+    /** Extra pixels between glyph cells, on top of the 5x7 grid's one-column gap. */
+    letterSpacing?: number;
+    /** Horizontal placement of the glyph run inside a `text` box that has a `width`. */
+    textAlign?: "left" | "center" | "right";
+    /** Paint order among siblings. Higher paints later. Ties fall back to tree order. */
+    zIndex?: number;
+}
+/**
+ * Every style key the overlay implements, for the templates' AGENTS.md and for error messages.
+ * @situation discover which React HUD style properties work on native
+ * @example supportedStyleKeys().includes("centerX")
+ */
+declare function supportedStyleKeys(): readonly string[];
+/** A resolved rectangle in screen pixels, origin top-left of the framebuffer. */
+interface IOverlayBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Width in pixels of a glyph run at a given cell height.
+ * @situation measure native React HUD text before laying it out
+ * @example const scoreWidth = measureText("SCORE 10", 24)
+ */
+declare function measureText(text: string, fontSize: number, letterSpacing?: number): number;
+
+/**
+ * A React renderer that commits to `CanvasLayer` instead of the DOM.
+ *
+ * `react` is the component model and has no DOM in it; `react-dom` is one renderer among several,
+ * and `react-reconciler` is the supported way to write another. The native host has no DOM to
+ * render into and no rasteriser to paint one with, so this maps React elements straight onto
+ * Three.js objects inside the orthographic, screen-pixel `CanvasLayer` that `renderOverlay` already
+ * draws on every platform. Nothing here imports `react-dom`, which is what keeps
+ * `TN_NATIVE_WEB_ONLY_UI` satisfied on a native bundle.
+ *
+ * There are exactly two element types, and that is the whole vocabulary:
+ *
+ * - `<view>` — a rectangle. Draws when it has a `background`; otherwise it only positions children.
+ * - `<text>` — a run of bitmap glyphs. Its children must be strings or numbers.
+ *
+ * Anything else throws `TN_REACT_UNKNOWN_ELEMENT` naming the tag. Tailwind class names cannot cross
+ * — they are CSS — so styling is the `style` prop, whose supported keys are named exhaustively on
+ * `IOverlayStyle` and enforced by `assertKnownStyle`.
+ */
+/** The two host element types, as strings React sees. Namespaced so no DOM or SVG tag can collide. */
+declare const VIEW_ELEMENT = "tn-view";
+/** @see VIEW_ELEMENT */
+declare const TEXT_ELEMENT = "tn-text";
+interface IReactOverlayOptions {
+    /** Where the tree is drawn. `ctx.canvasLayer` in a game. */
+    canvasLayer: Pick<CanvasLayer, "scene" | "camera" | "onResize">;
+    /**
+     * Called with any error React could not recover from, before the overlay draws its own named
+     * failure banner. The default logs it; nothing swallows it, because a blank HUD and a broken HUD
+     * must never look the same.
+     */
+    onError?: (error: Error) => void;
+}
+interface IReactOverlay {
+    /** Mount or update the tree. Synchronous, so a caller can assert on the result immediately. */
+    render(element: ReactNode): void;
+    /** Re-run layout — call after a resize. Cheap and idempotent; it no-ops when nothing moved. */
+    refresh(): void;
+    /** Unmount the tree and release every Three.js object it created. */
+    dispose(): void;
+    /** How many Three.js objects the last commit produced. For budgets and tests. */
+    readonly objectCount: number;
+    /** Number of hook/store updates that changed host nodes during `refresh()`. */
+    readonly commitCount: number;
+    /** Flush plus draw cost of the latest state-changing `refresh()`, in milliseconds. */
+    readonly lastCommitMs: number | undefined;
+}
+/**
+ * Mount React into a `CanvasLayer`.
+ *
+ * @situation show a React HUD on Android, iOS or desktop native
+ * @situation render the same React component on web and on a phone without a WebView
+ * @constraint import `react`, never `react-dom`, from a native entry
+ * @example const overlay = createReactOverlay({ canvasLayer: ctx.canvasLayer });
+ */
+declare function createReactOverlay(options: IReactOverlayOptions): IReactOverlay;
+
+interface IViewProps {
+    style?: IOverlayStyle;
+    children?: ReactNode;
+}
+interface ITextProps {
+    style?: IOverlayStyle;
+    /** Strings and numbers only. Nesting an element inside `Text` has nothing to draw it with. */
+    children?: ReactNode;
+}
+/**
+ * A rectangle. Paints when its style has a `background`; otherwise it only positions children.
+ * @situation group and position native React HUD elements
+ * @example <View style={{ centerX: 0, top: 24 }}><Text>READY</Text></View>
+ */
+declare function View(props: IViewProps): ReactNode;
+/**
+ * A run of bitmap glyphs, drawn as one instanced quad per lit pixel.
+ * @situation show text in a native React HUD without a DOM
+ * @example <Text style={{ color: "#ffffff", fontSize: 24 }}>SCORE 10</Text>
+ */
+declare function Text(props: ITextProps): ReactNode;
+
+export { type IOverlayBox, type IOverlayStyle, type IReactOverlay, type IReactOverlayOptions, type ITextProps, type IViewProps, type OverlayColor, TEXT_ELEMENT, Text, VIEW_ELEMENT, View, createReactOverlay, measureText, supportedGlyphs, supportedStyleKeys };