@dreamboard-games/sdk 0.2.0 → 0.2.1-alpha.1

package/src/runtime-internal/hooks/useBoardInteractions.ts

@@ -30,6 +30,12 @@ import {
   shouldRouteInteractionPending,
 } from "../utils/interaction-router.js";
 import { isInteractionAvailable } from "../utils/interaction-status.js";
+import {
+  createGameplayActuatorAttributes,
+  type BrowserInteractionAttributeMap,
+} from "../../browser-interaction/index.js";
+import { interactionDraftDigestForValues } from "../utils/interaction-draft-digest.js";
+import { gameplayCandidateMetadata } from "../utils/browser-interaction-effects.js";
 
 export type BoardEligibleTargets = Readonly<
   Record<BoardTargetKind, ReadonlySet<string>>
@@ -379,7 +385,7 @@ export function useBoardInteractions<I extends string = string>(
           return [];
         }
         if (!isInteractionAvailable(descriptor)) return [];
-        const draft = store.getDraft(descriptor.interactionKey);
+        const draft = drafts[descriptor.interactionKey] ?? {};
         const inputKey = inputKeyForTarget(
           descriptor,
           targetKind,
@@ -388,14 +394,7 @@ export function useBoardInteractions<I extends string = string>(
         );
         if (!inputKey) return [];
         const input = inputByTarget(descriptor, targetKind, targetId, draft);
-        if (
-          input &&
-          !isTargetSelectable(
-            input,
-            store.getDraft(descriptor.interactionKey),
-            targetId,
-          )
-        ) {
+        if (input && !isTargetSelectable(input, draft, targetId)) {
           return [];
         }
         const targets = eligibleTargetsForInput(descriptor, inputKey, draft);
@@ -410,7 +409,7 @@ export function useBoardInteractions<I extends string = string>(
       });
       return matches;
     },
-    [armedIds, interactions, store],
+    [armedIds, drafts, interactions],
   );
 
   const selectByKind = useCallback(
@@ -486,9 +485,19 @@ export function useBoardInteractions<I extends string = string>(
           ? candidates.map((candidate) => candidate.descriptor.interactionKey)
           : undefined,
         unavailableReason: candidateUnavailableReason(selected, conflict),
+        browserAttributes: selected
+          ? boardTargetBrowserAttributes({
+              descriptor: selected.descriptor,
+              inputKey: selected.inputKey,
+              targetKind,
+              targetId,
+              enabled: eligible && !!controllingPlayerId,
+              draft: drafts[selected.descriptor.interactionKey] ?? {},
+            })
+          : undefined,
       };
     },
-    [controllingPlayerId, pendingInteractionKey, resolveTargetMatches],
+    [controllingPlayerId, drafts, pendingInteractionKey, resolveTargetMatches],
   );
 
   const targetLayers = useMemo(() => {
@@ -634,6 +643,59 @@ interface MatchingDescriptor<I extends string> {
   armed: boolean;
 }
 
+const GAMEPLAY_BROWSER_SCOPE_ID = "runtime";
+
+function boardTargetBrowserAttributes({
+  descriptor,
+  inputKey,
+  targetKind,
+  targetId,
+  enabled,
+  draft,
+}: {
+  descriptor: InteractionDescriptor;
+  inputKey: string;
+  targetKind: BoardTargetKind;
+  targetId: string;
+  enabled: boolean;
+  draft: Readonly<Record<string, unknown>>;
+}): BrowserInteractionAttributeMap {
+  return createGameplayActuatorAttributes({
+    scopeId: GAMEPLAY_BROWSER_SCOPE_ID,
+    interactionKey: descriptor.interactionKey,
+    interactionId: descriptor.interactionId,
+    intent: "select",
+    enabled,
+    actuatorKind: "click",
+    actuatorId: `board:${targetKind}:${targetId}`,
+    ...(descriptor.descriptorDigest !== undefined
+      ? { descriptorDigest: descriptor.descriptorDigest }
+      : {}),
+    ...(descriptor.draftDigest !== undefined
+      ? { draftDigest: interactionDraftDigestForValues(descriptor, draft) }
+      : {}),
+    inputKey,
+    candidateValue: targetId,
+    candidateState: isBoardTargetSelected(draft[inputKey], targetId)
+      ? "selected"
+      : "unselected",
+    semanticEffects: gameplayCandidateMetadata({
+      descriptor,
+      draftValues: draft,
+      inputKey,
+      candidateValue: targetId,
+      intent: "select",
+    }).semanticEffects,
+  });
+}
+
+function isBoardTargetSelected(value: unknown, targetId: string): boolean {
+  if (Array.isArray(value)) {
+    return value.some((item) => String(item) === targetId);
+  }
+  return value !== undefined && String(value) === targetId;
+}
+
 function selectDispatchCandidate<I extends string>(
   matches: ReadonlyArray<MatchingDescriptor<I>>,
   targetKind: BoardTargetKind,

package/src/runtime-internal/primitives/board.tsx

@@ -40,6 +40,12 @@ import { runInteractionAction } from "./interaction-submit.js";
 import { useGameActionError } from "./game.js";
 import { isInteractionAvailable } from "../utils/interaction-status.js";
 import { useInteractionUiStore } from "../context/InteractionDraftContext.js";
+import {
+  createGameplayActuatorAttributes,
+  type BrowserInteractionAttributeMap,
+} from "../../browser-interaction/index.js";
+import { interactionDraftDigestForValues } from "../utils/interaction-draft-digest.js";
+import { gameplayCandidateMetadata } from "../utils/browser-interaction-effects.js";
 
 type BoardContextValue = BoardInteractionsContext;
 
@@ -312,6 +318,7 @@ function UnambiguousBoardTarget({
   return renderPrimitive("button", {
     type: "button",
     ...props,
+    ...targetState.browserAttributes,
     children,
     disabled: isDisabled,
     "aria-disabled": isDisabled,
@@ -377,9 +384,20 @@ function ExplicitBoardTarget({
     (eligibleTargets ?? inputDescriptor.domain.eligibleTargets).includes(value);
   const isDisabled =
     disabled ?? (!isInteractionAvailable(descriptor) || !eligible);
+  const browserAttributes = inputKey
+    ? boardTargetBrowserAttributes({
+        descriptor,
+        inputKey,
+        targetKind: kind,
+        targetId: value,
+        enabled: !isDisabled,
+        draft,
+      })
+    : undefined;
   return renderPrimitive("button", {
     type: "button",
     ...props,
+    ...browserAttributes,
     children,
     disabled: isDisabled,
     "aria-disabled": isDisabled,
@@ -447,6 +465,59 @@ function resolveExtraInputs(
     : (extraInputs ?? {});
 }
 
+const GAMEPLAY_BROWSER_SCOPE_ID = "runtime";
+
+function boardTargetBrowserAttributes({
+  descriptor,
+  inputKey,
+  targetKind,
+  targetId,
+  enabled,
+  draft,
+}: {
+  descriptor: InteractionDescriptor;
+  inputKey: string;
+  targetKind: BoardTargetKind;
+  targetId: string;
+  enabled: boolean;
+  draft: Readonly<Record<string, unknown>>;
+}): BrowserInteractionAttributeMap {
+  return createGameplayActuatorAttributes({
+    scopeId: GAMEPLAY_BROWSER_SCOPE_ID,
+    interactionKey: descriptor.interactionKey,
+    interactionId: descriptor.interactionId,
+    intent: "select",
+    enabled,
+    actuatorKind: "click",
+    actuatorId: `board:${targetKind}:${targetId}`,
+    ...(descriptor.descriptorDigest !== undefined
+      ? { descriptorDigest: descriptor.descriptorDigest }
+      : {}),
+    ...(descriptor.draftDigest !== undefined
+      ? { draftDigest: interactionDraftDigestForValues(descriptor, draft) }
+      : {}),
+    inputKey,
+    candidateValue: targetId,
+    candidateState: isBoardTargetSelected(draft[inputKey], targetId)
+      ? "selected"
+      : "unselected",
+    semanticEffects: gameplayCandidateMetadata({
+      descriptor,
+      draftValues: draft,
+      inputKey,
+      candidateValue: targetId,
+      intent: "select",
+    }).semanticEffects,
+  });
+}
+
+function isBoardTargetSelected(value: unknown, targetId: string): boolean {
+  if (Array.isArray(value)) {
+    return value.some((item) => String(item) === targetId);
+  }
+  return value !== undefined && String(value) === targetId;
+}
+
 export const Board = {
   Root: BoardRoot,
   State: BoardState,

package/src/runtime-internal/primitives/interaction.tsx

@@ -34,6 +34,7 @@ import {
   isResolvedTargetDomain,
   isTargetDomain,
   isManyTargetSelectable,
+  resolveInputDomain,
 } from "../utils/interaction-inputs.js";
 import {
   getInteractionDraftReadiness,
@@ -45,12 +46,25 @@ import {
   interactionUnavailableReason,
   isInteractionAvailable,
 } from "../utils/interaction-status.js";
+import {
+  gameplayCandidateMetadata,
+  gameplayPreparationPatternsForDescriptor,
+  gameplayScalarFillMetadata,
+  gameplaySubmitMetadata,
+} from "../utils/browser-interaction-effects.js";
 import { interactionLabel } from "../utils/interaction-labels.js";
 import {
   composeEventHandlers,
   renderPrimitive,
   type PrimitiveCommonProps,
 } from "./primitive-props.js";
+import {
+  createGameplayActuatorAttributes,
+  createGameplayInteractionRootAttributes,
+  type BrowserInteractionAttributeMap,
+  type GameplayActuatorAttributesInput,
+  type GameplayBrowserInteractionIntent,
+} from "../../browser-interaction/index.js";
 import {
   BoundInteractionForm,
   castInteractionDraft,
@@ -92,6 +106,56 @@ function humanizeInteraction(value: string): string {
     .replace(/^./, (first: string) => first.toUpperCase());
 }
 
+const GAMEPLAY_BROWSER_SCOPE_ID = "runtime";
+
+function gameplayActuatorAttributes({
+  descriptor,
+  inputKey,
+  intent,
+  candidateValue,
+  candidateState,
+  semanticEffects,
+  acceptedEffectPatterns,
+  preparationPatterns,
+  enabled,
+  actuatorKind,
+  actuatorId,
+}: {
+  descriptor: InteractionDescriptor;
+  inputKey?: string;
+  intent: GameplayBrowserInteractionIntent;
+  candidateValue?: unknown;
+  candidateState?: "selected" | "unselected" | "mixed";
+  semanticEffects?: GameplayActuatorAttributesInput["semanticEffects"];
+  acceptedEffectPatterns?: GameplayActuatorAttributesInput["acceptedEffectPatterns"];
+  preparationPatterns?: GameplayActuatorAttributesInput["preparationPatterns"];
+  enabled: boolean;
+  actuatorKind: GameplayActuatorAttributesInput["actuatorKind"];
+  actuatorId: string;
+}): BrowserInteractionAttributeMap {
+  return createGameplayActuatorAttributes({
+    scopeId: GAMEPLAY_BROWSER_SCOPE_ID,
+    interactionKey: descriptor.interactionKey,
+    interactionId: descriptor.interactionId,
+    intent,
+    enabled,
+    actuatorKind,
+    actuatorId,
+    ...(descriptor.descriptorDigest !== undefined
+      ? { descriptorDigest: descriptor.descriptorDigest }
+      : {}),
+    ...(descriptor.draftDigest !== undefined
+      ? { draftDigest: descriptor.draftDigest }
+      : {}),
+    ...(inputKey !== undefined ? { inputKey } : {}),
+    ...(candidateValue !== undefined ? { candidateValue } : {}),
+    ...(candidateState !== undefined ? { candidateState } : {}),
+    ...(semanticEffects !== undefined ? { semanticEffects } : {}),
+    ...(acceptedEffectPatterns !== undefined ? { acceptedEffectPatterns } : {}),
+    ...(preparationPatterns !== undefined ? { preparationPatterns } : {}),
+  });
+}
+
 export function useInteractionPrimitiveContext(): InteractionContextValue {
   const value = useContext(InteractionContext);
   if (!value) {
@@ -155,9 +219,30 @@ function ResolvedInteractionRoot({
     () => ({ interaction, descriptor, handle }),
     [descriptor, handle, interaction],
   );
+  const available = isInteractionAvailable(descriptor);
+  const rootAttributes = createGameplayInteractionRootAttributes({
+    scopeId: GAMEPLAY_BROWSER_SCOPE_ID,
+    interactionKey: descriptor.interactionKey,
+    interactionId: descriptor.interactionId,
+    ...(descriptor.descriptorDigest !== undefined
+      ? { descriptorDigest: descriptor.descriptorDigest }
+      : {}),
+    ...(descriptor.draftDigest !== undefined
+      ? { draftDigest: descriptor.draftDigest }
+      : {}),
+    readiness: available
+      ? handle.isReady
+        ? "ready"
+        : "blocked"
+      : "unavailable",
+  });
   return (
     <InteractionContext.Provider value={value}>
-      {children}
+      {renderPrimitive("span", {
+        ...rootAttributes,
+        style: { display: "contents" },
+        children,
+      })}
     </InteractionContext.Provider>
   );
 }
@@ -447,6 +532,19 @@ export function InteractionTrigger({
   return renderPrimitive("button", {
     type: "button",
     ...props,
+    ...(descriptor
+      ? gameplayActuatorAttributes({
+          descriptor,
+          intent: "arm",
+          enabled: !isDisabled,
+          actuatorKind: "click",
+          actuatorId: "primitive-trigger",
+          preparationPatterns: gameplayPreparationPatternsForDescriptor(
+            descriptor,
+            (handle?.values ?? {}) as Readonly<Record<string, unknown>>,
+          ),
+        })
+      : {}),
     disabled: isDisabled,
     "aria-disabled": isDisabled,
     "data-dreamboard-interaction-trigger": "",
@@ -595,6 +693,9 @@ export function InteractionSubmit({
   const gameActionError = useGameActionError();
   const isSubmitting = handle?.status === "submitting";
   const hasExplicitParams = params !== undefined;
+  const submitMetadata = descriptor
+    ? gameplaySubmitMetadata({ descriptor, explicitParams: hasExplicitParams })
+    : null;
   const available = isInteractionAvailable(descriptor);
   const isDisabled =
     disabled === true ||
@@ -604,6 +705,16 @@ export function InteractionSubmit({
   return renderPrimitive("button", {
     type: "button",
     ...props,
+    ...(descriptor
+      ? gameplayActuatorAttributes({
+          descriptor,
+          intent: submitMetadata?.intent ?? "submit",
+          enabled: !isDisabled,
+          actuatorKind: "click",
+          actuatorId: "primitive-submit",
+          semanticEffects: submitMetadata?.semanticEffects,
+        })
+      : {}),
     disabled: isDisabled,
     "aria-disabled": isDisabled,
     "data-dreamboard-interaction-submit": "",
@@ -650,9 +761,35 @@ export function InteractionInput({
   const { descriptor, handle } = useInteractionPrimitiveContext();
   const value = handle?.draft[name];
   const isDisabled = disabled === true || !isInteractionAvailable(descriptor);
+  const inputDescriptor = descriptor ? inputByKey(descriptor, name) : undefined;
+  const resolvedInputDescriptor =
+    inputDescriptor && handle
+      ? resolveInputDomain(
+          inputDescriptor,
+          handle.values as Readonly<Record<string, unknown>>,
+        )
+      : undefined;
+  const scalarFillMetadata =
+    resolvedInputDescriptor?.domain.type === "boundedNumber"
+      ? gameplayScalarFillMetadata({
+          inputKey: name,
+          domain: resolvedInputDescriptor.domain,
+        })
+      : undefined;
   return renderPrimitive("input", {
     ...props,
     name,
+    ...(descriptor
+      ? gameplayActuatorAttributes({
+          descriptor,
+          inputKey: name,
+          intent: "fill",
+          enabled: !isDisabled,
+          actuatorKind: "fill",
+          actuatorId: `primitive-input:${name}`,
+          acceptedEffectPatterns: scalarFillMetadata?.acceptedEffectPatterns,
+        })
+      : {}),
     disabled: isDisabled,
     "aria-disabled": isDisabled,
     "data-dreamboard-interaction-input": "",
@@ -850,6 +987,28 @@ export function InteractionCardInput<
     type: "button",
     ...props,
     children: renderedChildren,
+    ...(descriptor
+      ? gameplayActuatorAttributes({
+          descriptor,
+          inputKey: input,
+          intent: selection?.mode === "many" ? "toggle" : "select",
+          candidateValue: cardId,
+          candidateState: isSelected ? "selected" : "unselected",
+          enabled: !isDisabled,
+          actuatorKind: "click",
+          actuatorId: `primitive-card:${input}:${cardId ?? "missing"}`,
+          semanticEffects:
+            cardId !== undefined
+              ? gameplayCandidateMetadata({
+                  descriptor,
+                  draftValues: liveDraft,
+                  inputKey: input,
+                  candidateValue: cardId,
+                  intent: selection?.mode === "many" ? "toggle" : "select",
+                }).semanticEffects
+              : undefined,
+        })
+      : {}),
     disabled: isDisabled,
     "aria-disabled": isDisabled,
     "aria-pressed": isSelected,

package/src/runtime-internal/types/plugin-state.ts

@@ -388,6 +388,12 @@ interface InteractionDescriptorBase<Key extends string = string> {
   interactionId: string;
   /** Draft commit policy. Always materialized by the trusted reducer bundle. */
   commit: InteractionCommitPolicy;
+  /** Canonical descriptor digest used by browser replay/protocol tooling when projected by the host. */
+  descriptorDigest?: string;
+  /** Explicit authoring/runtime actor seat used by browser replay draft digests. */
+  actorSeat?: number;
+  /** Canonical draft digest used by browser replay/protocol tooling when projected by the host. */
+  draftDigest?: string;
   /** Source zone id for zone-scoped interactions (e.g., cardInput). */
   zoneId?: string;
   /** Source zone ids for zone-scoped interactions that span multiple zones. */