@reactor-team/js-sdk 3.0.0 → 3.0.2

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/dist/index.d.cts CHANGED
@@ -155,10 +155,11 @@ declare class RecorderDisabledError extends ReactorError {
155
155
  }
156
156
 
157
157
  /**
158
- * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back as a
159
- * top-level value in `sendCommand()`'s `data` and it's extracted and sent as
160
- * a separate upload reference rather than embedded in the JSON payload —
161
- * see `extractFileRefs()`.
158
+ * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back in
159
+ * `sendCommand()`'s `data` wherever the model's schema declares a file: as a
160
+ * top-level value it's extracted and sent as a separate upload reference,
161
+ * and inside an array or object it's serialized as one — see
162
+ * `extractFileRefs()`.
162
163
  */
163
164
  declare class FileRef {
164
165
  readonly uploadId: string;
@@ -639,6 +640,43 @@ declare class Reactor implements Disposable {
639
640
  * take ownership of Rust value while it was borrowed") or corrupt it
640
641
  * outright. */
641
642
  private readonly queue;
643
+ /** In-flight calls to `withReaderAccess()` — a "reply" `.catch(() => {})`
644
+ * copy of each, never the caller's own promise, so one rejecting can't
645
+ * make `Promise.all()` in `withWriterAccess()` reject and skip waiting
646
+ * for the rest. See `withReaderAccess()`/`withWriterAccess()`. */
647
+ private readonly activeReads;
648
+ /** True for the span of a `withWriterAccess()` call — after it has waited
649
+ * out every read active when it started, before it releases the ones
650
+ * that arrived while it ran. */
651
+ private writerActive;
652
+ /** Readers parked in `withReaderAccess()`'s wait loop, woken once
653
+ * `withWriterAccess()` finishes; each re-checks `writerActive` rather
654
+ * than assuming its turn, since another writer already queued behind the
655
+ * first one may have claimed it first. */
656
+ private writerIdleWaiters;
657
+ /**
658
+ * Runs a read — sendCommand()/requestSchema()/requestClip()/
659
+ * requestRecording() — excluded from a lifecycle op (`withWriterAccess()`)
660
+ * but not from other reads: unlike `queue`, concurrent reads run
661
+ * concurrently. Queuing them the same way `queue` serializes writes would
662
+ * head-of-line block an unrelated command, or even disconnect() itself,
663
+ * behind one slow reply (the binding correlates replies independently, so
664
+ * nothing requires this to be serial).
665
+ *
666
+ * Race-free the same way the wasm binding's own `readyState` check is: the
667
+ * `writerActive` check and this call's registration in `activeReads` both
668
+ * happen before the first `await` inside *fn*, so nothing can run between
669
+ * them on a single-threaded JS event loop.
670
+ */
671
+ private withReaderAccess;
672
+ /**
673
+ * Runs a lifecycle op's client-touching body exclusively: waits out every
674
+ * read already in flight, then blocks new ones (`writerActive`) until it
675
+ * finishes. Only ever called from inside a `queue`-serialized task, so at
676
+ * most one writer runs this at a time — it doesn't serialize against
677
+ * itself, only against `activeReads`.
678
+ */
679
+ private withWriterAccess;
642
680
  constructor(options: ReactorOptions);
643
681
  /**
644
682
  * `jwt`, when given, replaces whatever `new Reactor({ jwt })` was given —
@@ -680,9 +718,11 @@ declare class Reactor implements Disposable {
680
718
  * mode) actually hands back `null` — normalized here so callers can rely
681
719
  * on the documented type instead of the binding's serialization quirk.
682
720
  *
683
- * A `FileRef` (from `uploadFile`) may be passed as a top-level value in
684
- * `data` alongside regular parameters — it is extracted and sent as a
685
- * separate upload reference rather than embedded in the JSON payload.
721
+ * A `FileRef` (from `uploadFile`) may be passed in `data` wherever the
722
+ * model's schema declares a file. As a top-level value it is extracted and
723
+ * sent as a separate upload reference rather than embedded in the JSON
724
+ * payload; inside an array or object (a parameter that takes several files,
725
+ * say) it is serialized as an upload reference in place.
686
726
  *
687
727
  * Unlike every other method here, this never rejects — a failure (the
688
728
  * session isn't `"ready"`, the send itself fails, …) is reported through
@@ -759,6 +799,38 @@ declare class Reactor implements Disposable {
759
799
  * reconnect() for the same reason as `publishTrack()`.
760
800
  */
761
801
  pauseTrack(name: string): Promise<void>;
802
+ /**
803
+ * Bounds what one sender may spend, in bits per second.
804
+ *
805
+ * This is the ceiling that actually caps a video encoder, and it is easy to
806
+ * hit without knowing it exists: with nothing set, a Chromium-based browser
807
+ * derives a sender's maximum from the frame size alone, and that maximum is
808
+ * 2500 kbps for anything above 960x540. A 720p or 1080p publish caps at
809
+ * 2.5 Mbps until this raises it, however good the connection is.
810
+ *
811
+ * ```ts
812
+ * await reactor.publishTrack('camera', cameraTrack);
813
+ * await reactor.setTrackBitrate('camera', { maxBps: 8_000_000 });
814
+ * ```
815
+ *
816
+ * A ceiling is permission, not a target: the encoder still spends only what
817
+ * the congestion controller allocated and what the picture needs. What
818
+ * raising it buys is headroom for the moments that would otherwise clip.
819
+ *
820
+ * Needs a connected client, and a published track — there is no sender to
821
+ * bound before `publishTrack()`.
822
+ *
823
+ * Omit a bound to leave it at the browser default. `minBps` is non-standard —
824
+ * Chromium honours it, other engines ignore it.
825
+ *
826
+ * There is no connection-wide counterpart: browsers expose no equivalent of
827
+ * the native SDKs' `setBitrate`, and a method that quietly did nothing would
828
+ * be worse than its absence.
829
+ */
830
+ setTrackBitrate(name: string, bounds?: {
831
+ minBps?: number;
832
+ maxBps?: number;
833
+ }): Promise<void>;
762
834
  /** Resumes a track previously stopped with `pauseTrack()`. */
763
835
  resumeTrack(name: string): Promise<void>;
764
836
  /**
@@ -774,8 +846,9 @@ declare class Reactor implements Disposable {
774
846
  downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
775
847
  /**
776
848
  * Uploads a file to the session's object store, resolving with a
777
- * `FileRef` to pass as a top-level value in a `sendCommand()`'s `data`
778
- * (see `extractFileRefs`). The binding itself takes `(file, name?)`
849
+ * `FileRef` to pass in a `sendCommand()`'s `data`, at the top level or
850
+ * inside an array or object (see `extractFileRefs`). The binding itself
851
+ * takes `(file, name?)`
779
852
  * positionally and already applies the right defaulting — a bare
780
853
  * `Blob`'s name falls back to `"upload"`, and an empty/missing mime type
781
854
  * to `"application/octet-stream"` — so there's nothing to wrap here.
package/dist/index.d.ts CHANGED
@@ -155,10 +155,11 @@ declare class RecorderDisabledError extends ReactorError {
155
155
  }
156
156
 
157
157
  /**
158
- * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back as a
159
- * top-level value in `sendCommand()`'s `data` and it's extracted and sent as
160
- * a separate upload reference rather than embedded in the JSON payload —
161
- * see `extractFileRefs()`.
158
+ * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back in
159
+ * `sendCommand()`'s `data` wherever the model's schema declares a file: as a
160
+ * top-level value it's extracted and sent as a separate upload reference,
161
+ * and inside an array or object it's serialized as one — see
162
+ * `extractFileRefs()`.
162
163
  */
163
164
  declare class FileRef {
164
165
  readonly uploadId: string;
@@ -639,6 +640,43 @@ declare class Reactor implements Disposable {
639
640
  * take ownership of Rust value while it was borrowed") or corrupt it
640
641
  * outright. */
641
642
  private readonly queue;
643
+ /** In-flight calls to `withReaderAccess()` — a "reply" `.catch(() => {})`
644
+ * copy of each, never the caller's own promise, so one rejecting can't
645
+ * make `Promise.all()` in `withWriterAccess()` reject and skip waiting
646
+ * for the rest. See `withReaderAccess()`/`withWriterAccess()`. */
647
+ private readonly activeReads;
648
+ /** True for the span of a `withWriterAccess()` call — after it has waited
649
+ * out every read active when it started, before it releases the ones
650
+ * that arrived while it ran. */
651
+ private writerActive;
652
+ /** Readers parked in `withReaderAccess()`'s wait loop, woken once
653
+ * `withWriterAccess()` finishes; each re-checks `writerActive` rather
654
+ * than assuming its turn, since another writer already queued behind the
655
+ * first one may have claimed it first. */
656
+ private writerIdleWaiters;
657
+ /**
658
+ * Runs a read — sendCommand()/requestSchema()/requestClip()/
659
+ * requestRecording() — excluded from a lifecycle op (`withWriterAccess()`)
660
+ * but not from other reads: unlike `queue`, concurrent reads run
661
+ * concurrently. Queuing them the same way `queue` serializes writes would
662
+ * head-of-line block an unrelated command, or even disconnect() itself,
663
+ * behind one slow reply (the binding correlates replies independently, so
664
+ * nothing requires this to be serial).
665
+ *
666
+ * Race-free the same way the wasm binding's own `readyState` check is: the
667
+ * `writerActive` check and this call's registration in `activeReads` both
668
+ * happen before the first `await` inside *fn*, so nothing can run between
669
+ * them on a single-threaded JS event loop.
670
+ */
671
+ private withReaderAccess;
672
+ /**
673
+ * Runs a lifecycle op's client-touching body exclusively: waits out every
674
+ * read already in flight, then blocks new ones (`writerActive`) until it
675
+ * finishes. Only ever called from inside a `queue`-serialized task, so at
676
+ * most one writer runs this at a time — it doesn't serialize against
677
+ * itself, only against `activeReads`.
678
+ */
679
+ private withWriterAccess;
642
680
  constructor(options: ReactorOptions);
643
681
  /**
644
682
  * `jwt`, when given, replaces whatever `new Reactor({ jwt })` was given —
@@ -680,9 +718,11 @@ declare class Reactor implements Disposable {
680
718
  * mode) actually hands back `null` — normalized here so callers can rely
681
719
  * on the documented type instead of the binding's serialization quirk.
682
720
  *
683
- * A `FileRef` (from `uploadFile`) may be passed as a top-level value in
684
- * `data` alongside regular parameters — it is extracted and sent as a
685
- * separate upload reference rather than embedded in the JSON payload.
721
+ * A `FileRef` (from `uploadFile`) may be passed in `data` wherever the
722
+ * model's schema declares a file. As a top-level value it is extracted and
723
+ * sent as a separate upload reference rather than embedded in the JSON
724
+ * payload; inside an array or object (a parameter that takes several files,
725
+ * say) it is serialized as an upload reference in place.
686
726
  *
687
727
  * Unlike every other method here, this never rejects — a failure (the
688
728
  * session isn't `"ready"`, the send itself fails, …) is reported through
@@ -759,6 +799,38 @@ declare class Reactor implements Disposable {
759
799
  * reconnect() for the same reason as `publishTrack()`.
760
800
  */
761
801
  pauseTrack(name: string): Promise<void>;
802
+ /**
803
+ * Bounds what one sender may spend, in bits per second.
804
+ *
805
+ * This is the ceiling that actually caps a video encoder, and it is easy to
806
+ * hit without knowing it exists: with nothing set, a Chromium-based browser
807
+ * derives a sender's maximum from the frame size alone, and that maximum is
808
+ * 2500 kbps for anything above 960x540. A 720p or 1080p publish caps at
809
+ * 2.5 Mbps until this raises it, however good the connection is.
810
+ *
811
+ * ```ts
812
+ * await reactor.publishTrack('camera', cameraTrack);
813
+ * await reactor.setTrackBitrate('camera', { maxBps: 8_000_000 });
814
+ * ```
815
+ *
816
+ * A ceiling is permission, not a target: the encoder still spends only what
817
+ * the congestion controller allocated and what the picture needs. What
818
+ * raising it buys is headroom for the moments that would otherwise clip.
819
+ *
820
+ * Needs a connected client, and a published track — there is no sender to
821
+ * bound before `publishTrack()`.
822
+ *
823
+ * Omit a bound to leave it at the browser default. `minBps` is non-standard —
824
+ * Chromium honours it, other engines ignore it.
825
+ *
826
+ * There is no connection-wide counterpart: browsers expose no equivalent of
827
+ * the native SDKs' `setBitrate`, and a method that quietly did nothing would
828
+ * be worse than its absence.
829
+ */
830
+ setTrackBitrate(name: string, bounds?: {
831
+ minBps?: number;
832
+ maxBps?: number;
833
+ }): Promise<void>;
762
834
  /** Resumes a track previously stopped with `pauseTrack()`. */
763
835
  resumeTrack(name: string): Promise<void>;
764
836
  /**
@@ -774,8 +846,9 @@ declare class Reactor implements Disposable {
774
846
  downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
775
847
  /**
776
848
  * Uploads a file to the session's object store, resolving with a
777
- * `FileRef` to pass as a top-level value in a `sendCommand()`'s `data`
778
- * (see `extractFileRefs`). The binding itself takes `(file, name?)`
849
+ * `FileRef` to pass in a `sendCommand()`'s `data`, at the top level or
850
+ * inside an array or object (see `extractFileRefs`). The binding itself
851
+ * takes `(file, name?)`
779
852
  * positionally and already applies the right defaulting — a bare
780
853
  * `Blob`'s name falls back to `"upload"`, and an empty/missing mime type
781
854
  * to `"application/octet-stream"` — so there's nothing to wrap here.
package/dist/index.js CHANGED
@@ -244,16 +244,53 @@ function extractFileRefs(data) {
244
244
  let uploads;
245
245
  let scalars;
246
246
  for (const [key, value] of Object.entries(data)) {
247
- if (!isFileRef(value)) {
247
+ if (isFileRef(value)) {
248
+ uploads ??= {};
249
+ scalars ??= { ...data };
250
+ uploads[key] = toWireFileRef(value);
251
+ delete scalars[key];
248
252
  continue;
249
253
  }
250
- uploads ??= {};
251
- scalars ??= { ...data };
252
- uploads[key] = toWireFileRef(value);
253
- delete scalars[key];
254
+ const rewritten = rewriteNestedFileRefs(value);
255
+ if (rewritten !== value) {
256
+ scalars ??= { ...data };
257
+ scalars[key] = rewritten;
258
+ }
254
259
  }
255
260
  return { data: scalars ?? data, uploads };
256
261
  }
262
+ function rewriteNestedFileRefs(value) {
263
+ if (isFileRef(value)) {
264
+ return toWireFileRef(value);
265
+ }
266
+ if (Array.isArray(value)) {
267
+ const elements = value;
268
+ let copy;
269
+ elements.forEach((element, index) => {
270
+ const rewritten = rewriteNestedFileRefs(element);
271
+ if (rewritten !== element) {
272
+ copy ??= [...elements];
273
+ copy[index] = rewritten;
274
+ }
275
+ });
276
+ return copy ?? elements;
277
+ }
278
+ if (isSerializedAsObject(value)) {
279
+ let copy;
280
+ for (const [key, element] of Object.entries(value)) {
281
+ const rewritten = rewriteNestedFileRefs(element);
282
+ if (rewritten !== element) {
283
+ copy ??= { ...value };
284
+ copy[key] = rewritten;
285
+ }
286
+ }
287
+ return copy ?? value;
288
+ }
289
+ return value;
290
+ }
291
+ function isSerializedAsObject(value) {
292
+ return typeof value === "object" && value !== null && !ArrayBuffer.isView(value);
293
+ }
257
294
 
258
295
  // src/internal/recording.ts
259
296
  function toPublicClip(clip) {
@@ -372,6 +409,69 @@ async function importWasmModule() {
372
409
  return module;
373
410
  }
374
411
 
412
+ // package.json
413
+ var package_default = {
414
+ name: "@reactor-team/js-sdk",
415
+ version: "3.0.2",
416
+ description: "Connect your JavaScript/TypeScript app to a live Reactor model in the browser.",
417
+ license: "Apache-2.0",
418
+ repository: {
419
+ type: "git",
420
+ url: "git+https://github.com/reactor-team/reactor-client-sdks.git",
421
+ directory: "sdks/js"
422
+ },
423
+ type: "module",
424
+ sideEffects: false,
425
+ main: "./dist/index.cjs",
426
+ module: "./dist/index.js",
427
+ types: "./dist/index.d.ts",
428
+ exports: {
429
+ ".": {
430
+ types: "./dist/index.d.ts",
431
+ import: "./dist/index.js",
432
+ require: "./dist/index.cjs"
433
+ }
434
+ },
435
+ files: [
436
+ "dist"
437
+ ],
438
+ engines: {
439
+ node: ">=18"
440
+ },
441
+ scripts: {
442
+ build: "tsup && node scripts/copy-wasm.mjs",
443
+ prepack: "npm run build",
444
+ dev: "tsup --watch",
445
+ "type-check": "tsc --noEmit",
446
+ lint: "eslint .",
447
+ test: "vitest run",
448
+ clean: "rm -rf dist"
449
+ },
450
+ dependencies: {
451
+ awaitqueue: "^3.3.1",
452
+ "hls.js": "^1.6.0",
453
+ mp4box: "^2.4.1"
454
+ },
455
+ peerDependencies: {
456
+ react: "^18.0.0 || ^19.0.0"
457
+ },
458
+ devDependencies: {
459
+ "@eslint/js": "^9.39.5",
460
+ "@stylistic/eslint-plugin": "^5.10.0",
461
+ "@testing-library/react": "^16.0.0",
462
+ "@types/react": "^19.0.0",
463
+ eslint: "^9.39.5",
464
+ "eslint-plugin-react-hooks": "^5.0.0",
465
+ jsdom: "^25.0.0",
466
+ react: "^19.0.0",
467
+ "react-dom": "^19.0.0",
468
+ tsup: "^8.3.0",
469
+ typescript: "^5.6.0",
470
+ "typescript-eslint": "^8.67.0",
471
+ vitest: "^4.1.11"
472
+ }
473
+ };
474
+
375
475
  // src/recording.ts
376
476
  var RecordingError = class extends Error {
377
477
  constructor(code, reason) {
@@ -805,9 +905,73 @@ var Reactor = class {
805
905
  * take ownership of Rust value while it was borrowed") or corrupt it
806
906
  * outright. */
807
907
  queue = new AwaitQueue();
908
+ /** In-flight calls to `withReaderAccess()` — a "reply" `.catch(() => {})`
909
+ * copy of each, never the caller's own promise, so one rejecting can't
910
+ * make `Promise.all()` in `withWriterAccess()` reject and skip waiting
911
+ * for the rest. See `withReaderAccess()`/`withWriterAccess()`. */
912
+ activeReads = /* @__PURE__ */ new Set();
913
+ /** True for the span of a `withWriterAccess()` call — after it has waited
914
+ * out every read active when it started, before it releases the ones
915
+ * that arrived while it ran. */
916
+ writerActive = false;
917
+ /** Readers parked in `withReaderAccess()`'s wait loop, woken once
918
+ * `withWriterAccess()` finishes; each re-checks `writerActive` rather
919
+ * than assuming its turn, since another writer already queued behind the
920
+ * first one may have claimed it first. */
921
+ writerIdleWaiters = [];
922
+ /**
923
+ * Runs a read — sendCommand()/requestSchema()/requestClip()/
924
+ * requestRecording() — excluded from a lifecycle op (`withWriterAccess()`)
925
+ * but not from other reads: unlike `queue`, concurrent reads run
926
+ * concurrently. Queuing them the same way `queue` serializes writes would
927
+ * head-of-line block an unrelated command, or even disconnect() itself,
928
+ * behind one slow reply (the binding correlates replies independently, so
929
+ * nothing requires this to be serial).
930
+ *
931
+ * Race-free the same way the wasm binding's own `readyState` check is: the
932
+ * `writerActive` check and this call's registration in `activeReads` both
933
+ * happen before the first `await` inside *fn*, so nothing can run between
934
+ * them on a single-threaded JS event loop.
935
+ */
936
+ async withReaderAccess(fn) {
937
+ while (this.writerActive) {
938
+ await new Promise((resolve) => this.writerIdleWaiters.push(resolve));
939
+ }
940
+ const result = fn();
941
+ const tracked = result.catch(() => void 0);
942
+ this.activeReads.add(tracked);
943
+ try {
944
+ return await result;
945
+ } finally {
946
+ this.activeReads.delete(tracked);
947
+ }
948
+ }
949
+ /**
950
+ * Runs a lifecycle op's client-touching body exclusively: waits out every
951
+ * read already in flight, then blocks new ones (`writerActive`) until it
952
+ * finishes. Only ever called from inside a `queue`-serialized task, so at
953
+ * most one writer runs this at a time — it doesn't serialize against
954
+ * itself, only against `activeReads`.
955
+ */
956
+ async withWriterAccess(fn) {
957
+ this.writerActive = true;
958
+ if (this.activeReads.size > 0) {
959
+ await Promise.all(this.activeReads);
960
+ }
961
+ try {
962
+ return await fn();
963
+ } finally {
964
+ this.writerActive = false;
965
+ const waiters = this.writerIdleWaiters;
966
+ this.writerIdleWaiters = [];
967
+ for (const wake of waiters) {
968
+ wake();
969
+ }
970
+ }
971
+ }
808
972
  constructor(options) {
809
973
  const { jwt, ...clientOptions } = options;
810
- this.clientOptions = clientOptions;
974
+ this.clientOptions = { sdkVersion: package_default.version, ...clientOptions };
811
975
  this.jwt = jwt ?? null;
812
976
  }
813
977
  // ── Lifecycle ───────────────────────────────────────────────────────────
@@ -828,10 +992,13 @@ var Reactor = class {
828
992
  this.jwt = jwt;
829
993
  this.client?.setJwt(jwt);
830
994
  }
831
- await this.queue.push(async () => {
832
- const client = await this.getOrCreateClient();
833
- await client.connect(options);
834
- }, "connect");
995
+ await this.queue.push(
996
+ () => this.withWriterAccess(async () => {
997
+ const client = await this.getOrCreateClient();
998
+ await client.connect(options);
999
+ }),
1000
+ "connect"
1001
+ );
835
1002
  } catch (cause) {
836
1003
  throw this.captureError(cause);
837
1004
  }
@@ -854,15 +1021,18 @@ var Reactor = class {
854
1021
  async disconnect(recoverable = false) {
855
1022
  this.assertNotDisposed();
856
1023
  try {
857
- await this.queue.push(async () => {
858
- if (this.client) {
859
- await this.client.disconnect();
860
- }
861
- this.resetConnectionState();
862
- if (!recoverable) {
863
- this.freeClient();
864
- }
865
- }, "disconnect");
1024
+ await this.queue.push(
1025
+ () => this.withWriterAccess(async () => {
1026
+ if (this.client) {
1027
+ await this.client.disconnect();
1028
+ }
1029
+ this.resetConnectionState();
1030
+ if (!recoverable) {
1031
+ this.freeClient();
1032
+ }
1033
+ }),
1034
+ "disconnect"
1035
+ );
866
1036
  } catch (cause) {
867
1037
  throw this.captureError(cause);
868
1038
  }
@@ -876,10 +1046,13 @@ var Reactor = class {
876
1046
  async reconnect(options) {
877
1047
  this.assertNotDisposed();
878
1048
  try {
879
- await this.queue.push(async () => {
880
- const client = await this.getOrCreateClient();
881
- await client.reconnect(options);
882
- }, "reconnect");
1049
+ await this.queue.push(
1050
+ () => this.withWriterAccess(async () => {
1051
+ const client = await this.getOrCreateClient();
1052
+ await client.reconnect(options);
1053
+ }),
1054
+ "reconnect"
1055
+ );
883
1056
  } catch (cause) {
884
1057
  throw this.captureError(cause);
885
1058
  }
@@ -894,9 +1067,11 @@ var Reactor = class {
894
1067
  * mode) actually hands back `null` — normalized here so callers can rely
895
1068
  * on the documented type instead of the binding's serialization quirk.
896
1069
  *
897
- * A `FileRef` (from `uploadFile`) may be passed as a top-level value in
898
- * `data` alongside regular parameters — it is extracted and sent as a
899
- * separate upload reference rather than embedded in the JSON payload.
1070
+ * A `FileRef` (from `uploadFile`) may be passed in `data` wherever the
1071
+ * model's schema declares a file. As a top-level value it is extracted and
1072
+ * sent as a separate upload reference rather than embedded in the JSON
1073
+ * payload; inside an array or object (a parameter that takes several files,
1074
+ * say) it is serialized as an upload reference in place.
900
1075
  *
901
1076
  * Unlike every other method here, this never rejects — a failure (the
902
1077
  * session isn't `"ready"`, the send itself fails, …) is reported through
@@ -918,9 +1093,11 @@ var Reactor = class {
918
1093
  }
919
1094
  try {
920
1095
  this.assertNotDisposed();
921
- const client = await this.getOrCreateClient();
922
1096
  const extracted = extractFileRefs(data);
923
- const reply = await client.sendCommand(command, extracted.data, extracted.uploads);
1097
+ const reply = await this.withReaderAccess(async () => {
1098
+ const client = await this.getOrCreateClient();
1099
+ return client.sendCommand(command, extracted.data, extracted.uploads);
1100
+ });
924
1101
  return reply ?? void 0;
925
1102
  } catch (cause) {
926
1103
  this.emitError(cause);
@@ -947,8 +1124,10 @@ var Reactor = class {
947
1124
  switch (command) {
948
1125
  case "requestSchema":
949
1126
  try {
950
- const client = await this.getOrCreateClient();
951
- await this.refreshSchema(client);
1127
+ await this.withReaderAccess(async () => {
1128
+ const client = await this.getOrCreateClient();
1129
+ await this.refreshSchema(client);
1130
+ });
952
1131
  } catch (cause) {
953
1132
  this.emitError(cause);
954
1133
  }
@@ -970,8 +1149,10 @@ var Reactor = class {
970
1149
  async requestSchema() {
971
1150
  this.assertNotDisposed();
972
1151
  try {
973
- const client = await this.getOrCreateClient();
974
- return this.normalizeSchema(await client.requestSchema());
1152
+ return await this.withReaderAccess(async () => {
1153
+ const client = await this.getOrCreateClient();
1154
+ return this.normalizeSchema(await client.requestSchema());
1155
+ });
975
1156
  } catch (cause) {
976
1157
  throw this.captureError(cause);
977
1158
  }
@@ -1050,6 +1231,45 @@ var Reactor = class {
1050
1231
  throw this.captureError(cause);
1051
1232
  }
1052
1233
  }
1234
+ /**
1235
+ * Bounds what one sender may spend, in bits per second.
1236
+ *
1237
+ * This is the ceiling that actually caps a video encoder, and it is easy to
1238
+ * hit without knowing it exists: with nothing set, a Chromium-based browser
1239
+ * derives a sender's maximum from the frame size alone, and that maximum is
1240
+ * 2500 kbps for anything above 960x540. A 720p or 1080p publish caps at
1241
+ * 2.5 Mbps until this raises it, however good the connection is.
1242
+ *
1243
+ * ```ts
1244
+ * await reactor.publishTrack('camera', cameraTrack);
1245
+ * await reactor.setTrackBitrate('camera', { maxBps: 8_000_000 });
1246
+ * ```
1247
+ *
1248
+ * A ceiling is permission, not a target: the encoder still spends only what
1249
+ * the congestion controller allocated and what the picture needs. What
1250
+ * raising it buys is headroom for the moments that would otherwise clip.
1251
+ *
1252
+ * Needs a connected client, and a published track — there is no sender to
1253
+ * bound before `publishTrack()`.
1254
+ *
1255
+ * Omit a bound to leave it at the browser default. `minBps` is non-standard —
1256
+ * Chromium honours it, other engines ignore it.
1257
+ *
1258
+ * There is no connection-wide counterpart: browsers expose no equivalent of
1259
+ * the native SDKs' `setBitrate`, and a method that quietly did nothing would
1260
+ * be worse than its absence.
1261
+ */
1262
+ async setTrackBitrate(name, bounds = {}) {
1263
+ this.assertNotDisposed();
1264
+ try {
1265
+ await this.queue.push(async () => {
1266
+ const client = await this.getOrCreateClient();
1267
+ await client.setTrackBitrate(name, bounds.minBps, bounds.maxBps);
1268
+ }, "setTrackBitrate");
1269
+ } catch (cause) {
1270
+ throw this.captureError(cause);
1271
+ }
1272
+ }
1053
1273
  /** Resumes a track previously stopped with `pauseTrack()`. */
1054
1274
  async resumeTrack(name) {
1055
1275
  this.assertNotDisposed();
@@ -1072,8 +1292,10 @@ var Reactor = class {
1072
1292
  async requestClip(durationSeconds) {
1073
1293
  this.assertNotDisposed();
1074
1294
  try {
1075
- const client = await this.getOrCreateClient();
1076
- return toPublicClip(await client.requestClip(durationSeconds));
1295
+ return await this.withReaderAccess(async () => {
1296
+ const client = await this.getOrCreateClient();
1297
+ return toPublicClip(await client.requestClip(durationSeconds));
1298
+ });
1077
1299
  } catch (cause) {
1078
1300
  throw this.captureError(cause);
1079
1301
  }
@@ -1082,8 +1304,10 @@ var Reactor = class {
1082
1304
  async requestRecording() {
1083
1305
  this.assertNotDisposed();
1084
1306
  try {
1085
- const client = await this.getOrCreateClient();
1086
- return toPublicClip(await client.requestRecording());
1307
+ return await this.withReaderAccess(async () => {
1308
+ const client = await this.getOrCreateClient();
1309
+ return toPublicClip(await client.requestRecording());
1310
+ });
1087
1311
  } catch (cause) {
1088
1312
  throw this.captureError(cause);
1089
1313
  }
@@ -1095,8 +1319,9 @@ var Reactor = class {
1095
1319
  // ── Uploads ─────────────────────────────────────────────────────────────
1096
1320
  /**
1097
1321
  * Uploads a file to the session's object store, resolving with a
1098
- * `FileRef` to pass as a top-level value in a `sendCommand()`'s `data`
1099
- * (see `extractFileRefs`). The binding itself takes `(file, name?)`
1322
+ * `FileRef` to pass in a `sendCommand()`'s `data`, at the top level or
1323
+ * inside an array or object (see `extractFileRefs`). The binding itself
1324
+ * takes `(file, name?)`
1100
1325
  * positionally and already applies the right defaulting — a bare
1101
1326
  * `Blob`'s name falls back to `"upload"`, and an empty/missing mime type
1102
1327
  * to `"application/octet-stream"` — so there's nothing to wrap here.
@@ -1170,7 +1395,7 @@ var Reactor = class {
1170
1395
  this.resetConnectionState();
1171
1396
  this.emitter.clear();
1172
1397
  if (client) {
1173
- void this.queue.push(() => client.free(), "dispose").catch(() => {
1398
+ void this.queue.push(() => this.withWriterAccess(() => Promise.resolve(client.free())), "dispose").catch(() => {
1174
1399
  });
1175
1400
  }
1176
1401
  }