# Collection, decks and play

Updated October 11, 2026.

First Shuffle has three workspaces. Your **Collection** records cards you own. **My decks** saves selected cards and quantities. **Play helper** opens one saved deck so you can read its cards during a game.

## What each record means

| Record | Contains | Changes when |
| --- | --- | --- |
| Collection | Confirmed printing metadata and owned quantities | You add cards, adjust ownership or remove cards |
| Saved deck | Independent printing snapshots, selected quantities, settings, name, timestamps and source collection revision | You save edits, rebuild and save, or explicitly apply an ownership reduction to affected decks |
| Game helper | Six Prize slots for the latest ongoing game associated with a deck | You mark a Prize taken, note its revealed printing, or start a new game |
| Favorites | Starred collection printing IDs and a favorite flag on saved decks | You star or unstar an item |

A deck copies only its selected printings, not the entire collection. Adding cards to the collection never adds them to an existing deck. Saved printing text remains a snapshot; checking current ownership does not silently replace that text with a newer catalog record.

The collection revision records the source at save time. Ownership changes can update selected quantities later, so the revision is provenance rather than a promise that the deck can never change. Each propagated removal records its reason, revision and quantity changes. Deck plans do not reserve physical cards: two plans can reference the same copies, but cannot both be assembled at once unless you own enough for both.

## Build, edit and play

1. Add and confirm your cards in Collection.
2. Choose **Next: build a deck** or **New deck**, set your goals, then **Build and save deck**. The app saves a new named selection and opens it.
3. Edit selected quantities or search your collection to add a copy. Collection quantities stay intact. Changes remain a draft until saved.
4. Changing build settings leaves the current selection intact. **Preview rebuild** generates a draft; **Save changes** replaces that deck, while **Save as new** creates another.
5. **Play with this deck** opens its saved selection. Unsaved changes must be saved or discarded first. The Play helper always uses a saved deck, rather than the whole collection or an unsaved draft.

Manual additions check owned copies, the 60-card bound, the four-copy name limit and the ACE SPEC limit. Incomplete or unsupported selections can remain drafts with warnings. The rule validator and readiness checks run again after edits; saving is not a guarantee of tournament legality. See [the deck-building algorithm](deck-builder.html).

## Removing owned cards

Reducing ownership opens a preview. Choose a reason and one of two policies:

| Policy | Result |
| --- | --- |
| Update affected decks | Cap that printing in each deck at the copies still owned; zero removes the printing. Other cards stay intact. |
| Keep deck lists | Preserve selected quantities and flag missing owned copies. Useful for reference lists. |

Example: you own four copies, one deck uses four and another uses two. Trading one leaves three owned. Updating affected decks changes the first deck to three and leaves the second at two. Removing all copies removes that printing from every affected deck under the update policy.

No replacement card is added automatically. An affected deck may become incomplete or lose an evolution step; its checks report that. Session-only **Undo removal** restores the collection, affected decks and stars. A subsequent collection or saved-deck edit ends that Undo window. Collection and deck updates are persisted together in one authoritative browser-storage write.

## Favorites

Star a card in Collection or a deck in My decks. **Favorites** provides card readers and deck Edit/Play actions in one place. **Favorites only** filters the collection display; it does not limit the builder’s source cards. Stars never select cards for a deck. Removing all owned copies removes that printing’s collection star. Updating a saved deck preserves its star.

## Prize cards belong to a game

Normally, after drawing the opening hand and placing starting Pokémon, each player sets aside six cards from the top of the shuffled deck face down. Their identities are unknown until taken. They are not six cards to choose in the deck builder. Follow the [official setup and Prize rules](https://www.pokemon.com/us/pokemon-tcg/rules).

Play helper keeps six slots for the latest game of each saved deck. Mark a slot **taken** when the physical Prize is taken; optionally note the revealed printing. Turning a slot face down again clears its note. Notes cannot assign more copies of a printing than the deck contains. Switching decks restores each deck’s own tracker. **New game / reset Prizes** clears those notes and leaves the deck list intact.

These are manual notes, not a shuffled deck simulation, hand tracker, opponent tracker or automatic win detector. Deleted decks lose their stored game notes; session-only deck Undo restores both. Past games are not archived.

## Pip’s math helper

Tap Pip to practice addition or subtraction. The default is 5 + 3. Inputs accept whole numbers from 0 to 999. Smaller problems count ones; larger amounts take exact groups of ten or one hundred, with the final remainder counted explicitly. Ten frames and numbered ten bundles show the quantities. **Next step** advances manually; **Count with Pip** animates, with pause and reset. Reduced-motion mode advances one step at a time.

Pokémon readers and the Play helper can open HP subtraction. Printed HP and the largest printed attack number are starting inputs: edit them for existing damage, card effects, Weakness and Resistance. The helper does not calculate those effects. Arithmetic can go below zero; the separate card-game note explains that remaining HP stops at zero. A sword marks printed damage and a heart marks printed HP; conditional +/× damage retains its modifier.

## Storage and privacy

The version-2 browser workspace contains collection records, saved decks, stars, the collection revision, sample status and game notes. Older collection and deck storage is read and migrated on the next successful write. Old records are removed only after that write succeeds. Theme, sidebar and reader-size preferences remain separate.

This is browser `localStorage`: a built-in key/value store scoped to this Site’s origin. **Export** and **Import** appear once in the Cards workspace toolbar. Export downloads the full workspace as JSON. Import opens the JSON option in Add cards, where you choose a file or paste text, validate it, review the result, then save. Existing backup files remain supported. The app serializes the version-2 workspace as JSON under a versioned workspace key; theme, sidebar and reader-size preferences use separate keys. Guest browser resets can clear it. Signed-in workspaces are stored in D1 and load across devices; an account-specific cache and revision metadata are kept separately in this browser. Storage failures keep edits in the current tab and show a reminder. A deck-list download is not a complete workspace export.

The app collects a unique nickname, internal account ID, password/recovery hashes and session records for independent sign-in. New accounts require a verified contact email for account verification, recovery, and security notices; no real name or phone number is requested. Existing accounts retain their IDs and data while adding an email in Account security. Their accounts.invalid placeholders are replaced only after verification. No product analytics or chat logs are added. Resend processes recipient addresses, account messages, and delivery metadata; account messages use plain text without app-added tracking pixels or tracked links. Email OTPs use secret-salted hashes and expire after ten minutes; remembered-device hashes expire after thirty days. Security-notice payloads are encrypted, retried at most three times on account requests, and expire after three days. Photos are processed locally and not persisted. Hosting sign-in and external card-data requests are separate services, as described in the app’s Privacy & access panel.

## In-store and editing

Cards is read-only. An empty Cards workspace shows **Add cards to start**, with a button opening Add cards; filters, totals and builder controls stay hidden until cards exist. Sample cards are available only from the Overview when the collection is empty, never inside an Add tab. Update cards exposes quantity changes, removal and **Edit JSON**, which loads current records in the Add cards JSON editor. None of those changes automatically replaces a saved deck selection.

Card JSON accepts an array of `{id, qty}` rows for locally known printings, an array of `{card, qty}` records with complete printing metadata, or an object with a `collection` array. **Add quantities** increments ownership. **Replace my cards** replaces the card list, retains saved deck snapshots, and flags missing copies. It removes stars for printings no longer owned. Supplied card metadata and original added dates survive reload; updates receive a current timestamp. Use qty 1–999; remove a row to remove a printing during replacement. Duplicates, unknown IDs without metadata, invalid quantities, malformed fields and invalid dates block saving. Changing JSON, its mode, or workspace data requires validation again. There are no network requests during typing or validation.

The workspace also stores `storeCandidates`: up to 50 exact printings with quantities and timestamps. These are considered purchases, not owned cards. They do not contribute to deck building or ownership counts. Bring selected into Cards transfers only the purchased quantity; unpurchased copies stay as candidates. Clear candidates affects neither owned cards nor decks. Backups include candidates, and old backups without this field restore with an empty candidate list.

Full workspace files are detected separately. The validation summary names the card and deck counts and explains that saving replaces cards, decks, favorites, Prize notes and in-store candidates. The explicit **Replace workspace** action persists and opens Cards. Loading a file alone changes nothing. Storage failure is reported as tab-only. A fresh-window/reload regression uses the supplied 88-card, 82-printing backup. Workspace preferences are included for reference in the export; import retains this browser’s display preferences.

### Spreadsheet CSV exports

The Cards toolbar, sidebar, and account menu **Export** action opens a shared export dialog. Choose **Owned cards**, **In-store candidates**, **Saved decks**, **Cards in saved decks**, **Snapshot history**, **Cards in snapshots**, **Prize notes**, or **Local card catalog**. It downloads every row in the selected current dataset, independently of the table's current page/filter. The catalog is the catalog currently loaded by the app, not every online printing. Saved deck exports use saved versions, not an unsaved deck draft.

Papa Parse handles quotes, commas, Unicode, and multiline text. Exports include headers and a UTF-8 BOM, neutralize spreadsheet formula prefixes including whitespace-prefixed formulas, and select explicit scalar columns. Empty datasets still download their headers. Flattened deck/snapshot rows retain their parent IDs and quantities. Candidates remain separate from owned cards. No account credentials or authentication records are included, and ordinary exports need no API request. A dataset is capped at 20,000 rows and 10 MB; a complete JSON backup remains available for larger or restorable data.

CSV is for spreadsheets, not a full workspace restore format. **Download JSON backup** remains in the dialog, and conflict recovery continues using the existing JSON export. Exports never alter ownership, decks, history, or game notes. Admin CSV exports use a separate authorized endpoint and preserve the admin list's search, sort, and account scope across pages.

## Collection history

History records an independent copy of the previous card list before a successful card change. Save snapshot captures the current list explicitly. History keeps up to eight snapshots within a 2 MB budget, trimming the oldest first. It shares the authoritative workspace write and appears in Export/Import; old files without history still work. Snapshots cover card metadata and owned quantities, not deck edits or game notes. Guest history stays device-local. Signed-in history is stored online; clearing browser storage does not remove already-saved snapshots.

Open editable copy loads a snapshot into the JSON editor. It does not modify current cards until validation and Replace cards. Existing saved deck selections remain snapshots and flag missing ownership. Replacing the cards captures the displaced list, so the restore itself has a recovery path. Server writes check the expected account revision and reject conflicts. Multiple named collections remain planned.

## Other games and trade decisions

The [Collections and Magic proposal](collections-plan.html) describes collection IDs, game types, timestamps and the per-game boundary. No Magic catalog or engine is enabled. The earlier D&D proposal remains on hold.

The [Trade comparison proposal](trade-plan.html) separates exact-card ownership and deck effects from market-price estimates. Live pricing calls and a trade-confirmation flow are not enabled.

History uses a React Chrono vertical timeline. Current cards are shown separately and cannot be deleted through History. Saved-by-you and Automatic snapshots show names, timestamps, revisions and counts. Save snapshot can use an optional name. Preview is read-only; Edit a copy opens the existing JSON validation workflow. Each snapshot has a Delete action; History actions can delete all saved snapshots. Both require confirmation. Cancellation and stale reviews write nothing. The session Undo action restores deleted history only if it has not changed again. Current ownership, saved decks and Prize notes are unaffected.

The online workspace write now treats the submitted bounded history list as authoritative under the existing optimistic revision and write-token guard. Omitted snapshots are removed from the account's version table, so confirmed deletions survive reload. A previous current collection is still captured before card changes, avoiding a duplicate when the client already supplied that same revision and content. No database migration is required.