@dreamboard-games/sdk 0.5.0-alpha.3 → 0.5.0-alpha.30

package/README.md

@@ -13,7 +13,7 @@ pnpm add @dreamboard-games/sdk
 The package declarations and export map are the API authority. There are four entry points:
 
 - `@dreamboard-games/sdk`: framework-free instances, sources, features and canonical host protocol schemas.
-- `@dreamboard-games/sdk/react`: typed React provider, selector hook and subscription component.
+- `@dreamboard-games/sdk/react`: typed React provider, selectors, subscriptions, and card gesture and drop-area hooks.
 - `@dreamboard-games/sdk/reducer`: game authoring, manifest compilation, execution and trusted worker admission.
 - `@dreamboard-games/sdk/testing`: browser-safe local/scenario sources, replay, inspection and bounded exploration.
 
@@ -82,7 +82,7 @@ const ownCard = play.inputs.card({
     id: "own-card",
     errorCode: "NOT_YOUR_CARD",
     test: ({ q, playerId, targetId }) =>
-      q.zone.playerCards(playerId, "hand").includes(targetId),
+      q.zone("hand", playerId).includes(targetId),
   },
 });
 
@@ -95,11 +95,10 @@ export default play.define({
       inputs: { cardId: ownCard },
       reduce({ tx, input, q }) {
         // tx.state.phase.leadCardId and input.params.cardId are inferred.
-        tx.moveCardFromPlayerZoneToSharedZone({
-          playerId: input.playerId,
-          fromZoneId: "hand",
-          toZoneId: "trick",
-          cardId: input.params.cardId,
+        tx.moveComponentToZone({
+          componentId: input.params.cardId,
+          to: { zoneId: "trick" },
+          playedBy: input.playerId,
         });
         tx.patchPhaseState({ leadCardId: input.params.cardId });
         const next = q.player.nextInOrder(input.playerId);
@@ -107,7 +106,7 @@ export default play.define({
           tx.patchPublicState({ currentPlayerId: next });
           tx.setActivePlayers([next]);
         }
-        if (tx.q.zone.playerCards(input.playerId, "hand").length === 0) {
+        if (tx.q.zone("hand", input.playerId).length === 0) {
           return tx.transition("setup");
         }
       },
@@ -168,7 +167,7 @@ export default game.assemble({
   phases: { setup, play },
   view: game.view(({ state, playerId, q }) => ({
     me: playerId,
-    hand: q.zone.playerCards(playerId, "hand"),
+    hand: q.zone("hand", playerId),
     current: state.publicState.currentPlayerId,
   })),
 });
@@ -182,24 +181,119 @@ imports the assembled game, so there is no import cycle.
 New workspaces keep authored starter code in `app/game.ts` and `ui/App.tsx`.
 Import the manifest directly. `compileManifest(manifest)` provides inferred ID schemas,
 table schemas, fresh initial tables, and board metadata in memory. `createGame`
-also accepts the authored manifest directly. Bind a typed React hook with
-`createGameHook<Game>()({ features, coverage })` from `@dreamboard-games/sdk/react`,
+requires that compiled manifest when binding state schemas. Bind a typed React hook with
+`createGameHook<Game>()({ features })` from `@dreamboard-games/sdk/react`,
 and pass a source to its `GameProvider`. The hosted UI imports `Game` only as a type;
 `iframeSource()` supplies authoritative frames and handles commands.
 No authoring generation step or shared workspace files are needed.
 
+`createInitialTable({ playerIds })` takes the actual roster explicitly. Cards,
+piece, die and tile seeds can use `scope: "perPlayer"` to replicate for those
+seats, with initial ownership derived from the replication origin. Ownership
+changes do not change instance IDs. Use `perPlayerInstanceId` when constructing
+a reference from a known family, expanded base and seat; decoding validates
+syntax only, while table admission checks live membership. UI consumers should
+use the canonical IDs supplied by projected boards and eligible targets.
+Instance record factories likewise require `{ playerIds }`, for example
+`manifest.records.pieceIds(0, { playerIds })`. Player IDs are nonempty and unique;
+`__proto__` is reserved to preserve roster keys through record parsing.
+
+Zones declare either `scope` or `attachedTo` a board, generic board space, tile
+cell, piece type, or die type. Query and move through the same zone API with the concrete host ID;
+use `boardSpaceHostId(boardId, spaceId)` for a space attachment. Component-hosted
+access follows the host's current owner, independently of contained ownership
+and card face state. Initialization, movement and restore reject containment
+cycles. Containers, slots and their location variants are removed.
+
+`tileTypes` own immutable hex/square cells, annotations and rule fields;
+`tileSeeds` create game-owned instances with independent ownership and mutable
+properties. `q.tile(id)` addresses that inventory, including detached tiles.
+Canonical `OnBoard` locations own placement. Hex/square topology is derived from
+those locations and immutable definitions; runtime boards store only `baseId`
+and explicit session relations. Cell identity follows the tile instance and
+local cell, while world edges and vertices belong to the exact board instance.
+The flat seat `boards` projection is the sole client topology source.
+
+Private tile destinations remain rejected in this layer. Generic component
+moves cannot remove a placed tile or place tiles on component spaces, edges or
+vertices. Tile-cell zone hosts must remain empty while their tile is unplaced.
+The existing UI zone facade still presents cards.
+
+Manifest card counts and explicit piece/die/tile seed counts must be positive safe
+integers. Omitted seed counts mean one copy. Zero, negative, fractional, non-finite,
+and unsafe counts fail before ID expansion; negative, zero, and fractional literals
+also fail typechecking. Widened `number` values still require runtime validation.
+Player bounds must be positive safe integers with `minPlayers <= maxPlayers`.
+
+`defineTopologyManifest` returns `ValidatedManifest<M>` after semantic validation.
+`compileManifest` returns a branded `CompiledManifest<M>` after validation and table
+materialization. Both snapshot the authored input so later source edits do not
+change the validated value or future initial tables. Literal IDs remain inferred.
+
+`ReducerGameDefinitionInput` describes the authored assembly fields. The assembled
+`ReducerGameDefinition` adds the bound contract and validation brand; authors never
+supply those output-only fields.
+
+`game.assemble` checks phase names, the initial phase, interaction declarations,
+and simultaneous-phase requirements, then returns a branded `ReducerGameDefinition`.
+Runtime consumers such as `createReducerBundle` require that assembled type;
+handwritten structural lookalikes do not satisfy it. These brands record SDK
+construction checks, not correctness of arbitrary reducer callbacks, and do not
+replace validation of runtime commands or state. As with other TypeScript types,
+explicit assertions can bypass them; treat constructed definitions as immutable.
+Each card in a manual card set requires `id` for its definition and `cardType`
+for its category:
+
+```ts
+cards: [
+  { id: "ace", cardType: "ranked", name: "Ace", count: 2, properties: {} },
+  { id: "king", cardType: "ranked", name: "King", count: 1, properties: {} },
+];
+```
+
+These definitions create runtime IDs `ace-1`, `ace-2`, and `king`, all in the
+`ranked` category. Component IDs cannot start with `card-ref:`; that prefix is reserved
+for opaque concealed-card references. These references belong to one seat and
+authority version and expire after commits or restores. When the card schema has `byCardType`, every `cardType` must
+name one of its schemas; `compileManifest` rejects unknown categories before `createGame` binds the result.
+The inferred table narrows a card lookup by its runtime ID to that definition's
+card set, category, and properties. Author field schemas with `z.object`. For card categories, use
+`cardSchema: { byCardType: { ranked: base.extend({ points: z.number().int() }) } }`
+to reuse shared properties. Zod `.extend` defines property overrides in both
+the runtime schema and inferred type. Fields are required unless authored with
+`.optional()` or an explicit `.default(...)`; primitive defaults are not inferred.
+Use `ref.cardId()`, `ref.pieceId()`, and the other `ref` markers for manifest
+references. `defineTopologyManifest` exports portable JSON Schema while
+retaining the authored types; refinements, transforms, and unsupported Zod
+constructs fail at definition time.
+For external JSON documents, call `parseTopologyManifestJson(value)` before
+`compileManifest`. The parser checks structural keys, field schemas and manifest
+references; transport services can preserve the document without duplicating
+the SDK's model.
+To migrate an older manifest, replace each card's `type` with `id` and set
+`cardType` explicitly (often to the former `type` value).
+
 ## Reducer runner contract
 
-`createReducerBundle(game)` returns exactly the contract version and four
-operations: `boardStatic()`, `initialize(input)`, `dispatch({ state, input })`,
-and `project({ state, playerIds })`. The runner contract is `0.6.0`; hosts must
-require that exact version. Dispatch includes validation, direct transaction mutations, and phase entry.
+`createReducerBundle(game)` returns exactly the contract version and three
+operations: `initialize(input)`, `dispatch({ state, input, referenceBasis })`,
+and `project({ state, playerIds, referenceBasis })`. The runner contract is `0.11.0`; hosts must
+require that exact version. The host supplies `referenceBasis: { sessionId, version }`:
+use a fresh session ID for each authority lifetime, increment version exactly once
+for every accepted input, and advance it on restore without restoring an old
+version from checkpoint data. Never change authoritative state under the same
+basis. Submitted inputs carry the complete issuing frame basis; the host checks
+its action-set version before dispatch. Dispatch includes validation, direct
+transaction mutations, and phase entry.
 Initialization returns
 `{ state, terminal?, events? }`, preserving outcomes and events from initial
 phase entry and returned transitions.
 
-Mutation callbacks use `tx.roll(dieId)`, `tx.shuffle({ zoneId, playerId? })`, and
-`tx.deal({ fromZoneId, toZoneId, playerId, count })` directly. Return
+Mutation callbacks use `tx.roll(dieId)`, `tx.shuffle({ zone: { zoneId, hostId } })`,
+`tx.deal({ from, to, count })` and
+`tx.flipCard({ cardId, faceUp })` directly. Like events, the zones the latest
+accepted operation shuffled are recorded in the runtime state; every seat that
+sees such a zone learns that it was shuffled, never its new order. Return
 `tx.transition(phaseName)` to enter a phase, including reentering the current
 phase. An unreturned outcome schedules no work. Entry chains are bounded to
 1,000 entries per dispatch. `tx.endGame(outcome, { transition })` enters the
@@ -234,7 +328,8 @@ implicit costs, guidance metadata, and phase zone declarations are removed.
 
 A game authors one `view` for each requested seat. Public and private fields
 compose in that function; the transport never uses a seat view as a spectator
-payload. Static boards come directly from the compiled manifest.
+payload. Shared static boards come from compiled definitions; per-player boards
+are instantiated for the actual roster.
 
 Use `memoize((input: SomeImmutableObject) => result)` for shared pure calculations.
 It caches by object identity with a WeakMap, including `undefined` results. Pass
@@ -255,6 +350,149 @@ pnpm add @dreamboard-games/sdk react@^19 react-dom@^19 @tanstack/react-store@0.1
 install the React adapter. The `/react` entry delegates selectors to that package;
 the application bundler resolves its supported React subscription dependencies.
 
+`/react` classifies each card press as a tap, hold, drag or browse. Enable
+`dragFeature`, export `useCardGesture`, `useCardRow`, `useActiveCard`, `useDropArea` and `useDragOverlay` from the
+binding, and use the copied Hand and BoardTargets components or your own renderer.
+The SDK prescribes no layout. Headless `game.drag` remains browser-free and handles
+atomic domain routing. A drop area can bind typed inputs with
+`{ interaction: "play.move", params: { destination: "discard" } }`; the SDK
+adds the dragged card and admits the complete draft against current domains.
+A ready bound single-card drop submits the action even when its commit mode is
+manual; unbound drops and many-card drafts keep their normal commit behavior.
+`game.drag.getIsDropTarget(target)` uses the same admission as dropping.
+Interaction `getSubmitProps(params)` and `getSubmitHandler(params)` accept the
+same explicit params as `submit(params)`, retaining pending and connection gates.
+`fanLayout` computes arc positions that always fit a hand,
+`handFan` adds a focused, readable card with configurable presets and timing,
+and
+`originsFeature` adds `card.getOrigin()` so a newly shown card can animate from
+the zone or player it came from, and `zone.getShuffle()` so a shuffled pile can
+riffle.
+
+## Local hand sorting
+
+Install `handFeature(core, context, { zones })` with named sorts for each zone:
+`{ hand: { defaultSort: "rank", sorts: { rank: { compare } } } }`.
+Comparators receive the seat's projected `Card` objects; narrow `card.hidden`
+before reading visible card data. Equal comparisons retain source order.
+
+`game.hand.getSortModes(zone)` returns typed mode IDs in declaration order.
+Read `getSortMode(zone)` and `getSortedCardIds(zone)`, then call
+`setSortMode(zone, mode)` from your UI. The zone carries its canonical host;
+each host's choice is independent. Labels, buttons and cycling are authored UI.
+Without a selected or default mode, the order comes directly from the source.
+The feature retains the zone's selected/selectable card ID helpers.
+
+Sort changes notify subscribers and preserve drafts and card selection without
+submitting. Choices survive frames and reset on source or seat changes. Captured
+`game.hand` branches retain their modes, and sorted IDs are derived from the
+projected zone passed to that branch. Old lifetime setters and disposed setters
+do nothing. See [Optional features](../../docs/api/features.md).
+
+## Opt-in game shortcuts
+
+Install `shortcutsFeature` in the same `createGameHook<Definition>()` binding as
+other features, and export its inferred `useGameShortcuts` and
+`useShortcutTarget` and `useShortcutHints` hooks. A child inside the bound `GameProvider` installs the
+app's bindings once:
+
+```tsx
+function AppShortcuts() {
+  useGameShortcuts({
+    bindings: [
+      {
+        kind: "interaction",
+        keys: ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
+        label: "Draw cards",
+        target: "zone",
+        zoneId: "deck",
+        interaction: "play.draw",
+        inputs: ({ key }) => ({ count: Number(key) }),
+      },
+      {
+        kind: "interaction",
+        keys: ["f"],
+        label: "Flip card",
+        target: "card",
+        input: "card",
+        interaction: "play.flip",
+        inputs: ({ target }) => ({ card: target.value }),
+      },
+      {
+        kind: "local",
+        keys: ["s"],
+        label: "Change hand order",
+        target: "zone",
+        zoneId: "hand",
+        getIsAvailable: ({ target }) => target.hostId === playerId,
+        run: ({ target }) => changeAuthoredOrder(target.hostId),
+      },
+    ],
+  });
+  return null;
+}
+```
+
+These interaction and input names are examples from an authored reducer;
+`playerId` and `changeAuthoredOrder` are supplied by the game. The
+binding's discriminated types derive from that reducer: interaction names,
+input keys, target kinds, and every required payload field must match. A game
+that exposes a counted draw submits one `count` payload; shortcuts never repeat
+a draw-one action. No actions or keys are supplied by default.
+
+Local bindings run game-authored presentation callbacks for a focused zone
+control or a focused card in that zone. A focused card resolves its current
+containing zone and actual host, including opaque hidden card references. Local
+bindings always use real DOM focus, including focus acquired by clicking; hover
+alone never activates them. Mouse browsing can change the interaction target
+while local actions retain the focused control's zone. They are unavailable
+during a card pointer gesture or its settling drag overlay. Games own any
+further restrictions through the optional pure `getIsAvailable` predicate.
+They do not submit source commands, alter interaction drafts, or require the
+player's reducer turn; an interaction request does not block a local action.
+`run` returns `void` or `Promise<void>` and is never evaluated for hints.
+The SDK supplies no sorting modes or cycling policy.
+
+Card controls using `useCardGesture` share its canonical pointer and keyboard
+focus. Zone controls spread
+`useShortcutTarget({ kind: "zone", zoneId: "deck", hostId: "table" }).props`;
+`hostId` must be the actual host allowed by that zone's attachment. Selectable
+board and tile controls can use the same hook with their canonical
+`SelectionTarget`. Hidden cards retain their opaque seat references.
+
+Keys are exact browser `event.key` strings. The adapter ignores held repeats,
+composition, editing controls, modifier combinations, and open modal or menu
+surfaces. Native radio inputs can carry a zone target for authored shortcuts;
+their ordinary arrow and space keys remain native unless explicitly bound.
+It prevents the browser default only when a single eligible binding
+handles the key. Source and seat changes clear the gesture target; unmounting
+removes the listener and binding hints.
+
+Input factories must be pure: eligibility and hints evaluate them against the
+current projected domains. Availability predicates for local bindings must
+also be pure. `game.shortcuts.getHints(target, activity)` returns only
+currently usable, unambiguous keys with their labels and `kind`. Interaction
+hints also carry their typed interaction name; local hints do not. Both variants
+share key collision handling. Headless callers supply local focus explicitly as
+`activity: { focusedTarget, pointerActive, touch }`; omitting activity admits
+only interaction bindings. Hints are empty while `touch` is true. The mounted
+hooks set it when the latest press was a finger and clear it on the next key or
+mouse press; the keys themselves keep working. `useShortcutHints(target)` reads
+those hints reactively and returns no hints when the feature is absent. The mounted
+`useGameShortcuts` hook returns `{ target, hints }` for a reserved help/status
+area. Rejected actions and transport failures use the binding's existing
+`onError` handler; callbacks from an old source, seat, or unmounted child are
+ignored. `game.shortcuts.handle(key, target, activity)` returns `null` for an
+unhandled
+key, or a promise of `{ kind: "local" }` or
+`{ kind: "interaction", result: SubmitResult }`. Callback failures reject that
+promise and use the same `onError` path. Interaction bindings use the same
+atomic `interaction.submit(params)` path available to authored action buttons.
+Explicit params are validated against the current projected descriptor without
+mutating drafts. Existing `submit()` continues to submit the interaction draft
+and defaults; both forms share availability and in-flight lifecycle barriers.
+The headless feature installs no DOM listeners.
+
 ## Local development and tests
 
 `localSource(game, { players, seed, as, options })` executes the production reducer
@@ -264,12 +502,97 @@ the hosted entry uses only `iframeSource()` and type imports.
 
 Local sources expose `inspect`, bounded `explore`, typed explicit-actor `apply`,
 `switchSeat`, `checkpoint`, and validated `restore`. A JSON checkpoint preserves
-pending selections and terminal state; restoring does not replay commands.
+visible pending selections and terminal state; restoring does not replay commands.
+Concealed selections expire after any other accepted input or restore. Each
+accepted extension of that same unfinished selection issues a new validity stamp
+for the immediately following frame. This prevents drafts from tracking hidden
+tiles or cards through a shuffle, including a shuffle that leaves their position
+unchanged.
 `createTestSource(snapshot)` supplies controlled frames and acknowledgements for
 instance and React tests. Static and hosted sources do not expose `apply`.
 
 Hosts import `assertReducerBundleContract`, `REDUCER_CONTRACT_VERSION`,
 `ReducerWire` types and `ReducerWireZod` schemas from `/reducer`. Canonical iframe
 and gameplay websocket schemas plus `materializePluginGameplayFrame` live at the
-root. Materialize the seat projection with static board data before publishing it;
-sources publish the canonical seat view and keep command bases private.
+root. Materialize the requested seat directly from its projection before publishing it;
+sources publish the canonical seat view and submit the exact frame basis.
+
+Visible cards share one complete `ViewCard` shape: `id`, `cardType`, and JSON
+`properties`, plus optional `name`, `text`, `frontImage`, and `backImage`.
+`ViewCardSchema` validates this shape. Reducer and gameplay `cardViewsById` maps
+contain these objects directly. Headless `card.view` preserves the manifest's
+card identity, category, and property inference and is deeply readonly; table-only
+`cardSetId` and `componentType` are absent. Concealed cards have a positional
+opaque seat identity, no view, and an optional separate `cardBacksById` entry.
+This wire format requires plugin protocol version 11 and reducer contract `0.11.0`.
+
+Tiles use opaque `SeatTileRef` values even when visible. A projected tile is either
+`{ disclosure: "visible", ref, tileTypeId, name, ownerId, fields, properties, frontImage? }` or
+`{ disclosure: "concealed", ref, appearance }`; an omitted tile contributes no
+entry or count. Public appearances are authored independently of secret faces.
+Boards and zones each carry their own projected tiles. Only visible tiles
+contribute cells, edges, vertices, and relations to the seat's board topology.
+Use `phase.inputs.tile({ from: [zoneId] })` or
+`phase.inputs.tile({ boards: [boardId] })` to select a tile. Reducers receive
+its authoritative identity after the SDK validates and resolves the reference.
+`tx.setTileDisclosure` controls face audiences and public appearance;
+`tx.setBoardVisibility` controls the board's audience. Location visibility always
+caps tile disclosure. Authored defaults cannot identify concealed tiles or cards.
+Game-owned view fields can publish visible references through `references.tile`
+and `references.space`; arbitrary authored text and JSON remain explicit publication.
+
+Every `tx.emit` event declares `audience: { kind: "public" }` or
+`{ kind: "seats", playerIds }`. A typed detail `{ kind: "tile", tileId }` is
+projected only when that tile is visible to the audience. Identity-specific event
+details and view references never track a concealed tile. Clients receive only
+their own events and admitted tile references.
+
+Card sets contain their authored `cards`, `cardSchema`, and `defaultHome` directly.
+Standard playing cards are game-owned definitions with ordinary suit/rank
+properties; the SDK does not synthesize inventories or assign built-in rules.
+
+The exported `createGestureRecognizer(down, callbacks, options)` defaults to
+vertical touch dragging, up or down, so card containers retain sideways
+scrolling. A row that fits uses `{ scrub: true }`: a sliding finger reports each
+move through `browse`, and turning up or down still drags. Pile controls can use
+`{ dragDirection: "any" }` with `touch-action: none` to drag toward a hand
+beside them. This classifies pointer intent only; submit an authored interaction
+through the bound game to enforce its rules, without selecting a hidden card ID.
+
+### Local card groups and marquee selection
+
+`cardSelectionFeature` holds a local list of projected card IDs, separate from
+interaction drafts. Authors decide which zones allow selection and how to draw
+it. Selection clears on an authoritative frame or source/perspective change.
+
+```ts
+features(core, context) {
+  const selection = cardSelectionFeature(core, context);
+  return {
+    selection,
+    drag: dragFeature(core, context, {
+      getSelection(cardId) {
+        const ids = selection.root.cardSelection.cardIds;
+        return ids.includes(cardId) ? ids : undefined;
+      },
+    }),
+  };
+}
+```
+
+Use `game.cardSelection.set(ids)`, `.toggle(id)` and `.clear()` for authored
+controls. A selected group can drop only onto an interaction with a `many(...)`
+card input that admits the entire group. Dropping submits that input once in
+selection order, replacing its draft; it never submits a sequence of single-card
+moves. The reducer remains responsible for validating and applying the group
+atomically. An unselected card retains ordinary single-card draft behavior.
+`useDragOverlay().cardIds` identifies all lifted cards; `cardId` is the anchor.
+
+`useMarqueeSelection` from `/react` is an opt-in mouse/pen background gesture.
+Pass `enabled`, `getCards: () => [{ id, element }]`, and
+`onSelect: (ids, additive) => ...`; spread its `props` on the selectable area.
+It reports intersecting cards on release and viewport `bounds` for an authored
+fixed-position overlay. Shift requests additive selection; Escape, pointer
+cancellation, blur or disabling the area cancels. Buttons, inputs and card
+controls keep their own gestures, and touch retains scrolling. A background
+click reports an empty selection. The hook supplies no styling or bulk-action UI.

package/dist/board-element-DXLPBVk-.d.ts

@@ -0,0 +1,13 @@
+import { f as BoardEdgeId, n as BoardVertexId } from './extract-Bi6_tzUr.js';
+
+declare function boardEdgeId<BoardId extends string>(layout: "hex" | "square", boardId: BoardId, latticeId: string): BoardEdgeId<BoardId>;
+declare function boardVertexId<BoardId extends string>(layout: "hex" | "square", boardId: BoardId, latticeId: string): BoardVertexId<BoardId>;
+/** Syntax proves namespace only; current placement owns element membership. */
+declare function parseBoardElementId(value: unknown): {
+    kind: "edge" | "vertex";
+    layout: "hex" | "square";
+    boardId: string;
+    latticeId: string;
+} | null;
+
+export { boardVertexId as a, boardEdgeId as b, parseBoardElementId as p };