@threenative/core 0.3.4 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +57 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2408 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +574 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +850 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
package/src/react-css.ts
ADDED
|
@@ -0,0 +1,604 @@
|
|
|
1
|
+
import type { ReactNode } from "react";
|
|
2
|
+
import ReactReconciler from "react-reconciler";
|
|
3
|
+
import { DiscreteEventPriority, NoEventPriority } from "react-reconciler/constants.js";
|
|
4
|
+
import { type IUiMessage, connectUiBridge } from "./ui-bridge.js";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* A React host that renders standard JSX to a native CSS engine, with no DOM in the process.
|
|
8
|
+
*
|
|
9
|
+
* The vocabulary is the HTML a game already writes: `div`, `section`, `button`, `className`,
|
|
10
|
+
* `style`, `data-*`, `aria-*`. That is the whole point — the same component can mount through
|
|
11
|
+
* `react-dom` on the web and through here on a phone, so a game does not keep two UI trees.
|
|
12
|
+
*
|
|
13
|
+
* What crosses the UI bridge is not a tree but a stream of mutations, one frame per React commit,
|
|
14
|
+
* exactly what `packages/runtime-native/native/css-ui` replays. This half owns no layout, no style
|
|
15
|
+
* resolution and no Tailwind knowledge: a `class` attribute crosses byte-for-byte and the CSS engine
|
|
16
|
+
* decides what it means, which is the only arrangement in which `hover:bg-brand/80` behaves the
|
|
17
|
+
* same on a phone as in a browser. Nothing here imports `react-dom` or touches `document`.
|
|
18
|
+
*
|
|
19
|
+
* Fail closed: a tag the CSS engine cannot build throws naming it and the allowed list rather than
|
|
20
|
+
* mounting a subtree with a hole in it. Props outside the supported list — the tag list above, the
|
|
21
|
+
* pass-through and renamed attribute sets, the `on*` map and the supported style properties — are
|
|
22
|
+
* ignored rather than throwing, so a component shared with `react-dom` still mounts here.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
/** The one frame type this host sends. The native CSS engine keys on it. */
|
|
26
|
+
export const CSS_UI_MESSAGE = "tn:css";
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Every host tag the native CSS engine can build. Closed on purpose: an unknown tag is a missing
|
|
30
|
+
* element, not a different-looking one, and a UI that quietly drops half its tree is the failure
|
|
31
|
+
* this refuses to have.
|
|
32
|
+
*/
|
|
33
|
+
export const CSS_UI_TAGS = [
|
|
34
|
+
"div",
|
|
35
|
+
"section",
|
|
36
|
+
"aside",
|
|
37
|
+
"header",
|
|
38
|
+
"footer",
|
|
39
|
+
"main",
|
|
40
|
+
"nav",
|
|
41
|
+
"article",
|
|
42
|
+
"h1",
|
|
43
|
+
"h2",
|
|
44
|
+
"h3",
|
|
45
|
+
"h4",
|
|
46
|
+
"h5",
|
|
47
|
+
"h6",
|
|
48
|
+
"p",
|
|
49
|
+
"span",
|
|
50
|
+
"button",
|
|
51
|
+
"img",
|
|
52
|
+
"ul",
|
|
53
|
+
"ol",
|
|
54
|
+
"li",
|
|
55
|
+
"a",
|
|
56
|
+
"label",
|
|
57
|
+
"strong",
|
|
58
|
+
"em",
|
|
59
|
+
"b",
|
|
60
|
+
"i",
|
|
61
|
+
"small",
|
|
62
|
+
] as const;
|
|
63
|
+
|
|
64
|
+
/** One mutation for the CSS engine. The op set is closed and every one of these is legal to send. */
|
|
65
|
+
type CssOp =
|
|
66
|
+
| { op: "create"; id: number; tag: string }
|
|
67
|
+
| { op: "text"; id: number; text: string }
|
|
68
|
+
| { op: "setText"; id: number; text: string }
|
|
69
|
+
| { op: "append"; parent: number; child: number }
|
|
70
|
+
| { op: "insertBefore"; parent: number; child: number; before: number }
|
|
71
|
+
| { op: "remove"; id: number }
|
|
72
|
+
| { op: "attr"; id: number; name: string; value: string | null }
|
|
73
|
+
| { op: "listen"; id: number; event: string };
|
|
74
|
+
|
|
75
|
+
/** The body root the engine hangs the tree from. Its id is 0, which is why real ids start at 1. */
|
|
76
|
+
const ROOT_ID = 0;
|
|
77
|
+
|
|
78
|
+
/** The event an `on*` prop asks for, and so the event name that comes back over the bridge. */
|
|
79
|
+
const EVENT_PROPS: Readonly<Record<string, string>> = {
|
|
80
|
+
onClick: "click",
|
|
81
|
+
onPointerDown: "pointerdown",
|
|
82
|
+
onPointerUp: "pointerup",
|
|
83
|
+
onPointerEnter: "pointerenter",
|
|
84
|
+
onPointerLeave: "pointerleave",
|
|
85
|
+
onFocus: "focus",
|
|
86
|
+
onBlur: "blur",
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
const EVENT_NAMES: ReadonlySet<string> = new Set(Object.values(EVENT_PROPS));
|
|
90
|
+
|
|
91
|
+
/** Props whose attribute keeps the React name, and so crosses as typed. */
|
|
92
|
+
const PASSTHROUGH_ATTRS: ReadonlySet<string> = new Set([
|
|
93
|
+
"id",
|
|
94
|
+
"role",
|
|
95
|
+
"type",
|
|
96
|
+
"src",
|
|
97
|
+
"alt",
|
|
98
|
+
"title",
|
|
99
|
+
]);
|
|
100
|
+
|
|
101
|
+
/** The React props whose names are spelled differently as attributes. */
|
|
102
|
+
const RENAMED_ATTRS: Readonly<Record<string, string>> = {
|
|
103
|
+
className: "class",
|
|
104
|
+
tabIndex: "tabindex",
|
|
105
|
+
};
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* The CSS properties React does not append `px` to. Spelled out rather than derived: a wrong entry
|
|
109
|
+
* here is a layout that only looks right at the default font size.
|
|
110
|
+
*/
|
|
111
|
+
const UNITLESS_PROPERTIES: ReadonlySet<string> = new Set([
|
|
112
|
+
"lineHeight",
|
|
113
|
+
"opacity",
|
|
114
|
+
"flex",
|
|
115
|
+
"flexGrow",
|
|
116
|
+
"flexShrink",
|
|
117
|
+
"zIndex",
|
|
118
|
+
"order",
|
|
119
|
+
"fontWeight",
|
|
120
|
+
"zoom",
|
|
121
|
+
"aspectRatio",
|
|
122
|
+
"gridColumn",
|
|
123
|
+
"gridRow",
|
|
124
|
+
"gridRowStart",
|
|
125
|
+
"gridRowEnd",
|
|
126
|
+
"gridColumnStart",
|
|
127
|
+
"gridColumnEnd",
|
|
128
|
+
"lineClamp",
|
|
129
|
+
"WebkitLineClamp",
|
|
130
|
+
"columns",
|
|
131
|
+
"tabSize",
|
|
132
|
+
]);
|
|
133
|
+
|
|
134
|
+
/** A handler as this host stores it: React's signature, reached through our own event object. */
|
|
135
|
+
type CssHandler = (event: ICssSyntheticEvent) => void;
|
|
136
|
+
|
|
137
|
+
/** The only event shape a native control can honestly offer. There is no DOM here to be complete. */
|
|
138
|
+
interface ICssSyntheticEvent {
|
|
139
|
+
readonly type: string;
|
|
140
|
+
readonly target: { readonly id: number };
|
|
141
|
+
preventDefault(): void;
|
|
142
|
+
stopPropagation(): void;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
interface ICssElement {
|
|
146
|
+
readonly kind: "element";
|
|
147
|
+
readonly id: number;
|
|
148
|
+
readonly tag: string;
|
|
149
|
+
/** What the engine has been told, so an update emits the attributes that actually changed. */
|
|
150
|
+
readonly attrs: Map<string, string>;
|
|
151
|
+
readonly children: ICssNode[];
|
|
152
|
+
/** Live handlers by event name. Updated in place, so a new closure never crosses the bridge. */
|
|
153
|
+
readonly handlers: Map<string, CssHandler>;
|
|
154
|
+
/** Events a `listen` op was already sent for. One listener per node per event, forever. */
|
|
155
|
+
readonly listened: Set<string>;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
interface ICssText {
|
|
159
|
+
readonly kind: "text";
|
|
160
|
+
readonly id: number;
|
|
161
|
+
text: string;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
type ICssNode = ICssElement | ICssText;
|
|
165
|
+
|
|
166
|
+
interface ICssRoot {
|
|
167
|
+
/** The body root, which is also the reconciler's container: id 0, and a parent like any other. */
|
|
168
|
+
readonly root: ICssElement;
|
|
169
|
+
readonly byId: Map<number, ICssElement>;
|
|
170
|
+
readonly pending: CssOp[];
|
|
171
|
+
nextId: number;
|
|
172
|
+
opCount: number;
|
|
173
|
+
postCount: number;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/** Node ids are u32 from 1: 0 is the body root, which the engine already owns. */
|
|
177
|
+
function takeId(root: ICssRoot): number {
|
|
178
|
+
root.nextId += 1;
|
|
179
|
+
return root.nextId;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/** `WebkitLineClamp` is `-webkit-line-clamp`; a custom property is emitted exactly as written. */
|
|
183
|
+
function styleProperty(name: string): string {
|
|
184
|
+
// The leading capital of a vendor name is the leading dash of its CSS property, so
|
|
185
|
+
// hyphenating is the whole rule: `WebkitLineClamp` -> `-webkit-line-clamp`.
|
|
186
|
+
return name.startsWith("--")
|
|
187
|
+
? name
|
|
188
|
+
: name.replaceAll(/[A-Z]/gu, (upper) => `-${upper.toLowerCase()}`);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
function styleValue(name: string, value: string | number): string {
|
|
192
|
+
if (typeof value === "string") return value;
|
|
193
|
+
return name.startsWith("--") || UNITLESS_PROPERTIES.has(name) ? String(value) : `${value}px`;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** One `style` attribute. `undefined` means the object held nothing worth sending. */
|
|
197
|
+
function styleAttribute(style: unknown): string | undefined {
|
|
198
|
+
if (typeof style !== "object" || style === null) return undefined;
|
|
199
|
+
const declarations: string[] = [];
|
|
200
|
+
for (const [name, value] of Object.entries(style)) {
|
|
201
|
+
if (typeof value !== "string" && typeof value !== "number") continue;
|
|
202
|
+
declarations.push(`${styleProperty(name)}: ${styleValue(name, value)}`);
|
|
203
|
+
}
|
|
204
|
+
return declarations.length === 0 ? undefined : declarations.join("; ");
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** One prop as one attribute, or nothing for a prop that crosses as no attribute at all. */
|
|
208
|
+
function attrFor(name: string, value: unknown): readonly [string, string] | undefined {
|
|
209
|
+
if (value === null || value === undefined) return undefined;
|
|
210
|
+
if (name.startsWith("data-") || name.startsWith("aria-")) return [name, String(value)];
|
|
211
|
+
if (name === "disabled") return value ? [name, ""] : undefined;
|
|
212
|
+
if (name === "style") {
|
|
213
|
+
const css = typeof value === "string" ? value : styleAttribute(value);
|
|
214
|
+
return css === undefined ? undefined : [name, css];
|
|
215
|
+
}
|
|
216
|
+
const named = PASSTHROUGH_ATTRS.has(name) ? name : RENAMED_ATTRS[name];
|
|
217
|
+
return named === undefined ? undefined : [named, String(value)];
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* What the props say the engine should hold, as attributes. An allowlist, not a sweep: `children`,
|
|
222
|
+
* an unknown `on*` prop and anything else React owns is absent here rather than crossing as noise.
|
|
223
|
+
*/
|
|
224
|
+
function desiredAttrs(props: Record<string, unknown>): Map<string, string> {
|
|
225
|
+
const attrs = new Map<string, string>();
|
|
226
|
+
for (const [name, value] of Object.entries(props)) {
|
|
227
|
+
const attr = attrFor(name, value);
|
|
228
|
+
if (attr !== undefined) attrs.set(attr[0], attr[1]);
|
|
229
|
+
}
|
|
230
|
+
return attrs;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** Attributes that differ from what the engine holds, plus a `null` for each one it should drop. */
|
|
234
|
+
function attrOps(element: ICssElement, props: Record<string, unknown>): CssOp[] {
|
|
235
|
+
const desired = desiredAttrs(props);
|
|
236
|
+
const ops: CssOp[] = [];
|
|
237
|
+
for (const [name, value] of desired) {
|
|
238
|
+
if (element.attrs.get(name) === value) continue;
|
|
239
|
+
element.attrs.set(name, value);
|
|
240
|
+
ops.push({ op: "attr", id: element.id, name, value });
|
|
241
|
+
}
|
|
242
|
+
for (const name of [...element.attrs.keys()]) {
|
|
243
|
+
if (desired.has(name)) continue;
|
|
244
|
+
element.attrs.delete(name);
|
|
245
|
+
ops.push({ op: "attr", id: element.id, name, value: null });
|
|
246
|
+
}
|
|
247
|
+
return ops;
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
function makeElement(id: number, tag: string, props: Record<string, unknown>): ICssElement {
|
|
251
|
+
if (!(CSS_UI_TAGS as readonly string[]).includes(tag)) {
|
|
252
|
+
throw new Error(
|
|
253
|
+
`TN_CSS_UI_ELEMENT_UNSUPPORTED: <${tag}> has no native CSS element, so mounting it would drop the subtree under it. Build it from: ${CSS_UI_TAGS.join(" ")}.`,
|
|
254
|
+
);
|
|
255
|
+
}
|
|
256
|
+
if (props.dangerouslySetInnerHTML !== undefined) {
|
|
257
|
+
throw new Error(
|
|
258
|
+
"TN_CSS_UI_PROP_UNSUPPORTED: dangerouslySetInnerHTML has no native CSS equivalent, because the engine is handed a tree and not a string. Render the markup as elements, or send it as a sheet.",
|
|
259
|
+
);
|
|
260
|
+
}
|
|
261
|
+
return {
|
|
262
|
+
attrs: new Map(),
|
|
263
|
+
children: [],
|
|
264
|
+
handlers: new Map(),
|
|
265
|
+
id,
|
|
266
|
+
kind: "element",
|
|
267
|
+
listened: new Set(),
|
|
268
|
+
tag,
|
|
269
|
+
};
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
/**
|
|
273
|
+
* One `listen` the first time a node asks for an event, and the handler swapped in place after
|
|
274
|
+
* that. A HUD re-rendering every frame must not re-arm every button on every frame.
|
|
275
|
+
*/
|
|
276
|
+
function handlerOps(element: ICssElement, props: Record<string, unknown>): CssOp[] {
|
|
277
|
+
const ops: CssOp[] = [];
|
|
278
|
+
for (const [prop, event] of Object.entries(EVENT_PROPS)) {
|
|
279
|
+
const handler = props[prop];
|
|
280
|
+
if (typeof handler !== "function") {
|
|
281
|
+
// The prop is gone, so the control must stop firing. The engine keeps the listener it has.
|
|
282
|
+
element.handlers.delete(event);
|
|
283
|
+
continue;
|
|
284
|
+
}
|
|
285
|
+
if (!element.listened.has(event)) {
|
|
286
|
+
element.listened.add(event);
|
|
287
|
+
ops.push({ op: "listen", id: element.id, event });
|
|
288
|
+
}
|
|
289
|
+
element.handlers.set(event, handler as CssHandler);
|
|
290
|
+
}
|
|
291
|
+
return ops;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** Drop a removed subtree's handler entries with it, so a stale frame cannot reach a dead node. */
|
|
295
|
+
function free(root: ICssRoot, node: ICssNode): void {
|
|
296
|
+
root.byId.delete(node.id);
|
|
297
|
+
if (node.kind !== "element") return;
|
|
298
|
+
node.handlers.clear();
|
|
299
|
+
for (const child of node.children) free(root, child);
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
/** Ops that wire nodes together, which must not precede the ops that make those nodes exist. */
|
|
303
|
+
function wires(op: CssOp): boolean {
|
|
304
|
+
return op.op === "append" || op.op === "insertBefore";
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* The batch in an order the engine can replay without a partial tree.
|
|
309
|
+
*
|
|
310
|
+
* React builds a mount bottom-up, so a naive queue interleaves `append` of a child with the
|
|
311
|
+
* `create` of the next sibling. Every node is made first and the wiring follows in commit order,
|
|
312
|
+
* which leaves the root's own append last.
|
|
313
|
+
*/
|
|
314
|
+
function orderedOps(ops: readonly CssOp[]): CssOp[] {
|
|
315
|
+
const made = ops.filter((op) => !wires(op));
|
|
316
|
+
return made.length === ops.length ? [...ops] : [...made, ...ops.filter(wires)];
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/** The reconciler entry points this host calls; react-reconciler's own generics are 20 positional slots. */
|
|
320
|
+
interface IReconciler {
|
|
321
|
+
createContainer(...args: readonly unknown[]): unknown;
|
|
322
|
+
updateContainerSync(
|
|
323
|
+
element: unknown,
|
|
324
|
+
container: unknown,
|
|
325
|
+
parent: unknown,
|
|
326
|
+
callback: unknown,
|
|
327
|
+
): void;
|
|
328
|
+
flushSyncWork(): void;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
// quality-allow: react-reconciler's generics are 20 positional slots; narrowed once to IReconciler.
|
|
332
|
+
const createReconciler = ReactReconciler as unknown as (config: unknown) => IReconciler;
|
|
333
|
+
|
|
334
|
+
export interface ICssUiRootOptions {
|
|
335
|
+
/** The realm the bridge installs into. Defaults to `globalThis`; injected by tests and by hosts. */
|
|
336
|
+
readonly scope?: Record<string, unknown>;
|
|
337
|
+
/**
|
|
338
|
+
* Called with any error React could not recover from — an unsupported tag, an unresolvable prop.
|
|
339
|
+
* The default logs it; nothing swallows it, because a UI that silently lost half its tree and a
|
|
340
|
+
* UI that was never asked for both look like an empty screen.
|
|
341
|
+
*/
|
|
342
|
+
readonly onError?: (error: Error) => void;
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
export interface ICssUiRoot {
|
|
346
|
+
/** Mount or update the tree. Synchronous, so the caller can assert on the frame immediately. */
|
|
347
|
+
render(element: ReactNode): void;
|
|
348
|
+
/** Unmount the tree, publish the removal, and stop listening to the bridge. */
|
|
349
|
+
dispose(): void;
|
|
350
|
+
/** How many mutation ops this root has sent. For budgets and tests. */
|
|
351
|
+
readonly opCount: number;
|
|
352
|
+
/** How many frames this root has posted. A commit that changed nothing posts nothing. */
|
|
353
|
+
readonly postCount: number;
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
/**
|
|
357
|
+
* The host config, per root rather than per module: `createInstance` is called with no parent, so
|
|
358
|
+
* the counter, the op queue and the handler table have to be reachable from the config itself, and
|
|
359
|
+
* a module-level one would hand the second root the first root's state.
|
|
360
|
+
*/
|
|
361
|
+
function hostConfig(root: ICssRoot, flush: () => void): unknown {
|
|
362
|
+
let priority: number = NoEventPriority;
|
|
363
|
+
/** Every structural op also keeps the JS child list, which is how a removal finds its subtree. */
|
|
364
|
+
const append = (parent: ICssElement, child: ICssNode): void => {
|
|
365
|
+
const existing = parent.children.indexOf(child);
|
|
366
|
+
if (existing >= 0) parent.children.splice(existing, 1);
|
|
367
|
+
parent.children.push(child);
|
|
368
|
+
root.pending.push({ op: "append", parent: parent.id, child: child.id });
|
|
369
|
+
};
|
|
370
|
+
const insert = (parent: ICssElement, child: ICssNode, before: ICssNode): void => {
|
|
371
|
+
const existing = parent.children.indexOf(child);
|
|
372
|
+
if (existing >= 0) parent.children.splice(existing, 1);
|
|
373
|
+
parent.children.splice(parent.children.indexOf(before), 0, child);
|
|
374
|
+
root.pending.push({
|
|
375
|
+
op: "insertBefore",
|
|
376
|
+
parent: parent.id,
|
|
377
|
+
child: child.id,
|
|
378
|
+
before: before.id,
|
|
379
|
+
});
|
|
380
|
+
};
|
|
381
|
+
const remove = (parent: ICssElement, child: ICssNode): void => {
|
|
382
|
+
const at = parent.children.indexOf(child);
|
|
383
|
+
if (at >= 0) parent.children.splice(at, 1);
|
|
384
|
+
free(root, child);
|
|
385
|
+
root.pending.push({ op: "remove", id: child.id });
|
|
386
|
+
};
|
|
387
|
+
return {
|
|
388
|
+
supportsMutation: true,
|
|
389
|
+
supportsPersistence: false,
|
|
390
|
+
supportsHydration: false,
|
|
391
|
+
isPrimaryRenderer: false,
|
|
392
|
+
noTimeout: -1 as const,
|
|
393
|
+
scheduleTimeout: setTimeout,
|
|
394
|
+
cancelTimeout: clearTimeout,
|
|
395
|
+
|
|
396
|
+
createInstance: (tag: string, props: Record<string, unknown>) => {
|
|
397
|
+
const element = makeElement(takeId(root), tag, props);
|
|
398
|
+
root.byId.set(element.id, element);
|
|
399
|
+
root.pending.push({ op: "create", id: element.id, tag });
|
|
400
|
+
for (const op of attrOps(element, props)) root.pending.push(op);
|
|
401
|
+
for (const op of handlerOps(element, props)) root.pending.push(op);
|
|
402
|
+
return element;
|
|
403
|
+
},
|
|
404
|
+
createTextInstance: (text: string): ICssText => {
|
|
405
|
+
const node: ICssText = { id: takeId(root), kind: "text", text };
|
|
406
|
+
root.pending.push({ op: "text", id: node.id, text });
|
|
407
|
+
return node;
|
|
408
|
+
},
|
|
409
|
+
shouldSetTextContent: () => false,
|
|
410
|
+
getPublicInstance: (instance: ICssNode) => instance,
|
|
411
|
+
getRootHostContext: () => HOST_CONTEXT,
|
|
412
|
+
getChildHostContext: () => HOST_CONTEXT,
|
|
413
|
+
|
|
414
|
+
// `appendInitialChild` is the same wire op as `appendChild`: React assembles a detached subtree
|
|
415
|
+
// in the render phase, and the engine has to be handed that same subtree before the root's own
|
|
416
|
+
// append, which is the last op of the batch.
|
|
417
|
+
appendInitialChild: (parent: ICssElement, child: ICssNode) => append(parent, child),
|
|
418
|
+
appendChild: (parent: ICssElement, child: ICssNode) => append(parent, child),
|
|
419
|
+
appendChildToContainer: (target: ICssElement, child: ICssNode) => append(target, child),
|
|
420
|
+
insertBefore: (parent: ICssElement, child: ICssNode, before: ICssNode) =>
|
|
421
|
+
insert(parent, child, before),
|
|
422
|
+
insertInContainerBefore: (target: ICssElement, child: ICssNode, before: ICssNode) =>
|
|
423
|
+
insert(target, child, before),
|
|
424
|
+
removeChild: (parent: ICssElement, child: ICssNode) => remove(parent, child),
|
|
425
|
+
removeChildFromContainer: (target: ICssElement, child: ICssNode) => remove(target, child),
|
|
426
|
+
clearContainer: (target: ICssElement) => {
|
|
427
|
+
for (const child of [...target.children]) remove(target, child);
|
|
428
|
+
},
|
|
429
|
+
finalizeInitialChildren: () => false,
|
|
430
|
+
commitUpdate: (
|
|
431
|
+
instance: ICssElement,
|
|
432
|
+
_tag: string,
|
|
433
|
+
_prev: unknown,
|
|
434
|
+
next: Record<string, unknown>,
|
|
435
|
+
) => {
|
|
436
|
+
for (const op of attrOps(instance, next)) root.pending.push(op);
|
|
437
|
+
for (const op of handlerOps(instance, next)) root.pending.push(op);
|
|
438
|
+
},
|
|
439
|
+
commitTextUpdate: (instance: ICssText, _old: string, next: string) => {
|
|
440
|
+
instance.text = next;
|
|
441
|
+
root.pending.push({ op: "setText", id: instance.id, text: next });
|
|
442
|
+
},
|
|
443
|
+
|
|
444
|
+
prepareForCommit: () => null,
|
|
445
|
+
resetAfterCommit: () => flush(),
|
|
446
|
+
preparePortalMount: () => undefined,
|
|
447
|
+
detachDeletedInstance: () => undefined,
|
|
448
|
+
beforeActiveInstanceBlur: () => undefined,
|
|
449
|
+
afterActiveInstanceBlur: () => undefined,
|
|
450
|
+
prepareScopeUpdate: () => undefined,
|
|
451
|
+
getInstanceFromNode: () => null,
|
|
452
|
+
getInstanceFromScope: () => null,
|
|
453
|
+
|
|
454
|
+
setCurrentUpdatePriority: (value: number) => {
|
|
455
|
+
priority = value;
|
|
456
|
+
},
|
|
457
|
+
getCurrentUpdatePriority: () => priority,
|
|
458
|
+
// Discrete, as in the quad backend: an update lands on the sync lane, so a game loop's
|
|
459
|
+
// `flushSyncWork()` is all that is ever needed and the UI never waits on a scheduler.
|
|
460
|
+
resolveUpdatePriority: () => (priority !== NoEventPriority ? priority : DiscreteEventPriority),
|
|
461
|
+
getCurrentEventPriority: () => DiscreteEventPriority,
|
|
462
|
+
|
|
463
|
+
shouldAttemptEagerTransition: () => false,
|
|
464
|
+
requestPostPaintCallback: () => undefined,
|
|
465
|
+
maySuspendCommit: () => false,
|
|
466
|
+
preloadInstance: () => true,
|
|
467
|
+
startSuspendingCommit: () => undefined,
|
|
468
|
+
suspendInstance: () => undefined,
|
|
469
|
+
waitForCommitToBeReady: () => null,
|
|
470
|
+
resetFormInstance: () => undefined,
|
|
471
|
+
trackSchedulerEvent: () => undefined,
|
|
472
|
+
resolveEventType: () => null,
|
|
473
|
+
resolveEventTimeStamp: () => -1.1,
|
|
474
|
+
// quality-allow: the key is react-reconciler's own host API spelling and cannot be renamed.
|
|
475
|
+
// biome-ignore lint/style/useNamingConvention: exact React reconciler host API name.
|
|
476
|
+
NotPendingTransition: null,
|
|
477
|
+
// quality-allow: the key is react-reconciler's own host API spelling and cannot be renamed.
|
|
478
|
+
// biome-ignore lint/style/useNamingConvention: exact React reconciler host API name.
|
|
479
|
+
HostTransitionContext: {
|
|
480
|
+
$$typeof: Symbol.for("react.context"),
|
|
481
|
+
// quality-allow: the key is react-reconciler's own host API spelling and cannot be renamed.
|
|
482
|
+
// biome-ignore lint/style/useNamingConvention: exact React context API name.
|
|
483
|
+
Provider: null,
|
|
484
|
+
// quality-allow: the key is react-reconciler's own host API spelling and cannot be renamed.
|
|
485
|
+
// biome-ignore lint/style/useNamingConvention: exact React context API name.
|
|
486
|
+
Consumer: null,
|
|
487
|
+
_currentValue: null,
|
|
488
|
+
_currentValue2: null,
|
|
489
|
+
_threadCount: 0,
|
|
490
|
+
},
|
|
491
|
+
|
|
492
|
+
flush,
|
|
493
|
+
};
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
const HOST_CONTEXT = {};
|
|
497
|
+
|
|
498
|
+
/**
|
|
499
|
+
* Mount React into a native CSS engine.
|
|
500
|
+
*
|
|
501
|
+
* @situation mount a React HUD on the desktop host with no DOM in the runtime
|
|
502
|
+
* @situation write one React component and run it on the web and on the desktop host
|
|
503
|
+
* @constraint desktop only, and the game host must be built with the CSS backend (`TN_ENABLE_CSS_UI=1`); Android, iOS and web phones render a React HUD in a web overlay instead
|
|
504
|
+
* @constraint import `react`, never `react-dom`, from a native entry
|
|
505
|
+
* @constraint styling is CSS resolved by the native engine; JS only mirrors the element tree
|
|
506
|
+
* @example const root = createCssUiRoot();
|
|
507
|
+
* @example root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
|
|
508
|
+
*/
|
|
509
|
+
export function createCssUiRoot(options: ICssUiRootOptions = {}): ICssUiRoot {
|
|
510
|
+
const bridge = connectUiBridge({ end: "game", scope: options.scope });
|
|
511
|
+
const root: ICssRoot = {
|
|
512
|
+
byId: new Map(),
|
|
513
|
+
nextId: ROOT_ID,
|
|
514
|
+
opCount: 0,
|
|
515
|
+
pending: [],
|
|
516
|
+
postCount: 0,
|
|
517
|
+
root: {
|
|
518
|
+
attrs: new Map(),
|
|
519
|
+
children: [],
|
|
520
|
+
handlers: new Map(),
|
|
521
|
+
id: ROOT_ID,
|
|
522
|
+
kind: "element",
|
|
523
|
+
listened: new Set(),
|
|
524
|
+
tag: "body",
|
|
525
|
+
},
|
|
526
|
+
};
|
|
527
|
+
const report = (error: unknown): void => {
|
|
528
|
+
const named = error instanceof Error ? error : new Error(String(error));
|
|
529
|
+
if (options.onError !== undefined) options.onError(named);
|
|
530
|
+
else console.error(named.message);
|
|
531
|
+
};
|
|
532
|
+
const flush = (): void => {
|
|
533
|
+
const ops = orderedOps(root.pending);
|
|
534
|
+
if (ops.length === 0) return;
|
|
535
|
+
root.pending.length = 0;
|
|
536
|
+
root.opCount += ops.length;
|
|
537
|
+
root.postCount += 1;
|
|
538
|
+
bridge.post({ ops, type: CSS_UI_MESSAGE } satisfies IUiMessage);
|
|
539
|
+
};
|
|
540
|
+
const reconciler = createReconciler(hostConfig(root, flush));
|
|
541
|
+
const fiberRoot = reconciler.createContainer(
|
|
542
|
+
root.root,
|
|
543
|
+
0,
|
|
544
|
+
null,
|
|
545
|
+
false,
|
|
546
|
+
null,
|
|
547
|
+
"tn",
|
|
548
|
+
report,
|
|
549
|
+
report,
|
|
550
|
+
report,
|
|
551
|
+
null,
|
|
552
|
+
);
|
|
553
|
+
|
|
554
|
+
let eventDispatch: string | undefined;
|
|
555
|
+
let propagationStopped = false;
|
|
556
|
+
const unsubscribe = bridge.onMessage((message: IUiMessage) => {
|
|
557
|
+
const { type } = message;
|
|
558
|
+
if (!EVENT_NAMES.has(type)) return;
|
|
559
|
+
const id = message.id;
|
|
560
|
+
if (typeof id !== "number") return;
|
|
561
|
+
const dispatch = typeof message.dispatch === "string" ? message.dispatch : undefined;
|
|
562
|
+
if (dispatch === undefined || dispatch !== eventDispatch) {
|
|
563
|
+
eventDispatch = dispatch;
|
|
564
|
+
propagationStopped = false;
|
|
565
|
+
}
|
|
566
|
+
if (propagationStopped) return;
|
|
567
|
+
const handler = root.byId.get(id)?.handlers.get(type);
|
|
568
|
+
if (handler === undefined) return;
|
|
569
|
+
try {
|
|
570
|
+
handler({
|
|
571
|
+
preventDefault: () => undefined,
|
|
572
|
+
stopPropagation: () => {
|
|
573
|
+
if (dispatch !== undefined && dispatch === eventDispatch) propagationStopped = true;
|
|
574
|
+
},
|
|
575
|
+
target: { id },
|
|
576
|
+
type,
|
|
577
|
+
});
|
|
578
|
+
} catch (error) {
|
|
579
|
+
// A control that throws is a game's bug, and a bridge listener that throws with it takes
|
|
580
|
+
// every later event down too.
|
|
581
|
+
report(error);
|
|
582
|
+
}
|
|
583
|
+
});
|
|
584
|
+
|
|
585
|
+
return {
|
|
586
|
+
render(element: ReactNode) {
|
|
587
|
+
reconciler.updateContainerSync(element, fiberRoot, null, null);
|
|
588
|
+
reconciler.flushSyncWork();
|
|
589
|
+
},
|
|
590
|
+
dispose() {
|
|
591
|
+
reconciler.updateContainerSync(null, fiberRoot, null, null);
|
|
592
|
+
reconciler.flushSyncWork();
|
|
593
|
+
unsubscribe();
|
|
594
|
+
bridge.close();
|
|
595
|
+
root.byId.clear();
|
|
596
|
+
},
|
|
597
|
+
get opCount() {
|
|
598
|
+
return root.opCount;
|
|
599
|
+
},
|
|
600
|
+
get postCount() {
|
|
601
|
+
return root.postCount;
|
|
602
|
+
},
|
|
603
|
+
};
|
|
604
|
+
}
|