@dreamboard-games/sdk 0.5.0-alpha.4 → 0.5.0-alpha.6

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, selectors, subscriptions, and dnd-kit card/drop hooks.
+- `@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.
 
@@ -221,7 +221,8 @@ cards: [
 ```
 
 These definitions create runtime IDs `ace-1`, `ace-2`, and `king`, all in the
-`ranked` category. When the card schema has `variants`, every `cardType` must
+`ranked` category. Card IDs cannot start with `hidden:`; that prefix is reserved
+for the positions a seat uses to address concealed cards. When the card schema has `variants`, every `cardType` must
 name one of them; `compileManifest` and `createGame` reject unknown categories.
 The inferred table narrows a card lookup by its runtime ID to that definition's
 card set, category, and properties. A variant property overrides a shared
@@ -233,14 +234,15 @@ To migrate an older manifest, replace each card's `type` with `id` and set
 
 `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.7.0`; hosts must
+and `project({ state, playerIds })`. The runner contract is `0.8.0`; hosts must
 require that exact version. 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({ zoneId, playerId? })`,
+`tx.deal({ fromZoneId, toZoneId, playerId, count })` and
+`tx.flipCard({ cardId, faceUp })` directly. 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
@@ -296,10 +298,13 @@ 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.
 
-The SDK includes dnd-kit for `/react` drag and drop. Enable `dragFeature`, export
-`useCardDrag` and `useBoardDrop` from the binding, and use the copied Hand and
-BoardTargets components or your own renderer. GameProvider owns the drag provider.
-Headless `game.drag` remains browser-free and handles atomic domain routing.
+`/react` classifies each card press as a tap, hold, drag or browse. Enable
+`dragFeature`, export `useCardGesture`, `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. `fanLayout` computes arc positions for a hand, and
+`originsFeature` adds `card.getOrigin()` so a newly shown card can animate from
+the zone or player it came from.
 
 ## Local development and tests
 

package/dist/{chunk-OOFMBCFF.js → chunk-CSHKCPBY.js}

@@ -9,6 +9,66 @@ import {
   requireLookup
 } from "./chunk-3JXUL4VN.js";
 
+// src/headless/runtime-features.ts
+var runtimeFeatures = /* @__PURE__ */ Symbol("runtimeFeatures");
+
+// src/headless/input-control.ts
+function resourceValue(domain, value) {
+  const record = value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return Object.fromEntries(
+    domain.resources.map((resource) => {
+      const amount = record[resource.resourceId];
+      return [resource.resourceId, typeof amount === "number" ? amount : 0];
+    })
+  );
+}
+function createInputControl(input, props) {
+  const domain = input.getDomain();
+  const current = input.getValue();
+  const common = { key: input.key, disabled: props.disabled, props };
+  if (domain.type === "boundedNumber") {
+    if (domain.selection?.mode === "many")
+      return {
+        ...common,
+        type: "boundedNumber",
+        domain,
+        mode: "many",
+        value: Array.isArray(current) ? current.filter(
+          (value) => typeof value === "number"
+        ) : [],
+        setValue: (value) => input.setValue(value)
+      };
+    return {
+      ...common,
+      type: "boundedNumber",
+      domain,
+      mode: "single",
+      value: typeof current === "number" ? current : void 0,
+      setValue: (value) => value === void 0 ? input.clear() : input.setValue(value)
+    };
+  }
+  if (domain.type === "resourceMap") {
+    if (domain.selection?.mode === "many")
+      return {
+        ...common,
+        type: "resourceMap",
+        domain,
+        mode: "many",
+        value: Array.isArray(current) ? current.map((value) => resourceValue(domain, value)) : [],
+        setValue: (value) => input.setValue(value)
+      };
+    return {
+      ...common,
+      type: "resourceMap",
+      domain,
+      mode: "single",
+      value: current === void 0 ? void 0 : resourceValue(domain, current),
+      setValue: (value) => value === void 0 ? input.clear() : input.setValue(value)
+    };
+  }
+  return { ...common, type: "targets", options: input.getTargetOptions() };
+}
+
 // src/headless/instance.ts
 import { createStore } from "@tanstack/store";
 
@@ -348,6 +408,21 @@ var InputObject = class {
   get game() {
     return this.interaction.game;
   }
+  get domainType() {
+    return this.descriptor.domain.type;
+  }
+  get selectionMode() {
+    return isManyInput(this.descriptor) ? "many" : "single";
+  }
+  getTargetOptions() {
+    const domain = this.getDomain();
+    return this.getEligibleTargets().map((value) => ({
+      value,
+      label: (domain.type === "choice" || domain.type === "choiceList" ? domain.choices.find((choice) => Object.is(choice.value, value))?.label : void 0) ?? (value === null ? "None" : typeof value === "object" ? JSON.stringify(value) : String(value)),
+      selected: this.getIsSelected(value),
+      props: this.getTargetProps(value)
+    }));
+  }
   getDomain() {
     return this.descriptor.domain;
   }
@@ -407,28 +482,18 @@ var InputObject = class {
       onClick: () => this.getSelectHandler(value)()
     };
   }
-  getFieldProps() {
+  getControl() {
     const disabled = !this.interaction.getIsAvailable() || this.interaction.status !== "open" || !this.interaction.connected;
-    return {
+    return createInputControl(this, {
       ...data("option", this.interaction.key, this.key),
       "data-seat": this.interaction.seat,
-      value: this.getValue() ?? "",
       disabled,
-      "data-disabled": disabled,
-      onChange: (event) => {
-        if (event.currentTarget.value === "") {
-          this.clear();
-          return;
-        }
-        this.setValue(
-          this.descriptor.domain.type === "boundedNumber" ? Number(event.currentTarget.value) : event.currentTarget.value
-        );
-      }
-    };
+      "data-disabled": disabled
+    });
   }
 };
 var CardObject = class {
-  constructor(owner, id, zone, index, encoded, routes) {
+  constructor(owner, id, zone, index, encoded, backImage, routes) {
     this.owner = owner;
     this.id = id;
     this.zone = zone;
@@ -440,6 +505,7 @@ var CardObject = class {
     ) ?? -1;
     this.view = encoded ? immutableCopy(JSON.parse(encoded)) : null;
     this.hidden = this.view === null;
+    this.backImage = backImage ?? null;
   }
   owner;
   id;
@@ -450,6 +516,7 @@ var CardObject = class {
   seat;
   view;
   hidden;
+  backImage;
   get game() {
     return this.owner.instance;
   }
@@ -602,7 +669,60 @@ var Controller = class {
     this.localDrafts = options.initialState?.drafts ?? EMPTY_DRAFTS;
     this.localActive = options.initialState?.activeInteraction ?? null;
     this.sourceState = options.source.store.get();
+    const current = () => this.building ?? this.store.get();
     const root = {
+      get snapshot() {
+        return current().snapshot;
+      },
+      get view() {
+        return current().view;
+      },
+      get version() {
+        return current().version;
+      },
+      get connection() {
+        return current().connection;
+      },
+      get failure() {
+        return current().failure;
+      },
+      get request() {
+        return current().request;
+      },
+      get state() {
+        return current().state;
+      },
+      get phase() {
+        return current().phase;
+      },
+      get turn() {
+        return current().turn;
+      },
+      get me() {
+        return current().me;
+      },
+      get players() {
+        return current().players;
+      },
+      get interactions() {
+        return current().interactions;
+      },
+      get inputs() {
+        return current().inputs;
+      },
+      get zones() {
+        return current().zones;
+      },
+      get cards() {
+        return current().cards;
+      },
+      get events() {
+        return current().events;
+      },
+      store: {
+        get: () => this.store.get(),
+        subscribe: (listener) => this.store.subscribe(listener)
+      },
       getSnapshot: () => this.building ?? this.store.get(),
       getOptions: () => this.options,
       setOptions: (next) => this.setOptions(next),
@@ -614,35 +734,23 @@ var Controller = class {
       assertCoverage: () => this.assertCoverage(),
       inspect: () => this.store.get()
     };
-    this.instance = root;
-    for (const key of [
-      "snapshot",
-      "view",
-      "version",
-      "connection",
-      "failure",
-      "request",
-      "state",
-      "phase",
-      "turn",
-      "me",
-      "players",
-      "interactions",
-      "inputs",
-      "zones",
-      "cards",
-      "events"
-    ])
-      Object.defineProperty(root, key, {
-        get: () => (this.building ?? this.store.get())[key]
-      });
-    this.store = createStore(Object.freeze(this.build()));
-    Object.defineProperty(root, "store", {
-      value: {
-        get: () => this.store.get(),
-        subscribe: (listener) => this.store.subscribe(listener)
+    for (const [key, descriptor] of Object.entries(
+      Object.getOwnPropertyDescriptors(root)
+    )) {
+      if (descriptor.get) {
+        Object.defineProperty(root, key, {
+          enumerable: false,
+          configurable: false
+        });
       }
+    }
+    Object.defineProperty(root, "store", {
+      enumerable: false,
+      configurable: false,
+      writable: false
     });
+    this.instance = root;
+    this.store = createStore(Object.freeze(this.build()));
     if ("apply" in options.source)
       Object.defineProperty(root, "apply", {
         value: (action) => this.options.source.apply(action)
@@ -651,9 +759,14 @@ var Controller = class {
       Object.defineProperty(root, "explore", {
         value: (...args) => this.options.source.explore(...args)
       });
-    const context = {
-      createBoard: (id, data2) => this.object("board", {
-        id,
+    const runtime = {
+      game: this.instance,
+      getBoards: () => {
+        const view = this.instance.view;
+        return view?.boards?.byId ?? {};
+      },
+      createBoard: (data2) => this.object("board", {
+        id: data2.id,
         data: immutableCopy(data2),
         game: this.instance
       }),
@@ -663,6 +776,7 @@ var Controller = class {
         if (!this.disposed) this.refresh();
       }
     };
+    const context = { ...runtime, [runtimeFeatures]: runtime };
     for (const feature of Object.values(
       features?.(this.instance, context) ?? {}
     )) {
@@ -725,7 +839,8 @@ var Controller = class {
     );
   }
   object(hook, value) {
-    return Object.freeze(Object.setPrototypeOf(value, this.prototypes[hook]));
+    Object.setPrototypeOf(value, this.prototypes[hook]);
+    return Object.freeze(value);
   }
   drafts() {
     if (this.options.state && this.options.state === this.invalidControlledState)
@@ -1069,10 +1184,17 @@ var Controller = class {
     if (!interaction?.currentLifetime() || !interaction.getIsAvailable())
       return;
     const cardInput = interaction.findInput(target.cardInputKey);
-    const input = interaction.findInput(target.inputKey);
-    if (!cardInput || cardInput.descriptor.domain.type !== "cardTarget" || !cardInput.getIsEligible(cardId) || !input || !matchesBoardTarget(input.descriptor, target) || !input.getIsEligible(target.value))
+    if (!cardInput || cardInput.descriptor.domain.type !== "cardTarget" || !cardInput.getIsEligible(cardId))
+      return;
+    const input = target.kind === "interaction" ? void 0 : interaction.findInput(target.inputKey);
+    if (target.kind !== "interaction" && (!input || !matchesBoardTarget(input.descriptor, target) || !input.getIsEligible(target.value)))
       return;
     let next = { ...this.drafts()[interaction.key] };
+    const chosen = next[cardInput.key];
+    if (!input && isManyInput(cardInput.descriptor) && Array.isArray(chosen) && chosen.includes(cardId)) {
+      this.activate(interaction.key);
+      return;
+    }
     routeCardInputIntent(
       {
         getDraft: () => next,
@@ -1087,7 +1209,7 @@ var Controller = class {
       {
         cardId,
         cardInputKey: cardInput.key,
-        dropTarget: { inputKey: input.key, value: target.value }
+        dropTarget: input && target.kind !== "interaction" ? { inputKey: input.key, value: target.value } : void 0
       }
     );
     this.writeDraft(interaction.key, next);
@@ -1233,6 +1355,7 @@ var Controller = class {
                     id,
                     index,
                     zone.cardViewsById[cardId],
+                    zone.cardBacksById[cardId],
                     Object.freeze(
                       (zone.playableByCardId[cardId] ?? []).map(
                         (descriptor) => this.object(
@@ -1331,8 +1454,78 @@ function createGameInstance() {
   };
 }
 
+// src/headless/gesture.ts
+var GESTURE_THRESHOLDS = Object.freeze({
+  /** Movement, in CSS pixels, before a press becomes a drag or a browse. */
+  slop: 8,
+  /** A touch or pen held this long without moving inspects the card. */
+  holdMs: 350,
+  /** A mouse resting on a card this long inspects it. */
+  hoverMs: 250,
+  /** A finger drags when upward travel exceeds this multiple of sideways travel. */
+  axisBias: 1.25
+});
+function createGestureRecognizer(down, callbacks) {
+  const origin = { x: down.clientX, y: down.clientY };
+  const mouse = down.pointerType === "mouse";
+  let kind = "tap";
+  let finished = false;
+  const holdTimer = mouse ? void 0 : setTimeout(() => {
+    kind = "hold";
+    callbacks.hold();
+  }, GESTURE_THRESHOLDS.holdMs);
+  const point = (event) => ({
+    x: event.clientX,
+    y: event.clientY
+  });
+  const ours = (event) => !finished && (!event || event.pointerId === down.pointerId);
+  function finish() {
+    finished = true;
+    clearTimeout(holdTimer);
+  }
+  return {
+    move(event) {
+      if (!ours(event)) return;
+      if (kind === "drag") return callbacks.dragMove(point(event));
+      const dx = event.clientX - origin.x;
+      const dy = event.clientY - origin.y;
+      if (kind !== "tap" || Math.hypot(dx, dy) < GESTURE_THRESHOLDS.slop)
+        return;
+      clearTimeout(holdTimer);
+      const lifts = mouse || -dy > GESTURE_THRESHOLDS.axisBias * Math.abs(dx);
+      if (lifts && callbacks.dragStart(origin)) {
+        kind = "drag";
+        callbacks.dragMove(point(event));
+      } else kind = "browse";
+    },
+    up(event) {
+      if (!ours(event)) return;
+      finish();
+      callbacks.end(kind, point(event));
+    },
+    cancel(event) {
+      if (!ours(event)) return;
+      finish();
+      callbacks.cancel(kind);
+    }
+  };
+}
+
+// src/headless/drop-targets.ts
+function isSameDropTarget(left, right) {
+  if (left.interactionKey !== right.interactionKey || left.cardInputKey !== right.cardInputKey)
+    return false;
+  if (left.kind === "interaction" || right.kind === "interaction")
+    return left.kind === right.kind;
+  return left.kind === right.kind && left.valueKind === right.valueKind && inputValueKey(left.value) === inputValueKey(right.value) && (left.valueKind !== "board-id" || right.valueKind === "board-id" && left.boardId === right.boardId) && left.inputKey === right.inputKey;
+}
+
 export {
+  runtimeFeatures,
   AmbiguousTargetError,
-  createGameInstance
+  createGameInstance,
+  isSameDropTarget,
+  GESTURE_THRESHOLDS,
+  createGestureRecognizer
 };
-//# sourceMappingURL=chunk-OOFMBCFF.js.map
+//# sourceMappingURL=chunk-CSHKCPBY.js.map