Preview all OpenCull features in one runnable branch

AGENTS.md

@@ -0,0 +1,32 @@
+# Working on OpenCull
+
+OpenCull is an offline photo-culling desktop application: React/TypeScript in `src/`, Rust/Tauri in `src-tauri/src/`. Read `README.md` and `docs/HOW-IT-WORKS.md` before changing behavior.
+
+## Branches and review
+
+- Implement one feature per short-lived `feature/<description>` branch. Use `fix/`, `docs/`, or `chore/` for other work. Never implement directly on `main`.
+- Independent features start from current `upstream/main` so the original maintainer can select them independently. Default PR target is `wispdevon/OpenCull:main`; submit upstream only when requested.
+- Fetch before choosing a base. Keep upstream synchronization in a separate PR. Do not bundle other feature commits into a standalone feature branch.
+- Combine features only on a separate `integration/` branch. Document integration-only fixes there, including conflict resolutions.
+- Inspect Git status first. Preserve unrelated edits and use separate worktrees when another branch is dirty or work runs concurrently. Never reset or stash someone else's work.
+- Keep commits and PRs focused; separate unrelated refactoring, formatting, dependency changes, and lockfile changes. Review staged diffs before committing.
+- Do not force-push shared branches. Resolve conflicts deliberately and rerun affected checks. Merge only when requested; remove merged feature branches after completion.
+
+## Verification
+
+- `npm ci` installs the locked dependencies. Use Node 22.12+ (CI uses Node 22).
+- `npm run test:web` runs frontend tests; `npm run test:rust` runs Rust library tests; `npm test` runs both.
+- `npm run build` checks TypeScript and builds the frontend. There is no lint script: do not claim one passed.
+- For desktop changes, also run `npm run tauri build -- --debug --no-bundle` and relevant runtime checks. Linux requires GTK/WebKitGTK and the Tauri prerequisites; see the README and CI.
+- Add focused regression tests for behavior, using existing Vitest and inline Rust test conventions. Do not weaken checks to make a branch pass.
+- Documentation-only work needs diff/link review, not an application rebuild.
+- PR descriptions explain the problem, resulting behavior, validation, platform limitations, and any prerequisites. Report blocked checks honestly.
+
+## Product boundaries
+
+- Keep photos private: processing stays local; no remote font or media requests.
+- Preserve original files. Card review, rejecting, and copying must never delete sources. Source deletion must be a distinct explicitly confirmed action.
+- Preserve sidecar compatibility, RAW/JPEG associations, keyboard navigation, and existing normal-folder behavior.
+- Settings belong behind the shared preferences interface. Retain existing defaults in upstream-facing features; personal defaults belong in local configuration.
+- Support Linux without introducing macOS/Windows regressions. Test on available platforms and state what was not tested.
+- Keep browser demo and native Tauri paths working. Use semantic theme tokens, accessible labels, and the existing UI component system.

DESIGN.md

@@ -0,0 +1,29 @@
+# OpenCull interface design guidelines
+
+These rules apply across Home, ingest, culling, settings, menus and dialogs. Wisp is the reference theme for readable interface contrast; other presets retain their visual character.
+
+## Readability and surfaces
+
+Use semantic tokens for background, panel, row, input, selected state, text and focus. Avoid a single grey for every level. Wisp separates an ink workspace (#111827), navy panels (#162033), raised rows (#1d293d), and controls (#2b3b55). Borders (#71839f) identify controls and setting boundaries. Primary text is #f3f6ff; secondary copy is #bac8df. Violet (#b7a6ff) marks primary actions and active controls. Light mode uses paper surfaces with dark ink and a deeper violet.
+
+Normal text must reach 4.5:1 against its actual background; large text, icons and necessary control boundaries must reach 3:1. Test computed colours in every colour mode, including hover and selected states. Do not lower descriptive copy opacity until it becomes difficult to read. Colour never carries state alone: use position, border, checkmark, text or icon as well.
+
+## Hierarchy and density
+
+Keep identity and supporting text above a horizontal action row. Use an 8px spacing rhythm: 8 within groups, 16 between controls or rows, 24 between sections, 32 before image collections. Setting rows have their own surface, 1px visible border, 8px radius and 16px padding; title and description belong together, control aligned at the start. Do not put borders around every text fragment.
+
+Titles use a clear weight and size hierarchy. Home headings can scale from 36–56px with bounded container sizing. Section headings use 22–32px. Setting labels use 14px semibold; explanatory text uses 13px with 1.6 line height. Retain the user's font preference and native interface scale. Avoid fixed heights on text blocks; allow wrapping and vertical scrolling.
+
+Controls need a 40px hit area where practical, with a visible keyboard focus outline separated from their edge. Selected tabs need both a border and stronger text; checked switches need a contrasting thumb position and track. Disabled controls retain labels and never look active. Menus, dialogs and popovers use opaque readable surfaces. Dialog content stays within the viewport and scrolls on smaller windows.
+
+## Photograph-first workspace
+
+Photo pixels, marks and rating colours are never recoloured by the theme. Keep the loupe surround neutral; 18% grey is #767676. Native-aspect strips use displayed rotation and crop proportions. Keep selection rings, rank labels and resize edges visible over mixed photographs. Theme accents belong on interface controls, not as a tint over previews.
+
+Recent folder contact sheets stay visible. Compact presets may reduce card dimensions without turning images into text-only entries. Bulk actions appear after the first selection. Removing recent history must clearly distinguish itself from deleting source photos. Errors use readable text, not just red borders. Loading retains useful previews where possible.
+
+## Verification
+
+Check Home, ingest, culling and all Settings tabs in dark, light and 18% grey, at small and large windows and at 100%, 150% and 200% native interface scale. Verify keyboard focus, scrolling, switch/tab state contrast and forced colours. Use screenshots plus measured contrast; do not infer accessibility from palette names.
+
+Wisp is supplied by feature/wisp-theme and depends on feature/rapidraw-theme's preset infrastructure. It changes no personal default automatically and loads no remote fonts or assets.

README.md

@@ -33,6 +33,70 @@
   </p>
 </div>
 
+## Run this fork with all features
+
+The `integration/linux-features` branch combines every feature in this fork.
+No manual merging or cherry-picking is needed. Individual feature branches
+remain available for selective upstream review; fork `main` contains general
+tooling fixes rather than the combined application.
+
+Install [Rust stable](https://rustup.rs) and the
+[native Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) first:
+
+- **macOS:** install Xcode Command Line Tools (`xcode-select --install`), then
+  `brew install jpeg-turbo pkgconf`. Tauri automatically uses the macOS
+  `turbo-system` configuration.
+- **Linux:** install GTK/WebKitGTK prerequisites plus CMake and NASM (NASM is
+  needed on Intel/AMD). Tauri uses the Linux `turbo` configuration.
+- **Windows:** install the Visual Studio C++ and WebView2 prerequisites plus
+  CMake and NASM. Tauri uses the Windows `turbo` configuration.
+
+Then, using nvm (or your platform's Node version manager):
+
+```sh
+git clone --branch integration/linux-features --single-branch https://github.com/wispdevon/OpenCull.git
+cd OpenCull
+nvm install
+nvm use
+npm install --global npm@11.21.1
+npm ci
+npm run dev:desktop
+```
+
+Without nvm, install Node 22.23.3 and npm 11.21.1 using your preferred version
+manager, or run the last two commands through the pinned runtime:
+
+```sh
+npx --yes --package=node@22.23.3 --package=npm@11.21.1 --call 'npm ci && npm run dev:desktop'
+```
+
+The desktop development command starts the frontend and native backend
+together, with live frontend reloads and incremental Rust recompilation.
+It does not create a production bundle or installers. The initial native
+compile can take several minutes. On affected Linux/Wayland systems, use
+`WEBKIT_DISABLE_DMABUF_RENDERER=1 npm run dev:desktop`.
+
+All features are included: cull-before-import sessions, multiple card sources,
+specific card subfolders, configurable panels, video inclusion/playback,
+appearance modes, offline fonts, the optional RapidRAW inspired design,
+larger UI headings, XDG configuration, remembered/default view modes, Wisp contrast,
+saved interface scaling, recent session deletion, resizable stack strips,
+experimental native-aspect strips and eased zoom, and optional NVIDIA rendering profiles.
+Optional preferences are selectable in Settings; the RapidRAW design is under
+**Culling → Design theme**, and view/panel controls are under **Layout**.
+Linux settings are created in `$XDG_CONFIG_HOME/opencull/config.json`, normally
+`~/.config/opencull/config.json`. No personal configuration file is required.
+macOS and Windows use Tauri's native application-config directory instead.
+The Linux video streaming workaround is compiled only on Linux; macOS keeps
+native asset-protocol playback. `dev:desktop` sets no Linux environment flags.
+
+For a Mac tester, use the [macOS trial guide](docs/TRY-ON-MACOS.md).
+NVIDIA rendering profiles are Linux-only; macOS uses its native webview automatically.
+
+Run `npm run check` for automated checks. See the
+[feature and validation map](docs/features/VALIDATION.md) for individual PRs
+and platform limitations.
+
 <!-- TABLE OF CONTENTS -->
 <details>
   <summary>Table of Contents</summary>
@@ -155,7 +219,7 @@ also need the system packages on
 
 1. Clone the repo
    ```sh
-   git clone https://github.com/NatePhotos/OpenCull.git
+   git clone --branch integration/linux-features --single-branch https://github.com/wispdevon/OpenCull.git
    cd OpenCull
    ```
 2. Install the packages

docs/TRY-ON-MACOS.md

@@ -0,0 +1,39 @@
+# Try every OpenCull feature on macOS
+
+Share this link: https://github.com/wispdevon/OpenCull/tree/integration/linux-features
+
+The integration branch already combines the feature branches. Do not merge branches by hand or use fork main for the combined preview. Experimental features are available in Settings and remain opt-in. The discarded mountain welcome-page demo is excluded.
+
+## Prerequisites
+
+Install Xcode Command Line Tools (`xcode-select --install`), Homebrew, Rust stable from https://rustup.rs, and Node 22.23.3 (for example with nvm). Then:
+
+```sh
+brew install jpeg-turbo pkgconf
+git clone --branch integration/linux-features --single-branch https://github.com/wispdevon/OpenCull.git
+cd OpenCull
+nvm install
+nvm use
+npm install --global npm@11.21.1
+npm ci
+npm run dev:desktop
+```
+
+If Node 22.23.3 and npm 11.21.1 are already installed, omit the nvm and global npm steps. The first Rust compile can take several minutes. Keep the terminal open. This starts the Vite frontend and native Tauri backend together; it does not create an installer. A browser-only preview cannot ingest actual cards or exercise native image decoding.
+
+macOS automatically uses the Homebrew libjpeg-turbo configuration. Do not set Linux WebKit, DMA-BUF, CUDA or NVIDIA flags on a Mac. The NVIDIA profile commands intentionally apply only to Linux. Settings use the native macOS application-config directory; no personal Linux config is needed.
+
+## Things to try
+
+- Ingest from Card: navigate to a DCIM subfolder, add multiple cards to one review session, cull before copying, and resume through Recent Sessions.
+- Settings → Culling: choose Wisp, OpenCull or RapidRAW inspired design; choose colour mode and font. Wisp separates setting rows and active controls with stronger contrast.
+- Settings → Layout: interface scale (80–200%), default/remembered view, stack filmstrip placement. Drag each strip's top edge to resize; F hides both stack strips. Resize edges support arrow keys as well.
+- Settings → Culling → Experimental Features: native-aspect strips, including the stack overview; decoded JPEG dimensions allow early sizing before complete metadata.
+- Settings → Zoom → Experimental Features: eased click zoom. This affects motion curves, not the speed of CPU image decoding.
+- Select one recent item to reveal bulk controls. Deleting a session removes saved review history, never source photos.
+
+Use a copy of a small shoot for an initial trial. `npm run check` runs frontend tests/build and Rust tests. Update with `git pull --ff-only`, `npm ci`, then `npm run dev:desktop`.
+
+## Verification boundaries
+
+The earlier combined snapshot passed the macOS Apple-silicon CI tests and build. The final branch's CI additionally starts `dev:desktop`, checks Vite and the native process, and observes them through startup. This is a startup smoke test, not a visual, card-reader or performance test on the recipient's Mac. Intel macOS is not covered by the Apple-silicon runner. See the latest integration Build workflow for the exact commit and result.

docs/features/EXPERIMENTAL_FILMSTRIP.md

@@ -0,0 +1 @@
+Settings → Culling → Experimental Features → Native-aspect filmstrip. Disabled by default. Uses displayed rotation/crop proportions at a common height, preserving the existing virtualized horizontal strip. Unknown dimensions temporarily use 3:2 until metadata arrives. No masonry CSS dependency or photo changes.

docs/features/EXPERIMENTAL_ZOOM.md

@@ -0,0 +1 @@
+Settings → Zoom → Experimental Features → Smooth click zoom. Disabled by default. Click/keyboard/face/marquee zoom uses a fast-start, slow-stop cubic curve with 280–340 ms durations. Reduced motion disables these transitions. Wheel zoom and dragging remain immediate. Existing sharp rerasterization after motion is retained. This is an experimental motion option, not a promise of native macOS performance.

docs/features/INTERFACE_SCALE.md

@@ -0,0 +1,7 @@
+# Interface scale
+
+Saved desktop preference under Settings → Culling in the standalone feature, and Layout in the combined app. Uses Tauri Webview.setZoom so pixels, rems, menus, controls, and pointer coordinate systems scale together. Supports 80–200%, default 100%, plus Reset. Uses shared preferences. Browser demos retain browser zoom controls rather than simulating page zoom with CSS transforms.
+
+macOS requires 11+ (Tauri API requirement). Linux and Windows use their native webview zoom implementation. A narrowly scoped core:webview:allow-set-webview-zoom permission is added. Errors remain visible and unsuccessful changes are not persisted.
+
+Settings stay within the viewport, tabs wrap, settings content scrolls on short windows, and the culling toolbar wraps rather than clipping controls as usable CSS space decreases.

docs/features/NVIDIA_GRAPHICS.md

@@ -0,0 +1,9 @@
+# NVIDIA graphics rendering
+
+Independent feature branch: feature/nvidia-gpu-acceleration. Uses the native graphics stack for webview compositing, photo transformations, WebGL and supported 2D canvas rendering. It does not implement CUDA image decoding or change ONNX inference. WebKit still decides which operations are accelerated.
+
+Linux: `npm run dev:desktop:nvidia` requests hardware compositing, enables WebGL and supported accelerated canvas, and removes inherited software/compositing-disable overrides before GTK initializes. It uses `WEBKIT_DMABUF_RENDERER_FORCE_SHM=1` and `WEBKIT_DMABUF_RENDERER_DISABLE_GBM=1` rather than disabling the DMA-BUF renderer and prefers XWayland when an X display is available and no backend was explicitly requested, because direct DMA-BUF/GBM presentation failed with this test machine’s proprietary driver. This leaves accelerated compositing enabled while changing buffer transport. A native CSS-only animation probe on this RTX 3060 Ti allocated 53 MiB in the WebKit graphics process; no WebGL probe was needed to produce that allocation. `npm run dev:desktop:compatibility` retains the DMA-BUF workaround; `npm run dev:desktop:software` explicitly requests a software path for comparison. The ordinary desktop command remains automatic and changes no environment flags. Packaged binaries accept `--graphics=nvidia`, `--graphics=compatibility`, `--graphics=software`, or `OPENCULL_GRAPHICS`. Linux-only code and dependencies leave macOS/Windows native rendering unchanged.
+
+Settings → Storage → Graphics acceleration provides a renderer probe. An NVIDIA WebGL renderer is evidence for that context, not proof that every rendering operation is GPU accelerated. Verify native WebKit process GPU device use and frame timings as well. These profiles do not install drivers or edit system configuration. On hybrid systems, choose the discrete GPU through the system's normal offload launcher.
+
+Reference: https://docs.webkit.org/Ports/WebKitGTK%20and%20WPE%20WebKit/Graphics.html and the WebKitGTK HardwareAccelerationPolicy API. The NVIDIA profile requests Always; it does not claim a specific performance improvement. Compatibility remains available for driver/compositor issues.

docs/features/README.md

@@ -0,0 +1,15 @@
+# Independent feature initiative
+
+Approved feature branches (each starts at upstream main):
+
+- `feature/cull-before-ingest`: reuse culling before copying; local source-safe marks; choose files at finish; copy or import in place.
+- `feature/multi-card-session`: combine sources; conservatively pair RAW/JPEG across cards; one session.
+- `feature/configurable-ui`: settings for panel visibility and sizes, preserving defaults.
+- `feature/appearance-modes`: dark, light, 18% grey; preserve default dark.
+- `feature/font-selection`: system, offline Space Grotesk, custom local family; preserve default system.
+- `feature/video-culling`: ignore toggle, supported playback, import selection; default ignore.
+- `feature/xdg-config`: atomic native settings, Linux XDG path, migration from webview preferences.
+
+No feature requires another. Combined behavior and overlap resolutions belong on `integration/linux-features`. No automatic merges or upstream submissions.
+
+Personal configuration: Space Grotesk, 18% grey, existing panel visibility/sizes, videos ignored. Card workflow reviews first, then chooses Copy (initially all non-rejects) or Import in place (only selected members). No card writes during review or implicit deletion.

docs/features/RECENT_SESSIONS.md

@@ -0,0 +1 @@
+Depends on feature/cull-before-ingest. Card sessions are retained individually and shown under Recent Sessions. Legacy latest.json remains readable. Resume Latest Session compares card review save time with the last successfully opened normal folder. Missing cards produce a reconnect message. Source photos are never modified by session history.

docs/features/STACK_FILMSTRIP.md

@@ -0,0 +1 @@
+Settings → Culling → Stack filmstrip placement. Classic is the default. Keep normal filmstrip placement puts active stack frames in the shared full-width bottom filmstrip; the scene overview remains above. The existing show-filmstrip preference applies.