@dreamboard-games/sdk 0.5.0-alpha.13 → 0.5.0-alpha.15

package/README.md

@@ -352,7 +352,9 @@ the application bundler resolves its supported React subscription dependencies.
 `dragFeature`, export `useCardGesture`, `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. `fanLayout` computes arc positions for a hand, and
+atomic domain routing. `fanLayout` computes arc positions for 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.
 

package/dist/{chunk-6ZNAIOYG.js → chunk-TJQTLYDI.js}

@@ -7098,14 +7098,15 @@ export {
   isSparseMapSchema,
   getObjectShape,
   normalizeCommandParams,
+  enumerateZoneHosts,
+  resolveZoneAccess,
+  assertContainmentAcyclic,
+  assertZoneConsistency,
   REDUCER_CONTRACT_VERSION,
   assertReducerBundleContract,
   ZoneVisibilitySchema,
   TileTypeSpecSchema,
   GameTopologyManifestSchema,
-  enumerateZoneHosts,
-  assertContainmentAcyclic,
-  assertZoneConsistency,
   collectReducerDefinitionIndex,
   createIngressRuntimeCodec,
   noopDiagnosticsSink,
@@ -7122,4 +7123,4 @@ export {
   createProjectionBuilder,
   createReducerBundle
 };
-//# sourceMappingURL=chunk-6ZNAIOYG.js.map
+//# sourceMappingURL=chunk-TJQTLYDI.js.map

package/dist/index.d.ts

@@ -1500,6 +1500,122 @@ declare function fanLayout({ count, width, cardWidth, cardHeight, step, minStep,
 /** Moves a fanned card outward along its own tilt, as for a selected card. */
 declare function liftFanCard(card: FanCard, distance: number): FanCard;
 
+/**
+ * How a hand rests and focuses one card. Lengths are shares of the resting
+ * card, so one configuration fits every card size. Missing options come from
+ * `handFanPresets.open`.
+ */
+interface HandFanOptions extends Pick<FanOptions, "angle" | "maxSpread"> {
+    /** Distance between neighbouring cards when there is room, in card widths. Default 0.6, as `fanLayout`. */
+    readonly spacing?: number;
+    /** Share of each resting card's height below the hand's bottom edge. 0 shows whole cards. */
+    readonly tuck?: number;
+    /** Focused face width as a multiple of the resting card. */
+    readonly focusScale?: number;
+    /** Tallest focused face, as a share of the window height. */
+    readonly focusMaxHeight?: number;
+    /**
+     * Sideways shift of the first, second, third… neighbour, in card widths.
+     * The focused face's extra width tapers over the same neighbours.
+     */
+    readonly push?: readonly number[];
+    /** Narrowest strip of each neighbour kept visible, in card widths. */
+    readonly exposed?: number;
+}
+/** Starting points for a hand; spread one and override what differs. */
+declare const handFanPresets: {
+    /** Whole resting cards; focusing enlarges the card. */
+    readonly open: {
+        readonly tuck: 0;
+        readonly focusScale: 2;
+        readonly focusMaxHeight: 0.55;
+        readonly push: readonly [0.29, 0.19, 0.1];
+        readonly exposed: 0.35;
+    };
+    /**
+     * Larger cards tucked below the bottom edge and spaced like a dealt hand;
+     * focusing mostly reveals the card.
+     */
+    readonly tucked: {
+        readonly spacing: 0.75;
+        readonly tuck: 0.4;
+        readonly focusScale: 1.4;
+        readonly focusMaxHeight: 0.4;
+        readonly push: readonly [0.29, 0.19, 0.1];
+        readonly exposed: 0.35;
+    };
+    /** Coarse pointers: a shallower tuck and wider strips to tap. */
+    readonly touch: {
+        readonly spacing: 0.75;
+        readonly tuck: 0.2;
+        readonly focusScale: 1.6;
+        readonly focusMaxHeight: 0.5;
+        readonly push: readonly [0.35, 0.2, 0.1];
+        readonly exposed: 0.45;
+    };
+};
+/** A card's `fanLayout` pose with its scale and stacking order. */
+interface HandFanPose extends FanCard {
+    readonly scale: number;
+    /** Stacking order: fan order, with the focused card above the rest. */
+    readonly layer: number;
+}
+interface HandFan {
+    /** One pose per card, in the same coordinates as `fanLayout`. */
+    readonly cards: readonly HandFanPose[];
+    /** The fan's width, as `fanLayout` reports it. */
+    readonly width: number;
+    /** The visible band: the fan's height less the tucked part of its cards. */
+    readonly height: number;
+    /** Space above the band that a focused face can rise into. */
+    readonly headroom: number;
+}
+interface HandFanInput extends Pick<FanOptions, "count" | "width" | "cardWidth" | "cardHeight"> {
+    /** Index of the focused card, or -1 for none. */
+    readonly focused?: number;
+    /**
+     * The part of the fan the viewer can see after scrolling, in fan
+     * coordinates; a focused face stays inside it. Defaults to `width`,
+     * centred on the fan.
+     */
+    readonly visible?: {
+        readonly left: number;
+        readonly width: number;
+    };
+    /** Window height in pixels; `focusMaxHeight` is a share of it. */
+    readonly windowHeight?: number;
+    /** Pixels above the band's bottom edge that a focused face may use. */
+    readonly room?: number;
+    readonly options?: HandFanOptions;
+}
+/**
+ * Lays a hand on a `fanLayout` arc and focuses one card: upright on the
+ * band's bottom edge at a readable size, with nearby cards pushed sideways.
+ * Neighbours keep their order and at least their `exposed` strip.
+ */
+declare function handFan({ count, width, cardWidth, cardHeight, focused, visible, windowHeight, room, options, }: HandFanInput): HandFan;
+/**
+ * An exponential approach to the target. An animation restarted from the
+ * current pose continues the same curve at full speed, so retargeting never
+ * stalls a card or overshoots.
+ */
+declare function exponentialOut(progress: number): number;
+/** Durations in seconds with an easing function, as Motion transitions take them. */
+declare const handFanTiming: {
+    /** The focused face rises: 90% in about 45ms. */
+    readonly focus: {
+        readonly duration: 0.09;
+        readonly ease: typeof exponentialOut;
+    };
+    /** Sideways travel, neighbours and returning cards: 90% in about 300ms. */
+    readonly settle: {
+        readonly duration: 0.6;
+        readonly ease: typeof exponentialOut;
+    };
+};
+/** An easing function as a CSS `linear()` easing, for CSS transitions and the Web Animations API. */
+declare function cssEasing(ease: (progress: number) => number, samples?: number): string;
+
 declare function canonicalizePluginRuntimeJson(value: unknown): RuntimeJson;
 declare function encodeCanonicalPluginRuntimeJson(value: unknown): string;
 declare function digestPluginRuntimeJson(value: unknown): string;
@@ -4755,4 +4871,4 @@ declare function parsePluginGameplayFrame(value: unknown): PluginGameplayFrame;
 declare function parseHostToPluginEnvelope(value: unknown): PluginProtocolEnvelope<HostToPluginPayload>;
 declare function parsePluginToHostEnvelope(value: unknown): PluginProtocolEnvelope<PluginToHostPayload>;
 
-export { ActionProps, type ActionSetVersionInput, AmbiguousTargetError, AuthAcceptedFrameSchema, AuthConnectFrameSchema, AuthRefreshFrameSchema, BoardBase, BoardCollection, BoardDataOf, BoardEdgeId, type BoardFeature, type BoardLayoutOptions, type BoardLayoutTile, BoardSpace, BoardSpaceCollection, BoardVertexId, type CancelInteractionCommand, CancelInteractionCommandSchema, Card, type CardOrigin, type ClientGameplayFrame, ClientGameplayFrameSchema, CommandSource, CoreInstance, DREAMBOARD_PLUGIN_PROTOCOL, DREAMBOARD_PLUGIN_PROTOCOL_VERSION, DREAMBOARD_SDK_PACKAGES, DREAMBOARD_SDK_PACKAGE_SET, DREAMBOARD_SDK_VERSION, type DragController, type DragState, type DreamboardSdkPackageName, type DreamboardSdkPackageSet, DropTarget, type FanCard, type FanLayout, type FanOptions, FeatureContext, Features, GESTURE_THRESHOLDS, GameEventDetailSchema, GameEventSchema, GameInstance, GameOutcomeSchema, GameSource, GameplayBackpressureFrameSchema, GameplayBackpressureOperationSchema, GameplayBackpressureReasonSchema, GameplayBasis, GameplayBasisSchema, GameplayCloseCode, type GameplayCredential, GameplayCredentialSchema, type GestureCallbacks, type GestureKind, type GestureOptions, type GesturePointer, type GestureRecognizer, type HandOptions, type HostToPluginEnvelope, HostToPluginEnvelopeSchema, type HostToPluginPayload, HostToPluginPayloadSchema, IdOf, InstanceOptions, InteractionDescriptor, type InteractionResult, InteractionResultSchema, type MaterializePluginGameplayFrameInput, type PanZoomOptions, PlayerId, PluginGameplayFrame, PluginGameplayFrameSchema, PluginPlayerSummarySchema, type PluginProtocolEnvelope, PluginSessionDescriptor, PluginSessionDescriptorSchema, type PluginToHostEnvelope, PluginToHostEnvelopeSchema, type PluginToHostPayload, PluginToHostPayloadSchema, ReducerSeatProjectionBundle, RuntimeJson, RuntimeTargetOptions, SeatBoardTopology, SeatCardId, SeatFrameSchema, SeatProjectionBundleSchema, SeatSpaceRef, SeatTileRef, type ServerGameplayFrame, ServerGameplayFrameSchema, SessionResumeFrameSchema, SessionSnapshotFrameSchema, SimultaneousPhaseSnapshotSchema, SourceSnapshot, type SubmitInteractionCommand, SubmitInteractionCommandSchema, SystemActionEventSchema, TargetOptions, type ViewportSurface, type ViewportTransform, type WheelInput, Zone, ZoneHandlesSnapshotSchema, ZoneHostId, boardFeature, canonicalizePluginRuntimeJson, computePluginActionSetVersion, createGameInstance, createGestureRecognizer, createPluginProtocolEnvelopeSchema, digestPluginCommandRequest, digestPluginGameplayFrame, digestPluginRuntimeJson, dragFeature, encodeCanonicalPluginRuntimeJson, fanLayout, handFeature, hostSource, iframeSource, liftFanCard, magneticDropPoint, materializePluginGameplayFrame, originsFeature, panZoomFeature, parseHostToPluginEnvelope, parsePluginGameplayFrame, parsePluginSessionDescriptor, parsePluginToHostEnvelope, staticSource };
+export { ActionProps, type ActionSetVersionInput, AmbiguousTargetError, AuthAcceptedFrameSchema, AuthConnectFrameSchema, AuthRefreshFrameSchema, BoardBase, BoardCollection, BoardDataOf, BoardEdgeId, type BoardFeature, type BoardLayoutOptions, type BoardLayoutTile, BoardSpace, BoardSpaceCollection, BoardVertexId, type CancelInteractionCommand, CancelInteractionCommandSchema, Card, type CardOrigin, type ClientGameplayFrame, ClientGameplayFrameSchema, CommandSource, CoreInstance, DREAMBOARD_PLUGIN_PROTOCOL, DREAMBOARD_PLUGIN_PROTOCOL_VERSION, DREAMBOARD_SDK_PACKAGES, DREAMBOARD_SDK_PACKAGE_SET, DREAMBOARD_SDK_VERSION, type DragController, type DragState, type DreamboardSdkPackageName, type DreamboardSdkPackageSet, DropTarget, type FanCard, type FanLayout, type FanOptions, FeatureContext, Features, GESTURE_THRESHOLDS, GameEventDetailSchema, GameEventSchema, GameInstance, GameOutcomeSchema, GameSource, GameplayBackpressureFrameSchema, GameplayBackpressureOperationSchema, GameplayBackpressureReasonSchema, GameplayBasis, GameplayBasisSchema, GameplayCloseCode, type GameplayCredential, GameplayCredentialSchema, type GestureCallbacks, type GestureKind, type GestureOptions, type GesturePointer, type GestureRecognizer, type HandFan, type HandFanInput, type HandFanOptions, type HandFanPose, type HandOptions, type HostToPluginEnvelope, HostToPluginEnvelopeSchema, type HostToPluginPayload, HostToPluginPayloadSchema, IdOf, InstanceOptions, InteractionDescriptor, type InteractionResult, InteractionResultSchema, type MaterializePluginGameplayFrameInput, type PanZoomOptions, PlayerId, PluginGameplayFrame, PluginGameplayFrameSchema, PluginPlayerSummarySchema, type PluginProtocolEnvelope, PluginSessionDescriptor, PluginSessionDescriptorSchema, type PluginToHostEnvelope, PluginToHostEnvelopeSchema, type PluginToHostPayload, PluginToHostPayloadSchema, ReducerSeatProjectionBundle, RuntimeJson, RuntimeTargetOptions, SeatBoardTopology, SeatCardId, SeatFrameSchema, SeatProjectionBundleSchema, SeatSpaceRef, SeatTileRef, type ServerGameplayFrame, ServerGameplayFrameSchema, SessionResumeFrameSchema, SessionSnapshotFrameSchema, SimultaneousPhaseSnapshotSchema, SourceSnapshot, type SubmitInteractionCommand, SubmitInteractionCommandSchema, SystemActionEventSchema, TargetOptions, type ViewportSurface, type ViewportTransform, type WheelInput, Zone, ZoneHandlesSnapshotSchema, ZoneHostId, boardFeature, canonicalizePluginRuntimeJson, computePluginActionSetVersion, createGameInstance, createGestureRecognizer, createPluginProtocolEnvelopeSchema, cssEasing, digestPluginCommandRequest, digestPluginGameplayFrame, digestPluginRuntimeJson, dragFeature, encodeCanonicalPluginRuntimeJson, exponentialOut, fanLayout, handFan, handFanPresets, handFanTiming, handFeature, hostSource, iframeSource, liftFanCard, magneticDropPoint, materializePluginGameplayFrame, originsFeature, panZoomFeature, parseHostToPluginEnvelope, parsePluginGameplayFrame, parsePluginSessionDescriptor, parsePluginToHostEnvelope, staticSource };

package/dist/index.js

@@ -71,7 +71,7 @@ import {
 } from "./chunk-ES74C2IN.js";
 
 // src/package-set.ts
-var DREAMBOARD_SDK_VERSION = true ? "0.5.0-alpha.13" : "0.0.0-development";
+var DREAMBOARD_SDK_VERSION = true ? "0.5.0-alpha.15" : "0.0.0-development";
 var DREAMBOARD_SDK_PACKAGES = {
   "@dreamboard-games/sdk": DREAMBOARD_SDK_VERSION
 };
@@ -1578,6 +1578,151 @@ function liftFanCard(card, distance) {
     rotate: card.rotate
   };
 }
+
+// src/headless/hand-fan.ts
+var handFanPresets = {
+  /** Whole resting cards; focusing enlarges the card. */
+  open: {
+    tuck: 0,
+    focusScale: 2,
+    focusMaxHeight: 0.55,
+    push: [0.29, 0.19, 0.1],
+    exposed: 0.35
+  },
+  /**
+   * Larger cards tucked below the bottom edge and spaced like a dealt hand;
+   * focusing mostly reveals the card.
+   */
+  tucked: {
+    spacing: 0.75,
+    tuck: 0.4,
+    focusScale: 1.4,
+    focusMaxHeight: 0.4,
+    push: [0.29, 0.19, 0.1],
+    exposed: 0.35
+  },
+  /** Coarse pointers: a shallower tuck and wider strips to tap. */
+  touch: {
+    spacing: 0.75,
+    tuck: 0.2,
+    focusScale: 1.6,
+    focusMaxHeight: 0.5,
+    push: [0.35, 0.2, 0.1],
+    exposed: 0.45
+  }
+};
+function handFan({
+  count,
+  width,
+  cardWidth,
+  cardHeight,
+  focused = -1,
+  visible,
+  windowHeight = Infinity,
+  room = Infinity,
+  options
+}) {
+  const o = { ...handFanPresets.open, ...options };
+  const fan = fanLayout({
+    count,
+    width,
+    cardWidth,
+    cardHeight,
+    angle: o.angle,
+    maxSpread: o.maxSpread,
+    step: o.spacing === void 0 ? void 0 : o.spacing * cardWidth
+  });
+  const band = Math.max(0, fan.height - o.tuck * cardHeight);
+  const view = visible ?? {
+    left: (fan.width - width) / 2,
+    width
+  };
+  const exposed = cardWidth * o.exposed;
+  const largest = Math.max(
+    cardWidth,
+    Math.min(
+      cardWidth * o.focusScale,
+      windowHeight * o.focusMaxHeight * cardWidth / cardHeight,
+      room * cardWidth / cardHeight,
+      view.width
+    )
+  );
+  const headroom = Math.max(0, largest * cardHeight / cardWidth - band);
+  const cards = fan.cards.map((card, index) => ({
+    ...card,
+    scale: 1,
+    layer: index
+  }));
+  if (focused < 0 || focused >= count)
+    return { cards, width: fan.width, height: band, headroom };
+  const leftStrip = focused > 0 ? exposed : 0;
+  const rightStrip = focused < count - 1 ? exposed : 0;
+  const face = Math.max(
+    cardWidth,
+    Math.min(largest, view.width - leftStrip - rightStrip)
+  );
+  const scale = face / cardWidth;
+  const half = face / 2;
+  const centre = Math.max(
+    view.left + leftStrip + half,
+    Math.min(
+      view.left + view.width - rightStrip - half,
+      cards[focused].x + cardWidth / 2
+    )
+  );
+  cards[focused] = {
+    x: centre - cardWidth / 2,
+    y: band - cardHeight * (scale + 1) / 2,
+    rotate: 0,
+    scale,
+    layer: count
+  };
+  const extra = Math.max(0, half - cardWidth / 2);
+  const reach = o.push.length;
+  for (const direction of [-1, 1]) {
+    let previous = centre;
+    for (let distance = 1, index = focused + direction; index >= 0 && index < count; distance++, index += direction) {
+      const card = cards[index];
+      const shift = (o.push[distance - 1] ?? 0) * cardWidth + (reach ? extra * Math.max(0, 1 - (distance - 1) / reach) : 0);
+      const desired = card.x + cardWidth / 2 + direction * shift;
+      const angle = card.rotate * Math.PI / 180;
+      const halfWidth = (cardWidth * Math.cos(angle) + cardHeight * Math.abs(Math.sin(angle))) / 2;
+      const middleHalfWidth = cardWidth * Math.cos(angle) / 2;
+      const clearance = distance === 1 ? Math.max(exposed, half - middleHalfWidth + exposed) : exposed;
+      const boundary = direction === 1 && distance > 1 ? Math.max(previous + clearance, centre + half + exposed + halfWidth) : previous + direction * clearance;
+      let next = direction === 1 ? Math.max(desired, boundary) : Math.min(desired, boundary);
+      if (distance === 1)
+        next = direction === 1 ? Math.min(
+          next,
+          view.left + view.width - middleHalfWidth,
+          centre + half + middleHalfWidth
+        ) : Math.max(
+          next,
+          view.left + middleHalfWidth,
+          centre - half - middleHalfWidth
+        );
+      cards[index] = { ...card, x: next - cardWidth / 2 };
+      previous = next;
+    }
+  }
+  return { cards, width: fan.width, height: band, headroom };
+}
+function exponentialOut(progress) {
+  return (1 - Math.exp(-4.5 * progress)) / (1 - Math.exp(-4.5));
+}
+var handFanTiming = {
+  /** The focused face rises: 90% in about 45ms. */
+  focus: { duration: 0.09, ease: exponentialOut },
+  /** Sideways travel, neighbours and returning cards: 90% in about 300ms. */
+  settle: { duration: 0.6, ease: exponentialOut }
+};
+function cssEasing(ease, samples = 24) {
+  const points = Array.from(
+    { length: samples + 1 },
+    (_, index) => Number(ease(index / samples).toFixed(4))
+  );
+  return `linear(${points.join(", ")})`;
+}
 export {
   AmbiguousTargetError,
   AuthAcceptedFrameSchema,
@@ -1633,12 +1778,17 @@ export {
   createGameInstance,
   createGestureRecognizer,
   createPluginProtocolEnvelopeSchema,
+  cssEasing,
   digestPluginCommandRequest,
   digestPluginGameplayFrame,
   digestPluginRuntimeJson,
   dragFeature,
   encodeCanonicalPluginRuntimeJson,
+  exponentialOut,
   fanLayout,
+  handFan,
+  handFanPresets,
+  handFanTiming,
   handFeature,
   hostSource,
   iframeSource,