@joewinke/jatui 0.51.0 → 0.52.0

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,17 @@
 	} from '../video/rate';
 	import { readTimeParam, WRITE_THROTTLE_MS, writeTimeParam } from '../video/deepLink';
 	import { isContextMenuKey, lineTextWithTime } from '../video/lineMenu';
+	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 +321,25 @@
 		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,
 		theater = $bindable(false),
 		theaterMode = 'width',
 		theaterButton = true,
@@ -510,6 +542,17 @@
 		 * 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>;
 		/**
 		 * 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 +1048,20 @@
 	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 })
+	);
+
 	let zoomTimer: ReturnType<typeof setTimeout> | null = null;
 	let osdTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -1489,6 +1546,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;
@@ -3249,13 +3307,14 @@
 		// 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;
 		// 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 +3481,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 +3685,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 +4469,26 @@
 						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 !isAudio}
 						<button
 							type="button"
@@ -4645,6 +4884,22 @@
 			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}
 </div>
 
 <style>

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,17 @@ 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>;
     /**
      * 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,6 +20,7 @@ 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`. |
 | `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. |

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/package.json

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