@hypersoniclabs/helix-sdk 0.1.2 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (115) hide show
  1. package/README.md +859 -8
  2. package/dist/action-surface.d.ts +182 -0
  3. package/dist/action-surface.js +1032 -0
  4. package/dist/action-surface.js.map +1 -0
  5. package/dist/camera.d.ts +65 -1
  6. package/dist/camera.js +568 -0
  7. package/dist/camera.js.map +1 -1
  8. package/dist/dev-shell/criteria.d.ts +46 -0
  9. package/dist/dev-shell/criteria.js +98 -0
  10. package/dist/dev-shell/criteria.js.map +1 -0
  11. package/dist/dev-shell/index.d.ts +189 -0
  12. package/dist/dev-shell/index.js +287 -0
  13. package/dist/dev-shell/index.js.map +1 -0
  14. package/dist/dev-shell/keys.d.ts +14 -0
  15. package/dist/dev-shell/keys.js +78 -0
  16. package/dist/dev-shell/keys.js.map +1 -0
  17. package/dist/dev-shell/simulator.d.ts +436 -0
  18. package/dist/dev-shell/simulator.js +1634 -0
  19. package/dist/dev-shell/simulator.js.map +1 -0
  20. package/dist/dev-shell/state.d.ts +148 -0
  21. package/dist/dev-shell/state.js +196 -0
  22. package/dist/dev-shell/state.js.map +1 -0
  23. package/dist/device-definition-resolver.d.ts +34 -0
  24. package/dist/device-definition-resolver.js +172 -0
  25. package/dist/device-definition-resolver.js.map +1 -0
  26. package/dist/device-trial.d.ts +3 -0
  27. package/dist/device-trial.js +132 -0
  28. package/dist/device-trial.js.map +1 -0
  29. package/dist/devices.d.ts +228 -0
  30. package/dist/devices.js +198 -0
  31. package/dist/devices.js.map +1 -0
  32. package/dist/dreamerAudio.d.ts +126 -0
  33. package/dist/dreamerAudio.js +135 -0
  34. package/dist/dreamerAudio.js.map +1 -0
  35. package/dist/generated/runtime-contract.d.ts +15529 -0
  36. package/dist/generated/runtime-contract.js +20470 -0
  37. package/dist/generated/runtime-contract.js.map +1 -0
  38. package/dist/index.d.ts +272 -15
  39. package/dist/index.js +1401 -91
  40. package/dist/index.js.map +1 -1
  41. package/dist/interaction-mode.d.ts +172 -0
  42. package/dist/interaction-mode.js +553 -0
  43. package/dist/interaction-mode.js.map +1 -0
  44. package/dist/internal/avatar-pose.d.ts +25 -0
  45. package/dist/internal/avatar-pose.js +46 -0
  46. package/dist/internal/avatar-pose.js.map +1 -0
  47. package/dist/internal/keyed-collection.d.ts +2 -0
  48. package/dist/internal/keyed-collection.js +12 -0
  49. package/dist/internal/keyed-collection.js.map +1 -0
  50. package/dist/internal/vehicle-detach-action.d.ts +2 -0
  51. package/dist/internal/vehicle-detach-action.js +6 -0
  52. package/dist/internal/vehicle-detach-action.js.map +1 -0
  53. package/dist/matchmaking.d.ts +433 -0
  54. package/dist/matchmaking.js +1487 -0
  55. package/dist/matchmaking.js.map +1 -0
  56. package/dist/materials.d.ts +122 -0
  57. package/dist/materials.js +217 -0
  58. package/dist/materials.js.map +1 -0
  59. package/dist/multiplayer-accessors.d.ts +100 -0
  60. package/dist/multiplayer-accessors.js +200 -0
  61. package/dist/multiplayer-accessors.js.map +1 -0
  62. package/dist/multiplayer-contract/avatar-pose.d.ts +112 -0
  63. package/dist/multiplayer-contract/avatar-pose.js +250 -0
  64. package/dist/multiplayer-contract/avatar-pose.js.map +1 -0
  65. package/dist/multiplayer-contract/credential.d.ts +38 -0
  66. package/dist/multiplayer-contract/final-rest.d.ts +66 -0
  67. package/dist/multiplayer-contract/final-rest.js +38 -0
  68. package/dist/multiplayer-contract/final-rest.js.map +1 -0
  69. package/dist/multiplayer-contract/index.d.ts +11 -5
  70. package/dist/multiplayer-contract/index.js +16 -5
  71. package/dist/multiplayer-contract/index.js.map +1 -1
  72. package/dist/multiplayer-contract/messages.d.ts +461 -14
  73. package/dist/multiplayer-contract/messages.js +141 -15
  74. package/dist/multiplayer-contract/messages.js.map +1 -1
  75. package/dist/multiplayer-contract/room.d.ts +55 -4
  76. package/dist/multiplayer-contract/state.d.ts +181 -1
  77. package/dist/multiplayer-contract/state.js.map +1 -1
  78. package/dist/multiplayer-final-rest.d.ts +32 -0
  79. package/dist/multiplayer-final-rest.js +217 -0
  80. package/dist/multiplayer-final-rest.js.map +1 -0
  81. package/dist/multiplayer.d.ts +507 -16
  82. package/dist/multiplayer.js +2242 -73
  83. package/dist/multiplayer.js.map +1 -1
  84. package/dist/package.json +3 -0
  85. package/dist/protocol.d.ts +668 -5
  86. package/dist/protocol.js +101 -1
  87. package/dist/protocol.js.map +1 -1
  88. package/dist/runtime-contract/index.d.ts +15 -0
  89. package/dist/runtime-contract/index.js +12 -0
  90. package/dist/runtime-contract/index.js.map +1 -0
  91. package/dist/server-clock.d.ts +25 -0
  92. package/dist/server-clock.js +88 -0
  93. package/dist/server-clock.js.map +1 -0
  94. package/dist/tsconfig.build.tsbuildinfo +1 -1
  95. package/dist/universal-vehicles.d.ts +111 -0
  96. package/dist/universal-vehicles.js +2 -0
  97. package/dist/universal-vehicles.js.map +1 -0
  98. package/dist/vault.d.ts +562 -0
  99. package/dist/vault.js +365 -0
  100. package/dist/vault.js.map +1 -0
  101. package/dist/vehicle-specialty-placement.d.ts +28 -0
  102. package/dist/vehicle-specialty-placement.js +154 -0
  103. package/dist/vehicle-specialty-placement.js.map +1 -0
  104. package/dist/vehicle-specialty-transport.d.ts +78 -0
  105. package/dist/vehicle-specialty-transport.js +183 -0
  106. package/dist/vehicle-specialty-transport.js.map +1 -0
  107. package/dist/voice.d.ts +229 -0
  108. package/dist/voice.js +1348 -0
  109. package/dist/voice.js.map +1 -0
  110. package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
  111. package/generated/runtime-contract/known-answer.json +20471 -0
  112. package/generated/runtime-contract/known-answer.schema.json +630 -0
  113. package/generated/runtime-contract/runtime-contract.schema.json +607 -0
  114. package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
  115. package/package.json +32 -6
@@ -0,0 +1,172 @@
1
+ /** Validate, clone, and freeze the checksum-bound authored projection without resolving it. */
2
+ export function normalizeSealedDeviceDefinitionProjection(value) {
3
+ try {
4
+ assertProjectionEnvelope(value);
5
+ const projection = value;
6
+ const canonical = canonicalJson(projection.definition);
7
+ const definition = JSON.parse(canonical);
8
+ if (definition.format !== 'helix.device' ||
9
+ definition.formatVersion !== 1 ||
10
+ typeof definition.id !== 'string' ||
11
+ definition.id.length === 0 ||
12
+ typeof definition.version !== 'string' ||
13
+ definition.version.length === 0) {
14
+ return null;
15
+ }
16
+ return deepFreeze({
17
+ definition,
18
+ definitionChecksumSha256: projection.definitionChecksumSha256.toLowerCase(),
19
+ expiresAtEpochSeconds: projection.expiresAtEpochSeconds,
20
+ pin: {
21
+ packageId: projection.pin.packageId,
22
+ version: projection.pin.version,
23
+ manifestCid: projection.pin.manifestCid,
24
+ },
25
+ });
26
+ }
27
+ catch {
28
+ return null;
29
+ }
30
+ }
31
+ const CONTINUUM_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
32
+ const CONTINUUM_CID = /^cid:sha256:[a-f0-9]{64}$/;
33
+ const SHA256_HEX = /^[a-f0-9]{64}$/i;
34
+ /**
35
+ * Adapt a single server-sealed trial projection to WorldDeviceHost.
36
+ *
37
+ * This never resolves inventory, follows mutable package aliases, fetches
38
+ * source, or converts room IR back into an authored Device definition.
39
+ */
40
+ export function createSealedDeviceDefinitionResolver(projection, options = {}) {
41
+ assertProjectionEnvelope(projection);
42
+ const normalized = normalizeSealedDeviceDefinitionProjection(projection);
43
+ if (normalized === null)
44
+ throw new Error('Sealed Device definition is invalid');
45
+ // Snapshot before the caller can mutate the response object. The canonical
46
+ // bytes are also the exact checksum input shared with the backend.
47
+ const canonical = canonicalJson(normalized.definition);
48
+ const definition = normalized.definition;
49
+ const expectedChecksum = normalized.definitionChecksumSha256;
50
+ const expiresAtMs = normalized.expiresAtEpochSeconds * 1_000;
51
+ const now = options.now ?? Date.now;
52
+ const sha256 = options.sha256 ?? defaultSha256;
53
+ let disposed = false;
54
+ let validated;
55
+ const resolver = (async (reference) => {
56
+ assertActive(disposed, expiresAtMs, now);
57
+ assertDefinitionIdentity(definition, reference);
58
+ validated ??= (async () => {
59
+ const bytes = new TextEncoder().encode(canonical);
60
+ const actualChecksum = (await sha256(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength))).toLowerCase();
61
+ if (!SHA256_HEX.test(actualChecksum) ||
62
+ actualChecksum !== expectedChecksum) {
63
+ throw new Error('Sealed Device definition checksum mismatch');
64
+ }
65
+ assertDefinitionIdentity(definition, reference);
66
+ if (definition.compatibility !== undefined &&
67
+ (!Array.isArray(definition.compatibility?.hosts) ||
68
+ !definition.compatibility.hosts.includes('world'))) {
69
+ throw new Error(`Device ${definition.id} does not support World hosts`);
70
+ }
71
+ if (!definition.state ||
72
+ typeof definition.state !== 'object' ||
73
+ Array.isArray(definition.state) ||
74
+ !Array.isArray(definition.interactions)) {
75
+ throw new Error('Sealed Device definition structure is invalid');
76
+ }
77
+ return definition;
78
+ })();
79
+ const result = await validated;
80
+ assertActive(disposed, expiresAtMs, now);
81
+ return result;
82
+ });
83
+ resolver.dispose = () => {
84
+ disposed = true;
85
+ validated = undefined;
86
+ };
87
+ return resolver;
88
+ }
89
+ function assertProjectionEnvelope(projection) {
90
+ if (!projection ||
91
+ !projection.definition ||
92
+ typeof projection.definition !== 'object' ||
93
+ Array.isArray(projection.definition)) {
94
+ throw new Error('Sealed Device definition is invalid');
95
+ }
96
+ if (!projection.pin ||
97
+ typeof projection.pin.packageId !== 'string' ||
98
+ !CONTINUUM_UUID.test(projection.pin.packageId) ||
99
+ typeof projection.pin.version !== 'string' ||
100
+ projection.pin.version.length === 0 ||
101
+ projection.pin.version.length > 64 ||
102
+ typeof projection.pin.manifestCid !== 'string' ||
103
+ !CONTINUUM_CID.test(projection.pin.manifestCid)) {
104
+ throw new Error('Sealed Device definition pin is invalid');
105
+ }
106
+ if (typeof projection.definitionChecksumSha256 !== 'string' ||
107
+ !SHA256_HEX.test(projection.definitionChecksumSha256)) {
108
+ throw new Error('Sealed Device definition checksum is invalid');
109
+ }
110
+ if (!Number.isSafeInteger(projection.expiresAtEpochSeconds) ||
111
+ projection.expiresAtEpochSeconds <= 0 ||
112
+ projection.expiresAtEpochSeconds > Number.MAX_SAFE_INTEGER / 1_000) {
113
+ throw new Error('Sealed Device definition expiry is invalid');
114
+ }
115
+ }
116
+ function assertActive(disposed, expiresAtMs, now) {
117
+ if (disposed)
118
+ throw new Error('Sealed Device definition resolver is disposed');
119
+ if (now() >= expiresAtMs) {
120
+ throw new Error('Sealed Device definition projection has expired');
121
+ }
122
+ }
123
+ function assertDefinitionIdentity(definition, reference) {
124
+ if (definition.format !== 'helix.device' ||
125
+ definition.formatVersion !== 1 ||
126
+ definition.id !== reference.id ||
127
+ definition.version !== reference.version) {
128
+ throw new Error(`Sealed Device definition identity mismatch for ${reference.id}@${reference.version}`);
129
+ }
130
+ }
131
+ function canonicalJson(value) {
132
+ const rendered = JSON.stringify(canonicalValue(value));
133
+ if (typeof rendered !== 'string') {
134
+ throw new Error('Sealed Device definition is not JSON');
135
+ }
136
+ return rendered;
137
+ }
138
+ function canonicalValue(value) {
139
+ if (value === null)
140
+ return null;
141
+ if (Array.isArray(value))
142
+ return value.map(canonicalValue);
143
+ if (typeof value === 'object') {
144
+ const result = {};
145
+ for (const key of Object.keys(value).sort()) {
146
+ const child = value[key];
147
+ if (child !== undefined)
148
+ result[key] = canonicalValue(child);
149
+ }
150
+ return result;
151
+ }
152
+ return value;
153
+ }
154
+ function deepFreeze(value) {
155
+ if (!value || typeof value !== 'object' || Object.isFrozen(value))
156
+ return value;
157
+ for (const child of Object.values(value)) {
158
+ deepFreeze(child);
159
+ }
160
+ return Object.freeze(value);
161
+ }
162
+ async function defaultSha256(bytes) {
163
+ const subtle = globalThis.crypto?.subtle;
164
+ if (!subtle) {
165
+ throw new Error('Sealed Device definition verification requires Web Crypto SHA-256 or an injected sha256 function');
166
+ }
167
+ const digest = await subtle.digest('SHA-256', bytes);
168
+ return Array.from(new Uint8Array(digest))
169
+ .map((byte) => byte.toString(16).padStart(2, '0'))
170
+ .join('');
171
+ }
172
+ //# sourceMappingURL=device-definition-resolver.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"device-definition-resolver.js","sourceRoot":"","sources":["../src/device-definition-resolver.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,3 @@
1
+ import type { DeviceTrialSpawn, HelixSession } from './protocol.js';
2
+ /** Snapshot one Device trial from the authenticated shell session. Invalid or expired rows fail closed. */
3
+ export declare function normalizeDeviceTrialSpawn(session: HelixSession | null, now?: () => number): DeviceTrialSpawn | null;
@@ -0,0 +1,132 @@
1
+ import { normalizeSealedDeviceDefinitionProjection } from './device-definition-resolver.js';
2
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
3
+ const CONTINUUM_CID = /^cid:sha256:[a-f0-9]{64}$/;
4
+ const FORBIDDEN_FIELDS = new Set([
5
+ 'instanceId',
6
+ 'itemInstanceId',
7
+ 'ownerUserId',
8
+ 'persistentVars',
9
+ 'worldState',
10
+ ]);
11
+ /** Snapshot one Device trial from the authenticated shell session. Invalid or expired rows fail closed. */
12
+ export function normalizeDeviceTrialSpawn(session, now = Date.now) {
13
+ const trial = session?.trial;
14
+ const raw = trial?.spawnedItem;
15
+ if (trial?.kind !== 'device' ||
16
+ !record(raw) ||
17
+ !UUID.test(trial.id) ||
18
+ !UUID.test(trial.itemId) ||
19
+ !Number.isSafeInteger(trial.expiresAt) ||
20
+ now() >= trial.expiresAt * 1_000 ||
21
+ [...FORBIDDEN_FIELDS].some((field) => field in raw) ||
22
+ raw.kind !== 'device' ||
23
+ raw.placementId !== trial.id ||
24
+ raw.itemId !== trial.itemId ||
25
+ raw.expiresAt !== trial.expiresAt ||
26
+ typeof raw.name !== 'string' ||
27
+ raw.name.length === 0 ||
28
+ raw.name.length > 256 ||
29
+ !servableAssetUrl(raw.modelUrl) ||
30
+ !validTransform(raw.transform) ||
31
+ !record(raw.deviceDefinition) ||
32
+ typeof raw.deviceDefinition.id !== 'string' ||
33
+ raw.deviceDefinition.id.length === 0 ||
34
+ typeof raw.deviceDefinition.version !== 'string' ||
35
+ raw.deviceDefinition.version.length === 0 ||
36
+ !record(raw.functionalPin) ||
37
+ typeof raw.functionalPin.continuumPackageId !== 'string' ||
38
+ !UUID.test(raw.functionalPin.continuumPackageId) ||
39
+ typeof raw.functionalPin.continuumPackageVersion !== 'string' ||
40
+ raw.functionalPin.continuumPackageVersion.length === 0 ||
41
+ raw.functionalPin.continuumPackageVersion.length > 64 ||
42
+ typeof raw.functionalPin.continuumManifestCid !== 'string' ||
43
+ !CONTINUUM_CID.test(raw.functionalPin.continuumManifestCid) ||
44
+ !record(raw.composition)) {
45
+ return null;
46
+ }
47
+ const projection = normalizeSealedDeviceDefinitionProjection({
48
+ definition: raw.definition,
49
+ definitionChecksumSha256: raw.definitionChecksumSha256,
50
+ expiresAtEpochSeconds: trial.expiresAt,
51
+ pin: {
52
+ packageId: raw.functionalPin.continuumPackageId,
53
+ version: raw.functionalPin.continuumPackageVersion,
54
+ manifestCid: raw.functionalPin.continuumManifestCid,
55
+ },
56
+ });
57
+ if (projection === null ||
58
+ projection.definition.id !== raw.deviceDefinition.id ||
59
+ projection.definition.version !== raw.deviceDefinition.version) {
60
+ return null;
61
+ }
62
+ try {
63
+ const transform = raw.transform;
64
+ return deepFreeze({
65
+ placementId: trial.id,
66
+ itemId: trial.itemId,
67
+ kind: 'device',
68
+ name: raw.name,
69
+ modelUrl: raw.modelUrl,
70
+ transform: {
71
+ position: [...transform.position],
72
+ yawDeg: transform.yawDeg,
73
+ scale: transform.scale,
74
+ },
75
+ expiresAt: trial.expiresAt,
76
+ deviceDefinition: {
77
+ id: projection.definition.id,
78
+ version: projection.definition.version,
79
+ },
80
+ definition: projection.definition,
81
+ definitionChecksumSha256: projection.definitionChecksumSha256,
82
+ functionalPin: {
83
+ continuumPackageId: projection.pin.packageId,
84
+ continuumPackageVersion: projection.pin.version,
85
+ continuumManifestCid: projection.pin.manifestCid,
86
+ },
87
+ composition: jsonSnapshot(raw.composition),
88
+ });
89
+ }
90
+ catch {
91
+ return null;
92
+ }
93
+ }
94
+ function record(value) {
95
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
96
+ }
97
+ function servableAssetUrl(value) {
98
+ if (value === null)
99
+ return true;
100
+ if (typeof value !== 'string' || value.length > 2048)
101
+ return false;
102
+ try {
103
+ const url = new URL(value);
104
+ const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]';
105
+ return !url.username && !url.password && (url.protocol === 'https:' || (url.protocol === 'http:' && loopback));
106
+ }
107
+ catch {
108
+ return false;
109
+ }
110
+ }
111
+ function validTransform(value) {
112
+ if (!record(value) || !Array.isArray(value.position) || value.position.length !== 3)
113
+ return false;
114
+ return value.position.every((part) => typeof part === 'number' && Number.isFinite(part)) &&
115
+ typeof value.yawDeg === 'number' && Number.isFinite(value.yawDeg) &&
116
+ typeof value.scale === 'number' && Number.isFinite(value.scale) && value.scale > 0;
117
+ }
118
+ function jsonSnapshot(value) {
119
+ const rendered = JSON.stringify(value);
120
+ if (rendered === undefined || rendered.length > 1_000_000) {
121
+ throw new Error('Device trial composition is not bounded JSON');
122
+ }
123
+ return JSON.parse(rendered);
124
+ }
125
+ function deepFreeze(value) {
126
+ if (!value || typeof value !== 'object' || Object.isFrozen(value))
127
+ return value;
128
+ for (const child of Object.values(value))
129
+ deepFreeze(child);
130
+ return Object.freeze(value);
131
+ }
132
+ //# sourceMappingURL=device-trial.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"device-trial.js","sourceRoot":"","sources":["../src/device-trial.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,228 @@
1
+ import type { HelixRoom } from './multiplayer.js';
2
+ import type { RoomVarValue } from './multiplayer-contract/room.js';
3
+ import type { WorldSpawn } from './universal-vehicles.js';
4
+ import type { ActionSurfaceAction } from './action-surface.js';
5
+ export type DeviceDefinitionReference = {
6
+ id: string;
7
+ version: string;
8
+ };
9
+ export type DevicePortKindV1 = 'value' | 'event' | 'command' | 'stream';
10
+ export type DevicePortDirectionV1 = 'input' | 'output' | 'bidirectional';
11
+ export type DevicePortDataTypeV1 = 'boolean' | 'number' | 'string' | 'media.audio' | 'media.video';
12
+ export type DevicePortAuthorityV1 = 'local' | 'server';
13
+ export type DeviceStreamRoutabilityV1 = 'routable' | 'embedded-only' | 'unavailable';
14
+ /** Engine-neutral endpoint declaration. Concrete Links belong to the host. */
15
+ export interface DevicePortV1 {
16
+ id: string;
17
+ direction: DevicePortDirectionV1;
18
+ kind: DevicePortKindV1;
19
+ dataType: DevicePortDataTypeV1;
20
+ /** Exact compatibility identity, such as helix.audio/1. */
21
+ interface?: string;
22
+ /** Stable event/command/stream meaning. Defaults to the port id for v1 devices. */
23
+ semantic?: string;
24
+ /** Signal authority lane. Legacy declarations inherit from Device authority. */
25
+ authority?: DevicePortAuthorityV1;
26
+ stateKey?: string;
27
+ autoPair?: boolean;
28
+ maxLinks?: number;
29
+ /** Stream availability; meaningful only for stream outputs. */
30
+ routability?: DeviceStreamRoutabilityV1;
31
+ }
32
+ export interface DevicePortAddressV1 {
33
+ instanceId: string;
34
+ port: string;
35
+ }
36
+ /** Opaque host registry token; it never contains media samples. */
37
+ export type DeviceStreamHandleV1 = string & {
38
+ readonly __deviceStreamHandleV1: unique symbol;
39
+ };
40
+ /** Host-authored delivery. Callers never provide an authorization role. */
41
+ export interface DeviceBusEnvelopeV1<T = unknown> {
42
+ schemaVersion: 1;
43
+ deliveryId: string;
44
+ linkId: string;
45
+ source: DevicePortAddressV1;
46
+ target: DevicePortAddressV1;
47
+ kind: DevicePortKindV1;
48
+ semantic: string;
49
+ hostSequence: number;
50
+ hopCount: number;
51
+ payload?: T;
52
+ stream?: {
53
+ status: DeviceStreamRoutabilityV1;
54
+ handle?: DeviceStreamHandleV1;
55
+ mediaKind: 'audio' | 'video';
56
+ };
57
+ }
58
+ export interface DeviceBusBudgetsV1 {
59
+ maxGraphLinks: number;
60
+ maxLinksPerEndpoint: number;
61
+ maxHopsPerDelivery: number;
62
+ maxQueuedDeliveriesPerTick: number;
63
+ maxDeliveriesPerLinkPerTick: number;
64
+ replayWindow: number;
65
+ }
66
+ /** A Device mount can come from an owned World spawn or an authored Build asset. */
67
+ export type WorldDeviceMount = Pick<WorldSpawn, 'placementId' | 'deviceDefinition'> & Partial<Omit<WorldSpawn, 'placementId' | 'deviceDefinition'>>;
68
+ /**
69
+ * App kinds a definition's `screen` components may bind to.
70
+ *
71
+ * `remoteImage` is the narrowest kind: ONE external image the host draws,
72
+ * addressed by a URL held in typed string state rather than by `entry`. It is
73
+ * not a document, so `network.fetch` is its only legal permission and its
74
+ * `entry` may be omitted.
75
+ *
76
+ * `ownerImage` is ONE image the owned copy's owner uploaded (the Custom
77
+ * Poster, capability `app.image.owner`). It names no source, origin or
78
+ * permission: the image is per-copy state on the owned instance and the HOST
79
+ * resolves it through the placement the viewer is entitled to see. A host
80
+ * without owned, placed copies (a Device Lab, an SDK-hosted world) does not
81
+ * grant `app.image.owner`, so `mount()` refuses it rather than showing a
82
+ * blank face.
83
+ */
84
+ export type DeviceAppTypeV1 = 'localWeb' | 'remoteWeb' | 'youtube' | 'canvas' | 'remoteImage' | 'ownerImage';
85
+ /** Permissions an app declaration may request from the host. */
86
+ export type DeviceAppPermissionV1 = 'web.content' | 'network.fetch' | 'web.externalNavigation' | 'audio.media';
87
+ /**
88
+ * Engine-neutral app declaration. The SDK types the declared surface — which
89
+ * powers a package asks for and where its content may come from — and never
90
+ * how a renderer draws it.
91
+ */
92
+ export interface DeviceAppDefinitionV1 {
93
+ type: DeviceAppTypeV1;
94
+ /** Authored source or host renderer id. Optional for `remoteImage`; absent for `ownerImage`. */
95
+ entry?: string;
96
+ allowedOrigins?: string[];
97
+ permissions?: DeviceAppPermissionV1[];
98
+ }
99
+ export interface DeviceDefinitionV1 {
100
+ format: 'helix.device';
101
+ formatVersion: 1;
102
+ id: string;
103
+ version: string;
104
+ state: Record<string, {
105
+ type: 'boolean' | 'integer' | 'float' | 'string' | 'enum';
106
+ default?: string | number | boolean;
107
+ persist?: boolean;
108
+ }>;
109
+ interactions: Array<{
110
+ id: string;
111
+ label: string;
112
+ verb?: 'use' | 'open' | 'close' | 'toggle' | 'play' | 'sit' | 'custom';
113
+ maxDistanceM?: number;
114
+ /** Viewer-local HUD for one declared web app; never a replicated state action. */
115
+ presentation?: {
116
+ kind: 'webPanel';
117
+ app: string;
118
+ };
119
+ /** Universal Action Surface control; omitted means a normal run row. */
120
+ control?: {
121
+ kind: 'number';
122
+ stateKey: string;
123
+ min?: number;
124
+ max?: number;
125
+ step?: number;
126
+ unit?: string;
127
+ } | {
128
+ kind: 'choice';
129
+ stateKey: string;
130
+ options: Array<{
131
+ value: string;
132
+ label: string;
133
+ disabled?: boolean;
134
+ reason?: string;
135
+ }>;
136
+ } | {
137
+ /** Native text entry rendered by the Universal Action Surface. */
138
+ kind: 'text';
139
+ /** Typed Device state written after authority accepts the submission. */
140
+ stateKey: string;
141
+ /** The interaction label is the Action Surface label; these tune its input. */
142
+ placeholder?: string;
143
+ maxLength?: number;
144
+ inputMode?: ActionSurfaceAction['inputMode'];
145
+ };
146
+ }>;
147
+ compatibility?: {
148
+ hosts: Array<'home' | 'world'>;
149
+ requiredCapabilities?: string[];
150
+ };
151
+ /** Native powers granted by the host; unknown/ungranted powers refuse mount. */
152
+ capabilities?: string[];
153
+ /** Public endpoints. Home/World composition owns concrete Links. */
154
+ ports?: DevicePortV1[];
155
+ /** Apps a screen component may bind to, keyed by the name it binds with. */
156
+ apps?: Record<string, DeviceAppDefinitionV1>;
157
+ [key: string]: unknown;
158
+ }
159
+ export interface WorldDevicePresentation {
160
+ applyState(state: Readonly<Record<string, unknown>>): void;
161
+ dispose(): void | Promise<void>;
162
+ }
163
+ export interface WorldDevicePresentationAdapter {
164
+ /** Renderer powers only; room authority, typed state and time come from the host. */
165
+ readonly capabilities: ReadonlySet<string>;
166
+ mount(input: {
167
+ spawn: WorldDeviceMount;
168
+ definition: DeviceDefinitionV1;
169
+ now: () => number;
170
+ /** Route a run/number/choice invocation into placement-scoped authority. */
171
+ interact: (interactionId: string, args?: Record<string, RoomVarValue>) => void;
172
+ }): WorldDevicePresentation | Promise<WorldDevicePresentation>;
173
+ }
174
+ export type WorldDeviceDefinitionResolver = (reference: DeviceDefinitionReference) => Promise<DeviceDefinitionV1>;
175
+ export interface WorldDevicePersistenceEntry {
176
+ value: Record<string, unknown>;
177
+ version: number;
178
+ }
179
+ export interface WorldDevicePersistence {
180
+ load(placementId: string): Promise<WorldDevicePersistenceEntry | null>;
181
+ save(placementId: string, value: Record<string, unknown>, expectedVersion: number): Promise<void>;
182
+ }
183
+ /**
184
+ * World-scoped persistence backed by the existing HELIX dataStore contract.
185
+ * It deliberately never addresses a Universal Item instance: the same owned
186
+ * item keeps its per-instance state, while a Build-authored Device uses this
187
+ * World namespace and lifecycle.
188
+ */
189
+ export declare class WorldDeviceDataStorePersistence implements WorldDevicePersistence {
190
+ readonly dataStore: {
191
+ getEntry<T>(key: string): Promise<{
192
+ value: T;
193
+ version: number;
194
+ } | null>;
195
+ set(key: string, value: unknown, options?: {
196
+ expectedVersion?: number;
197
+ }): Promise<void>;
198
+ };
199
+ constructor(dataStore: {
200
+ getEntry<T>(key: string): Promise<{
201
+ value: T;
202
+ version: number;
203
+ } | null>;
204
+ set(key: string, value: unknown, options?: {
205
+ expectedVersion?: number;
206
+ }): Promise<void>;
207
+ });
208
+ key(placementId: string): string;
209
+ load(placementId: string): Promise<WorldDevicePersistenceEntry | null>;
210
+ save(placementId: string, value: Record<string, unknown>, expectedVersion: number): Promise<void>;
211
+ }
212
+ /** Stable placement-scoped module id shared with the platform compositor. */
213
+ export declare function deviceRuntimeModuleId(definitionId: string, placementId: string): string;
214
+ /**
215
+ * Renderer-neutral World Device host. The world supplies its engine adapter;
216
+ * HELIX supplies immutable placement identity, authoritative room state/actions,
217
+ * server time, compatibility checks, and lifecycle.
218
+ */
219
+ export declare class WorldDeviceHost {
220
+ #private;
221
+ readonly room: Pick<HelixRoom, 'state' | 'module' | 'onStateChange' | 'sendAction'>;
222
+ readonly adapter: WorldDevicePresentationAdapter;
223
+ readonly resolveDefinition: WorldDeviceDefinitionResolver;
224
+ constructor(room: Pick<HelixRoom, 'state' | 'module' | 'onStateChange' | 'sendAction'>, adapter: WorldDevicePresentationAdapter, resolveDefinition: WorldDeviceDefinitionResolver);
225
+ now: () => number;
226
+ mount(spawn: WorldDeviceMount): Promise<boolean>;
227
+ dispose(): Promise<void>;
228
+ }