@hypersoniclabs/helix-manifest

The HELIX Instant world manifest schema and validator — the single source of truth for bundle validation, shared by every component that touches a world bundle:

• the backend (helix-backend-api Instant World module) validates manifests at publish and finalize,
• the CLI (helix-creator-cli) validates a bundle before upload,
• the SDK (helix-web-sdk) consumes the manifest types,
• and the MCP agent tooling validates what it generates.

Because all of them import the same validateManifest / validatePackageEnvelope, the rules can never drift between client and server.

Install

npm install @hypersoniclabs/helix-manifest

Usage

import { validateManifest, BUNDLE_MAX_TOTAL_BYTES, bundleContentType } from '@hypersoniclabs/helix-manifest';

const result = validateManifest(JSON.parse(helixJson));
if (!result.valid) throw new Error(result.errors.join('; '));
const manifest = result.manifest; // NormalizedHelixManifest — defaults applied

Exports

• validateManifest(data) / parseManifest(json) — validate + normalize a world helix.json (v0.1–v0.3).
• validatePackageEnvelope(data) / parsePackageEnvelope(json) — validate the system | ability | asset-pack | interactable envelope.
• validateInteractablePackageManifest(data) / validateInteractableServerFragment(data) — validate a portable interactable manifest, run its authority fragment through the world grammar, and recompute its budget.
• validatePlatformRuntimeDelivery({ descriptor, manifestSystems, entryHtml }) — the shared CLI/server gate for system-bearing World builds. It accepts safe compatible ^/~ ranges or explicit exact pins, requires the built import map to match, and rejects legacy bundled delivery.
• validateSceneDocument(data, options?) / parseSceneDocument(json, options?) — validate and normalize a portable HELIX Scene v2 document shared by Home and World profiles.
• validateSceneDocumentForPublication(data, options) — the publication-safe gate whose type requires an Ed25519 implementation-signature verifier.
• normalizeSceneDocument(scene) — return a detached, defaulted copy of an already validated Scene v2 document.
• canonicalSceneDocumentPayload(scene) / computeSceneDocumentIntegrity(scene) / verifySceneDocumentIntegrity(scene) — RFC 8785 canonical payload and SHA-256 identity helpers; only the top-level self field is excluded.
• Scene vocabulary: HELIX_SCENE_FORMAT, HELIX_SCENE_VERSION, HELIX_SCENE_MEDIA_TYPE, HELIX_SCENE_CAPS, behavior/runtime-extension/signing-key allow-lists, sceneResourceMimeCompatible, sceneBundleUriMatchesResource, sceneProfileMemoryCommitmentMiB, behaviorImplementationSignaturePayload, HELIX_TO_UNREAL_ADAPTER, and helixPositionToUnrealCm(position).
• Bundle rules: BUNDLE_MAX_FILES, BUNDLE_MAX_FILE_BYTES, BUNDLE_MAX_TOTAL_BYTES, BUNDLE_PATH_PATTERN, bundleContentType(path), bundleLimitsForKind(kind), classifyBundleFile(kind, path), ASSET_EXTENSIONS.
• Vocabulary + federation maps: BUNDLE_KINDS, MAIN_BACKEND_PACKAGE_TYPE, MAIN_BACKEND_CONTENT_RATING, PERMISSIONS_V01, PERMISSIONS_V03, PLATFORM_MAX_PLAYERS_PER_ROOM, MANIFEST_FILENAME, MANIFEST_VERSIONS.
• Types: HelixManifest, NormalizedHelixManifest, HelixBundleKind, HelixContentRating, HelixPermission, HelixMultiplayerConfig, HelixPackageEnvelope, NormalizedPackageEnvelope, HelixScenePin, HelixSceneV2, and the exported Scene v2 section types.

HELIX Scene v2

Scene v2 is the portable content contract for both Homes and Worlds. A Home is a home profile plus residence-owned instance state; it is not a separate rendering format. Scene JSON contains immutable resource handles, stable nodes, physical lighting intent, surfaces, collision/navigation, streaming/LOD and registered declarative behavior. It never contains executable code or arbitrary remote URLs.

See the creator contract and the dual-profile example. The published JSON Schema is schema/scene-v2.schema.json.

Module bank references

A module-v1 world names the interactables it hosts as itx:<slug>@<version>#<sha256> references. The digest is the package registry's published checksumSha256 for that version — read, never computed.

See the module bank reference contract.

Develop

npm install
npm test       # jest
npm run build  # tsc → dist/
npm run lint

The JSON schemas live in schema/ and are bundled into the published package alongside the compiled dist/.