@camstack/ui-library 1.2.191 → 1.2.192

package/dist/composites/clips/ClipBandBar.d.ts

@@ -0,0 +1,16 @@
+import { DayWindow, DensityBucket } from '../cap-settings/recording-timeline-model.js';
+export interface ClipBandBarProps {
+    /** The calendar day the window is inside. */
+    readonly day: Date;
+    readonly onDayChange: (day: Date) => void;
+    /** The visible window — the band, whenever no bucket is picked. */
+    readonly view: DayWindow;
+    /** The full day, the clamp for every zoom and pan. */
+    readonly dayBounds: DayWindow;
+    readonly onViewChange: (view: DayWindow) => void;
+    readonly buckets: readonly DensityBucket[];
+    readonly selectedBucketIndex: number | null;
+    readonly onSelectBucket: (index: number) => void;
+    readonly densityLoading: boolean;
+}
+export declare function ClipBandBar({ day, onDayChange, view, dayBounds, onViewChange, buckets, selectedBucketIndex, onSelectBucket, densityLoading, }: ClipBandBarProps): import("react").JSX.Element;

package/dist/composites/clips/clip-band.d.ts

@@ -0,0 +1,58 @@
+import { DayWindow } from '../cap-settings/recording-timeline-model.js';
+/** The half-open instant range `listClips` is asked for. */
+export interface ClipBand {
+    readonly fromMs: number;
+    readonly toMs: number;
+}
+/**
+ * How many local days a band may touch and still be asked for.
+ *
+ * Two, which is every band the timebar can produce: its view window never
+ * spans more than one calendar day, and the only way to reach a second is to
+ * sit across local midnight. A third is not a gesture this control has, so it
+ * is a bug or a future widening — either way the list refuses rather than
+ * guesses.
+ */
+export declare const MAX_BAND_LOCAL_DAYS = 2;
+/** What the surface may do with a band, decided once. */
+export type ClipBandPlan = {
+    readonly kind: 'askable';
+    readonly band: ClipBand;
+    readonly localDays: number;
+} | {
+    readonly kind: 'too-wide';
+    readonly band: ClipBand;
+    readonly localDays: number;
+    readonly maxLocalDays: number;
+};
+/**
+ * How many LOCAL calendar days the half-open band touches.
+ *
+ * The end instant is exclusive, so a band that ends exactly at the next local
+ * midnight is one day, not two — otherwise every whole-day band would report
+ * double what it costs.
+ */
+export declare function localDaysInBand(band: ClipBand): number;
+/** Whether this band may be asked for, and what it costs, in one value. */
+export declare function planClipBand(band: ClipBand): ClipBandPlan;
+/** A density bucket's own window, as `EventHeatmap` hands it back. */
+export interface ClipBandBucket {
+    readonly startMs: number;
+    readonly endMs: number;
+}
+/**
+ * The band for the current selection: the picked bucket, or — when nothing is
+ * picked — the whole visible window.
+ *
+ * "Nothing picked means everything visible" is safe here and only here,
+ * because the visible window is itself bounded by the timebar. It is never
+ * "everything the camera holds" (D382's unstated ask).
+ */
+export declare function bandForSelection(view: DayWindow, bucket: ClipBandBucket | null): ClipBand;
+/**
+ * The band, spelled out.
+ *
+ * Every state renders it — an empty list has to say WHICH period it is empty
+ * for, the same rule the day label carried before the band replaced it.
+ */
+export declare function formatBandLabel(band: ClipBand): string;

package/dist/composites/clips/clip-day-window.d.ts

@@ -1,37 +1,36 @@
 /**
- * Day navigation for the clips browser — and the window `listClips` is asked
- * for.
+ * LOCAL calendar-day arithmetic for the clips browser.
  *
- * Every recording timestamp on the wire is the CAMERA's wall clock (D549
- * decision 7), and the operator navigates a calendar, so a "day" here is a
- * LOCAL wall-clock day: from the instant local midnight starts to the instant
- * the next local midnight starts, half-open. Two consequences that are pinned
- * by spec because both are invisible until they are wrong:
+ * The browser no longer NAVIGATES days — it follows a band selected on the
+ * recording timebar (D564) — but the local day survived the move as the unit
+ * the COST is counted in: a Reolink search is clamped to one camera-local day
+ * per call, so `clip-band.ts` counts a band's local days to decide whether it
+ * may be asked for. The window builder this file used to own went with the day
+ * picker; `recording-timeline-model.ts`'s `dayWindow(date, nowMs)` is the one
+ * that builds windows now, and one directory holding two functions of that
+ * name was the confusion worth deleting.
  *
- *  - Building the window in UTC shifts every list by the browser's offset, and
- *    an operator in Berlin would see a 22:00 clip filed under the next day.
+ * Two properties are pinned by spec because both are invisible until they are
+ * wrong:
+ *
+ *  - Deriving the day in UTC shifts every band by the browser's offset, and an
+ *    operator in Berlin would see a 22:00 clip filed under the next day.
  *  - Walking days by adding 86 400 000 ms repeats or skips a calendar day
  *    across a DST change. The walk goes through `Date`'s own day arithmetic.
  *
- * A day id is `YYYY-MM-DD` — the shape a URL and a `<input type="date">` both
- * take, so navigation never needs a second representation.
+ * A day id is `YYYY-MM-DD` — it orders lexicographically, which is what lets
+ * the band's day walk terminate on a comparison rather than on a count.
  */
-/** The half-open instant range `listClips` is asked for. */
-export interface ClipDayWindow {
-    readonly since: number;
-    readonly until: number;
-}
 /** The LOCAL calendar day an instant falls in, as `YYYY-MM-DD`. */
 export declare function toDayId(instant: Date): string;
-/** The half-open local-wall-clock window of one day. */
-export declare function dayWindow(dayId: string): ClipDayWindow;
 /** Walk `days` calendar days from `dayId` — DST-safe, because `Date` does it. */
 export declare function shiftDay(dayId: string, days: number): string;
 /**
- * The day, spelled out for the header.
+ * The day, spelled out — the calendar half of a band's label.
  *
- * An empty list has to say WHICH day it is empty for — "no clips" with no date
- * beside it is the ambiguity this surface exists to remove — so this label is
- * rendered next to every state, not only the populated one.
+ * An empty list has to say WHICH period it is empty for; "no clips" with no
+ * date beside it is the ambiguity this surface exists to remove. `formatBandLabel`
+ * puts the times around it, and every state renders the result, not only the
+ * populated one.
  */
 export declare function formatDayLabel(dayId: string): string;

package/dist/composites/clips/clip-still-retry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * When a tile comes back for a still the server said was queued — and when it
+ * gives up (D563).
+ *
+ * ## Why a retry, and not a queue or a push
+ *
+ * A deferred refusal is FREE. The provider's lane rejects past its capacity
+ * without touching the camera, so asking again costs one cheap HTTP round trip
+ * to the addon and zero Baichuan commands. That is what rules out the
+ * alternatives: a push would need a channel, a subscription and server-side
+ * fan-out of 60 tile identities to save requests that cost nothing, and a
+ * client-side queue would be a second copy of the authority that already lives
+ * where the camera's real constraint is. Scroll-into-view alone does not help
+ * either — the 43 tiles measured refusing on 592 are already on screen.
+ *
+ * ## The shape
+ *
+ * Exponential, jittered, bounded. Exponential because a fixed interval either
+ * hammers or dawdles; JITTERED because 43 tiles refused in the same paint
+ * would otherwise come back in the same instant and refuse together again;
+ * BOUNDED because a tile that asks for ever is the other way to show the
+ * operator nothing.
+ *
+ * The server's `retry-after` is taken only when it is LONGER than the curve.
+ * The curve is the floor, so a provider answering `retry-after: 1` for a whole
+ * page cannot turn this into 43 requests a second.
+ *
+ * Sized against the measurement: one page is 60 tiles and the provider serves
+ * one mint in flight per host, so the last tile is ~60 mints away. The budget
+ * below outlasts that; a shorter one would be theatre.
+ */
+/** How many times a tile comes back before it says so and stops. */
+export declare const STILL_RETRY_ATTEMPTS = 4;
+/** First wait, doubling from there. */
+export declare const STILL_RETRY_BASE_MS = 4000;
+/** No single wait is longer than this, whatever the server hints. */
+export declare const STILL_RETRY_MAX_WAIT_MS = 30000;
+export interface StillRetryInput {
+    /** 0 for the first retry, 1 for the second, … */
+    readonly attempt: number;
+    /** The server's `retry-after`, in ms, or `null` when it sent none. */
+    readonly serverHintMs: number | null;
+    /** Injected so the schedule is assertable; `Math.random` in production. */
+    readonly random: () => number;
+}
+export interface StillRetryPlan {
+    readonly waitMs: number;
+}
+/** The next wait, or `null` when the budget is spent. */
+export declare function planStillRetry(input: StillRetryInput): StillRetryPlan | null;

package/dist/composites/clips/clip-tile-media.d.ts

@@ -1,11 +1,19 @@
 import { Clip } from '@camstack/types';
-/** The four things a tile can be. */
+/** The five things a tile can be. */
 export type ClipTileMedia = {
     readonly kind: 'vouched';
     readonly url: string;
 } | {
     readonly kind: 'mint';
     readonly url: string;
+}
+/** The still is QUEUED. The tile shows loading and comes back, under a
+ *  bound — `text` is what it says if the bound runs out. */
+ | {
+    readonly kind: 'deferred';
+    readonly reason: string;
+    readonly text: string;
+    readonly retryAfterMs: number | null;
 } | {
     readonly kind: 'unavailable';
     readonly reason: string;
@@ -14,14 +22,24 @@ export type ClipTileMedia = {
     readonly kind: 'none';
     readonly text: string;
 };
+/** A 204, as its three headers arrived. `undefined` where a header was absent
+ *  — which is a real case, not a defect: an addon older than D563 sends only
+ *  the prose. */
+export interface MintRefusalHeaders {
+    readonly code: string | undefined;
+    readonly reason: string;
+    readonly disposition: string | undefined;
+    readonly retryAfterMs?: number | null;
+}
 /** What to draw for one clip's tile. */
 export declare function resolveTileMedia(clip: Clip): ClipTileMedia;
 /**
- * A mint that answered 204 — latch its `x-camstack-reason` to this instant.
+ * A 204, as something the tile can draw.
  *
- * The refusal is about NOW (a full queue, a sleeping camera), so it replaces
- * the offer for as long as the tile is mounted and is not retried behind the
- * operator's back. An unknown reason is shown raw rather than dropped: a
- * firmware inventing a refusal must not become a blank tile.
+ * `deferred` is the ONLY answer that comes back, and only because the server
+ * said so. Everything else — an unknown disposition, an absent one, a code
+ * this build has never heard of — is final, so the failure mode of a
+ * vocabulary that moves is a tile that stops early, never one that asks for
+ * ever.
  */
-export declare function latchMintRefusal(reason: string): ClipTileMedia;
+export declare function describeRefusal(headers: MintRefusalHeaders): ClipTileMedia;

package/dist/composites/clips/clip-view-state.d.ts

@@ -1,9 +1,16 @@
 import { Clip, ClipSource } from '@camstack/types';
+import { ClipBand, ClipBandPlan } from './clip-band.js';
 import { ClipSourceNotice } from './clip-source-state.js';
 /** React Query's settled-ness, narrowed to what this decision needs. */
 export type ClipQueryStatus = 'pending' | 'error' | 'success';
 export interface ClipsViewInput {
-    readonly dayId: string;
+    /**
+     * The period the list is about, and whether it may be asked for at all
+     * (`clip-band.ts`). A refused plan means NO query was fired, which is why
+     * the refusal has to be decided here rather than inferred from a query that
+     * will stay `pending` for ever.
+     */
+    readonly plan: ClipBandPlan;
     readonly clipsStatus: ClipQueryStatus;
     readonly clips: readonly Clip[];
     readonly sourcesStatus: ClipQueryStatus;
@@ -16,9 +23,15 @@ export type ClipsViewState = {
 } | {
     readonly kind: 'failed';
     readonly message: string;
+} | {
+    /** The band is wider than the bound, so nothing was asked. */
+    readonly kind: 'refused';
+    readonly band: ClipBand;
+    readonly localDays: number;
+    readonly maxLocalDays: number;
 } | {
     readonly kind: 'empty';
-    readonly dayId: string;
+    readonly band: ClipBand;
     readonly answered: readonly ClipSourceNotice[];
     readonly silent: readonly ClipSourceNotice[];
     /** No source could answer at all — a different fact from a quiet day. */

package/dist/generated/system-hooks.d.ts

@@ -1267,6 +1267,8 @@ export declare const usePipelineAnalyticsGetTrackMedia: typeof trpc.pipelineAnal
 export declare const usePipelineAnalyticsListTrackMedia: typeof trpc.pipelineAnalytics.listTrackMedia.useQuery;
 /** Generated alias around `trpc.pipelineAnalytics.listEventMedia.useQuery`. */
 export declare const usePipelineAnalyticsListEventMedia: typeof trpc.pipelineAnalytics.listEventMedia.useQuery;
+/** Generated alias around `trpc.pipelineAnalytics.ownersWithMedia.useQuery`. */
+export declare const usePipelineAnalyticsOwnersWithMedia: typeof trpc.pipelineAnalytics.ownersWithMedia.useQuery;
 /** Generated alias around `trpc.pipelineAnalytics.searchObjectEvents.useQuery`. */
 export declare const usePipelineAnalyticsSearchObjectEvents: typeof trpc.pipelineAnalytics.searchObjectEvents.useQuery;
 /** Generated alias around `trpc.pipelineAnalytics.wipeObjectEmbeddings.useMutation`. */