cursedbelt 4.1.0 → 4.3.0

package/dist/react/media/sourceFault.d.ts

@@ -0,0 +1,146 @@
+/**
+ * What a media URL ANSWERED, when what it answered was not the bytes.
+ *
+ * ── 🔴 The report this exists for ───────────────────────────────────────────────────────
+ * Owner, 2026-09-17: *"make a 404 stop the media player spinner so I don't think it's going
+ * to eventually load."* One item in his catalogue has no ladder, so the very first request a
+ * player makes is answered honestly and immediately:
+ *
+ *     GET …/u_fd668e6a….hls/master.m3u8  →  404  {"error":"not_found"}  in 0.2 s
+ *
+ * and the spinner then ran until he gave up. **A 404 is a COMPLETE ANSWER** — there is
+ * nothing still in flight, nothing to wait for, and no amount of waiting changes it — and it
+ * was the one status every surface here treated as "still loading".
+ *
+ * ── 🔴 The distinction this module is entirely about ────────────────────────────────────
+ * A hang and an answer must not look the same to somebody watching a spinner:
+ *
+ * | what happened | is it an answer? | what the viewer should see |
+ * |---|---|---|
+ * | slow segment, tunnel blinked, origin waking | no — still in flight | keep spinning |
+ * | `404` / `410` | yes, and it is final | the reason, now |
+ * | `401` / `403` | yes, and it is RECOVERABLE | re-ask the app, then the reason |
+ * | any other `4xx`/`5xx` | yes, and we cannot name it | the reason, now |
+ *
+ * `403` is split out because it is the one that comes back on its own: every signed URL in
+ * this fleet carries `exp = iat + 2 × window`, so a page left open across a window boundary
+ * meets a stale token legitimately and the fix is to ASK THE APP AGAIN, not to tell the
+ * viewer his film is gone. Collapsing it into "gone" would put a false and permanent-sounding
+ * sentence on screen for the one fault that clears itself.
+ *
+ * ── 🔴 Why a probe, and why only on the failure path ────────────────────────────────────
+ * `hls.js` hands us the status directly (`ErrorData.response.code`), so the ladder and its
+ * rungs cost nothing. An `<img>` and a `<video>` do NOT: both fire a bare `error` event that
+ * carries no status at all, so "the file is gone" and "the token went stale" and "the codec
+ * is unplayable" arrive as the same undifferentiated failure. {@link probeSourceFault} is the
+ * one way to tell them apart, and it runs ONLY after the element has already given up — so a
+ * gallery that is working costs exactly nothing, and a one-byte `Range` request is the whole
+ * price of a sentence that is true.
+ *
+ * (`bytes=0-0` is a CORS-safelisted range, so the probe is a simple request and never costs a
+ * preflight; the 404 in the report above answers `access-control-allow-origin: *`, which is
+ * what makes the status readable cross-origin at all. When it is not readable the fetch
+ * throws, and that is `unknown` — honest, still not a spinner.)
+ *
+ * ── 🔴 Why one module holds the reading, the wording AND the overlay ────────────────────
+ * Three surfaces have to agree about the same fault — the gallery's picture stage, its native
+ * video stage and the shared player — and the thing they must agree on is not the mechanism,
+ * it is the SENTENCE. Split across three files this becomes three wordings, and the owner
+ * meets whichever one his file happens to be behind.
+ *
+ * It is deliberately NOT a published subpath and nothing here is re-exported from
+ * `react/media/index.ts`. `publicSurface.baseline` charges for a permanent promise, and none
+ * of this is one: the wording is copy, the overlay is chrome, and a consumer that wanted to
+ * draw its own would be re-implementing the corner rather than importing it. (Same call the
+ * badge stack in `VideoPlayer.tsx` made — see that baseline entry's "what did NOT go on the
+ * surface".) A `.tsx` holding a component beside its helpers is `galleryItemMedia.tsx`'s
+ * shape, for the same reason.
+ */
+/** Which of the three answers came back. `expired` is the only one worth re-asking. */
+export type SourceFaultKind = 
+/** The source said there is nothing here — `404`/`410`. Final. */
+'gone'
+/** The token went stale — `401`/`403`. A fresh URL from the app fixes it. */
+ | 'expired'
+/** It answered something else, or did not answer readably. Not a hang either way. */
+ | 'unknown';
+export interface SourceFault {
+    kind: SourceFaultKind;
+    /** The HTTP status that said so, when one was readable. Absent for an unreadable failure. */
+    status?: number;
+}
+/**
+ * Classify one HTTP status. `null` for anything below 400 — a source that answered `200` and
+ * still would not play is not a fault of the URL, and saying otherwise would blame the store
+ * for an unplayable codec.
+ */
+export declare function sourceFaultFromStatus(status: number): SourceFault | null;
+/**
+ * Is this worth asking the app for a fresh URL? Exactly one kind is.
+ *
+ * 🔴 A caller that re-asks must BOUND it — see `useItemMedia`'s one-re-ask-per-item rule. An
+ * unbounded retry against a URL that is never going to be fresh is the same spinner with more
+ * requests in it, which is the thing this whole module exists to stop.
+ */
+export declare function isRecoverableFault(fault: SourceFault): boolean;
+/**
+ * Ask the URL what it is, once, with a one-byte range.
+ *
+ * Only ever called after an element has already failed, so this is never on the happy path.
+ * Never throws: an unreadable failure (offline, CORS, DNS) resolves `unknown` rather than
+ * rejecting, because the caller's job at that point is to say SOMETHING instead of spinning.
+ *
+ * Reads `globalThis.fetch` at call time rather than closing over it, so a spec can install its
+ * own and the unit suite never puts a request on a real socket
+ * (`src/iframesMakeNoRealRequest.spec.ts` is the standing rule).
+ */
+export declare function probeSourceFault(url: string | undefined): Promise<SourceFault>;
+/**
+ * The sentence a viewer reads.
+ *
+ * 🔴 One place, because the gallery's picture stage, its native video stage and the shared
+ * player all have to say the SAME thing about the same fault — three copies of this is three
+ * wordings, and the owner would meet whichever one his file happened to be behind. The specs
+ * spell the sentences out as literals rather than importing them, for the reason the badge
+ * copy in `VideoPlayer.tsx` gives: which words are on the picture IS the deliverable, so an
+ * assertion that reads the function asserts nothing.
+ *
+ * `subject` is the noun for the thing that failed — "This video", "This picture", the file's
+ * own name. It leads the sentence, so it is capitalised by the caller.
+ */
+export declare function sourceFaultMessage(fault: SourceFault, subject: string): string;
+/**
+ * Did an `hls.js` error carry an ANSWER, or is the ladder still coming?
+ *
+ * 🔴 The whole of the owner's report is in this predicate. hls.js sets `response.code` only
+ * when the server actually replied — a timeout, an abort and a stalled fetch carry none — so a
+ * status here means the ladder is not on its way and never was, and the copy that always
+ * exists should take over NOW rather than after four retries and twelve seconds of backoff. A
+ * fatal error with no status is the case those retries exist for and must keep them.
+ *
+ * `unknown` rather than hls.js's `ErrorData`: the library is an OPTIONAL peer and a ~525 KB
+ * dynamic import in exactly one branch, so its types must not become a static dependency of
+ * every file that reads one of its payloads.
+ */
+export declare function hlsErrorIsAnswer(detail: unknown): boolean;
+/**
+ * What a video surface says once every source has ANSWERED.
+ *
+ * ── 🔴 Why it covers the picture instead of sitting beside it ───────────────────────────
+ * The thing being replaced is a buffering spinner drawn by Vidstack's own layout, which
+ * cannot be turned off from outside it — so a sentence in the corner would be a sentence NEXT
+ * TO a spinner, which is the owner's report ("I don't think it's going to eventually load")
+ * with extra words rather than without it. Opaque, `inset: 0`, over the whole surface: the
+ * spinner is gone because it is not visible, and that is the only lever there is.
+ *
+ * 🔴 The player is NOT unmounted by it. A `403` is recoverable and the app's fix is a fresh
+ * URL, which arrives as new props on the same mount; tearing the player down would throw away
+ * the position, the volume and the decoder to say one sentence that may be obsolete a second
+ * later. The gallery's stages do the opposite and REPLACE their element — there the `<video>`
+ * is the spinner, so nothing short of removing it would do.
+ */
+export declare function SourceFaultOverlay({ fault, name }: {
+    fault: SourceFault;
+    name: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=sourceFault.d.ts.map

package/dist/react/media/sourceFault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceFault.d.ts","sourceRoot":"","sources":["../../../src/react/media/sourceFault.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,uFAAuF;AACvF,MAAM,MAAM,eAAe;AACzB,kEAAkE;AAChE,MAAM;AACR,6EAA6E;GAC3E,SAAS;AACX,qFAAqF;GACnF,SAAS,CAAC;AAEd,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAKxE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAqBpF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAS9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,+BA4BvF"}

package/dist/react/media/sourceFault.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Classify one HTTP status. `null` for anything below 400 — a source that answered `200` and
+ * still would not play is not a fault of the URL, and saying otherwise would blame the store
+ * for an unplayable codec.
+ */
+export function sourceFaultFromStatus(status) {
+    if (status === 404 || status === 410)
+        return { kind: 'gone', status };
+    if (status === 401 || status === 403)
+        return { kind: 'expired', status };
+    if (status >= 400)
+        return { kind: 'unknown', status };
+    return null;
+}
+/**
+ * Is this worth asking the app for a fresh URL? Exactly one kind is.
+ *
+ * 🔴 A caller that re-asks must BOUND it — see `useItemMedia`'s one-re-ask-per-item rule. An
+ * unbounded retry against a URL that is never going to be fresh is the same spinner with more
+ * requests in it, which is the thing this whole module exists to stop.
+ */
+export function isRecoverableFault(fault) {
+    return fault.kind === 'expired';
+}
+/**
+ * Ask the URL what it is, once, with a one-byte range.
+ *
+ * Only ever called after an element has already failed, so this is never on the happy path.
+ * Never throws: an unreadable failure (offline, CORS, DNS) resolves `unknown` rather than
+ * rejecting, because the caller's job at that point is to say SOMETHING instead of spinning.
+ *
+ * Reads `globalThis.fetch` at call time rather than closing over it, so a spec can install its
+ * own and the unit suite never puts a request on a real socket
+ * (`src/iframesMakeNoRealRequest.spec.ts` is the standing rule).
+ */
+export async function probeSourceFault(url) {
+    const fetchImpl = globalThis.fetch;
+    if (!url || typeof fetchImpl !== 'function')
+        return { kind: 'unknown' };
+    try {
+        const res = await fetchImpl(url, {
+            method: 'GET',
+            // One byte. The status is the whole point; the body is not wanted and a media file is
+            // the last thing to download twice.
+            headers: { Range: 'bytes=0-0' },
+            cache: 'no-store',
+        });
+        // 🔴 A status BELOW 400 is deliberately dropped rather than reported: the URL is fine and
+        // the bytes are there, so the element failed for a reason that is not the store's — an
+        // unplayable codec, a decode stall. Printing "could not be loaded (HTTP 200)" would blame
+        // the wrong thing in the one case where the file is not actually missing.
+        return sourceFaultFromStatus(res.status) ?? { kind: 'unknown' };
+    }
+    catch {
+        // No readable answer at all. Still not a hang — the element already stopped — so the
+        // caller states what it can rather than leaving the spinner up.
+        return { kind: 'unknown' };
+    }
+}
+/**
+ * The sentence a viewer reads.
+ *
+ * 🔴 One place, because the gallery's picture stage, its native video stage and the shared
+ * player all have to say the SAME thing about the same fault — three copies of this is three
+ * wordings, and the owner would meet whichever one his file happened to be behind. The specs
+ * spell the sentences out as literals rather than importing them, for the reason the badge
+ * copy in `VideoPlayer.tsx` gives: which words are on the picture IS the deliverable, so an
+ * assertion that reads the function asserts nothing.
+ *
+ * `subject` is the noun for the thing that failed — "This video", "This picture", the file's
+ * own name. It leads the sentence, so it is capitalised by the caller.
+ */
+export function sourceFaultMessage(fault, subject) {
+    const status = fault.status != null ? ` (HTTP ${fault.status})` : '';
+    if (fault.kind === 'gone') {
+        return `${subject} is no longer on the media store${status} — nothing is still loading.`;
+    }
+    if (fault.kind === 'expired') {
+        return `${subject}'s link has expired${status} — reopen it for a fresh one.`;
+    }
+    return `${subject} could not be loaded${status} — nothing is still loading.`;
+}
+/**
+ * Did an `hls.js` error carry an ANSWER, or is the ladder still coming?
+ *
+ * 🔴 The whole of the owner's report is in this predicate. hls.js sets `response.code` only
+ * when the server actually replied — a timeout, an abort and a stalled fetch carry none — so a
+ * status here means the ladder is not on its way and never was, and the copy that always
+ * exists should take over NOW rather than after four retries and twelve seconds of backoff. A
+ * fatal error with no status is the case those retries exist for and must keep them.
+ *
+ * `unknown` rather than hls.js's `ErrorData`: the library is an OPTIONAL peer and a ~525 KB
+ * dynamic import in exactly one branch, so its types must not become a static dependency of
+ * every file that reads one of its payloads.
+ */
+export function hlsErrorIsAnswer(detail) {
+    const data = detail;
+    const code = data?.response?.code;
+    if (!data?.fatal || typeof code !== 'number')
+        return false;
+    return sourceFaultFromStatus(code) !== null;
+}
+/**
+ * What a video surface says once every source has ANSWERED.
+ *
+ * ── 🔴 Why it covers the picture instead of sitting beside it ───────────────────────────
+ * The thing being replaced is a buffering spinner drawn by Vidstack's own layout, which
+ * cannot be turned off from outside it — so a sentence in the corner would be a sentence NEXT
+ * TO a spinner, which is the owner's report ("I don't think it's going to eventually load")
+ * with extra words rather than without it. Opaque, `inset: 0`, over the whole surface: the
+ * spinner is gone because it is not visible, and that is the only lever there is.
+ *
+ * 🔴 The player is NOT unmounted by it. A `403` is recoverable and the app's fix is a fresh
+ * URL, which arrives as new props on the same mount; tearing the player down would throw away
+ * the position, the volume and the decoder to say one sentence that may be obsolete a second
+ * later. The gallery's stages do the opposite and REPLACE their element — there the `<video>`
+ * is the spinner, so nothing short of removing it would do.
+ */
+export function SourceFaultOverlay({ fault, name }) {
+    return (_jsxs("div", { role: 'status', style: {
+            position: 'absolute',
+            inset: 0,
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 6,
+            padding: 16,
+            textAlign: 'center',
+            // Over VIDEO content, not app chrome — dark-on-video regardless of app theme, the same
+            // convention the player's corner badges use and for the same reason.
+            // guardrails-ignore no-hardcoded-colors: see comment above.
+            background: 'rgba(0, 0, 0, 0.82)',
+            // guardrails-ignore no-hardcoded-colors: see comment above.
+            color: 'rgba(255, 255, 255, 0.92)',
+        }, children: [_jsx("span", { style: { fontSize: 13, fontWeight: 600 }, children: name }), _jsx("span", { style: { fontSize: 13, lineHeight: 1.5, maxWidth: '42ch' }, children: sourceFaultMessage(fault, 'This video') })] }));
+}
+//# sourceMappingURL=sourceFault.js.map

package/dist/react/media/sourceFault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sourceFault.js","sourceRoot":"","sources":["../../../src/react/media/sourceFault.tsx"],"names":[],"mappings":"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"}

package/dist/react/media/videoChapterEditor.css

@@ -17,6 +17,25 @@
 	border-radius: var(--radius-md, 8px);
 }
 
+/* Why there is no film, said IN the player's own place — the sibling of `.cbvc-nofilm` in
+   `videoCutEditor.css`, which documents both halves of the reasoning (why the panel wears the
+   video's own class, and why the turner's white-on-black note cannot be reused on a theme
+   surface). Restated here for the same reason every `.cbch-*` rule is a sibling of a `.cbvc-*`
+   one: these two sheets ride their own lazily-imported chunks and share nothing. */
+.cbch-nofilm {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	min-block-size: 8rem;
+	margin: 0;
+	padding: 1.5rem;
+	text-align: center;
+	text-wrap: balance;
+	font-size: 13px;
+	line-height: 1.5;
+	color: var(--muted-foreground, var(--foreground));
+}
+
 /* The one authoring row: name the section, then mark it. In that order, because the button
    is disabled until there is a name — see the component. */
 .cbch-add {

package/dist/react/media/videoCutEditor.css

@@ -17,6 +17,28 @@
 	border-radius: var(--radius-md, 8px);
 }
 
+/* Why there is no film, said IN the player's own place — the owner's *"I see a black screen"*,
+   which he could only report as a black screen because the dialog said nothing. It carries
+   `.cbvc-video` as well, so the panel is the same width, ground and corner as the element it
+   stands in for and the dialog does not jump when a source resolves.
+
+   🔴 Not `.cbpe-frame-note`, which the turner and the grabber share: that note is white on the
+   true black of a photograph's frame, and this sheet's ground is a theme surface — reusing it
+   here would be invisible text in the light theme. */
+.cbvc-nofilm {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	min-block-size: 8rem;
+	margin: 0;
+	padding: 1.5rem;
+	text-align: center;
+	text-wrap: balance;
+	font-size: 13px;
+	line-height: 1.5;
+	color: var(--muted-foreground, var(--foreground));
+}
+
 .cbvc-marks {
 	display: flex;
 	align-items: center;

package/dist/react/media-gallery/MediaGallery.d.ts

@@ -44,8 +44,19 @@ export declare function galleryTileLine(item: MediaGalleryItem, options?: {
  * listed here, so the feature was invisible with nothing anywhere reporting a fault. It is a
  * pure function so a test can read it directly; the rendered player is a Vidstack custom
  * element that happy-dom never brings to life, so no DOM assertion can see any of this.
+ *
+ * 🔴 The return type is spelled out rather than imported as `PlayerVideo` from
+ * `../media/VideoPlayer`, and the reason is BYTES, not taste. The player is reached from here
+ * through `React.lazy(() => import(…))` on purpose, and `scripts/styleAreas.ts`'s closure walk
+ * reads STATIC specifiers — an `import type` is one, and tsc erases it long after that walk has
+ * decided. Measured 2026-09-18: naming the type pulled the player's whole static closure into
+ * the `media-gallery` area stylesheet, 2023 candidates to 2190, for a line that emits nothing
+ * at runtime. The two definitions are structurally identical, so tsc still joins them at the
+ * one call site that matters (`<LazyVideoPlayer video={…}>` below).
  */
-export declare function stagePlayableVideo(item: MediaGalleryItem, media: MediaGalleryItemMedia, streamUrl: string): ChapteredVideo;
+export declare function stagePlayableVideo(item: MediaGalleryItem, media: MediaGalleryItemMedia, streamUrl: string): ChapteredVideo & {
+    playbackDegraded?: boolean;
+};
 export interface MediaGalleryProps {
     items: MediaGalleryItem[];
     /** Header title. */

package/dist/react/media-gallery/MediaGallery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MediaGallery.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/MediaGallery.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"MediaGallery.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/MediaGallery.tsx"],"names":[],"mappings":"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"}