jessitron/mtg-deck-shuffler — documented rules

They belong outside the port (src/ proper or table-sync/).

No ShapeUtil, no client-side selection/drag mechanics touched — this split is pure server-side event routing and mint-position logic, the same "identity contract every hook in MtgCardShapeUtil depends on, not this owner's mechanics territory per se" category this file was already in.

wire/port shapes (SpineJoinRequest, SpineJoinResult, SpinePort) → stay in the port

env reading (shufflerPublicUrl, cardBackImageUrl, defaultPlaymatImageUrl, playmatImageUrlFromPath) → these are Shuffler-side facts about our own public URLs, not Spine facts. They belong outside the port (src/ proper or table-sync/).

the Shuffler mints a short-GUID seatId at join and records all three on BOTH PersistedGamePrep and PersistedGameState (optional fields, no version bumps).

TableInfo, GameState, and the persisted game/prep all carry tableUrl alongside spineTableId/spineSeatNumber (optional, no version bump).

JoinTablePort (types.ts) speaks the Shuffler's domain: join(JoinTableRequest) answering a SeatAtTable.

The abstract SpineJoinAdapter owns the translation into the Spine's /join wire vocabulary (spineWire.ts), including the seat-decoration builders; HttpSpineJoinAdapter (real) and FakeSpineJoinAdapter (tests, and the in-memory seat-allocation policy — one table per name, seats 1-4, idempotence by the request's joinRequestId) subclass it and supply only submission.

Card images in src/port-card-images/ (CardImagesPort): ScryfallCardImagesGateway (batched, throttled, 429-retrying), FakeCardImagesGateway, and enrichDeckWithImages().

JoinTablePort.join(JoinTableRequest): SeatAtTable, and SpineEventsPort, which covers both directions of one capability — announceCardPlayed/announceCardReturned/announceCardDiscarded going out, and followTable(tableId, applyEvent, appliedThrough) coming in.

Constant PersistedDeck.version, Defined in src/port-persist-state/persisted-types.ts, Current 2, Stamped on PersistedDeck ( dehydrateDeck ), Validated (fails) at not validated on load (dehydrated form)

It holds seats, seenEventIds, spineTableId, spineSubscription and stackCardCount() — none of which are tldraw's business — plus a raw .room it never encapsulates, which every module mutates directly (entry.seenEventIds.add, playerArea.graveyardCount++, entry.seats.set).

The clearest tell is applyCardArrival(tableName, body: unknown) in src/server/cardArrival.ts: it accepts a raw envelope, runs Ajv, checks slugifyTableName(envelope.tableId) !== tableName, sniffs whether name === "card.played-face-down", and only then places a shape.

/game now paints the picked mat too — CLOSED (2026-08-09). GameState/ PersistedGameState snapshot sleeveColor/playmatImagePath off PersistedGamePrep at /start-game and /restart-game (GameState.newGame gained two trailing optional params; both call sites in app.ts pass prep.sleeveColor, prep.playmatImagePath).

LIBRARY_PILE_INSET (12) in src/shared/mtgZoneShape.ts is shared server/client — tableFurniture.ts uses it for the card-back image geometry, MtgZoneShapeUtil for the sleeve pile.

The sleeve treatment lives in two .tsx files — the card's ring in MtgCardShapeUtil.tsx (the sleeve object), the library pile in MtgZoneShapeUtil.tsx (the sleevePile block). Changing the sleeve look means both.

The Shuffler reaches exactly one other ship, through one directory: port-spine/. Since the 2026-09-06 layering refactor that directory holds two ports, one per capability — join/ (JoinTablePort) and events/ (SpineEventsPort, both directions) — each with an adapter (domain↔envelope translation, reconnect orchestration) over a gateway (the actual fetch).

apps/shuffler/src/port-tabletop/ holds envelope-shape helpers only (buildCardPlayedEvent, the CardPlayedEvent/EventEnvelope types) — don't add an HTTP client back into it on the theory the directory name implies one.

Filtering Shuffler→Spine failures on exception.type: as of 2026-09-06 it is SpineGatewayError for all of them — join, event send, and SSE connection drop — where it used to be Error (non-2xx) or TypeError (unreachable host, undici timeout). All three gateways wrap, preserving message verbatim and the original as cause; span names, attribute keys, and log strings are byte-identical.

Wired into TablePage.tsx alongside useCardArrivalSpans/usePhysicsAnnouncements, same inSpan() idiom.

Wired into TablePage.tsx alongside useCardArrivalSpans/ usePhysicsAnnouncements, using the same inSpan("name", () => {}, {attrs}) idiom as useCardArrivalSpans.ts.

Shuffler side. SpineJoinResult (apps/shuffler/src/port-spine/join/spineWire.ts) and SpineJoinOutcome (apps/shuffler/src/table-sync/sendToSpine.ts) carry seatId through;

GameState.recordSpineJoin (apps/shuffler/src/GameState.ts) adopts outcome.seatId as this.seatId when present (the field is no longer readonly) — deliberately with no telemetry call inside GameState itself, per the rule that stamping stays in the HTTP/command layer, never the domain model.

Returns read-only array of GameCard & { location: LibraryLocation }

MtgZoneShapeUtil.component() calls useIsZoneArmed(this.editor, shape.id) unconditionally at the top, before any conditional branching, purely to read derived state for rendering.

ZoneHit widened from {id, zone} to {id, zone, seatId} — topmostZoneAt now reads the winning candidate's props.seatId too, since the new check needs it.

apps/tabletop/src/shared/mtgLifeCounterShape.ts (MtgLifeCounterShapeProps = {w, h, value}, the standard TLGlobalShapePropsMap augmentation) and apps/tabletop/src/client/shapes/MtgLifeCounterShapeUtil.tsx (BaseBoxShapeUtil, no interaction hooks — same as mtg-zone).

A fifth custom shape type, mtg-title (apps/tabletop/src/shared/mtgTitleShape.ts, props {w, h, text}; apps/tabletop/src/client/shapes/MtgTitleShapeUtil.tsx, BaseBoxShapeUtil<MtgTitleShape>), replaces the locked stock text seat-name label in tableFurniture.ts's ensurePlayerArea.

A third custom shape type, mtg-counter (apps/tabletop/src/shared/mtgCounterShape.ts, props {w, h, text}; apps/tabletop/src/client/shapes/MtgCounterShapeUtil.tsx, BaseBoxShapeUtil<MtgCounterShape>): an unlocked, draggable disc with free editable text, blank by default.

apps/tabletop/src/client/shapes/MtgCounterTool.ts, a StateNode with id "mtg-counter": click-to-place one counter, then back to the select tool.

Three changes, only the second and third of which are this owner's territory (the first — owner/isCommander becoming validated MtgCardShapeProps fields — is a fact the shape carries, not a mechanic; it grants no capability and adds no hook):

The mtgCardShape() builder (apps/tabletop/src/server/tableFurniture.ts, next to the existing zoneShape() helper): both mint seams now call this instead of writing their own store.put({...} as any) literal.

The fix is one function, apps/tabletop/src/client/clearStaleSelectionOnPointerDown.ts, registered once at Tldraw mount time (TablePage.tsx's onTldrawMount, renamed from aimCameraAtTheTable since it now does two things at mount, not one):

apps/tabletop/src/client/closeContextMenuBeforeOutsideClick.ts (new) exports closeContextMenuBeforeOutsideClick(): () => void, registered from onTldrawMount in TablePage.tsx alongside clearStaleSelectionOnPointerDown(editor):

Furniture is now mtg-zone, a genuine custom shape type (ticket 13, landed 2026-08-08; apps/tabletop/src/shared/mtgZoneShape.ts + apps/tabletop/src/client/shapes/ MtgZoneShapeUtil.tsx) — no longer stock, locked geo/image shapes stamped with a bare meta.zone string.

Zone heights changed 2026-08-09 (zone-label-band, 0d61890) without touching detection. Every card-holding zone now reserves ZONE_LABEL_BAND (40, exported from shared/mtgZoneShape.ts) of label headroom: library/command/exile are 278, graveyard 356.

One centralized listener, apps/tabletop/src/client/clearStaleSelectionOnPointerDown.ts (registered at Tldraw mount, TablePage.tsx's onTldrawMount), now clears a stale selection on every pointer_down whenever the hit shape isn't already selected — closing this watch point for every shape type, present and future, without a per-type hook.

ZoneHit grew a field to make this possible: topmostZoneAt's return type is now {id, zone, seatId}, not {id, zone} — seatId comes straight off the winning mtg-zone candidate's props.seatId and is threaded through to both callers (zoneAt()'s drag-settle check ignores the new field; armedZoneIdSignal's live-drag check is what actually reads it).

name, cardDefinitionId (a Scryfall printing id for scryfall cards, a UUIDv5 for custom cards; renamed from scryfallId in 0a6c52dd), multiverseid?, oracleCardName, colorIdentity, set.

ArchidektDeckToDeckAdapter.convertCustomCard reads the deck API's customCards array (types in archidektTypes.ts, ArchidektCustomCard).

CardDefinition carries two optional fields for this: imageUris?: CardImageUris (front/only face) and backImageUris?: CardImageUris (present only when twoFaced).

Image URLs are stored on the card (imageUris/backImageUris), fetched from Scryfall at ingestion via src/port-card-images/ (ScryfallCardImagesGateway → POST /cards/collection). getCardImageUrl(card, format, face) prefers the stored URL; constructCardImageUrl(scryfallId, format, face) is the fallback.

GameState.flipCard() mutates currentFace on the GameCard

CardDefinition changes: CardDefinition is intentionally minimal — identity fields, twoFaced, cardTypes, plus the optional imageUris/backImageUris (image URLs) and cardSource (absent = scryfall; read via cardSourceOf, never card.cardSource directly).