feat(scanner): fill the screen with the camera and add preview zoom and pan

The camera preview now covers the whole screen behind the floating
controls instead of letterboxing in black, and the page background
follows the palette. Scanner settings gain a Camera preview section with
zoom and horizontal/vertical pan, so a phone on a scanning stand can
centre the card between the controls. Only the preview moves: the
recognizer still scans the whole camera image. The corner brackets frame
the on-screen part inside the system bars, and tap-to-focus and detected
card outlines follow the preview crop.

Amp-Thread-ID: https://ampcode.com/threads/T-01a0eaaa-22a0-77a9-8d6c-ddfed62424d8

Author: cfbender

assets/react/src/pages/scan/preview-framing.ts

@@ -0,0 +1,40 @@
+export type Size = { width: number; height: number }
+/** A rectangle in the camera image's pixel space. */
+export type Rect = { x: number; y: number; width: number; height: number }
+
+/**
+ * How the camera preview fills the screen. The preview always covers the screen; `zoom`
+ * enlarges it beyond that, and `panX`/`panY` (0–1 of the camera image) pick the point shown at
+ * the middle of the screen, as far as the image's edges allow. Only the preview changes: the
+ * recognizer always scans the whole camera image.
+ */
+export interface PreviewFraming {
+  zoom: number
+  panX: number
+  panY: number
+}
+
+/** The part of the camera `image` the preview shows in a `box` of the given size. */
+export function previewRect(image: Size, box: Size, framing: PreviewFraming): Rect {
+  const scale = Math.max(box.width / image.width, box.height / image.height) * framing.zoom
+  const width = Math.min(image.width, box.width / scale)
+  const height = Math.min(image.height, box.height / scale)
+  const clamp = (value: number, max: number) => Math.min(Math.max(value, 0), max)
+  return {
+    x: clamp(framing.panX * image.width - width / 2, image.width - width),
+    y: clamp(framing.panY * image.height - height / 2, image.height - height),
+    width,
+    height,
+  }
+}
+
+/** A `box` on screen (relative to the preview's `container`) in camera image pixels. */
+export function inImage(box: Rect, visible: Rect, container: Rect): Rect {
+  const scale = visible.width / container.width
+  return {
+    x: visible.x + box.x * scale,
+    y: visible.y + box.y * scale,
+    width: box.width * scale,
+    height: box.height * scale,
+  }
+}

assets/react/src/pages/scan/scan-page.tsx

@@ -58,7 +58,7 @@ export function ScanPage() {
 
   return (
     <div
-      className="scan-page fixed inset-0 z-40 overflow-hidden bg-black text-base-content"
+      className="scan-page fixed inset-0 z-40 overflow-hidden bg-base-100 text-base-content"
       data-theme="dark"
       data-palette={
         typeof document === "undefined"
@@ -69,10 +69,15 @@ export function ScanPage() {
       <ScanViewfinder
         videoRef={camera.videoRef}
         view={view}
+        framing={{
+          zoom: settings.previewZoom,
+          panX: settings.previewPanX,
+          panY: settings.previewPanY,
+        }}
         onFocusAt={(x, y) => void camera.focusAt(x, y)}
       />
 
-      <header className="absolute inset-x-0 top-0 z-10 flex items-center gap-2 bg-gradient-to-b from-black/70 to-transparent px-3 pb-8 pt-[calc(var(--safe-top)_+_0.75rem)]">
+      <header className="absolute inset-x-0 top-0 z-10 flex items-center gap-2 bg-gradient-to-b from-base-100/80 to-transparent px-3 pb-8 pt-[calc(var(--safe-top)_+_0.75rem)]">
         <Link
           to="/collection"
           search={{ importFile: false }}
@@ -116,7 +121,7 @@ export function ScanPage() {
       {camera.state.status === "error" ? (
         <CameraErrorPanel message={camera.state.message} onRetry={start} />
       ) : (
-        <div className="absolute inset-x-0 bottom-0 mx-auto flex max-w-xl flex-col gap-2 bg-gradient-to-t from-black/70 to-transparent px-3 pb-[calc(var(--safe-bottom)_+_0.75rem)] pt-10">
+        <div className="absolute inset-x-0 bottom-0 mx-auto flex max-w-xl flex-col gap-2 bg-gradient-to-t from-base-100/80 to-transparent px-3 pb-[calc(var(--safe-bottom)_+_0.75rem)] pt-10">
           <div className="flex items-center justify-center gap-2">
             <StatusPill camera={camera.state} recognizer={recognizer.state} view={view} />
             {recognizer.state.status === "ready" && camera.state.status === "live" ? (

assets/react/src/pages/scan/scan-settings-sheet.tsx

@@ -12,7 +12,13 @@ import { Input } from "../../components/ui/input"
 import { Switch } from "../../components/ui/switch"
 import { SetCombobox } from "../collection/set-combobox"
 import type { RecognizerState } from "./recognition/use-recognizer"
-import { normalizeScanSettings, type ScanSettings } from "./scan-settings"
+import {
+  DEFAULT_SCAN_SETTINGS,
+  normalizeScanSettings,
+  PREVIEW_ZOOM_MAX,
+  PREVIEW_ZOOM_MIN,
+  type ScanSettings,
+} from "./scan-settings"
 import { playScanSound, unlockScanSounds } from "./scan-sounds"
 
 export function ScanSettingsSheet({
@@ -74,6 +80,57 @@ export function ScanSettingsSheet({
             />
           </section>
 
+          <section className="space-y-3 px-5 py-4">
+            <div>
+              <h3 className="text-sm font-bold">Camera preview</h3>
+              <p className="text-sm text-base-content/70">
+                Zoom and pan the preview to where cards sit, for example with the phone on a
+                scanning stand. Scanning still uses the whole camera image.
+              </p>
+            </div>
+            <RangeField
+              label="Zoom"
+              value={settings.previewZoom}
+              min={PREVIEW_ZOOM_MIN}
+              max={PREVIEW_ZOOM_MAX}
+              step={0.05}
+              format={(zoom) => `${zoom.toFixed(2)}×`}
+              onChange={(previewZoom) => update({ previewZoom })}
+            />
+            <RangeField
+              label="Pan across"
+              value={settings.previewPanX}
+              min={0}
+              max={1}
+              step={0.01}
+              format={formatPan}
+              onChange={(previewPanX) => update({ previewPanX })}
+            />
+            <RangeField
+              label="Pan down"
+              value={settings.previewPanY}
+              min={0}
+              max={1}
+              step={0.01}
+              format={formatPan}
+              onChange={(previewPanY) => update({ previewPanY })}
+            />
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() =>
+                update({
+                  previewZoom: DEFAULT_SCAN_SETTINGS.previewZoom,
+                  previewPanX: DEFAULT_SCAN_SETTINGS.previewPanX,
+                  previewPanY: DEFAULT_SCAN_SETTINGS.previewPanY,
+                })
+              }
+            >
+              Reset preview
+            </Button>
+          </section>
+
           <section className="space-y-3 px-5 py-4">
             <ToggleRow
               label="Sounds"
@@ -116,6 +173,52 @@ export function ScanSettingsSheet({
   )
 }
 
+/** Pan as an offset from the middle of the camera image: -50% to +50%. */
+function formatPan(pan: number) {
+  const offset = Math.round((pan - 0.5) * 100)
+  return offset > 0 ? `+${offset}%` : `${offset}%`
+}
+
+function RangeField({
+  label,
+  value,
+  min,
+  max,
+  step,
+  format,
+  onChange,
+}: {
+  label: string
+  value: number
+  min: number
+  max: number
+  step: number
+  format: (value: number) => string
+  onChange: (value: number) => void
+}) {
+  const id = useId()
+  return (
+    <div className="flex items-center gap-3">
+      <label htmlFor={id} className="w-24 shrink-0 text-sm font-bold">
+        {label}
+      </label>
+      <input
+        id={id}
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        onChange={(event) => onChange(Number.parseFloat(event.target.value))}
+        className="range range-primary range-sm flex-1"
+      />
+      <span className="w-14 shrink-0 text-right font-mono text-xs tabular-nums text-base-content/70">
+        {format(value)}
+      </span>
+    </div>
+  )
+}
+
 function testSound(sound: "ding" | "big-ding") {
   unlockScanSounds()
   playScanSound(sound)

assets/react/src/pages/scan/scan-settings.ts

@@ -12,8 +12,16 @@ export interface ScanSettings {
   showTotal: boolean
   /** Upload each logged scan's camera frame to this server for training recognition. */
   collectTraining: boolean
+  /** Camera preview zoom beyond filling the screen, for phones on a scanning stand. */
+  previewZoom: number
+  /** The point of the camera image (0–1) shown at the middle of the preview. */
+  previewPanX: number
+  previewPanY: number
 }
 
+export const PREVIEW_ZOOM_MIN = 1
+export const PREVIEW_ZOOM_MAX = 2.5
+
 export const DEFAULT_SCAN_SETTINGS: ScanSettings = {
   lockedSets: [],
   ignorePromos: true,
@@ -23,6 +31,9 @@ export const DEFAULT_SCAN_SETTINGS: ScanSettings = {
   bigDingThresholdCents: 1000,
   showTotal: true,
   collectTraining: false,
+  previewZoom: 1,
+  previewPanX: 0.5,
+  previewPanY: 0.5,
 }
 
 /** Stored settings from an older version or a hand-edited value fall back field by field. */
@@ -38,6 +49,12 @@ export function normalizeScanSettings(value: unknown): ScanSettings {
       ? Math.round(number)
       : DEFAULT_SCAN_SETTINGS[key]
   }
+  const within = (key: "previewZoom" | "previewPanX" | "previewPanY", min: number, max: number) => {
+    const number = stored[key]
+    return typeof number === "number" && Number.isFinite(number)
+      ? Math.min(Math.max(number, min), max)
+      : DEFAULT_SCAN_SETTINGS[key]
+  }
   return {
     lockedSets: Array.isArray(stored.lockedSets)
       ? [
@@ -55,6 +72,9 @@ export function normalizeScanSettings(value: unknown): ScanSettings {
     bigDingThresholdCents: cents("bigDingThresholdCents"),
     showTotal: bool("showTotal"),
     collectTraining: bool("collectTraining"),
+    previewZoom: within("previewZoom", PREVIEW_ZOOM_MIN, PREVIEW_ZOOM_MAX),
+    previewPanX: within("previewPanX", 0, 1),
+    previewPanY: within("previewPanY", 0, 1),
   }
 }