wide-trace/open-higgsfield

Gallery

• Four scopes — Image, Video, Assets (every finished run) and Favorites — as an arrow-key-navigable tab rail.
• Masonry grid of real runs at their true aspect ratio, newest first, with a gradient placeholder while media loads.
• Per-tile actions: reuse, favorite, delete, select.
• Reuse restores model, settings and prompt, so the same run can be re-rendered, not just re-typed.
• Viewer. Full-size media with prompt (copy in one click), model, resolved settings, timestamp, download, favorite and Recreate.
• Selection mode. Click a tile's checkbox to enter; shift-click extends a range. Bulk download (sequential, with progress and a report of any files the CDN refused), bulk favorite/unfavorite, bulk delete. Esc exits.
• Undo. Deletion is reversible for 6 seconds via a bar with a draining hairline, in the strip the composer already reserves.
• Empty states that hand you a starter prompt instead of a blank grid.

State and errors

• History persists in IndexedDB in this browser (60 records). Favorites are a deliberate keep and never age out of the cap. Result URLs belong to the generation platform, so old history can outlive its CDN lifetime and show gaps.
• Failed, NSFW and canceled runs are recorded as failed tiles carrying the reason and a retry that restores the prompt and model.
• Your own platform key. Entered in a modal, stored by a server action in an httpOnly cookie. A missing key opens the modal — it never fails silently. The topbar lamp states whether a key is held and whether a run is in flight.

Architecture

Each generate is one object: { model, prompt, media, settings }.

• The UI builds that object and hands it to a server action. The action resolves it against the catalog and maps it to the generation API's own fields (image_urls, aspect_ratio, …).
• Server actions are the only caller. The browser never talks to the generation API. Submit is POST /{model}; status is GET /requests/{id}/status. Auth is Authorization: Key <api_key>.
• The catalog is the source of truth (src/generation/catalog/). A new entry appears in the picker, brings its own settings rail and media roles, and needs no studio changes.
• Five small Zustand stores — shared image/video prompt, shared image/video media, settings[modelId], and a tiny active store. No store per model.
• Uploads go client-direct to Vercel Blob through /api/blob, which issues scoped tokens. blob: URLs are preview-only.

Getting started

pnpm install
pnpm dev            # http://localhost:3000

Open the studio, press Add key, and paste your platform key as id:secret.

Environment

HF_API_BASE_URL=                      # generation API origin, server only
OPEN_HIGGSFIELD_READ_WRITE_TOKEN=     # Vercel Blob read-write token

Commands

Layout

src/
  app/          /  is the full-viewport studio and the only page
                /api/blob issues upload tokens
                base.css owns the document canvas
  generation/   generate requests, server actions, API mapping, catalog, stores
  openhiggsfield/
                the studio surface: composer, gallery, viewer, model picker,
                settings, asset picker, selection bar — and openhiggsfield.css

Design principles

Dark studio ground, a single lime accent #d1fe17, Inter throughout. The chrome stays neutral so the generated work is the only color on the surface.

1. The tool disappears into the task — expression never obscures state or affordance.
2. Accent is state, not decoration — selection, primary action, liveness only.
3. Data is data — settings, counts and durations read in tabular numerals. One typeface throughout; no monospace anywhere.
4. Motion conveys state — the generation lifecycle, the arrival of a run. Nothing loops decoratively.
5. Every control ships all its states — hover, focus, active, disabled, loading, error, empty.
6. The catalog is the source of truth — the studio renders what the model declares, never a parallel hardcoded list.

Built for people who work in long sessions, iterating on prompts, inputs and settings.