@world-engines/tmw 0.1.0-alpha.0

package/dist/view-interaction-manifest-v3.js

@@ -0,0 +1,198 @@
+import { canonicalTmwBytes, canonicalTmwJson, tmwSha256Hex } from "./runtime-contract.js";
+import { parseViewPayloadSchemaV3, viewPayloadMatchesSchemaV3, } from "./view-payload-schema.js";
+import { parseViewEventDeliveryDeclarations, } from "./view-event-delivery.js";
+export { parseViewPayloadSchemaV3, viewPayloadMatchesSchemaV3, } from "./view-payload-schema.js";
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+const STABLE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const EVENT_TYPE = /^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$/;
+const MAX_EVENT_COUNT = 256;
+const MAX_CAPABILITY_COUNT = 256;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasExactKeys = (value, required, optional = []) => {
+    const allowed = new Set([...required, ...optional]);
+    return required.every((key) => Object.hasOwn(value, key))
+        && Object.keys(value).every((key) => allowed.has(key));
+};
+const isPositiveSafeInteger = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+const isCanonicalBootstrapUrl = (value) => {
+    if (typeof value !== "string")
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.username !== "" || parsed.password !== "" || parsed.hash !== "")
+        return false;
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && parsed.hostname === "localhost")) {
+        return false;
+    }
+    return parsed.toString() === value;
+};
+const parseEventDeclaration = (value) => {
+    if (!isRecord(value) || !hasExactKeys(value, ["event_id", "event_type", "capability", "payload_schema"])) {
+        return null;
+    }
+    if (typeof value.event_id !== "string" || !STABLE_ID.test(value.event_id))
+        return null;
+    if (typeof value.event_type !== "string" || !EVENT_TYPE.test(value.event_type))
+        return null;
+    if (typeof value.capability !== "string" || !STABLE_ID.test(value.capability))
+        return null;
+    if (parseViewPayloadSchemaV3(value.payload_schema) === null)
+        return null;
+    return value;
+};
+export const parseViewInteractionManifestV3 = (value) => {
+    if (!isRecord(value) || !hasExactKeys(value, [
+        "schema",
+        "generation",
+        "epoch",
+        "artifact_digest",
+        "runtime_contract_hash",
+        "bootstrap_url",
+        "capabilities",
+        "events"
+    ], ["view_deliveries"]))
+        return null;
+    if (value.schema !== "view-interaction-manifest.v3" || value.generation !== 3)
+        return null;
+    if (!isPositiveSafeInteger(value.epoch))
+        return null;
+    if (typeof value.artifact_digest !== "string" || !SHA256_HEX.test(value.artifact_digest))
+        return null;
+    if (typeof value.runtime_contract_hash !== "string" || !SHA256_HEX.test(value.runtime_contract_hash))
+        return null;
+    if (!isCanonicalBootstrapUrl(value.bootstrap_url))
+        return null;
+    if (!Array.isArray(value.capabilities)
+        || value.capabilities.length > MAX_CAPABILITY_COUNT
+        || !value.capabilities.every((capability) => typeof capability === "string" && STABLE_ID.test(capability)))
+        return null;
+    if (!Array.isArray(value.events)
+        || value.events.length > MAX_EVENT_COUNT
+        || !value.events.every((event) => parseEventDeclaration(event) !== null))
+        return null;
+    const capabilities = new Set(value.capabilities);
+    if (capabilities.size !== value.capabilities.length)
+        return null;
+    const eventIds = new Set();
+    const eventTypes = new Set();
+    for (const event of value.events) {
+        if (eventIds.has(event.event_id)
+            || eventTypes.has(event.event_type)
+            || !capabilities.has(event.capability))
+            return null;
+        eventIds.add(event.event_id);
+        eventTypes.add(event.event_type);
+    }
+    if (value.view_deliveries !== undefined && !parseViewEventDeliveryDeclarations(value.view_deliveries).ok) {
+        return null;
+    }
+    return value;
+};
+export const parseViewInteractionSourceV3 = (value) => {
+    if (!isRecord(value) || !hasExactKeys(value, [
+        "schema",
+        "generation",
+        "manifest",
+        "manifest_digest"
+    ]))
+        return null;
+    if (value.schema !== "view-interaction-source.v3" || value.generation !== 3)
+        return null;
+    if (parseViewInteractionManifestV3(value.manifest) === null)
+        return null;
+    if (typeof value.manifest_digest !== "string" || !SHA256_HEX.test(value.manifest_digest))
+        return null;
+    return value;
+};
+export const canonicalViewInteractionManifestV3 = (manifest) => {
+    const parsed = parseViewInteractionManifestV3(manifest);
+    if (parsed === null)
+        throw new Error("view_interaction_manifest_v3_invalid");
+    return canonicalTmwJson(parsed);
+};
+export const digestViewInteractionManifestV3 = async (manifest) => {
+    canonicalViewInteractionManifestV3(manifest);
+    return tmwSha256Hex(canonicalTmwBytes(manifest));
+};
+export const parseViewInteractionEventV3 = (value, manifest, manifestDigest) => {
+    const parsedManifest = parseViewInteractionManifestV3(manifest);
+    if (parsedManifest === null || !SHA256_HEX.test(manifestDigest)) {
+        return { ok: false, code: "view_manifest_invalid" };
+    }
+    if (!isRecord(value) || !hasExactKeys(value, [
+        "schema",
+        "generation",
+        "event_id",
+        "event_type",
+        "payload",
+        "interaction_id",
+        "manifest_digest",
+        "epoch",
+        "artifact_digest",
+        "nonce"
+    ]))
+        return { ok: false, code: "view_event_envelope_invalid" };
+    if (value.schema !== "view-interaction-event.v3" || value.generation !== 3) {
+        return { ok: false, code: "view_event_generation_unsupported" };
+    }
+    if (value.epoch !== manifest.epoch)
+        return { ok: false, code: "stale_content_epoch" };
+    if (value.artifact_digest !== manifest.artifact_digest)
+        return { ok: false, code: "view_event_artifact_mismatch" };
+    if (value.manifest_digest !== manifestDigest)
+        return { ok: false, code: "view_event_manifest_mismatch" };
+    if (typeof value.event_id !== "string" || typeof value.event_type !== "string") {
+        return { ok: false, code: "view_event_identity_invalid" };
+    }
+    const declaration = manifest.events.find((event) => event.event_id === value.event_id);
+    if (declaration === undefined || declaration.event_type !== value.event_type) {
+        return { ok: false, code: "view_event_not_declared" };
+    }
+    if (!manifest.capabilities.includes(declaration.capability)) {
+        return { ok: false, code: "view_event_capability_denied" };
+    }
+    if (!isRecord(value.payload) || !viewPayloadMatchesSchemaV3(value.payload, declaration.payload_schema)) {
+        return { ok: false, code: "view_event_payload_invalid" };
+    }
+    if (typeof value.interaction_id !== "string" || !STABLE_ID.test(value.interaction_id)) {
+        return { ok: false, code: "view_event_interaction_id_invalid" };
+    }
+    if (typeof value.nonce !== "string" || !STABLE_ID.test(value.nonce)) {
+        return { ok: false, code: "view_event_nonce_invalid" };
+    }
+    return { ok: true, event: value };
+};
+/** Pure stateful replay gate; the Player/preview host remains the sole listener. */
+export const createViewInteractionEventGateV3 = (manifest, manifestDigest, maxReplayNonces = 2_048) => {
+    if (!Number.isSafeInteger(maxReplayNonces) || maxReplayNonces <= 0) {
+        throw new Error("view_event_replay_window_invalid");
+    }
+    const seenNonces = new Set();
+    const nonceOrder = [];
+    return Object.freeze({
+        parse: (value) => {
+            const parsed = parseViewInteractionEventV3(value, manifest, manifestDigest);
+            if (!parsed.ok)
+                return parsed;
+            if (seenNonces.has(parsed.event.nonce))
+                return { ok: false, code: "view_event_replayed" };
+            seenNonces.add(parsed.event.nonce);
+            nonceOrder.push(parsed.event.nonce);
+            if (nonceOrder.length > maxReplayNonces) {
+                const oldest = nonceOrder.shift();
+                if (oldest !== undefined)
+                    seenNonces.delete(oldest);
+            }
+            return parsed;
+        },
+        clear: () => {
+            seenNonces.clear();
+            nonceOrder.length = 0;
+        }
+    });
+};

package/dist/view-payload-schema.d.ts

@@ -0,0 +1,17 @@
+import { type TmwJsonPrimitive, type TmwJsonValue } from "./runtime-contract.js";
+export type ViewPayloadPrimitiveKind = "string" | "number" | "integer" | "boolean" | "null";
+export interface ViewPayloadPropertyV3 {
+    readonly type: ViewPayloadPrimitiveKind;
+    readonly required: boolean;
+    readonly enum?: ReadonlyArray<TmwJsonPrimitive>;
+}
+export interface ViewPayloadSchemaV3 {
+    readonly type: "object";
+    readonly additional_properties: false;
+    readonly properties: Readonly<Record<string, ViewPayloadPropertyV3>>;
+    readonly max_bytes: number;
+}
+/** 仅校验 View payload schema；不涉及 manifest 身份、能力或 epoch。 */
+export declare const parseViewPayloadSchemaV3: (value: unknown) => ViewPayloadSchemaV3 | null;
+/** 仅校验 payload 是否符合已校验 schema；不涉及 event envelope 身份。 */
+export declare const viewPayloadMatchesSchemaV3: (payload: Record<string, unknown>, schema: ViewPayloadSchemaV3) => payload is Record<string, TmwJsonValue>;

package/dist/view-payload-schema.js

@@ -0,0 +1,84 @@
+import { canonicalTmwBytes } from "./runtime-contract.js";
+const STABLE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const MAX_SCHEMA_PROPERTIES = 128;
+const MAX_PAYLOAD_BYTES = 32 * 1024;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasExactKeys = (value, required, optional = []) => {
+    const allowed = new Set([...required, ...optional]);
+    return required.every((key) => Object.hasOwn(value, key))
+        && Object.keys(value).every((key) => allowed.has(key));
+};
+const isPositiveSafeInteger = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+const isJsonValue = (value) => {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    return isRecord(value) && Object.values(value).every(isJsonValue);
+};
+const parseProperty = (value) => {
+    if (!isRecord(value) || !hasExactKeys(value, ["type", "required"], ["enum"]))
+        return null;
+    if (value.type !== "string"
+        && value.type !== "number"
+        && value.type !== "integer"
+        && value.type !== "boolean"
+        && value.type !== "null")
+        return null;
+    if (typeof value.required !== "boolean")
+        return null;
+    if (value.enum !== undefined) {
+        if (!Array.isArray(value.enum) || value.enum.length === 0 || !value.enum.every((item) => (item === null
+            || typeof item === "string"
+            || typeof item === "boolean"
+            || (typeof item === "number" && Number.isFinite(item)))))
+            return null;
+    }
+    return value;
+};
+/** 仅校验 View payload schema；不涉及 manifest 身份、能力或 epoch。 */
+export const parseViewPayloadSchemaV3 = (value) => {
+    if (!isRecord(value) || !hasExactKeys(value, ["type", "additional_properties", "properties", "max_bytes"])) {
+        return null;
+    }
+    if (value.type !== "object" || value.additional_properties !== false)
+        return null;
+    if (!isRecord(value.properties) || Object.keys(value.properties).length > MAX_SCHEMA_PROPERTIES)
+        return null;
+    if (!isPositiveSafeInteger(value.max_bytes) || value.max_bytes > MAX_PAYLOAD_BYTES)
+        return null;
+    for (const [key, property] of Object.entries(value.properties)) {
+        if (!STABLE_ID.test(key) || parseProperty(property) === null)
+            return null;
+    }
+    return value;
+};
+/** 仅校验 payload 是否符合已校验 schema；不涉及 event envelope 身份。 */
+export const viewPayloadMatchesSchemaV3 = (payload, schema) => {
+    const keys = Object.keys(payload);
+    if (keys.some((key) => !Object.hasOwn(schema.properties, key)))
+        return false;
+    for (const [key, property] of Object.entries(schema.properties)) {
+        if (property.required && !Object.hasOwn(payload, key))
+            return false;
+        if (!Object.hasOwn(payload, key))
+            continue;
+        const item = payload[key];
+        const matches = property.type === "null"
+            ? item === null
+            : property.type === "string"
+                ? typeof item === "string"
+                : property.type === "boolean"
+                    ? typeof item === "boolean"
+                    : property.type === "integer"
+                        ? typeof item === "number" && Number.isSafeInteger(item)
+                        : typeof item === "number" && Number.isFinite(item);
+        if (!matches || !isJsonValue(item))
+            return false;
+        if (property.enum !== undefined && !property.enum.some((candidate) => Object.is(candidate, item)))
+            return false;
+    }
+    return canonicalTmwBytes(payload).byteLength <= schema.max_bytes;
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@world-engines/tmw",
+  "private": false,
+  "version": "0.1.0-alpha.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./scene-state": {
+      "types": "./dist/scene-state.d.ts",
+      "import": "./dist/scene-state.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@world-engines/protocol-ts": "0.1.0-alpha.0",
+    "@world-engines/scenario-author-source": "0.1.0-alpha.0",
+    "@world-engines/spatial-authoring": "0.1.0-alpha.0",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "worldengine_source_sha256": "06d11db2ee456554759811314f133283599d3990f28a1a968453d68885453acf",
+  "worldengine_source_identity_provenance": {
+    "schema": "worldengine-public-namespace-projection/v1",
+    "kind": "composite-source-identity; namespace projection; not-full-source-recompile",
+    "original_name": "@chat/tmw",
+    "original_archive_sha256": "5fc6c8ab7d45f37f4d1d8197e0edd7c4b232b0dce346822712159aae736d14cd",
+    "original_source_sha256": "1272f256e0f4c2851625b1279d68c572bfc98f42a94002512b0445ba5a803078",
+    "projected_name": "@world-engines/tmw",
+    "package_name_mapping": {
+      "@chat/blocks-editor": "@world-engines/blocks-editor",
+      "@chat/ladybug-bridge": "@world-engines/ladybug-bridge",
+      "@chat/monaco-host": "@world-engines/monaco-host",
+      "@chat/protocol-ts": "@world-engines/protocol-ts",
+      "@chat/scenario-author-source": "@world-engines/scenario-author-source",
+      "@chat/scenario-review-snapshot": "@world-engines/scenario-review-snapshot",
+      "@chat/tmw": "@world-engines/tmw",
+      "@chat/view-exposure": "@world-engines/view-exposure",
+      "@world-engines/chatplay-vite-plugin": "@world-engines/chatplay-vite-plugin",
+      "@worldengine/agent-kit": "@world-engines/agent-kit",
+      "@worldengine/authoring-bridge": "@world-engines/authoring-bridge",
+      "@worldengine/authoring-ui": "@world-engines/authoring-ui",
+      "@worldengine/create-project": "@world-engines/create-project",
+      "@worldengine/project-format": "@world-engines/project-format",
+      "@worldengine/project-host": "@world-engines/project-host",
+      "@worldengine/project-setup": "@world-engines/project-setup",
+      "@worldengine/spatial-authoring": "@world-engines/spatial-authoring",
+      "@worldengine/view-sdk": "@world-engines/view-sdk"
+    }
+  }
+}