entangled-worlds-orbiters-shared 2.9.0 → 2.10.0

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 (39) hide show
  1. package/README.md +16 -0
  2. package/dist/capabilities/errors.d.ts +79 -0
  3. package/dist/capabilities/errors.js +87 -0
  4. package/dist/capabilities/index.d.ts +9 -0
  5. package/dist/capabilities/index.js +9 -0
  6. package/dist/capabilities/registry.d.ts +106 -0
  7. package/dist/capabilities/registry.js +215 -0
  8. package/dist/capabilities/schema.d.ts +52 -0
  9. package/dist/capabilities/schema.js +139 -0
  10. package/dist/studio/autosaveSession.d.ts +56 -0
  11. package/dist/studio/autosaveSession.js +138 -0
  12. package/dist/studio/headerBroadcast.d.ts +9 -0
  13. package/dist/studio/headerBroadcast.js +37 -0
  14. package/dist/studio/history.d.ts +37 -0
  15. package/dist/studio/history.js +50 -0
  16. package/dist/studio/hostTransport.d.ts +20 -0
  17. package/dist/studio/hostTransport.js +61 -0
  18. package/dist/studio/index.d.ts +6 -0
  19. package/dist/studio/index.js +9 -0
  20. package/dist/studio/patchStore.d.ts +7 -0
  21. package/dist/studio/patchStore.js +30 -0
  22. package/dist/studio/statusChannel.d.ts +12 -0
  23. package/dist/studio/statusChannel.js +14 -0
  24. package/dist/uploads/index.d.ts +34 -0
  25. package/dist/uploads/index.js +49 -0
  26. package/package.json +20 -4
  27. package/src/capabilities/errors.ts +115 -0
  28. package/src/capabilities/index.ts +22 -0
  29. package/src/capabilities/registry.ts +307 -0
  30. package/src/capabilities/schema.ts +164 -0
  31. package/src/loaders/cubeMapLoader.js +37 -15
  32. package/src/studio/autosaveSession.ts +186 -0
  33. package/src/studio/headerBroadcast.ts +52 -0
  34. package/src/studio/history.ts +91 -0
  35. package/src/studio/hostTransport.ts +70 -0
  36. package/src/studio/index.ts +30 -0
  37. package/src/studio/patchStore.ts +38 -0
  38. package/src/studio/statusChannel.ts +29 -0
  39. package/src/uploads/index.ts +93 -0
@@ -0,0 +1,38 @@
1
+ // A tiny external store: an immutable snapshot that is patched and broadcast. Compatible with
2
+ // React's `useSyncExternalStore(store.subscribe, store.getSnapshot)` without importing React.
3
+ // A studio's header store is one of these plus named setters — the mirror of controller state,
4
+ // never its source.
5
+
6
+ export interface PatchStore<T extends object> {
7
+ subscribe(listener: () => void): () => void
8
+ getSnapshot(): T
9
+ /** Shallow-merge `next` into a new snapshot and notify. No-op when nothing changes. */
10
+ patch(next: Partial<T>): void
11
+ }
12
+
13
+ export function createPatchStore<T extends object>(initial: T): PatchStore<T> {
14
+ let state = initial
15
+ const listeners = new Set<() => void>()
16
+
17
+ return {
18
+ subscribe(listener) {
19
+ listeners.add(listener)
20
+ return () => {
21
+ listeners.delete(listener)
22
+ }
23
+ },
24
+ getSnapshot: () => state,
25
+ patch(next) {
26
+ let changed = false
27
+ for (const key of Object.keys(next) as (keyof T)[]) {
28
+ if (!Object.is(state[key], next[key])) {
29
+ changed = true
30
+ break
31
+ }
32
+ }
33
+ if (!changed) return
34
+ state = { ...state, ...next }
35
+ listeners.forEach((l) => l())
36
+ },
37
+ }
38
+ }
@@ -0,0 +1,29 @@
1
+ // Studio status line ("Saving…", "Saved", errors). Studio core boots before its UI, so it stays
2
+ // UI-free: it calls `show()`, and the UI layer (a toaster) registers itself as the sink on mount.
3
+ // Calls made while no sink is registered are dropped — status is transient by nature.
4
+
5
+ export interface StatusShowOptions {
6
+ /** Hide after this many ms; 0 keeps it until replaced. */
7
+ autoHideMs?: number
8
+ }
9
+
10
+ export interface StatusSink {
11
+ show(text: string, opts: Required<StatusShowOptions>): void
12
+ }
13
+
14
+ export interface StatusChannel {
15
+ setSink(sink: StatusSink | null | undefined): void
16
+ show(text: unknown, opts?: StatusShowOptions): void
17
+ }
18
+
19
+ export function createStatusChannel(): StatusChannel {
20
+ let sink: StatusSink | null = null
21
+ return {
22
+ setSink(next) {
23
+ sink = next || null
24
+ },
25
+ show(text, { autoHideMs = 0 } = {}) {
26
+ sink?.show(String(text ?? ''), { autoHideMs })
27
+ },
28
+ }
29
+ }
@@ -0,0 +1,93 @@
1
+ // Uploading a file through the platform API's signed-URL flow, shared by the Entangled World and
2
+ // Orbiter studios: ask the API for a presigned PUT (`/spaces/upload-init`), send the bytes straight
3
+ // to storage, then tell the API the object landed (`/spaces/upload-complete`) so it can attach the
4
+ // key to the entity and queue thumbnails.
5
+ //
6
+ // Transport-agnostic: each app passes its own authenticated JSON caller, so auth (bearer, cookie,
7
+ // host token) stays with the app. The storage PUT carries no auth — the signature is the grant.
8
+
9
+ export type UploadJsonCaller = (
10
+ path: string,
11
+ init: { method: 'POST'; body: unknown; signal?: AbortSignal },
12
+ ) => Promise<unknown>
13
+
14
+ export interface SignedUpload {
15
+ uploadUrl: string
16
+ key: string
17
+ }
18
+
19
+ export interface PutOptions {
20
+ /** Upload progress, 0–1. */
21
+ onProgress?: (fraction: number) => void
22
+ signal?: AbortSignal
23
+ }
24
+
25
+ /**
26
+ * PUT a file to a presigned URL. XHR rather than fetch because fetch still cannot report upload
27
+ * progress. Resolves with the storage key; rejects with `aborted: true` when the signal fires.
28
+ */
29
+ export function putToSignedUrl(
30
+ file: Blob,
31
+ { uploadUrl, key }: SignedUpload,
32
+ { onProgress, signal }: PutOptions = {},
33
+ ): Promise<string> {
34
+ return new Promise((resolve, reject) => {
35
+ if (signal?.aborted) {
36
+ reject(Object.assign(new Error('Upload aborted'), { aborted: true }))
37
+ return
38
+ }
39
+ const xhr = new XMLHttpRequest()
40
+ xhr.open('PUT', uploadUrl)
41
+ // Must match the type the URL was signed for, or storage rejects the signature.
42
+ if (file.type) xhr.setRequestHeader('Content-Type', file.type)
43
+ signal?.addEventListener('abort', () => xhr.abort(), { once: true })
44
+ if (onProgress) {
45
+ xhr.upload.addEventListener('progress', (e) => {
46
+ if (e.lengthComputable) onProgress(e.loaded / e.total)
47
+ })
48
+ }
49
+ xhr.onload = () =>
50
+ xhr.status >= 200 && xhr.status < 300 ? resolve(key) : reject(new Error(`Upload failed: ${xhr.status}`))
51
+ xhr.onerror = () => reject(new Error('Upload network error'))
52
+ xhr.onabort = () => reject(Object.assign(new Error('Upload aborted'), { aborted: true }))
53
+ xhr.send(file)
54
+ })
55
+ }
56
+
57
+ export interface UploadViaSignedUrlOptions extends PutOptions {
58
+ fetchJson: UploadJsonCaller
59
+ file: Blob
60
+ /** The `/spaces/upload-init` body (entity, variant, file name and type…). */
61
+ init: Record<string, unknown>
62
+ /** The `/spaces/upload-complete` body; `key` is filled in from the init response. */
63
+ complete: Record<string, unknown>
64
+ }
65
+
66
+ export interface UploadResult {
67
+ key: string
68
+ /** Whatever `/spaces/upload-complete` answered (e.g. `previewURL`). */
69
+ completed: unknown
70
+ }
71
+
72
+ /** The whole flow: init → PUT → complete. */
73
+ export async function uploadViaSignedUrl({
74
+ fetchJson,
75
+ file,
76
+ init,
77
+ complete,
78
+ onProgress,
79
+ signal,
80
+ }: UploadViaSignedUrlOptions): Promise<UploadResult> {
81
+ const signed = (await fetchJson('/spaces/upload-init', { method: 'POST', body: init, signal })) as
82
+ | Partial<SignedUpload>
83
+ | null
84
+ const { uploadUrl, key } = signed ?? {}
85
+ if (!uploadUrl || !key) throw new Error('upload-init: missing uploadUrl or key')
86
+ await putToSignedUrl(file, { uploadUrl, key }, { onProgress, signal })
87
+ const completed = await fetchJson('/spaces/upload-complete', {
88
+ method: 'POST',
89
+ body: { ...complete, key },
90
+ signal,
91
+ })
92
+ return { key, completed }
93
+ }