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

package/src/runtime-internal/components/InteractionForm.tsx

@@ -20,6 +20,14 @@ import {
   useTheme,
   useThemeCssVars,
 } from "../../ui.js";
+import {
+  createGameplayActuatorAttributes,
+  createGameplayInteractionRootAttributes,
+  type GameplayActuatorAttributesInput,
+  type BrowserInteractionAttributeMap,
+  type BrowserInteractionCandidateState,
+  type GameplayBrowserInteractionIntent,
+} from "../../browser-interaction/index.js";
 import type {
   DraftValidation,
   InteractionHandle,
@@ -40,7 +48,16 @@ import {
   resolveInteractionInputs,
   toggleManyValue,
 } from "../utils/interaction-inputs.js";
+import { interactionDraftDigestForValues } from "../utils/interaction-draft-digest.js";
 import { isInteractionAvailable } from "../utils/interaction-status.js";
+import {
+  gameplayCandidateMetadata,
+  gameplayPreparationPatternsForDescriptor,
+  gameplayResourceMetadata,
+  gameplayScalarFillMetadata,
+  gameplayScalarStepMetadata,
+  gameplaySubmitMetadata,
+} from "../utils/browser-interaction-effects.js";
 import { useChromeSuppression, ThemedButton } from "../../ui.js";
 
 export interface InteractionFieldRenderProps<
@@ -163,6 +180,92 @@ export interface InteractionFormProps<
 }
 
 const EMPTY_FIELD_ERRORS: readonly string[] = [];
+const GAMEPLAY_BROWSER_SCOPE_ID = "runtime";
+
+function gameplayInteractionRootAttributes({
+  descriptor,
+  draftValues,
+  ready,
+  available,
+}: {
+  descriptor: InteractionDescriptor;
+  draftValues?: Readonly<Record<string, unknown>>;
+  ready: boolean;
+  available: boolean;
+}): BrowserInteractionAttributeMap {
+  return createGameplayInteractionRootAttributes({
+    scopeId: GAMEPLAY_BROWSER_SCOPE_ID,
+    interactionKey: descriptor.interactionKey,
+    interactionId: descriptor.interactionId,
+    ...(descriptor.descriptorDigest !== undefined
+      ? { descriptorDigest: descriptor.descriptorDigest }
+      : {}),
+    ...(descriptor.draftDigest !== undefined
+      ? {
+          draftDigest: interactionDraftDigestForValues(
+            descriptor,
+            draftValues ?? {},
+          ),
+        }
+      : {}),
+    readiness: available ? (ready ? "ready" : "blocked") : "unavailable",
+  });
+}
+
+function gameplayActuatorAttributes({
+  descriptor,
+  inputKey,
+  intent,
+  candidateValue,
+  candidateState,
+  semanticEffects,
+  acceptedEffectPatterns,
+  preparationPatterns,
+  draftValues,
+  enabled,
+  actuatorKind,
+  actuatorId,
+}: {
+  descriptor: InteractionDescriptor;
+  inputKey?: string;
+  intent: GameplayBrowserInteractionIntent;
+  candidateValue?: unknown;
+  candidateState?: BrowserInteractionCandidateState;
+  semanticEffects?: GameplayActuatorAttributesInput["semanticEffects"];
+  acceptedEffectPatterns?: GameplayActuatorAttributesInput["acceptedEffectPatterns"];
+  preparationPatterns?: GameplayActuatorAttributesInput["preparationPatterns"];
+  draftValues?: Readonly<Record<string, unknown>>;
+  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: interactionDraftDigestForValues(
+            descriptor,
+            draftValues ?? {},
+          ),
+        }
+      : {}),
+    ...(inputKey !== undefined ? { inputKey } : {}),
+    ...(candidateValue !== undefined ? { candidateValue } : {}),
+    ...(candidateState !== undefined ? { candidateState } : {}),
+    ...(semanticEffects !== undefined ? { semanticEffects } : {}),
+    ...(acceptedEffectPatterns !== undefined ? { acceptedEffectPatterns } : {}),
+    ...(preparationPatterns !== undefined ? { preparationPatterns } : {}),
+  });
+}
 
 export function InteractionForm<
   Params extends InteractionParamsShape = InteractionParamsShape,
@@ -227,6 +330,34 @@ export function InteractionForm<
   ];
   const isDisabled = disabled || pending || !isInteractionAvailable(descriptor);
   const useAccordion = accordion && visibleInputs.length > 0;
+  const rootBrowserAttributes = gameplayInteractionRootAttributes({
+    descriptor,
+    draftValues: handle.values as Readonly<Record<string, unknown>>,
+    ready: handle.isReady,
+    available: !isDisabled,
+  });
+  const armBrowserAttributes = gameplayActuatorAttributes({
+    descriptor,
+    draftValues: handle.values as Readonly<Record<string, unknown>>,
+    intent: "arm",
+    enabled: !isDisabled,
+    actuatorKind: "click",
+    actuatorId: "arm",
+    preparationPatterns: gameplayPreparationPatternsForDescriptor(
+      descriptor,
+      handle.values as Readonly<Record<string, unknown>>,
+    ),
+  });
+  const submitMetadata = gameplaySubmitMetadata({ descriptor });
+  const submitBrowserAttributes = gameplayActuatorAttributes({
+    descriptor,
+    draftValues: handle.values as Readonly<Record<string, unknown>>,
+    intent: submitMetadata.intent,
+    enabled: !isDisabled && handle.isReady,
+    actuatorKind: "click",
+    actuatorId: "submit",
+    semanticEffects: submitMetadata.semanticEffects,
+  });
 
   useEffect(() => {
     setAccordionOpen(defaultOpen);
@@ -391,6 +522,7 @@ export function InteractionForm<
                 size="sm"
                 disabled={isDisabled}
                 className="h-9 px-3 text-sm"
+                {...submitBrowserAttributes}
                 {...buttonProps}
               >
                 {pending
@@ -408,6 +540,7 @@ export function InteractionForm<
           size="sm"
           disabled={isDisabled}
           className="h-9 px-3 text-sm"
+          {...submitBrowserAttributes}
         >
           {pending ? "Submitting..." : (submitLabel ?? fallbackLabel)}
         </ThemedButton>
@@ -429,6 +562,7 @@ export function InteractionForm<
       data-interaction-id={descriptor.interactionId}
       onSubmit={(event) => void submit(event)}
       style={containerStyle}
+      {...rootBrowserAttributes}
     >
       {useAccordion ? (
         <AccordionPrimitive.Root
@@ -442,6 +576,7 @@ export function InteractionForm<
           <AccordionPrimitive.Item value="fields">
             <AccordionPrimitive.Header style={{ margin: 0 }}>
               <AccordionPrimitive.Trigger
+                {...armBrowserAttributes}
                 style={{
                   alignItems: "center",
                   appearance: "none",
@@ -543,6 +678,24 @@ function createInteractionInputSlot<
       kind === "card"
         ? { "data-dreamboard-interaction-card-slot": "" }
         : { "data-dreamboard-interaction-target-slot": "" };
+    const browserAttributes = gameplayActuatorAttributes({
+      descriptor,
+      draftValues: handle.values as Readonly<Record<string, unknown>>,
+      inputKey: input.key,
+      intent: selection?.mode === "many" ? "toggle" : "select",
+      candidateValue: targetValue,
+      candidateState: selected ? "selected" : "unselected",
+      enabled: !isDisabled,
+      actuatorKind: "click",
+      actuatorId: `${kind}:${input.key}:${targetValue}`,
+      semanticEffects: gameplayCandidateMetadata({
+        descriptor,
+        draftValues: handle.values as Readonly<Record<string, unknown>>,
+        inputKey: input.key,
+        candidateValue: targetValue,
+        intent: selection?.mode === "many" ? "toggle" : "select",
+      }).semanticEffects,
+    });
     return (
       <button
         type="button"
@@ -556,6 +709,7 @@ function createInteractionInputSlot<
         data-selected={selected || undefined}
         data-disabled={isDisabled || undefined}
         {...dataAttribute}
+        {...browserAttributes}
         {...buttonProps}
         onClick={() => {
           if (isDisabled) return;
@@ -588,6 +742,26 @@ function createInteractionInputSlot<
     Default: ({ children }) => {
       const hasDefault = "defaultValue" in input;
       const isDisabled = disabled || !hasDefault;
+      const browserAttributes = gameplayActuatorAttributes({
+        descriptor,
+        draftValues: handle.values as Readonly<Record<string, unknown>>,
+        inputKey: input.key,
+        intent: "select",
+        candidateValue: input.defaultValue,
+        candidateState: "unselected",
+        enabled: !isDisabled,
+        actuatorKind: "click",
+        actuatorId: `default:${input.key}`,
+        semanticEffects: hasDefault
+          ? gameplayCandidateMetadata({
+              descriptor,
+              draftValues: handle.values as Readonly<Record<string, unknown>>,
+              inputKey: input.key,
+              candidateValue: input.defaultValue,
+              intent: "select",
+            }).semanticEffects
+          : undefined,
+      });
       return (
         <button
           type="button"
@@ -596,6 +770,7 @@ function createInteractionInputSlot<
           data-dreamboard-interaction-default-slot=""
           data-input-name={input.key}
           data-disabled={isDisabled || undefined}
+          {...browserAttributes}
           onClick={() => {
             if (isDisabled) return;
             handle.setInput(input.key, input.defaultValue as Params[Key]);
@@ -869,6 +1044,8 @@ function ChoiceField<
   Params extends InteractionParamsShape,
   Key extends keyof Params & string,
 >({
+  descriptor,
+  handle,
   input,
   value,
   setValue,
@@ -903,15 +1080,38 @@ function ChoiceField<
         >
           {choices.map((choice) => {
             const selected = value === choice.value;
+            const isDisabled = disabled || choice.disabled;
             return (
               <ThemedButton
                 key={choiceRenderKey(choice)}
                 type="button"
                 variant={selected ? "primary" : "secondary"}
                 size="sm"
-                disabled={disabled || choice.disabled}
+                disabled={isDisabled}
                 aria-pressed={selected}
                 title={choice.disabledReason ?? choice.description}
+                {...gameplayActuatorAttributes({
+                  descriptor,
+                  draftValues: handle.values as Readonly<
+                    Record<string, unknown>
+                  >,
+                  inputKey: input.key,
+                  intent: "select",
+                  candidateValue: choice.value,
+                  candidateState: selected ? "selected" : "unselected",
+                  enabled: !isDisabled,
+                  actuatorKind: "click",
+                  actuatorId: `choice:${input.key}:${choiceRenderKey(choice)}`,
+                  semanticEffects: gameplayCandidateMetadata({
+                    descriptor,
+                    draftValues: handle.values as Readonly<
+                      Record<string, unknown>
+                    >,
+                    inputKey: input.key,
+                    candidateValue: choice.value,
+                    intent: "select",
+                  }).semanticEffects,
+                })}
                 onClick={() => setValue(choice.value as Params[Key])}
                 className="h-8 px-3 text-sm"
               >
@@ -937,7 +1137,24 @@ function ChoiceField<
           setValue(decodeChoiceSelectValue(next) as Params[Key])
         }
       >
-        <SelectTrigger id={controlId} size="sm" className="w-full bg-white">
+        <SelectTrigger
+          id={controlId}
+          size="sm"
+          className="w-full bg-white"
+          {...gameplayActuatorAttributes({
+            descriptor,
+            draftValues: handle.values as Readonly<Record<string, unknown>>,
+            inputKey: input.key,
+            intent: "reveal",
+            enabled: !disabled,
+            actuatorKind: "click",
+            actuatorId: `choice-reveal:${input.key}`,
+            preparationPatterns: gameplayPreparationPatternsForDescriptor(
+              { inputs: [input] },
+              handle.values as Readonly<Record<string, unknown>>,
+            ),
+          })}
+        >
           <span data-slot="select-value">
             {selectedChoice ? (
               <ChoiceOptionLabel choice={selectedChoice} />
@@ -960,6 +1177,27 @@ function ChoiceField<
               value={choiceRenderKey(choice)}
               textValue={choice.label}
               disabled={choice.disabled}
+              {...gameplayActuatorAttributes({
+                descriptor,
+                draftValues: handle.values as Readonly<Record<string, unknown>>,
+                inputKey: input.key,
+                intent: "select",
+                candidateValue: choice.value,
+                candidateState:
+                  value === choice.value ? "selected" : "unselected",
+                enabled: !disabled && !choice.disabled,
+                actuatorKind: "click",
+                actuatorId: `choice:${input.key}:${choiceRenderKey(choice)}`,
+                semanticEffects: gameplayCandidateMetadata({
+                  descriptor,
+                  draftValues: handle.values as Readonly<
+                    Record<string, unknown>
+                  >,
+                  inputKey: input.key,
+                  candidateValue: choice.value,
+                  intent: "select",
+                }).semanticEffects,
+              })}
             >
               <ChoiceOptionLabel choice={choice} />
             </SelectItem>
@@ -975,6 +1213,8 @@ function ChoiceListField<
   Params extends InteractionParamsShape,
   Key extends keyof Params & string,
 >({
+  descriptor,
+  handle,
   input,
   value,
   setValue,
@@ -1028,19 +1268,37 @@ function ChoiceListField<
         {(domain.choices ?? []).map((choice) => {
           const value = choice.value as string;
           const checked = selected.has(value);
+          const isDisabled =
+            disabled || choice.disabled || (!checked && selected.size >= max);
           return (
             <ThemedButton
               key={value}
               type="button"
               variant={checked ? "primary" : "secondary"}
               size="sm"
-              disabled={
-                disabled ||
-                choice.disabled ||
-                (!checked && selected.size >= max)
-              }
+              disabled={isDisabled}
               aria-pressed={checked}
               title={choice.disabledReason ?? choice.description}
+              {...gameplayActuatorAttributes({
+                descriptor,
+                draftValues: handle.values as Readonly<Record<string, unknown>>,
+                inputKey: input.key,
+                intent: "toggle",
+                candidateValue: value,
+                candidateState: checked ? "selected" : "unselected",
+                enabled: !isDisabled,
+                actuatorKind: "click",
+                actuatorId: `choice-list:${input.key}:${value}`,
+                semanticEffects: gameplayCandidateMetadata({
+                  descriptor,
+                  draftValues: handle.values as Readonly<
+                    Record<string, unknown>
+                  >,
+                  inputKey: input.key,
+                  candidateValue: value,
+                  intent: "toggle",
+                }).semanticEffects,
+              })}
               onClick={() => toggle(value)}
               className="h-8 px-3 text-sm"
             >
@@ -1057,6 +1315,8 @@ function ResourceMapField<
   Params extends InteractionParamsShape,
   Key extends keyof Params & string,
 >({
+  descriptor,
+  handle,
   input,
   value,
   setValue,
@@ -1123,6 +1383,23 @@ function ResourceMapField<
               <StepperButton
                 label={`Decrease ${resource.label ?? resource.resourceId}`}
                 disabled={disabled || amount <= min}
+                browserAttributes={gameplayActuatorAttributes({
+                  descriptor,
+                  draftValues: handle.values as Readonly<
+                    Record<string, unknown>
+                  >,
+                  inputKey: input.key,
+                  intent: "decrement",
+                  candidateValue: resource.resourceId,
+                  enabled: !(disabled || amount <= min),
+                  actuatorKind: "click",
+                  actuatorId: `resource-decrement:${input.key}:${resource.resourceId}`,
+                  semanticEffects: gameplayResourceMetadata({
+                    inputKey: input.key,
+                    resourceKey: resource.resourceId,
+                    delta: -1,
+                  }).semanticEffects,
+                })}
                 onClick={() => update(resource.resourceId, -1, min, max)}
               >
                 -
@@ -1139,6 +1416,23 @@ function ResourceMapField<
               <StepperButton
                 label={`Increase ${resource.label ?? resource.resourceId}`}
                 disabled={disabled || amount >= max}
+                browserAttributes={gameplayActuatorAttributes({
+                  descriptor,
+                  draftValues: handle.values as Readonly<
+                    Record<string, unknown>
+                  >,
+                  inputKey: input.key,
+                  intent: "increment",
+                  candidateValue: resource.resourceId,
+                  enabled: !(disabled || amount >= max),
+                  actuatorKind: "click",
+                  actuatorId: `resource-increment:${input.key}:${resource.resourceId}`,
+                  semanticEffects: gameplayResourceMetadata({
+                    inputKey: input.key,
+                    resourceKey: resource.resourceId,
+                    delta: 1,
+                  }).semanticEffects,
+                })}
                 onClick={() => update(resource.resourceId, 1, min, max)}
               >
                 +
@@ -1155,6 +1449,8 @@ function BoundedNumberField<
   Params extends InteractionParamsShape,
   Key extends keyof Params & string,
 >({
+  descriptor,
+  handle,
   input,
   value,
   setValue,
@@ -1190,6 +1486,19 @@ function BoundedNumberField<
         <StepperButton
           label={`Decrease ${input.key}`}
           disabled={disabled || current <= min}
+          browserAttributes={gameplayActuatorAttributes({
+            descriptor,
+            draftValues: handle.values as Readonly<Record<string, unknown>>,
+            inputKey: input.key,
+            intent: "decrement",
+            enabled: !(disabled || current <= min),
+            actuatorKind: "click",
+            actuatorId: `bounded-decrement:${input.key}`,
+            semanticEffects: gameplayScalarStepMetadata({
+              inputKey: input.key,
+              value: Math.max(min, Math.min(max, current - step)),
+            }).semanticEffects,
+          })}
           onClick={() => update(current - step)}
         >
           -
@@ -1202,12 +1511,38 @@ function BoundedNumberField<
           step={step}
           value={current}
           disabled={disabled}
+          {...gameplayActuatorAttributes({
+            descriptor,
+            draftValues: handle.values as Readonly<Record<string, unknown>>,
+            inputKey: input.key,
+            intent: "fill",
+            enabled: !disabled,
+            actuatorKind: "fill",
+            actuatorId: `bounded-fill:${input.key}`,
+            acceptedEffectPatterns: gameplayScalarFillMetadata({
+              inputKey: input.key,
+              domain,
+            }).acceptedEffectPatterns,
+          })}
           onChange={(event) => update(Number(event.target.value))}
           className="h-9 w-[8ch] px-2 text-center text-sm md:text-sm"
         />
         <StepperButton
           label={`Increase ${input.key}`}
           disabled={disabled || current >= max}
+          browserAttributes={gameplayActuatorAttributes({
+            descriptor,
+            draftValues: handle.values as Readonly<Record<string, unknown>>,
+            inputKey: input.key,
+            intent: "increment",
+            enabled: !(disabled || current >= max),
+            actuatorKind: "click",
+            actuatorId: `bounded-increment:${input.key}`,
+            semanticEffects: gameplayScalarStepMetadata({
+              inputKey: input.key,
+              value: Math.max(min, Math.min(max, current + step)),
+            }).semanticEffects,
+          })}
           onClick={() => update(current + step)}
         >
           +
@@ -1259,11 +1594,13 @@ function targetSelectionLabel(domain: InputDomain): string {
 function StepperButton({
   label,
   disabled,
+  browserAttributes,
   onClick,
   children,
 }: {
   label: string;
   disabled: boolean;
+  browserAttributes?: BrowserInteractionAttributeMap;
   onClick: () => void;
   children: ReactNode;
 }) {
@@ -1274,6 +1611,7 @@ function StepperButton({
       size="sm"
       aria-label={label}
       disabled={disabled}
+      {...browserAttributes}
       onClick={onClick}
       className="h-8 w-8 text-sm"
     >

package/src/runtime-internal/components/PluginRuntime.tsx

@@ -2,6 +2,7 @@ import React from "react";
 import { InteractionUiProvider } from "../context/InteractionDraftContext.js";
 import { RuntimeProvider } from "../context/RuntimeContext.js";
 import { usePluginSession } from "../context/PluginSessionContext.js";
+import { RuntimeSemanticProjectionMarker } from "../context/PluginStateContext.js";
 import { usePluginRuntime } from "../hooks/usePluginRuntime.js";
 import { GameSkeleton } from "../../ui.js";
 
@@ -97,6 +98,7 @@ function SessionScopedInteractionUiProvider({
   const { controllingPlayerId } = usePluginSession();
   return (
     <InteractionUiProvider key={controllingPlayerId ?? "__no_player__"}>
+      <RuntimeSemanticProjectionMarker />
       {children}
     </InteractionUiProvider>
   );

package/src/runtime-internal/components/board/target-layer.ts

@@ -1,4 +1,5 @@
 import type { BoardTargetKind } from "../../utils/interaction-inputs.js";
+import type { BrowserInteractionAttributeMap } from "../../../browser-interaction/index.js";
 
 export interface InteractiveTargetState {
   kind?: BoardTargetKind;
@@ -13,6 +14,7 @@ export interface InteractiveTargetState {
   conflict: boolean;
   conflictInteractionKeys?: readonly string[];
   unavailableReason?: string;
+  browserAttributes?: BrowserInteractionAttributeMap;
   select?: () => unknown | Promise<unknown>;
 }
 

package/src/runtime-internal/context/PluginStateContext.tsx

@@ -10,6 +10,12 @@ import {
 import type { PluginStateSnapshot } from "../types/plugin-state.js";
 import { useRuntimeContext } from "./RuntimeContext.js";
 import type { PluginRuntimeAPI } from "../runtime/createPluginRuntimeAPI.js";
+import {
+  BROWSER_INTERACTION_ATTRIBUTES,
+  DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
+  GAMEPLAY_BROWSER_INTERACTION_SURFACE,
+} from "../../browser-interaction/index.js";
+import { semanticProjectionDigestForState } from "../utils/semantic-projection-digest.js";
 
 /**
  * React Context for providing plugin state from state-sync messages.
@@ -121,11 +127,46 @@ export function PluginStateProvider({
 
   return (
     <PluginStateContext.Provider value={state}>
+      <SemanticProjectionMarker state={state} />
       {children}
     </PluginStateContext.Provider>
   );
 }
 
+const GAMEPLAY_BROWSER_SCOPE_ID = "runtime";
+const BROWSER_PROJECTION_DIGEST_ATTRIBUTE = "data-dreamboard-projection-digest";
+
+export function RuntimeSemanticProjectionMarker() {
+  const state = usePluginState((snapshot) => snapshot);
+  return <SemanticProjectionMarker state={state} />;
+}
+
+export function SemanticProjectionMarker({
+  state,
+}: {
+  state: PluginStateSnapshot;
+}) {
+  const digest = semanticProjectionDigestForState(state);
+  if (!digest) {
+    return null;
+  }
+  return (
+    <span
+      aria-hidden="true"
+      style={{ display: "none" }}
+      {...{
+        [BROWSER_INTERACTION_ATTRIBUTES.protocol]:
+          DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
+        [BROWSER_INTERACTION_ATTRIBUTES.surface]:
+          GAMEPLAY_BROWSER_INTERACTION_SURFACE,
+        [BROWSER_INTERACTION_ATTRIBUTES.scope]: GAMEPLAY_BROWSER_SCOPE_ID,
+        [BROWSER_INTERACTION_ATTRIBUTES.role]: "projection",
+        [BROWSER_PROJECTION_DIGEST_ATTRIBUTE]: digest,
+      }}
+    />
+  );
+}
+
 /**
  * Hook to access the full plugin state snapshot.
  *