state-scenarios 0.2.0 → 0.3.0

package/dist/chunk-HEVJQ47T.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/save.ts"],"sourcesContent":["import { existsSync, mkdirSync, writeFileSync } from 'node:fs';\nimport { createServer, type IncomingMessage, type ServerResponse } from 'node:http';\nimport { join, relative } from 'node:path';\nimport { z } from 'zod';\nimport { SAVE_ENDPOINT } from './link.js';\nimport { JsonSchema, ScenarioSchema } from './schema.js';\n\n// The panel's \"Save to project\" endpoint, shared by the Vite plugin and the Next.js route.\n\nconst MAX_BODY = 20 * 1024 * 1024;\n\nconst SaveRequestSchema = z.object({ scenario: JsonSchema, overwrite: z.boolean().optional() });\n\ninterface SaveReply {\n  error?: string;\n  /** Saved file, relative to the project root. */\n  path?: string;\n  /** Saved file, absolute. */\n  file?: string;\n  /** Scenarios folder, relative to the project root. */\n  dir?: string;\n}\n\nexport interface SaveTarget {\n  /** Absolute folder scenarios are written into. */\n  dir: string;\n  /** Absolute project root; replies show paths relative to it. */\n  root: string;\n  /** Page origins allowed to save cross-origin. Without it, only same-origin requests may. */\n  origins?: string[];\n}\n\n/**\n * GET reports the folder; POST `{ scenario, overwrite? }` writes `<dir>/<name>.json`.\n * JSON from an allowed origin on a loopback host only, schema-checked, and never replaces a\n * file unless `overwrite` is set.\n */\nexport async function handleSaveRequest(\n  request: Request,\n  { dir, root, origins }: SaveTarget,\n): Promise<Response> {\n  const display = (file: string) => relative(root, file).replaceAll('\\\\', '/');\n  const reply = (status: number, body: SaveReply) => Response.json(body, { status });\n\n  if (!allowedOrigin(request.headers, origins)) {\n    return reply(403, { error: 'Save refused: only the app on localhost may write files' });\n  }\n\n  if (request.method === 'GET') return reply(200, { dir: display(dir) });\n\n  if (request.method !== 'POST') return reply(405, { error: 'Use GET or POST' });\n\n  // A JSON content type also forces a CORS preflight, which only allowed origins pass.\n  if (!request.headers.get('content-type')?.startsWith('application/json')) {\n    return reply(415, { error: 'Send application/json' });\n  }\n\n  let body: z.output<typeof SaveRequestSchema>;\n\n  try {\n    body = SaveRequestSchema.parse(JSON.parse(await readCapped(request)));\n  } catch (err) {\n    return reply(400, { error: err instanceof z.ZodError ? z.prettifyError(err) : String(err) });\n  }\n\n  // The schema's kebab-case name rule also keeps the file inside `dir`.\n  const parsed = ScenarioSchema.safeParse(body.scenario);\n\n  if (!parsed.success) return reply(400, { error: z.prettifyError(parsed.error) });\n\n  const { name } = parsed.data;\n\n  if (name.includes(',')) return reply(400, { error: \"A saved scenario name can't contain a comma\" });\n\n  const file = join(dir, `${name}.json`);\n\n  if (existsSync(file) && !body.overwrite) {\n    return reply(409, { error: `${display(file)} already exists`, path: display(file) });\n  }\n\n  mkdirSync(dir, { recursive: true });\n  // Write what the panel sent, not the parsed form, so defaults don't bloat the file.\n  writeFileSync(file, `${JSON.stringify(body.scenario, null, 2)}\\n`);\n\n  return reply(200, { path: display(file), file });\n}\n\n/**\n * The save endpoint as Node middleware. Headers can be forged by any client and the socket\n * can't, so only connections from this machine reach the handler.\n */\nexport function createSaveHandler(target: SaveTarget) {\n  return async (req: IncomingMessage, res: ServerResponse) => {\n    const origin = req.headers.origin;\n\n    // Cross-origin saves (the Next.js save server) need CORS for the origins the target allows.\n    if (origin && target.origins?.includes(origin)) {\n      res.setHeader('access-control-allow-origin', origin);\n      res.setHeader('vary', 'origin');\n    }\n\n    if (req.method === 'OPTIONS') {\n      res.setHeader('access-control-allow-methods', 'GET, POST');\n      res.setHeader('access-control-allow-headers', 'content-type');\n      res.statusCode = 204;\n      res.end();\n\n      return;\n    }\n\n    let response: Response;\n\n    try {\n      response = isLoopbackAddress(req.socket.remoteAddress)\n        ? await handleSaveRequest(toRequest(req), target)\n        : Response.json({ error: 'Save refused: only this machine may write files' }, { status: 403 });\n    } catch (err) {\n      // A bad Host header or a dropped connection: answer rather than leave the request hanging.\n      response = Response.json({ error: String(err) }, { status: 500 });\n    }\n\n    res.statusCode = response.status;\n    response.headers.forEach((value, key) => res.setHeader(key, value));\n    res.end(await response.text());\n  };\n}\n\n/**\n * Start a save server on 127.0.0.1, unreachable from other machines whatever the app server\n * listens on. Resolves to its save URL.\n */\nexport function startSaveServer(target: SaveTarget): Promise<string> {\n  const handle = createSaveHandler(target);\n  const server = createServer((req, res) => void handle(req, res));\n\n  return new Promise((done, fail) => {\n    server.once('error', fail);\n    server.listen(0, '127.0.0.1', () => {\n      const { port } = z.object({ port: z.number() }).parse(server.address());\n      server.unref(); // never keeps the dev process alive on its own\n      done(`http://127.0.0.1:${port}${SAVE_ENDPOINT}`);\n    });\n  });\n}\n\n/** True for a loopback peer address, as Node reports it in `socket.remoteAddress`. */\nexport function isLoopbackAddress(address: string | undefined): boolean {\n  if (!address) return false;\n  const ip = address.replace(/^::ffff:/, '');\n\n  return ip === '::1' || /^127(\\.\\d{1,3}){3}$/.test(ip);\n}\n\nfunction allowedOrigin(headers: Headers, origins: string[] | undefined): boolean {\n  const host = headers.get('host') ?? '';\n\n  // DNS rebinding points an attacker's domain at 127.0.0.1, making its requests \"same-origin\";\n  // the Host header still names that domain, so only loopback hosts may write.\n  if (!isLoopbackHost(host)) return false;\n\n  const origin = headers.get('origin');\n\n  // No Origin: same-origin GET, curl or a test. Browsers always send it on cross-origin requests.\n  if (!origin) return true;\n\n  if (origins) return origins.includes(origin);\n\n  try {\n    return new URL(origin).host === host;\n  } catch {\n    return false; // \"null\" from sandboxed frames and file:// pages\n  }\n}\n\nfunction isLoopbackHost(host: string): boolean {\n  let hostname: string;\n\n  try {\n    hostname = new URL(`http://${host}`).hostname;\n  } catch {\n    return false;\n  }\n\n  return hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '[::1]'\n    || /^127(\\.\\d{1,3}){3}$/.test(hostname);\n}\n\nfunction toRequest(req: IncomingMessage): Request {\n  const headers = new Headers();\n\n  for (let i = 0; i < req.rawHeaders.length; i += 2) headers.append(req.rawHeaders[i], req.rawHeaders[i + 1]);\n\n  const method = req.method ?? 'GET';\n\n  // Streamed, so the handler can refuse a request before reading (or capping) its body.\n  const body = method === 'GET' || method === 'HEAD' ? undefined : new ReadableStream<Uint8Array>({\n    start(controller) {\n      req.on('data', (chunk: Buffer) => controller.enqueue(new Uint8Array(chunk)));\n      req.on('end', () => controller.close());\n      req.on('error', (err) => controller.error(err));\n    },\n    cancel() {\n      req.destroy();\n    },\n  });\n\n  const init: RequestInit & { duplex: 'half'; } = { method, headers, body, duplex: 'half' };\n\n  return new Request(new URL(req.url ?? '/', `http://${headers.get('host') ?? 'localhost'}`), init);\n}\n\nasync function readCapped(request: Request): Promise<string> {\n  const reader = request.body?.getReader();\n\n  if (!reader) return '';\n\n  const chunks: Uint8Array[] = [];\n  let size = 0;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n\n    if (done) break;\n    size += value.length;\n\n    if (size > MAX_BODY) {\n      await reader.cancel();\n      throw new Error('Scenario too large');\n    }\n\n    chunks.push(value);\n  }\n\n  return Buffer.concat(chunks).toString('utf8');\n}\n"],"mappings":"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","names":["file","body"]}

package/dist/chunk-KYU7RUWI.js

@@ -0,0 +1,179 @@
+import {
+  parseScenario
+} from "./chunk-DCURPYW5.js";
+
+// src/catalog.ts
+var defineScenarioRules = (rules) => rules;
+function createCatalog(raw, { rules = [] } = {}) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const [i, data] of raw.entries()) {
+    const s = parseScenario(data, `#${i}`);
+    if (s.name.includes(",")) throw new Error(`Scenario name "${s.name}" can't contain a comma`);
+    if (byName.has(s.name)) throw new Error(`Duplicate scenario name "${s.name}"`);
+    byName.set(s.name, s);
+  }
+  const flatten = (s, seen) => {
+    if (seen.includes(s.name)) {
+      throw new Error(`Circular extends: ${[...seen, s.name].join(" -> ")}`);
+    }
+    const parents = [s.extends ?? []].flat().map((name) => {
+      const parent = byName.get(name);
+      if (!parent) throw new Error(`Scenario "${s.name}" extends unknown "${name}"`);
+      return flatten(parent, [...seen, s.name]);
+    });
+    const { extends: _extends, $schema: _schema, ...own } = s;
+    return [...parents, own].reduce(merge, { name: own.name });
+  };
+  const resolve = (s) => {
+    const flat = flatten(s, []);
+    const violations = rules.flatMap((rule) => rule(flat) ?? []);
+    if (violations.length) {
+      throw new Error(`Scenario "${s.name}" breaks rules:
+${violations.map((m) => `- ${m}`).join("\n")}`);
+    }
+    return flat;
+  };
+  return {
+    list: [...byName.values()],
+    get: (name) => byName.get(name),
+    resolve,
+    check: () => [...byName.values()].flatMap((s) => {
+      try {
+        resolve(s);
+        return [];
+      } catch (err) {
+        return [err instanceof Error ? err.message : String(err)];
+      }
+    })
+  };
+}
+var byKey = ([a], [b]) => a.localeCompare(b);
+var routeKey = (e) => `${e.method} ${e.path} ${JSON.stringify(Object.entries(e.query ?? {}).toSorted(byKey))}`;
+function merge(base, over) {
+  const overKeys = new Set((over.network ?? []).map(routeKey));
+  return {
+    ...base,
+    ...over,
+    // Own-only fields: a child describes and finishes rendering differently.
+    description: over.description,
+    tags: over.tags,
+    ready: over.ready,
+    // A null param removes the inherited one.
+    url: Object.fromEntries(Object.entries({ ...base.url, ...over.url }).filter(([, v]) => v !== null)),
+    network: [
+      ...(over.network ?? []).filter((e) => !e.remove),
+      ...(base.network ?? []).filter((e) => !overKeys.has(routeKey(e)))
+    ],
+    state: mergeObjects(base.state ?? {}, over.state ?? {})
+  };
+}
+var isJsonObject = (value) => value instanceof Object && !Array.isArray(value);
+function mergeObjects(base, over) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    if (v === null) delete out[k];
+    else out[k] = deepMerge(base[k], v);
+  }
+  return out;
+}
+function deepMerge(base, over) {
+  return isJsonObject(base) && isJsonObject(over) ? mergeObjects(base, over) : over;
+}
+function diffScenario(captured, base) {
+  if (!base) {
+    return compactScenario({
+      name: captured.name,
+      description: captured.description,
+      tags: captured.tags,
+      path: captured.path,
+      url: captured.url,
+      network: captured.network,
+      state: captured.state,
+      ready: captured.ready
+    });
+  }
+  const url = diffUrl(base.url, captured.url);
+  const network = diffNetwork(base.network ?? [], captured.network ?? []);
+  const state = diffObjects(base.state ?? {}, captured.state ?? {});
+  return compactScenario({
+    name: captured.name,
+    extends: base.name,
+    description: captured.description,
+    tags: captured.tags,
+    path: captured.path !== base.path ? captured.path : void 0,
+    url,
+    network: network.length ? network : void 0,
+    state,
+    ready: captured.ready
+  });
+}
+function diffUrl(base, captured) {
+  const baseUrl = base ?? {};
+  const capturedUrl = captured ?? {};
+  const out = {};
+  for (const [k, v] of Object.entries(capturedUrl)) {
+    if (v === null) continue;
+    if (baseUrl[k] !== v) out[k] = v;
+  }
+  for (const [k, v] of Object.entries(baseUrl)) {
+    if (v === null) continue;
+    if (!(k in capturedUrl) || capturedUrl[k] === null) out[k] = null;
+  }
+  return Object.keys(out).length ? out : void 0;
+}
+function diffNetwork(base, captured) {
+  const baseByKey = new Map(base.map((e) => [routeKey(e), e]));
+  const capByKey = /* @__PURE__ */ new Map();
+  for (const e of captured) if (!capByKey.has(routeKey(e))) capByKey.set(routeKey(e), e);
+  const out = [];
+  for (const [key, e] of capByKey) {
+    const prior = baseByKey.get(key);
+    if (!prior || !jsonEqual(prior, e)) out.push(e);
+  }
+  for (const [key, e] of baseByKey) {
+    if (!capByKey.has(key)) {
+      const removed = { method: e.method, path: e.path, remove: true };
+      if (e.query) removed.query = e.query;
+      out.push(removed);
+    }
+  }
+  return out;
+}
+function diffObjects(base, captured) {
+  const out = {};
+  for (const [k, v] of Object.entries(captured)) {
+    if (!(k in base)) out[k] = v;
+    else if (isJsonObject(base[k]) && isJsonObject(v)) {
+      const nested = diffObjects(base[k], v);
+      if (nested) out[k] = nested;
+    } else if (!jsonEqual(base[k], v)) out[k] = v;
+  }
+  for (const k of Object.keys(base)) {
+    if (!(k in captured)) out[k] = null;
+  }
+  return Object.keys(out).length ? out : void 0;
+}
+function jsonEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+function compactScenario(s) {
+  const out = { name: s.name };
+  if (s.$schema !== void 0) out.$schema = s.$schema;
+  if (s.description !== void 0) out.description = s.description;
+  if (s.tags !== void 0) out.tags = s.tags;
+  if (s.extends !== void 0) out.extends = s.extends;
+  if (s.path !== void 0) out.path = s.path;
+  if (s.url !== void 0 && Object.keys(s.url).length) out.url = s.url;
+  if (s.network !== void 0 && s.network.length) out.network = s.network;
+  if (s.state !== void 0 && Object.keys(s.state).length) out.state = s.state;
+  if (s.ready !== void 0) out.ready = s.ready;
+  return out;
+}
+
+export {
+  defineScenarioRules,
+  createCatalog,
+  deepMerge,
+  diffScenario
+};
+//# sourceMappingURL=chunk-KYU7RUWI.js.map

package/dist/chunk-KYU7RUWI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/catalog.ts"],"sourcesContent":["import {\n  type Json,\n  type JsonObject,\n  type NetworkEntry,\n  parseScenario,\n  type Scenario,\n  type ScenarioInput,\n} from './schema.js';\n\n/**\n * A business rule a resolved scenario must satisfy, beyond schema shape.\n * Return a message (or several) for each violation.\n */\nexport type ScenarioRule = (scenario: Scenario) => string | string[] | void | undefined;\n\n/** Identity helper for typing rule lists. */\nexport const defineScenarioRules = (rules: ScenarioRule[]) => rules;\n\nexport interface Catalog {\n  list: Scenario[];\n  get(name: string): Scenario | undefined;\n  /** Flatten `extends` into one self-contained scenario, then check the rules. */\n  resolve(scenario: Scenario): Scenario;\n  /** Resolve every scenario; returns one message per problem. */\n  check(): string[];\n}\n\nexport function createCatalog(\n  raw: ScenarioInput[],\n  { rules = [] }: { rules?: ScenarioRule[]; } = {},\n): Catalog {\n  const byName = new Map<string, Scenario>();\n\n  for (const [i, data] of raw.entries()) {\n    const s = parseScenario(data, `#${i}`);\n\n    // Commas join names in ?scenario=a,b, so a catalog name can't contain one.\n    if (s.name.includes(',')) throw new Error(`Scenario name \"${s.name}\" can't contain a comma`);\n\n    if (byName.has(s.name)) throw new Error(`Duplicate scenario name \"${s.name}\"`);\n    byName.set(s.name, s);\n  }\n\n  const flatten = (s: Scenario, seen: string[]): Scenario => {\n    if (seen.includes(s.name)) {\n      throw new Error(`Circular extends: ${[...seen, s.name].join(' -> ')}`);\n    }\n\n    const parents = [s.extends ?? []].flat().map((name) => {\n      const parent = byName.get(name);\n\n      if (!parent) throw new Error(`Scenario \"${s.name}\" extends unknown \"${name}\"`);\n\n      return flatten(parent, [...seen, s.name]);\n    });\n\n    const { extends: _extends, $schema: _schema, ...own } = s;\n\n    // Start from an empty base so standalone scenarios are normalised too (remove entries, nulls).\n    return [...parents, own].reduce(merge, { name: own.name });\n  };\n\n  const resolve = (s: Scenario) => {\n    const flat = flatten(s, []);\n    const violations = rules.flatMap((rule) => rule(flat) ?? []);\n\n    if (violations.length) {\n      throw new Error(`Scenario \"${s.name}\" breaks rules:\\n${violations.map((m) => `- ${m}`).join('\\n')}`);\n    }\n\n    return flat;\n  };\n\n  return {\n    list: [...byName.values()],\n    get: (name) => byName.get(name),\n    resolve,\n    check: () =>\n      [...byName.values()].flatMap((s) => {\n        try {\n          resolve(s);\n\n          return [];\n        } catch (err) {\n          return [err instanceof Error ? err.message : String(err)];\n        }\n      }),\n  };\n}\n\nconst byKey = ([a]: [string, unknown], [b]: [string, unknown]) => a.localeCompare(b);\n\nconst routeKey = (e: NetworkEntry) =>\n  `${e.method} ${e.path} ${JSON.stringify(Object.entries(e.query ?? {}).toSorted(byKey))}`;\n\nfunction merge(base: Scenario, over: Scenario): Scenario {\n  const overKeys = new Set((over.network ?? []).map(routeKey));\n\n  return {\n    ...base,\n    ...over,\n    // Own-only fields: a child describes and finishes rendering differently.\n    description: over.description,\n    tags: over.tags,\n    ready: over.ready,\n    // A null param removes the inherited one.\n    url: Object.fromEntries(Object.entries({ ...base.url, ...over.url }).filter(([, v]) => v !== null)),\n    network: [\n      ...(over.network ?? []).filter((e) => !e.remove),\n      ...(base.network ?? []).filter((e) => !overKeys.has(routeKey(e))),\n    ],\n    state: mergeObjects(base.state ?? {}, over.state ?? {}),\n  };\n}\n\nconst isJsonObject = (value: Json | undefined): value is JsonObject =>\n  value instanceof Object && !Array.isArray(value);\n\nfunction mergeObjects(base: JsonObject, over: JsonObject): JsonObject {\n  const out = { ...base };\n\n  for (const [k, v] of Object.entries(over)) {\n    if (v === null) delete out[k];\n    else out[k] = deepMerge(base[k], v);\n  }\n\n  return out;\n}\n\n/** Objects merge recursively, `null` deletes a key, anything else replaces. */\nexport function deepMerge(base: Json | undefined, over: Json): Json {\n  return isJsonObject(base) && isJsonObject(over) ? mergeObjects(base, over) : over;\n}\n\n/**\n * Inverse of `extends` merge: overrides that turn a resolved `base` into `captured`.\n * Pass the flattened base (from `catalog.resolve`). Copy-link keeps `captured` as-is;\n * Download JSON uses this so the file can `extends` the base instead of repeating it.\n */\nexport function diffScenario(captured: Scenario, base?: Scenario): ScenarioInput {\n  if (!base) {\n    return compactScenario({\n      name: captured.name,\n      description: captured.description,\n      tags: captured.tags,\n      path: captured.path,\n      url: captured.url,\n      network: captured.network,\n      state: captured.state,\n      ready: captured.ready,\n    });\n  }\n\n  const url = diffUrl(base.url, captured.url);\n  const network = diffNetwork(base.network ?? [], captured.network ?? []);\n  const state = diffObjects(base.state ?? {}, captured.state ?? {});\n\n  return compactScenario({\n    name: captured.name,\n    extends: base.name,\n    description: captured.description,\n    tags: captured.tags,\n    path: captured.path !== base.path ? captured.path : undefined,\n    url,\n    network: network.length ? network : undefined,\n    state,\n    ready: captured.ready,\n  });\n}\n\nfunction diffUrl(\n  base: Scenario['url'],\n  captured: Scenario['url'],\n): ScenarioInput['url'] {\n  const baseUrl = base ?? {};\n  const capturedUrl = captured ?? {};\n  const out: Record<string, string | null> = {};\n\n  for (const [k, v] of Object.entries(capturedUrl)) {\n    if (v === null) continue;\n\n    if (baseUrl[k] !== v) out[k] = v;\n  }\n\n  for (const [k, v] of Object.entries(baseUrl)) {\n    if (v === null) continue;\n\n    if (!(k in capturedUrl) || capturedUrl[k] === null) out[k] = null;\n  }\n\n  return Object.keys(out).length ? out : undefined;\n}\n\nfunction diffNetwork(base: NetworkEntry[], captured: NetworkEntry[]): NetworkEntry[] {\n  const baseByKey = new Map(base.map((e) => [routeKey(e), e]));\n  const capByKey = new Map<string, NetworkEntry>();\n\n  // First match wins in MSW, so a later duplicate route is unreachable; keep the first.\n  for (const e of captured) if (!capByKey.has(routeKey(e))) capByKey.set(routeKey(e), e);\n\n  const out: NetworkEntry[] = [];\n\n  for (const [key, e] of capByKey) {\n    const prior = baseByKey.get(key);\n\n    if (!prior || !jsonEqual(prior, e)) out.push(e);\n  }\n\n  for (const [key, e] of baseByKey) {\n    if (!capByKey.has(key)) {\n      const removed: NetworkEntry = { method: e.method, path: e.path, remove: true };\n\n      if (e.query) removed.query = e.query;\n\n      out.push(removed);\n    }\n  }\n\n  return out;\n}\n\nfunction diffObjects(base: JsonObject, captured: JsonObject): JsonObject | undefined {\n  const out: JsonObject = {};\n\n  for (const [k, v] of Object.entries(captured)) {\n    if (!(k in base)) out[k] = v;\n    else if (isJsonObject(base[k]) && isJsonObject(v)) {\n      const nested = diffObjects(base[k], v);\n\n      if (nested) out[k] = nested;\n    } else if (!jsonEqual(base[k], v)) out[k] = v;\n  }\n\n  for (const k of Object.keys(base)) {\n    if (!(k in captured)) out[k] = null;\n  }\n\n  return Object.keys(out).length ? out : undefined;\n}\n\nfunction jsonEqual(a: Json | NetworkEntry, b: Json | NetworkEntry): boolean {\n  return JSON.stringify(a) === JSON.stringify(b);\n}\n\nfunction compactScenario(s: ScenarioInput): ScenarioInput {\n  const out: ScenarioInput = { name: s.name };\n\n  if (s.$schema !== undefined) out.$schema = s.$schema;\n\n  if (s.description !== undefined) out.description = s.description;\n\n  if (s.tags !== undefined) out.tags = s.tags;\n\n  if (s.extends !== undefined) out.extends = s.extends;\n\n  if (s.path !== undefined) out.path = s.path;\n\n  if (s.url !== undefined && Object.keys(s.url).length) out.url = s.url;\n\n  if (s.network !== undefined && s.network.length) out.network = s.network;\n\n  if (s.state !== undefined && Object.keys(s.state).length) out.state = s.state;\n\n  if (s.ready !== undefined) out.ready = s.ready;\n\n  return out;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export { type Catalog, createCatalog, deepMerge, defineScenarioRules, type ScenarioRule } from './catalog.js';
-export { DATA_KEY, PARAM, readInline, scenarioHref, STRICT_PARAM } from './link.js';
+export { type CapturedScenario, type CaptureOptions, captureScenario } from './capture.js';
+export { type Catalog, createCatalog, deepMerge, defineScenarioRules, diffScenario, type ScenarioRule, } from './catalog.js';
+export { DATA_KEY, PARAM, readInline, RECORD_PARAM, scenarioHref, STRICT_PARAM } from './link.js';
 export { toHandlers } from './network.js';
+export { checkReadySelector, type ReadyCheck, selectorForElement, suggestReadySelectors } from './ready.js';
 export { type Adapter, type Connection, currentSession, type JsonAdapter, type MswWorker, navigate, type ScenarioSession, type StartOptions, startScenarios, type TypedAdapter, } from './runtime.js';
 export { type Json, type JsonObject, JsonSchema, type NetworkEntry, parseJson, parseScenario, type Scenario, type ScenarioInput, scenarioJsonSchema, ScenarioSchema, type Serializable, } from './schema.js';

package/dist/index.js

@@ -1,25 +1,102 @@
 import {
   toHandlers
 } from "./chunk-U3I7ORTB.js";
+import {
+  captureScenario,
+  checkReadySelector,
+  selectorForElement,
+  suggestReadySelectors
+} from "./chunk-FTWYRB6F.js";
 import {
   DATA_KEY,
   PARAM,
+  RECORD_PARAM,
+  SAVE_ENDPOINT,
   STRICT_PARAM,
   readInline,
   scenarioHref
-} from "./chunk-KRCYO64S.js";
+} from "./chunk-3M6SD4TA.js";
 import {
   createCatalog,
   deepMerge,
-  defineScenarioRules
-} from "./chunk-KDH572NI.js";
+  defineScenarioRules,
+  diffScenario
+} from "./chunk-KYU7RUWI.js";
 import {
   JsonSchema,
+  MethodSchema,
   ScenarioSchema,
   parseJson,
   parseScenario,
   scenarioJsonSchema
-} from "./chunk-6L55WKFS.js";
+} from "./chunk-DCURPYW5.js";
+
+// src/record.ts
+function createRecorder() {
+  const started = /* @__PURE__ */ new Map();
+  const calls = [];
+  const pending = /* @__PURE__ */ new Set();
+  let next = 0;
+  return {
+    start(requestId) {
+      started.set(requestId, next++);
+    },
+    /** A mocked response: nothing to record. */
+    drop(requestId) {
+      started.delete(requestId);
+    },
+    bypass(requestId, request, response) {
+      const order = started.get(requestId) ?? next++;
+      started.delete(requestId);
+      const method = MethodSchema.safeParse(request.method);
+      const own = new URL(request.url).pathname.startsWith(SAVE_ENDPOINT);
+      if (own || !method.success || !response.headers.get("content-type")?.includes("json")) {
+        return Promise.resolve();
+      }
+      const url = new URL(request.url);
+      if (new Set(url.searchParams.keys()).size < [...url.searchParams.keys()].length) {
+        console.warn(`[state-scenarios] not recorded: ${request.method} ${url} repeats a query key`);
+        return Promise.resolve();
+      }
+      const read = response.clone().text().then((text) => {
+        const call = {
+          order,
+          method: method.data,
+          path: url.origin === location.origin ? url.pathname : url.origin + url.pathname,
+          query: Object.fromEntries(url.searchParams),
+          status: response.status
+        };
+        if (text) call.body = parseJson(text);
+        calls.push(call);
+      }).catch((err) => console.warn("[state-scenarios] skipped a recorded response", err)).finally(() => pending.delete(read));
+      pending.add(read);
+      return read;
+    },
+    /** Responses whose bodies have been read, as network entries. */
+    entries: () => toNetwork(calls),
+    /** Wait for bodies still being read. */
+    settled: async () => {
+      await Promise.all(pending);
+    }
+  };
+}
+function toNetwork(calls) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const call of calls.toSorted((a, b) => a.order - b.order)) {
+    const query = Object.fromEntries(Object.entries(call.query).toSorted(([a], [b]) => a.localeCompare(b)));
+    const key = JSON.stringify([call.method, call.path, query]);
+    groups.set(key, [...groups.get(key) ?? [], { ...call, query }]);
+  }
+  return [...groups.values()].map(([first, ...rest]) => {
+    const responses = [first, ...rest].map(({ status, body }) => ({ status, body }));
+    const same = responses.every((r) => JSON.stringify(r) === JSON.stringify(responses[0]));
+    const entry = { method: first.method, path: first.path };
+    if (Object.keys(first.query).length) entry.query = first.query;
+    if (same) entry.response = responses[0];
+    else entry.sequence = responses;
+    return entry;
+  }).toSorted((a, b) => Object.keys(b.query ?? {}).length - Object.keys(a.query ?? {}).length);
+}
 
 // src/runtime.ts
 var STORAGE_KEY = "state-scenarios:active";
@@ -60,6 +137,30 @@ async function startScenarios(options) {
       }
     }
   };
+  const recorder = createRecorder();
+  let stopListening = null;
+  const listen = (target) => {
+    if (!session.recording || stopListening) return;
+    if (!target.events) {
+      console.warn("[state-scenarios] recording needs a worker with `events`");
+      return;
+    }
+    const { events } = target;
+    const start = ({ requestId }) => recorder.start(requestId);
+    const mocked = ({ requestId }) => recorder.drop(requestId);
+    const bypass = ({ requestId, request, response }) => {
+      void recorder.bypass(requestId, request, response).then(emit);
+    };
+    events.on("request:start", start);
+    events.on("response:mocked", mocked);
+    events.on("response:bypass", bypass);
+    stopListening = () => {
+      events.removeListener("request:start", start);
+      events.removeListener("response:mocked", mocked);
+      events.removeListener("response:bypass", bypass);
+      stopListening = null;
+    };
+  };
   let worker = options.worker ?? null;
   let ownWorker = null;
   const appHandlers = options.worker ? [...options.worker.listHandlers()] : [];
@@ -82,7 +183,7 @@ async function startScenarios(options) {
   };
   const boundAdapters = () => [...connected.values()].map((entry) => entry.adapter);
   const setNetwork = async (resolved2) => {
-    if (!resolved2.network?.length && !session.strict && !worker) return;
+    if (!resolved2.network?.length && !session.strict && !session.recording && !worker) return;
     const [{ toHandlers: toHandlers2 }, msw] = await Promise.all([import("./network-MYTTJ2HL.js"), import("msw")]);
     if (destroyed) return;
     const allow = options.allow ?? [];
@@ -92,7 +193,7 @@ async function startScenarios(options) {
       const allowed = allow.some(
         (rule) => rule instanceof RegExp ? rule.test(request.url) : request.url.includes(rule)
       );
-      if (isPage || isAsset(request.url) || pathname.startsWith("/@") || allowed) {
+      if (isPage || isAsset(request.url) || pathname.startsWith("/@") || pathname.startsWith(SAVE_ENDPOINT) || allowed) {
         return msw.passthrough();
       }
       const label = `${request.method} ${request.url}`;
@@ -105,9 +206,10 @@ async function startScenarios(options) {
     const handlers = [...toHandlers2(resolved2.network), ...appHandlers, fallback];
     if (worker) {
       worker.resetHandlers(...handlers);
+      listen(worker);
       return;
     }
-    const { setupWorker } = await import("msw/browser");
+    const { setupWorker } = await import("#msw-browser");
     const started = setupWorker(...handlers);
     await started.start({ quiet: true, ...options.workerOptions });
     if (destroyed) {
@@ -115,6 +217,7 @@ async function startScenarios(options) {
       return;
     }
     worker = ownWorker = started;
+    listen(started);
   };
   const activate = (active2, resolved2, link) => {
     fromLink = link;
@@ -150,7 +253,7 @@ async function startScenarios(options) {
     unhandled.splice(0);
     activate(next, resolved2, inline);
     const at = new URL(href);
-    history.replaceState(history.state, "", at);
+    replaceUrl(at);
     const data = readInline(at.hash);
     store(data ? { data, strict: session.strict } : { name: next.name, strict: session.strict });
     emit();
@@ -186,6 +289,10 @@ async function startScenarios(options) {
     resolved: null,
     strict: options.strict ?? !!selection?.strict,
     unhandled,
+    // Held in memory: a full page load starts a new recording.
+    recording: options.record ?? url.searchParams.has(RECORD_PARAM),
+    recorded: recorder.entries,
+    settleRecording: recorder.settled,
     keys: () => [...connected.keys()],
     read(key) {
       const entry = connected.get(key);
@@ -225,6 +332,7 @@ async function startScenarios(options) {
       for (const entry of connected.values()) entry.unsubscribe?.();
       connected.clear();
       listeners.clear();
+      stopListening?.();
       if (ownWorker) void ownWorker.stop();
       else worker?.resetHandlers(...appHandlers);
       worker = ownWorker = null;
@@ -240,7 +348,10 @@ async function startScenarios(options) {
   current = session;
   const initial = (options.adapters ?? []).map(bind);
   for (const adapter of initial) attach(adapter);
-  if (!selection) return session;
+  if (!selection) {
+    if (session.recording) await setNetwork({ name: "live" });
+    return session;
+  }
   const loaded = (() => {
     try {
       const active2 = selection.data ? parseScenario(JSON.parse(selection.data), "inline scenario") : lookup(catalog, selection.name ?? "");
@@ -257,7 +368,7 @@ async function startScenarios(options) {
   for (const [k, v] of Object.entries(resolved.url ?? {})) {
     if (v !== null && !url.searchParams.has(k)) url.searchParams.set(k, v);
   }
-  history.replaceState(history.state, "", url);
+  replaceUrl(url);
   await applyPrepared(prepared);
   if (destroyed) return session;
   activate(active, resolved, !!selection.data);
@@ -268,13 +379,18 @@ var isAsset = (href) => {
   const url = new URL(href);
   return url.protocol === "file:" || url.hostname === "fonts.googleapis.com" || url.pathname.includes("node_modules") || url.pathname.includes("@vite") || /\.(s?css|less|m?jsx?|m?tsx?|html|ttf|otf|woff2?|eot|gif|jpe?g|png|avif|webp|svg|mp4|webm|ogg|mov|mp3|wav|flac|aac|pdf|txt|csv|json|xml|md|zip|tar|gz|rar|7z)$/i.test(url.pathname);
 };
+var replaceUrl = (url) => {
+  const state = history.state;
+  const { __NA, ...rest } = Object(state);
+  history.replaceState(__NA === void 0 ? state : rest, "", url);
+};
 var byKey = ([a], [b]) => a.localeCompare(b);
 var appParams = (search) => [...new URLSearchParams(search)].filter(([k]) => k !== PARAM && k !== STRICT_PARAM).toSorted(byKey);
 var sortedParams = (url) => Object.entries(url ?? {}).filter(([, v]) => v !== null).toSorted(byKey);
 function navigate(href) {
   const next = new URL(href, location.href);
   if (next.pathname + next.search === location.pathname + location.search) {
-    history.replaceState(history.state, "", next);
+    replaceUrl(next);
     location.reload();
   } else {
     location.href = next.toString();
@@ -329,19 +445,25 @@ export {
   DATA_KEY,
   JsonSchema,
   PARAM,
+  RECORD_PARAM,
   STRICT_PARAM,
   ScenarioSchema,
+  captureScenario,
+  checkReadySelector,
   createCatalog,
   currentSession,
   deepMerge,
   defineScenarioRules,
+  diffScenario,
   navigate,
   parseJson,
   parseScenario,
   readInline,
   scenarioHref,
   scenarioJsonSchema,
+  selectorForElement,
   startScenarios,
+  suggestReadySelectors,
   toHandlers
 };
 //# sourceMappingURL=index.js.map