@adea-ai/spatial 0.69.10

package/dist/telemetry.d.ts

@@ -0,0 +1,106 @@
+export type SceneNavigationType = 'navigate' | 'push' | 'replace' | 'traverse' | 'scene-mount';
+export type ScenePerformanceReport = {
+    version: 1;
+    event: 'load' | 'runtime' | 'dispose' | 'error';
+    release?: string;
+    scene: string;
+    path: string;
+    navigation: {
+        id: string;
+        type: SceneNavigationType;
+        startTime: number;
+    };
+    milestones: {
+        firstRenderedFrameMs?: number;
+        playableCharacterMs?: number;
+        phasesMs: Record<string, number>;
+    };
+    network: {
+        requests: number;
+        networkRequests: number;
+        cacheHits: number;
+        unknownCacheStatus: number;
+        transferBytes: number;
+        encodedBodyBytes: number;
+        decodedBodyBytes: number;
+    };
+    runtime: {
+        sampleWindowMs: number;
+        frames: number;
+        fps?: number;
+        p50FrameMs?: number;
+        p95FrameMs?: number;
+        longestFrameMs?: number;
+        p95FrameIntervalMs?: number;
+        longestFrameIntervalMs?: number;
+        longTasks: number;
+        longTaskDurationMs: number;
+        drawCalls?: number;
+        drawCallsP95?: number;
+        drawCallsMax?: number;
+        triangles?: number;
+        geometries?: number;
+        textures?: number;
+        programs?: number;
+        reactCommits?: number;
+        reactCommitDurationMs?: number;
+        reactMaxCommitMs?: number;
+    };
+    renderables: SceneRuntimeStats;
+    lifecycle: {
+        disposedGeometries: number;
+        disposedMaterials: number;
+        disposedTextures: number;
+    };
+    device: {
+        tier: 'high' | 'standard' | 'low';
+        mobile: boolean;
+        devicePixelRatio: number;
+        hardwareConcurrency: number;
+        deviceMemoryGb?: number;
+        webglVersion: string;
+        gpu?: string;
+        maxTextureSize?: number;
+    };
+    error?: string;
+};
+export type SceneRuntimeStats = {
+    meshes: number;
+    visibleMeshes: number;
+    frustumCulledMeshes: number;
+    materials: number;
+    instancedMeshes: number;
+    instances: number;
+    foliageMeshes: number;
+    foliageInstances: number;
+    fenceMeshes: number;
+    fenceInstances: number;
+    repeatedGeometryGroups: number;
+    repeatedGeometryInstances: number;
+};
+export declare const SCENE_TELEMETRY_LOG_PREFIX = "[scene-telemetry] ";
+export declare const MAX_SCENE_TELEMETRY_BYTES: number;
+export type SceneTelemetryEnvelope = {
+    receivedAt: string;
+    deployment?: string;
+    report: ScenePerformanceReport;
+};
+export declare function parseScenePerformanceReport(value: unknown): ScenePerformanceReport | null;
+export declare function createSceneTelemetryEnvelope(report: ScenePerformanceReport, receivedAt?: Date, deployment?: string | undefined): SceneTelemetryEnvelope;
+type NavigationStart = {
+    id: string;
+    url: string;
+    startTime: number;
+    type: 'navigate' | 'push' | 'replace' | 'traverse';
+    claimed?: boolean;
+};
+declare global {
+    interface Window {
+        __ADEA_NAVIGATION_START__?: NavigationStart;
+        __ADEA_SCENE_TELEMETRY_ENDPOINT__?: string;
+        __ADEA_RELEASE__?: string;
+    }
+}
+export declare function recordNavigation(url: string, type: 'navigate' | 'push' | 'replace' | 'traverse', startTime: number): void;
+export declare function onRouterTransitionStart(url: string, navigationType: 'push' | 'replace' | 'traverse'): void;
+export {};

package/dist/telemetry.js

@@ -0,0 +1,79 @@
+export const SCENE_TELEMETRY_LOG_PREFIX = '[scene-telemetry] ';
+export const MAX_SCENE_TELEMETRY_BYTES = 64 * 1024;
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function validReport(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.version !== 1 || !['load', 'runtime', 'dispose', 'error'].includes(String(value.event)))
+        return false;
+    if (typeof value.scene !== 'string' || value.scene.length < 1 || value.scene.length > 80)
+        return false;
+    if (typeof value.path !== 'string' || value.path.length < 1 || value.path.length > 256)
+        return false;
+    if (value.release != null && (typeof value.release !== 'string' || value.release.length > 128))
+        return false;
+    if (!isRecord(value.navigation) ||
+        typeof value.navigation.id !== 'string' ||
+        !isFiniteNumber(value.navigation.startTime))
+        return false;
+    if (!isRecord(value.milestones) || !isRecord(value.milestones.phasesMs))
+        return false;
+    if (!isRecord(value.network) ||
+        !isFiniteNumber(value.network.requests) ||
+        !isFiniteNumber(value.network.transferBytes))
+        return false;
+    if (!isRecord(value.runtime) ||
+        !isFiniteNumber(value.runtime.sampleWindowMs) ||
+        !isFiniteNumber(value.runtime.frames))
+        return false;
+    if (!isRecord(value.device) || !['high', 'standard', 'low'].includes(String(value.device.tier)))
+        return false;
+    if (typeof value.device.mobile !== 'boolean' || !isFiniteNumber(value.device.devicePixelRatio))
+        return false;
+    return true;
+}
+export function parseScenePerformanceReport(value) {
+    return validReport(value) ? value : null;
+}
+export function createSceneTelemetryEnvelope(report, receivedAt = new Date(), deployment = process.env.DEPLOY_GIT_COMMIT_SHA) {
+    return {
+        receivedAt: receivedAt.toISOString(),
+        ...(deployment ? { deployment } : {}),
+        report,
+    };
+}
+export function recordNavigation(url, type, startTime) {
+    window.__ADEA_NAVIGATION_START__ = {
+        id: `nav-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        url,
+        startTime,
+        type,
+    };
+}
+try {
+    const navigation = performance.getEntriesByType('navigation')[0];
+    recordNavigation(window.location.href, 'navigate', navigation?.startTime ?? 0);
+    const endpoint = process.env.ADEA_PUBLIC_SCENE_TELEMETRY_ENDPOINT ||
+        (process.env.NODE_ENV === 'production' ? '/api/telemetry/scene-performance' : undefined);
+    if (endpoint)
+        window.__ADEA_SCENE_TELEMETRY_ENDPOINT__ = endpoint;
+    const release = process.env.ADEA_PUBLIC_DEPLOY_GIT_COMMIT_SHA;
+    if (release)
+        window.__ADEA_RELEASE__ = release;
+}
+catch {
+    // Telemetry must never interfere with page initialization.
+}
+export function onRouterTransitionStart(url, navigationType) {
+    try {
+        recordNavigation(new URL(url, window.location.href).href, navigationType, performance.now());
+    }
+    catch {
+        // Invalid route metadata should not affect navigation.
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@adea-ai/spatial",
+  "version": "0.69.10",
+  "description": "Scene and asset manifest contracts plus the shell-to-engine spatial protocol for Adea workspaces: scene mount manifests, spawn URL helpers, and scene telemetry schemas. Pure types — no rendering, no binaries.",
+  "keywords": [
+    "assets",
+    "manifest",
+    "protocol",
+    "scene",
+    "spatial",
+    "telemetry",
+    "threejs",
+    "workspace"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adea-ai/adea.git",
+    "directory": "packages/spatial"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "lint": "oxlint",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "test": "bun test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/asset-manifests.ts

@@ -0,0 +1,95 @@
+export type SceneAvailability = 'ready' | 'planned'
+
+export type SceneZone = {
+  id: string
+  assetUrl: string
+  /** Optional collision layer that follows this visual zone. */
+  collisionAssetUrl?: string
+  /** Additional visual layers that load and unload with this zone. */
+  assetUrls?: readonly string[]
+  /** Exact-triangle field colliders that load and unload with this zone. */
+  collisionAssetUrls?: readonly string[]
+  preload?: boolean
+  /** Load the zone automatically when the player enters this radius. */
+  preloadDistance?: number
+  /** Optional transform for a model authored in local building space. */
+  transform?: {
+    position?: readonly [number, number, number]
+    quaternion?: readonly [number, number, number, number]
+    scale?: readonly [number, number, number]
+  }
+}
+
+export type SceneStartPosition = {
+  x: number
+  y: number
+  z: number
+  yaw?: number
+  pitch?: number
+  /** Keep an authored start height instead of snapping to the first ray hit. */
+  snapToGround?: boolean
+}
+
+export type StaticFieldAssetUrls = {
+  foliage?: string
+  props?: string
+}
+
+export type AssignedPropManifestPlacement = {
+  id?: string
+  p?: readonly [number, number, number]
+  q?: readonly [number, number, number, number]
+  s?: readonly [number, number, number]
+  footprint?: readonly [number, number]
+}
+
+export type AssignedPropManifestAsset = {
+  assetUrl: string
+  defaultScale: number
+  footprint?: readonly [number, number]
+  placementSurface?: 'floor' | 'wall'
+  wallMountHeight?: number
+  floorLift?: number
+  placeableOnTop?: boolean
+}
+
+/** Runtime-only room content for props already assigned to a scene. */
+export type AssignedPropsManifest = {
+  version?: number
+  scene?: string
+  assets: Record<string, AssignedPropManifestAsset>
+  placements: Record<string, AssignedPropManifestPlacement[]>
+}
+
+export type SceneManifest = {
+  id: string
+  label: string
+  availability?: SceneAvailability
+  entryAssetUrl: string
+  /** Optional id for making the initially loaded asset unloadable as a zone. */
+  entryZoneId?: string
+  /** Keep the entry collision layer active while visual zones transition. */
+  preserveEntryCollision?: boolean
+  collisionAssetUrl?: string
+  /** Additional collision layers kept active for multi-level scenes. */
+  additionalCollisionAssetUrls?: readonly string[]
+  additionalAssetUrls?: readonly string[]
+  zones?: SceneZone[]
+  startPosition?: SceneStartPosition
+  /** Build-generated instanced fields for static scenes (preferred over runtime manifests). */
+  staticFieldAssetUrls?: StaticFieldAssetUrls
+  /** Render-free exact-triangle companions for the generated static fields. */
+  staticFieldCollisionAssetUrls?: StaticFieldAssetUrls
+  /** Optional foliage placement manifest (instanced from the foliage catalog at runtime). */
+  foliageManifestUrl?: string
+  /** Optional props placement manifest (instanced from the props catalog at runtime). */
+  propsManifestUrl?: string
+  /** Runtime-only manifest for props explicitly assigned to this workspace. */
+  assignedPropsManifestUrl?: string
+  /** Public URL for persisted authored-object editor overrides. */
+  editorOverridesUrl?: string
+  /** Optional repository-relative source path for persisted overrides. */
+  editorOverridesSourcePath?: string
+  /** Optional repository-relative public copy path for persisted overrides. */
+  editorOverridesPublicPath?: string
+}

package/src/engine.ts

@@ -0,0 +1,97 @@
+/**
+ * Entitlement gate and loading contract for the Agent Sim engine.
+ *
+ * The engine (models, textures, audio, runtime code) lives in the private
+ * agent-sim repo and never ships in this public one. The shell may only
+ * resolve the engine remote when the deployment is entitled to it:
+ *
+ * - Web: the site is served from an official Adea domain (adea.dev /
+ *   adea.io, including subdomains). Forked deployments on other origins
+ *   are refused before any engine fetch happens.
+ * - Desktop / any build: an official build packs the engine into its own
+ *   assets at build time (see scripts/pack-agent-sim.mjs, wired into the
+ *   release lanes). The pack writes a manifest at a well-known same-origin
+ *   URL; plain checkouts and fork builds simply do not have it.
+ *
+ * Both signals are checked; the engine is fetched only when both pass, so
+ * copying engine assets into a forked website still fails the host gate.
+ */
+
+export const OFFICIAL_AGENT_SIM_WEB_HOSTS = ['adea.dev', 'adea.io'] as const
+
+/** Known-public hostname suffixes never treated as official even if they embed an official host. */
+const NON_OFFICIAL_SUFFIXES = ['.local', '.localhost', '.internal']
+const OFFICIAL_LOCAL_HOSTS = ['localhost', '127.0.0.1', '[::1]']
+
+export type AgentSimWebPlatform = 'web' | 'desktop'
+
+export type AgentSimEngineManifest = {
+  /**
+   * Same-origin ES module URL of the engine entry. The entry must register
+   * the `window.__adeaAgentSim` mount API documented in the package README
+   * before its load event resolves.
+   */
+  entryUrl: string
+  /** Engine pack version (agent-sim repo release). Diagnostics only. */
+  version: string
+}
+
+/** Well-known same-origin URL the official pack lane writes the manifest to. */
+export function agentSimEngineManifestUrl(origin: string): string {
+  return new URL('/assets/agent-sim/engine.json', origin).toString()
+}
+
+/**
+ * Parse and validate an engine manifest fetched from a trusted origin.
+ * Rejects payloads that would point the loader off the deployment's own
+ * origin — the engine ships with the site, never from third parties.
+ */
+export function parseAgentSimEngineManifest(
+  value: unknown,
+  origin: string
+): { ok: true; manifest: AgentSimEngineManifest } | { ok: false } {
+  if (typeof value !== 'object' || value === null) return { ok: false }
+  const entryUrl = (value as { engine?: { entryUrl?: unknown } }).engine?.entryUrl
+  const version = (value as { engine?: { version?: unknown } }).engine?.version
+  if (typeof entryUrl !== 'string' || entryUrl.length === 0) return { ok: false }
+  if (typeof version !== 'string' || version.length === 0) return { ok: false }
+  let resolved: URL
+  try {
+    resolved = new URL(entryUrl, origin)
+  } catch {
+    return { ok: false }
+  }
+  if (resolved.origin !== new URL(origin).origin) return { ok: false }
+  if (!resolved.pathname.endsWith('.js')) return { ok: false }
+  return { ok: true, manifest: { entryUrl: resolved.toString(), version } }
+}
+
+/**
+ * Whether a web origin is an official Adea deployment allowed to resolve the
+ * Agent Sim engine remote. Desktop builds skip this check: they are gated by
+ * the packed engine manifest instead.
+ */
+export function isOfficialAgentSimWebOrigin(origin: string): boolean {
+  let url: URL
+  try {
+    url = new URL(origin)
+  } catch {
+    return false
+  }
+  if (url.protocol !== 'https:') return false
+  const host = url.hostname.toLowerCase()
+  if (NON_OFFICIAL_SUFFIXES.some((suffix) => host.endsWith(suffix))) return false
+  return OFFICIAL_AGENT_SIM_WEB_HOSTS.some(
+    (official) => host === official || host.endsWith(`.${official}`)
+  )
+}
+
+/**
+ * Hosts where a developer runs the shell locally. Local development is
+ * entitled only when the engine was explicitly packed into the local build
+ * (engine manifest present); the host check alone never entitles it.
+ */
+export function isLocalDevHost(hostname: string): boolean {
+  const host = hostname.toLowerCase()
+  return OFFICIAL_LOCAL_HOSTS.includes(host) || host.endsWith('.localhost')
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+export * from './asset-manifests'
+export {
+  agentSimEngineManifestUrl,
+  isLocalDevHost,
+  isOfficialAgentSimWebOrigin,
+  parseAgentSimEngineManifest,
+  OFFICIAL_AGENT_SIM_WEB_HOSTS,
+  type AgentSimEngineManifest,
+} from './engine'
+export { hqHomeManifest, hqWorkManifest } from './manifests'
+export {
+  appRouteHref,
+  encodeSceneStartPosition,
+  portalNavigationHref,
+  readSceneStartPosition,
+  type PortalNavigation,
+  type SceneApp,
+} from './scene-spawn'
+export {
+  createSceneTelemetryEnvelope,
+  MAX_SCENE_TELEMETRY_BYTES,
+  onRouterTransitionStart,
+  parseScenePerformanceReport,
+  recordNavigation,
+  SCENE_TELEMETRY_LOG_PREFIX,
+  type SceneNavigationType,
+  type ScenePerformanceReport,
+  type SceneRuntimeStats,
+  type SceneTelemetryEnvelope,
+} from './telemetry'
+export const configurableCharacterId = 'configurable'
+export const DEFAULT_CHARACTER_ID = configurableCharacterId
+
+/**
+ * Shell-side character param check. The engine validates against its
+ * reference/preset catalogs on mount; the shell only needs a plausible
+ * non-empty value to thread through.
+ */
+export function isPlausibleCharacterId(value: string | undefined): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= 128
+}

package/src/manifests.ts

@@ -0,0 +1,41 @@
+import type { SceneManifest } from './asset-manifests'
+
+// Scene ids mirror @adea-ai/app-core's HqSceneId, which remains the canonical
+// shell-side scene identity. This package only carries mount constants.
+type HqSceneId = 'home' | 'work'
+
+type HqSceneConfig = {
+  label: string
+  floorVersion: number
+  foliageVersion: number
+}
+
+const sceneConfig = {
+  home: { label: 'Home', floorVersion: 20, foliageVersion: 10 },
+  work: { label: 'Work', floorVersion: 21, foliageVersion: 11 },
+} as const satisfies Record<HqSceneId, HqSceneConfig>
+
+// Start height mirrors the engine's ROOM_GALLERY_FOUNDATION_TOP_Y (slab base 0
+// + height 6) plus the authored 135-unit lift. The engine's room-config is
+// the simulation source of truth; this package carries the mount constants
+// the shell needs without depending on engine code.
+const START_Y = 6 + 135
+
+function createHqManifest(scene: HqSceneId): SceneManifest {
+  const { label, floorVersion, foliageVersion } = sceneConfig[scene]
+  const sceneId = `hq-${scene}`
+  return {
+    id: sceneId,
+    label,
+    availability: 'ready',
+    entryAssetUrl: `/assets/worlds/${sceneId}/floor.glb?v=${floorVersion}`,
+    collisionAssetUrl: `/assets/worlds/${sceneId}/floor-collision.glb?v=${floorVersion}`,
+    foliageManifestUrl: `/assets/worlds/${sceneId}/foliage.json?v=${foliageVersion}`,
+    assignedPropsManifestUrl: `/assets/worlds/${sceneId}/props-runtime.json?v=room-layout`,
+    zones: [],
+    startPosition: { x: 0, y: START_Y, z: 0, yaw: 0, pitch: -0.2 },
+  }
+}
+
+export const hqHomeManifest = createHqManifest('home')
+export const hqWorkManifest = createHqManifest('work')

package/src/scene-spawn.ts

@@ -0,0 +1,107 @@
+import type { SceneStartPosition } from './asset-manifests'
+
+export type SceneApp = 'world' | 'hq'
+
+const SPAWN_QUERY_KEY = 'spawn'
+const APP_DEV_PORTS: Record<SceneApp, string> = { world: '3000', hq: '3004' }
+const APP_PORTLESS_URLS: Record<SceneApp, string> = {
+  world: 'https://world.localhost',
+  hq: 'https://adea.localhost',
+}
+
+function firstValue(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value
+}
+
+function finiteNumber(value: string | undefined): number | undefined {
+  if (!value) return undefined
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+/** Encode a scene start position for a cross-app navigation URL. */
+export function encodeSceneStartPosition(position: SceneStartPosition): string {
+  return [
+    position.x,
+    position.y,
+    position.z,
+    position.yaw ?? '',
+    position.pitch ?? '',
+    position.snapToGround == null ? '' : position.snapToGround ? '1' : '0',
+  ].join(',')
+}
+
+/** Parse a validated scene start position from a route's `spawn` query. */
+export function readSceneStartPosition(
+  value: string | string[] | undefined
+): SceneStartPosition | undefined {
+  const parts = firstValue(value)?.split(',')
+  if (!parts || parts.length < 3 || parts.length > 6) return undefined
+  const x = finiteNumber(parts[0])
+  const y = finiteNumber(parts[1])
+  const z = finiteNumber(parts[2])
+  if (x == null || y == null || z == null) return undefined
+  const yaw = finiteNumber(parts[3])
+  const pitch = finiteNumber(parts[4])
+  const snap = parts[5]
+  if (parts[3] && yaw == null) return undefined
+  if (parts[4] && pitch == null) return undefined
+  if (snap && snap !== '0' && snap !== '1') return undefined
+  return {
+    x,
+    y,
+    z,
+    ...(yaw == null ? {} : { yaw }),
+    ...(pitch == null ? {} : { pitch }),
+    ...(snap === '0' ? { snapToGround: false } : snap === '1' ? { snapToGround: true } : {}),
+  }
+}
+
+function configuredAppBase(app: SceneApp): string | undefined {
+  const configured =
+    app === 'world' ? process.env.ADEA_PUBLIC_WORLD_URL : process.env.ADEA_PUBLIC_HQ_URL
+  return configured?.trim() || undefined
+}
+
+function isDevelopmentHost(hostname: string): boolean {
+  return (
+    hostname === 'localhost' ||
+    hostname === '127.0.0.1' ||
+    hostname === '0.0.0.0' ||
+    hostname === 'amf-mb-pro' ||
+    hostname.endsWith('.localhost') ||
+    hostname.endsWith('.ts.net')
+  )
+}
+
+/** Resolve a route for the sibling World or HQ app in dev and production. */
+export function appRouteHref(app: SceneApp, path: string, currentHref?: string): string {
+  const current = new URL(currentHref ?? window.location.href)
+  const configuredBase = configuredAppBase(app)
+  const isPortlessHost = current.hostname.endsWith('.localhost')
+  const target = new URL(
+    path,
+    configuredBase ?? (isPortlessHost ? APP_PORTLESS_URLS[app] : current.origin)
+  )
+  if (!configuredBase && !isPortlessHost && isDevelopmentHost(current.hostname)) {
+    target.port = APP_DEV_PORTS[app]
+  }
+  return target.toString()
+}
+
+export type PortalNavigation = {
+  app: SceneApp
+  path: string
+  spawn?: SceneStartPosition
+}
+
+/** Build a portal URL while carrying the selected character and target spawn. */
+export function portalNavigationHref(navigation: PortalNavigation, currentHref?: string): string {
+  const current = new URL(currentHref ?? window.location.href)
+  const target = new URL(appRouteHref(navigation.app, navigation.path, current.toString()))
+  const character = current.searchParams.get('character')
+  if (character) target.searchParams.set('character', character)
+  if (navigation.spawn)
+    target.searchParams.set(SPAWN_QUERY_KEY, encodeSceneStartPosition(navigation.spawn))
+  return target.toString()
+}