# Record Remix Theme Pack Contract v2

Version: 2.0  
Module slug: `record-remix`

A Record Remix theme pack is a static ZIP containing the booth skin, its preview, and a library of premade album-cover renderings. Theme Studio installs the ZIP and the front-booth selector can preview any installed skin immediately.

## Required ZIP layout

```text
theme.json
theme.css
preview.jpg
album-covers/
  contracts.jpg
  water.jpg
  shared-signals.jpg
```

The files may be at the ZIP root or inside one top-level folder. Do not add an extra nesting layer below that.

## `theme.json`

```json
{
  "schema": "record-remix-theme/v2",
  "id": "dj-swamp-01",
  "name": "DJ Swamp",
  "version": "1.0.0",
  "description": "A short description of the booth skin.",
  "designer": {
    "name": "Designer name"
  },
  "css": "theme.css",
  "preview": "preview.jpg",
  "palette": {
    "ink": "#171714",
    "paper": "#efe2c3",
    "signal": "#c94f39",
    "gold": "#d3ad4c",
    "screen": "#9cc9ad"
  },
  "mood": ["turntablism", "woodgrain", "vintage"],
  "covers": [
    {
      "id": "water-rights",
      "file": "album-covers/water-rights.jpg",
      "label": "Water Rights",
      "keywords": ["water", "river", "rights", "well", "utility", "land"]
    },
    {
      "id": "public-money",
      "file": "album-covers/public-money.jpg",
      "label": "Public Money",
      "keywords": ["budget", "contract", "invoice", "grant", "tax", "purchase"]
    },
    {
      "id": "wildcard",
      "file": "album-covers/wildcard.jpg",
      "label": "Shared Signals",
      "keywords": ["records", "connection", "transparency", "regional"],
      "default": true
    }
  ]
}
```

Theme IDs use lowercase letters, numbers, and hyphens. An updated ZIP with the same custom ID replaces that custom theme after Theme Studio copies the previous version into `storage/theme-backups/`. Stock IDs cannot be overwritten.

For compatibility with early packs, Record Remix also reads `albumCovers` and `album_covers`, but new packs should use `covers`.

## Album-cover renderings

Album art is selected from the files in the active theme pack. The module does not call an external image service at recording time.

Record Remix calculates hot topics separately for Side A and Side B using title/body frequency, views, downloads, featured status, and recency. It then combines those agency topics with the subjects found in the cross-agency connection tracks. Each cover receives a score based on overlap with its `keywords`, and the highest-ranked renderings appear first in the cassette recorder.

Recommended cover library:

- 6 to 12 square renderings per theme.
- JPG is the most portable format for the built-in PDF recorder.
- PNG and WebP work in the web album. They are converted for PDF when the server has GD; otherwise the PDF safely falls back to the stock JPG cover.
- 1200 x 1200 pixels is a strong default. The validator accepts 160 to 6000 pixels per side.
- Include a broad `default` cover for mixes that do not strongly match a specialized topic.
- Write specific, reusable keywords. Good: `contract`, `invoice`, `water`, `zoning`, `camera`, `meeting`. Weak: `cool`, `interesting`.

The PDF preserves a copy of the selected cover beside the saved remix, so later theme updates or deletions do not change an already recorded release.

## Stable CSS slots

`theme.css` should override variables on `.rr-app` rather than replacing the application layout:

```css
.rr-app {
  --rr-booth-bg: #201d19;
  --rr-booth-bg-image: repeating-linear-gradient(90deg,#4b3426 0 54px,#543b2a 54px 108px);
  --rr-console: #c0aa78;
  --rr-console-dark: #2b2923;
  --rr-console-edge: #171714;
  --rr-label: #eadfc5;
  --rr-signal: #c34f3a;
  --rr-signal-2: #d0ad55;
  --rr-screen: #9fc9af;
  --rr-screen-ink: #10251c;
  --rr-ink: #201d19;
  --rr-muted: #756b59;
  --rr-card: #f0e7d2;
  --rr-paper: #f6efdf;
  --rr-focus: #ffcc58;
  --rr-radius: 14px;
  --rr-shadow: 0 18px 50px rgba(0,0,0,.28);
  --rr-font-display: ui-monospace, monospace;
  --rr-font-body: ui-sans-serif, system-ui, sans-serif;
}
```

Stable component hooks include:

- `.rr-booth-shell`
- `.rr-console-panel`
- `.rr-hardware-panel`
- `.rr-deck-a` and `.rr-deck-b`
- `.rr-platter`
- `.rr-screen`
- `.rr-signal-button`
- `.rr-cassette-hardware`
- `.rr-record-button`
- `.rr-connection-card`

Keep layout overrides modest so the module remains usable on phone, tablet, and desktop.

## Security rules

Theme packs are static design packages, not plugins. Theme Studio rejects:

- PHP, JavaScript, HTML, shell scripts, executables, archives inside the archive, and unknown extensions.
- Absolute paths, `..` traversal, control characters, duplicate paths, oversized files, and oversized expanded packages.
- CSS `@import`, remote/protocol-relative URLs, `javascript:`, HTML data URLs, `expression()`, `behavior`, and `-moz-binding`.
- Active SVG. A sanitized `DESIGN-MAP.svg` or SVG under `docs/` is accepted only as designer documentation; it cannot be the preview or an album cover.

Allowed file types are JSON, CSS, JPG/JPEG, PNG, WebP, TXT, Markdown, and the limited documentation SVG described above.

## DJ Swamp pack deployment checklist

1. Set the manifest ID to `dj-swamp-01` or another unique lowercase ID.
2. Put the complete console skin in `theme.css` using the stable variables/hooks.
3. Add `preview.jpg`.
4. Add the premade square album covers under `album-covers/`.
5. Add meaningful keywords for every cover and one broad default cover.
6. ZIP the contents so `theme.json` is at the root or inside one top-level folder.
7. Open Record Remix > Theme Studio, upload the ZIP, and optionally activate it.
8. Return to the booth. The skin appears in the Booth Skin selector immediately.

## What lives inside a recorded PDF

The album PDF contains the selected front cover, a back-cover synopsis and track list, mixer/analytics liner notes, every connection track with paired evidence and source links, and an embedded `record-remix.json` containing the full saved remix record. Original source documents remain linked to their authoritative archive locations instead of being duplicated into the PDF.

## Bundled DJ Swamp cover topics in v2.3.0

The fresh Record Remix build ships DJ Swamp — Wax Assassin with seven stock cover renderings: camera access, public money, water rights, contracts/invoices, data center signals, meeting minutes, and shared signals. Custom theme packs can use the same `covers` array with their own local JPG/PNG/WebP files and keywords.