@dreamboard-games/sdk 0.5.0-alpha.16 → 0.5.0-alpha.18

package/README.md

@@ -349,7 +349,7 @@ install the React adapter. The `/react` entry delegates selectors to that packag
 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`, `useActiveCard`, `useDropArea` and `useDragOverlay` from the
+`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
@@ -360,12 +360,32 @@ 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 for a hand,
+`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.
 
+## 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
@@ -378,6 +398,7 @@ function AppShortcuts() {
   useGameShortcuts({
     bindings: [
       {
+        kind: "interaction",
         keys: ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
         label: "Draw cards",
         target: "zone",
@@ -386,6 +407,7 @@ function AppShortcuts() {
         inputs: ({ key }) => ({ count: Number(key) }),
       },
       {
+        kind: "interaction",
         keys: ["f"],
         label: "Flip card",
         target: "card",
@@ -393,18 +415,41 @@ function AppShortcuts() {
         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. The
+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`;
@@ -414,19 +459,29 @@ board and tile controls can use the same hook with their canonical
 
 Keys are exact browser `event.key` strings. The adapter ignores held repeats,
 composition, editing controls, modifier combinations, and open modal or menu
-surfaces. It prevents the browser default only when a single eligible binding
+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. `game.shortcuts.getHints(target)` returns only
-currently usable, unambiguous keys with their labels and typed interaction
-names, for menus or help. `useShortcutHints(target)` reads those hints reactively
+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 }`; omitting activity admits only
+interaction bindings. `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)` uses the same
+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
@@ -492,7 +547,47 @@ 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
-upward touch dragging so hands retain sideways scrolling. Pile controls can use
+upward touch dragging so card containers retain sideways scrolling. A row that
+fits uses `{ scrub: true }`: a sliding finger reports each move through
+`browse`, and turning upward still drags. Pile controls can use
 `{ dragDirection: "any" }` with `touch-action: none` to drag toward a hand below
 or 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-CRN_hj5F.d.ts → board-element-Bi_CEmNa.d.ts}

@@ -1,4 +1,4 @@
-import { f as BoardEdgeId, n as BoardVertexId } from './extract-DgzrJ5el.js';
+import { f as BoardEdgeId, n as BoardVertexId } from './extract-DcvrH9lh.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>;

package/dist/{chunk-TJQTLYDI.js → chunk-BNQF7QXR.js}

@@ -8,7 +8,7 @@ import {
   boardSpaceHostId,
   isCardReferenceNamespace,
   parseBoardSpaceHostId
-} from "./chunk-B4RMCLUN.js";
+} from "./chunk-U6R7FAH4.js";
 import {
   AuthoredTileDisclosureSchema,
   BoardProjectionSchema,
@@ -30,11 +30,13 @@ import {
   inputValueInDomain,
   inputValueKey,
   isBoardSpaceTarget,
+  isPositionTarget,
   parsePerPlayerInstanceId,
   parseTileSpaceId,
   requireLookup,
-  tileSpaceId
-} from "./chunk-ES74C2IN.js";
+  tileSpaceId,
+  zonePositions
+} from "./chunk-CZRPUWCT.js";
 
 // src/reducer/model/error-codes.ts
 var FrameworkErrorCodes = {
@@ -1344,6 +1346,20 @@ function moveComponentToZoneInPlace(options) {
   destination.ids.splice(index, 0, componentId);
   place(table, definitions, componentId, destination.ref, playedBy);
 }
+function moveComponentToPositionInPlace(options) {
+  const { table, definitions, componentId, at, playedBy } = options;
+  const to = { zoneId: at.zoneId, hostId: at.hostId };
+  const source = table.componentLocations[componentId];
+  const from = source?.type === "InZone" && source.zoneId === at.zoneId && source.hostId === at.hostId ? resolveZone(table, definitions, to).ids.indexOf(componentId) : -1;
+  moveComponentToZoneInPlace({
+    table,
+    definitions,
+    componentId,
+    to,
+    position: from >= 0 && from < at.index ? at.index - 1 : at.index,
+    playedBy
+  });
+}
 function dealComponentsInPlace(options) {
   const { table, definitions } = options;
   assertNonNegativeSafeInteger(options.count, "Deal count");
@@ -2448,6 +2464,14 @@ var transactionMutations = {
     moveComponentToZoneInPlace({ table: state.table, definitions, ...args });
     return state;
   },
+  moveComponentToPosition(state, args, definitions) {
+    moveComponentToPositionInPlace({
+      table: state.table,
+      definitions,
+      ...args
+    });
+    return state;
+  },
   deal(state, args, definitions) {
     dealComponentsInPlace({ table: state.table, definitions, ...args });
     return state;
@@ -3806,6 +3830,14 @@ function baseValuesForDomain(domain, collector, context) {
         )
       );
     }
+    case "zonePosition":
+      return finiteValueSource(
+        collector.eligibleTargets ? collector.eligibleTargets(
+          context.domainState,
+          context.playerId,
+          context.queries()
+        ) : zonePositions(domain.zones)
+      );
     case "choiceList":
       return choiceListValueSource(domain);
     case "boundedNumber":
@@ -5772,6 +5804,22 @@ function boardReference(value, domain, disclosure, decode) {
   if (typeof value !== "string") return denied2;
   return map(domain.targetKind, domain.boardId, value) ?? denied2;
 }
+function zoneHostReference(zoneId, hostId, disclosure, decode) {
+  const zone = disclosure.zones.find(
+    (zone2) => zone2.zoneId === zoneId && (decode ? zone2.seatHostId : zone2.hostId) === hostId
+  );
+  return zone ? decode ? zone.hostId : zone.seatHostId : null;
+}
+function positionReference(value, disclosure, decode) {
+  if (!isPositionTarget(value)) return denied2;
+  const hostId = zoneHostReference(
+    value.zoneId,
+    value.hostId,
+    disclosure,
+    decode
+  );
+  return hostId === null ? denied2 : { ...value, hostId };
+}
 function domainMapper(domain, disclosure, cards, decode) {
   switch (domain.type) {
     case "tileTarget":
@@ -5780,12 +5828,16 @@ function domainMapper(domain, disclosure, cards, decode) {
       return (value) => cardReference(value, disclosure, cards, decode);
     case "boardTarget":
       return (value) => boardReference(value, domain, disclosure, decode);
+    case "zonePosition":
+      return (value) => positionReference(value, disclosure, decode);
     default:
       return void 0;
   }
 }
 function collectorMapper(collector, disclosure, cards, decode) {
   switch (collector.kind) {
+    case "position":
+      return (value) => positionReference(value, disclosure, decode);
     case "tile":
       return (value) => typeof value === "string" ? (decode ? disclosure.tileId(value) : disclosure.tileRef(value)) ?? denied2 : denied2;
     case "card":
@@ -5826,15 +5878,25 @@ function projectInput(input, disclosure, cards) {
   const map = domainMapper(input.domain, disclosure, cards, false);
   if (!map) return input;
   const domain = input.domain;
-  if (domain.type !== "tileTarget" && domain.type !== "cardTarget" && domain.type !== "boardTarget")
+  if (domain.type !== "tileTarget" && domain.type !== "cardTarget" && domain.type !== "boardTarget" && domain.type !== "zonePosition")
     return input;
-  const eligibleTargets = domain.eligibleTargets.flatMap((value) => {
-    const mapped = map(value);
-    return mapped === denied2 ? [] : [mapped];
-  });
-  const projectedDomain = {
+  const projectedDomain = domain.type === "zonePosition" ? {
+    ...domain,
+    zones: domain.zones.flatMap((zone) => {
+      const hostId = zoneHostReference(
+        zone.zoneId,
+        zone.hostId,
+        disclosure,
+        false
+      );
+      return hostId === null ? [] : [{ ...zone, hostId }];
+    })
+  } : {
     ...domain,
-    eligibleTargets
+    eligibleTargets: domain.eligibleTargets.flatMap((value) => {
+      const mapped = map(value);
+      return mapped === denied2 ? [] : [mapped];
+    })
   };
   const { defaultValue, ...rest } = input;
   const mappedDefault = defaultValue === void 0 ? denied2 : mapSelection(
@@ -7123,4 +7185,4 @@ export {
   createProjectionBuilder,
   createReducerBundle
 };
-//# sourceMappingURL=chunk-TJQTLYDI.js.map
+//# sourceMappingURL=chunk-BNQF7QXR.js.map