cursedbelt 3.0.2 → 4.0.0

package/dist/react/media-gallery/mediaGallery.css

@@ -177,12 +177,52 @@
 	container-type: size;
 }
 
+/* 🔴 The turned picture surface is SIZED to the swapped panel, not merely bounded by it.
+   Owner, `ideas/collections-09-14.md`: *"If I rotate a portait style video 90 degrees it should
+   be changed to fit the wide screen panel … so I can watch it like it was recorded with wide
+   screen."* — a rotation on its own leaves the footage the size it already was.
+
+   These used to be `max-block-size`/`max-inline-size`, which can only SHRINK. Measured in
+   Chromium on 2026-09-16 against `demo`'s 9:16 clip in a 505×284 panel: the player gives its
+   `<video>` a 16:9 box of its own (284×160 there), `object-fit: contain` draws the portrait
+   film as a 90×160 pillar inside it, and the max-* pair had nothing to bind on — so the turn
+   painted 160×90 of film in a 505×284 panel, which is the tall thin picture in the middle of a
+   black stage that was reported. `e2e/video-turn.spec.ts` measures exactly that rectangle.
+
+   Width from the container's BLOCK size and height from its INLINE size — the axis swap, said
+   in the only units that can say it — so after the rotation the box is the panel again. The
+   fit itself is then `object-fit: contain`'s, which is what keeps this honest for footage whose
+   aspect is not the panel's inverse: a 16:9 clip turned on its end is letterboxed whole rather
+   than blown up and cropped, and a square one is left alone. A scale factor on the transform
+   cannot make that distinction — it does not know the film's shape — which is why the fit lives
+   on the box and only the rotation travels in `--cbmg-turn`. */
 .cbmg-stage-turn[data-turned='true'] video,
 .cbmg-stage-turn[data-turned='true'] .vds-poster img {
 	max-width: none;
 	max-height: none;
-	max-block-size: 100cqi;
-	max-inline-size: 100cqb;
+	max-block-size: none;
+	max-inline-size: none;
+	width: 100cqb;
+	height: 100cqi;
+	/* The player sets its own 16:9 on the element; an explicit pair of sides must win over it,
+	   or the swap above is computed and then thrown away. */
+	aspect-ratio: auto;
+	object-fit: contain;
+}
+
+/* 🔴 …and it has to be turned about the PANEL's centre, which means it has to sit at it first.
+   A rotation pivots on the element's own middle, so an element the player has left against the
+   left edge of its provider box lands a quarter of the panel off to one side — measured in
+   Chromium on 2026-09-16: a correctly sized 505×284 of film, painted at x=278 in a panel
+   starting at x=388, i.e. 110px of it outside the frame and a black band the same width down
+   the other edge. The wrapper above centres what IS its child; on the Vidstack path the child
+   is the player, and the element being turned is two boxes further in. Same reach as
+   `.vds-poster` / `.vds-controls` elsewhere in this file, and inert on the native stage, whose
+   `<video>` is already the wrapper's own flex-centred child. */
+.cbmg-stage-turn[data-turned='true'] [data-media-provider] {
+	display: flex;
+	align-items: center;
+	justify-content: center;
 }
 
 /* Inside the turned frame the stage element must stop claiming its own 70vh, or the flex
@@ -322,6 +362,63 @@
 	background: color-mix(in srgb, var(--accent-solid) 12%, transparent);
 }
 
+/* ── The tile the STAGE is showing ───────────────────────────────────────────────────────
+ *
+ * Owner, `ideas/collections-09-14.md`: *"I want to … still see the playing video in the list
+ * and nothing about the list changes as I pick other videos."* The strip under the stage used
+ * to drop the open file; it keeps it now and marks it here.
+ *
+ * 🔴 `::before`, where the selection tint is `::after`, so a tile that is BOTH ticked and
+ * playing draws both marks instead of one silently replacing the other. Neither pseudo is a
+ * `:first-child`, so `.cbmg-selectable > :first-child { height: 100% }` above is untouched.
+ */
+.cbmg-selectable.is-playing::before {
+	content: '';
+	position: absolute;
+	inset: 0;
+	/* guardrails-ignore no-raw-zindex: the same tile-local stacking the selection tint uses —
+	   the mark over its own tile, inside the isolated `.cbmg-selectable` context. */
+	z-index: 1;
+	pointer-events: none;
+	border-radius: 8px;
+	/* Thicker than the selection's 2px: this one has to be findable while scrolling past it,
+	   which is the whole reason the tile stays in the list. */
+	outline: 3px solid var(--accent-solid);
+	outline-offset: -3px;
+	background: color-mix(in srgb, var(--accent-solid) 10%, transparent);
+}
+/* A filled capsule with its own foreground token (DESIGN.md §3 — never a thin outline), at
+   the 12px floor (§4). `pointer-events: none` because the whole tile is one button and a
+   label that swallowed the click would make its corner dead. */
+.cbmg-playing-chip {
+	position: absolute;
+	top: 6px;
+	left: 6px;
+	/* guardrails-ignore no-raw-zindex: tile-local stacking, over this tile's own mark. */
+	z-index: 2;
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	max-width: calc(100% - 12px);
+	padding: 3px 8px;
+	border-radius: 999px;
+	background: var(--accent-solid);
+	color: var(--accent-solid-foreground);
+	font-size: 12px;
+	font-weight: 600;
+	line-height: 1.2;
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	pointer-events: none;
+}
+/* The one corner collision: a document tile draws its type badge in this exact spot. The mark
+   wins for as long as it is there — the stage directly above is showing the file, and its
+   titlebar says what kind it is, so the badge is the redundant one of the two. */
+.cbmg-selectable.is-playing .cbmg-doc-badge {
+	display: none;
+}
+
 .cbmg-bulkbar {
 	display: flex;
 	align-items: center;
@@ -356,7 +453,7 @@
    frame grabber were each written inside ONE app's `detailActions`; these are the rules that
    came with them. Plain CSS under `.cbmg-`, like the rest of this file. */
 
-/* 🔴 The ☀ Picture adjustment reaches the stage through a custom property set on the stage
+/* 🔴 The Picture adjustment reaches the stage through a custom property set on the stage
    anchor, NOT through a prop threaded into the player — the video stage is Vidstack's and is
    several components deep, so a prop would make every consumer of the player primitive learn
    about a control only the gallery offers.
@@ -544,6 +641,21 @@
 	box-shadow: inset 3px 0 0 0 var(--accent);
 }
 
+/* The row the stage is showing — the table's half of the grid tile's mark. Same shape as the
+   selected row so the two read as one family, and a step louder (the SOLID accent, a 4px bar)
+   because there is exactly one of these and it is the row the reader is looking for.
+   The name it is given is `.cbgd-sr-only` text in the name cell; `GalleryTable.tsx` says why a
+   visible capsule cannot live in a fixed-layout cell. */
+.cbgt-row.is-playing {
+	background: color-mix(in srgb, var(--accent-solid) 12%, transparent);
+	box-shadow: inset 4px 0 0 0 var(--accent-solid);
+}
+/* …and it keeps that reading under the pointer, which the hover rule above would otherwise
+   take away by painting the plain hover fill over it. */
+.cbgt-row.is-playing:hover {
+	background: color-mix(in srgb, var(--accent-solid) 18%, transparent);
+}
+
 /* Fixed tracks, declared once. `table-layout: fixed` means these widths are the layout. */
 .cbgt-cell--check {
 	width: 36px;
@@ -566,6 +678,14 @@
 .cbgt-cell--length {
 	width: 78px;
 }
+/* The exact byte count. Wider than the rounded Size beside it because the whole point of the
+   column is that nothing is dropped: a terabyte is 13 digits plus 4 separators, and a count
+   that truncated to "1,402,653,1…" would be exactly as useless for telling two files apart as
+   the rounded "1.4 GB" it exists to replace. `.cbgt-cell--num` already right-aligns it and
+   gives it tabular figures, which is what makes two counts comparable down a column. */
+.cbgt-cell--bytes {
+	width: 132px;
+}
 /* The date is the widest of the three numeric columns: "21 Aug 2026" at 12px does not fit
    the 96px the others use, and a DATE that truncates to "Aug 21, 2…" is a column that has
    stopped answering the question it exists for. Deliberately generous — every locale this
@@ -731,7 +851,14 @@
 /* ── Narrow screens ──────────────────────────────────────────────────────────────────────
  *
  * Kind and Length are the two columns a phone can lose without the row stopping being
- * useful — the name, the size and the date are what the owner is scanning for. */
+ * useful — the name, the size and the date are what the owner is scanning for.
+ *
+ * 🔴 The exact-bytes column goes with them, and it is the one that would hurt most to keep:
+ * it is the widest track in the table (132px), and these widths ARE the layout under
+ * `table-layout: fixed` — thumb + size + bytes + date already exceeds a 390px phone on their
+ * own, so keeping it would trade the file NAME for a digit count. The rounded Size stays, so
+ * the row still answers "how big"; comparing two counts to the byte is a desk instrument, and
+ * the desk is where the column is. */
 @media (max-width: 720px) {
 	.cbgt-head th:first-child,
 	.cbgt-row td:first-child {
@@ -742,6 +869,7 @@
 		padding-right: 12px;
 	}
 	.cbgt-cell--kind,
+	.cbgt-cell--bytes,
 	.cbgt-cell--length {
 		display: none;
 	}
@@ -782,3 +910,51 @@
 	min-width: 0;
 	min-height: 0;
 }
+
+/*
+ * ── The DESCRIPTION, under the title on the stage ───────────────────────────────────────
+ *
+ * Owner, `ideas/collections-09-14.md`: *"In media galleries have an option for apps to tag
+ * media and aadd descriptions to media."*
+ *
+ * 🔴 It cannot ride the ` · ` facts line. `.cbgd-meta-line` is `white-space: nowrap` with an
+ * ellipsis because the SAME class captions every tile in the grid, so a sentence appended
+ * there is a sentence nobody can read past its first few words. These two rules are what let
+ * the titlebar's own wrapping flex row carry a second, wrapping line — the facts keep the
+ * nowrap behaviour they have always had, and the description is a block beneath them.
+ *
+ * The width cap is readability, not decoration: `DESIGN.md` §4 asks for a measure, and a
+ * description running the full width of a 1680px stage is one line of 200 characters.
+ */
+.cbmg-stage-facts {
+	display: block;
+}
+.cbmg-stage-description {
+	display: block;
+	/* Overrides the nowrap/ellipsis inherited from `.cbgd-meta-line` — see above. */
+	white-space: normal;
+	max-width: 68ch;
+	margin-top: 2px;
+	font-size: 12px;
+	line-height: 1.45;
+	color: var(--muted-foreground);
+}
+
+/*
+ * The tag/description editor's body — see `MediaMetaEditor.tsx`. Plain CSS in this module's
+ * own stylesheet rather than utilities on the elements, for the reason the rest of this file
+ * records: the sheet is already loaded wherever the gallery is, and the dialog is otherwise
+ * built entirely from design-system components that bring their own chrome.
+ */
+.cbmm {
+	display: flex;
+	flex-direction: column;
+	gap: 14px;
+}
+.cbmm-count {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	font-size: 13px;
+	color: var(--muted-foreground);
+}

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

@@ -0,0 +1,62 @@
+import type { MediaGalleryItem } from './types';
+/**
+ * Tags and a description, expressed as a CHANGE rather than as a new value.
+ *
+ * ── Why a change and not a pair of fields ──────────────────────────────────────────────
+ * The owner's ask, `ideas/collections-09-14.md`, 2026-09-14: *"In media galleries have an
+ * option for apps to tag media and aadd descriptions to media."* The case he will actually
+ * hit is forty holiday photographs at once, and forty items do not share one tag list — each
+ * one has its own, and "the new tags" cannot be a single array without wiping thirty-nine
+ * lists that were never on screen.
+ *
+ * So the plural verb carries `addTags`/`removeTags`, which mean the same thing for one item
+ * as for forty, and a consumer writes ONE handler rather than a singular one plus a loop.
+ * That is the rule `tasks/Completed/240-*.md` states for the file tree's multi-select in as
+ * many words — *"One request for N ids, not N requests: the tree deliberately does not loop
+ * `onMove`, because a tree re-derived between each write is how a batch move half-lands."*
+ *
+ * 🔴 Everything here is case-INSENSITIVE and spelling-preserving. A vocabulary that mints
+ * `Bank`, `bank` and `BANK` as three tags is a vocabulary nothing can filter by, and the
+ * gallery's own chips would show all three. The first spelling seen wins; a tag that differs
+ * only in case from one already present is not an addition at all.
+ */
+export interface MediaMetaChange {
+    /** Tags to add to EVERY item in the set. Already trimmed, de-duplicated, never empty strings. */
+    addTags: string[];
+    /** Tags to remove from EVERY item in the set. Matched case-insensitively. */
+    removeTags: string[];
+    /**
+     * The new description, or `''` to clear it. `undefined` means "not part of this change" —
+     * which is what a bulk tag always sends, because one sentence cannot describe forty files
+     * and writing it onto all of them would delete thirty-nine that were never read.
+     */
+    description?: string;
+}
+/** Trim, drop the empties, drop case-insensitive duplicates keeping the first spelling. */
+export declare function cleanTags(tags: readonly string[]): string[];
+/**
+ * What it takes to get from `before` to `after` — the single-item editor's save, expressed in
+ * the same two lists the bulk one sends, so both paths arrive at a consumer as one shape.
+ */
+export declare function tagDiff(before: readonly string[] | undefined, after: readonly string[]): {
+    addTags: string[];
+    removeTags: string[];
+};
+/** Nothing to save. The editor's Save is disabled on this, so a no-op never reaches an app. */
+export declare function isEmptyMetaChange(change: MediaMetaChange): boolean;
+/**
+ * The merge a consumer would otherwise write itself — one item's row after the change lands.
+ *
+ * Exported for the same reason `fileTreeSelection.ts`'s rules are: the gallery persists
+ * nothing, so every app has to do this arithmetic, and four apps re-deriving "add these,
+ * remove those, keep the spelling" is four chances to mint a duplicate tag. `tags` comes back
+ * cleaned; `description` is omitted from the result when the change did not carry one, so a
+ * caller can spread the result over its row without clearing a description it never touched.
+ */
+export declare function applyMetaChange(item: Pick<MediaGalleryItem, 'tags' | 'description'>, change: MediaMetaChange): {
+    tags: string[];
+    description?: string;
+};
+/** Every tag on any of these items, cleaned and in first-seen order — the "Remove" vocabulary. */
+export declare function tagsOn(items: readonly Pick<MediaGalleryItem, 'tags'>[]): string[];
+//# sourceMappingURL=mediaMeta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mediaMeta.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/mediaMeta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAY3D;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAS7C;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAMlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,aAAa,CAAC,EACpD,MAAM,EAAE,eAAe,GACtB;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAK1C;AAED,kGAAkG;AAClG,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,CAEjF"}

package/dist/react/media-gallery/mediaMeta.js

@@ -0,0 +1,56 @@
+/** Trim, drop the empties, drop case-insensitive duplicates keeping the first spelling. */
+export function cleanTags(tags) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of tags) {
+        const tag = raw.trim();
+        if (!tag)
+            continue;
+        const key = tag.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(tag);
+    }
+    return out;
+}
+/**
+ * What it takes to get from `before` to `after` — the single-item editor's save, expressed in
+ * the same two lists the bulk one sends, so both paths arrive at a consumer as one shape.
+ */
+export function tagDiff(before, after) {
+    const was = cleanTags(before ?? []);
+    const now = cleanTags(after);
+    const wasKeys = new Set(was.map((t) => t.toLowerCase()));
+    const nowKeys = new Set(now.map((t) => t.toLowerCase()));
+    return {
+        addTags: now.filter((tag) => !wasKeys.has(tag.toLowerCase())),
+        removeTags: was.filter((tag) => !nowKeys.has(tag.toLowerCase())),
+    };
+}
+/** Nothing to save. The editor's Save is disabled on this, so a no-op never reaches an app. */
+export function isEmptyMetaChange(change) {
+    return (change.addTags.length === 0 &&
+        change.removeTags.length === 0 &&
+        change.description === undefined);
+}
+/**
+ * The merge a consumer would otherwise write itself — one item's row after the change lands.
+ *
+ * Exported for the same reason `fileTreeSelection.ts`'s rules are: the gallery persists
+ * nothing, so every app has to do this arithmetic, and four apps re-deriving "add these,
+ * remove those, keep the spelling" is four chances to mint a duplicate tag. `tags` comes back
+ * cleaned; `description` is omitted from the result when the change did not carry one, so a
+ * caller can spread the result over its row without clearing a description it never touched.
+ */
+export function applyMetaChange(item, change) {
+    const removed = new Set(change.removeTags.map((t) => t.toLowerCase()));
+    const kept = cleanTags(item.tags ?? []).filter((tag) => !removed.has(tag.toLowerCase()));
+    const tags = cleanTags([...kept, ...change.addTags]);
+    return change.description === undefined ? { tags } : { tags, description: change.description };
+}
+/** Every tag on any of these items, cleaned and in first-seen order — the "Remove" vocabulary. */
+export function tagsOn(items) {
+    return cleanTags(items.flatMap((item) => item.tags ?? []));
+}
+//# sourceMappingURL=mediaMeta.js.map

package/dist/react/media-gallery/mediaMeta.js.map

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

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

@@ -133,4 +133,81 @@ export declare const nextPlaybackEnd: (current: PlaybackEndBehavior) => Playback
 export type GalleryViewMode = 'grid' | 'table';
 export declare function readViewMode(): GalleryViewMode;
 export declare function writeViewMode(mode: GalleryViewMode): void;
+/**
+ * The level a player opens at, and whether it opens silent.
+ *
+ * ── The owner's spec, verbatim (`ideas/collections-09-14.md`, 2026-09-14) ───────────────
+ * *"Keep the media player volume where I set it after changing it during a session except if
+ * I refresh or first log in then continue starting it at mute. Then if I unmute it, keep that
+ * value as I change to other videos."*
+ *
+ * Three rules, and the middle one is the whole design:
+ *
+ *   | fresh page load / first sign-in | muted, exactly as it is today |
+ *   | he changes it, then opens another clip | that level, for the rest of the session |
+ *   | he refreshes | muted again |
+ *
+ * ── 🔴 It is kept IN MEMORY. Not `localStorage`, and not `sessionStorage` either ────────
+ * The neighbours above are `localStorage` because they are ways of WORKING — how a folder
+ * plays through, how a stage is pinned — and a way of working survives a reload. Loudness is
+ * not: *"except if I refresh … continue starting it at mute"* is a request for this to be
+ * FORGOTTEN, so the only correct store is one that cannot outlive the page.
+ *
+ * 🔴 `sessionStorage` is NOT that store, however much its name suggests it. It is cleared
+ * when the TAB closes, not when the page loads — MDN, in as many words: *"the data survives
+ * page reloads and restores"*. Measured here 2026-09-16 in the repo's own Chromium (write,
+ * `page.reload()`, read: the value is still there), because the difference is invisible in a
+ * unit test and is precisely the row of the table above that he called out. A volume put
+ * there comes back LOUD on the one gesture he named as the one that must return to silence.
+ *
+ * A module-level `Map` dies with the document, which is what a person means by "this
+ * session". It is also why nothing here needs the `try` wrapping every reader above carries:
+ * there is no web storage to be denied by a sandboxed iframe or by Safari's private mode, and
+ * therefore no read that can throw the gallery render away over a remembered volume. The
+ * specs assert both stores stay untouched, so a later move onto one of them — which would
+ * silently restore loudness across a refresh — fails rather than passes.
+ *
+ * SSR-safe for the same reason: writes only ever happen in a browser event handler, so the
+ * map a server renders against is always empty and every server-rendered player starts muted.
+ *
+ * ── 🔴 Muted and the level are TWO facts ────────────────────────────────────────────────
+ * *"if I unmute it, keep that value"* — so a mute may not be stored as `volume: 0`. Pressing
+ * mute and pressing unmute has to leave the level where he put it, which it only does if the
+ * level survives the mute independently. Every media element already models these two
+ * separately; collapsing them here is what would break it.
+ */
+export interface SessionVolume {
+    /** 0–1: what it plays at, and what UNMUTING returns to. */
+    volume: number;
+    /** Silent — whatever level is underneath. */
+    muted: boolean;
+}
+/**
+ * What a player opens at when the person has not touched the volume this session: full level,
+ * no sound. It is the level that matters — a restored `volume: 1` under a mute is what makes
+ * the control bar's unmute button behave the way it did before any of this existed.
+ */
+export declare const DEFAULT_SESSION_VOLUME: SessionVolume;
+/**
+ * Where a session volume is kept — the CALLER names it, for the same reason
+ * `media/stageResize.ts` makes the remembered HEIGHT a keyed value: there is more than one
+ * player in this package, and one shared key would make setting the level on one of them
+ * silently reach into the other. The gallery stage and the shared `VideoPlayer` primitive an
+ * app mounts on a page of its own are two players.
+ */
+export declare const PLAYER_VOLUME_KEY = "cbvp:volume";
+/** The gallery stage's own — both transports of it (Vidstack and the native `<video>`). */
+export declare const STAGE_VOLUME_KEY = "cbmg:stage-volume";
+/**
+ * What he set this session, or `null` for "he has not touched it".
+ *
+ * 🔴 `null` rather than {@link DEFAULT_SESSION_VOLUME}, and the distinction is load-bearing:
+ * a player that was never going to make a sound anyway (`autoPlay={false}`, which mutes
+ * nothing today) must keep behaving exactly as it did, and it only can if the caller can tell
+ * "nothing set" apart from "set to the default". Handing back the default here would silence
+ * every click-to-play consumer in the fleet on upgrade.
+ */
+export declare function readSessionVolume(key: string): SessionVolume | null;
+/** Remember it for the rest of this PAGE. Never longer — see {@link SessionVolume}. */
+export declare function writeSessionVolume(key: string, value: SessionVolume): void;
 //# sourceMappingURL=playbackPreferences.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"playbackPreferences.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/playbackPreferences.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,wDAAwD;AACxD,MAAM,MAAM,mBAAmB;AAC7B,8EAA8E;AAC5E,MAAM;AACR,oCAAoC;GAClC,QAAQ;AACV,sFAAsF;GACpF,MAAM;AACR,wFAAwF;GACtF,KAAK;AACP,2FAA2F;GACzF,SAAS,CAAC;AAEd,eAAO,MAAM,sBAAsB,EAAE,mBAAmB,EAMvD,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,EAAE,MAAM,CACtC,mBAAmB,EACnB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmB/C,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,CASrD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAMpE;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,uCAAwC,CAAC;AAEzE,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAIrC;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAQvC;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAMrD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAMtC;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAMnD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAM3C;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAMpD;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,GAAI,SAAS,mBAAmB,KAAG,mBAGlD,CAAC;AAEd;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,CAAC;AAI/C,wBAAgB,YAAY,IAAI,eAAe,CAM9C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAMzD"}
+{"version":3,"file":"playbackPreferences.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/playbackPreferences.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,wDAAwD;AACxD,MAAM,MAAM,mBAAmB;AAC7B,8EAA8E;AAC5E,MAAM;AACR,oCAAoC;GAClC,QAAQ;AACV,sFAAsF;GACpF,MAAM;AACR,wFAAwF;GACtF,KAAK;AACP,2FAA2F;GACzF,SAAS,CAAC;AAEd,eAAO,MAAM,sBAAsB,EAAE,mBAAmB,EAMvD,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,EAAE,MAAM,CACtC,mBAAmB,EACnB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmB/C,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,CASrD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAMpE;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,uCAAwC,CAAC;AAEzE,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAIrC;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAQvC;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAMrD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAMtC;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAMnD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAM3C;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAMpD;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,GAAI,SAAS,mBAAmB,KAAG,mBAGlD,CAAC;AAEd;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,CAAC;AAI/C,wBAAgB,YAAY,IAAI,eAAe,CAM9C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAMzD;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAA0C,CAAC;AAEhF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAE/C,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAKpD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAKnE;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAO1E"}

package/dist/react/media-gallery/playbackPreferences.js

@@ -210,4 +210,46 @@ export function writeViewMode(mode) {
         // Unremembered is still usable this session.
     }
 }
+/**
+ * What a player opens at when the person has not touched the volume this session: full level,
+ * no sound. It is the level that matters — a restored `volume: 1` under a mute is what makes
+ * the control bar's unmute button behave the way it did before any of this existed.
+ */
+export const DEFAULT_SESSION_VOLUME = { volume: 1, muted: true };
+/**
+ * Where a session volume is kept — the CALLER names it, for the same reason
+ * `media/stageResize.ts` makes the remembered HEIGHT a keyed value: there is more than one
+ * player in this package, and one shared key would make setting the level on one of them
+ * silently reach into the other. The gallery stage and the shared `VideoPlayer` primitive an
+ * app mounts on a page of its own are two players.
+ */
+export const PLAYER_VOLUME_KEY = 'cbvp:volume';
+/** The gallery stage's own — both transports of it (Vidstack and the native `<video>`). */
+export const STAGE_VOLUME_KEY = 'cbmg:stage-volume';
+/** Per key, for this document only. See {@link SessionVolume} for why it is not a web store. */
+const sessionVolumes = new Map();
+/**
+ * What he set this session, or `null` for "he has not touched it".
+ *
+ * 🔴 `null` rather than {@link DEFAULT_SESSION_VOLUME}, and the distinction is load-bearing:
+ * a player that was never going to make a sound anyway (`autoPlay={false}`, which mutes
+ * nothing today) must keep behaving exactly as it did, and it only can if the caller can tell
+ * "nothing set" apart from "set to the default". Handing back the default here would silence
+ * every click-to-play consumer in the fleet on upgrade.
+ */
+export function readSessionVolume(key) {
+    const held = sessionVolumes.get(key);
+    // A COPY: the caller hands this to a player that will go on changing it, and a shared
+    // object would let one surface's live state leak into the next one's starting value.
+    return held ? { ...held } : null;
+}
+/** Remember it for the rest of this PAGE. Never longer — see {@link SessionVolume}. */
+export function writeSessionVolume(key, value) {
+    sessionVolumes.set(key, {
+        // Clamped here rather than at every call site: this lands on `HTMLMediaElement.volume`,
+        // which throws `IndexSizeError` outside 0–1.
+        volume: Math.min(1, Math.max(0, value.volume)),
+        muted: value.muted,
+    });
+}
 //# sourceMappingURL=playbackPreferences.js.map

package/dist/react/media-gallery/playbackPreferences.js.map

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

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

@@ -1,5 +1,6 @@
 import type { FileCategory } from 'cwip/file-kind';
 import type { ProcessingStatus } from 'cursedbelt-core/media';
+import type { VideoChapter } from '../media/videoChapters';
 /**
  * Sort orders the gallery header offers.
  *
@@ -82,6 +83,25 @@ export interface MediaGalleryItem extends MediaGalleryItemMedia {
     durationSeconds?: number;
     /** Free-form tags — shown in the meta line and as filter chips when any item has them. */
     tags?: string[];
+    /**
+     * What this file IS, in the owner's own words — shown under the title on the stage.
+     *
+     * 🔴 The owner's ask, `ideas/collections-09-14.md`, 2026-09-14: *"In media galleries have an
+     * option for apps to tag media and aadd descriptions to media."* Tags were already readable
+     * here and there was no description field at all, so half of that sentence had nowhere to
+     * land even for an app that stored one.
+     *
+     * Like {@link tags} it is READ freely: an item that carries one renders it whether or not
+     * the app can write one. Authoring both is a capability — pass
+     * {@link MediaGalleryProps.onSaveMeta} and the control appears.
+     *
+     * 🔴 Deliberately NOT on the tile caption. That caption is two lines by design (see
+     * `galleryTileLine`) and is already contested between the tags and the measurement; a
+     * sentence there would either be an ellipsis or a third line on every tile in the grid.
+     * The stage has the room, and the stage is where somebody is actually reading about one
+     * file rather than scanning forty.
+     */
+    description?: string;
     /** Download href when it differs from `url` (e.g. `?download=1` variants). */
     downloadUrl?: string;
     /**
@@ -104,6 +124,20 @@ export interface MediaGalleryItem extends MediaGalleryItemMedia {
         flipX?: boolean;
         flipY?: boolean;
     };
+    /**
+     * The named sections of a video — YouTube chapters, stored by the app on its own row.
+     *
+     * 🔴 The owner's ask, 2026-09-15: *"allow putting markers on videos at points in time and
+     * giving them a title for the section for knowing what that part of the video is about, like
+     * youtube chapters."* Like {@link orientation}, this is metadata the app keeps beside the
+     * file rather than anything baked into it — a chapter costs no encode, applies the instant it
+     * is saved, and is free to be wrong.
+     *
+     * The stage passes them to the player, which draws the dividers on the scrub bar and fills
+     * its chapters menu (see `stagePlayableVideo`). Authoring them is a separate capability:
+     * pass {@link MediaGalleryProps.onSaveChapters} and the Sections control appears.
+     */
+    chapters?: VideoChapter[];
     /**
      * Lazily resolve this item's media URLs the first time a tile or stage needs them.
      * Called once per item id per gallery mount (cached); return `null` when the bytes

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,WAAW,GACX,MAAM,GACN,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,WAAW,GACX,MAAM,GACN,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CAC5D"}

package/dist/scripts/guardrailsEnforce.d.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env bun
+interface Violation {
+    file: string;
+    line: number;
+    snippet: string;
+}
+interface Rule {
+    name: string;
+    description: string;
+    check: (filePath: string, source: string) => Violation[];
+}
+export declare function walk(dir: string, out?: string[]): string[];
+export declare function setReimplementedNames(names: readonly string[]): void;
+export declare const RULES: Record<string, Rule>;
+export declare const ALLOWED_FILE_CATEGORIES: Set<string>;
+export interface FileAllow {
+    rules: Set<string>;
+    category: string;
+    reason: string;
+    line: number;
+}
+/** Parse honored file-level allowances from a source file's header, plus warnings for any
+ *  malformed/unrecognized directive (which is NOT honored — its violations still fire). */
+export declare function parseFileAllows(source: string): {
+    allows: FileAllow[];
+    warnings: string[];
+};
+export type { Rule, Violation };
+//# sourceMappingURL=guardrailsEnforce.d.ts.map

package/dist/scripts/guardrailsEnforce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrailsEnforce.d.ts","sourceRoot":"","sources":["../../scripts/guardrailsEnforce.ts"],"names":[],"mappings":";AAwKA,UAAU,SAAS;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,IAAI;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;CACzD;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CA6B9D;AAu2BD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAEpE;AAweD,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAkBtC,CAAC;AASF,eAAO,MAAM,uBAAuB,aAAkD,CAAC;AAGvF,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACb;AAED;2FAC2F;AAC3F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CA0C3F;AAED,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC"}