@ksp-gonogo/kerbcast-react 1.12.0-rc.4 → 1.12.0-rc.5

package/README.md

@@ -181,7 +181,11 @@ quality follows how large it is shown (pass `reportSize={false}` to opt out).
   feed primitives use it internally; multiple views of one camera from a
   client collapse to a single MAX report. Pass `aspect` for the shape to ask
   for (default 16:9), and `videoRef` / `streamSize` so a resize that follows
-  the stream is not reported.
+  the stream is not reported. A request is never under `MIN_DISPLAY_REPORT_PX`
+  (128) on either axis: a smaller box asks for that much at the camera's
+  shape. An empty box (a hidden or not yet laid out tile) reports nothing.
+  When the last feed of a camera empties, the client tells the sidecar it no
+  longer needs a size, so the camera stops rendering for a box nobody sees.
 
 - `useKerbcastCameras(): CameraState[]`. The live camera registry,
   re-rendering as cameras appear, change, or are destroyed.

package/dist/context.js

@@ -158,11 +158,15 @@ export function createClientDisplaySizes(client) {
     function recompute(flightId) {
         const instances = perCamera.get(flightId);
         if (!instances || instances.size === 0) {
-            // No reporters left. Drop bookkeeping and send nothing: the subscription
-            // release (unsubscribe -> sidecar remove_track -> forget_display_size)
-            // clears the sidecar side. Sending a spurious size here would fight it.
+            /*
+             * No reporters left, as when the last feed showing the camera is hidden
+             * while still subscribed. A 0x0 report is no demand to the sidecar, so
+             * the camera stops rendering at a size nobody sees. An unsubscribe that
+             * follows clears the same entry, so the two never disagree.
+             */
             perCamera.delete(flightId);
-            lastSent.delete(flightId);
+            if (lastSent.delete(flightId))
+                client.reportDisplaySize(flightId, 0, 0).catch(() => { });
             return;
         }
         let maxW = 0;

package/dist/hooks/useReportDisplaySize.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The smallest request on either axis: a small box asks for this much, at the
+ * camera's shape, because hardware encoders refuse to encode tinier frames.
+ */
+export declare const MIN_DISPLAY_REPORT_PX = 128;
 /** Shape of a camera whose configured capture size is not known. */
 export declare const DEFAULT_FEED_ASPECT: number;
 /**

package/dist/hooks/useReportDisplaySize.js

@@ -38,6 +38,13 @@ const SUSPECT_MS = 2500;
 const HOLD_MS = 5000;
 const ASPECT_TOLERANCE = 0.06;
 const MAGNITUDE_SLACK = 1.15;
+/**
+ * The smallest request on either axis: a small box asks for this much, at the
+ * camera's shape, because hardware encoders refuse to encode tinier frames.
+ */
+export const MIN_DISPLAY_REPORT_PX = 128;
+/* A box under this on either axis (hidden, or not yet laid out) is no demand, matching the sidecar. */
+const EMPTY_BOX_PX = 2;
 function bucket(px) {
     const b = Math.ceil(px / BUCKET_PX) * BUCKET_PX;
     return b < BUCKET_PX ? BUCKET_PX : b;
@@ -51,8 +58,15 @@ export const DEFAULT_FEED_ASPECT = 16 / 9;
 export function displayReportSize(width, height, aspect = DEFAULT_FEED_ASPECT) {
     const a = aspect > 0 && Number.isFinite(aspect) ? aspect : DEFAULT_FEED_ASPECT;
     const fit = width > 0 && height > 0 ? Math.min(width, height * a) : width;
-    const w = bucket(fit);
-    return { width: w, height: Math.max(2, Math.round(w / a / 2) * 2) };
+    let w = bucket(fit);
+    if (w < MIN_DISPLAY_REPORT_PX)
+        w = bucket(MIN_DISPLAY_REPORT_PX);
+    if (w / a < MIN_DISPLAY_REPORT_PX)
+        w = bucket(MIN_DISPLAY_REPORT_PX * a);
+    return { width: w, height: Math.round(w / a / 2) * 2 };
+}
+function isEmpty(box) {
+    return !(box.width >= EMPTY_BOX_PX) || !(box.height >= EMPTY_BOX_PX);
 }
 function spread(a, b) {
     return a > b ? a / b : b / a;
@@ -179,7 +193,7 @@ export function useReportDisplaySize(flightId, ref, { enabled = true, square = f
         const sizeFor = (box) => {
             if (!square)
                 return displayReportSize(box.width, box.height, aspectRef.current);
-            const side = bucket(Math.min(box.width, box.height));
+            const side = Math.max(MIN_DISPLAY_REPORT_PX, bucket(Math.min(box.width, box.height)));
             return { width: side, height: side };
         };
         const send = ({ width, height }) => {
@@ -187,6 +201,13 @@ export function useReportDisplaySize(flightId, ref, { enabled = true, square = f
             lastH = height;
             displaySizes.report(flightId, instanceId, width, height);
         };
+        const withdraw = () => {
+            if (lastW < 0)
+                return;
+            lastW = -1;
+            lastH = -1;
+            displaySizes.clear(flightId, instanceId);
+        };
         /*
          * Judged when the debounce settles, so a stream change noted a little after
          * the observer fired (a host that commits the stream and the box in a
@@ -200,10 +221,15 @@ export function useReportDisplaySize(flightId, ref, { enabled = true, square = f
             if (prev && near.some((c) => c.at >= seenAt - FOLLOW_MS && followsStream(prev, box, c))) {
                 return;
             }
+            if (isEmpty(box)) {
+                withdraw();
+                return;
+            }
             const next = sizeFor(box);
             if (next.width === lastW && next.height === lastH)
                 return;
-            if (near.length > 0) {
+            /* With nothing reported since a withdraw there is no loop to break. */
+            if (near.length > 0 && lastW >= 0) {
                 const held = now - lastSuspectAt < HOLD_MS;
                 lastSuspectAt = now;
                 if (held)
@@ -216,6 +242,9 @@ export function useReportDisplaySize(flightId, ref, { enabled = true, square = f
             if (!entry)
                 return;
             const box = { width: entry.contentRect.width, height: entry.contentRect.height };
+            /* Until the box is first laid out, every measurement counts as the first, so it reports promptly. */
+            if (!firstReported && isEmpty(box))
+                return;
             if (!firstReported) {
                 firstReported = true;
                 baseline = box;
@@ -231,7 +260,7 @@ export function useReportDisplaySize(flightId, ref, { enabled = true, square = f
         });
         observer.observe(el);
         reapply.current = () => {
-            if (!baseline)
+            if (!baseline || isEmpty(baseline))
                 return;
             const next = sizeFor(baseline);
             if (next.width !== lastW || next.height !== lastH)

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 export { useKerbcastWaitingForSlot } from "./hooks/useKerbcastWaitingForSlot";
-export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+export { useReportDisplaySize, MIN_DISPLAY_REPORT_PX } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
 export type { RecordingsStore, ActiveRecordingInfo } from "./hooks/useRecordings";
 export { nowMs, formatElapsed } from "./timing";

package/dist/index.js

@@ -14,7 +14,7 @@ export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 export { useKerbcastWaitingForSlot } from "./hooks/useKerbcastWaitingForSlot";
-export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+export { useReportDisplaySize, MIN_DISPLAY_REPORT_PX } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
 // Shared elapsed-timer helpers (REC badges, RecGroupBar's toolbar)
 export { nowMs, formatElapsed } from "./timing";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksp-gonogo/kerbcast-react",
-  "version": "1.12.0-rc.4",
+  "version": "1.12.0-rc.5",
   "description": "React components and hooks for kerbcast camera feeds.",
   "license": "MIT",
   "author": "Jon Pepler",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@ksp-gonogo/kerbcast": "^1.12.0-rc.4"
+    "@ksp-gonogo/kerbcast": "^1.12.0-rc.5"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/CameraFeed.test.tsx

@@ -1043,6 +1043,85 @@ describe("CameraFeed - stall presentation (showStatic)", () => {
     }
   });
 
+  it("data-kc-signal reads none while an auto-reconnect rebuilds the peer, then stalled, then live", async () => {
+    const env = installStallEnv();
+    try {
+      const sidecar = new MockSidecar();
+      sidecar.addCamera(toInit(makeCamera({ flightId: 42, cameraName: "Starboard Cam" })));
+      const client = new KerbcastClient(
+        { host: "h", port: 1, negotiate: (o) => sidecar.negotiate(o), autoReconnect: { initialDelayMs: 1 } },
+        sidecar.createTransport(),
+      );
+      createdClients.push(client);
+      await act(async () => {
+        await client.connect([], { slots: 4 });
+      });
+      await act(async () => {
+        sidecar.open();
+        sidecar.setConnectionState("connected");
+      });
+      const { container } = renderFeed(client, { flightId: 42 });
+      const signal = () => container.querySelector("[data-kc-signal]")?.getAttribute("data-kc-signal");
+      await act(async () => {
+        sidecar.deliverTrack(sidecar.slotMidFor(42) as string, {} as MediaStreamTrack);
+      });
+      env.setNow(1000);
+      await act(async () => {
+        env.fireFrame();
+        env.drawOnce();
+      });
+      expect(signal()).toBe("live");
+
+      const reconnected = new Promise<void>((resolve) => {
+        const off = client.on("reconnect-attempt", () => {
+          off();
+          resolve();
+        });
+      });
+      await act(async () => {
+        sidecar.setConnectionState("failed");
+      });
+      expect(signal()).toBe("none");
+      await act(async () => {
+        await reconnected;
+      });
+      expect(signal()).toBe("none");
+
+      /* The mock outlives the peer, so the re-subscribe binds a slot of its own. */
+      let reboundMid: string | undefined;
+      sidecar.onSubscribe((flightId, mid) => {
+        if (flightId === 42) reboundMid = mid;
+      });
+      await act(async () => {
+        sidecar.open();
+        sidecar.setConnectionState("connected");
+      });
+      expect(signal()).toBe("none");
+      await act(async () => {
+        sidecar.deliverTrack(reboundMid as string, {} as MediaStreamTrack);
+      });
+      env.setNow(2000);
+      await act(async () => {
+        env.drawOnce();
+      });
+      /* A fresh source with no frame yet never reads live. */
+      expect(signal()).toBe("stalled");
+      env.setNow(2601);
+      await act(async () => {
+        env.drawOnce();
+      });
+      expect(signal()).toBe("stalled");
+
+      await act(async () => {
+        env.fireFrame();
+        env.drawOnce();
+      });
+      expect(signal()).toBe("live");
+    } finally {
+      env.restore();
+    }
+  });
+
   it("data-kc-signal reads stalled for a source that never delivers a frame", async () => {
     const env = installStallEnv();
     try {
@@ -1848,7 +1927,8 @@ describe("CameraFeed - render size in a narrow, tall tile", () => {
     const { client, sidecar } = await connect();
     renderFeed(client, { flightId: 42 });
     await run(500);
-    expect(sizeReports(sidecar)).toEqual([{ flightId: 42, width: 176, height: 100 }]);
+    /* 176x99 at 16:9, raised so the height meets the floor. */
+    expect(sizeReports(sidecar)).toEqual([{ flightId: 42, width: 240, height: 136 }]);
   });
 
   it("sends no request when the stream comes back smaller, larger or another shape", async () => {

package/src/KerbalFaceFeed.test.tsx

@@ -152,14 +152,14 @@ describe("KerbalFaceFeed - reporting + showActions", () => {
       </KerbcastProvider>,
     );
     // A non-square measured box still reports square (min edge, bucketed): the
-    // face capture is square, so 50x40 -> min 40 -> 48x48.
+    // face capture is square, so 50x40 -> min 40 -> 48x48, raised to the 128 floor.
     act(() => {
       resizeCallback?.(
         [{ contentRect: { width: 50, height: 40 } }] as ResizeObserverEntry[],
         {} as ResizeObserver,
       );
     });
-    expect(reports.at(-1)).toEqual({ flightId: KERBAL_ID, w: 48, h: 48 });
+    expect(reports.at(-1)).toEqual({ flightId: KERBAL_ID, w: 128, h: 128 });
   });
 
   it("does not report when reportSize is false", async () => {

package/src/context.test.tsx

@@ -80,13 +80,27 @@ describe("createClientDisplaySizes", () => {
     expect(reports.at(-1)).toEqual({ flightId: 1, width: 40, height: 40 });
   });
 
-  it("sends nothing more once the last reporter departs (backend forget clears it)", () => {
+  it("withdraws the size with a 0x0 report once the last reporter departs, once", () => {
+    const { client, reports } = fakeClient();
+    const reg = createClientDisplaySizes(client);
+    reg.report(1, "a", 400, 400);
+    reg.report(1, "b", 200, 200);
+    reg.clear(1, "b");
+    expect(reports).toEqual([{ flightId: 1, width: 400, height: 400 }]);
+    reg.clear(1, "a");
+    expect(reports.at(-1)).toEqual({ flightId: 1, width: 0, height: 0 });
+    reg.clear(1, "a");
+    expect(reports).toHaveLength(2);
+    /* A feed laid out again reports afresh. */
+    reg.report(1, "a", 400, 400);
+    expect(reports.at(-1)).toEqual({ flightId: 1, width: 400, height: 400 });
+  });
+
+  it("sends nothing for a camera that never reported", () => {
     const { client, reports } = fakeClient();
     const reg = createClientDisplaySizes(client);
-    reg.report(1, "a", 40, 40);
-    const countBefore = reports.length;
     reg.clear(1, "a");
-    expect(reports.length).toBe(countBefore); // no extra report on empty
+    expect(reports).toEqual([]);
   });
 
   it("keeps separate maxes per flightId", () => {

package/src/context.tsx

@@ -226,11 +226,14 @@ export function createClientDisplaySizes(
   function recompute(flightId: number): void {
     const instances = perCamera.get(flightId);
     if (!instances || instances.size === 0) {
-      // No reporters left. Drop bookkeeping and send nothing: the subscription
-      // release (unsubscribe -> sidecar remove_track -> forget_display_size)
-      // clears the sidecar side. Sending a spurious size here would fight it.
+      /*
+       * No reporters left, as when the last feed showing the camera is hidden
+       * while still subscribed. A 0x0 report is no demand to the sidecar, so
+       * the camera stops rendering at a size nobody sees. An unsubscribe that
+       * follows clears the same entry, so the two never disagree.
+       */
       perCamera.delete(flightId);
-      lastSent.delete(flightId);
+      if (lastSent.delete(flightId)) client.reportDisplaySize(flightId, 0, 0).catch(() => {});
       return;
     }
     let maxW = 0;

package/src/hooks/useReportDisplaySize.loop.test.tsx

@@ -172,7 +172,7 @@ function mount(mode: Mode, sidecar = makeSidecar()) {
 
 beforeEach(() => {
   vi.useFakeTimers();
-  tile = { width: 170, height: 400 };
+  tile = { width: 340, height: 800 };
   watched = [];
   globalThis.ResizeObserver = class {
     private readonly cb: ResizeObserverCallback;
@@ -198,13 +198,13 @@ describe("useReportDisplaySize: a box sized from the stream", () => {
   it("asks once for a tile sized by layout, at 16:9 whatever the tile's shape", () => {
     const sidecar = mount("tile");
     run(5000);
-    expect(sidecar.reports).toEqual([{ width: 176, height: 100 }]);
+    expect(sidecar.reports).toEqual([{ width: 352, height: 198 }]);
   });
 
   it("settles after the first request when the frame keeps the stream's aspect", () => {
     const sidecar = mount("fit");
     run(10_000);
-    expect(sidecar.reports).toEqual([{ width: 176, height: 100 }]);
+    expect(sidecar.reports).toEqual([{ width: 352, height: 198 }]);
   });
 
   it("does not ratchet down when a video at its own size arrives smaller than asked", () => {
@@ -278,11 +278,32 @@ describe("useReportDisplaySize: a genuine layout change", () => {
     expect(sidecar.reports.slice(before)).toEqual([{ width: 320, height: 180 }]);
   });
 
+  it("reports a tile shown again right after a stream change, even inside the hold", () => {
+    const sidecar = mount("tile");
+    run(5000);
+    const before = sidecar.reports.length;
+    /* A resize near a stream change uses up the hold. */
+    sidecar.streamBecomes({ width: 400, height: 300 });
+    resizeTile({ width: 640, height: 400 });
+    run(500);
+    expect(sidecar.reports.slice(before)).toEqual([{ width: 640, height: 360 }]);
+    /* Hidden, then shown again next to another stream change. */
+    resizeTile({ width: 0, height: 0 });
+    run(500);
+    sidecar.streamBecomes({ width: 200, height: 150 });
+    resizeTile({ width: 960, height: 600 });
+    run(500);
+    expect(sidecar.reports.slice(before)).toEqual([
+      { width: 640, height: 360 },
+      { width: 960, height: 540 },
+    ]);
+  });
+
   it("still reports a resize right after a stream change that the stream can not explain", () => {
     const sidecar = mount("fit");
     run(10_000);
     const before = sidecar.reports.length;
-    sidecar.streamBecomes({ width: 160, height: 90 });
+    sidecar.streamBecomes({ width: 320, height: 180 });
     resizeTile({ width: 640, height: 400 });
     run(1000);
     expect(sidecar.reports.slice(before)).toEqual([{ width: 640, height: 360 }]);

package/src/hooks/useReportDisplaySize.test.tsx

@@ -11,7 +11,7 @@ import { useRef } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { KerbcastProvider, type KerbcastDisplaySizes } from "../context";
-import { displayReportSize, useReportDisplaySize } from "./useReportDisplaySize";
+import { displayReportSize, MIN_DISPLAY_REPORT_PX, useReportDisplaySize } from "./useReportDisplaySize";
 
 // A controllable ResizeObserver: captures the callback so a test can fire a
 // resize with a chosen contentRect.
@@ -89,16 +89,16 @@ describe("useReportDisplaySize", () => {
         <Harness flightId={7} />
       </KerbcastProvider>,
     );
-    // 40x30 -> width ceiled to a 16-multiple (48), height at 16:9 rounded to even (28), reported without advancing timers.
-    fireResize(40, 30);
-    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 48, h: 28 }]);
+    // 440x330 -> width ceiled to a 16-multiple (448), height at 16:9 rounded to even (252), reported without advancing timers.
+    fireResize(440, 330);
+    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 448, h: 252 }]);
   });
 
   it("asks for the 16:9 picture that fits the box, never the box's shape", () => {
     expect(displayReportSize(1024, 576)).toEqual({ width: 1024, height: 576 });
     expect(displayReportSize(441, 246)).toEqual({ width: 448, height: 252 });
-    // A narrow, tall tile is limited by its width.
-    expect(displayReportSize(170, 400)).toEqual({ width: 176, height: 100 });
+    // A narrow, tall tile is limited by its width, then raised so the height meets the floor.
+    expect(displayReportSize(170, 400)).toEqual({ width: 240, height: 136 });
     // A wide, short one by its height: the letterboxed picture is ~356x200.
     expect(displayReportSize(800, 200)).toEqual({ width: 368, height: 208 });
   });
@@ -110,9 +110,9 @@ describe("useReportDisplaySize", () => {
         <Harness flightId={7} square />
       </KerbcastProvider>,
     );
-    // min(50,40)=40 -> 48x48 square.
-    fireResize(50, 40);
-    expect(reports.at(-1)).toMatchObject({ w: 48, h: 48 });
+    // min(250,200)=200 -> 208x208 square.
+    fireResize(250, 200);
+    expect(reports.at(-1)).toMatchObject({ w: 208, h: 208 });
   });
 
   it("debounces churn after the first report", () => {
@@ -122,12 +122,12 @@ describe("useReportDisplaySize", () => {
         <Harness flightId={7} />
       </KerbcastProvider>,
     );
-    fireResize(48, 48); // prompt first -> 48x28
-    fireResize(200, 200); // debounced, not yet applied
+    fireResize(300, 300); // prompt first -> 304x172
+    fireResize(600, 600); // debounced, not yet applied
     expect(reports).toHaveLength(1);
     act(() => vi.advanceTimersByTime(200));
-    // 200 -> 208 wide at 16:9; the debounced resize now lands.
-    expect(reports.at(-1)).toMatchObject({ w: 208, h: 118 });
+    // 600 -> 608 wide at 16:9; the debounced resize now lands.
+    expect(reports.at(-1)).toMatchObject({ w: 608, h: 342 });
   });
 
   it("does not re-report a sub-bucket change", () => {
@@ -137,8 +137,8 @@ describe("useReportDisplaySize", () => {
         <Harness flightId={7} />
       </KerbcastProvider>,
     );
-    fireResize(40, 40); // -> 48x28
-    fireResize(44, 44); // still ceils to 48x28 -> no new report
+    fireResize(290, 290); // -> 304x172
+    fireResize(300, 300); // still ceils to 304x172 -> no new report
     act(() => vi.advanceTimersByTime(200));
     expect(reports).toHaveLength(1);
   });
@@ -150,7 +150,7 @@ describe("useReportDisplaySize", () => {
         <Harness flightId={7} />
       </KerbcastProvider>,
     );
-    fireResize(40, 40);
+    fireResize(400, 400);
     const id = reports[0].id;
     act(() => unmount());
     expect(clears).toEqual([{ flightId: 7, id }]);
@@ -189,7 +189,74 @@ describe("useReportDisplaySize", () => {
     const { rerender } = render(view(false));
     expect(resizeCallback).toBeUndefined();
     rerender(view(true));
-    fireResize(40, 30);
-    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 48, h: 28 }]);
+    fireResize(440, 330);
+    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 448, h: 252 }]);
+  });
+
+  it("never asks for less than the floor on either axis", () => {
+    for (const [w, h] of [[16, 10], [1, 1], [140, 130], [130, 2000], [4000, 130]]) {
+      const size = displayReportSize(w, h);
+      expect(size.width).toBeGreaterThanOrEqual(MIN_DISPLAY_REPORT_PX);
+      expect(size.height).toBeGreaterThanOrEqual(MIN_DISPLAY_REPORT_PX);
+    }
+    // A tall camera is held to the floor by its width.
+    expect(displayReportSize(16, 10, 9 / 16)).toEqual({ width: 128, height: 228 });
+  });
+
+  it("reports nothing for an empty box, then reports the first laid out box promptly", () => {
+    const { displaySizes, reports, clears } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} />
+      </KerbcastProvider>,
+    );
+    fireResize(0, 0);
+    fireResize(400, 1);
+    act(() => vi.advanceTimersByTime(1000));
+    expect(reports).toEqual([]);
+    expect(clears).toEqual([]);
+    fireResize(440, 330);
+    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 448, h: 252 }]);
+  });
+
+  it("withdraws its size when the box empties, and reports again when it is laid out again", () => {
+    const { displaySizes, reports, clears } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} />
+      </KerbcastProvider>,
+    );
+    fireResize(440, 330);
+    const id = reports[0].id;
+    fireResize(0, 0);
+    act(() => vi.advanceTimersByTime(200));
+    expect(clears).toEqual([{ flightId: 7, id }]);
+    expect(reports).toHaveLength(1);
+    fireResize(440, 330);
+    act(() => vi.advanceTimersByTime(200));
+    expect(reports).toHaveLength(2);
+    expect(reports.at(-1)).toMatchObject({ w: 448, h: 252 });
+  });
+
+  it("raises a small box's request to the floor", () => {
+    const { displaySizes, reports } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} />
+      </KerbcastProvider>,
+    );
+    fireResize(18, 10);
+    expect(reports).toEqual([{ flightId: 7, id: expect.any(String), w: 240, h: 136 }]);
+  });
+
+  it("raises a small square box's request to the floor", () => {
+    const { displaySizes, reports } = recordingRegistry();
+    render(
+      <KerbcastProvider client={fakeClient} displaySizes={displaySizes}>
+        <Harness flightId={7} square />
+      </KerbcastProvider>,
+    );
+    fireResize(50, 40);
+    expect(reports.at(-1)).toMatchObject({ w: 128, h: 128 });
   });
 });

package/src/hooks/useReportDisplaySize.ts

@@ -41,6 +41,15 @@ const HOLD_MS = 5000;
 const ASPECT_TOLERANCE = 0.06;
 const MAGNITUDE_SLACK = 1.15;
 
+/**
+ * The smallest request on either axis: a small box asks for this much, at the
+ * camera's shape, because hardware encoders refuse to encode tinier frames.
+ */
+export const MIN_DISPLAY_REPORT_PX = 128;
+
+/* A box under this on either axis (hidden, or not yet laid out) is no demand, matching the sidecar. */
+const EMPTY_BOX_PX = 2;
+
 function bucket(px: number): number {
   const b = Math.ceil(px / BUCKET_PX) * BUCKET_PX;
   return b < BUCKET_PX ? BUCKET_PX : b;
@@ -60,8 +69,14 @@ export function displayReportSize(
 ): { width: number; height: number } {
   const a = aspect > 0 && Number.isFinite(aspect) ? aspect : DEFAULT_FEED_ASPECT;
   const fit = width > 0 && height > 0 ? Math.min(width, height * a) : width;
-  const w = bucket(fit);
-  return { width: w, height: Math.max(2, Math.round(w / a / 2) * 2) };
+  let w = bucket(fit);
+  if (w < MIN_DISPLAY_REPORT_PX) w = bucket(MIN_DISPLAY_REPORT_PX);
+  if (w / a < MIN_DISPLAY_REPORT_PX) w = bucket(MIN_DISPLAY_REPORT_PX * a);
+  return { width: w, height: Math.round(w / a / 2) * 2 };
+}
+
+function isEmpty(box: Size): boolean {
+  return !(box.width >= EMPTY_BOX_PX) || !(box.height >= EMPTY_BOX_PX);
 }
 
 export interface Size {
@@ -246,7 +261,7 @@ export function useReportDisplaySize(
 
     const sizeFor = (box: Size): Size => {
       if (!square) return displayReportSize(box.width, box.height, aspectRef.current);
-      const side = bucket(Math.min(box.width, box.height));
+      const side = Math.max(MIN_DISPLAY_REPORT_PX, bucket(Math.min(box.width, box.height)));
       return { width: side, height: side };
     };
 
@@ -256,6 +271,13 @@ export function useReportDisplaySize(
       displaySizes.report(flightId, instanceId, width, height);
     };
 
+    const withdraw = () => {
+      if (lastW < 0) return;
+      lastW = -1;
+      lastH = -1;
+      displaySizes.clear(flightId, instanceId);
+    };
+
     /*
      * Judged when the debounce settles, so a stream change noted a little after
      * the observer fired (a host that commits the stream and the box in a
@@ -269,9 +291,14 @@ export function useReportDisplaySize(
       if (prev && near.some((c) => c.at >= seenAt - FOLLOW_MS && followsStream(prev, box, c))) {
         return;
       }
+      if (isEmpty(box)) {
+        withdraw();
+        return;
+      }
       const next = sizeFor(box);
       if (next.width === lastW && next.height === lastH) return;
-      if (near.length > 0) {
+      /* With nothing reported since a withdraw there is no loop to break. */
+      if (near.length > 0 && lastW >= 0) {
         const held = now - lastSuspectAt < HOLD_MS;
         lastSuspectAt = now;
         if (held) return;
@@ -283,6 +310,8 @@ export function useReportDisplaySize(
       const entry = entries[0];
       if (!entry) return;
       const box = { width: entry.contentRect.width, height: entry.contentRect.height };
+      /* Until the box is first laid out, every measurement counts as the first, so it reports promptly. */
+      if (!firstReported && isEmpty(box)) return;
       if (!firstReported) {
         firstReported = true;
         baseline = box;
@@ -296,7 +325,7 @@ export function useReportDisplaySize(
     });
     observer.observe(el);
     reapply.current = () => {
-      if (!baseline) return;
+      if (!baseline || isEmpty(baseline)) return;
       const next = sizeFor(baseline);
       if (next.width !== lastW || next.height !== lastH) send(next);
     };

package/src/index.ts

@@ -30,7 +30,7 @@ export { useKerbcastClock } from "./hooks/useKerbcastClock";
 export { useDisplayedFrameUt } from "./hooks/useDisplayedFrameUt";
 export { useKerbcastInFlight } from "./hooks/useKerbcastInFlight";
 export { useKerbcastWaitingForSlot } from "./hooks/useKerbcastWaitingForSlot";
-export { useReportDisplaySize } from "./hooks/useReportDisplaySize";
+export { useReportDisplaySize, MIN_DISPLAY_REPORT_PX } from "./hooks/useReportDisplaySize";
 export { useRecordings } from "./hooks/useRecordings";
 export type { RecordingsStore, ActiveRecordingInfo } from "./hooks/useRecordings";