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

package/dist/testing.js

@@ -2,6 +2,14 @@ import {
   StaleContractArtifactError,
   isStaleContractArtifactError
 } from "./chunk-3OZMHZK3.js";
+import {
+  BROWSER_INTERACTION_ACTUATOR_KINDS,
+  DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
+  browserInteractionEffectSchema
+} from "./chunk-MALRKLRR.js";
+import {
+  RuntimeJsonSchema
+} from "./chunk-AEUXCFGM.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/testing/definitions.ts
@@ -666,12 +674,484 @@ function createTestRuntime(options) {
     setControllingPlayer
   };
 }
+
+// src/testing/ui-fixture/canonical.ts
+import { createHash } from "crypto";
+var sha256DigestPattern = /^sha256:[a-f0-9]{64}$/;
+function isSha256Digest(value) {
+  return sha256DigestPattern.test(value);
+}
+function canonicalizeUIFixtureJson(value) {
+  if (value === null) {
+    return null;
+  }
+  switch (typeof value) {
+    case "boolean":
+    case "string":
+      return value;
+    case "number":
+      if (Number.isFinite(value)) {
+        return value;
+      }
+      break;
+    case "object": {
+      if (Array.isArray(value)) {
+        return value.map((item) => canonicalizeUIFixtureJson(item));
+      }
+      if (Object.getPrototypeOf(value) !== Object.prototype) {
+        break;
+      }
+      const entries = Object.entries(value);
+      return Object.fromEntries(
+        entries.filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, canonicalizeUIFixtureJson(item)])
+      );
+    }
+  }
+  throw new Error(
+    `UI fixture values must be deterministic JSON. Received ${typeof value}.`
+  );
+}
+function canonicalUIFixtureJson(value) {
+  return JSON.stringify(canonicalizeUIFixtureJson(value));
+}
+function digestUIFixtureJson(value) {
+  return sha256(canonicalUIFixtureJson(value));
+}
+function digestUIFixtureRequest(request) {
+  return digestUIFixtureJson({
+    digestVersion: "ui-replay-request@1",
+    request
+  });
+}
+function canonicalizeUIScenarioFixture(fixture) {
+  return canonicalizeUIFixtureJson({
+    ...fixture,
+    tags: [...fixture.tags].sort(),
+    environment: {
+      ...fixture.environment,
+      viewportTags: [...fixture.environment.viewportTags].sort()
+    }
+  });
+}
+function serializeUIScenarioFixture(fixture) {
+  return `${JSON.stringify(canonicalizeUIScenarioFixture(fixture), null, 2)}
+`;
+}
+function digestUIScenarioFixture(fixture) {
+  return sha256(serializeUIScenarioFixture(fixture));
+}
+function sha256(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+// src/testing/ui-fixture/schema.ts
+import { z } from "zod";
+var UI_SCENARIO_FIXTURE_SCHEMA_VERSION = 1;
+var UI_SCENARIO_FIXTURE_BUNDLE_SCHEMA_VERSION = 1;
+var UI_SCENARIO_FIXTURE_SUPPORTED_BROWSER_PROTOCOL_MAJOR = 2;
+var digestSchema = z.string().refine(isSha256Digest, {
+  message: "Expected a sha256:<64 lowercase hex> digest."
+});
+var nonEmptyStringSchema = z.string().min(1);
+var jsonSchema = RuntimeJsonSchema;
+var environmentSchema = z.object({
+  clockIso: nonEmptyStringSchema,
+  randomSeed: nonEmptyStringSchema,
+  locale: z.literal("en-US"),
+  timezone: z.literal("UTC"),
+  viewportTags: z.array(z.enum(["desktop", "tablet", "phone", "touch"]))
+}).strict();
+var pluginSessionSchema = z.object({
+  sessionId: nonEmptyStringSchema,
+  controllablePlayerIds: z.array(nonEmptyStringSchema),
+  controllingPlayerId: nonEmptyStringSchema.nullable(),
+  userId: nonEmptyStringSchema.nullable()
+}).catchall(jsonSchema);
+var gameplaySnapshotSchema = z.object({
+  currentPhase: nonEmptyStringSchema.nullable(),
+  currentStage: nonEmptyStringSchema.nullable(),
+  activePlayers: z.array(nonEmptyStringSchema),
+  simultaneousPhase: jsonSchema.nullable().optional(),
+  availableInteractions: z.array(jsonSchema),
+  zones: z.record(z.string(), jsonSchema)
+}).catchall(jsonSchema);
+var uiFixturePluginStateSnapshotSchema = z.object({
+  view: jsonSchema.nullable(),
+  gameplay: gameplaySnapshotSchema,
+  lobby: jsonSchema.nullable(),
+  notifications: z.array(jsonSchema),
+  session: pluginSessionSchema,
+  history: jsonSchema.nullable(),
+  syncId: z.number().int().nonnegative()
+}).strict();
+var uiFixtureFrameSchema = z.object({
+  id: nonEmptyStringSchema,
+  snapshot: uiFixturePluginStateSnapshotSchema,
+  projectionDigest: digestSchema
+}).strict();
+var uiFixtureTransportExchangeSchema = z.object({
+  id: nonEmptyStringSchema,
+  fromFrameId: nonEmptyStringSchema,
+  operation: z.enum(["validate", "submit", "refresh"]),
+  requestDigest: digestSchema,
+  response: z.union([
+    z.object({
+      kind: z.literal("accepted"),
+      nextFrameId: nonEmptyStringSchema
+    }).strict(),
+    z.object({
+      kind: z.literal("rejected"),
+      diagnostics: z.array(
+        z.object({
+          code: nonEmptyStringSchema,
+          message: nonEmptyStringSchema
+        }).strict()
+      )
+    }).strict()
+  ])
+}).strict();
+var browserInteractionIntentRequestSchema = z.object({
+  surface: nonEmptyStringSchema,
+  scopeId: nonEmptyStringSchema.optional(),
+  interactionKey: nonEmptyStringSchema.optional(),
+  interactionId: nonEmptyStringSchema.optional(),
+  intent: nonEmptyStringSchema,
+  inputKey: nonEmptyStringSchema.optional(),
+  candidateValue: jsonSchema.optional(),
+  candidateValueKey: nonEmptyStringSchema.optional(),
+  actuatorKind: z.enum(BROWSER_INTERACTION_ACTUATOR_KINDS).optional(),
+  allowDisabled: z.boolean().optional()
+}).strict();
+var browserInteractionEffectRequestSchema = z.object({
+  surface: nonEmptyStringSchema,
+  scopeId: nonEmptyStringSchema.optional(),
+  interactionKey: nonEmptyStringSchema.optional(),
+  interactionId: nonEmptyStringSchema.optional(),
+  effect: browserInteractionEffectSchema,
+  allowDisabled: z.boolean().optional()
+}).strict();
+var uiReplayRequestSchema = z.union([
+  browserInteractionIntentRequestSchema,
+  browserInteractionEffectRequestSchema
+]);
+var uiReplayExecutionSchema = z.union([
+  z.object({
+    kind: z.literal("activate")
+  }).strict(),
+  z.object({
+    kind: z.literal("fill"),
+    value: z.string()
+  }).strict(),
+  z.object({
+    kind: z.literal("drag"),
+    target: browserInteractionEffectRequestSchema
+  }).strict()
+]);
+var uiStepExpectationSchema = z.object({
+  frameId: nonEmptyStringSchema.optional(),
+  projectionDigest: digestSchema.optional(),
+  semanticDigest: digestSchema.optional(),
+  draftDigest: digestSchema.optional(),
+  submissionDigest: digestSchema.optional(),
+  focusedInteractionKey: nonEmptyStringSchema.optional(),
+  visibleInteractionKeys: z.array(nonEmptyStringSchema).optional()
+}).strict();
+var uiResolvedReplayIdentitySchema = z.object({
+  stepId: nonEmptyStringSchema,
+  surface: nonEmptyStringSchema,
+  scopeId: nonEmptyStringSchema,
+  interactionKey: nonEmptyStringSchema,
+  interactionId: nonEmptyStringSchema,
+  actuatorId: nonEmptyStringSchema,
+  descriptorDigest: digestSchema.optional(),
+  draftDigest: digestSchema.optional()
+}).strict();
+var portableSemanticReplayStepSchema = z.object({
+  stepId: nonEmptyStringSchema,
+  requestDigest: digestSchema,
+  resolve: uiReplayRequestSchema,
+  execute: uiReplayExecutionSchema,
+  expectedIdentity: uiResolvedReplayIdentitySchema.optional(),
+  expect: uiStepExpectationSchema
+}).strict();
+var uiScenarioReplayStepSchema = z.union([
+  portableSemanticReplayStepSchema,
+  z.object({
+    stepId: nonEmptyStringSchema,
+    kind: z.literal("assert"),
+    expect: uiStepExpectationSchema
+  }).strict()
+]);
+var uiScenarioFixtureSchema = z.object({
+  schemaVersion: z.literal(UI_SCENARIO_FIXTURE_SCHEMA_VERSION),
+  browserInteractionProtocol: z.literal(
+    DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION
+  ),
+  id: nonEmptyStringSchema,
+  title: nonEmptyStringSchema,
+  gameId: nonEmptyStringSchema,
+  tags: z.array(nonEmptyStringSchema),
+  source: z.object({
+    scenarioId: nonEmptyStringSchema,
+    reducerFingerprint: nonEmptyStringSchema,
+    uiContractFingerprint: nonEmptyStringSchema,
+    renderModule: nonEmptyStringSchema,
+    renderModuleDigest: digestSchema,
+    sourceDigest: digestSchema
+  }).strict(),
+  viewer: z.object({
+    seatId: nonEmptyStringSchema,
+    playerId: nonEmptyStringSchema.optional()
+  }).strict(),
+  environment: environmentSchema,
+  frames: z.array(uiFixtureFrameSchema).min(1),
+  transport: z.array(uiFixtureTransportExchangeSchema),
+  replay: z.array(uiScenarioReplayStepSchema),
+  expected: z.object({
+    initialProjectionDigest: digestSchema,
+    finalProjectionDigest: digestSchema,
+    finalSemanticDigest: digestSchema,
+    submissionDigest: digestSchema
+  }).strict()
+}).strict();
+var uiScenarioFixtureBundleIndexSchema = z.object({
+  schemaVersion: z.literal(UI_SCENARIO_FIXTURE_BUNDLE_SCHEMA_VERSION),
+  bundleId: nonEmptyStringSchema,
+  sdkCommit: nonEmptyStringSchema,
+  browserInteractionProtocol: z.literal(
+    DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION
+  ),
+  fixtures: z.array(
+    z.object({
+      id: nonEmptyStringSchema,
+      file: nonEmptyStringSchema,
+      sha256: digestSchema,
+      renderModule: nonEmptyStringSchema,
+      renderModuleSha256: digestSchema,
+      components: z.array(nonEmptyStringSchema),
+      capabilities: z.array(nonEmptyStringSchema)
+    }).strict()
+  )
+}).strict();
+function parseUIScenarioFixture(value) {
+  const fixture = uiScenarioFixtureSchema.parse(
+    value
+  );
+  validateUIScenarioFixtureReferences(fixture);
+  return fixture;
+}
+function parseUIScenarioFixtureBundleIndex(value) {
+  const bundle = uiScenarioFixtureBundleIndexSchema.parse(value);
+  assertSupportedBrowserInteractionProtocol(bundle.browserInteractionProtocol);
+  const ids = /* @__PURE__ */ new Set();
+  for (const entry of bundle.fixtures) {
+    if (ids.has(entry.id)) {
+      throw new Error(`Duplicate fixture id '${entry.id}' in bundle index.`);
+    }
+    ids.add(entry.id);
+  }
+  return bundle;
+}
+function assertSupportedBrowserInteractionProtocol(version) {
+  const major = Number(version.split(".")[0]);
+  if (major !== UI_SCENARIO_FIXTURE_SUPPORTED_BROWSER_PROTOCOL_MAJOR) {
+    throw new Error(
+      `Unsupported browser-interaction protocol '${version}'. Expected major ${UI_SCENARIO_FIXTURE_SUPPORTED_BROWSER_PROTOCOL_MAJOR}.`
+    );
+  }
+}
+function validateUIScenarioFixtureReferences(fixture) {
+  assertSupportedBrowserInteractionProtocol(fixture.browserInteractionProtocol);
+  const frameIds = /* @__PURE__ */ new Set();
+  for (const frame of fixture.frames) {
+    if (frameIds.has(frame.id)) {
+      throw new Error(`Duplicate fixture frame id '${frame.id}'.`);
+    }
+    frameIds.add(frame.id);
+  }
+  for (const exchange of fixture.transport) {
+    if (!frameIds.has(exchange.fromFrameId)) {
+      throw new Error(
+        `Transport exchange '${exchange.id}' references missing fromFrameId '${exchange.fromFrameId}'.`
+      );
+    }
+    if (exchange.response.kind === "accepted" && !frameIds.has(exchange.response.nextFrameId)) {
+      throw new Error(
+        `Transport exchange '${exchange.id}' references missing nextFrameId '${exchange.response.nextFrameId}'.`
+      );
+    }
+  }
+  for (const step of fixture.replay) {
+    if ("resolve" in step) {
+      const actualDigest = digestUIFixtureRequest(
+        step.resolve
+      );
+      if (step.requestDigest !== actualDigest) {
+        throw new Error(
+          `Replay step '${step.stepId}' requestDigest ${step.requestDigest} does not match ${actualDigest}.`
+        );
+      }
+    }
+    const expectedFrameId = step.expect.frameId;
+    if (expectedFrameId && !frameIds.has(expectedFrameId)) {
+      throw new Error(
+        `Replay step '${step.stepId}' expects missing frameId '${expectedFrameId}'.`
+      );
+    }
+  }
+}
+
+// src/testing/ui-fixture/compiler.ts
+function compileUIScenarioFixture(options) {
+  const firstFrame = options.frames[0];
+  const finalFrame = options.frames[options.frames.length - 1];
+  if (!firstFrame || !finalFrame) {
+    throw new Error("compileUIScenarioFixture requires at least one frame.");
+  }
+  const replay = options.replay ?? [];
+  const submissionDigest = options.expected?.submissionDigest ?? digestUIFixtureJson({
+    digestVersion: "ui-submission@1",
+    fixtureId: options.id,
+    replay: replay.map(
+      (step) => "requestDigest" in step ? step.requestDigest : step.stepId
+    )
+  });
+  const finalSemanticDigest = options.expected?.finalSemanticDigest ?? digestUIFixtureJson({
+    digestVersion: "ui-semantic@1",
+    fixtureId: options.id,
+    frameId: finalFrame.id,
+    projectionDigest: finalFrame.projectionDigest
+  });
+  return parseUIScenarioFixture(
+    canonicalizeUIScenarioFixture({
+      schemaVersion: 1,
+      browserInteractionProtocol: DREAMBOARD_BROWSER_INTERACTION_PROTOCOL_VERSION,
+      id: options.id,
+      title: options.title,
+      gameId: options.gameId,
+      tags: [...options.tags ?? []],
+      source: options.source,
+      viewer: options.viewer,
+      environment: options.environment,
+      frames: options.frames,
+      transport: [...options.transport ?? []],
+      replay,
+      expected: {
+        initialProjectionDigest: options.expected?.initialProjectionDigest ?? firstFrame.projectionDigest,
+        finalProjectionDigest: options.expected?.finalProjectionDigest ?? finalFrame.projectionDigest,
+        finalSemanticDigest,
+        submissionDigest
+      }
+    })
+  );
+}
+function assertDeterministicUIScenarioFixture(first, second) {
+  const firstBytes = serializeUIScenarioFixture(first);
+  const secondBytes = serializeUIScenarioFixture(second);
+  if (firstBytes !== secondBytes) {
+    throw new Error(
+      `UI scenario fixture '${first.id}' is non-deterministic across compilation runs.`
+    );
+  }
+}
+function assertUniqueReplayIdentity(step, candidates) {
+  if (candidates.length !== 1) {
+    throw new Error(
+      `Replay step '${step.stepId}' resolved ${candidates.length} identities; expected exactly one.`
+    );
+  }
+  const candidate = candidates[0];
+  if (!candidate) {
+    throw new Error(`Replay step '${step.stepId}' did not resolve.`);
+  }
+  const expected = step.expectedIdentity;
+  if (!expected) {
+    return candidate;
+  }
+  for (const key of [
+    "surface",
+    "scopeId",
+    "interactionKey",
+    "interactionId",
+    "actuatorId",
+    "descriptorDigest",
+    "draftDigest"
+  ]) {
+    const expectedValue = expected[key];
+    if (expectedValue !== void 0 && candidate[key] !== expectedValue) {
+      throw new Error(
+        `Replay step '${step.stepId}' resolved ${key} '${String(
+          candidate[key]
+        )}', expected '${expectedValue}'.`
+      );
+    }
+  }
+  return candidate;
+}
+function assertUIStepExpectationSatisfied(stepId, expected, actual) {
+  for (const key of [
+    "frameId",
+    "projectionDigest",
+    "semanticDigest",
+    "draftDigest",
+    "submissionDigest",
+    "focusedInteractionKey"
+  ]) {
+    if (expected[key] !== void 0 && expected[key] !== actual[key]) {
+      throw new Error(
+        `Replay step '${stepId}' expected ${key} '${expected[key]}', received '${actual[key]}'.`
+      );
+    }
+  }
+  if (expected.visibleInteractionKeys) {
+    const actualKeys = new Set(actual.visibleInteractionKeys ?? []);
+    const missing = expected.visibleInteractionKeys.filter(
+      (key) => !actualKeys.has(key)
+    );
+    if (missing.length > 0) {
+      throw new Error(
+        `Replay step '${stepId}' missing visible interactions: ${missing.join(
+          ", "
+        )}.`
+      );
+    }
+  }
+}
 export {
   StaleContractArtifactError,
+  UI_SCENARIO_FIXTURE_BUNDLE_SCHEMA_VERSION,
+  UI_SCENARIO_FIXTURE_SCHEMA_VERSION,
+  UI_SCENARIO_FIXTURE_SUPPORTED_BROWSER_PROTOCOL_MAJOR,
+  assertDeterministicUIScenarioFixture,
+  assertSupportedBrowserInteractionProtocol,
+  assertUIStepExpectationSatisfied,
+  assertUniqueReplayIdentity,
+  canonicalUIFixtureJson,
+  canonicalizeUIFixtureJson,
+  canonicalizeUIScenarioFixture,
+  compileUIScenarioFixture,
   createExpectApi,
   createTestRuntime,
   defineBase,
   defineScenario,
-  isStaleContractArtifactError
+  digestUIFixtureJson,
+  digestUIFixtureRequest,
+  digestUIScenarioFixture,
+  isSha256Digest,
+  isStaleContractArtifactError,
+  parseUIScenarioFixture,
+  parseUIScenarioFixtureBundleIndex,
+  portableSemanticReplayStepSchema,
+  serializeUIScenarioFixture,
+  uiFixtureFrameSchema,
+  uiFixturePluginStateSnapshotSchema,
+  uiFixtureTransportExchangeSchema,
+  uiReplayExecutionSchema,
+  uiReplayRequestSchema,
+  uiResolvedReplayIdentitySchema,
+  uiScenarioFixtureBundleIndexSchema,
+  uiScenarioFixtureSchema,
+  uiScenarioReplayStepSchema,
+  uiStepExpectationSchema
 };
 //# sourceMappingURL=testing.js.map