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

package/dist/chunk-QLG6VEMW.js

@@ -0,0 +1,1691 @@
+// src/browser-interaction/constants.ts
+var DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_NAME = "dreamboard-browser-interaction";
+var DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION = "2.0.0";
+var 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"
+};
+var BROWSER_INTERACTION_RECORD_ROLES = [
+  "interaction",
+  "actuator"
+];
+var GAMEPLAY_BROWSER_INTERACTION_SURFACE = "gameplay";
+var GAMEPLAY_BROWSER_INTERACTION_INTENTS = [
+  "arm",
+  "reveal",
+  "invoke",
+  "select",
+  "toggle",
+  "increment",
+  "decrement",
+  "fill",
+  "submit"
+];
+var GAMEPLAY_BROWSER_INTERACTION_EFFECT_KINDS = [
+  "setCandidate",
+  "adjustResource",
+  "setScalar",
+  "commit",
+  "invoke"
+];
+var BROWSER_INTERACTION_READINESS_VALUES = [
+  "ready",
+  "blocked",
+  "unavailable"
+];
+var BROWSER_INTERACTION_CANDIDATE_STATES = [
+  "selected",
+  "unselected",
+  "mixed"
+];
+var BROWSER_INTERACTION_ACTUATOR_KINDS = [
+  "click",
+  "fill",
+  "keyboard",
+  "pointer"
+];
+
+// src/browser-interaction/canonical.ts
+function assertCanonicalValue(value) {
+  if (value === null) return;
+  switch (typeof value) {
+    case "boolean":
+    case "string":
+      return;
+    case "number":
+      if (Number.isFinite(value)) return;
+      break;
+    case "object":
+      if (Array.isArray(value)) {
+        value.forEach(assertCanonicalValue);
+        return;
+      }
+      if (Object.getPrototypeOf(value) !== Object.prototype) break;
+      for (const [key, item] of Object.entries(value)) {
+        if (item === void 0) {
+          throw new Error(
+            `Browser interaction candidate '${key}' cannot be undefined.`
+          );
+        }
+        assertCanonicalValue(item);
+      }
+      return;
+  }
+  throw new Error(
+    `Browser interaction candidates must be JSON-serializable primitives, arrays or plain objects. Received ${typeof value}.`
+  );
+}
+function canonicalizeValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalizeValue);
+  }
+  if (value && typeof value === "object") {
+    const objectValue = value;
+    return Object.fromEntries(
+      Object.keys(objectValue).sort().map((key) => [key, canonicalizeValue(objectValue[key])])
+    );
+  }
+  return value;
+}
+function encodeCanonicalCandidateValue(value) {
+  assertCanonicalValue(value);
+  return JSON.stringify(canonicalizeValue(value));
+}
+function decodeCanonicalCandidateValue(encoded) {
+  const parsed = JSON.parse(encoded);
+  assertCanonicalValue(parsed);
+  return canonicalizeValue(parsed);
+}
+function compareStableJson(a, b) {
+  const encodedA = encodeCanonicalCandidateValue(a);
+  const encodedB = encodeCanonicalCandidateValue(b);
+  return encodedA.localeCompare(encodedB);
+}
+
+// src/browser-interaction/effects.ts
+function encodeBrowserInteractionEffect(effect) {
+  return encodeCanonicalCandidateValue(effect);
+}
+function decodeBrowserInteractionEffect(encoded) {
+  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;
+  const kind = decodedObject.kind;
+  if (typeof kind !== "string" || kind.length === 0) {
+    throw new Error("Browser interaction effect requires a string kind.");
+  }
+  return decodedObject;
+}
+function encodeBrowserInteractionEffectPattern(pattern) {
+  return encodeCanonicalCandidateValue(pattern);
+}
+function decodeBrowserInteractionEffectPattern(encoded) {
+  const decoded = decodeCanonicalCandidateValue(encoded);
+  assertBrowserInteractionEffectPattern(decoded);
+  return decoded;
+}
+function browserInteractionEffectPatternMatches(pattern, effect) {
+  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 === void 0) 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 !== void 0 && actual < scalar.min) {
+          return false;
+        }
+        if (scalar.max !== void 0 && actual > scalar.max) {
+          return false;
+        }
+      }
+      return true;
+    }
+  }
+}
+function assertBrowserInteractionEffectPattern(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Browser interaction effect pattern must be an object.");
+  }
+  const pattern = value;
+  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 !== void 0) {
+      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 !== void 0) {
+      if (!pattern.scalar || typeof pattern.scalar !== "object" || Array.isArray(pattern.scalar) || typeof pattern.scalar.field !== "string" || pattern.scalar.field.length === 0) {
+        throw new Error(
+          "Browser interaction scalar pattern requires a scalar field."
+        );
+      }
+    }
+    return;
+  }
+  throw new Error("Unknown browser interaction effect pattern kind.");
+}
+function gameplaySetCandidateEffect(input) {
+  return { kind: "setCandidate", ...input };
+}
+function gameplayAdjustResourceEffect(input) {
+  return { kind: "adjustResource", ...input };
+}
+function gameplaySetScalarEffect(input) {
+  return { kind: "setScalar", ...input };
+}
+function gameplayCommitEffect() {
+  return { kind: "commit" };
+}
+function gameplayInvokeEffect() {
+  return { kind: "invoke" };
+}
+
+// src/browser-interaction/attributes.ts
+function baseGameplayAttributes(input) {
+  return {
+    [BROWSER_INTERACTION_ATTRIBUTES.protocol]: DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
+    [BROWSER_INTERACTION_ATTRIBUTES.surface]: input.surface,
+    [BROWSER_INTERACTION_ATTRIBUTES.scope]: input.scopeId,
+    [BROWSER_INTERACTION_ATTRIBUTES.interactionKey]: input.interactionKey,
+    [BROWSER_INTERACTION_ATTRIBUTES.interactionId]: input.interactionId
+  };
+}
+function createBrowserInteractionRootAttributes(input) {
+  return {
+    ...baseGameplayAttributes(input),
+    [BROWSER_INTERACTION_ATTRIBUTES.role]: "interaction",
+    [BROWSER_INTERACTION_ATTRIBUTES.descriptorDigest]: input.descriptorDigest ?? "",
+    [BROWSER_INTERACTION_ATTRIBUTES.draftDigest]: input.draftDigest ?? "",
+    [BROWSER_INTERACTION_ATTRIBUTES.readiness]: input.readiness
+  };
+}
+function createBrowserInteractionActuatorAttributes(input) {
+  const attrs = {
+    ...baseGameplayAttributes(input),
+    [BROWSER_INTERACTION_ATTRIBUTES.role]: "actuator",
+    [BROWSER_INTERACTION_ATTRIBUTES.intent]: input.intent,
+    [BROWSER_INTERACTION_ATTRIBUTES.actuatorKind]: input.actuatorKind,
+    [BROWSER_INTERACTION_ATTRIBUTES.enabled]: input.enabled === false ? "false" : "true"
+  };
+  if (input.descriptorDigest) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.descriptorDigest] = input.descriptorDigest;
+  }
+  if (input.draftDigest) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.draftDigest] = input.draftDigest;
+  }
+  if (input.actuatorId) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.actuatorId] = input.actuatorId;
+  }
+  if (input.inputKey) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.inputKey] = input.inputKey;
+  }
+  if ("candidateValue" in input) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.candidateValue] = encodeCanonicalCandidateValue(input.candidateValue);
+  }
+  if (input.candidateState) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.candidateState] = input.candidateState;
+  }
+  if (input.semanticEffects && input.semanticEffects.length > 0) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.semanticEffects] = JSON.stringify(
+      input.semanticEffects.map(encodeBrowserInteractionEffect)
+    );
+  }
+  if (input.acceptedEffectPatterns && input.acceptedEffectPatterns.length > 0) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.acceptedEffectPatterns] = JSON.stringify(
+      input.acceptedEffectPatterns.map(encodeBrowserInteractionEffectPattern)
+    );
+  }
+  if (input.preparationPatterns && input.preparationPatterns.length > 0) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.preparationPatterns] = JSON.stringify(
+      input.preparationPatterns.map(encodeBrowserInteractionEffectPattern)
+    );
+  }
+  if (input.prepares) {
+    attrs[BROWSER_INTERACTION_ATTRIBUTES.preparesIntent] = input.prepares.intent;
+    if (input.prepares.inputKey) {
+      attrs[BROWSER_INTERACTION_ATTRIBUTES.preparesInputKey] = input.prepares.inputKey;
+    }
+    if (input.prepares.candidateValueKey) {
+      attrs[BROWSER_INTERACTION_ATTRIBUTES.preparesCandidateValue] = input.prepares.candidateValueKey;
+    } else if ("candidateValue" in input.prepares) {
+      attrs[BROWSER_INTERACTION_ATTRIBUTES.preparesCandidateValue] = encodeCanonicalCandidateValue(input.prepares.candidateValue);
+    }
+    if (input.prepares.actuatorKind) {
+      attrs[BROWSER_INTERACTION_ATTRIBUTES.preparesActuatorKind] = input.prepares.actuatorKind;
+    }
+  }
+  return attrs;
+}
+function createGameplayInteractionRootAttributes(input) {
+  return createBrowserInteractionRootAttributes({
+    ...input,
+    surface: GAMEPLAY_BROWSER_INTERACTION_SURFACE
+  });
+}
+function createGameplayActuatorAttributes(input) {
+  return createBrowserInteractionActuatorAttributes({
+    ...input,
+    surface: GAMEPLAY_BROWSER_INTERACTION_SURFACE
+  });
+}
+function createBrowserInteractionActuatorKey(input) {
+  return [
+    input.surface,
+    input.scopeId,
+    input.interactionKey,
+    input.intent,
+    input.inputKey ?? "",
+    input.candidateValueKey ?? "",
+    input.actuatorKind
+  ].map((part) => encodeURIComponent(part)).join("|");
+}
+
+// src/browser-interaction/registry.ts
+function defineBrowserInteractionSurface(definition) {
+  const seen = /* @__PURE__ */ new Set();
+  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;
+}
+var gameplayBrowserInteractionSurface = defineBrowserInteractionSurface({
+  surface: GAMEPLAY_BROWSER_INTERACTION_SURFACE,
+  intents: GAMEPLAY_BROWSER_INTERACTION_INTENTS,
+  effectKinds: GAMEPLAY_BROWSER_INTERACTION_EFFECT_KINDS
+});
+function createBrowserInteractionRegistry(definitions = [
+  gameplayBrowserInteractionSurface
+]) {
+  const surfaces = /* @__PURE__ */ new Map();
+  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 };
+}
+var defaultBrowserInteractionRegistry = createBrowserInteractionRegistry();
+
+// src/browser-interaction/normalize.ts
+function normalizeBrowserInteractionRecords(records, options = {}) {
+  const registry = options.registry ?? defaultBrowserInteractionRegistry;
+  const diagnostics = [];
+  const surfaces = /* @__PURE__ */ new Map();
+  const getSurface = (surface, scopeId) => {
+    const registered = registry.surfaces.get(surface);
+    const key = `${surface}\0${scopeId}`;
+    const existing = surfaces.get(key);
+    if (existing) return existing;
+    if (!registered) {
+      const diagnostic = diagnosticFor({
+        code: "unknown-surface",
+        message: `Unknown browser interaction surface '${surface}'.`,
+        surface,
+        scopeId
+      });
+      diagnostics.push(diagnostic);
+      const pending2 = {
+        kind: "unknown",
+        surface,
+        scopeId,
+        diagnostics: [diagnostic]
+      };
+      surfaces.set(key, pending2);
+      return pending2;
+    }
+    const pending = {
+      kind: "semantic",
+      surface,
+      scopeId,
+      interactions: /* @__PURE__ */ new Map(),
+      diagnostics: []
+    };
+    surfaces.set(key, pending);
+    return pending;
+  };
+  for (const record of records) {
+    const attributes = record.attributes;
+    const protocol = text(attributes, BROWSER_INTERACTION_ATTRIBUTES.protocol);
+    const surface = text(attributes, BROWSER_INTERACTION_ATTRIBUTES.surface);
+    const scopeId = text(attributes, BROWSER_INTERACTION_ATTRIBUTES.scope);
+    const role = text(attributes, BROWSER_INTERACTION_ATTRIBUTES.role);
+    if (protocol !== DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION) {
+      diagnostics.push(
+        diagnosticFor({
+          code: "invalid-protocol",
+          message: `Expected browser interaction protocol ${DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION}.`,
+          surface,
+          scopeId
+        })
+      );
+      continue;
+    }
+    if (!surface || !scopeId || role !== "interaction" && role !== "actuator") {
+      diagnostics.push(
+        diagnosticFor({
+          code: "invalid-record",
+          message: "Browser interaction records require protocol, surface, scope and role.",
+          surface,
+          scopeId
+        })
+      );
+      continue;
+    }
+    const pendingSurface = getSurface(surface, scopeId);
+    if (!pendingSurface || pendingSurface.kind !== "semantic") {
+      continue;
+    }
+    const interactionKey = text(
+      attributes,
+      BROWSER_INTERACTION_ATTRIBUTES.interactionKey
+    );
+    const interactionId = text(
+      attributes,
+      BROWSER_INTERACTION_ATTRIBUTES.interactionId
+    );
+    if (!interactionKey || !interactionId) {
+      pushSurfaceDiagnostic(
+        pendingSurface,
+        diagnostics,
+        diagnosticFor({
+          code: "invalid-record",
+          message: "Browser interaction records require interaction key and id.",
+          surface,
+          scopeId
+        })
+      );
+      continue;
+    }
+    const interaction = getInteraction(
+      pendingSurface,
+      interactionKey,
+      interactionId
+    );
+    if (role === "interaction") {
+      interaction.rootSeen = true;
+      interaction.descriptorDigest = optionalText(
+        attributes,
+        BROWSER_INTERACTION_ATTRIBUTES.descriptorDigest
+      );
+      interaction.draftDigest = optionalText(
+        attributes,
+        BROWSER_INTERACTION_ATTRIBUTES.draftDigest
+      );
+      interaction.readiness = parseReadiness(
+        text(attributes, BROWSER_INTERACTION_ATTRIBUTES.readiness)
+      );
+      continue;
+    }
+    const actuator = parseGameplayActuator(attributes, {
+      surface,
+      scopeId,
+      interactionKey,
+      interactionId
+    });
+    if (actuator.diagnostics.length > 0) {
+      interaction.diagnostics.push(...actuator.diagnostics);
+      diagnostics.push(...actuator.diagnostics);
+    }
+    const registered = registry.surfaces.get(surface);
+    if (registered && !registered.intents.includes(actuator.intent)) {
+      const diagnostic = diagnosticFor({
+        code: "unknown-intent",
+        message: `Unknown browser interaction intent '${actuator.intent}' for surface '${surface}'.`,
+        surface,
+        scopeId,
+        interactionKey,
+        intent: actuator.intent,
+        actuatorId: actuator.actuatorId
+      });
+      interaction.diagnostics.push(diagnostic);
+      diagnostics.push(diagnostic);
+    }
+    if (registered?.effectKinds) {
+      for (const effect of actuator.semanticEffects) {
+        if (!registered.effectKinds.includes(effect.kind)) {
+          const diagnostic = diagnosticFor({
+            code: "unknown-surface-effect",
+            message: `Unknown browser interaction effect '${effect.kind}' for surface '${surface}'.`,
+            surface,
+            scopeId,
+            interactionKey,
+            intent: actuator.intent,
+            actuatorId: actuator.actuatorId
+          });
+          interaction.diagnostics.push(diagnostic);
+          diagnostics.push(diagnostic);
+        }
+      }
+      for (const pattern of [
+        ...actuator.acceptedEffectPatterns,
+        ...actuator.preparationPatterns
+      ]) {
+        const effectKind = pattern.kind === "exact" ? pattern.effect.kind : pattern.effectKind;
+        if (!registered.effectKinds.includes(effectKind)) {
+          const diagnostic = diagnosticFor({
+            code: "unknown-surface-effect",
+            message: `Unknown browser interaction effect '${effectKind}' for surface '${surface}'.`,
+            surface,
+            scopeId,
+            interactionKey,
+            intent: actuator.intent,
+            actuatorId: actuator.actuatorId
+          });
+          interaction.diagnostics.push(diagnostic);
+          diagnostics.push(diagnostic);
+        }
+      }
+    }
+    interaction.actuators.push(actuator);
+  }
+  for (const surface of surfaces.values()) {
+    if (surface.kind !== "semantic") continue;
+    for (const interaction of surface.interactions.values()) {
+      if (interaction.rootSeen || interaction.actuators.length === 0) continue;
+      const diagnostic = diagnosticFor({
+        code: "orphan-actuator",
+        message: "Browser interaction actuators require a rendered semantic root.",
+        surface: surface.surface,
+        scopeId: surface.scopeId,
+        interactionKey: interaction.interactionKey
+      });
+      interaction.diagnostics.push(diagnostic);
+      diagnostics.push(diagnostic);
+    }
+  }
+  const snapshot = {
+    protocol: {
+      name: DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_NAME,
+      version: DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION
+    },
+    surfaces: [...surfaces.values()].map(finalizeSurface).sort(compareSurface),
+    diagnostics: []
+  };
+  const validationDiagnostics = validateBrowserInteractionSnapshot(snapshot);
+  return {
+    ...snapshot,
+    diagnostics: [...diagnostics, ...validationDiagnostics].sort(
+      compareDiagnostic
+    )
+  };
+}
+function validateBrowserInteractionSnapshot(snapshot) {
+  const diagnostics = [];
+  for (const surface of snapshot.surfaces) {
+    if (!isSemanticSurfaceSnapshot(surface)) continue;
+    for (const interaction of surface.interactions) {
+      const enabledByKey = /* @__PURE__ */ new Map();
+      for (const actuator of interaction.actuators) {
+        if (!actuator.enabled) continue;
+        const key = actuatorIdentityKey({
+          surface: surface.surface,
+          scopeId: surface.scopeId,
+          interactionKey: interaction.interactionKey,
+          actuator
+        });
+        const group = enabledByKey.get(key) ?? [];
+        group.push(actuator);
+        enabledByKey.set(key, group);
+      }
+      for (const [key, actuators] of enabledByKey) {
+        if (actuators.length > 1) {
+          diagnostics.push(
+            diagnosticFor({
+              code: "duplicate-enabled-actuator",
+              message: `Duplicate enabled actuator for '${key}'.`,
+              surface: surface.surface,
+              scopeId: surface.scopeId,
+              interactionKey: interaction.interactionKey,
+              intent: actuators[0]?.intent,
+              actuatorId: actuators[0]?.actuatorId
+            })
+          );
+        }
+      }
+      diagnostics.push(
+        ...diagnosticsForPreparationCycles(surface, interaction),
+        ...diagnosticsForPreparationPatternAmbiguity(surface, interaction),
+        ...diagnosticsForInvalidAcceptedPatterns(surface, interaction),
+        ...diagnosticsForGameplayEffectCompatibility(surface, interaction)
+      );
+    }
+  }
+  return diagnostics.sort(compareDiagnostic);
+}
+function diagnosticsForInvalidAcceptedPatterns(surface, interaction) {
+  const diagnostics = [];
+  for (const actuator of interaction.actuators) {
+    for (const pattern of actuator.acceptedEffectPatterns) {
+      if (pattern.kind === "match" && Object.keys(pattern.fields ?? {}).length === 0 && pattern.scalar === void 0) {
+        diagnostics.push(
+          diagnosticFor({
+            code: "invalid-effect-pattern",
+            message: "Accepted-effect match patterns must be bounded by fields or scalar constraints.",
+            surface: surface.surface,
+            scopeId: surface.scopeId,
+            interactionKey: interaction.interactionKey,
+            intent: actuator.intent,
+            actuatorId: actuator.actuatorId
+          })
+        );
+      }
+    }
+  }
+  return diagnostics;
+}
+function diagnosticsForGameplayEffectCompatibility(surface, interaction) {
+  if (surface.surface !== GAMEPLAY_BROWSER_INTERACTION_SURFACE) return [];
+  const diagnostics = [];
+  for (const actuator of interaction.actuators) {
+    for (const effect of actuator.semanticEffects) {
+      if (!gameplayIntentCanPerformEffect(actuator.intent, effect.kind)) {
+        diagnostics.push(
+          diagnosticFor({
+            code: "effect-intent-incompatibility",
+            message: "Gameplay browser interaction intent is incompatible with its semantic effect.",
+            surface: surface.surface,
+            scopeId: surface.scopeId,
+            interactionKey: interaction.interactionKey,
+            intent: actuator.intent,
+            actuatorId: actuator.actuatorId
+          })
+        );
+      }
+    }
+  }
+  return diagnostics;
+}
+function gameplayIntentCanPerformEffect(intent, effectKind) {
+  switch (effectKind) {
+    case "setCandidate":
+      return intent === "select" || intent === "toggle";
+    case "adjustResource":
+      return intent === "increment" || intent === "decrement";
+    case "setScalar":
+      return intent === "fill" || intent === "increment" || intent === "decrement";
+    case "commit":
+      return intent === "submit" || intent === "invoke";
+    case "invoke":
+      return intent === "invoke" || intent === "select" || intent === "toggle";
+    default:
+      return true;
+  }
+}
+function parseGameplayActuator(attributes, context) {
+  const diagnostics = [];
+  const intent = text(attributes, BROWSER_INTERACTION_ATTRIBUTES.intent);
+  const actuatorKind = parseActuatorKind(
+    text(attributes, BROWSER_INTERACTION_ATTRIBUTES.actuatorKind)
+  );
+  const inputKey = optionalText(
+    attributes,
+    BROWSER_INTERACTION_ATTRIBUTES.inputKey
+  );
+  const candidate = parseCandidate(
+    attributes,
+    BROWSER_INTERACTION_ATTRIBUTES.candidateValue,
+    context,
+    intent,
+    diagnostics
+  );
+  const candidateState = parseCandidateState(
+    optionalText(attributes, BROWSER_INTERACTION_ATTRIBUTES.candidateState)
+  );
+  const explicitId = optionalText(
+    attributes,
+    BROWSER_INTERACTION_ATTRIBUTES.actuatorId
+  );
+  const enabled = parseEnabled(
+    attributes[BROWSER_INTERACTION_ATTRIBUTES.enabled]
+  );
+  const actuatorId = explicitId ?? createBrowserInteractionActuatorKey({
+    surface: context.surface,
+    scopeId: context.scopeId,
+    interactionKey: context.interactionKey,
+    intent,
+    inputKey,
+    candidateValueKey: candidate?.candidateValueKey,
+    actuatorKind
+  });
+  const preparesIntent = optionalText(
+    attributes,
+    BROWSER_INTERACTION_ATTRIBUTES.preparesIntent
+  );
+  const preparesCandidate = parseCandidate(
+    attributes,
+    BROWSER_INTERACTION_ATTRIBUTES.preparesCandidateValue,
+    context,
+    preparesIntent ?? intent,
+    diagnostics
+  );
+  const prepares = preparesIntent === void 0 ? void 0 : {
+    intent: preparesIntent,
+    inputKey: optionalText(
+      attributes,
+      BROWSER_INTERACTION_ATTRIBUTES.preparesInputKey
+    ),
+    candidateValue: preparesCandidate?.candidateValue,
+    candidateValueKey: preparesCandidate?.candidateValueKey,
+    actuatorKind: parseOptionalActuatorKind(
+      optionalText(
+        attributes,
+        BROWSER_INTERACTION_ATTRIBUTES.preparesActuatorKind
+      )
+    )
+  };
+  const semanticEffects = parseEffectList(
+    attributes,
+    BROWSER_INTERACTION_ATTRIBUTES.semanticEffects,
+    context,
+    intent,
+    diagnostics
+  );
+  const acceptedEffectPatterns = parseEffectPatternList(
+    attributes,
+    BROWSER_INTERACTION_ATTRIBUTES.acceptedEffectPatterns,
+    context,
+    intent,
+    diagnostics
+  );
+  const preparationPatterns = parseEffectPatternList(
+    attributes,
+    BROWSER_INTERACTION_ATTRIBUTES.preparationPatterns,
+    context,
+    intent,
+    diagnostics
+  );
+  if (!intent) {
+    diagnostics.push(
+      diagnosticFor({
+        code: "invalid-record",
+        message: "Browser interaction actuator records require an intent.",
+        ...context
+      })
+    );
+  }
+  return {
+    actuatorId,
+    intent,
+    descriptorDigest: optionalText(
+      attributes,
+      BROWSER_INTERACTION_ATTRIBUTES.descriptorDigest
+    ),
+    draftDigest: optionalText(
+      attributes,
+      BROWSER_INTERACTION_ATTRIBUTES.draftDigest
+    ),
+    inputKey,
+    candidateValue: candidate?.candidateValue,
+    candidateValueKey: candidate?.candidateValueKey,
+    candidateState,
+    enabled,
+    actuatorKind,
+    semanticEffects,
+    acceptedEffectPatterns,
+    preparationPatterns,
+    prepares,
+    diagnostics: diagnostics.sort(compareDiagnostic)
+  };
+}
+function parseEffectList(attributes, attribute, context, intent, diagnostics) {
+  const encodedList = optionalText(attributes, attribute);
+  if (encodedList === void 0) return [];
+  try {
+    const raw = JSON.parse(encodedList);
+    if (!Array.isArray(raw) || raw.some((item) => typeof item !== "string")) {
+      throw new Error("Expected encoded effect array.");
+    }
+    return raw.map((encoded) => decodeBrowserInteractionEffect(encoded)).sort(
+      (a, b) => encodeBrowserInteractionEffect(a).localeCompare(
+        encodeBrowserInteractionEffect(b)
+      )
+    );
+  } catch {
+    diagnostics.push(
+      diagnosticFor({
+        code: "invalid-effect-payload",
+        message: "Invalid browser interaction semantic effect payload.",
+        ...context,
+        intent
+      })
+    );
+    return [];
+  }
+}
+function parseEffectPatternList(attributes, attribute, context, intent, diagnostics) {
+  const encodedList = optionalText(attributes, attribute);
+  if (encodedList === void 0) return [];
+  try {
+    const raw = JSON.parse(encodedList);
+    if (!Array.isArray(raw) || raw.some((item) => typeof item !== "string")) {
+      throw new Error("Expected encoded effect pattern array.");
+    }
+    return raw.map((encoded) => decodeBrowserInteractionEffectPattern(encoded)).sort(
+      (a, b) => encodeBrowserInteractionEffectPattern(a).localeCompare(
+        encodeBrowserInteractionEffectPattern(b)
+      )
+    );
+  } catch {
+    diagnostics.push(
+      diagnosticFor({
+        code: "invalid-effect-pattern",
+        message: "Invalid browser interaction semantic effect pattern.",
+        ...context,
+        intent
+      })
+    );
+    return [];
+  }
+}
+function parseCandidate(attributes, attribute, context, intent, diagnostics) {
+  const encoded = optionalText(attributes, attribute);
+  if (encoded === void 0) return void 0;
+  try {
+    const candidateValue = decodeCanonicalCandidateValue(encoded);
+    return {
+      candidateValue,
+      candidateValueKey: encodeCanonicalCandidateValue(candidateValue)
+    };
+  } catch {
+    diagnostics.push(
+      diagnosticFor({
+        code: "invalid-candidate",
+        message: `Invalid canonical browser interaction candidate '${encoded}'.`,
+        ...context,
+        intent
+      })
+    );
+    return void 0;
+  }
+}
+function getInteraction(surface, interactionKey, interactionId) {
+  const existing = surface.interactions.get(interactionKey);
+  if (existing) return existing;
+  const next = {
+    interactionKey,
+    interactionId,
+    readiness: "ready",
+    rootSeen: false,
+    actuators: [],
+    diagnostics: []
+  };
+  surface.interactions.set(interactionKey, next);
+  return next;
+}
+function finalizeSurface(surface) {
+  if (surface.kind !== "semantic") {
+    return {
+      surface: surface.surface,
+      scopeId: surface.scopeId,
+      diagnostics: surface.diagnostics.sort(compareDiagnostic)
+    };
+  }
+  const interactions = [
+    ...surface.interactions.values()
+  ].map((interaction) => ({
+    interactionKey: interaction.interactionKey,
+    interactionId: interaction.interactionId,
+    descriptorDigest: interaction.descriptorDigest,
+    draftDigest: interaction.draftDigest,
+    readiness: interaction.readiness,
+    actuators: interaction.actuators.sort(compareActuator),
+    diagnostics: interaction.diagnostics.sort(compareDiagnostic)
+  })).sort((a, b) => a.interactionKey.localeCompare(b.interactionKey));
+  return {
+    surface: surface.surface,
+    scopeId: surface.scopeId,
+    interactions,
+    diagnostics: surface.diagnostics.sort(compareDiagnostic)
+  };
+}
+function diagnosticsForPreparationCycles(surface, interaction) {
+  const diagnostics = [];
+  diagnostics.push(
+    ...diagnosticsForEffectPreparationCycles(surface, interaction)
+  );
+  const actuators = /* @__PURE__ */ new Map();
+  for (const actuator of interaction.actuators) {
+    actuators.set(
+      actuatorIdentityKey({
+        surface: surface.surface,
+        scopeId: surface.scopeId,
+        interactionKey: interaction.interactionKey,
+        actuator
+      }),
+      actuator
+    );
+  }
+  for (const actuator of interaction.actuators) {
+    const visited = /* @__PURE__ */ new Set();
+    let current = actuator;
+    while (current?.prepares) {
+      const key = actuatorIdentityKey({
+        surface: surface.surface,
+        scopeId: surface.scopeId,
+        interactionKey: interaction.interactionKey,
+        actuator: current
+      });
+      if (visited.has(key)) {
+        diagnostics.push(
+          diagnosticFor({
+            code: "preparation-cycle",
+            message: `Preparation cycle detected for actuator '${current.actuatorId}'.`,
+            surface: surface.surface,
+            scopeId: surface.scopeId,
+            interactionKey: interaction.interactionKey,
+            intent: current.intent,
+            actuatorId: current.actuatorId
+          })
+        );
+        break;
+      }
+      visited.add(key);
+      current = actuators.get(
+        targetIdentityKey({
+          surface: surface.surface,
+          scopeId: surface.scopeId,
+          interactionKey: interaction.interactionKey,
+          target: current.prepares
+        })
+      );
+    }
+  }
+  return diagnostics;
+}
+function diagnosticsForEffectPreparationCycles(surface, interaction) {
+  const diagnostics = [];
+  const actuatorKeys = /* @__PURE__ */ new Map();
+  interaction.actuators.forEach((actuator, index) => {
+    actuatorKeys.set(actuator, `${actuator.actuatorId}\0${index}`);
+  });
+  for (const actuator of interaction.actuators) {
+    const visited = /* @__PURE__ */ new Set();
+    let current = actuator;
+    while (current) {
+      const key = actuatorKeys.get(current);
+      if (!key) break;
+      if (visited.has(key)) {
+        diagnostics.push(
+          diagnosticFor({
+            code: "preparation-cycle",
+            message: `Semantic preparation cycle detected for actuator '${current.actuatorId}'.`,
+            surface: surface.surface,
+            scopeId: surface.scopeId,
+            interactionKey: interaction.interactionKey,
+            intent: current.intent,
+            actuatorId: current.actuatorId
+          })
+        );
+        break;
+      }
+      visited.add(key);
+      current = interaction.actuators.find(
+        (candidate) => current?.preparationPatterns.some(
+          (pattern) => candidate.semanticEffects.some(
+            (effect) => browserInteractionEffectPatternMatches(pattern, effect)
+          )
+        )
+      );
+    }
+  }
+  return diagnostics;
+}
+function diagnosticsForPreparationPatternAmbiguity(surface, interaction) {
+  const diagnostics = [];
+  for (const target of interaction.actuators) {
+    for (const effect of target.semanticEffects) {
+      const matches = interaction.actuators.filter(
+        (actuator) => actuator.preparationPatterns.some(
+          (pattern) => browserInteractionEffectPatternMatches(pattern, effect)
+        )
+      );
+      const uniqueActuatorIds = new Set(
+        matches.map((match) => match.actuatorId)
+      );
+      if (uniqueActuatorIds.size > 1) {
+        diagnostics.push(
+          diagnosticFor({
+            code: "ambiguous-preparation-pattern",
+            message: "Multiple preparation patterns can prepare the same semantic effect.",
+            surface: surface.surface,
+            scopeId: surface.scopeId,
+            interactionKey: interaction.interactionKey,
+            intent: target.intent,
+            actuatorId: target.actuatorId
+          })
+        );
+      }
+    }
+  }
+  return diagnostics;
+}
+function actuatorIdentityKey(input) {
+  return createBrowserInteractionActuatorKey({
+    surface: input.surface,
+    scopeId: input.scopeId,
+    interactionKey: input.interactionKey,
+    intent: input.actuator.intent,
+    inputKey: input.actuator.inputKey,
+    candidateValueKey: input.actuator.candidateValueKey,
+    actuatorKind: input.actuator.actuatorKind
+  });
+}
+function isSemanticSurfaceSnapshot(surface) {
+  return "interactions" in surface;
+}
+function targetIdentityKey(input) {
+  return createBrowserInteractionActuatorKey({
+    surface: input.surface,
+    scopeId: input.scopeId,
+    interactionKey: input.interactionKey,
+    intent: input.target.intent,
+    inputKey: input.target.inputKey,
+    candidateValueKey: input.target.candidateValueKey,
+    actuatorKind: input.target.actuatorKind ?? "click"
+  });
+}
+function pushSurfaceDiagnostic(surface, all, diagnostic) {
+  surface.diagnostics.push(diagnostic);
+  all.push(diagnostic);
+}
+function diagnosticFor(input) {
+  return { severity: "error", ...input };
+}
+function text(attributes, key) {
+  const value = attributes[key];
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return value ?? "";
+}
+function optionalText(attributes, key) {
+  const value = text(attributes, key);
+  return value === "" ? void 0 : value;
+}
+function parseReadiness(value) {
+  return BROWSER_INTERACTION_READINESS_VALUES.includes(
+    value
+  ) ? value : "blocked";
+}
+function parseCandidateState(value) {
+  return BROWSER_INTERACTION_CANDIDATE_STATES.includes(
+    value
+  ) ? value : void 0;
+}
+function parseActuatorKind(value) {
+  return parseOptionalActuatorKind(value) ?? "click";
+}
+function parseOptionalActuatorKind(value) {
+  return BROWSER_INTERACTION_ACTUATOR_KINDS.includes(
+    value
+  ) ? value : void 0;
+}
+function parseEnabled(value) {
+  if (value === false || value === "false") return false;
+  return true;
+}
+function compareSurface(a, b) {
+  return a.surface.localeCompare(b.surface) || a.scopeId.localeCompare(b.scopeId);
+}
+function compareActuator(a, b) {
+  return a.actuatorId.localeCompare(b.actuatorId);
+}
+function compareDiagnostic(a, b) {
+  return a.code.localeCompare(b.code) || (a.surface ?? "").localeCompare(b.surface ?? "") || (a.scopeId ?? "").localeCompare(b.scopeId ?? "") || (a.interactionKey ?? "").localeCompare(b.interactionKey ?? "") || (a.intent ?? "").localeCompare(b.intent ?? "") || (a.actuatorId ?? "").localeCompare(b.actuatorId ?? "") || a.message.localeCompare(b.message);
+}
+
+// src/browser-interaction/resolve.ts
+function resolveBrowserInteractionIntent(snapshot, request) {
+  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) : void 0);
+  const surfaces = snapshot.surfaces.filter(
+    (surface) => isSemanticSurfaceSnapshot(surface) && surface.surface === request.surface && (request.scopeId === void 0 || surface.scopeId === request.scopeId)
+  );
+  const matches = surfaces.flatMap(
+    (surface) => surface.interactions.flatMap((interaction) => {
+      if (request.interactionKey !== void 0 && interaction.interactionKey !== request.interactionKey) {
+        return [];
+      }
+      if (request.interactionId !== void 0 && 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) => diagnosticFor2({
+          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: [
+        diagnosticFor2({
+          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: [
+      diagnosticFor2({
+        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
+      })
+    ]
+  };
+}
+function resolveBrowserInteractionEffect(snapshot, request) {
+  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: [
+        diagnosticFor2({
+          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: [
+      diagnosticFor2({
+        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, request, candidateValueKey) {
+  return actuator.intent === request.intent && (request.inputKey === void 0 || actuator.inputKey === request.inputKey) && (candidateValueKey === void 0 || actuator.candidateValueKey === candidateValueKey) && (request.actuatorKind === void 0 || actuator.actuatorKind === request.actuatorKind);
+}
+function findPreparationChain(surfaces, request, candidateValueKey) {
+  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 === void 0 || actuator.prepares.inputKey === targetRequest.inputKey) && (targetRequest.candidateValueKey === void 0 || actuator.prepares.candidateValueKey === targetRequest.candidateValueKey) && (targetRequest.actuatorKind === void 0 || 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, interaction, actuator) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const candidate of interaction.actuators) {
+    byKey.set(
+      actuatorIdentityKey({
+        surface: surface.surface,
+        scopeId: surface.scopeId,
+        interactionKey: interaction.interactionKey,
+        actuator: candidate
+      }),
+      candidate
+    );
+  }
+  const chain = [];
+  const visited = /* @__PURE__ */ new Set();
+  let current = 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
+      })
+    ) : void 0;
+  }
+  return chain;
+}
+function interactionMatchesRequest(interaction, request) {
+  return (request.interactionKey === void 0 || interaction.interactionKey === request.interactionKey) && (request.interactionId === void 0 || interaction.interactionId === request.interactionId);
+}
+function matchingSurfaces(snapshot, request) {
+  return snapshot.surfaces.filter(
+    (surface) => isSemanticSurfaceSnapshot(surface) && surface.surface === request.surface && (request.scopeId === void 0 || surface.scopeId === request.scopeId)
+  );
+}
+function collectInteractionMatches(surfaces, request) {
+  return surfaces.flatMap(
+    (surface) => surface.interactions.flatMap((interaction) => {
+      if (request.interactionKey !== void 0 && interaction.interactionKey !== request.interactionKey) {
+        return [];
+      }
+      if (request.interactionId !== void 0 && interaction.interactionId !== request.interactionId) {
+        return [];
+      }
+      return interaction.actuators.map((actuator) => ({
+        surface,
+        interaction,
+        actuator
+      }));
+    })
+  );
+}
+function effectSuccess(match, effect, kind) {
+  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, code, message) {
+  return {
+    ok: false,
+    code: "ambiguous",
+    diagnostics: matches.map(
+      (match) => diagnosticFor2({
+        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, code, message) {
+  return {
+    ok: false,
+    code: "unavailable",
+    diagnostics: [
+      diagnosticFor2({
+        code,
+        message,
+        surface: request.surface,
+        scopeId: request.scopeId,
+        interactionKey: request.interactionKey
+      })
+    ]
+  };
+}
+function findEffectPreparationChain(surfaces, request) {
+  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) => diagnosticFor2({
+          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, request) {
+  if (!effect || typeof effect.kind !== "string" || effect.kind.length === 0) {
+    return [
+      diagnosticFor2({
+        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 [
+        diagnosticFor2({
+          code: "invalid-scalar-argument",
+          message: "setScalar browser interaction effects require a finite value.",
+          surface: request.surface,
+          scopeId: request.scopeId,
+          interactionKey: request.interactionKey
+        })
+      ];
+    }
+  }
+  return [];
+}
+function diagnosticFor2(input) {
+  return { severity: "error", ...input };
+}
+
+// src/browser-interaction/schemas.ts
+import { z } from "zod";
+var jsonValueSchema = z.lazy(
+  () => z.union([
+    z.null(),
+    z.boolean(),
+    z.number().finite(),
+    z.string(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema)
+  ])
+);
+var browserInteractionEffectSchema = z.object({
+  kind: z.string().min(1)
+}).catchall(jsonValueSchema);
+var browserInteractionEffectPatternSchema = z.union([
+  z.object({
+    kind: z.literal("exact"),
+    effect: browserInteractionEffectSchema
+  }),
+  z.object({
+    kind: z.literal("match"),
+    effectKind: z.string().min(1),
+    fields: z.record(z.string(), jsonValueSchema).optional(),
+    scalar: z.object({
+      field: z.string().min(1),
+      min: z.number().finite().optional(),
+      max: z.number().finite().optional(),
+      integer: z.boolean().optional()
+    }).optional()
+  })
+]);
+var gameplaySemanticEffectSchema = z.union([
+  z.object({
+    kind: z.literal("setCandidate"),
+    inputKey: z.string(),
+    candidateValue: jsonValueSchema,
+    beforeSelected: z.boolean(),
+    afterSelected: z.boolean()
+  }),
+  z.object({
+    kind: z.literal("adjustResource"),
+    inputKey: z.string(),
+    resourceKey: jsonValueSchema,
+    delta: z.union([z.literal(-1), z.literal(1)])
+  }),
+  z.object({
+    kind: z.literal("setScalar"),
+    inputKey: z.string(),
+    value: z.number().finite()
+  }),
+  z.object({
+    kind: z.literal("commit")
+  }),
+  z.object({
+    kind: z.literal("invoke")
+  })
+]);
+var browserInteractionDiagnosticSchema = z.object({
+  code: z.string(),
+  severity: z.enum(["error", "warning"]),
+  message: z.string(),
+  surface: z.string().optional(),
+  scopeId: z.string().optional(),
+  interactionKey: z.string().optional(),
+  intent: z.string().optional(),
+  actuatorId: z.string().optional()
+});
+var browserInteractionActuatorSchema = z.object({
+  actuatorId: z.string(),
+  intent: z.string(),
+  inputKey: z.string().optional(),
+  candidateValue: jsonValueSchema.optional(),
+  candidateValueKey: z.string().optional(),
+  candidateState: z.enum(BROWSER_INTERACTION_CANDIDATE_STATES).optional(),
+  enabled: z.boolean(),
+  actuatorKind: z.enum(BROWSER_INTERACTION_ACTUATOR_KINDS),
+  semanticEffects: z.array(browserInteractionEffectSchema),
+  acceptedEffectPatterns: z.array(browserInteractionEffectPatternSchema),
+  preparationPatterns: z.array(browserInteractionEffectPatternSchema),
+  prepares: z.object({
+    intent: z.string(),
+    inputKey: z.string().optional(),
+    candidateValue: jsonValueSchema.optional(),
+    candidateValueKey: z.string().optional(),
+    actuatorKind: z.enum(BROWSER_INTERACTION_ACTUATOR_KINDS).optional()
+  }).optional(),
+  diagnostics: z.array(browserInteractionDiagnosticSchema)
+});
+var browserGameplayInteractionSchema = z.object({
+  interactionKey: z.string(),
+  interactionId: z.string(),
+  descriptorDigest: z.string().optional(),
+  draftDigest: z.string().optional(),
+  readiness: z.enum(BROWSER_INTERACTION_READINESS_VALUES),
+  actuators: z.array(browserInteractionActuatorSchema),
+  diagnostics: z.array(browserInteractionDiagnosticSchema)
+});
+var browserGameplaySurfaceSnapshotSchema = z.object({
+  surface: z.literal(GAMEPLAY_BROWSER_INTERACTION_SURFACE),
+  scopeId: z.string(),
+  interactions: z.array(browserGameplayInteractionSchema),
+  diagnostics: z.array(browserInteractionDiagnosticSchema)
+});
+var browserSemanticSurfaceSnapshotSchema = z.object({
+  surface: z.string(),
+  scopeId: z.string(),
+  interactions: z.array(browserGameplayInteractionSchema),
+  diagnostics: z.array(browserInteractionDiagnosticSchema)
+});
+var browserUnknownSurfaceSnapshotSchema = z.object({
+  surface: z.string(),
+  scopeId: z.string(),
+  diagnostics: z.array(browserInteractionDiagnosticSchema)
+});
+var browserInteractionSnapshotSchema = z.object({
+  protocol: z.object({
+    name: z.literal(DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_NAME),
+    version: z.literal(DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION)
+  }),
+  surfaces: z.array(
+    z.union([
+      browserSemanticSurfaceSnapshotSchema,
+      browserUnknownSurfaceSnapshotSchema
+    ])
+  ),
+  diagnostics: z.array(browserInteractionDiagnosticSchema)
+});
+
+export {
+  DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_NAME,
+  DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
+  BROWSER_INTERACTION_ATTRIBUTES,
+  BROWSER_INTERACTION_RECORD_ROLES,
+  GAMEPLAY_BROWSER_INTERACTION_SURFACE,
+  GAMEPLAY_BROWSER_INTERACTION_INTENTS,
+  GAMEPLAY_BROWSER_INTERACTION_EFFECT_KINDS,
+  BROWSER_INTERACTION_READINESS_VALUES,
+  BROWSER_INTERACTION_CANDIDATE_STATES,
+  BROWSER_INTERACTION_ACTUATOR_KINDS,
+  encodeCanonicalCandidateValue,
+  decodeCanonicalCandidateValue,
+  compareStableJson,
+  encodeBrowserInteractionEffect,
+  decodeBrowserInteractionEffect,
+  encodeBrowserInteractionEffectPattern,
+  decodeBrowserInteractionEffectPattern,
+  browserInteractionEffectPatternMatches,
+  assertBrowserInteractionEffectPattern,
+  gameplaySetCandidateEffect,
+  gameplayAdjustResourceEffect,
+  gameplaySetScalarEffect,
+  gameplayCommitEffect,
+  gameplayInvokeEffect,
+  createBrowserInteractionRootAttributes,
+  createBrowserInteractionActuatorAttributes,
+  createGameplayInteractionRootAttributes,
+  createGameplayActuatorAttributes,
+  createBrowserInteractionActuatorKey,
+  defineBrowserInteractionSurface,
+  gameplayBrowserInteractionSurface,
+  createBrowserInteractionRegistry,
+  defaultBrowserInteractionRegistry,
+  normalizeBrowserInteractionRecords,
+  validateBrowserInteractionSnapshot,
+  actuatorIdentityKey,
+  isSemanticSurfaceSnapshot,
+  targetIdentityKey,
+  resolveBrowserInteractionIntent,
+  resolveBrowserInteractionEffect,
+  browserInteractionEffectSchema,
+  browserInteractionEffectPatternSchema,
+  gameplaySemanticEffectSchema,
+  browserInteractionDiagnosticSchema,
+  browserInteractionActuatorSchema,
+  browserGameplayInteractionSchema,
+  browserGameplaySurfaceSnapshotSchema,
+  browserSemanticSurfaceSnapshotSchema,
+  browserUnknownSurfaceSnapshotSchema,
+  browserInteractionSnapshotSchema
+};
+//# sourceMappingURL=chunk-QLG6VEMW.js.map