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

package/src/browser-interaction/registry.ts

@@ -1,70 +0,0 @@
-import {
-  GAMEPLAY_BROWSER_INTERACTION_EFFECT_KINDS,
-  GAMEPLAY_BROWSER_INTERACTION_INTENTS,
-  GAMEPLAY_BROWSER_INTERACTION_SURFACE,
-} from "./constants.js";
-import type {
-  BrowserInteractionIntent,
-  BrowserInteractionRegistry,
-  BrowserInteractionSurface,
-  BrowserInteractionSurfaceDefinition,
-} from "./types.js";
-
-export function defineBrowserInteractionSurface<
-  Surface extends BrowserInteractionSurface,
-  Intent extends BrowserInteractionIntent,
->(
-  definition: BrowserInteractionSurfaceDefinition<Surface, Intent>,
-): BrowserInteractionSurfaceDefinition<Surface, Intent> {
-  const seen = new Set<string>();
-  for (const intent of definition.intents) {
-    if (seen.has(intent)) {
-      throw new Error(
-        `Browser interaction surface '${definition.surface}' declares duplicate intent '${intent}'.`,
-      );
-    }
-    seen.add(intent);
-  }
-  return definition;
-}
-
-export const gameplayBrowserInteractionSurface =
-  defineBrowserInteractionSurface({
-    surface: GAMEPLAY_BROWSER_INTERACTION_SURFACE,
-    intents: GAMEPLAY_BROWSER_INTERACTION_INTENTS,
-    effectKinds: GAMEPLAY_BROWSER_INTERACTION_EFFECT_KINDS,
-  });
-
-export function createBrowserInteractionRegistry(
-  definitions: readonly BrowserInteractionSurfaceDefinition[] = [
-    gameplayBrowserInteractionSurface,
-  ],
-): BrowserInteractionRegistry {
-  const surfaces = new Map<
-    BrowserInteractionSurface,
-    BrowserInteractionSurfaceDefinition
-  >();
-  for (const definition of definitions) {
-    const existing = surfaces.get(definition.surface);
-    if (existing) {
-      const existingIntents = existing.intents.join(",");
-      const nextIntents = definition.intents.join(",");
-      const existingEffectKinds = (existing.effectKinds ?? []).join(",");
-      const nextEffectKinds = (definition.effectKinds ?? []).join(",");
-      if (
-        existingIntents !== nextIntents ||
-        existingEffectKinds !== nextEffectKinds
-      ) {
-        throw new Error(
-          `Browser interaction surface '${definition.surface}' is already registered with a different intent vocabulary or effect vocabulary.`,
-        );
-      }
-      continue;
-    }
-    surfaces.set(definition.surface, definition);
-  }
-  return { surfaces };
-}
-
-export const defaultBrowserInteractionRegistry =
-  createBrowserInteractionRegistry();

package/src/browser-interaction/resolve.ts

@@ -1,596 +0,0 @@
-import { encodeCanonicalCandidateValue } from "./canonical.js";
-import {
-  browserInteractionEffectPatternMatches,
-  encodeBrowserInteractionEffect,
-} from "./effects.js";
-import {
-  actuatorIdentityKey,
-  isSemanticSurfaceSnapshot,
-  targetIdentityKey,
-  validateBrowserInteractionSnapshot,
-} from "./normalize.js";
-import type {
-  BrowserInteractionActuator,
-  BrowserInteractionDiagnostic,
-  BrowserInteractionEffectRequest,
-  BrowserInteractionEffectResolution,
-  BrowserInteractionEntity,
-  BrowserInteractionIntentRequest,
-  BrowserInteractionResolution,
-  BrowserInteractionSemanticSurfaceSnapshot,
-  BrowserInteractionSnapshot,
-  BrowserInteractionSurfaceEffect,
-} from "./types.js";
-
-export function resolveBrowserInteractionIntent(
-  snapshot: BrowserInteractionSnapshot,
-  request: BrowserInteractionIntentRequest,
-): BrowserInteractionResolution {
-  const snapshotDiagnostics = [
-    ...snapshot.diagnostics,
-    ...validateBrowserInteractionSnapshot(snapshot),
-  ];
-  if (
-    snapshotDiagnostics.some((diagnostic) => diagnostic.severity === "error")
-  ) {
-    return {
-      ok: false,
-      code: "invalid-snapshot",
-      diagnostics: snapshotDiagnostics,
-    };
-  }
-
-  const candidateValueKey =
-    request.candidateValueKey ??
-    ("candidateValue" in request
-      ? encodeCanonicalCandidateValue(request.candidateValue)
-      : undefined);
-  const surfaces = snapshot.surfaces.filter(
-    (surface): surface is BrowserInteractionSemanticSurfaceSnapshot =>
-      isSemanticSurfaceSnapshot(surface) &&
-      surface.surface === request.surface &&
-      (request.scopeId === undefined || surface.scopeId === request.scopeId),
-  );
-  const matches = surfaces.flatMap((surface) =>
-    surface.interactions.flatMap((interaction) => {
-      if (
-        request.interactionKey !== undefined &&
-        interaction.interactionKey !== request.interactionKey
-      ) {
-        return [];
-      }
-      if (
-        request.interactionId !== undefined &&
-        interaction.interactionId !== request.interactionId
-      ) {
-        return [];
-      }
-      return interaction.actuators
-        .filter((actuator) =>
-          actuatorMatchesRequest(actuator, request, candidateValueKey),
-        )
-        .map((actuator) => ({ surface, interaction, actuator }));
-    }),
-  );
-  const enabledMatches = matches.filter((match) => match.actuator.enabled);
-  const actionable = request.allowDisabled === true ? matches : enabledMatches;
-
-  if (actionable.length === 1) {
-    const match = actionable[0];
-    if (!match) throw new Error("unreachable browser interaction match");
-    return {
-      ok: true,
-      actuator: match.actuator,
-      surface: match.surface.surface,
-      scopeId: match.surface.scopeId,
-      interactionKey: match.interaction.interactionKey,
-      diagnostics: [],
-    };
-  }
-
-  if (actionable.length > 1) {
-    return {
-      ok: false,
-      code: "ambiguous",
-      diagnostics: actionable.map((match) =>
-        diagnosticFor({
-          code: "ambiguous-actuator",
-          message: "Browser interaction intent resolved to multiple actuators.",
-          surface: match.surface.surface,
-          scopeId: match.surface.scopeId,
-          interactionKey: match.interaction.interactionKey,
-          intent: match.actuator.intent,
-          actuatorId: match.actuator.actuatorId,
-        }),
-      ),
-    };
-  }
-
-  const preparation = findPreparationChain(
-    surfaces,
-    request,
-    candidateValueKey,
-  );
-  if (preparation.length > 0) {
-    return {
-      ok: false,
-      code: "preparation-required",
-      diagnostics: [
-        diagnosticFor({
-          code: "unavailable-actuator",
-          message:
-            "Requested browser interaction intent requires preparation before its actuator is available.",
-          surface: request.surface,
-          scopeId: request.scopeId,
-          interactionKey: request.interactionKey,
-          intent: request.intent,
-        }),
-      ],
-      preparation,
-    };
-  }
-
-  return {
-    ok: false,
-    code: matches.length > 0 ? "unavailable" : "not-found",
-    diagnostics: [
-      diagnosticFor({
-        code: "unavailable-actuator",
-        message:
-          matches.length > 0
-            ? "Browser interaction intent exists but has no enabled actuator."
-            : "Browser interaction intent is not present in the current snapshot.",
-        surface: request.surface,
-        scopeId: request.scopeId,
-        interactionKey: request.interactionKey,
-        intent: request.intent,
-      }),
-    ],
-  };
-}
-
-export function resolveBrowserInteractionEffect(
-  snapshot: BrowserInteractionSnapshot,
-  request: BrowserInteractionEffectRequest,
-): BrowserInteractionEffectResolution {
-  const snapshotDiagnostics = [
-    ...snapshot.diagnostics,
-    ...validateBrowserInteractionSnapshot(snapshot),
-  ];
-  if (
-    snapshotDiagnostics.some((diagnostic) => diagnostic.severity === "error")
-  ) {
-    return {
-      ok: false,
-      code: "invalid-snapshot",
-      diagnostics: snapshotDiagnostics,
-    };
-  }
-
-  const effectDiagnostics = validateEffectRequest(request.effect, request);
-  if (effectDiagnostics.length > 0) {
-    return {
-      ok: false,
-      code: "invalid-effect",
-      diagnostics: effectDiagnostics,
-    };
-  }
-
-  const surfaces = matchingSurfaces(snapshot, request);
-  const matches = collectInteractionMatches(surfaces, request);
-  const exactMatches = matches.filter((match) =>
-    match.actuator.semanticEffects.some(
-      (effect) =>
-        encodeBrowserInteractionEffect(effect) ===
-        encodeBrowserInteractionEffect(request.effect),
-    ),
-  );
-  const enabledExactMatches = exactMatches.filter(
-    (match) => match.actuator.enabled,
-  );
-  const actionableExactMatches =
-    request.allowDisabled === true ? exactMatches : enabledExactMatches;
-
-  if (actionableExactMatches.length === 1) {
-    const match = actionableExactMatches[0];
-    if (!match) throw new Error("unreachable browser effect match");
-    return effectSuccess(match, request.effect, "exact");
-  }
-
-  if (actionableExactMatches.length > 1) {
-    return effectAmbiguous(
-      actionableExactMatches,
-      "duplicate-enabled-effect-actuator",
-      "Browser interaction effect resolved to multiple exact actuators.",
-    );
-  }
-
-  if (exactMatches.length > 0 && enabledExactMatches.length === 0) {
-    return effectUnavailable(
-      request,
-      "disabled-effect-actuator",
-      "Browser interaction effect exists but has no enabled actuator.",
-    );
-  }
-
-  const acceptedMatches = matches.filter((match) =>
-    match.actuator.acceptedEffectPatterns.some((pattern) =>
-      browserInteractionEffectPatternMatches(pattern, request.effect),
-    ),
-  );
-  const enabledAcceptedMatches = acceptedMatches.filter(
-    (match) => match.actuator.enabled,
-  );
-  const actionableAcceptedMatches =
-    request.allowDisabled === true ? acceptedMatches : enabledAcceptedMatches;
-
-  if (actionableAcceptedMatches.length === 1) {
-    const match = actionableAcceptedMatches[0];
-    if (!match) throw new Error("unreachable browser accepted effect match");
-    return effectSuccess(match, request.effect, "accepted-pattern");
-  }
-
-  if (actionableAcceptedMatches.length > 1) {
-    return effectAmbiguous(
-      actionableAcceptedMatches,
-      "duplicate-accepted-effect-pattern-match",
-      "Browser interaction effect matched multiple accepted-effect patterns.",
-    );
-  }
-
-  if (acceptedMatches.length > 0 && enabledAcceptedMatches.length === 0) {
-    return effectUnavailable(
-      request,
-      "disabled-effect-actuator",
-      "Browser interaction effect pattern exists but has no enabled actuator.",
-    );
-  }
-
-  const preparation = findEffectPreparationChain(surfaces, request);
-  if (preparation.ok) {
-    return {
-      ok: false,
-      code: "preparation-required",
-      diagnostics: [
-        diagnosticFor({
-          code: "unavailable-actuator",
-          message:
-            "Requested browser interaction effect requires preparation before its actuator is available.",
-          surface: request.surface,
-          scopeId: request.scopeId,
-          interactionKey: request.interactionKey,
-        }),
-      ],
-      preparation: preparation.preparation,
-    };
-  }
-  if (preparation.diagnostics.length > 0) {
-    return {
-      ok: false,
-      code: "ambiguous",
-      diagnostics: preparation.diagnostics,
-    };
-  }
-
-  return {
-    ok: false,
-    code: "not-found",
-    diagnostics: [
-      diagnosticFor({
-        code: "missing-effect",
-        message:
-          "Browser interaction effect is not present in the current snapshot.",
-        surface: request.surface,
-        scopeId: request.scopeId,
-        interactionKey: request.interactionKey,
-      }),
-    ],
-  };
-}
-
-function actuatorMatchesRequest(
-  actuator: BrowserInteractionActuator,
-  request: BrowserInteractionIntentRequest,
-  candidateValueKey: string | undefined,
-): boolean {
-  return (
-    actuator.intent === request.intent &&
-    (request.inputKey === undefined ||
-      actuator.inputKey === request.inputKey) &&
-    (candidateValueKey === undefined ||
-      actuator.candidateValueKey === candidateValueKey) &&
-    (request.actuatorKind === undefined ||
-      actuator.actuatorKind === request.actuatorKind)
-  );
-}
-
-function findPreparationChain(
-  surfaces: readonly BrowserInteractionSemanticSurfaceSnapshot[],
-  request: BrowserInteractionIntentRequest,
-  candidateValueKey: string | undefined,
-): BrowserInteractionActuator[] {
-  const targetRequest = {
-    ...request,
-    candidateValueKey,
-  };
-  const preparationMatches = surfaces.flatMap((surface) =>
-    surface.interactions.flatMap((interaction) => {
-      if (!interactionMatchesRequest(interaction, request)) return [];
-      return interaction.actuators
-        .filter(
-          (actuator) =>
-            actuator.enabled &&
-            actuator.prepares &&
-            actuator.prepares.intent === targetRequest.intent &&
-            (targetRequest.inputKey === undefined ||
-              actuator.prepares.inputKey === targetRequest.inputKey) &&
-            (targetRequest.candidateValueKey === undefined ||
-              actuator.prepares.candidateValueKey ===
-                targetRequest.candidateValueKey) &&
-            (targetRequest.actuatorKind === undefined ||
-              actuator.prepares.actuatorKind === targetRequest.actuatorKind),
-        )
-        .map((actuator) => ({ surface, interaction, actuator }));
-    }),
-  );
-  if (preparationMatches.length !== 1) return [];
-  const match = preparationMatches[0];
-  if (!match) return [];
-  return expandPreparationChain(
-    match.surface,
-    match.interaction,
-    match.actuator,
-  );
-}
-
-function expandPreparationChain(
-  surface: BrowserInteractionSemanticSurfaceSnapshot,
-  interaction: BrowserInteractionEntity,
-  actuator: BrowserInteractionActuator,
-): BrowserInteractionActuator[] {
-  const byKey = new Map<string, BrowserInteractionActuator>();
-  for (const candidate of interaction.actuators) {
-    byKey.set(
-      actuatorIdentityKey({
-        surface: surface.surface,
-        scopeId: surface.scopeId,
-        interactionKey: interaction.interactionKey,
-        actuator: candidate,
-      }),
-      candidate,
-    );
-  }
-  const chain: BrowserInteractionActuator[] = [];
-  const visited = new Set<string>();
-  let current: BrowserInteractionActuator | undefined = actuator;
-  while (current) {
-    const key = actuatorIdentityKey({
-      surface: surface.surface,
-      scopeId: surface.scopeId,
-      interactionKey: interaction.interactionKey,
-      actuator: current,
-    });
-    if (visited.has(key)) return [];
-    visited.add(key);
-    chain.push(current);
-    current = current.prepares
-      ? byKey.get(
-          targetIdentityKey({
-            surface: surface.surface,
-            scopeId: surface.scopeId,
-            interactionKey: interaction.interactionKey,
-            target: current.prepares,
-          }),
-        )
-      : undefined;
-  }
-  return chain;
-}
-
-function interactionMatchesRequest(
-  interaction: BrowserInteractionEntity,
-  request: BrowserInteractionIntentRequest,
-): boolean {
-  return (
-    (request.interactionKey === undefined ||
-      interaction.interactionKey === request.interactionKey) &&
-    (request.interactionId === undefined ||
-      interaction.interactionId === request.interactionId)
-  );
-}
-
-function matchingSurfaces(
-  snapshot: BrowserInteractionSnapshot,
-  request: Pick<BrowserInteractionEffectRequest, "surface" | "scopeId">,
-): BrowserInteractionSemanticSurfaceSnapshot[] {
-  return snapshot.surfaces.filter(
-    (surface): surface is BrowserInteractionSemanticSurfaceSnapshot =>
-      isSemanticSurfaceSnapshot(surface) &&
-      surface.surface === request.surface &&
-      (request.scopeId === undefined || surface.scopeId === request.scopeId),
-  );
-}
-
-function collectInteractionMatches(
-  surfaces: readonly BrowserInteractionSemanticSurfaceSnapshot[],
-  request: Pick<
-    BrowserInteractionEffectRequest,
-    "interactionKey" | "interactionId"
-  >,
-) {
-  return surfaces.flatMap((surface) =>
-    surface.interactions.flatMap((interaction) => {
-      if (
-        request.interactionKey !== undefined &&
-        interaction.interactionKey !== request.interactionKey
-      ) {
-        return [];
-      }
-      if (
-        request.interactionId !== undefined &&
-        interaction.interactionId !== request.interactionId
-      ) {
-        return [];
-      }
-      return interaction.actuators.map((actuator) => ({
-        surface,
-        interaction,
-        actuator,
-      }));
-    }),
-  );
-}
-
-function effectSuccess(
-  match: {
-    readonly surface: BrowserInteractionSemanticSurfaceSnapshot;
-    readonly interaction: BrowserInteractionEntity;
-    readonly actuator: BrowserInteractionActuator;
-  },
-  effect: BrowserInteractionSurfaceEffect,
-  kind: "exact" | "accepted-pattern",
-): BrowserInteractionEffectResolution {
-  return {
-    ok: true,
-    actuator: match.actuator,
-    surface: match.surface.surface,
-    scopeId: match.surface.scopeId,
-    interactionKey: match.interaction.interactionKey,
-    match: kind,
-    effect,
-    diagnostics: [],
-  };
-}
-
-function effectAmbiguous(
-  matches: readonly {
-    readonly surface: BrowserInteractionSemanticSurfaceSnapshot;
-    readonly interaction: BrowserInteractionEntity;
-    readonly actuator: BrowserInteractionActuator;
-  }[],
-  code:
-    | "duplicate-enabled-effect-actuator"
-    | "duplicate-accepted-effect-pattern-match",
-  message: string,
-): BrowserInteractionEffectResolution {
-  return {
-    ok: false,
-    code: "ambiguous",
-    diagnostics: matches.map((match) =>
-      diagnosticFor({
-        code,
-        message,
-        surface: match.surface.surface,
-        scopeId: match.surface.scopeId,
-        interactionKey: match.interaction.interactionKey,
-        intent: match.actuator.intent,
-        actuatorId: match.actuator.actuatorId,
-      }),
-    ),
-  };
-}
-
-function effectUnavailable(
-  request: BrowserInteractionEffectRequest,
-  code: "disabled-effect-actuator",
-  message: string,
-): BrowserInteractionEffectResolution {
-  return {
-    ok: false,
-    code: "unavailable",
-    diagnostics: [
-      diagnosticFor({
-        code,
-        message,
-        surface: request.surface,
-        scopeId: request.scopeId,
-        interactionKey: request.interactionKey,
-      }),
-    ],
-  };
-}
-
-function findEffectPreparationChain(
-  surfaces: readonly BrowserInteractionSemanticSurfaceSnapshot[],
-  request: BrowserInteractionEffectRequest,
-):
-  | {
-      readonly ok: true;
-      readonly preparation: readonly BrowserInteractionActuator[];
-    }
-  | {
-      readonly ok: false;
-      readonly diagnostics: readonly BrowserInteractionDiagnostic[];
-    } {
-  const matches = collectInteractionMatches(surfaces, request).filter((match) =>
-    match.actuator.preparationPatterns.some((pattern) =>
-      browserInteractionEffectPatternMatches(pattern, request.effect),
-    ),
-  );
-  const enabledMatches = matches.filter((match) => match.actuator.enabled);
-  if (enabledMatches.length === 1) {
-    const match = enabledMatches[0];
-    if (!match) return { ok: false, diagnostics: [] };
-    return { ok: true, preparation: [match.actuator] };
-  }
-  if (enabledMatches.length > 1) {
-    return {
-      ok: false,
-      diagnostics: enabledMatches.map((match) =>
-        diagnosticFor({
-          code: "ambiguous-preparation-pattern",
-          message:
-            "Browser interaction effect resolved to multiple preparation actuators.",
-          surface: match.surface.surface,
-          scopeId: match.surface.scopeId,
-          interactionKey: match.interaction.interactionKey,
-          intent: match.actuator.intent,
-          actuatorId: match.actuator.actuatorId,
-        }),
-      ),
-    };
-  }
-  return { ok: false, diagnostics: [] };
-}
-
-function validateEffectRequest(
-  effect: BrowserInteractionSurfaceEffect,
-  request: Pick<
-    BrowserInteractionEffectRequest,
-    "surface" | "scopeId" | "interactionKey"
-  >,
-): readonly BrowserInteractionDiagnostic[] {
-  if (!effect || typeof effect.kind !== "string" || effect.kind.length === 0) {
-    return [
-      diagnosticFor({
-        code: "invalid-effect-payload",
-        message: "Browser interaction effect requires a string kind.",
-        surface: request.surface,
-        scopeId: request.scopeId,
-        interactionKey: request.interactionKey,
-      }),
-    ];
-  }
-  if (effect.kind === "setScalar") {
-    const value = effect.value;
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-      return [
-        diagnosticFor({
-          code: "invalid-scalar-argument",
-          message:
-            "setScalar browser interaction effects require a finite value.",
-          surface: request.surface,
-          scopeId: request.scopeId,
-          interactionKey: request.interactionKey,
-        }),
-      ];
-    }
-  }
-  return [];
-}
-
-function diagnosticFor(
-  input: Omit<BrowserInteractionDiagnostic, "severity">,
-): BrowserInteractionDiagnostic {
-  return { severity: "error", ...input };
-}