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

package/src/browser-interaction/constants.ts

@@ -0,0 +1,77 @@
+export const DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_NAME =
+  "dreamboard-browser-interaction" as const;
+
+export const DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION = "2.0.0" as const;
+
+export const BROWSER_INTERACTION_ATTRIBUTES = {
+  protocol: "data-dreamboard-browser-protocol",
+  surface: "data-dreamboard-browser-surface",
+  scope: "data-dreamboard-browser-scope",
+  role: "data-dreamboard-browser-role",
+  intent: "data-dreamboard-browser-intent",
+  interactionKey: "data-dreamboard-interaction-key",
+  interactionId: "data-dreamboard-interaction-id",
+  descriptorDigest: "data-dreamboard-descriptor-digest",
+  draftDigest: "data-dreamboard-draft-digest",
+  readiness: "data-dreamboard-readiness",
+  inputKey: "data-dreamboard-input-key",
+  candidateValue: "data-dreamboard-candidate-value",
+  candidateState: "data-dreamboard-candidate-state",
+  actuatorKind: "data-dreamboard-actuator-kind",
+  enabled: "data-dreamboard-actuator-enabled",
+  actuatorId: "data-dreamboard-actuator-id",
+  semanticEffects: "data-dreamboard-semantic-effects",
+  acceptedEffectPatterns: "data-dreamboard-accepted-effect-patterns",
+  preparationPatterns: "data-dreamboard-preparation-patterns",
+  preparesIntent: "data-dreamboard-prepares-intent",
+  preparesInputKey: "data-dreamboard-prepares-input-key",
+  preparesCandidateValue: "data-dreamboard-prepares-candidate-value",
+  preparesActuatorKind: "data-dreamboard-prepares-actuator-kind",
+  diagnostic: "data-dreamboard-browser-diagnostic",
+} as const;
+
+export const BROWSER_INTERACTION_RECORD_ROLES = [
+  "interaction",
+  "actuator",
+] as const;
+
+export const GAMEPLAY_BROWSER_INTERACTION_SURFACE = "gameplay" as const;
+
+export const GAMEPLAY_BROWSER_INTERACTION_INTENTS = [
+  "arm",
+  "reveal",
+  "invoke",
+  "select",
+  "toggle",
+  "increment",
+  "decrement",
+  "fill",
+  "submit",
+] as const;
+
+export const GAMEPLAY_BROWSER_INTERACTION_EFFECT_KINDS = [
+  "setCandidate",
+  "adjustResource",
+  "setScalar",
+  "commit",
+  "invoke",
+] as const;
+
+export const BROWSER_INTERACTION_READINESS_VALUES = [
+  "ready",
+  "blocked",
+  "unavailable",
+] as const;
+
+export const BROWSER_INTERACTION_CANDIDATE_STATES = [
+  "selected",
+  "unselected",
+  "mixed",
+] as const;
+
+export const BROWSER_INTERACTION_ACTUATOR_KINDS = [
+  "click",
+  "fill",
+  "keyboard",
+  "pointer",
+] as const;

package/src/browser-interaction/effects.ts

@@ -0,0 +1,176 @@
+import {
+  decodeCanonicalCandidateValue,
+  encodeCanonicalCandidateValue,
+  type CanonicalBrowserInteractionValue,
+} from "./canonical.js";
+import type {
+  BrowserInteractionEffectPattern,
+  BrowserInteractionSurfaceEffect,
+  GameplaySemanticEffect,
+} from "./types.js";
+
+export function encodeBrowserInteractionEffect(
+  effect: BrowserInteractionSurfaceEffect,
+): string {
+  return encodeCanonicalCandidateValue(effect);
+}
+
+export function decodeBrowserInteractionEffect(
+  encoded: string,
+): BrowserInteractionSurfaceEffect {
+  const decoded = decodeCanonicalCandidateValue(encoded);
+  if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
+    throw new Error("Browser interaction effect must be a canonical object.");
+  }
+  const decodedObject = decoded as {
+    readonly [key: string]: CanonicalBrowserInteractionValue;
+  };
+  const kind = decodedObject.kind;
+  if (typeof kind !== "string" || kind.length === 0) {
+    throw new Error("Browser interaction effect requires a string kind.");
+  }
+  return decodedObject as BrowserInteractionSurfaceEffect;
+}
+
+export function encodeBrowserInteractionEffectPattern(
+  pattern: BrowserInteractionEffectPattern,
+): string {
+  return encodeCanonicalCandidateValue(pattern);
+}
+
+export function decodeBrowserInteractionEffectPattern(
+  encoded: string,
+): BrowserInteractionEffectPattern {
+  const decoded = decodeCanonicalCandidateValue(encoded);
+  assertBrowserInteractionEffectPattern(decoded);
+  return decoded;
+}
+
+export function browserInteractionEffectPatternMatches(
+  pattern: BrowserInteractionEffectPattern,
+  effect: BrowserInteractionSurfaceEffect,
+): boolean {
+  switch (pattern.kind) {
+    case "exact":
+      return (
+        encodeBrowserInteractionEffect(pattern.effect) ===
+        encodeBrowserInteractionEffect(effect)
+      );
+    case "match": {
+      if (effect.kind !== pattern.effectKind) return false;
+      for (const [field, expected] of Object.entries(pattern.fields ?? {})) {
+        const actual = effect[field];
+        if (actual === undefined) return false;
+        if (
+          encodeCanonicalCandidateValue(actual) !==
+          encodeCanonicalCandidateValue(expected)
+        ) {
+          return false;
+        }
+      }
+      const scalar = pattern.scalar;
+      if (scalar) {
+        const actual = effect[scalar.field];
+        if (typeof actual !== "number" || !Number.isFinite(actual)) {
+          return false;
+        }
+        if (scalar.integer === true && !Number.isInteger(actual)) {
+          return false;
+        }
+        if (scalar.min !== undefined && actual < scalar.min) {
+          return false;
+        }
+        if (scalar.max !== undefined && actual > scalar.max) {
+          return false;
+        }
+      }
+      return true;
+    }
+  }
+}
+
+export function assertBrowserInteractionEffectPattern(
+  value: unknown,
+): asserts value is BrowserInteractionEffectPattern {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Browser interaction effect pattern must be an object.");
+  }
+  const pattern = value as {
+    readonly [key: string]: unknown;
+  };
+  if (pattern.kind === "exact") {
+    decodeBrowserInteractionEffect(
+      encodeCanonicalCandidateValue(pattern.effect),
+    );
+    return;
+  }
+  if (pattern.kind === "match") {
+    if (
+      typeof pattern.effectKind !== "string" ||
+      pattern.effectKind.length === 0
+    ) {
+      throw new Error(
+        "Browser interaction match pattern requires an effectKind.",
+      );
+    }
+    if (pattern.fields !== undefined) {
+      if (
+        !pattern.fields ||
+        typeof pattern.fields !== "object" ||
+        Array.isArray(pattern.fields)
+      ) {
+        throw new Error(
+          "Browser interaction match pattern fields must be an object.",
+        );
+      }
+    }
+    if (pattern.scalar !== undefined) {
+      if (
+        !pattern.scalar ||
+        typeof pattern.scalar !== "object" ||
+        Array.isArray(pattern.scalar) ||
+        typeof (pattern.scalar as { readonly field?: unknown }).field !==
+          "string" ||
+        (pattern.scalar as { readonly field: string }).field.length === 0
+      ) {
+        throw new Error(
+          "Browser interaction scalar pattern requires a scalar field.",
+        );
+      }
+    }
+    return;
+  }
+  throw new Error("Unknown browser interaction effect pattern kind.");
+}
+
+export function gameplaySetCandidateEffect(input: {
+  readonly inputKey: string;
+  readonly candidateValue: CanonicalBrowserInteractionValue;
+  readonly beforeSelected: boolean;
+  readonly afterSelected: boolean;
+}): GameplaySemanticEffect {
+  return { kind: "setCandidate", ...input };
+}
+
+export function gameplayAdjustResourceEffect(input: {
+  readonly inputKey: string;
+  readonly resourceKey: CanonicalBrowserInteractionValue;
+  readonly delta: -1 | 1;
+}): GameplaySemanticEffect {
+  return { kind: "adjustResource", ...input };
+}
+
+export function gameplaySetScalarEffect(input: {
+  readonly inputKey: string;
+  readonly value: number;
+}): GameplaySemanticEffect {
+  return { kind: "setScalar", ...input };
+}
+
+export function gameplayCommitEffect(): GameplaySemanticEffect {
+  return { kind: "commit" };
+}
+
+export function gameplayInvokeEffect(): GameplaySemanticEffect {
+  return { kind: "invoke" };
+}

package/src/browser-interaction/index.ts

@@ -0,0 +1,111 @@
+export {
+  BROWSER_INTERACTION_ACTUATOR_KINDS,
+  BROWSER_INTERACTION_ATTRIBUTES,
+  BROWSER_INTERACTION_CANDIDATE_STATES,
+  BROWSER_INTERACTION_READINESS_VALUES,
+  BROWSER_INTERACTION_RECORD_ROLES,
+  DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_NAME,
+  DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
+  GAMEPLAY_BROWSER_INTERACTION_EFFECT_KINDS,
+  GAMEPLAY_BROWSER_INTERACTION_INTENTS,
+  GAMEPLAY_BROWSER_INTERACTION_SURFACE,
+} from "./constants.js";
+export {
+  compareStableJson,
+  decodeCanonicalCandidateValue,
+  encodeCanonicalCandidateValue,
+  type CanonicalBrowserInteractionValue,
+} from "./canonical.js";
+export {
+  assertBrowserInteractionEffectPattern,
+  browserInteractionEffectPatternMatches,
+  decodeBrowserInteractionEffect,
+  decodeBrowserInteractionEffectPattern,
+  encodeBrowserInteractionEffect,
+  encodeBrowserInteractionEffectPattern,
+  gameplayAdjustResourceEffect,
+  gameplayCommitEffect,
+  gameplayInvokeEffect,
+  gameplaySetCandidateEffect,
+  gameplaySetScalarEffect,
+} from "./effects.js";
+export {
+  createBrowserInteractionActuatorAttributes,
+  createBrowserInteractionActuatorKey,
+  createBrowserInteractionRootAttributes,
+  createGameplayActuatorAttributes,
+  createGameplayInteractionRootAttributes,
+  type BrowserInteractionActuatorAttributesInput,
+  type BrowserInteractionAttributeMap,
+  type BrowserInteractionRootAttributesInput,
+  type GameplayActuatorAttributesInput,
+  type GameplayInteractionRootAttributesInput,
+} from "./attributes.js";
+export {
+  createBrowserInteractionRegistry,
+  defaultBrowserInteractionRegistry,
+  defineBrowserInteractionSurface,
+  gameplayBrowserInteractionSurface,
+} from "./registry.js";
+export {
+  actuatorIdentityKey,
+  isSemanticSurfaceSnapshot,
+  normalizeBrowserInteractionRecords,
+  targetIdentityKey,
+  validateBrowserInteractionSnapshot,
+  type NormalizeBrowserInteractionRecordsOptions,
+} from "./normalize.js";
+export {
+  resolveBrowserInteractionEffect,
+  resolveBrowserInteractionIntent,
+} from "./resolve.js";
+export {
+  browserInteractionEffectPatternSchema,
+  browserInteractionEffectSchema,
+  browserGameplayInteractionSchema,
+  browserGameplaySurfaceSnapshotSchema,
+  browserInteractionActuatorSchema,
+  browserInteractionDiagnosticSchema,
+  browserInteractionSnapshotSchema,
+  browserSemanticSurfaceSnapshotSchema,
+  browserUnknownSurfaceSnapshotSchema,
+  gameplaySemanticEffectSchema,
+} from "./schemas.js";
+export type {
+  BrowserGameplayInteraction,
+  BrowserGameplaySurfaceSnapshot,
+  BrowserInteractionActuator,
+  BrowserInteractionActuatorKind,
+  BrowserInteractionCandidateState,
+  BrowserInteractionDiagnostic,
+  BrowserInteractionEffectPattern,
+  BrowserInteractionEffectRequest,
+  BrowserInteractionEffectResolution,
+  BrowserInteractionEffectResolutionFailure,
+  BrowserInteractionEffectResolutionSuccess,
+  BrowserInteractionEntity,
+  BrowserInteractionIntent,
+  BrowserInteractionIntentRequest,
+  BrowserInteractionPreparationTarget,
+  BrowserInteractionProtocolIdentity,
+  BrowserInteractionRawRecord,
+  BrowserInteractionReadiness,
+  BrowserInteractionRegistry,
+  BrowserInteractionResolution,
+  BrowserInteractionResolutionFailure,
+  BrowserInteractionResolutionSuccess,
+  BrowserInteractionScalarPattern,
+  BrowserInteractionSemanticSurfaceSnapshot,
+  BrowserInteractionSnapshot,
+  BrowserInteractionSurfaceEffect,
+  BrowserInteractionSurface,
+  BrowserInteractionSurfaceDefinition,
+  BrowserInteractionSurfaceSnapshot,
+  BrowserInteractionUnknownSurfaceSnapshot,
+  GameplayBrowserInteractionEffectKind,
+  GameplayBrowserInteractionEffectRequest,
+  GameplayBrowserInteractionIntent,
+  GameplayBrowserInteractionSurface,
+  GameplaySemanticEffect,
+  GameplaySemanticEffectPattern,
+} from "./types.js";