@threenative/core 0.2.0 → 0.3.1

package/dist/ui-layer.js

@@ -0,0 +1,425 @@
+// src/ui-bridge.ts
+var HIT_REGIONS_MESSAGE = "tn:hit-regions";
+var GAME_STATE_MESSAGE = "tn:state";
+var UI_INTENT_MESSAGE = "tn:intent";
+var UI_READY_INTENT = "tn:ready";
+var UI_BRIDGE_GLOBALS = {
+  /** UI end, inbound: the host calls this with one JSON string. */
+  uiReceive: "__tnUiReceive",
+  /** UI end, outbound: an injected object with `postMessage(string)`. */
+  uiHost: "tnHost",
+  /** Game end, inbound: the runtime calls this with one JSON string. */
+  gameReceive: "__tnUiGameReceive",
+  /** Game end, outbound: the runtime installs this and forwards to the web view. */
+  gamePost: "__tnUiPost"
+};
+function assertSendable(message) {
+  if (typeof message !== "object" || message === null || Array.isArray(message)) {
+    throw new Error("TN_UI_BRIDGE_MESSAGE_INVALID: a bridge message must be a JSON object.");
+  }
+  if (typeof message.type !== "string" || message.type.length === 0) {
+    throw new Error("TN_UI_BRIDGE_MESSAGE_INVALID: a bridge message must carry a string 'type'.");
+  }
+  let frame;
+  try {
+    frame = JSON.stringify(message);
+  } catch (error) {
+    throw new Error(
+      `TN_UI_BRIDGE_MESSAGE_INVALID: '${message.type}' is not JSON-serialisable: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (frame === void 0) {
+    throw new Error(`TN_UI_BRIDGE_MESSAGE_INVALID: '${message.type}' serialised to nothing.`);
+  }
+  return frame;
+}
+function parseFrame(frame) {
+  const text = typeof frame === "string" ? frame : frame?.data;
+  if (typeof text !== "string") {
+    throw new Error("TN_UI_BRIDGE_FRAME_INVALID: expected a JSON string from the host.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(
+      `TN_UI_BRIDGE_FRAME_INVALID: not JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("TN_UI_BRIDGE_FRAME_INVALID: a bridge frame must be a JSON object.");
+  }
+  if (typeof parsed.type !== "string") {
+    throw new Error("TN_UI_BRIDGE_FRAME_INVALID: a bridge frame must carry a string 'type'.");
+  }
+  return parsed;
+}
+function findOutbound(scope, end) {
+  if (end === "game") {
+    const post = scope[UI_BRIDGE_GLOBALS.gamePost];
+    return typeof post === "function" ? (frame) => post(frame) : void 0;
+  }
+  const injected = scope[UI_BRIDGE_GLOBALS.uiHost];
+  if (typeof injected?.postMessage === "function") {
+    return (frame) => injected.postMessage(frame);
+  }
+  const webkit = scope.webkit;
+  const handler = webkit?.messageHandlers?.[UI_BRIDGE_GLOBALS.uiHost];
+  if (typeof handler?.postMessage === "function") {
+    return (frame) => handler.postMessage(frame);
+  }
+  const ipc = scope.ipc;
+  if (typeof ipc?.postMessage === "function") {
+    return (frame) => ipc.postMessage(frame);
+  }
+  return void 0;
+}
+var BROKER_KEY = "__tnUiBridgeBroker";
+function broker(scope) {
+  const existing = scope[BROKER_KEY];
+  if (existing !== void 0) return existing;
+  const created = { game: /* @__PURE__ */ new Set(), ui: /* @__PURE__ */ new Set() };
+  scope[BROKER_KEY] = created;
+  return created;
+}
+function connectUiBridge(options) {
+  const { end } = options;
+  if (end !== "game" && end !== "ui") {
+    throw new Error(`TN_UI_BRIDGE_END_INVALID: expected 'game' or 'ui', got '${String(end)}'.`);
+  }
+  const scope = options.scope ?? globalThis;
+  const listeners = /* @__PURE__ */ new Set();
+  const deliver = (frame) => {
+    const message = parseFrame(frame);
+    for (const listener of [...listeners]) listener(message);
+  };
+  const outbound = findOutbound(scope, end);
+  const inboundKey = end === "ui" ? UI_BRIDGE_GLOBALS.uiReceive : UI_BRIDGE_GLOBALS.gameReceive;
+  let closed = false;
+  if (outbound === void 0) {
+    const bus = broker(scope);
+    const peer = end === "ui" ? "game" : "ui";
+    const own = (message) => {
+      for (const listener of [...listeners]) listener(message);
+    };
+    bus[end].add(own);
+    return {
+      end,
+      transport: "in-process",
+      hasPeer: () => bus[peer].size > 0,
+      post(message) {
+        const frame = assertSendable(message);
+        if (closed) throw new Error("TN_UI_BRIDGE_CLOSED: post on a closed bridge.");
+        const copy = JSON.parse(frame);
+        for (const listener of [...bus[peer]]) listener(copy);
+      },
+      onMessage(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      close() {
+        closed = true;
+        listeners.clear();
+        bus[end].delete(own);
+      }
+    };
+  }
+  scope[inboundKey] = deliver;
+  const injected = scope[UI_BRIDGE_GLOBALS.uiHost];
+  if (end === "ui" && injected !== void 0 && typeof injected === "object") {
+    injected.onmessage = (event) => deliver(event);
+  }
+  return {
+    end,
+    transport: "host",
+    hasPeer() {
+      const attached = scope.__tnUiOverlayAttached;
+      if (end === "ui") return true;
+      return typeof attached === "function" ? attached() === true : false;
+    },
+    post(message) {
+      const frame = assertSendable(message);
+      if (closed) throw new Error("TN_UI_BRIDGE_CLOSED: post on a closed bridge.");
+      outbound(frame);
+    },
+    onMessage(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    close() {
+      closed = true;
+      listeners.clear();
+      if (scope[inboundKey] === deliver) scope[inboundKey] = void 0;
+      if (end === "ui" && injected !== void 0 && typeof injected === "object") {
+        injected.onmessage = void 0;
+      }
+    }
+  };
+}
+
+// src/ui-state.ts
+var microtask = (flush) => {
+  void Promise.resolve().then(flush);
+};
+function publishUiState(bridge, store, options = {}) {
+  if (bridge.end !== "game") {
+    throw new Error(
+      `TN_UI_STATE_WRONG_END: state is published by the 'game' end, not '${bridge.end}'.`
+    );
+  }
+  const schedule = options.schedule ?? microtask;
+  const read = () => store.getPublishedState === void 0 ? store.getState() : store.getPublishedState();
+  let stopped = false;
+  let queued = false;
+  let lastFrame = "";
+  const publish = () => {
+    if (stopped) return;
+    const state = read();
+    lastFrame = JSON.stringify(state);
+    bridge.post({ type: GAME_STATE_MESSAGE, state });
+  };
+  const flush = () => {
+    queued = false;
+    if (stopped) return;
+    if (!bridge.hasPeer()) return;
+    if (JSON.stringify(read()) === lastFrame) return;
+    publish();
+  };
+  const unsubscribe = store.subscribe(() => {
+    if (stopped || queued) return;
+    queued = true;
+    schedule(flush);
+  });
+  if (bridge.hasPeer()) publish();
+  return {
+    publish,
+    stop() {
+      stopped = true;
+      unsubscribe();
+    }
+  };
+}
+function subscribeUiState(bridge) {
+  if (bridge.end !== "ui") {
+    throw new Error(
+      `TN_UI_STATE_WRONG_END: state is mirrored by the 'ui' end, not '${bridge.end}'.`
+    );
+  }
+  const listeners = /* @__PURE__ */ new Set();
+  let current;
+  const off = bridge.onMessage((message) => {
+    if (message.type !== GAME_STATE_MESSAGE) return;
+    const state = message.state;
+    if (typeof state !== "object" || state === null || Array.isArray(state)) {
+      throw new Error("TN_UI_STATE_FRAME_INVALID: a published state frame must carry an object.");
+    }
+    current = state;
+    for (const listener of [...listeners]) listener();
+  });
+  return {
+    get: () => current,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    stop() {
+      off();
+      listeners.clear();
+    }
+  };
+}
+function sendUiIntent(bridge, intent, payload) {
+  if (bridge.end !== "ui") {
+    throw new Error(
+      `TN_UI_INTENT_WRONG_END: intents are sent by the 'ui' end, not '${bridge.end}'.`
+    );
+  }
+  if (typeof intent !== "string" || intent.length === 0) {
+    throw new Error("TN_UI_INTENT_INVALID: an intent needs a non-empty name.");
+  }
+  bridge.post({
+    type: UI_INTENT_MESSAGE,
+    intent,
+    ...payload === void 0 ? {} : { payload }
+  });
+}
+function onUiIntent(bridge, listener) {
+  if (bridge.end !== "game") {
+    throw new Error(
+      `TN_UI_INTENT_WRONG_END: intents are received by the 'game' end, not '${bridge.end}'.`
+    );
+  }
+  return bridge.onMessage((message) => {
+    if (message.type !== UI_INTENT_MESSAGE) return;
+    if (typeof message.intent !== "string" || message.intent.length === 0) {
+      throw new Error("TN_UI_INTENT_INVALID: an intent frame must carry a non-empty name.");
+    }
+    listener(message.intent, message.payload);
+  });
+}
+
+// src/ui-hit-regions.ts
+var INTERACTIVE_ATTRIBUTE = "data-tn-interactive";
+function quantize(value) {
+  return Math.round(value * 1e5) / 1e5;
+}
+var TRANSITION_START = ["transitionrun", "transitionstart", "animationstart"];
+var TRANSITION_END = [
+  "transitionend",
+  "transitioncancel",
+  "animationend",
+  "animationcancel"
+];
+var LAYOUT_EVENTS = ["resize", "orientationchange", "scroll"];
+function publishHitRegions(options) {
+  const scope = options.scope ?? globalThis;
+  const document = scope.document;
+  if (document === void 0 || typeof document.querySelectorAll !== "function") {
+    throw new Error(
+      "TN_UI_HIT_REGIONS_NO_DOCUMENT: the interactive-rect registry runs in the UI page and found no document."
+    );
+  }
+  const selector = `[${options.attribute ?? INTERACTIVE_ATTRIBUTE}]`;
+  const bridge = options.bridge;
+  if (bridge.end !== "ui") {
+    throw new Error(
+      `TN_UI_HIT_REGIONS_WRONG_END: hit regions are published by the 'ui' end, not '${bridge.end}'.`
+    );
+  }
+  const unmarkedWarning = { warned: false };
+  let published = [];
+  let publishedFrame = "";
+  let stopped = false;
+  let liveTransitions = 0;
+  let frameHandle;
+  const viewport = () => ({
+    width: scope.innerWidth ?? document.documentElement?.clientWidth ?? 0,
+    height: scope.innerHeight ?? document.documentElement?.clientHeight ?? 0
+  });
+  const boxesOf = (element) => {
+    const list = element.getClientRects?.();
+    if (list === void 0 || list.length === 0) return [element.getBoundingClientRect()];
+    const boxes = [];
+    for (let index = 0; index < list.length; index += 1) {
+      const rect = list[index];
+      if (rect !== void 0) boxes.push(rect);
+    }
+    return boxes;
+  };
+  const normalize = (boxes, width, height) => boxes.filter((rect) => rect.width > 0 && rect.height > 0).map((rect) => ({
+    x: quantize(rect.left / width),
+    y: quantize(rect.top / height),
+    width: quantize(rect.width / width),
+    height: quantize(rect.height / height)
+  }));
+  const measure = () => {
+    const { width, height } = viewport();
+    if (width <= 0 || height <= 0) return [];
+    const regions = [];
+    const elements = document.querySelectorAll(selector);
+    for (let index = 0; index < elements.length; index += 1) {
+      const element = elements[index];
+      if (element !== void 0) regions.push(...normalize(boxesOf(element), width, height));
+    }
+    warnAboutUnmarkedControls(document, selector, scope, unmarkedWarning);
+    return regions;
+  };
+  const publish = (regions) => {
+    const frame = JSON.stringify(regions);
+    if (frame === publishedFrame) return;
+    publishedFrame = frame;
+    published = regions;
+    bridge.post({ type: HIT_REGIONS_MESSAGE, regions });
+  };
+  const refresh = () => {
+    if (stopped) return;
+    publish(measure());
+  };
+  const requestFrame = scope.requestAnimationFrame;
+  const cancelFrame = scope.cancelAnimationFrame;
+  const pump = () => {
+    frameHandle = void 0;
+    if (stopped || liveTransitions <= 0) return;
+    refresh();
+    if (requestFrame !== void 0) frameHandle = requestFrame(pump);
+  };
+  const onTransitionStart = () => {
+    liveTransitions += 1;
+    if (frameHandle === void 0 && requestFrame !== void 0) frameHandle = requestFrame(pump);
+  };
+  const onTransitionEnd = () => {
+    liveTransitions = Math.max(0, liveTransitions - 1);
+    refresh();
+  };
+  const listen = (on, host, types, listener) => {
+    const method = host[on];
+    if (typeof method !== "function") return;
+    for (const type of types) method.call(host, type, listener, true);
+  };
+  listen("addEventListener", document, TRANSITION_START, onTransitionStart);
+  listen("addEventListener", document, TRANSITION_END, onTransitionEnd);
+  listen("addEventListener", scope, LAYOUT_EVENTS, refresh);
+  const MutationObserverCtor = scope.MutationObserver;
+  const mutations = MutationObserverCtor === void 0 ? void 0 : new MutationObserverCtor(refresh);
+  mutations?.observe(document, {
+    attributes: true,
+    childList: true,
+    subtree: true,
+    characterData: true
+  });
+  const ResizeObserverCtor = scope.ResizeObserver;
+  const resizes = ResizeObserverCtor === void 0 ? void 0 : new ResizeObserverCtor(refresh);
+  if (resizes !== void 0 && document.documentElement !== void 0) {
+    resizes.observe(document.documentElement);
+  }
+  refresh();
+  return {
+    refresh,
+    regions: () => published,
+    stop() {
+      if (stopped) return;
+      stopped = true;
+      if (frameHandle !== void 0 && cancelFrame !== void 0) cancelFrame(frameHandle);
+      frameHandle = void 0;
+      listen("removeEventListener", document, TRANSITION_START, onTransitionStart);
+      listen("removeEventListener", document, TRANSITION_END, onTransitionEnd);
+      listen("removeEventListener", scope, LAYOUT_EVENTS, refresh);
+      mutations?.disconnect();
+      resizes?.disconnect();
+      published = [];
+      publishedFrame = "[]";
+      bridge.post({ type: HIT_REGIONS_MESSAGE, regions: [] });
+    }
+  };
+}
+var UNMARKED_CONTROL_SELECTOR = 'button, [role="button"], a[href], input, select, textarea';
+function warnAboutUnmarkedControls(document, selector, scope, once) {
+  if (once.warned || !isDevelopment()) return;
+  if (typeof document.querySelectorAll !== "function") return;
+  const candidates = document.querySelectorAll(UNMARKED_CONTROL_SELECTOR);
+  const unmarked = [];
+  for (let index = 0; index < candidates.length; index += 1) {
+    const element = candidates[index];
+    if (element === void 0) continue;
+    if (element.closest?.(selector) != null) continue;
+    unmarked.push(describe(element));
+  }
+  if (unmarked.length === 0) return;
+  once.warned = true;
+  const names = unmarked.slice(0, 5).join(", ");
+  const rest = unmarked.length > 5 ? ` and ${unmarked.length - 5} more` : "";
+  scope.console?.warn?.(
+    `TN_UI_UNMARKED_CONTROLS: ${unmarked.length} control(s) publish no hit region, so on native the press reaches the game instead: ${names}${rest}. Mark each with ${INTERACTIVE_ATTRIBUTE}, or wrap them in an element that carries it.`
+  );
+}
+function describe(element) {
+  const tag = (element.tagName ?? "element").toLowerCase();
+  const id = element.id === void 0 || element.id === "" ? "" : `#${element.id}`;
+  const first = (element.className ?? "").split(/\s+/u).filter(Boolean)[0];
+  return `<${tag}${id}${first === void 0 ? "" : `.${first}`}>`;
+}
+function isDevelopment() {
+  return import.meta.env?.DEV === true;
+}
+
+export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, INTERACTIVE_ATTRIBUTE, UI_BRIDGE_GLOBALS, UI_INTENT_MESSAGE, UI_READY_INTENT, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };

package/dist/world.d.ts

@@ -0,0 +1,254 @@
+import { Object3D, Mesh, LOD, Vector3, Group, BufferGeometry } from 'three';
+import { I as IComputeDriven, a as IGPUReadbackSample } from './gpu-readback-D2iRvoe9.js';
+import { I as IRendererLike } from './renderer-C6hqZpoG.js';
+import { I as IAssetLoader } from './assets-kyoF7JlJ.js';
+import 'three/webgpu';
+
+interface IWorldErosionOptions {
+    readonly depositionRate: number;
+    readonly erosionRate: number;
+    readonly evaporation: number;
+    readonly iterations: number;
+    readonly rainfall: number;
+    readonly sedimentCapacity: number;
+    readonly timeStep: number;
+}
+
+type MeshSurface = NonNullable<ConstructorParameters<typeof Mesh>[1]>;
+interface IWorldTileCollider {
+    dispose(): void;
+}
+interface IWorldTileColliderInput {
+    readonly field: Heightfield;
+    readonly key: string;
+    readonly object: Object3D;
+    readonly tileX: number;
+    readonly tileZ: number;
+}
+interface IWorldTile {
+    readonly bytes: number;
+    readonly collider: IWorldTileCollider;
+    readonly field: Heightfield;
+    readonly key: string;
+    readonly lod: LOD;
+    readonly lodLevel: number;
+    readonly object: Object3D;
+    readonly skirtVertexCount: number;
+    readonly tileX: number;
+    readonly tileZ: number;
+}
+interface IWorldTilesFollowPosition {
+    readonly x: number;
+    readonly z: number;
+}
+interface IWorldTilesTopologyObservation {
+    readonly columns: number;
+    readonly depth: number;
+    readonly origin: IHeightfieldOrigin;
+    readonly rows: number;
+    readonly width: number;
+}
+interface IWorldTilesOptions {
+    /** Releases a caller-supplied model key when its last tile reference is evicted. */
+    readonly assets?: Pick<IAssetLoader, "release">;
+    /** A game-owned, already-loaded logical model key, or a key resolver per tile. */
+    readonly assetKey?: string | ((tileX: number, tileZ: number) => string);
+    /** Creates the physics body from the field's explicit collider-order copy. */
+    readonly createCollider?: (input: IWorldTileColliderInput) => IWorldTileCollider;
+    /** TSL pass options are game supplied and are forwarded to each resident field. */
+    readonly worldPasses?: IHeightfieldWorldPassOptions;
+    /** Game-owned surface; this class never creates or mutates it. */
+    readonly surface: MeshSurface;
+    readonly residentByteBudget: number;
+    readonly residentTileBudget: number;
+    readonly sampleHeight: IHeightfieldSamplerOptions["sampleHeight"];
+    /** How deep each edge skirt extends below its surface. Defaults to one tile width. */
+    readonly skirtDepth?: number;
+    /** Square tile neighborhood to consider around the followed point. Defaults to 1. */
+    readonly streamRadius?: number;
+    readonly tileResolution: number;
+    readonly tileSize: number;
+    /** Vertex decimation factors. Defaults to 1, 2, and 4 over the same field. */
+    readonly lodFactors?: readonly number[];
+    /** Distances in world units at which the next LOD becomes active. */
+    readonly lodDistances?: readonly number[];
+    /** Explicit game-owned measurement region used by the topology evaluator. */
+    readonly topologyObservation?: IWorldTilesTopologyObservation;
+}
+/**
+ * Stream a bounded square of game-authored heightfields and keep their render and physics units
+ * together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling
+ * to the renderer's existing scene path.
+ *
+ * @situation stream terrain without cracks
+ * @situation keep generated terrain resident around a moving player
+ * @situation put a generated terrain tile into a game-owned physics world
+ * @alias stream terrain across chunks
+ * @constraint sampleHeight and surface are required game choices; no landform or surface preset is installed
+ * @constraint residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws
+ * @override tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, and budgets
+ * @example const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
+ */
+declare class TerrainTiles extends Object3D implements IComputeDriven {
+    #private;
+    readonly residentTileBudget: number;
+    readonly residentByteBudget: number;
+    readonly skirtDepth: number;
+    readonly tileResolution: number;
+    readonly tileSize: number;
+    readonly processCadence: "render";
+    constructor(options: IWorldTilesOptions);
+    get released(): boolean;
+    get residentTileCount(): number;
+    get residentBytes(): number;
+    get peakResidentTileCount(): number;
+    get peakResidentBytes(): number;
+    get residentKeys(): readonly string[];
+    get residentColliderKeys(): readonly string[];
+    get lodLevelCount(): number;
+    get lodTransitions(): number;
+    /** Maximum per-render-frame displacement of the visible LOD surface during transitions. */
+    get maxLodPop(): number;
+    /** Maximum number of rendered frames during which an LOD transition remained observable. */
+    get maxLodTransitionFrames(): number;
+    /** Maximum visible edge gap observed across follow/process calls for this residency owner. */
+    get maxSeamGap(): number;
+    /** Maximum remaining visible gap after skirt or bridge coverage observed across follow/process calls. */
+    get maxVisualSeamGap(): number;
+    /** Number of mixed-LOD edge reconciliations observed during this residency lifetime. */
+    get stitchedEdgeCount(): number;
+    get warmupNodes(): readonly unknown[];
+    getTile(key: string): IWorldTile | undefined;
+    follow(position: IWorldTilesFollowPosition | Pick<Vector3, "x" | "z">): void;
+    heightAt(x: number, z: number): number;
+    normalAt(x: number, z: number, target?: Vector3): Vector3;
+    sample(channel: string, x: number, z: number): number;
+    attachRenderer(renderer: IRendererLike): void;
+    process(renderer?: IRendererLike | undefined): void;
+    debug(): Record<string, unknown>;
+    detach(): void;
+    dispose(): void;
+}
+
+type WorldGenerationPath = "gpu" | "cpu-fallback" | "unsupported";
+interface IWorldComputeLimits {
+    readonly maxComputeInvocationsPerWorkgroup: number;
+    readonly maxComputeWorkgroupsPerDimension: number;
+    readonly maxStorageBufferBindingSize: number;
+}
+interface IWorldCapabilities {
+    readonly compute: boolean;
+    /** Whether the host exposed a GPU adapter, even when its limits cannot run the world pass. */
+    readonly gpu: boolean;
+    readonly generation: WorldGenerationPath;
+    readonly limits: IWorldComputeLimits;
+    readonly cpuFallbackIterations: number;
+    readonly reason?: string;
+}
+interface IWorldCapabilitiesOptions {
+    /** Explicitly supplied by a host that already probed its adapter. */
+    readonly gpuAvailable?: boolean;
+    readonly limits?: Partial<IWorldComputeLimits>;
+    readonly minimumWorkgroupsPerDimension?: number;
+    readonly minimumStorageBufferBindingSize?: number;
+    /** A positive value makes CPU generation an explicit, reduced fallback. */
+    readonly cpuFallbackIterations?: number;
+}
+/**
+ * Resolve the active world-generation path from host capability facts.
+ *
+ * The function accepts the adapter facts instead of reaching through a renderer-specific global,
+ * so browser and native hosts can report the same object. Missing limits are not treated as
+ * infinite: a host must either provide a valid GPU limit report or explicitly choose CPU fallback.
+ * GPU generation remains unavailable until a GPU readback can own the canonical field; a host
+ * adapter report therefore never upgrades a CPU fallback into a GPU generation claim.
+ *
+ * @situation decide whether generated terrain can use GPU compute
+ * @situation report why terrain generation is using a reduced CPU fallback
+ * @constraint unsupported is returned when compute limits are unknown or below the requirement; callers must not silently continue
+ * @override minimumWorkgroupsPerDimension, minimumStorageBufferBindingSize, and cpuFallbackIterations
+ * @example const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackIterations: 8 });
+ */
+declare function getWorldCapabilities(options?: IWorldCapabilitiesOptions): IWorldCapabilities;
+
+interface IHeightfieldOrigin {
+    readonly x: number;
+    readonly z: number;
+}
+interface IHeightfieldOptions {
+    readonly columns: number;
+    readonly depth: number;
+    readonly heights: Float32Array;
+    readonly origin: IHeightfieldOrigin;
+    readonly rows: number;
+    readonly width: number;
+    readonly worldPasses?: IHeightfieldWorldPassOptions;
+}
+interface IHeightfieldWorldPassOptions {
+    /** Maximum TSL compute dispatches submitted by one rendered frame. */
+    readonly dispatchBudget: number;
+    /** Reserved GPU path; true is rejected until GPU readback owns the canonical field. */
+    readonly gpu?: boolean;
+    /** Every physical coefficient is game supplied; core owns no terrain preset. */
+    readonly erosion: IWorldErosionOptions;
+}
+interface IHeightfieldSamplerOptions extends Omit<IHeightfieldOptions, "heights"> {
+    /** Game-owned terrain function. It is evaluated once and never retained. */
+    readonly sampleHeight: (x: number, z: number) => number;
+}
+interface IStoredHeightfieldChannels {
+    readonly flow?: Float32Array;
+    readonly moisture?: Float32Array;
+}
+/**
+ * One height buffer shared by world queries, rendered geometry, and a physics heightfield.
+ *
+ * The game supplies every value, so changing the terrain's shape never requires a package edit.
+ * `fromSampler` evaluates that game function exactly once at each vertex and retains only the
+ * resulting numbers. Queries interpolate those same numbers instead of evaluating the function
+ * again.
+ *
+ * @situation build terrain geometry and collision from one game-authored height function
+ * @situation generate a terrain a player can walk across
+ * @situation query the same ground height or normal that a player sees and collides with
+ * @situation ask how high the ground is here
+ * @situation build islands and coastlines from terrain
+ * @constraint sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output
+ * @constraint rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
+ * @override rows, columns, width, depth, origin, and sampleHeight are explicit on every field
+ * @example const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
+ */
+declare class Heightfield extends Group implements IComputeDriven {
+    #private;
+    readonly columns: number;
+    readonly depth: number;
+    readonly origin: IHeightfieldOrigin;
+    readonly rows: number;
+    readonly width: number;
+    readonly processCadence: "render";
+    readonly warmupNodes: readonly unknown[];
+    constructor(options: IHeightfieldOptions & IStoredHeightfieldChannels);
+    static fromSampler(options: IHeightfieldSamplerOptions): Heightfield;
+    sample(channel: string, x: number, z: number): number;
+    get released(): boolean;
+    get generationComplete(): boolean;
+    get gpuHeightSample(): IGPUReadbackSample | undefined;
+    attachRenderer(renderer: IRendererLike): void;
+    process(renderer?: IRendererLike | undefined): void;
+    debug(): Record<string, unknown>;
+    detach(): void;
+    /** A copy of the canonical row-major samples, safe for game-side analysis. */
+    get heights(): Float32Array;
+    /** A copy of the normalized routed-flow channel, when world passes were requested. */
+    get flow(): Float32Array | undefined;
+    /** Bytes retained by this field's CPU channels and its conservative GPU allowance. */
+    get memoryBytes(): number;
+    heightAt(x: number, z: number): number;
+    normalAt(x: number, z: number, target?: Vector3): Vector3;
+    /** The same values transposed once into Rapier's column-major height-matrix order. */
+    toColliderHeights(): Float32Array;
+    /** Builds an ordinary Three.js geometry without choosing its surface. */
+    toGeometry(): BufferGeometry;
+}
+
+export { Heightfield, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldSamplerOptions, type IHeightfieldWorldPassOptions, type IWorldCapabilities, type IWorldTileColliderInput, type IWorldTilesTopologyObservation, TerrainTiles, getWorldCapabilities };