@joewinke/jatui 0.51.0 → 0.53.0

package/CLAUDE.md

@@ -177,7 +177,7 @@ Item-by-item review surfaces (MOS review-ux, design mos-z8vgx). One `VerdictOpti
 | `ThumbnailGrid` | Generic thumbnail strip (chimaro port) — image tiles with text-tile fallback, +N overflow counter, remove/add affordances. Decoupled from any media library: pass `{id, url, alt}` items, or a `cell` snippet for full control of tile contents. `removeMode` — `'hover'` (default) reveals the × on hover/focus and keeps it visible on coarse (touch) pointers (ContextMenuTrigger pattern); `'always'` pins it for touch-first flows. `gridCols` (e.g. `'grid-cols-2 sm:grid-cols-4'`) switches the strip to a responsive CSS grid with column-filling tiles. Items take optional `progress` (0–100): an upload ring draws around the tile and a tiny % occupies the remove-× corner, cross-fading into the × at 100 (same slot, no layout shift; per-tile `role="progressbar"`). | `items: ThumbnailItem[]` (`{id, url?, alt, progress?}`), `max`, `size` (`xs\|sm\|md\|lg`), `removable`+`onRemove`, `removeMode` (`hover\|always`), `addable`+`onAdd`, `onSelect`, `gridCols`, `class`, `cell` snippet |
 | `MediaWorkbench` | Full-featured image editor modal — upload, AI generate, AI edit, background removal, annotation canvas. **Preferred over `SmartImageEditor` for new image fields.** Two-column modal: preview left, 4 action tabs right (Generate, Edit, Remove BG, Annotate). Save uploads blob to `uploadEndpoint` or emits `onComplete`. Requires proxy endpoints from jst-23w1l.2. | `value` (bindable `string \| null`), `uploadEndpoint?` (default `/api/media`), `onComplete?`, `accept?` |
 | `MediaLightbox` | Full-screen media preview — z-9040 backdrop, arrow-key paging when given an array, `+/-/0` zoom, download action, Escape/backdrop close. **Use this for the general "just show it big" case** — replaces hand-rolled `fixed inset-0 z-[9040]` modals. For annotated / markup-overlaid image previews, use `ImageLightbox` instead. | `src?`, `filename?`, `kind?: 'image' \| 'video'`, `downloadUrl?`, `items?: MediaItem[]`, `initialIndex?`, `onClose?`, `zIndex?` |
-| `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker, `Shift+T` toggle) and a "Talk time" legend (2+ speakers only; one voice gets no legend and no per-row name). **`kind="audio"` renders no stage**, and **`transport="band"`** (the audio default) drops the native `<video controls>` bar for a transport row on the band (play/pause, `now / total`, speed, mute + volume, fullscreen for video), so the band is the ONE timeline. A double-click on the picture toggles fullscreen (band transport; with native controls the browser owns the gesture), a buffering spinner shows while the media is waiting, and volume/mute survive a reload through `settingsStore` (else guarded localStorage). **Every intelligence prop is optional** — a bare mp4 still gets the scrubber, hover-time card, wheel volume and the full keyboard map (Space/K, arrows/J/L, vol/mute, −/= speed + Backspace reset, </> frame step, [/] chapters, B bookmark, t theater, ? help overlay), and each pane lights up as its data arrives (nothing shifts layout when diarization lands late). Wheel means volume over the video (shift = seek, alt = speed; a wheel/keyboard volume change also flashes a clear volume OSD — glyph, level bar and %, "Muted" at 0, opacity-only fade) and zoom over the band; Shift+wheel over the transcript steps line by line (a plain wheel over the transcript scrolls the pane natively — the page is never trapped); `/` opens an in-transcript search (only when a transcript exists and focus is not in a text field; the omnibar yields): matches highlight in place with a live `n / m` count (`aria-live`), Enter/Shift+Enter walk next/previous (seek + the line follows), Esc closes the search first in the Esc layering. Right-click a transcript line (or `Menu` / `Shift+F10` on a focused one) for the **line menu** — Play from here, Copy text, Copy text with timestamp (`[0:02] text`), Copy link at this time when `buildTimeLink` supplies the URL builder (without it the item is absent; `?t=` shape via `buildTimeUrl`); Escape closes and returns focus to the line, the player's keys are dead while it floats, and in fill theater Esc closes the menu without leaving the theater. Internals live in `src/lib/video/` (band/keys/rate/deepLink/settings + contracts for audio/night/presence — see that README; gap audit vs the extension: `VIDEO-PLAYER-GAP-AUDIT.md`). | `src`, `kind?` (`'video' \| 'audio'`), `transport?` (`'native' \| 'band'`), `chapters?`, `speakers?`, `transcript?`, `bookmarks?`, `waveform?`, `talkTime?`, `startAt?`, `poster?`, `captionsSrc?`, `crossorigin?` (`'anonymous'` — what frame-reading features need), `syncUrlTime?` (`?t=` deep-link, opt-in), `transcriptPosition?` (`'below' \| 'side'`), `transcriptMaxHeight?` (pane bound — default `min(40vh, 28rem)` below, the player's height beside; the active-line follow scrolls only the pane; only a gesture that actually moves the PANE pauses it — a wheel that scrolls the page doesn't — behind a "Resume following" pill, and it resumes by itself on seek / line or chapter click / play after pause / `followResumeMs` (6000) idle while playing; a hovered chapter fills its whole span in the theme accent with full-height edges), `followResumeMs?`, `transcriptLineMenu?` (true — right-click/`Menu`/`Shift+F10` on a transcript line opens the line menu; `false` leaves transcript lines to the browser's own context menu), `buildTimeLink?` ((sec) → URL for "Copy link at this time"; the host owns the address shape), `theater?` (bindable — theater mode, NOT fullscreen: control-bar button + `t`, the HOST lays the page out full-width; a side transcript moves below; remembered per viewer as the `player.theater` setting via `settingsStore`, else guarded localStorage), `theaterMode?` (`'width'` default — the host widens its page \| `'fill'` — the player becomes a fixed full-viewport dialog: `role="dialog"` + `aria-modal`, page scroll locked, Tab trapped, Esc/the button exits and returns focus, largest 16:9 stage that fits, transcript beside it ≥64rem else below, z from `--jatui-z-theater`; a remembered theater never fills on load, only a viewer gesture), `theaterButton?` (true), `onTheaterChange?`, `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
+| `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker, `Shift+T` toggle) and a "Talk time" legend (2+ speakers only; one voice gets no legend and no per-row name). **`kind="audio"` renders no stage**, and **`transport="band"`** (the audio default) drops the native `<video controls>` bar for a transport row on the band (play/pause, `now / total`, speed, mute + volume, fullscreen for video), so the band is the ONE timeline. A double-click on the picture toggles fullscreen (band transport; with native controls the browser owns the gesture), a buffering spinner shows while the media is waiting, and volume/mute survive a reload through `settingsStore` (else guarded localStorage). **Every intelligence prop is optional** — a bare mp4 still gets the scrubber, hover-time card, wheel volume and the full keyboard map (Space/K, arrows/J/L, vol/mute, −/= speed + Backspace reset, </> frame step, [/] chapters, B bookmark, t theater, ? help overlay), and each pane lights up as its data arrives (nothing shifts layout when diarization lands late). Wheel means volume over the video (shift = seek, alt = speed; a wheel/keyboard volume change also flashes a clear volume OSD — glyph, level bar and %, "Muted" at 0, opacity-only fade) and zoom over the band; Shift+wheel over the transcript steps line by line (a plain wheel over the transcript scrolls the pane natively — the page is never trapped); `/` opens an in-transcript search (only when a transcript exists and focus is not in a text field; the omnibar yields): matches highlight in place with a live `n / m` count (`aria-live`), Enter/Shift+Enter walk next/previous (seek + the line follows), Esc closes the search first in the Esc layering. Right-click a transcript line (or `Menu` / `Shift+F10` on a focused one) for the **line menu** — Play from here, Copy text, Copy text with timestamp (`[0:02] text`), Copy link at this time when `buildTimeLink` supplies the URL builder (without it the item is absent; `?t=` shape via `buildTimeUrl`); Escape closes and returns focus to the line, the player's keys are dead while it floats, and in fill theater Esc closes the menu without leaving the theater. A QR button on the transport (when `buildTimeLink` exists) opens a **continue-on-phone** card — the deep link at the current second as a scannable SVG QR; clicking the code copies it (jatui-3k7cp). Internals live in `src/lib/video/` (band/keys/rate/deepLink/settings + contracts for audio/night/presence — see that README; gap audit vs the extension: `VIDEO-PLAYER-GAP-AUDIT.md`). | `src`, `kind?` (`'video' \| 'audio'`), `transport?` (`'native' \| 'band'`), `chapters?`, `speakers?`, `transcript?`, `bookmarks?`, `waveform?`, `talkTime?`, `startAt?`, `poster?`, `captionsSrc?`, `crossorigin?` (`'anonymous'` — what frame-reading features need), `syncUrlTime?` (`?t=` deep-link, opt-in), `transcriptPosition?` (`'below' \| 'side'`), `transcriptMaxHeight?` (pane bound — default `min(40vh, 28rem)` below, the player's height beside; the active-line follow scrolls only the pane; only a gesture that actually moves the PANE pauses it — a wheel that scrolls the page doesn't — behind a "Resume following" pill, and it resumes by itself on seek / line or chapter click / play after pause / `followResumeMs` (6000) idle while playing; a hovered chapter fills its whole span in the theme accent with full-height edges), `followResumeMs?`, `transcriptLineMenu?` (true — right-click/`Menu`/`Shift+F10` on a transcript line opens the line menu; `false` leaves transcript lines to the browser's own context menu), `buildTimeLink?` ((sec) → URL for "Copy link at this time"; the host owns the address shape), `qrContinue?` (true — the QR button: the host's `buildTimeLink` at the current second as an SVG QR card, click the code to copy; hidden entirely when no `buildTimeLink` — the player never guesses a URL), `theater?` (bindable — theater mode, NOT fullscreen: control-bar button + `t`, the HOST lays the page out full-width; a side transcript moves below; remembered per viewer as the `player.theater` setting via `settingsStore`, else guarded localStorage), `theaterMode?` (`'width'` default — the host widens its page \| `'fill'` — the player becomes a fixed full-viewport dialog: `role="dialog"` + `aria-modal`, page scroll locked, Tab trapped, Esc/the button exits and returns focus, largest 16:9 stage that fits, transcript beside it ≥64rem else below, z from `--jatui-z-theater`; a remembered theater never fills on load, only a viewer gesture), `theaterButton?` (true), `onTheaterChange?`, `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
 | `MediaCapture` | One-tap audio/selfie-video/screen(+mic) recording — a host-agnostic PRIMITIVE. Owns permission requests, MIME negotiation, the record/stop state machine, live self-preview, and mixes screen+mic audio into one track via AudioContext. Never uploads anything — hands the finished clip to `onCapture` as a Blob and the host decides what to do with it. `onCapture` may be async; the component shows "processing" until it resolves. | `onCapture: (result: MediaCaptureResult) => void \| Promise<void>`, `modes?` (default all three), `maxDurationMs?` (default 120000), `label?`, `hint?`, `compact?`, `disabled?` |
 | `MultimodalCaptureField` | "Upload a file, or record yourself going over it" as one input surface — composes `FileDropzone` (capped to one file) with `MediaCapture`. File and recording are independent (either, both, or neither); neither half uploads anything, same "validate and hand back" contract as `FileDropzone`. | `onFileSelected?`, `onFileRemoved?`, `onCapture?`, `onRecordingRemoved?`, `accept?`, `maxFileSize?`, `modes?`, `maxDurationMs?`, `file?`/`fileUrl?`/`fileName?`, `recordingSummary?` |
 | `ListenControl` | "Listen to this page" — a compact pill that expands into a TWO-ROW playback bar over the host's PER-SENTENCE audio (TTS): row 1 = play/pause · chapter chip + current sentence (full remaining width) · ONE settings pill ("1.25× · Sarah" → speed 0.75–2× + voice menu) · close; row 2 = prev/next sentence and −15s/+15s · a document-wide progress bar with chapter ticks (a hatched tail marks the not-yet-synthesized part), time, close. The host supplies an async `source` (sentences/paragraphs with ids → audio URLs, streamed page by page so playback starts on the first chunk while the rest synthesizes; pages merge by id so late URLs fill in) and gets `onSegmentChange(id)` at every boundary for highlight + scroll-follow. Media Session (lock-screen/headset controls, one document-wide position), keyboard scoped to the player (Space/K, ←/→ sentences, Shift+←/→ ±15s, [ / ] speed, Escape), speed+voice persisted in localStorage, `bind:api` for hosts wiring their own global keys, reduced-motion aware, token-only theming, never overflows its host (border-box, `max-width: 100%`, `min-width: 0` chain), fixed sticky mini-bar (same two rows) on narrow screens. Internals in `src/lib/listen/` (one timeline across per-sentence files — `buildTimeline` offsets; see `video/` for the doctrine). Demo synthesizes real WAVs locally. | `source`, `voices?`, `voiceId?` (bindable), `chapters?`, `title?`, `triggerLabel?`, `open?` (bindable), `preload?`, `estimateSec?`, `storageKey?`, `onSegmentChange?`, `onOpenChange?`, `api?` (bindable), `class?`, `children?` (custom trigger) |

package/dist/components/VideoPlayer.svelte

@@ -26,6 +26,8 @@
 	export type { ResumePoint } from '../video/advisors/resume-point';
 	// mos-5lzns.35 — settings registry + panel.
 	export type { VideoSettingsStore, SettingValue, SettingSpec } from '../video/settings';
+	// jatui-8nu4g — frame capture (what the host's "set as poster" hook receives).
+	export type { VideoFrameCapture } from '../video/capture';
 </script>
 
 <script lang="ts">
@@ -199,6 +201,18 @@
 	} from '../video/rate';
 	import { readTimeParam, WRITE_THROTTLE_MS, writeTimeParam } from '../video/deepLink';
 	import { isContextMenuKey, lineTextWithTime } from '../video/lineMenu';
+	import { qrSymbol, shareLinkAt } from '../video/qrShare';
+	import {
+		CAPTURE_NO_CORS_MESSAGE,
+		CAPTURE_NO_FRAME_MESSAGE,
+		captureActions,
+		captureFilename,
+		clipboardImageSupported,
+		frameDrawSize,
+		isCrossOriginCaptureError,
+		type CaptureAction,
+		type VideoFrameCapture
+	} from '../video/capture';
 	import {
 		biasCells,
 		biasGradient,
@@ -308,6 +322,35 @@
 		followResumeMs = FOLLOW_RESUME_IDLE_MS,
 		transcriptLineMenu = true,
 		buildTimeLink = undefined,
+		/**
+		 * Frame capture (jatui-8nu4g, extension-library parity library.js:9262):
+		 * a camera button on the band transport and the `C` key open a menu of
+		 * the frame verbs — Save frame as PNG, Copy frame to clipboard (only
+		 * where the platform can actually write an image; otherwise save-only),
+		 * and Set as poster when `onCaptureFrame` is supplied. Video only —
+		 * audio has no frame to grab. Default on; `false` removes the button
+		 * and the key.
+		 */
+		frameCapture = true,
+		/**
+		 * The host's capture hook — fires with the grabbed frame (PNG Blob,
+		 * data URL, playback time, pixel size, suggested name) when the viewer
+		 * picks "Set as poster"; MOS Studio uploads it and pins the video's
+		 * poster. Without it the menu item simply doesn't exist. May be async;
+		 * the player waits for it before reporting done, and a rejection is
+		 * said, not hidden.
+		 */
+		onCaptureFrame = undefined,
+		/**
+		 * Continue on phone (jatui-3k7cp, extension-library parity
+		 * library.js:4635): a QR button on the band transport opens a card with
+		 * the deep link AT THE CURRENT SECOND as a scannable QR code — the
+		 * host's `buildTimeLink` builds it (MOS builds its watch URL with
+		 * `?t=`); clicking the code copies the link. Hidden entirely when the
+		 * host supplies no `buildTimeLink` — the player never guesses a URL.
+		 * Default on; `false` removes the button.
+		 */
+		qrContinue = true,
 		theater = $bindable(false),
 		theaterMode = 'width',
 		theaterButton = true,
@@ -510,6 +553,23 @@
 		 * simply not on the menu — the player never guesses a URL.
 		 */
 		buildTimeLink?: (sec: number) => string;
+		/**
+		 * Frame capture (jatui-8nu4g) — see the destructure note above. Reads
+		 * the frame through a canvas, which a cross-origin video without CORS
+		 * taints: the export throws SecurityError and the player SAYS so
+		 * ("Can't capture this video (no CORS)") instead of failing silently.
+		 * Pass `crossorigin="anonymous"` for cross-origin media you want
+		 * frame-readable.
+		 */
+		frameCapture?: boolean;
+		/** The host's "set as poster" hook — receives a `VideoFrameCapture`. */
+		onCaptureFrame?: (capture: VideoFrameCapture) => void | Promise<void>;
+		/**
+		 * Continue on phone (jatui-3k7cp) — see the destructure note above.
+		 * Needs `buildTimeLink`: the URL is the host's (the player never
+		 * guesses one), so without a builder there is simply no QR button.
+		 */
+		qrContinue?: boolean;
 		/**
 		 * Theater mode (jatui-ee2ty) — bindable. NOT fullscreen: the player
 		 * only says it wants the page's width; the HOST lays its page out
@@ -1005,6 +1065,60 @@
 	let lineMenuY = $state(0);
 	let lineMenuSeg = $state<VideoTranscriptSegment | null>(null);
 
+	// ── Frame capture menu (jatui-8nu4g, extension library.js:9262) ────────
+	let captureMenuOpen = $state(false);
+	let captureMenuX = $state(0);
+	let captureMenuY = $state(0);
+	let captureBtnEl: HTMLButtonElement | undefined = $state();
+	/** Feature on: video only, and the host hasn't opted out. */
+	const frameCaptureOn = $derived(frameCapture && !isAudio);
+	/** Can this platform write an IMAGE to the clipboard? Static per page. */
+	const captureClipboardOk = $derived(clipboardImageSupported());
+	/** The verbs on the menu, in order — the pure decision, mapped to items. */
+	const captureMenuActions = $derived(
+		captureActions({ clipboardImage: captureClipboardOk, hostHook: onCaptureFrame != null })
+	);
+
+	// ── Continue on phone (jatui-3k7cp, extension library.js:4635) ───────
+	let qrOpen = $state(false);
+	let qrBtnEl: HTMLButtonElement | undefined = $state();
+	/** The link the open symbol was built from — frozen at open so the code
+	 *  under the phone's camera never changes mid-scan. */
+	let qrLink = $state('');
+	/** The second the link was frozen at — the card's own clock. */
+	let qrSec = $state(0);
+	/** Feature on: the host must own the URL (buildTimeLink). Without a
+	 *  builder there is nothing to encode — the player never guesses one —
+	 *  so the button simply doesn't exist. */
+	const qrShareOn = $derived(qrContinue && typeof buildTimeLink === 'function');
+	/** The symbol for the frozen link. Null ⇒ the card says the link is
+	 *  beyond the encoder's ceiling and keeps the copy verb working. */
+	const qrSym = $derived(qrOpen && qrLink ? qrSymbol(qrLink) : null);
+
+	/** Open the QR card: freeze the host's link at the CURRENT SECOND, then
+	 *  show the card. A builder that answers nothing (or throws) is said on
+	 *  the OSD — never a silent no-op, never an empty card. */
+	function openQrCard() {
+		const link = shareLinkAt(buildTimeLink, currentTime);
+		if (!link) {
+			flashOsd('No link to share');
+			announce('No link to share — the host did not supply one');
+			return;
+		}
+		qrLink = link;
+		qrSec = Math.max(0, Math.floor(currentTime));
+		qrOpen = true;
+	}
+
+	/** Clicking the code copies the link (and closes — the scan or the
+	 *  paste is the point; the card's job is done). The failure is said. */
+	async function copyQrLink() {
+		const ok = await copyText(qrLink);
+		flashOsd(ok ? 'Link copied' : 'Copy failed');
+		announce(ok ? 'Link copied to clipboard' : 'Copy failed');
+		if (ok) qrOpen = false;
+	}
+
 	let zoomTimer: ReturnType<typeof setTimeout> | null = null;
 	let osdTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -1489,6 +1603,7 @@
 			if (row.when === 'chapters') return sortedChapters.length > 0;
 		if (row.when === 'rail') return railOn;
 			if (row.when === 'bookmarks') return onAddBookmark != null;
+			if (row.when === 'capture') return frameCaptureOn;
 			if (row.when === 'transcript') return sortedSegments.length > 0;
 			if (row.when === 'comments') return socialMarkers.comments.length > 0;
 			if (row.when === 'night') return nightPresent;
@@ -3228,7 +3343,10 @@
 				// menu closes itself, the theater must not leave with it. The
 				// panel's own handler may already have closed it by the time this
 				// bubble-phase handler runs, hence the target check too.
-				!(lineMenuOpen || (e.target instanceof Element && e.target.closest('[role="menu"]')))
+				!(lineMenuOpen || (e.target instanceof Element && e.target.closest('[role="menu"]'))) &&
+				// The continue-on-phone card (jatui-3k7cp) owns Escape while it
+				// is open — Escape closes the card, never the theater.
+				!qrOpen
 			) {
 				e.preventDefault();
 				toggleTheater();
@@ -3249,13 +3367,23 @@
 		// Space/Enter on a focused button activates THAT button (play, a
 		// speaker chip, a transcript row); toggling playback too would undo it.
 		if (tag === 'BUTTON' && (e.key === ' ' || e.key === 'Enter')) return;
-		// The transcript line menu (jatui-3wl5x) owns the keyboard while it is
-		// open: arrows/Enter drive it (its panel preventDefaults what it uses,
-		// which the defaultPrevented guard above already yields to), Escape
-		// closes it, and nothing else drives the player underneath a floating
-		// menu. Tab is the shared ContextMenu's own behaviour (focus moves out
-		// with the menu still up; click/Escape dismiss it).
-		if (lineMenuOpen) return;
+		// The transcript line menu (jatui-3wl5x) and the frame-capture menu
+		// (jatui-8nu4g) own the keyboard while they are open: arrows/Enter drive
+		// them (their panel preventDefaults what it uses, which the
+		// defaultPrevented guard above already yields to), Escape closes, and
+		// nothing else drives the player underneath a floating menu. Tab is the
+		// shared ContextMenu's own behaviour (focus moves out with the menu
+		// still up; click/Escape dismiss it).
+		if (lineMenuOpen || captureMenuOpen) return;
+		// The continue-on-phone card (jatui-3k7cp) owns Escape while it is
+		// open; nothing else drives the player underneath it.
+		if (qrOpen) {
+			if (e.key === 'Escape') {
+				e.preventDefault();
+				qrOpen = false;
+			}
+			return;
+		}
 		// mos-777hj — the chapter rail owns j/k (listNav) and Enter/Space (row
 		// activation) while focus is inside it; without this guard a rail `k`
 		// would also toggle play/pause and a rail `j` also seek ±5s.
@@ -3422,6 +3550,15 @@
 					cycleNight();
 				}
 				return;
+			case 'c':
+			case 'C':
+				// Frame capture (jatui-8nu4g): video only; `frameCapture={false}`
+				// removes the key with the button. Off ⇒ not ours — no
+				// preventDefault, the page may keep it.
+				if (!frameCaptureOn) return;
+				e.preventDefault();
+				openCaptureMenuAtTrigger();
+				return;
 			case 'Home':
 				seekTo(0);
 				break;
@@ -3617,6 +3754,157 @@
 		return items;
 	});
 
+	// ── Frame capture (jatui-8nu4g, extension library.js:9262) ─────────────
+	// The camera button (band transport) and the `C` key both open ONE menu
+	// of frame verbs. The extension also burned a caption into the frame and
+	// ran OCR on it — deliberately not ported (the player has no OCR budget;
+	// hosts that want it can run it on the hook's dataUrl).
+
+	/** Open the menu anchored to the camera button (a click) — or, on a
+	 *  native transport with no button, the stage (`C` still works there);
+	 *  the position:fixed panel is viewport-clamped by floating-ui, so the
+	 *  anchor is a hint, not a law. */
+	function openCaptureMenuAtTrigger() {
+		const rect =
+			captureBtnEl?.getBoundingClientRect() ??
+			stageWrapEl?.getBoundingClientRect() ??
+			rootEl?.getBoundingClientRect();
+		captureMenuX = rect?.left ?? 0;
+		captureMenuY = rect ? rect.bottom + 6 : 0;
+		captureMenuOpen = true;
+	}
+
+	/** The current frame as a canvas at natural size. Null when there is
+	 *  nothing to grab yet — no metadata (videoWidth is 0 until it) or no
+	 *  decoded frame (drawImage refuses to make up pixels). Callers SAY
+	 *  null — never a silent no-op. */
+	function captureCanvas(): { canvas: HTMLCanvasElement; width: number; height: number } | null {
+		const size = frameDrawSize(videoEl);
+		if (!size || !videoEl) return null;
+		const canvas = document.createElement('canvas');
+		canvas.width = size.width;
+		canvas.height = size.height;
+		const ctx = canvas.getContext('2d');
+		if (!ctx) return null;
+		try {
+			ctx.drawImage(videoEl, 0, 0, size.width, size.height);
+		} catch {
+			return null; // no decoded frame yet (readyState too low)
+		}
+		return { canvas, width: size.width, height: size.height };
+	}
+
+	/** canvas.toBlob as a promise. A tainted canvas throws SecurityError out
+	 *  of toBlob itself — re-thrown here so every verb can check the NAME. */
+	function canvasToPng(canvas: HTMLCanvasElement): Promise<Blob> {
+		return new Promise((resolve, reject) => {
+			try {
+				canvas.toBlob(
+					(blob) => (blob ? resolve(blob) : reject(new Error('toBlob produced no blob'))),
+					'image/png'
+				);
+			} catch (e) {
+				reject(e);
+			}
+		});
+	}
+
+	function flashNoFrame() {
+		flashOsd(CAPTURE_NO_FRAME_MESSAGE);
+		announce('No frame yet — wait until the video has loaded a picture');
+	}
+
+	/** The taint verdict, said twice: OSD for the eye, polite region for the
+	 *  screen reader — a silent failure would read as a broken button. */
+	function flashNoCors() {
+		flashOsd(CAPTURE_NO_CORS_MESSAGE);
+		announce(`${CAPTURE_NO_CORS_MESSAGE} — the video host must allow cross-origin reads (CORS) to export frames.`);
+	}
+
+	function flashCaptureFailed(what: string) {
+		flashOsd(`${what} failed`);
+		announce(`${what} failed`);
+	}
+
+	/** Save frame as PNG: draw → toBlob → anchor download. A cross-origin
+	 *  video without CORS throws SecurityError out of toBlob itself —
+	 *  caught, said, never silent. */
+	function saveFrame() {
+		const c = captureCanvas();
+		if (!c) return flashNoFrame();
+		try {
+			c.canvas.toBlob((blob) => {
+				if (!blob) return flashCaptureFailed('Capture');
+				const url = URL.createObjectURL(blob);
+				const a = document.createElement('a');
+				a.href = url;
+				a.download = captureFilename(currentTime);
+				document.body.appendChild(a);
+				a.click();
+				a.remove();
+				setTimeout(() => URL.revokeObjectURL(url), 1000);
+				flashOsd('Frame saved');
+				announce('Frame saved as PNG');
+			}, 'image/png');
+		} catch (e) {
+			if (isCrossOriginCaptureError(e)) flashNoCors();
+			else flashCaptureFailed('Capture');
+		}
+	}
+
+	/** Copy frame: ClipboardItem carrying a PROMISE for the blob — the write
+	 *  call lands inside the click's user-gesture budget while the pixels
+	 *  encode async (Safari's gesture timer is the constraint). Unsupported
+	 *  platforms never get here: the item is omitted, save-only degrade. */
+	async function copyFrame() {
+		const c = captureCanvas();
+		if (!c) return flashNoFrame();
+		try {
+			await navigator.clipboard.write([new ClipboardItem({ 'image/png': canvasToPng(c.canvas) })]);
+			flashOsd('Copied');
+			announce('Frame copied to clipboard');
+		} catch (e) {
+			if (isCrossOriginCaptureError(e)) return flashNoCors();
+			flashCaptureFailed('Copy');
+		}
+	}
+
+	/** Set as poster: hand the frame to the host. MOS Studio uploads the
+	 *  blob and pins the video's poster; other hosts own their meaning. The
+	 *  host's rejection is said, not hidden. */
+	async function sendFrameToHost() {
+		const c = captureCanvas();
+		if (!c) return flashNoFrame();
+		try {
+			const blob = await canvasToPng(c.canvas);
+			const dataUrl = c.canvas.toDataURL('image/png');
+			const capture: VideoFrameCapture = {
+				blob,
+				dataUrl,
+				timeSec: currentTime,
+				width: c.width,
+				height: c.height,
+				name: captureFilename(currentTime)
+			};
+			await onCaptureFrame?.(capture);
+			flashOsd('Frame captured');
+			announce('Frame sent to host');
+		} catch (e) {
+			if (isCrossOriginCaptureError(e)) return flashNoCors();
+			flashCaptureFailed('Set as poster');
+		}
+	}
+
+	/** The menu's items for the verbs this page can actually run. */
+	const captureMenuItems = $derived.by<ContextMenuItem[]>(() => {
+		const verbs: Record<CaptureAction, ContextMenuItem> = {
+			save: { label: 'Save frame as PNG', icon: '⤓', onSelect: saveFrame },
+			copy: { label: 'Copy frame to clipboard', icon: '⧉', onSelect: copyFrame },
+			poster: { label: 'Set as poster', icon: '🖼️', onSelect: sendFrameToHost }
+		};
+		return captureMenuActions.map((a) => verbs[a]);
+	});
+
 	// ── Transcript search (jatui-xmtnv) ───────────────────────────────────
 	/** `/`: open the box (showing the transcript if it was hidden) and hand
 	 *  it focus once it mounts — the effect below lands it. */
@@ -4250,6 +4538,49 @@
 						aria-valuetext="{Math.round((mutedNow ? 0 : volumeLevel) * 100)}%"
 						oninput={onVolumeInput}
 					/>
+					{#if frameCaptureOn}
+						<!-- Frame capture (jatui-8nu4g): opens the frame verbs menu
+						     (save PNG / copy / set as poster). A picture verb, so it
+						     sits with the picture verbs at the end of the cluster. -->
+						<button
+							type="button"
+							class="vp-tbtn"
+							bind:this={captureBtnEl}
+							aria-haspopup="menu"
+							aria-expanded={captureMenuOpen}
+							aria-label="Capture frame"
+							title="Capture frame · C"
+							onclick={openCaptureMenuAtTrigger}
+						>
+							<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+								<path d="M3 8.6A1.6 1.6 0 0 1 4.6 7h3.4l1.3-2.2h5.4L16 7h3.4A1.6 1.6 0 0 1 21 8.6v8.8a1.6 1.6 0 0 1-1.6 1.6H4.6A1.6 1.6 0 0 1 3 17.4z" />
+								<circle cx="12" cy="13" r="3.2" />
+							</svg>
+						</button>
+					{/if}
+					{#if qrShareOn}
+						<!-- Continue on phone (jatui-3k7cp): opens the QR card for the
+						     host's buildTimeLink at the current second. A share verb,
+						     so it sits beside the capture verb at the end of the
+						     cluster. Works for audio too — the link is the point,
+						     not the picture. -->
+						<button
+							type="button"
+							class="vp-tbtn"
+							bind:this={qrBtnEl}
+							aria-haspopup="dialog"
+							aria-expanded={qrOpen}
+							aria-label="Continue on phone"
+							title="Continue on phone"
+							onclick={openQrCard}
+						>
+							<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" aria-hidden="true">
+								<!-- QR glyph: three finder squares + a few data modules -->
+								<path d="M3.5 3.5h6v6h-6zM14.5 3.5h6v6h-6zM3.5 14.5h6v6h-6z" />
+								<path d="M14.5 14.5h2.5v2.5h-2.5zM19 14.5h1.5v1.5H19zM14.5 19h1.5v1.5h-1.5zM18.5 18.5h2v2h-2z" fill="currentColor" stroke="none" />
+							</svg>
+						</button>
+					{/if}
 					{#if !isAudio}
 						<button
 							type="button"
@@ -4645,6 +4976,71 @@
 			onClose={() => (lineMenuSeg = null)}
 		/>
 	{/if}
+
+	{#if frameCaptureOn}
+		<!-- Frame-capture menu (jatui-8nu4g, extension library.js:9262): ONE
+		     panel, opened at the camera button (click) or wherever the `C` key
+		     was pressed from (anchored to the stage on a native transport).
+		     Rendered inside the root so the fill-theater Tab trap keeps cycling
+		     through its items; position:fixed + floating-ui place it wherever
+		     this spot sits in the layout. The header is the frame's own clock. -->
+		<ContextMenu
+			bind:open={captureMenuOpen}
+			x={captureMenuX}
+			y={captureMenuY}
+			items={captureMenuItems}
+			header={formatTime(currentTime, useHours)}
+		/>
+	{/if}
+
+	{#if qrShareOn && qrOpen}
+		<!-- Continue-on-phone card (jatui-3k7cp, extension library.js:4635):
+		     the same overlay family as the `?` help card — centered over the
+		     player, big enough to scan from arm's length, backdrop click or
+		     Escape closes. The link was FROZEN at open (qrLink), so the code
+		     under the phone's camera never changes mid-scan. The code is a real
+		     button: click it (or press Enter/Space on it) and the link is on
+		     the clipboard. Rendered as SVG <path> data from qrSymbol() — never
+		     {@html} of untrusted text. The black-on-white symbol is deliberate:
+		     QR contrast rules are about the SCANNER, not the theme, and a
+		     theme-tinted code scans far worse in dim rooms. -->
+		<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_static_element_interactions -->
+		<div class="vp-qr-backdrop" onclick={(e) => { if (e.target === e.currentTarget) qrOpen = false; }}>
+			<div class="vp-qr-card" role="dialog" aria-label="Continue on phone">
+				<div class="vp-qr-title">Continue on phone</div>
+				<div class="vp-qr-time">{formatTime(qrSec, useHours)}</div>
+				{#if qrSym}
+					<button
+						type="button"
+						class="vp-qr-code"
+						aria-label="Copy the link: {qrLink}"
+						title="Click to copy the link"
+						onclick={copyQrLink}
+					>
+						<svg
+							viewBox="0 0 {qrSym.size} {qrSym.size}"
+							shape-rendering="crispEdges"
+							role="img"
+							aria-hidden="true"
+						>
+							<rect width="{qrSym.size}" height="{qrSym.size}" fill="#ffffff" />
+							<path d={qrSym.path} fill="#000000" />
+						</svg>
+						<span class="vp-qr-hint">Click to copy the link</span>
+					</button>
+					<div class="vp-qr-link" title={qrLink}>{qrLink}</div>
+				{:else}
+					<!-- The encoder's ceiling (version 10) — said, with the copy
+					     verb kept working: the QR is the affordance, the link is
+					     the point. -->
+					<p class="vp-qr-fallback">
+						This link is too long for a QR code.
+					</p>
+					<button type="button" class="vp-qr-copy" onclick={copyQrLink}>Copy the link instead</button>
+				{/if}
+			</div>
+		</div>
+	{/if}
 </div>
 
 <style>
@@ -5986,6 +6382,112 @@
 		box-shadow: 0 8px 30px color-mix(in oklch, var(--color-base-content) 25%, transparent);
 	}
 
+	/* ── Continue on phone (jatui-3k7cp) — the QR card ─────────────────── */
+	/* Same overlay family as the `?` help card: centered over the player,
+	   backdrop click / Escape closes, focus stays in the root. */
+	.vp-qr-backdrop {
+		position: absolute;
+		inset: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		background: color-mix(in oklch, var(--color-base-100) 70%, transparent);
+		z-index: 10;
+		border-radius: inherit;
+	}
+
+	.vp-qr-card {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: var(--jatui-space-sm, 4px);
+		max-width: min(20rem, 90%);
+		padding: var(--jatui-space-lg, 12px);
+		background: var(--color-base-100);
+		border: var(--jatui-border-w, 1px) solid
+			color-mix(in oklch, var(--color-base-content) 18%, transparent);
+		border-radius: var(--jatui-radius-box, 0.5rem);
+		color: var(--color-base-content);
+		box-shadow: 0 8px 30px color-mix(in oklch, var(--color-base-content) 25%, transparent);
+	}
+
+	.vp-qr-title {
+		font-weight: 600;
+		font-size: 0.875rem;
+	}
+
+	.vp-qr-time {
+		font-size: 0.75rem;
+		opacity: 0.65;
+		font-variant-numeric: tabular-nums;
+	}
+
+	/* The code itself is a real button — click copies. The black-on-white
+	   symbol is FIXED colour, not theme tokens: QR contrast is about the
+	   scanner, not the palette (a theme-tinted code scans badly in dim
+	   rooms). Crisp edges keep modules square at every scale. */
+	.vp-qr-code {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: var(--jatui-space-xs, 2px);
+		padding: var(--jatui-space-sm, 4px);
+		border-radius: var(--jatui-radius-box, 0.5rem);
+		background: transparent;
+		border: none;
+		cursor: pointer;
+	}
+
+	.vp-qr-code:focus-visible {
+		outline: 2px solid var(--color-primary);
+		outline-offset: 2px;
+	}
+
+	.vp-qr-code svg {
+		width: 13rem;
+		height: 13rem;
+		max-width: 100%;
+		display: block;
+		border-radius: 0.25rem;
+	}
+
+	.vp-qr-hint {
+		font-size: 0.6875rem;
+		opacity: 0.6;
+	}
+
+	.vp-qr-link {
+		max-width: 100%;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+		font-size: 0.6875rem;
+		opacity: 0.75;
+		direction: rtl;
+		text-align: left;
+	}
+
+	.vp-qr-fallback {
+		font-size: 0.8125rem;
+		opacity: 0.8;
+		margin: var(--jatui-space-sm, 4px) 0 0;
+	}
+
+	.vp-qr-copy {
+		padding: var(--jatui-space-xs, 2px) var(--jatui-space-md, 6px);
+		border-radius: var(--jatui-radius-field, 0.5rem);
+		border: var(--jatui-border-w, 1px) solid
+			color-mix(in oklch, var(--color-base-content) 25%, transparent);
+		background: transparent;
+		color: inherit;
+		font-size: 0.8125rem;
+		cursor: pointer;
+	}
+
+	.vp-qr-copy:hover {
+		background: color-mix(in oklch, var(--color-base-content) 10%, transparent);
+	}
+
 	.vp-keys-title {
 		font-size: 0.66rem;
 		font-weight: 700;

package/dist/components/VideoPlayer.svelte.d.ts

@@ -9,6 +9,7 @@ export type { VideoAdSpan, RateReport } from '../video/rate';
 export type { WindDownState, WindDownPhase, PresenceSource, VideoResumeStore, FlipSource } from '../video/presence';
 export type { ResumePoint } from '../video/advisors/resume-point';
 export type { VideoSettingsStore, SettingValue, SettingSpec } from '../video/settings';
+export type { VideoFrameCapture } from '../video/capture';
 /**
      * VideoPlayer — one video surface for everything, from a bare mp4 to a
      * fully-analysed recording.
@@ -71,6 +72,7 @@ import { type BandState } from '../video/band/axis';
 import { type VideoLumaTrack } from '../video/band/luma';
 import { type VideoMarker } from '../video/band/markers';
 import { type RateReport, type VideoAdSpan } from '../video/rate';
+import { type VideoFrameCapture } from '../video/capture';
 import { type NightMode, type NightWindow } from '../video/night/clock';
 import { type AudioBrokenReason, type AudioState } from '../video/audio';
 import { type FlipSource, type VideoResumeStore, type WindDownState } from '../video/presence';
@@ -209,6 +211,23 @@ type $$ComponentProps = {
      * simply not on the menu — the player never guesses a URL.
      */
     buildTimeLink?: (sec: number) => string;
+    /**
+     * Frame capture (jatui-8nu4g) — see the destructure note above. Reads
+     * the frame through a canvas, which a cross-origin video without CORS
+     * taints: the export throws SecurityError and the player SAYS so
+     * ("Can't capture this video (no CORS)") instead of failing silently.
+     * Pass `crossorigin="anonymous"` for cross-origin media you want
+     * frame-readable.
+     */
+    frameCapture?: boolean;
+    /** The host's "set as poster" hook — receives a `VideoFrameCapture`. */
+    onCaptureFrame?: (capture: VideoFrameCapture) => void | Promise<void>;
+    /**
+     * Continue on phone (jatui-3k7cp) — see the destructure note above.
+     * Needs `buildTimeLink`: the URL is the host's (the player never
+     * guesses one), so without a builder there is simply no QR button.
+     */
+    qrContinue?: boolean;
     /**
      * Theater mode (jatui-ee2ty) — bindable. NOT fullscreen: the player
      * only says it wants the page's width; the HOST lays its page out

package/dist/video/README.md

@@ -20,7 +20,9 @@ props + callback surfaces.
 | `keys.ts` | .28 (done) | The keyboard map — `PLAYER_KEYS` (the `?` overlay renders it), `chapterJump`, `FRAME_STEP_SEC`. Every key that exists is in the map; a key not in the map doesn't exist. |
 | `rate.ts` + `rate/` | .28 contract — **.32** (done) | `rate.ts` is the barrel. `compose.ts` — the contract (`composeRate`, clamp [0.0625, 16], `shouldWriteRate`'s 0.001 deadband with an exact return to base), the `SPEED_STEPS` staircase, `formatSpeedLabel`. `speaker.ts` — props → `advisors/speaker-rate`; manual rates keyed by NAME always beat measured. `silence.ts` — waveform → `advisors/smart-speed` map + boost + the OSD saving claim. `ads.ts` — `adSpans` ∪ `ad: true` turns; skip only when PLAYBACK runs into an ad, never when a seek lands in one. `tick.ts` — the component's own 120ms loop's one-tick decision. `manual` (E73, jatui-p3m3u) — the viewer's remembered per-speaker speeds from the chip menu, multiplying with the automatic advisor; the composer clamps the product. None of them write `playbackRate`; they advise. |
 | `deepLink.ts` | .28 (done) | `?t=` parse/format/read/write (replaceState, throttled, other params preserved) + `buildTimeUrl` (jatui-3wl5x) — the `?t=` URL builder hosts pass as `buildTimeLink` (MOS's "copy link at this time" shape). |
+| `capture.ts` | **jatui-8nu4g** (done) | The frame-capture menu's pure pieces (extension-library parity, library.js:9262): `captureFilename` (the frame clock as the name — `frame-1m30s.png`, junk times clamp to 0), `clipboardImageSupported` (secure context + `navigator.clipboard.write` + `ClipboardItem` — false ⇒ save-only degrade, the Copy row is OMITTED, never dead), `captureActions` (which verbs the menu carries — save always, copy only where the platform can write an image, poster only when the host supplied `onCaptureFrame`), `frameDrawSize` (null before metadata — a 0×0 canvas is never a valid capture), `isCrossOriginCaptureError` (the SecurityError NAME is the contract — a tainted canvas throws SecurityError out of toBlob/toDataURL itself) and `VideoFrameCapture` (what the host's "set as poster" hook receives: blob, dataUrl, timeSec, width, height, name). The component owns the canvas and the `<video>` (drawImage / toBlob / toDataURL / download / clipboard calls live there); a cross-origin video without CORS is SAID — `CAPTURE_NO_CORS_MESSAGE` on the OSD + polite region, never a silent no-op. |
 | `lineMenu.ts` | **jatui-3wl5x** | The transcript line right-click menu's pure pieces: `isContextMenuKey` (the keyboard's right-click — Context-menu key or Shift+F10) and `lineTextWithTime` (`[1:23] text`, the row's own clock). The component owns the DOM — which row opened it, cursor vs row anchoring, focus return — and the menu itself is the shared `ContextMenu`. |
+| `qrShare.ts` | **jatui-3k7cp** | "Continue on phone" pure pieces (extension-library parity, library.js:4635): `qrSymbol` — the QR of a link as SVG PATH DATA over `advisors/qr`'s zero-dep encoder (dark modules run-merged into one `path` the test re-parses; quiet zone 4; null, never a throw, when the text can't be a symbol — the component says "too long" and keeps copy working), and `shareLinkAt` (the host's `buildTimeLink` at the FLOORED current second; every broken shape degrades to null). The URL is the host's — no builder, no button. The component owns the card: centered like the `?` help overlay, link frozen at open so the code under the phone's camera never changes mid-scan, clicking the code copies, SVG only — never `{@html}` of untrusted text. |
 | `transcriptSearch.ts` | **jatui-xmtnv** (E25/E57) | The transcript search + wheel line-scrub pure helpers: `searchHits` (case-insensitive, non-overlapping), `highlightRowHtml` (`<mark>`s around matches, everything else escaped — host transcript text is never markup), `pickMatch` (Enter walks matches from the playhead, wrapping), `lineScrubTarget` + `transcriptWheelDecision`/`effectiveWheelDelta` (Shift+wheel steps a line per ~100px notch; a plain wheel is never claimed). The component owns the box, focus, Esc layering and the `n / m` count. |
 | `settings.ts` + `settings/` | **.35** (done) — knobs added by .30–.34 | `settings.ts` is the barrel. `registry.ts` — `VIDEO_SETTINGS`: id, group, label, **mandatory hint**, the prop it drives, the availability gate (`when`); `coerce` never throws (hostile values, throwing `valueOf`, Symbols → undefined). Labels/hints are the single source for the panel AND a host help page. `store.ts` — the host-supplied `VideoSettingsStore` (`get`/`set`, either async; jatui never persists on its own) and `createSettingsSession`: coerced reads, a choice made on screen beats a late read, per-id debounced writes flushed on close. `panel.ts` — `panelGroups` (rows only for features this player has — omitted, never disabled), value formatting, radio stepping. `SettingsPanel.svelte` — the generated dialog (switch / radio group / range, focus trap, Esc/`,` close, focus handed back). `remembered.ts` (jatui-xz6so) — remembered MEDIA state (E12: volume + mute survive a reload), coerced like settings and persisted through the same store split (`settingsStore`, else guarded localStorage) but deliberately never panel rows: remembering is not configuring. In the component a stored choice overlays its prop but never creates a presence-gated feature; `night`/`nightDepth` are written through their bindings and `N`/the moon wheel are saved back. The one permission ask is `sleep.desktopIdle` turned on, from that click. A knob lands WITH its reader. |
 | `audio.ts` + `audio/` | **.31** (done) | `audio.ts` is the barrel. `rider.ts` — pure: RMS dBFS (silence → null), the 12 dB relative-gated loud estimate (rise 0.08 / forget 0.01), want-gain clamped 0.3–1.35, the asymmetric ride (down 0.15 / up 0.02), limiter constants + `compressorMakeupDb`/`limiterTrim` (DynamicsCompressor's automatic makeup, cancelled by a trim node), `routeSafety` (only blob:/data: or a `crossorigin` load — a same-origin URL may redirect cross-origin and route to SILENCE). `graph.ts` — `createAudioSession`: source → gain → quiet chain → limiter → trim → destination, analyser on the source. Context first, route last: the element is taken only when a feature is on, the source is route-safe and `ctx.state === 'running'` (gestures resume + retry; never navigator.userActivation). After routing it watches: an unsafe src or bit-exact zeros while audibly playing ⇒ `broken` (`unsafe-src` / `silent`) via `onBroken`. A construction throw is a permanent `build-failed` (context closed if the element wasn't taken; kept with source → destination if it was). Level off cancels before it sets; limiter moves are ramped. The element never enters the module — the component passes a `route` closure. |

package/dist/video/advisors/README.md

@@ -16,5 +16,5 @@
  * | `speaker-rate` | each speaker's measured wpm, the rates that even them out | rate composer's `speaker` advisor (.32) |
  * | `resume-point` | the nearest real boundary at-or-before a stored time + the line to say | resume-at-sentence (.34) |
  * | `quiet-listening` | the loudness-compensated tone graph + how much of it is wanted | audio graph (.31) |
- * | `qr` | the deep link as a scannable symbol | "continue on phone" (host UI) |
+ * | `qr` | the deep link as a scannable symbol | "continue on phone" (jatui-3k7cp, via `../qrShare`) |
  */

package/dist/video/capture.d.ts

@@ -0,0 +1,90 @@
+/**
+ * VideoPlayer frame capture (jatui-8nu4g — extension-library parity,
+ * library.js:9262) — the capture menu's PURE pieces, per the advisor
+ * doctrine: no DOM here, no element, no settings reads. The component owns
+ * the canvas and the `<video>` (the drawImage / toBlob / toDataURL /
+ * download / clipboard calls live there); everything that DECIDES lives in
+ * this file so it stays node-testable.
+ *
+ * The verbs: Save frame as PNG (always), Copy frame to clipboard (only
+ * where the platform can actually write an image — secure context +
+ * `navigator.clipboard.write` + `ClipboardItem` — otherwise the item is
+ * OMITTED, never a dead menu row), and Set as poster (only when the host
+ * supplies `onCaptureFrame`; the host owns what "poster" means).
+ *
+ * Cross-origin video without CORS taints the canvas: toBlob/toDataURL
+ * throw SecurityError. The component catches that and says so —
+ * `CAPTURE_NO_CORS_MESSAGE` — never a silent no-op.
+ */
+/** The OSD + polite-region message for a tainted canvas (no CORS). */
+export declare const CAPTURE_NO_CORS_MESSAGE = "Can't capture this video (no CORS)";
+/** The message when there is no decodable frame to grab yet. */
+export declare const CAPTURE_NO_FRAME_MESSAGE = "No frame yet";
+/**
+ * The suggested download name for the frame at `sec`: `frame-1m30s.png`,
+ * `frame-1h02m30s.png` on long videos, seconds zero-padded. A junk time
+ * (negative, NaN) clamps to 0 — a filename never carries NaN.
+ */
+export declare function captureFilename(sec: number): string;
+/** The pieces of the platform a clipboard IMAGE write needs. */
+export interface ClipboardImageEnv {
+    /** `navigator.clipboard?.write` — undefined off a secure context. */
+    clipboardWrite?: unknown;
+    /** `window.isSecureContext`. */
+    isSecureContext?: boolean;
+    /** The global `ClipboardItem` constructor. */
+    clipboardItem?: unknown;
+}
+/**
+ * Can this platform write an image to the clipboard? A clipboard image
+ * write needs a secure context (navigator.clipboard only exists on HTTPS /
+ * localhost), the `write` method, and the `ClipboardItem` constructor.
+ * False ⇒ the component degrades to save-only: the Copy item is omitted,
+ * never rendered dead.
+ */
+export declare function clipboardImageSupported(env?: ClipboardImageEnv): boolean;
+/** The capture menu's verbs, in menu order. */
+export type CaptureAction = 'save' | 'copy' | 'poster';
+/**
+ * Which verbs the capture menu carries. Save is always there; Copy only
+ * where the platform can write an image (degrade to save-only); the poster
+ * hook only when the host supplied `onCaptureFrame`. Omitted — never
+ * disabled — matching the settings-panel doctrine.
+ */
+export declare function captureActions(opts?: {
+    clipboardImage?: boolean;
+    hostHook?: boolean;
+}): CaptureAction[];
+/** What `onCaptureFrame` receives when the viewer picks "Set as poster". */
+export interface VideoFrameCapture {
+    /** The frame as an `image/png` Blob — upload it, attach it, store it. */
+    blob: Blob;
+    /** The same frame as a PNG data URL — preview without an objectURL lifecycle. */
+    dataUrl: string;
+    /** Playback time the frame was grabbed at (seconds). */
+    timeSec: number;
+    /** Natural frame dimensions in px. */
+    width: number;
+    height: number;
+    /** Suggested filename — `captureFilename(timeSec)`. */
+    name: string;
+}
+/**
+ * The natural frame size to draw at, or null before metadata has landed
+ * (videoWidth/videoHeight are 0 until then — there is nothing to grab yet,
+ * and a 0×0 canvas is never a valid capture).
+ */
+export declare function frameDrawSize(video: {
+    videoWidth?: number | null;
+    videoHeight?: number | null;
+}): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * A SecurityError from the canvas means the media's bytes are not readable
+ * from this origin (cross-origin without CORS) — the export path, not the
+ * player, is refusing. Other engines word it differently; the NAME is the
+ * contract.
+ */
+export declare function isCrossOriginCaptureError(e: unknown): boolean;

package/dist/video/capture.js

@@ -0,0 +1,104 @@
+/**
+ * VideoPlayer frame capture (jatui-8nu4g — extension-library parity,
+ * library.js:9262) — the capture menu's PURE pieces, per the advisor
+ * doctrine: no DOM here, no element, no settings reads. The component owns
+ * the canvas and the `<video>` (the drawImage / toBlob / toDataURL /
+ * download / clipboard calls live there); everything that DECIDES lives in
+ * this file so it stays node-testable.
+ *
+ * The verbs: Save frame as PNG (always), Copy frame to clipboard (only
+ * where the platform can actually write an image — secure context +
+ * `navigator.clipboard.write` + `ClipboardItem` — otherwise the item is
+ * OMITTED, never a dead menu row), and Set as poster (only when the host
+ * supplies `onCaptureFrame`; the host owns what "poster" means).
+ *
+ * Cross-origin video without CORS taints the canvas: toBlob/toDataURL
+ * throw SecurityError. The component catches that and says so —
+ * `CAPTURE_NO_CORS_MESSAGE` — never a silent no-op.
+ */
+/** The OSD + polite-region message for a tainted canvas (no CORS). */
+export const CAPTURE_NO_CORS_MESSAGE = "Can't capture this video (no CORS)";
+/** The message when there is no decodable frame to grab yet. */
+export const CAPTURE_NO_FRAME_MESSAGE = 'No frame yet';
+/**
+ * The suggested download name for the frame at `sec`: `frame-1m30s.png`,
+ * `frame-1h02m30s.png` on long videos, seconds zero-padded. A junk time
+ * (negative, NaN) clamps to 0 — a filename never carries NaN.
+ */
+export function captureFilename(sec) {
+    const t = Number.isFinite(sec) ? Math.max(0, Math.floor(sec)) : 0;
+    const h = Math.floor(t / 3600);
+    const m = Math.floor((t % 3600) / 60);
+    const s = t % 60;
+    const ss = String(s).padStart(2, '0');
+    const clock = h > 0 ? `${h}h${String(m).padStart(2, '0')}m${ss}s` : `${m}m${ss}s`;
+    return `frame-${clock}.png`;
+}
+/**
+ * Reads the real platform (SSR/node safe — every global behind a typeof).
+ * Isolated from the predicate so tests inject fakes instead of stubbing
+ * globals.
+ */
+function currentClipboardImageEnv() {
+    if (typeof navigator === 'undefined')
+        return { isSecureContext: false, clipboardItem: undefined };
+    const clip = navigator.clipboard;
+    let item = undefined;
+    try {
+        // Reference the global indirectly: a bare `typeof ClipboardItem` is
+        // fine, but keeping it in one place documents that ONLY its existence
+        // matters here, not what it can hold.
+        item = typeof ClipboardItem === 'function' ? ClipboardItem : undefined;
+    }
+    catch {
+        item = undefined;
+    }
+    return {
+        clipboardWrite: clip?.write,
+        isSecureContext: typeof window !== 'undefined' ? window.isSecureContext === true : false,
+        clipboardItem: item
+    };
+}
+/**
+ * Can this platform write an image to the clipboard? A clipboard image
+ * write needs a secure context (navigator.clipboard only exists on HTTPS /
+ * localhost), the `write` method, and the `ClipboardItem` constructor.
+ * False ⇒ the component degrades to save-only: the Copy item is omitted,
+ * never rendered dead.
+ */
+export function clipboardImageSupported(env = currentClipboardImageEnv()) {
+    return typeof env.clipboardWrite === 'function' && env.isSecureContext === true && typeof env.clipboardItem === 'function';
+}
+/**
+ * Which verbs the capture menu carries. Save is always there; Copy only
+ * where the platform can write an image (degrade to save-only); the poster
+ * hook only when the host supplied `onCaptureFrame`. Omitted — never
+ * disabled — matching the settings-panel doctrine.
+ */
+export function captureActions(opts = {}) {
+    const actions = ['save'];
+    if (opts.clipboardImage)
+        actions.push('copy');
+    if (opts.hostHook)
+        actions.push('poster');
+    return actions;
+}
+/**
+ * The natural frame size to draw at, or null before metadata has landed
+ * (videoWidth/videoHeight are 0 until then — there is nothing to grab yet,
+ * and a 0×0 canvas is never a valid capture).
+ */
+export function frameDrawSize(video) {
+    const w = video?.videoWidth ?? 0;
+    const h = video?.videoHeight ?? 0;
+    return w > 0 && h > 0 ? { width: w, height: h } : null;
+}
+/**
+ * A SecurityError from the canvas means the media's bytes are not readable
+ * from this origin (cross-origin without CORS) — the export path, not the
+ * player, is refusing. Other engines word it differently; the NAME is the
+ * contract.
+ */
+export function isCrossOriginCaptureError(e) {
+    return e instanceof DOMException && e.name === 'SecurityError';
+}

package/dist/video/keys.d.ts

@@ -11,8 +11,9 @@
  * none yet).
  * Deliberately NOT ported: F/M (favourite/file-under — library-app verbs,
  * not player verbs). N (night cycle) landed with the night module
- * (mos-5lzns.33) and `,` (settings) with the settings panel
- * (mos-5lzns.35), each gated on the host opting in.
+ * (mos-5lzns.33), `,` (settings) with the settings panel (mos-5lzns.35) and
+ * C (frame capture) with the capture menu (jatui-8nu4g, extension
+ * library.js:9262), each gated on the host opting in.
  */
 export interface PlayerKeyRow {
     /** Keycap label as shown in the help overlay — `/`-separated alternates. */
@@ -22,7 +23,7 @@ export interface PlayerKeyRow {
      * Availability gate: the row is only advertised (and the key only bound)
      * when the feature's data exists. Undefined ⇒ always active.
      */
-    when?: 'chapters' | 'rail' | 'bookmarks' | 'transcript' | 'comments' | 'night' | 'settings' | 'theater';
+    when?: 'chapters' | 'rail' | 'bookmarks' | 'capture' | 'transcript' | 'comments' | 'night' | 'settings' | 'theater';
 }
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export declare const PLAYER_KEYS: PlayerKeyRow[];

package/dist/video/keys.js

@@ -11,8 +11,9 @@
  * none yet).
  * Deliberately NOT ported: F/M (favourite/file-under — library-app verbs,
  * not player verbs). N (night cycle) landed with the night module
- * (mos-5lzns.33) and `,` (settings) with the settings panel
- * (mos-5lzns.35), each gated on the host opting in.
+ * (mos-5lzns.33), `,` (settings) with the settings panel (mos-5lzns.35) and
+ * C (frame capture) with the capture menu (jatui-8nu4g, extension
+ * library.js:9262), each gated on the host opting in.
  */
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export const PLAYER_KEYS = [
@@ -32,6 +33,10 @@ export const PLAYER_KEYS = [
     // and "people's reactions to it" sit under one hand (mos-5lzns.30).
     { keys: '{ / }', description: 'Previous / next comment', when: 'comments' },
     { keys: 'B', description: 'Bookmark at the current time', when: 'bookmarks' },
+    // C (jatui-8nu4g, extension library.js:9262) — the frame-capture menu:
+    // save the current frame as PNG, copy it (where the platform can write
+    // images), and set as poster when the host supplies the hook. Video only.
+    { keys: 'C', description: 'Frame capture: save PNG / copy / set as poster', when: 'capture' },
     // t = theater, YouTube's key; the transcript moved to Shift+T (jatui-ee2ty).
     { keys: 't', description: 'Theater mode on / off', when: 'theater' },
     { keys: 'Shift+T', description: 'Cycle transcript layout: side / below / hidden', when: 'transcript' },

package/dist/video/qrShare.d.ts

@@ -0,0 +1,55 @@
+/**
+ * "Continue on phone" (jatui-3k7cp — extension-library parity, library.js:4635
+ * / lib/qr.js): the video you are watching moves from the desk to a phone
+ * mid-sentence. The player shows a QR of the deep link AT THE CURRENT SECOND —
+ * the host's `buildTimeLink` builder (the same one the transcript line menu's
+ * "Copy link at this time" uses; MOS builds its watch URL with `?t=`) — the
+ * viewer points a phone camera at it, and clicking the symbol copies the link.
+ *
+ * The URL is the HOST's: the player never guesses one, and the whole feature
+ * is absent when no builder is supplied. The encoder underneath is the
+ * zero-dependency ISO 18004 port in `advisors/qr.ts` (deliberately no npm
+ * dependency — see that file's header for why).
+ *
+ * The pure pieces live here so they stay node-testable; the component owns
+ * the DOM: the button, the card, the clipboard write.
+ *
+ * The symbol is rendered as SVG PATH DATA — dark modules become one `path`
+ * element the host stylesheet/theme can never reflow — never `{@html}` of
+ * untrusted text.
+ */
+import { type EccLevel } from './advisors/qr';
+/** The spec's minimum quiet zone — 4 modules of light around the symbol. */
+export declare const QR_QUIET_ZONE = 4;
+export interface QrSymbol {
+    /** SVG viewBox side in modules: the symbol plus the quiet zone on both sides. */
+    size: number;
+    /**
+     * Path data covering exactly the dark modules, one subpath per horizontal
+     * run (`M{x} {y}h{w}v1h-{w}z`), coordinates offset by the quiet zone so
+     * the viewBox is `0 0 size size`. Designed to be re-parsed: the unit test
+     * reconstructs the grid from this string and compares it against
+     * `qrMatrix`'s own modules.
+     */
+    path: string;
+}
+/**
+ * The QR symbol for `text` as SVG geometry, or null when it cannot exist —
+ * non-string/empty input, or text beyond the encoder's ceiling (version 10
+ * at this ECC; ~213 bytes at M). Null, never a throw: the component SAYS
+ * "too long" and keeps the copy verb working — a missing symbol must not
+ * take the whole action down.
+ */
+export declare function qrSymbol(text: unknown, opts?: {
+    ecc?: EccLevel;
+    quietZone?: number;
+}): QrSymbol | null;
+/**
+ * The shareable link at a playback second, from the host's builder. Floors
+ * the second (the link's promise is "picks up at 1:23", not "1:22.87" — same
+ * convention as deepLink.ts's writes), and degrades to null rather than
+ * throwing: a builder that isn't a function, a non-finite time, a builder
+ * that throws, or one that answers empty all mean "no link to share", which
+ * the component says instead of opening an empty card.
+ */
+export declare function shareLinkAt(build: unknown, sec: number): string | null;

package/dist/video/qrShare.js

@@ -0,0 +1,86 @@
+/**
+ * "Continue on phone" (jatui-3k7cp — extension-library parity, library.js:4635
+ * / lib/qr.js): the video you are watching moves from the desk to a phone
+ * mid-sentence. The player shows a QR of the deep link AT THE CURRENT SECOND —
+ * the host's `buildTimeLink` builder (the same one the transcript line menu's
+ * "Copy link at this time" uses; MOS builds its watch URL with `?t=`) — the
+ * viewer points a phone camera at it, and clicking the symbol copies the link.
+ *
+ * The URL is the HOST's: the player never guesses one, and the whole feature
+ * is absent when no builder is supplied. The encoder underneath is the
+ * zero-dependency ISO 18004 port in `advisors/qr.ts` (deliberately no npm
+ * dependency — see that file's header for why).
+ *
+ * The pure pieces live here so they stay node-testable; the component owns
+ * the DOM: the button, the card, the clipboard write.
+ *
+ * The symbol is rendered as SVG PATH DATA — dark modules become one `path`
+ * element the host stylesheet/theme can never reflow — never `{@html}` of
+ * untrusted text.
+ */
+import { qrMatrix } from './advisors/qr';
+/** The spec's minimum quiet zone — 4 modules of light around the symbol. */
+export const QR_QUIET_ZONE = 4;
+/**
+ * The QR symbol for `text` as SVG geometry, or null when it cannot exist —
+ * non-string/empty input, or text beyond the encoder's ceiling (version 10
+ * at this ECC; ~213 bytes at M). Null, never a throw: the component SAYS
+ * "too long" and keeps the copy verb working — a missing symbol must not
+ * take the whole action down.
+ */
+export function qrSymbol(text, opts) {
+    if (typeof text !== 'string' || text === '')
+        return null;
+    let quiet = Math.trunc(Number(opts?.quietZone));
+    if (!Number.isFinite(quiet) || quiet < 0)
+        quiet = QR_QUIET_ZONE;
+    quiet = Math.min(quiet, 8);
+    let matrix;
+    try {
+        matrix = qrMatrix(text, { ecc: opts?.ecc ?? 'M' });
+    }
+    catch {
+        return null;
+    }
+    const { size, modules } = matrix;
+    let path = '';
+    for (let y = 0; y < size; y++) {
+        const row = modules[y];
+        let x = 0;
+        while (x < size) {
+            if (!row[x]) {
+                x++;
+                continue;
+            }
+            let run = 1;
+            while (x + run < size && row[x + run])
+                run++;
+            path += `M${x + quiet} ${y + quiet}h${run}v1h-${run}z`;
+            x += run;
+        }
+    }
+    return { size: size + quiet * 2, path };
+}
+/**
+ * The shareable link at a playback second, from the host's builder. Floors
+ * the second (the link's promise is "picks up at 1:23", not "1:22.87" — same
+ * convention as deepLink.ts's writes), and degrades to null rather than
+ * throwing: a builder that isn't a function, a non-finite time, a builder
+ * that throws, or one that answers empty all mean "no link to share", which
+ * the component says instead of opening an empty card.
+ */
+export function shareLinkAt(build, sec) {
+    if (typeof build !== 'function')
+        return null;
+    const s = Number(sec);
+    if (!Number.isFinite(s) || s < 0)
+        return null;
+    let link;
+    try {
+        link = build(Math.floor(s));
+    }
+    catch {
+        return null;
+    }
+    return typeof link === 'string' && link !== '' ? link : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",