@world-engines/spatial-authoring 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/dist/SpatialWorldCanvas.d.ts

@@ -0,0 +1,18 @@
+import type { JSX } from "react";
+import type { SpatialObjectV1, SpatialWorldSourceV1 } from "./schema.js";
+export interface SpatialCanvasObject {
+    readonly id: string;
+    readonly label: string;
+    readonly x: number;
+    readonly y: number;
+    readonly selected: boolean;
+}
+export interface SpatialWorldCanvasProps {
+    readonly source: SpatialWorldSourceV1;
+    readonly selectedId?: string;
+    readonly onSelect?: (object: SpatialObjectV1) => void;
+    readonly className?: string;
+}
+/** 将唯一 source 映射为纯 SVG 图元；不产生 Three scene 或复制作者数据。 */
+export declare function planSpatialCanvas(source: SpatialWorldSourceV1, selectedId?: string): readonly SpatialCanvasObject[];
+export declare function SpatialWorldCanvas({ source, selectedId, onSelect, className }: SpatialWorldCanvasProps): JSX.Element;

package/dist/SpatialWorldCanvas.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { validateSpatialWorldSourceV1 } from "./schema.js";
+/** 将唯一 source 映射为纯 SVG 图元；不产生 Three scene 或复制作者数据。 */
+export function planSpatialCanvas(source, selectedId) {
+    const validSource = validateSpatialWorldSourceV1(source);
+    return validSource.objects.map((object) => ({
+        id: object.id,
+        label: object.label,
+        x: object.x,
+        y: object.y,
+        selected: object.id === selectedId,
+    }));
+}
+export function SpatialWorldCanvas({ source, selectedId, onSelect, className }) {
+    const validSource = validateSpatialWorldSourceV1(source);
+    const select = (object) => onSelect?.(object);
+    const selectFromKeyboard = (event, object) => {
+        if (event.key !== "Enter" && event.key !== " ")
+            return;
+        event.preventDefault();
+        select(object);
+    };
+    return (_jsxs("svg", { "aria-label": "\u7A7A\u95F4\u4E16\u754C\u753B\u5E03", className: className, "data-source-revision": validSource.revision, role: "group", viewBox: `0 0 ${validSource.topology.width} ${validSource.topology.height}`, children: [_jsx("rect", { fill: "transparent", height: validSource.topology.height, width: validSource.topology.width }), validSource.objects.map((object) => (_jsxs("g", { "aria-label": object.label, onClick: () => select(object), onKeyDown: (event) => selectFromKeyboard(event, object), role: onSelect === undefined ? undefined : "button", tabIndex: onSelect === undefined ? undefined : 0, transform: `translate(${object.x} ${object.y})`, children: [_jsx("circle", { fill: object.id === selectedId ? "#2563eb" : "#64748b", r: "4" }), _jsx("text", { dy: "-7", textAnchor: "middle", children: object.label })] }, object.id)))] }));
+}

package/dist/SpatialWorldEditor.d.ts

@@ -0,0 +1,38 @@
+import { type JSX } from "react";
+import type { SpatialObjectV1, SpatialWorldSourceV1 } from "./schema.js";
+export interface SpatialObjectDraftV1 {
+    readonly key: string;
+    readonly kind: SpatialObjectV1["kind"];
+    readonly label: string;
+    readonly x: number;
+    readonly y: number;
+}
+/** 仅是传给 source authority 的意图；组件绝不在本地拼装下一份 source。 */
+export interface SpatialCreateRequest {
+    readonly sourceRevision: number;
+    readonly object: SpatialObjectDraftV1;
+}
+export interface SpatialUpdateRequest {
+    readonly sourceRevision: number;
+    readonly spatialId: string;
+    readonly patch: Pick<SpatialObjectDraftV1, "label" | "x" | "y">;
+}
+export interface SpatialRemoveRequest {
+    readonly sourceRevision: number;
+    readonly spatialId: string;
+    readonly confirmed: boolean;
+}
+export interface SpatialWorldEditorProps {
+    /** source 由宿主提供，是唯一可编辑 authority；本组件不持久化、不直接 mutation。 */
+    readonly source: SpatialWorldSourceV1;
+    /** 由宿主控制的选择；null 表示明确取消选择，undefined 则使用本组件局部状态。 */
+    readonly selectedId?: string | null;
+    readonly onSelectionChange?: (object: SpatialObjectV1 | undefined) => void;
+    readonly onCreate?: (request: SpatialCreateRequest) => void;
+    readonly onUpdate?: (request: SpatialUpdateRequest) => void;
+    readonly onRemove?: (request: SpatialRemoveRequest) => void;
+    /** 宿主 readback 处于围栏外时必须关闭所有 source mutation。 */
+    readonly disabled?: boolean;
+    readonly className?: string;
+}
+export declare function SpatialWorldEditor({ source, selectedId: controlledSelectedId, onSelectionChange, onCreate, onUpdate, onRemove, disabled, className }: SpatialWorldEditorProps): JSX.Element;

package/dist/SpatialWorldEditor.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from "react";
+import { SpatialWorldCanvas } from "./SpatialWorldCanvas.js";
+import { validateSpatialWorldSourceV1 } from "./schema.js";
+import { planSpatialObjectRemoval } from "./source-adapter.js";
+export function SpatialWorldEditor({ source, selectedId: controlledSelectedId, onSelectionChange, onCreate, onUpdate, onRemove, disabled = false, className }) {
+    const validSource = validateSpatialWorldSourceV1(source);
+    const [uncontrolledSelectedId, setUncontrolledSelectedId] = useState(null);
+    const [newKey, setNewKey] = useState("");
+    const [newKind, setNewKind] = useState("location");
+    const [newLabel, setNewLabel] = useState("");
+    const [newX, setNewX] = useState("0");
+    const [newY, setNewY] = useState("0");
+    const [editLabel, setEditLabel] = useState("");
+    const [editX, setEditX] = useState("");
+    const [editY, setEditY] = useState("");
+    const [removalPlan, setRemovalPlan] = useState(null);
+    const selectedId = controlledSelectedId === undefined ? uncontrolledSelectedId : controlledSelectedId;
+    const selected = useMemo(() => selectedId === null ? undefined : validSource.objects.find((object) => object.id === selectedId), [selectedId, validSource.objects]);
+    useEffect(() => {
+        setEditLabel(selected?.label ?? "");
+        setEditX(selected === undefined ? "" : String(selected.x));
+        setEditY(selected === undefined ? "" : String(selected.y));
+        setRemovalPlan(null);
+    }, [selected]);
+    const select = (object) => {
+        if (controlledSelectedId === undefined)
+            setUncontrolledSelectedId(object.id);
+        onSelectionChange?.(object);
+    };
+    const createObject = (event) => {
+        event.preventDefault();
+        const x = Number(newX);
+        const y = Number(newY);
+        if (onCreate === undefined || newKey.trim().length === 0 || newLabel.trim().length === 0 || !Number.isFinite(x) || !Number.isFinite(y))
+            return;
+        onCreate({ sourceRevision: validSource.revision, object: { key: newKey.trim(), kind: newKind, label: newLabel.trim(), x, y } });
+    };
+    const updateObject = (event) => {
+        event.preventDefault();
+        const x = Number(editX);
+        const y = Number(editY);
+        if (selected === undefined || onUpdate === undefined || editLabel.trim().length === 0 || !Number.isFinite(x) || !Number.isFinite(y))
+            return;
+        onUpdate({ sourceRevision: validSource.revision, spatialId: selected.id, patch: { label: editLabel.trim(), x, y } });
+    };
+    const requestRemoval = () => {
+        if (selected !== undefined)
+            setRemovalPlan(planSpatialObjectRemoval(validSource, selected.id));
+    };
+    const confirmRemoval = (event) => {
+        event.preventDefault();
+        if (removalPlan === null || onRemove === undefined)
+            return;
+        const confirmed = new FormData(event.currentTarget).get("confirm-removal") === "on";
+        if (removalPlan.requiresConfirmation && !confirmed)
+            return;
+        onRemove({ sourceRevision: removalPlan.sourceRevision, spatialId: removalPlan.target.id, confirmed });
+    };
+    return (_jsxs("section", { className: className, "data-spatial-world-id": validSource.worldId, "data-source-revision": validSource.revision, children: [_jsxs("header", { children: [_jsx("h2", { children: validSource.worldId }), _jsxs("p", { children: [validSource.objects.length, " \u4E2A\u7A7A\u95F4\u5BF9\u8C61\uFF0Crevision ", validSource.revision] })] }), _jsx(SpatialWorldCanvas, { onSelect: select, source: validSource, ...(selectedId === null ? {} : { selectedId }) }), _jsx("aside", { "aria-live": "polite", children: selected === undefined ? "请选择地图对象" : `${selected.label}（${selected.references.length} 个引用）` }), onCreate === undefined ? null : (_jsxs("form", { "aria-label": "\u521B\u5EFA\u7A7A\u95F4\u5BF9\u8C61", onSubmit: createObject, children: [_jsx("h3", { children: "\u521B\u5EFA\u7A7A\u95F4\u5BF9\u8C61" }), _jsx("input", { "aria-label": "\u65B0\u5BF9\u8C61 key", disabled: disabled, onChange: (event) => setNewKey(event.target.value), value: newKey }), _jsxs("select", { "aria-label": "\u65B0\u5BF9\u8C61\u7C7B\u578B", disabled: disabled, onChange: (event) => setNewKind(event.target.value), value: newKind, children: [_jsx("option", { value: "location", children: "location" }), _jsx("option", { value: "portal", children: "portal" }), _jsx("option", { value: "region", children: "region" })] }), _jsx("input", { "aria-label": "\u65B0\u5BF9\u8C61\u6807\u7B7E", disabled: disabled, onChange: (event) => setNewLabel(event.target.value), value: newLabel }), _jsx("input", { "aria-label": "\u65B0\u5BF9\u8C61 X", disabled: disabled, inputMode: "decimal", onChange: (event) => setNewX(event.target.value), value: newX }), _jsx("input", { "aria-label": "\u65B0\u5BF9\u8C61 Y", disabled: disabled, inputMode: "decimal", onChange: (event) => setNewY(event.target.value), value: newY }), _jsx("button", { disabled: disabled || newKey.trim().length === 0 || newLabel.trim().length === 0, type: "submit", children: "\u521B\u5EFA\u5BF9\u8C61" })] })), selected === undefined || onUpdate === undefined ? null : (_jsxs("form", { "aria-label": "\u7F16\u8F91\u7A7A\u95F4\u5BF9\u8C61", onSubmit: updateObject, children: [_jsxs("h3", { children: ["\u7F16\u8F91 ", selected.id] }), _jsx("input", { "aria-label": "\u5BF9\u8C61\u6807\u7B7E", disabled: disabled, onChange: (event) => setEditLabel(event.target.value), value: editLabel }), _jsx("input", { "aria-label": "\u5BF9\u8C61 X", disabled: disabled, inputMode: "decimal", onChange: (event) => setEditX(event.target.value), value: editX }), _jsx("input", { "aria-label": "\u5BF9\u8C61 Y", disabled: disabled, inputMode: "decimal", onChange: (event) => setEditY(event.target.value), value: editY }), _jsx("button", { disabled: disabled || editLabel.trim().length === 0, type: "submit", children: "\u4FDD\u5B58\u5BF9\u8C61" })] })), selected === undefined || onRemove === undefined ? null : _jsx("button", { disabled: disabled, onClick: requestRemoval, type: "button", children: "\u5220\u9664\u5BF9\u8C61" }), removalPlan === null ? null : (_jsxs("form", { "aria-label": "\u786E\u8BA4\u5220\u9664\u7A7A\u95F4\u5BF9\u8C61", onSubmit: confirmRemoval, children: [_jsxs("h3", { children: ["\u5220\u9664 ", removalPlan.target.label] }), removalPlan.impacts.length === 0 ? _jsx("p", { children: "\u8BE5\u5BF9\u8C61\u6CA1\u6709\u5F15\u7528\u5F71\u54CD\u3002" }) : (_jsxs(_Fragment, { children: [_jsx("p", { children: "\u5220\u9664\u4F1A\u5F71\u54CD\u4EE5\u4E0B\u5F15\u7528\uFF1A" }), _jsx("ul", { "aria-label": "\u7A7A\u95F4\u5F15\u7528\u5F71\u54CD\u5217\u8868", children: removalPlan.impacts.map(({ reference }) => _jsxs("li", { children: [reference.ownerKind, " ", reference.ownerId, " \u00B7 ", reference.fieldPath] }, `${reference.ownerId}:${reference.fieldPath}`)) }), _jsxs("label", { children: [_jsx("input", { disabled: disabled, name: "confirm-removal", type: "checkbox" }), " \u6211\u5DF2\u77E5\u6089\u8FD9\u4E9B\u5F15\u7528\u4F1A\u5931\u6548"] })] })), _jsx("button", { disabled: disabled, type: "submit", children: "\u786E\u8BA4\u5220\u9664" }), _jsx("button", { disabled: disabled, onClick: () => setRemovalPlan(null), type: "button", children: "\u53D6\u6D88" })] }))] }));
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./schema.js";
+export * from "./plane-generation.js";
+export * from "./procedural-city.js";
+export * from "./road-generation.js";
+export * from "./road-parcels.js";
+export * from "./spatial-runtime.js";
+export * from "./spatial-templates.js";
+export * from "./protobuf-source-codec.js";
+export * from "./source-adapter.js";
+export * from "./worker.js";
+export * from "./SpatialWorldCanvas.js";
+export * from "./SpatialWorldEditor.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./schema.js";
+export * from "./plane-generation.js";
+export * from "./procedural-city.js";
+export * from "./road-generation.js";
+export * from "./road-parcels.js";
+export * from "./spatial-runtime.js";
+export * from "./spatial-templates.js";
+export * from "./protobuf-source-codec.js";
+export * from "./source-adapter.js";
+export * from "./worker.js";
+export * from "./SpatialWorldCanvas.js";
+export * from "./SpatialWorldEditor.js";

package/dist/plane-generation.d.ts

@@ -0,0 +1,48 @@
+export declare const PLANE_GENERATION_PROFILE: "plane-perlin-hydrology-v1";
+export declare const SPHERE_GENERATION_PROFILE: "sphere-climate-v2";
+export declare const SPHERE_CLIMATE_V2_IDENTITY: "sha256:76923954c7c8681a750e59d273539db5065a48a16d26c8980449891b5561cfd2";
+export declare const PLANE_GENERATION_MAX_EXTENT_METERS: 1000000000;
+export declare const PLANE_GENERATION_MAX_ASPECT_RATIO: 64;
+export type PlaneGenerationResolution = 128 | 256 | 512;
+/** 旧平面 profile 的 exact-compatible 输入。 */
+export interface LegacyPlaneGenerationV1 {
+    readonly profile: typeof PLANE_GENERATION_PROFILE;
+    readonly seed: number;
+    readonly widthMeters: number;
+    readonly heightMeters: number;
+    readonly resolution: PlaneGenerationResolution;
+    readonly waterCoverage: number;
+    readonly relief: number;
+    readonly riverDensity: number;
+    readonly lakeDensity: number;
+    readonly rainfall: number;
+}
+/** 新建世界使用的球面气候生成合同。 */
+export interface WorldGenerationV2 {
+    readonly profile: typeof SPHERE_GENERATION_PROFILE;
+    readonly topology: "sphere";
+    readonly seed: number;
+    readonly widthMeters: number;
+    readonly heightMeters: number;
+    readonly resolution: PlaneGenerationResolution;
+    readonly waterCoverage: number;
+    readonly relief: number;
+    readonly riverDensity: number;
+    readonly lakeDensity: number;
+    readonly rainfall: number;
+    readonly temperatureC: number;
+}
+/** 保留既有导出名；调用方按 profile 判别旧平面与球面 v2。 */
+export type PlaneGenerationV1 = LegacyPlaneGenerationV1 | WorldGenerationV2;
+export type BiomeId = "ocean" | "freshwater" | "icecap" | "permafrost" | "tundra" | "alpine" | "desert" | "grassland" | "temperate" | "rainforest";
+export interface BiomePaletteEntry {
+    readonly id: BiomeId;
+    readonly label: string;
+    readonly color: `#${string}`;
+}
+/** 生态颜色的唯一 authority；WASM 只输出稳定 biome id。 */
+export declare const BIOME_PALETTE: readonly BiomePaletteEntry[];
+export declare const DEFAULT_PLANE_GENERATION: Readonly<LegacyPlaneGenerationV1>;
+export declare const DEFAULT_WORLD_GENERATION: Readonly<WorldGenerationV2>;
+/** 严格验证并返回按 profile 判别的 canonical 参数；未知字段不会被静默丢弃。 */
+export declare function validatePlaneGeneration(value: unknown): PlaneGenerationV1;

package/dist/plane-generation.js

@@ -0,0 +1,126 @@
+export const PLANE_GENERATION_PROFILE = "plane-perlin-hydrology-v1";
+export const SPHERE_GENERATION_PROFILE = "sphere-climate-v2";
+export const SPHERE_CLIMATE_V2_IDENTITY = "sha256:76923954c7c8681a750e59d273539db5065a48a16d26c8980449891b5561cfd2";
+export const PLANE_GENERATION_MAX_EXTENT_METERS = 1_000_000_000;
+export const PLANE_GENERATION_MAX_ASPECT_RATIO = 64;
+/** 生态颜色的唯一 authority；WASM 只输出稳定 biome id。 */
+export const BIOME_PALETTE = Object.freeze([
+    { id: "ocean", label: "海洋", color: "#1769aa" },
+    { id: "freshwater", label: "湖泊", color: "#2f9ee5" },
+    { id: "icecap", label: "冰盖", color: "#f7fbff" },
+    { id: "permafrost", label: "永久冻土", color: "#b7d4d2" },
+    { id: "tundra", label: "苔原", color: "#8f9d6a" },
+    { id: "alpine", label: "高山", color: "#77777f" },
+    { id: "desert", label: "荒漠", color: "#e3b341" },
+    { id: "grassland", label: "草原", color: "#79ad45" },
+    { id: "temperate", label: "温带林地", color: "#3f8f45" },
+    { id: "rainforest", label: "热带雨林", color: "#075c36" },
+]);
+export const DEFAULT_PLANE_GENERATION = Object.freeze({
+    profile: PLANE_GENERATION_PROFILE,
+    seed: 2_050_986_450,
+    widthMeters: 100_000,
+    heightMeters: 100_000,
+    resolution: 256,
+    waterCoverage: 0.62,
+    relief: 0.38,
+    riverDensity: 0.5,
+    lakeDensity: 0.08,
+    rainfall: 1,
+});
+export const DEFAULT_WORLD_GENERATION = Object.freeze({
+    profile: SPHERE_GENERATION_PROFILE,
+    topology: "sphere",
+    seed: 2_050_986_450,
+    widthMeters: 40_030_000,
+    heightMeters: 20_015_000,
+    resolution: 512,
+    waterCoverage: 0.62,
+    relief: 0.38,
+    riverDensity: 0.5,
+    lakeDensity: 0.08,
+    rainfall: 1,
+    temperatureC: 30,
+});
+const LEGACY_KEYS = new Set([
+    "profile", "seed", "widthMeters", "heightMeters", "resolution", "waterCoverage", "relief",
+    "riverDensity", "lakeDensity", "rainfall",
+]);
+const SPHERE_KEYS = new Set([
+    "profile", "topology", "seed", "widthMeters", "heightMeters", "resolution", "waterCoverage",
+    "relief", "riverDensity", "lakeDensity", "rainfall", "temperatureC",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function finiteNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new TypeError(`${field} 必须是有限数`);
+    return value;
+}
+function boundedNumber(value, field, minimum, maximum) {
+    const number = finiteNumber(value, field);
+    if (number < minimum || number > maximum)
+        throw new RangeError(`${field} 必须位于 ${minimum}..${maximum}`);
+    return number;
+}
+function validateExactKeys(value, expected, label) {
+    const unknownKeys = Object.keys(value).filter((key) => !expected.has(key));
+    if (unknownKeys.length > 0)
+        throw new TypeError(`${label} 包含未知字段：${unknownKeys.join(", ")}`);
+    const missingKeys = [...expected].filter((key) => !Object.hasOwn(value, key));
+    if (missingKeys.length > 0)
+        throw new TypeError(`${label} 缺少字段：${missingKeys.join(", ")}`);
+}
+function validateSharedNumbers(value) {
+    const seed = finiteNumber(value.seed, "seed");
+    if (!Number.isInteger(seed) || seed < 0 || seed > 0xffff_ffff)
+        throw new RangeError("seed 必须是 uint32");
+    const widthMeters = boundedNumber(value.widthMeters, "widthMeters", 1, PLANE_GENERATION_MAX_EXTENT_METERS);
+    const heightMeters = boundedNumber(value.heightMeters, "heightMeters", 1, PLANE_GENERATION_MAX_EXTENT_METERS);
+    const resolution = finiteNumber(value.resolution, "resolution");
+    if (resolution !== 128 && resolution !== 256 && resolution !== 512) {
+        throw new RangeError("resolution 必须为 128、256 或 512");
+    }
+    return {
+        seed,
+        widthMeters,
+        heightMeters,
+        resolution: resolution,
+        waterCoverage: boundedNumber(value.waterCoverage, "waterCoverage", 0, 0.95),
+        relief: boundedNumber(value.relief, "relief", 0, 1),
+        riverDensity: boundedNumber(value.riverDensity, "riverDensity", 0, 1),
+        lakeDensity: boundedNumber(value.lakeDensity, "lakeDensity", 0, 0.25),
+        rainfall: boundedNumber(value.rainfall, "rainfall", 0.1, 8),
+    };
+}
+/** 严格验证并返回按 profile 判别的 canonical 参数；未知字段不会被静默丢弃。 */
+export function validatePlaneGeneration(value) {
+    if (!isRecord(value))
+        throw new TypeError("PlaneGenerationV1 必须是对象");
+    if (value.profile === PLANE_GENERATION_PROFILE) {
+        validateExactKeys(value, LEGACY_KEYS, "LegacyPlaneGenerationV1");
+        const shared = validateSharedNumbers(value);
+        if (Math.max(shared.widthMeters, shared.heightMeters) / Math.min(shared.widthMeters, shared.heightMeters)
+            > PLANE_GENERATION_MAX_ASPECT_RATIO) {
+            throw new RangeError(`widthMeters 与 heightMeters 的比例不得超过 ${PLANE_GENERATION_MAX_ASPECT_RATIO}:1`);
+        }
+        return Object.freeze({ profile: PLANE_GENERATION_PROFILE, ...shared });
+    }
+    if (value.profile === SPHERE_GENERATION_PROFILE) {
+        validateExactKeys(value, SPHERE_KEYS, "WorldGenerationV2");
+        if (value.topology !== "sphere")
+            throw new TypeError("topology 必须为 sphere");
+        const shared = validateSharedNumbers(value);
+        if (shared.widthMeters !== shared.heightMeters * 2) {
+            throw new RangeError("球面 widthMeters 必须严格等于 heightMeters 的两倍");
+        }
+        return Object.freeze({
+            profile: SPHERE_GENERATION_PROFILE,
+            topology: "sphere",
+            ...shared,
+            temperatureC: boundedNumber(value.temperatureC, "temperatureC", -40, 60),
+        });
+    }
+    throw new TypeError(`profile 必须为 ${PLANE_GENERATION_PROFILE} 或 ${SPHERE_GENERATION_PROFILE}`);
+}

package/dist/plane-generator/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "worldengine-plane-generator",
+  "type": "module",
+  "version": "0.1.0",
+  "files": [
+    "plane-generator_bg.wasm",
+    "plane-generator.js",
+    "plane-generator.d.ts"
+  ],
+  "main": "plane-generator.js",
+  "types": "plane-generator.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ]
+}

package/dist/plane-generator/plane-generator.d.ts

@@ -0,0 +1,57 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export function generate_plane_json(input: string): string;
+
+/**
+ * 原始 terrain-roads-v1 core ABI，供行为测试和非 plane adapter 调用。
+ */
+export function generate_road_network_json(input: string): string;
+
+/**
+ * 为旧平面地形生成固定、与相机无关的道路缓存。
+ *
+ * sphere-climate-v2 尚未接入此 plane-only adapter；调用者须按 profile
+ * 明确选择适配器，不能把球面参数悄然降级为平面。
+ */
+export function generate_world_roads_json(input: string): string;
+
+export function sample_plane_tile_json(input: string): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly generate_plane_json: (a: number, b: number) => [number, number, number, number];
+    readonly generate_road_network_json: (a: number, b: number) => [number, number, number, number];
+    readonly generate_world_roads_json: (a: number, b: number) => [number, number, number, number];
+    readonly sample_plane_tile_json: (a: number, b: number) => [number, number, number, number];
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;