@threenative/core 0.1.0 → 0.3.0

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,55 @@
+import { Vector3, BufferGeometry } from 'three';
+
+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;
+}
+interface IHeightfieldSamplerOptions extends Omit<IHeightfieldOptions, "heights"> {
+    /** Game-owned terrain function. It is evaluated once and never retained. */
+    readonly sampleHeight: (x: number, z: number) => number;
+}
+/**
+ * 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 query the same ground height or normal that a player sees and collides with
+ * @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 {
+    #private;
+    readonly columns: number;
+    readonly depth: number;
+    readonly origin: IHeightfieldOrigin;
+    readonly rows: number;
+    readonly width: number;
+    constructor(options: IHeightfieldOptions);
+    static fromSampler(options: IHeightfieldSamplerOptions): Heightfield;
+    sample(channel: string, x: number, z: number): number;
+    /** A copy of the canonical row-major samples, safe for game-side analysis. */
+    get heights(): Float32Array;
+    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 };

package/dist/world.js

@@ -0,0 +1,175 @@
+import { Vector3, BufferGeometry, BufferAttribute } from 'three';
+
+// src/world.ts
+function finite(value, name) {
+  if (!Number.isFinite(value)) throw new Error(`Heightfield ${name} must be finite.`);
+  return value;
+}
+function positive(value, name) {
+  finite(value, name);
+  if (value <= 0) throw new Error(`Heightfield ${name} must be greater than zero.`);
+  return value;
+}
+function count(value, name) {
+  if (!Number.isInteger(value) || value < 2)
+    throw new Error(`Heightfield ${name} must be an integer of at least 2.`);
+  return value;
+}
+var Heightfield = class _Heightfield {
+  columns;
+  depth;
+  origin;
+  rows;
+  width;
+  #cellDepth;
+  #cellWidth;
+  #colliderHeights;
+  #heights;
+  #minimumX;
+  #minimumZ;
+  constructor(options) {
+    this.columns = count(options.columns, "columns");
+    this.rows = count(options.rows, "rows");
+    this.width = positive(options.width, "width");
+    this.depth = positive(options.depth, "depth");
+    this.origin = {
+      x: finite(options.origin.x, "origin.x"),
+      z: finite(options.origin.z, "origin.z")
+    };
+    const expected = this.rows * this.columns;
+    if (options.heights.length !== expected)
+      throw new Error(
+        `Heightfield expected ${expected} heights, received ${options.heights.length}.`
+      );
+    for (const height of options.heights) finite(height, "height sample");
+    this.#heights = options.heights.slice();
+    this.#colliderHeights = new Float32Array(expected);
+    for (let column = 0; column < this.columns; column += 1) {
+      for (let row = 0; row < this.rows; row += 1) {
+        this.#colliderHeights[column * this.rows + row] = this.#height(row * this.columns + column);
+      }
+    }
+    this.#cellWidth = this.width / (this.columns - 1);
+    this.#cellDepth = this.depth / (this.rows - 1);
+    this.#minimumX = this.origin.x - this.width / 2;
+    this.#minimumZ = this.origin.z - this.depth / 2;
+  }
+  static fromSampler(options) {
+    const columns = count(options.columns, "columns");
+    const rows = count(options.rows, "rows");
+    const width = positive(options.width, "width");
+    const depth = positive(options.depth, "depth");
+    const originX = finite(options.origin.x, "origin.x");
+    const originZ = finite(options.origin.z, "origin.z");
+    const minimumX = originX - width / 2;
+    const minimumZ = originZ - depth / 2;
+    const cellWidth = width / (columns - 1);
+    const cellDepth = depth / (rows - 1);
+    const heights = new Float32Array(rows * columns);
+    for (let row = 0; row < rows; row += 1) {
+      const z = minimumZ + row * cellDepth;
+      for (let column = 0; column < columns; column += 1) {
+        const x = minimumX + column * cellWidth;
+        heights[row * columns + column] = finite(options.sampleHeight(x, z), "sampleHeight result");
+      }
+    }
+    return new _Heightfield({ columns, depth, heights, origin: options.origin, rows, width });
+  }
+  sample(channel, x, z) {
+    if (channel !== "height") throw new Error(`Heightfield unknown channel '${channel}'.`);
+    return this.heightAt(x, z);
+  }
+  /** A copy of the canonical row-major samples, safe for game-side analysis. */
+  get heights() {
+    return this.#heights.slice();
+  }
+  heightAt(x, z) {
+    finite(x, "query x");
+    finite(z, "query z");
+    const column = (x - this.#minimumX) / this.#cellWidth;
+    const row = (z - this.#minimumZ) / this.#cellDepth;
+    const epsilon = 1e-9;
+    if (column < -epsilon || row < -epsilon || column > this.columns - 1 + epsilon || row > this.rows - 1 + epsilon)
+      throw new Error(`Heightfield query (${x}, ${z}) is outside its resident region.`);
+    return this.#interpolate(
+      Math.min(this.columns - 1, Math.max(0, column)),
+      Math.min(this.rows - 1, Math.max(0, row))
+    );
+  }
+  normalAt(x, z, target = new Vector3()) {
+    this.heightAt(x, z);
+    const leftX = Math.max(this.#minimumX, x - this.#cellWidth);
+    const rightX = Math.min(this.#minimumX + this.width, x + this.#cellWidth);
+    const nearZ = Math.max(this.#minimumZ, z - this.#cellDepth);
+    const farZ = Math.min(this.#minimumZ + this.depth, z + this.#cellDepth);
+    const slopeX = (this.heightAt(rightX, z) - this.heightAt(leftX, z)) / (rightX - leftX);
+    const slopeZ = (this.heightAt(x, farZ) - this.heightAt(x, nearZ)) / (farZ - nearZ);
+    return target.set(-slopeX, 1, -slopeZ).normalize();
+  }
+  /** The same values transposed once into Rapier's column-major height-matrix order. */
+  toColliderHeights() {
+    return this.#colliderHeights.slice();
+  }
+  /** Builds an ordinary Three.js geometry without choosing its surface. */
+  toGeometry() {
+    const count2 = this.rows * this.columns;
+    const positions = new Float32Array(count2 * 3);
+    const normals = new Float32Array(count2 * 3);
+    const normal = new Vector3();
+    for (let row = 0; row < this.rows; row += 1) {
+      const localZ = -this.depth / 2 + row * this.#cellDepth;
+      const worldZ = this.origin.z + localZ;
+      for (let column = 0; column < this.columns; column += 1) {
+        const index = row * this.columns + column;
+        const localX = -this.width / 2 + column * this.#cellWidth;
+        const worldX = this.origin.x + localX;
+        positions[index * 3] = localX;
+        positions[index * 3 + 1] = this.#height(index);
+        positions[index * 3 + 2] = localZ;
+        this.normalAt(worldX, worldZ, normal);
+        normals[index * 3] = normal.x;
+        normals[index * 3 + 1] = normal.y;
+        normals[index * 3 + 2] = normal.z;
+      }
+    }
+    const indices = new Uint32Array((this.rows - 1) * (this.columns - 1) * 6);
+    let offset = 0;
+    for (let row = 0; row < this.rows - 1; row += 1) {
+      for (let column = 0; column < this.columns - 1; column += 1) {
+        const upperLeft = row * this.columns + column;
+        const upperRight = upperLeft + 1;
+        const lowerLeft = upperLeft + this.columns;
+        const lowerRight = lowerLeft + 1;
+        indices.set([upperLeft, lowerLeft, upperRight, upperRight, lowerLeft, lowerRight], offset);
+        offset += 6;
+      }
+    }
+    const geometry = new BufferGeometry();
+    geometry.setAttribute("position", new BufferAttribute(positions, 3));
+    geometry.setAttribute("normal", new BufferAttribute(normals, 3));
+    geometry.setIndex(new BufferAttribute(indices, 1));
+    return geometry;
+  }
+  #interpolate(column, row) {
+    const column0 = Math.floor(column);
+    const row0 = Math.floor(row);
+    const column1 = Math.min(this.columns - 1, column0 + 1);
+    const row1 = Math.min(this.rows - 1, row0 + 1);
+    const columnMix = column - column0;
+    const rowMix = row - row0;
+    const upperLeft = this.#height(row0 * this.columns + column0);
+    const upperRight = this.#height(row0 * this.columns + column1);
+    const lowerLeft = this.#height(row1 * this.columns + column0);
+    const lowerRight = this.#height(row1 * this.columns + column1);
+    const upper = upperLeft + (upperRight - upperLeft) * columnMix;
+    const lower = lowerLeft + (lowerRight - lowerLeft) * columnMix;
+    return upper + (lower - upper) * rowMix;
+  }
+  #height(index) {
+    const height = this.#heights[index];
+    if (height === void 0) throw new Error(`Heightfield internal sample ${index} is missing.`);
+    return height;
+  }
+};
+
+export { Heightfield };

package/mcp/assets.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { launchMcpServer } from "./launch.mjs";
+import { MCP_PACKAGES } from "./servers.mjs";
+
+await launchMcpServer(MCP_PACKAGES.assets);