@lavitre/apps 1.51.0 → 1.52.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.
package/README.md CHANGED
@@ -126,6 +126,26 @@ settingsSchema: { type: 'object', properties: { city: { type: 'string' } } }
126
126
 
127
127
  `type: 'object'` + `properties` is only for a setting that is itself an object. The wrong shape is a type error since 1.50 (`SettingsSchemaProperties`), and plain-JS apps get it unwrapped at runtime with a `console.error` — hosts that predate the 2026-09 fix crash their settings form on it. Every `properties` value and `items` must be a schema object (never `items: 'string'`), and `required` is an array of key names on the enclosing object. Always read settings through `ensureDefaultValue(hostInformation.settings, defaults)`: the value may be `null` or partial.
128
128
 
129
+ ### Local camera preview — `LocalPreview`
130
+
131
+ Shows the Vitre's main camera the way the participants see it: zoom and offsets of the device in fullscreen (else of this device), rotation and mirror of the local camera. Same rendering as the host's own video element.
132
+
133
+ ```ts
134
+ import { LocalPreview } from '@lavitre/apps/Frame'
135
+
136
+ const preview = new LocalPreview(frame) // opens the camera, retries, follows scaling updates
137
+ preview.attach(document.getElementById('view')!) // CSS transforms, no per-frame cost
138
+ video.srcObject = preview.getScaledStream() // or: frames already cropped (WebGL, recorder…)
139
+ const jpeg = await preview.capture() // still image, e.g. for onExportRequest
140
+ preview.dispose()
141
+ ```
142
+
143
+ It listens through `frame.addDeviceStateListener`, so the app's `onDeviceScalingUpdated` & co. stay its own. While the camera cannot be opened, `preview.error` (also in `addListener`'s state) says why — `NotAllowedError`, `NotFoundError`, `TimeoutError`… — and retries continue with a growing delay. `getScaledStream` redraws each frame in a worker on Chromium (insertable streams), on the main thread when the worker cannot run (CSP without `blob:` in `worker-src`), and with a canvas elsewhere. Apps drawing the preview themselves use the pure helpers from `@lavitre/apps/Common`: `resolvePreviewScaling(hostInformation)` → `computePreviewLayout(scaling)` → `previewMatrix(layout, srcW, srcH, outW, outH)`, a matrix for `ctx.setTransform` or CSS `matrix()`.
144
+
145
+ ## Development
146
+
147
+ `pnpm typecheck`, `pnpm build`, and `pnpm test` for the unit tests (`node:test`; Node ≥ 22.18 runs the TypeScript directly).
148
+
129
149
  ## Versioning
130
150
 
131
151
  The package ships compiled ESM + `.d.ts` (`pnpm build` → `dist/`); import paths (`@lavitre/apps/<Module>`) are unchanged. `Version.ts` carries `apiVersion`, refreshed at build time by `replaceVersion.js`. The host enforces a minimum SDK version on initialize — bumping a breaking change requires a major-version bump in `package.json`.
@@ -0,0 +1,62 @@
1
+ import type { CropMode, Device, DeviceScaling, HostInformation } from './Common.Model.js';
2
+ export declare const DEFAULT_DEVICE_SCALING: DeviceScaling;
3
+ /**
4
+ * How the source pixels are laid out in the preview before cropping:
5
+ * - `mirror`: flipped horizontally (emulated `top`, or no emulated rotation)
6
+ * - `transpose` / `antiTranspose`: emulated `left` / `right` — a quarter
7
+ * turn combined with the mirror, so the result is a diagonal flip
8
+ * - `flipY`: emulated `bottom` — half turn combined with the mirror
9
+ */
10
+ export type PreviewOrientation = 'mirror' | 'transpose' | 'antiTranspose' | 'flipY';
11
+ export type PreviewLayout = {
12
+ orientation: PreviewOrientation;
13
+ /** True when the preview swaps width and height of the source. */
14
+ swapsAxes: boolean;
15
+ scale: number;
16
+ /** Offsets of the cropped area, already adjusted for the mirror. */
17
+ offsetX: number;
18
+ offsetY: number;
19
+ cropMode?: CropMode;
20
+ };
21
+ /** 2D affine matrix in canvas `setTransform(a, b, c, d, e, f)` order. */
22
+ export type PreviewMatrix = [number, number, number, number, number, number];
23
+ /**
24
+ * The scaling the host applies to this camera when sending it to `device`.
25
+ * Falls back to the pre-`sendingScaling` field of older hosts.
26
+ */
27
+ export declare const getDeviceScaling: (device?: Device) => DeviceScaling | undefined;
28
+ /**
29
+ * Converts a `legacy` scaling (offsets relative to a 16:9 frame whatever the
30
+ * rotation) to `rotationIndependent`. A top/bottom camera is already 16:9, so
31
+ * only its version changes — same rule as the host.
32
+ */
33
+ export declare const toRotationIndependent: (scaling: DeviceScaling) => DeviceScaling;
34
+ /**
35
+ * The scaling the local preview must show: zoom and offsets of the device in
36
+ * fullscreen (what the person looking at us sees), else our own; orientation,
37
+ * crop mode and ratio always from the local device, since they describe our
38
+ * camera.
39
+ */
40
+ export declare const resolvePreviewScaling: (host: HostInformation) => DeviceScaling;
41
+ /**
42
+ * Turns a scaling into a renderer-independent layout. The horizontal offset
43
+ * is mirrored for `left`/`right` only, whatever `orientationBy` says: that is
44
+ * the host's `mirrorScaling`, keep them in step.
45
+ */
46
+ export declare const computePreviewLayout: (scaling: DeviceScaling) => PreviewLayout;
47
+ /** Width / height of the preview for a source of the given size. */
48
+ export declare const previewAspectRatio: (layout: PreviewLayout, sourceWidth: number, sourceHeight: number) => number;
49
+ /**
50
+ * Matrix mapping source pixels (`sourceWidth` × `sourceHeight`) to preview
51
+ * pixels (`outputWidth` × `outputHeight`). Use it as is with
52
+ * `CanvasRenderingContext2D.setTransform` before `drawImage(source, 0, 0)`,
53
+ * or as a CSS `matrix()` on an element of the source size with
54
+ * `transform-origin: 0 0`. The output should have the aspect ratio given by
55
+ * `previewAspectRatio`, otherwise the image is stretched.
56
+ */
57
+ export declare const previewMatrix: (layout: PreviewLayout, sourceWidth: number, sourceHeight: number, outputWidth: number, outputHeight: number) => PreviewMatrix;
58
+ /** Pixel size of the preview of a source: the source size, rotated, capped so its longest side is at most `maxSize`. */
59
+ export declare const previewOutputSize: (layout: PreviewLayout, sourceWidth: number, sourceHeight: number, maxSize: number) => {
60
+ width: number;
61
+ height: number;
62
+ };
@@ -0,0 +1,132 @@
1
+ /**
2
+ * Pure geometry of the local camera preview: what the participants of the
3
+ * space see of this device's camera, expressed so that any renderer (CSS,
4
+ * canvas, WebGL) can reproduce it. No DOM access — usable in a worker.
5
+ *
6
+ * Follows the host's own rendering of a camera (lavitre-app
7
+ * `VideoElement`), which the core app's `localpreview` copied with two
8
+ * divergences fixed here: an emulated `top` is mirrored, and a `legacy`
9
+ * top/bottom scaling keeps its offsets.
10
+ */
11
+ /** Ratio the host assumes when converting a `legacy` scaling. */
12
+ const LEGACY_RATIO = 16 / 9;
13
+ export const DEFAULT_DEVICE_SCALING = {
14
+ scale: 1,
15
+ offsetX: 0,
16
+ offsetY: 0,
17
+ version: 'rotationIndependent',
18
+ };
19
+ /**
20
+ * The scaling the host applies to this camera when sending it to `device`.
21
+ * Falls back to the pre-`sendingScaling` field of older hosts.
22
+ */
23
+ export const getDeviceScaling = (device) => device ? (device.sendingScaling ?? device.scaling) : undefined;
24
+ /**
25
+ * Converts a `legacy` scaling (offsets relative to a 16:9 frame whatever the
26
+ * rotation) to `rotationIndependent`. A top/bottom camera is already 16:9, so
27
+ * only its version changes — same rule as the host.
28
+ */
29
+ export const toRotationIndependent = (scaling) => scaling.version === 'rotationIndependent'
30
+ ? scaling
31
+ : scaling.version === 'legacy' &&
32
+ (scaling.orientation === 'top' || scaling.orientation === 'bottom')
33
+ ? { ...scaling, version: 'rotationIndependent' }
34
+ : {
35
+ ...scaling,
36
+ offsetX: scaling.offsetX * LEGACY_RATIO,
37
+ offsetY: scaling.offsetY / LEGACY_RATIO,
38
+ version: 'rotationIndependent',
39
+ };
40
+ /**
41
+ * The scaling the local preview must show: zoom and offsets of the device in
42
+ * fullscreen (what the person looking at us sees), else our own; orientation,
43
+ * crop mode and ratio always from the local device, since they describe our
44
+ * camera.
45
+ */
46
+ export const resolvePreviewScaling = (host) => {
47
+ const local = getDeviceScaling(host.device);
48
+ const remote = getDeviceScaling(host.devicesInSpace.find((d) => d.fullscreen === 'fullscreen')) ?? local;
49
+ if (!remote)
50
+ return DEFAULT_DEVICE_SCALING;
51
+ return toRotationIndependent({
52
+ ...(local ?? DEFAULT_DEVICE_SCALING),
53
+ scale: remote.scale,
54
+ offsetX: remote.offsetX,
55
+ offsetY: remote.offsetY,
56
+ version: remote.version,
57
+ });
58
+ };
59
+ /**
60
+ * Emulated orientations are rotated by the app; `system` ones arrive already
61
+ * rotated, so only the mirror applies.
62
+ */
63
+ const previewOrientation = (scaling) => {
64
+ if ((scaling.orientationBy ?? 'emulated') !== 'emulated')
65
+ return 'mirror';
66
+ switch (scaling.orientation) {
67
+ case 'left':
68
+ return 'transpose';
69
+ case 'right':
70
+ return 'antiTranspose';
71
+ case 'top':
72
+ return 'mirror';
73
+ case 'bottom':
74
+ return 'flipY';
75
+ default:
76
+ return 'mirror';
77
+ }
78
+ };
79
+ /**
80
+ * Turns a scaling into a renderer-independent layout. The horizontal offset
81
+ * is mirrored for `left`/`right` only, whatever `orientationBy` says: that is
82
+ * the host's `mirrorScaling`, keep them in step.
83
+ */
84
+ export const computePreviewLayout = (scaling) => {
85
+ const s = toRotationIndependent(scaling);
86
+ const orientation = previewOrientation(s);
87
+ const mirrorsOffset = s.orientation === 'left' || s.orientation === 'right';
88
+ return {
89
+ orientation,
90
+ swapsAxes: orientation === 'transpose' || orientation === 'antiTranspose',
91
+ scale: s.scale,
92
+ offsetX: mirrorsOffset ? -(s.scale + s.offsetX - 1) : s.offsetX,
93
+ offsetY: s.offsetY,
94
+ cropMode: s.cropMode,
95
+ };
96
+ };
97
+ /** Width / height of the preview for a source of the given size. */
98
+ export const previewAspectRatio = (layout, sourceWidth, sourceHeight) => layout.swapsAxes ? sourceHeight / sourceWidth : sourceWidth / sourceHeight;
99
+ const ORIENTATION_MATRICES = {
100
+ mirror: [-1, 0, 0, 1, 1, 0],
101
+ transpose: [0, 1, 1, 0, 0, 0],
102
+ antiTranspose: [0, -1, -1, 0, 1, 1],
103
+ flipY: [1, 0, 0, -1, 0, 1],
104
+ };
105
+ /**
106
+ * Matrix mapping source pixels (`sourceWidth` × `sourceHeight`) to preview
107
+ * pixels (`outputWidth` × `outputHeight`). Use it as is with
108
+ * `CanvasRenderingContext2D.setTransform` before `drawImage(source, 0, 0)`,
109
+ * or as a CSS `matrix()` on an element of the source size with
110
+ * `transform-origin: 0 0`. The output should have the aspect ratio given by
111
+ * `previewAspectRatio`, otherwise the image is stretched.
112
+ */
113
+ export const previewMatrix = (layout, sourceWidth, sourceHeight, outputWidth, outputHeight) => {
114
+ const [a, b, c, d, e, f] = ORIENTATION_MATRICES[layout.orientation];
115
+ const s = layout.scale;
116
+ return [
117
+ (a * s * outputWidth) / sourceWidth,
118
+ (b * s * outputHeight) / sourceWidth,
119
+ (c * s * outputWidth) / sourceHeight,
120
+ (d * s * outputHeight) / sourceHeight,
121
+ (e * s + layout.offsetX) * outputWidth,
122
+ (f * s + layout.offsetY) * outputHeight,
123
+ ];
124
+ };
125
+ /** Pixel size of the preview of a source: the source size, rotated, capped so its longest side is at most `maxSize`. */
126
+ export const previewOutputSize = (layout, sourceWidth, sourceHeight, maxSize) => {
127
+ const w = layout.swapsAxes ? sourceHeight : sourceWidth;
128
+ const h = layout.swapsAxes ? sourceWidth : sourceHeight;
129
+ const k = Math.min(1, maxSize / Math.max(w, h));
130
+ return { width: Math.round(w * k), height: Math.round(h * k) };
131
+ };
132
+ //# sourceMappingURL=PreviewScaling.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"PreviewScaling.js","sourceRoot":"","sources":["../../Common/PreviewScaling.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n CropMode,\n Device,\n DeviceScaling,\n HostInformation,\n} from './Common.Model.js'\n\n/**\n * Pure geometry of the local camera preview: what the participants of the\n * space see of this device's camera, expressed so that any renderer (CSS,\n * canvas, WebGL) can reproduce it. No DOM access — usable in a worker.\n *\n * Follows the host's own rendering of a camera (lavitre-app\n * `VideoElement`), which the core app's `localpreview` copied with two\n * divergences fixed here: an emulated `top` is mirrored, and a `legacy`\n * top/bottom scaling keeps its offsets.\n */\n\n/** Ratio the host assumes when converting a `legacy` scaling. */\nconst LEGACY_RATIO = 16 / 9\n\nexport const DEFAULT_DEVICE_SCALING: DeviceScaling = {\n scale: 1,\n offsetX: 0,\n offsetY: 0,\n version: 'rotationIndependent',\n}\n\n/**\n * How the source pixels are laid out in the preview before cropping:\n * - `mirror`: flipped horizontally (emulated `top`, or no emulated rotation)\n * - `transpose` / `antiTranspose`: emulated `left` / `right` — a quarter\n * turn combined with the mirror, so the result is a diagonal flip\n * - `flipY`: emulated `bottom` — half turn combined with the mirror\n */\nexport type PreviewOrientation =\n | 'mirror'\n | 'transpose'\n | 'antiTranspose'\n | 'flipY'\n\nexport type PreviewLayout = {\n orientation: PreviewOrientation\n /** True when the preview swaps width and height of the source. */\n swapsAxes: boolean\n scale: number\n /** Offsets of the cropped area, already adjusted for the mirror. */\n offsetX: number\n offsetY: number\n cropMode?: CropMode\n}\n\n/** 2D affine matrix in canvas `setTransform(a, b, c, d, e, f)` order. */\nexport type PreviewMatrix = [number, number, number, number, number, number]\n\n/**\n * The scaling the host applies to this camera when sending it to `device`.\n * Falls back to the pre-`sendingScaling` field of older hosts.\n */\nexport const getDeviceScaling = (device?: Device): DeviceScaling | undefined =>\n device ? (device.sendingScaling ?? (device as any).scaling) : undefined\n\n/**\n * Converts a `legacy` scaling (offsets relative to a 16:9 frame whatever the\n * rotation) to `rotationIndependent`. A top/bottom camera is already 16:9, so\n * only its version changes — same rule as the host.\n */\nexport const toRotationIndependent = (scaling: DeviceScaling): DeviceScaling =>\n scaling.version === 'rotationIndependent'\n ? scaling\n : scaling.version === 'legacy' &&\n (scaling.orientation === 'top' || scaling.orientation === 'bottom')\n ? { ...scaling, version: 'rotationIndependent' }\n : {\n ...scaling,\n offsetX: scaling.offsetX * LEGACY_RATIO,\n offsetY: scaling.offsetY / LEGACY_RATIO,\n version: 'rotationIndependent',\n }\n\n/**\n * The scaling the local preview must show: zoom and offsets of the device in\n * fullscreen (what the person looking at us sees), else our own; orientation,\n * crop mode and ratio always from the local device, since they describe our\n * camera.\n */\nexport const resolvePreviewScaling = (host: HostInformation): DeviceScaling => {\n const local = getDeviceScaling(host.device)\n const remote =\n getDeviceScaling(\n host.devicesInSpace.find((d) => d.fullscreen === 'fullscreen'),\n ) ?? local\n if (!remote) return DEFAULT_DEVICE_SCALING\n return toRotationIndependent({\n ...(local ?? DEFAULT_DEVICE_SCALING),\n scale: remote.scale,\n offsetX: remote.offsetX,\n offsetY: remote.offsetY,\n version: remote.version,\n })\n}\n\n/**\n * Emulated orientations are rotated by the app; `system` ones arrive already\n * rotated, so only the mirror applies.\n */\nconst previewOrientation = (scaling: DeviceScaling): PreviewOrientation => {\n if ((scaling.orientationBy ?? 'emulated') !== 'emulated') return 'mirror'\n switch (scaling.orientation) {\n case 'left':\n return 'transpose'\n case 'right':\n return 'antiTranspose'\n case 'top':\n return 'mirror'\n case 'bottom':\n return 'flipY'\n default:\n return 'mirror'\n }\n}\n\n/**\n * Turns a scaling into a renderer-independent layout. The horizontal offset\n * is mirrored for `left`/`right` only, whatever `orientationBy` says: that is\n * the host's `mirrorScaling`, keep them in step.\n */\nexport const computePreviewLayout = (scaling: DeviceScaling): PreviewLayout => {\n const s = toRotationIndependent(scaling)\n const orientation = previewOrientation(s)\n const mirrorsOffset = s.orientation === 'left' || s.orientation === 'right'\n return {\n orientation,\n swapsAxes: orientation === 'transpose' || orientation === 'antiTranspose',\n scale: s.scale,\n offsetX: mirrorsOffset ? -(s.scale + s.offsetX - 1) : s.offsetX,\n offsetY: s.offsetY,\n cropMode: s.cropMode,\n }\n}\n\n/** Width / height of the preview for a source of the given size. */\nexport const previewAspectRatio = (\n layout: PreviewLayout,\n sourceWidth: number,\n sourceHeight: number,\n) =>\n layout.swapsAxes ? sourceHeight / sourceWidth : sourceWidth / sourceHeight\n\nconst ORIENTATION_MATRICES: Record<PreviewOrientation, PreviewMatrix> = {\n mirror: [-1, 0, 0, 1, 1, 0],\n transpose: [0, 1, 1, 0, 0, 0],\n antiTranspose: [0, -1, -1, 0, 1, 1],\n flipY: [1, 0, 0, -1, 0, 1],\n}\n\n/**\n * Matrix mapping source pixels (`sourceWidth` × `sourceHeight`) to preview\n * pixels (`outputWidth` × `outputHeight`). Use it as is with\n * `CanvasRenderingContext2D.setTransform` before `drawImage(source, 0, 0)`,\n * or as a CSS `matrix()` on an element of the source size with\n * `transform-origin: 0 0`. The output should have the aspect ratio given by\n * `previewAspectRatio`, otherwise the image is stretched.\n */\nexport const previewMatrix = (\n layout: PreviewLayout,\n sourceWidth: number,\n sourceHeight: number,\n outputWidth: number,\n outputHeight: number,\n): PreviewMatrix => {\n const [a, b, c, d, e, f] = ORIENTATION_MATRICES[layout.orientation]\n const s = layout.scale\n return [\n (a * s * outputWidth) / sourceWidth,\n (b * s * outputHeight) / sourceWidth,\n (c * s * outputWidth) / sourceHeight,\n (d * s * outputHeight) / sourceHeight,\n (e * s + layout.offsetX) * outputWidth,\n (f * s + layout.offsetY) * outputHeight,\n ]\n}\n\n/** Pixel size of the preview of a source: the source size, rotated, capped so its longest side is at most `maxSize`. */\nexport const previewOutputSize = (\n layout: PreviewLayout,\n sourceWidth: number,\n sourceHeight: number,\n maxSize: number,\n) => {\n const w = layout.swapsAxes ? sourceHeight : sourceWidth\n const h = layout.swapsAxes ? sourceWidth : sourceHeight\n const k = Math.min(1, maxSize / Math.max(w, h))\n return { width: Math.round(w * k), height: Math.round(h * k) }\n}\n"]}
@@ -4,3 +4,4 @@ export { CrdtChannel, MIN_CRDT_HOST_VERSION, type CrdtAttachment, type CrdtInbou
4
4
  export { BlobStore } from './BlobStore.js';
5
5
  export { AiChannel, MIN_AI_HOST_VERSION, type AiTool, type AiToolHandler, type AiInboundMessage, type AiOutboundMessage, type AiPostMessage, } from './AiChannel.js';
6
6
  export declare const ensureDefaultValue: <T>(value: Partial<T> | null, defaultValue: T) => T;
7
+ export * from './PreviewScaling.js';
@@ -29,4 +29,5 @@ export const ensureDefaultValue = (value, defaultValue) => {
29
29
  };
30
30
  return ensureValue(value === undefined ? {} : value, defaultValue);
31
31
  };
32
+ export * from './PreviewScaling.js';
32
33
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../Common/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EACL,WAAW,EACX,qBAAqB,GAKtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EACL,SAAS,EACT,mBAAmB,GAMpB,MAAM,gBAAgB,CAAA;AAEvB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAwB,EACxB,YAAe,EACf,EAAE;IACF,MAAM,WAAW,GAAG,CAAC,KAAU,EAAE,YAAiB,EAAE,EAAE;QACpD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,OAAO,YAAY,EAAE,CAAC;YACzC,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1B,OAAO,YAAY,CAAA;gBACrB,CAAC;qBAAM,CAAC;oBACN,OAAO,KAAK,CAAA;gBACd,CAAC;YACH,CAAC;YAED,KAAK,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;YACzD,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;gBACxC,KAAK,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;YAChE,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,OAAO,WAAW,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,YAAY,CAAM,CAAA;AACzE,CAAC,CAAA","sourcesContent":["export * from './Common.Model.js'\nexport { compareVersions, isMinVersion } from './Version.js'\nexport {\n CrdtChannel,\n MIN_CRDT_HOST_VERSION,\n type CrdtAttachment,\n type CrdtInboundMessage,\n type CrdtOutboundMessage,\n type CrdtPostMessage,\n} from './CrdtChannel.js'\nexport { BlobStore } from './BlobStore.js'\nexport {\n AiChannel,\n MIN_AI_HOST_VERSION,\n type AiTool,\n type AiToolHandler,\n type AiInboundMessage,\n type AiOutboundMessage,\n type AiPostMessage,\n} from './AiChannel.js'\n\nexport const ensureDefaultValue = <T>(\n value: Partial<T> | null,\n defaultValue: T,\n) => {\n const ensureValue = (value: any, defaultValue: any) => {\n if (defaultValue === undefined) {\n return value\n }\n\n if (typeof value !== typeof defaultValue) {\n return defaultValue\n }\n\n if (typeof defaultValue === 'object') {\n if (Array.isArray(defaultValue)) {\n if (!Array.isArray(value)) {\n return defaultValue\n } else {\n return value\n }\n }\n\n value = value === undefined || value == null ? {} : value\n Object.keys(defaultValue).forEach((key) => {\n value[key] = ensureDefaultValue(value[key], defaultValue[key])\n })\n }\n\n return value\n }\n\n return ensureValue(value === undefined ? {} : value, defaultValue) as T\n}\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../Common/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EACL,WAAW,EACX,qBAAqB,GAKtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EACL,SAAS,EACT,mBAAmB,GAMpB,MAAM,gBAAgB,CAAA;AAEvB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAwB,EACxB,YAAe,EACf,EAAE;IACF,MAAM,WAAW,GAAG,CAAC,KAAU,EAAE,YAAiB,EAAE,EAAE;QACpD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,OAAO,YAAY,EAAE,CAAC;YACzC,OAAO,YAAY,CAAA;QACrB,CAAC;QAED,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1B,OAAO,YAAY,CAAA;gBACrB,CAAC;qBAAM,CAAC;oBACN,OAAO,KAAK,CAAA;gBACd,CAAC;YACH,CAAC;YAED,KAAK,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;YACzD,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;gBACxC,KAAK,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;YAChE,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,OAAO,WAAW,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,YAAY,CAAM,CAAA;AACzE,CAAC,CAAA;AACD,cAAc,qBAAqB,CAAA","sourcesContent":["export * from './Common.Model.js'\nexport { compareVersions, isMinVersion } from './Version.js'\nexport {\n CrdtChannel,\n MIN_CRDT_HOST_VERSION,\n type CrdtAttachment,\n type CrdtInboundMessage,\n type CrdtOutboundMessage,\n type CrdtPostMessage,\n} from './CrdtChannel.js'\nexport { BlobStore } from './BlobStore.js'\nexport {\n AiChannel,\n MIN_AI_HOST_VERSION,\n type AiTool,\n type AiToolHandler,\n type AiInboundMessage,\n type AiOutboundMessage,\n type AiPostMessage,\n} from './AiChannel.js'\n\nexport const ensureDefaultValue = <T>(\n value: Partial<T> | null,\n defaultValue: T,\n) => {\n const ensureValue = (value: any, defaultValue: any) => {\n if (defaultValue === undefined) {\n return value\n }\n\n if (typeof value !== typeof defaultValue) {\n return defaultValue\n }\n\n if (typeof defaultValue === 'object') {\n if (Array.isArray(defaultValue)) {\n if (!Array.isArray(value)) {\n return defaultValue\n } else {\n return value\n }\n }\n\n value = value === undefined || value == null ? {} : value\n Object.keys(defaultValue).forEach((key) => {\n value[key] = ensureDefaultValue(value[key], defaultValue[key])\n })\n }\n\n return value\n }\n\n return ensureValue(value === undefined ? {} : value, defaultValue) as T\n}\nexport * from './PreviewScaling.js'\n"]}
@@ -147,6 +147,17 @@ export declare class Frame {
147
147
  set yjsDoc(doc: Y.Doc);
148
148
  position: Rect;
149
149
  zIndex: number;
150
+ private deviceStateListeners;
151
+ /**
152
+ * Called after any change of `hostInformation.device`,
153
+ * `hostInformation.devicesInSpace` or the available media devices (device
154
+ * joined or left, privacy, fullscreen, scaling, media devices, Vitre
155
+ * settings), once the matching `on…` callback has run. Unlike those callbacks, several
156
+ * listeners can coexist: SDK helpers use this so they never replace a
157
+ * handler the app assigned. Returns the unsubscribe function. Added 1.52.
158
+ */
159
+ addDeviceStateListener(listener: () => void): () => void;
160
+ private notifyDeviceState;
150
161
  constructor(postMessage: PostMessageFrameApiOut, initMessage: InitializeFrame, options: ViewOptions, initState?: Record<string, any>);
151
162
  private resolveRequest;
152
163
  raiseMessage(msg: FrameApiMessagesIn): void;
@@ -14,6 +14,28 @@ export class Frame {
14
14
  set yjsDoc(doc) {
15
15
  this.crdt.attach(doc);
16
16
  }
17
+ /**
18
+ * Called after any change of `hostInformation.device`,
19
+ * `hostInformation.devicesInSpace` or the available media devices (device
20
+ * joined or left, privacy, fullscreen, scaling, media devices, Vitre
21
+ * settings), once the matching `on…` callback has run. Unlike those callbacks, several
22
+ * listeners can coexist: SDK helpers use this so they never replace a
23
+ * handler the app assigned. Returns the unsubscribe function. Added 1.52.
24
+ */
25
+ addDeviceStateListener(listener) {
26
+ this.deviceStateListeners.add(listener);
27
+ return () => this.deviceStateListeners.delete(listener);
28
+ }
29
+ notifyDeviceState() {
30
+ for (const listener of this.deviceStateListeners) {
31
+ try {
32
+ listener();
33
+ }
34
+ catch (error) {
35
+ console.error('[Frame] device state listener failed', error);
36
+ }
37
+ }
38
+ }
17
39
  constructor(
18
40
  // `protected` (not `private`) so the companion-only subclass
19
41
  // `CompanionFrameImpl` (CompanionFrame.ts) can post its companion-frame
@@ -344,7 +366,12 @@ export class Frame {
344
366
  enumerable: true,
345
367
  configurable: true,
346
368
  writable: true,
347
- value: { top: 0, right: 0, bottom: 0, left: 0 }
369
+ value: {
370
+ top: 0,
371
+ right: 0,
372
+ bottom: 0,
373
+ left: 0,
374
+ }
348
375
  });
349
376
  /**
350
377
  * The companion's own identity/runtime context, present only when this
@@ -447,6 +474,12 @@ export class Frame {
447
474
  writable: true,
448
475
  value: void 0
449
476
  });
477
+ Object.defineProperty(this, "deviceStateListeners", {
478
+ enumerable: true,
479
+ configurable: true,
480
+ writable: true,
481
+ value: new Set()
482
+ });
450
483
  Object.defineProperty(this, "requestResolvers", {
451
484
  enumerable: true,
452
485
  configurable: true,
@@ -588,6 +621,7 @@ export class Frame {
588
621
  ],
589
622
  };
590
623
  this.onDeviceJoined?.(msg.device);
624
+ this.notifyDeviceState();
591
625
  break;
592
626
  case 'deviceLeft':
593
627
  this.hostInformation = {
@@ -595,6 +629,7 @@ export class Frame {
595
629
  devicesInSpace: this.hostInformation.devicesInSpace.filter((d) => d.id !== msg.deviceId),
596
630
  };
597
631
  this.onDeviceLeft?.(msg.deviceId);
632
+ this.notifyDeviceState();
598
633
  break;
599
634
  case 'deviceMessageReceived':
600
635
  this.onDeviceMessageReceived?.(msg);
@@ -666,6 +701,7 @@ export class Frame {
666
701
  },
667
702
  };
668
703
  this.onVitreSettingsUpdated?.(msg);
704
+ this.notifyDeviceState();
669
705
  break;
670
706
  case 'connectionCodeUpdated':
671
707
  this.hostInformation = {
@@ -689,6 +725,7 @@ export class Frame {
689
725
  ],
690
726
  };
691
727
  this.onDevicePrivacyChanged?.(msg.device);
728
+ this.notifyDeviceState();
692
729
  break;
693
730
  case 'deviceFrameLoaded':
694
731
  this.onDeviceFrameLoaded?.(msg);
@@ -725,6 +762,7 @@ export class Frame {
725
762
  this.hostInformation.devicesInSpace =
726
763
  this.hostInformation.devicesInSpace.map((d) => d.id === msg.deviceId ? { ...d, fullscreen: msg.fullscreen } : d);
727
764
  this.onDeviceFullscreenUpdated?.(msg);
765
+ this.notifyDeviceState();
728
766
  break;
729
767
  case 'visibilityChanged':
730
768
  this.onVisibilityChanged?.(msg);
@@ -745,6 +783,7 @@ export class Frame {
745
783
  }
746
784
  : d);
747
785
  this.onDeviceScalingUpdated?.(msg);
786
+ this.notifyDeviceState();
748
787
  break;
749
788
  case 'updateFrameName':
750
789
  this.options.name = msg.name;
@@ -782,6 +821,7 @@ export class Frame {
782
821
  },
783
822
  };
784
823
  this.onMediaDevicesChanged?.(msg.devices);
824
+ this.notifyDeviceState();
785
825
  break;
786
826
  case 'bluetooth':
787
827
  this.onBluetoothMessage?.(msg);
@@ -1083,7 +1123,8 @@ export class Frame {
1083
1123
  const requestId = randomUuid();
1084
1124
  const { tracks, transfer } = this.toShareTracks(stream);
1085
1125
  await this.postRequest({ type: 'shareStream', requestId, sharedStreamId, options, tracks }, (msg, resolve, reject) => {
1086
- if (msg.type === 'shareStreamCompleted' && msg.requestId === requestId) {
1126
+ if (msg.type === 'shareStreamCompleted' &&
1127
+ msg.requestId === requestId) {
1087
1128
  if (msg.error != null)
1088
1129
  reject(msg.error);
1089
1130
  else
@@ -1107,7 +1148,8 @@ export class Frame {
1107
1148
  const requestId = randomUuid();
1108
1149
  const { tracks, transfer } = this.toShareTracks(stream);
1109
1150
  await this.postRequest({ type: 'replaceShareStream', requestId, sharedStreamId, tracks }, (msg, resolve, reject) => {
1110
- if (msg.type === 'shareStreamCompleted' && msg.requestId === requestId) {
1151
+ if (msg.type === 'shareStreamCompleted' &&
1152
+ msg.requestId === requestId) {
1111
1153
  if (msg.error != null)
1112
1154
  reject(msg.error);
1113
1155
  else