executable-stories-cypress 2.0.0

package/README.md

@@ -0,0 +1,79 @@
+# executable-stories-cypress
+
+BDD-style executable stories for Cypress with documentation generation. Uses Cypress’s native `describe`/`it`; story meta is sent from the browser to Node via `cy.task` and merged with run results for the reporter.
+
+## Install
+
+```bash
+npm i -D executable-stories-cypress
+```
+
+## Setup
+
+1. **Plugin** — register the task in `cypress.config.ts`:
+
+```ts
+import { defineConfig } from "cypress";
+import { registerExecutableStoriesPlugin } from "executable-stories-cypress/plugin";
+
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on) {
+      registerExecutableStoriesPlugin(on);
+    },
+  },
+});
+```
+
+2. **Support file** — import the support file so story meta is sent after each test (e.g. in `cypress/support/e2e.ts`):
+
+```ts
+import "executable-stories-cypress/support";
+```
+
+3. **Reporter** (optional) — to generate Markdown/HTML from runs, use the reporter or build a RawRun and pass it to the formatters. See [Reporter options](#reporter-options) below.
+
+## Usage
+
+In a spec, call `story.init()` at the start of each test that should be documented, then use step markers:
+
+```ts
+import { story } from "executable-stories-cypress";
+
+describe("Calculator", () => {
+  it("adds two numbers", () => {
+    story.init();
+
+    story.given("two numbers 5 and 3");
+    const a = 5, b = 3;
+
+    story.when("I add them together");
+    const result = a + b;
+
+    story.then("the result is 8");
+    expect(result).toBe(8);
+  });
+});
+```
+
+With options:
+
+```ts
+story.init({ tags: ["smoke"], ticket: "JIRA-123" });
+```
+
+## Reporter options
+
+The package outputs to the **executable-stories-formatters** schema (RawRun). You can:
+
+- Use the Mocha reporter (when Cypress invokes it) with `--reporter executable-stories-cypress/reporter` and `--reporter-options outputDir=...,outputName=...`.
+- Or use the Module API: after `cypress.run()`, call `buildRawRunFromCypressResult(result, options)` then `generateReportsFromRawRun(rawRun, options)` (see exports from `executable-stories-cypress/reporter`).
+
+Options match the formatters’ `FormatterOptions` (e.g. `formats`, `outputDir`, `outputName`, `markdown`, `rawRunPath`).
+
+## Exports
+
+- **Main:** `story`, `getAndClearMeta`, types from `executable-stories-cypress`.
+- **Support:** `executable-stories-cypress/support` (side-effect: registers `afterEach` + `cy.task`).
+- **Plugin:** `registerExecutableStoriesPlugin` from `executable-stories-cypress/plugin`.
+- **Reporter:** default reporter and `buildRawRunFromCypressResult`, `generateReportsFromRawRun` from `executable-stories-cypress/reporter`.

package/dist/index.cjs

@@ -0,0 +1,334 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  getAndClearMeta: () => getAndClearMeta,
+  story: () => story
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/story-api.ts
+var activeContext = null;
+var sourceOrderCounter = 0;
+function getContext() {
+  if (!activeContext) {
+    throw new Error(
+      "story.init() must be called first. Use: it('name', () => { story.init(); ... });"
+    );
+  }
+  return activeContext;
+}
+function normalizeTickets(ticket) {
+  if (!ticket) return void 0;
+  return Array.isArray(ticket) ? ticket : [ticket];
+}
+function convertStoryDocsToEntries(docs) {
+  const entries = [];
+  if (docs.note) {
+    entries.push({ kind: "note", text: docs.note, phase: "runtime" });
+  }
+  if (docs.tag) {
+    const names = Array.isArray(docs.tag) ? docs.tag : [docs.tag];
+    entries.push({ kind: "tag", names, phase: "runtime" });
+  }
+  if (docs.kv) {
+    for (const [label, value] of Object.entries(docs.kv)) {
+      entries.push({ kind: "kv", label, value, phase: "runtime" });
+    }
+  }
+  if (docs.code) {
+    entries.push({
+      kind: "code",
+      label: docs.code.label,
+      content: docs.code.content,
+      lang: docs.code.lang,
+      phase: "runtime"
+    });
+  }
+  if (docs.json) {
+    entries.push({
+      kind: "code",
+      label: docs.json.label,
+      content: JSON.stringify(docs.json.value, null, 2),
+      lang: "json",
+      phase: "runtime"
+    });
+  }
+  if (docs.table) {
+    entries.push({
+      kind: "table",
+      label: docs.table.label,
+      columns: docs.table.columns,
+      rows: docs.table.rows,
+      phase: "runtime"
+    });
+  }
+  if (docs.link) {
+    entries.push({
+      kind: "link",
+      label: docs.link.label,
+      url: docs.link.url,
+      phase: "runtime"
+    });
+  }
+  if (docs.section) {
+    entries.push({
+      kind: "section",
+      title: docs.section.title,
+      markdown: docs.section.markdown,
+      phase: "runtime"
+    });
+  }
+  if (docs.mermaid) {
+    entries.push({
+      kind: "mermaid",
+      code: docs.mermaid.code,
+      title: docs.mermaid.title,
+      phase: "runtime"
+    });
+  }
+  if (docs.screenshot) {
+    entries.push({
+      kind: "screenshot",
+      path: docs.screenshot.path,
+      alt: docs.screenshot.alt,
+      phase: "runtime"
+    });
+  }
+  if (docs.custom) {
+    entries.push({
+      kind: "custom",
+      type: docs.custom.type,
+      data: docs.custom.data,
+      phase: "runtime"
+    });
+  }
+  return entries;
+}
+function attachDoc(entry) {
+  const ctx = getContext();
+  if (ctx.currentStep) {
+    ctx.currentStep.docs ??= [];
+    ctx.currentStep.docs.push(entry);
+  } else {
+    ctx.meta.docs ??= [];
+    ctx.meta.docs.push(entry);
+  }
+}
+function extractSuitePath(titlePath) {
+  if (titlePath.length <= 1) return void 0;
+  const suitePath = titlePath.slice(0, -1);
+  return suitePath.length > 0 ? suitePath : void 0;
+}
+function createStepMarker(keyword) {
+  return function stepMarker(text, docs) {
+    const ctx = getContext();
+    const step = {
+      id: `step-${ctx.stepCounter++}`,
+      keyword,
+      text,
+      docs: docs ? convertStoryDocsToEntries(docs) : []
+    };
+    ctx.meta.steps.push(step);
+    ctx.currentStep = step;
+  };
+}
+function init(options) {
+  const currentTest = Cypress.currentTest;
+  const spec = Cypress.spec;
+  if (!currentTest) {
+    throw new Error("story.init() must be called inside an it() block so Cypress.currentTest is available.");
+  }
+  const titlePath = currentTest.titlePath ?? [currentTest.title];
+  const scenario = currentTest.title;
+  const suitePath = extractSuitePath(titlePath);
+  const specRelative = spec?.relative ?? "unknown";
+  const meta = {
+    scenario,
+    steps: [],
+    suitePath,
+    tags: options?.tags,
+    tickets: normalizeTickets(options?.ticket),
+    meta: options?.meta,
+    sourceOrder: sourceOrderCounter++
+  };
+  activeContext = {
+    meta,
+    currentStep: null,
+    stepCounter: 0,
+    attachments: [],
+    activeTimers: /* @__PURE__ */ new Map(),
+    timerCounter: 0,
+    specRelative,
+    titlePath
+  };
+}
+function getAndClearMeta() {
+  if (!activeContext) return null;
+  const payload = {
+    specRelative: activeContext.specRelative,
+    titlePath: activeContext.titlePath,
+    meta: activeContext.meta,
+    attachments: activeContext.attachments.length > 0 ? activeContext.attachments : void 0
+  };
+  activeContext = null;
+  return payload;
+}
+function fn(keyword, text, body) {
+  const ctx = getContext();
+  const step = {
+    id: `step-${ctx.stepCounter++}`,
+    keyword,
+    text,
+    docs: [],
+    wrapped: true
+  };
+  ctx.meta.steps.push(step);
+  ctx.currentStep = step;
+  const start = performance.now();
+  try {
+    const result = body();
+    if (result instanceof Promise) {
+      return result.then(
+        (val) => {
+          step.durationMs = performance.now() - start;
+          return val;
+        },
+        (err) => {
+          step.durationMs = performance.now() - start;
+          throw err;
+        }
+      );
+    }
+    step.durationMs = performance.now() - start;
+    return result;
+  } catch (err) {
+    step.durationMs = performance.now() - start;
+    throw err;
+  }
+}
+function storyExpect(text, body) {
+  return fn("Then", text, body);
+}
+var story = {
+  init,
+  // BDD step markers
+  given: createStepMarker("Given"),
+  when: createStepMarker("When"),
+  then: createStepMarker("Then"),
+  and: createStepMarker("And"),
+  but: createStepMarker("But"),
+  // AAA pattern aliases
+  arrange: createStepMarker("Given"),
+  act: createStepMarker("When"),
+  assert: createStepMarker("Then"),
+  // Additional aliases
+  setup: createStepMarker("Given"),
+  context: createStepMarker("Given"),
+  execute: createStepMarker("When"),
+  action: createStepMarker("When"),
+  verify: createStepMarker("Then"),
+  // Standalone doc methods
+  note(text) {
+    attachDoc({ kind: "note", text, phase: "runtime" });
+  },
+  tag(name) {
+    const names = Array.isArray(name) ? name : [name];
+    attachDoc({ kind: "tag", names, phase: "runtime" });
+  },
+  kv(options) {
+    attachDoc({ kind: "kv", label: options.label, value: options.value, phase: "runtime" });
+  },
+  json(options) {
+    const content = JSON.stringify(options.value, null, 2);
+    attachDoc({ kind: "code", label: options.label, content, lang: "json", phase: "runtime" });
+  },
+  code(options) {
+    attachDoc({ kind: "code", label: options.label, content: options.content, lang: options.lang, phase: "runtime" });
+  },
+  table(options) {
+    attachDoc({ kind: "table", label: options.label, columns: options.columns, rows: options.rows, phase: "runtime" });
+  },
+  link(options) {
+    attachDoc({ kind: "link", label: options.label, url: options.url, phase: "runtime" });
+  },
+  section(options) {
+    attachDoc({ kind: "section", title: options.title, markdown: options.markdown, phase: "runtime" });
+  },
+  mermaid(options) {
+    attachDoc({ kind: "mermaid", code: options.code, title: options.title, phase: "runtime" });
+  },
+  screenshot(options) {
+    attachDoc({ kind: "screenshot", path: options.path, alt: options.alt, phase: "runtime" });
+  },
+  custom(options) {
+    attachDoc({ kind: "custom", type: options.type, data: options.data, phase: "runtime" });
+  },
+  // Attachments
+  attach(options) {
+    const ctx = getContext();
+    const stepIndex = ctx.currentStep ? ctx.meta.steps.indexOf(ctx.currentStep) : void 0;
+    ctx.attachments.push({
+      ...options,
+      stepIndex: stepIndex !== void 0 && stepIndex >= 0 ? stepIndex : void 0,
+      stepId: ctx.currentStep?.id
+    });
+  },
+  // Step timing
+  startTimer() {
+    const ctx = getContext();
+    const token = ctx.timerCounter++;
+    const stepIndex = ctx.currentStep ? ctx.meta.steps.indexOf(ctx.currentStep) : void 0;
+    ctx.activeTimers.set(token, {
+      start: performance.now(),
+      stepIndex: stepIndex !== void 0 && stepIndex >= 0 ? stepIndex : void 0,
+      stepId: ctx.currentStep?.id,
+      consumed: false
+    });
+    return token;
+  },
+  endTimer(token) {
+    const ctx = getContext();
+    const entry = ctx.activeTimers.get(token);
+    if (!entry || entry.consumed) return;
+    entry.consumed = true;
+    const durationMs = performance.now() - entry.start;
+    let step;
+    if (entry.stepId) {
+      step = ctx.meta.steps.find((s) => s.id === entry.stepId);
+    }
+    if (!step && entry.stepIndex !== void 0) {
+      step = ctx.meta.steps[entry.stepIndex];
+    }
+    if (step) {
+      step.durationMs = durationMs;
+    }
+  },
+  // Step wrappers
+  fn,
+  expect: storyExpect
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getAndClearMeta,
+  story
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/story-api.ts"],"sourcesContent":["/**\n * Cypress Executable Stories\n *\n * BDD-style executable documentation for Cypress.\n *\n * @example\n * ```ts\n * import { story } from 'executable-stories-cypress';\n *\n * describe('Calculator', () => {\n *   it('adds two numbers', () => {\n *     story.init();\n *\n *     story.given('two numbers 5 and 3');\n *     const a = 5, b = 3;\n *\n *     story.when('I add them together');\n *     const result = a + b;\n *\n *     story.then('the result is 8');\n *     expect(result).toBe(8);\n *   });\n * });\n * ```\n */\n\n// Story API\nexport { story, getAndClearMeta } from './story-api';\nexport type { Story, RecordMetaPayload } from './story-api';\n\n// Re-export types from local types module\nexport type {\n  StoryMeta,\n  StoryStep,\n  DocEntry,\n  StepKeyword,\n  StoryDocs,\n  StoryOptions,\n  KvOptions,\n  JsonOptions,\n  CodeOptions,\n  TableOptions,\n  LinkOptions,\n  SectionOptions,\n  MermaidOptions,\n  ScreenshotOptions,\n  CustomOptions,\n} from './types';\n","/**\n * Cypress story.* API for executable-stories.\n *\n * Uses native Cypress describe/it with opt-in documentation.\n * Story meta is flushed to Node via cy.task from the support file.\n *\n * @example\n * ```ts\n * import { story } from 'executable-stories-cypress';\n *\n * describe('Calculator', () => {\n *   it('adds two numbers', () => {\n *     story.init();\n *\n *     story.given('two numbers 5 and 3');\n *     const a = 5, b = 3;\n *\n *     story.when('I add them together');\n *     const result = a + b;\n *\n *     story.then('the result is 8');\n *     expect(result).toBe(8);\n *   });\n * });\n * ```\n */\n\nimport type {\n  StepKeyword,\n  StoryMeta,\n  StoryStep,\n  DocEntry,\n  StoryDocs,\n  StoryOptions,\n  AttachmentOptions,\n  ScopedAttachment,\n  RecordMetaPayload,\n  KvOptions,\n  JsonOptions,\n  CodeOptions,\n  TableOptions,\n  LinkOptions,\n  SectionOptions,\n  MermaidOptions,\n  ScreenshotOptions,\n  CustomOptions,\n} from './types';\n\n// Re-export types for consumers\nexport type {\n  StoryMeta,\n  StoryStep,\n  DocEntry,\n  StepKeyword,\n  StoryDocs,\n  StoryOptions,\n  AttachmentOptions,\n} from './types';\n\nexport type { RecordMetaPayload } from './types';\n\n// ============================================================================\n// Internal types\n// ============================================================================\n\ninterface TimerEntry {\n  start: number;\n  stepIndex?: number;\n  stepId?: string;\n  consumed: boolean;\n}\n\ninterface StoryContext {\n  meta: StoryMeta;\n  currentStep: StoryStep | null;\n  stepCounter: number;\n  attachments: ScopedAttachment[];\n  activeTimers: Map<number, TimerEntry>;\n  timerCounter: number;\n  specRelative: string;\n  titlePath: string[];\n}\n\n// ============================================================================\n// Cypress-specific context\n// ============================================================================\n\n/** Active story context - set by story.init() */\nlet activeContext: StoryContext | null = null;\n\n/** Counter to track source order of stories (increments on each story.init call) */\nlet sourceOrderCounter = 0;\n\n/**\n * Get the current story context. Throws if story.init() wasn't called.\n */\nfunction getContext(): StoryContext {\n  if (!activeContext) {\n    throw new Error(\n      \"story.init() must be called first. Use: it('name', () => { story.init(); ... });\"\n    );\n  }\n  return activeContext;\n}\n\n// ============================================================================\n// Helper functions (inlined from core)\n// ============================================================================\n\nfunction normalizeTickets(ticket: string | string[] | undefined): string[] | undefined {\n  if (!ticket) return undefined;\n  return Array.isArray(ticket) ? ticket : [ticket];\n}\n\nfunction convertStoryDocsToEntries(docs: StoryDocs): DocEntry[] {\n  const entries: DocEntry[] = [];\n\n  if (docs.note) {\n    entries.push({ kind: 'note', text: docs.note, phase: 'runtime' });\n  }\n  if (docs.tag) {\n    const names = Array.isArray(docs.tag) ? docs.tag : [docs.tag];\n    entries.push({ kind: 'tag', names, phase: 'runtime' });\n  }\n  if (docs.kv) {\n    for (const [label, value] of Object.entries(docs.kv)) {\n      entries.push({ kind: 'kv', label, value, phase: 'runtime' });\n    }\n  }\n  if (docs.code) {\n    entries.push({\n      kind: 'code',\n      label: docs.code.label,\n      content: docs.code.content,\n      lang: docs.code.lang,\n      phase: 'runtime',\n    });\n  }\n  if (docs.json) {\n    entries.push({\n      kind: 'code',\n      label: docs.json.label,\n      content: JSON.stringify(docs.json.value, null, 2),\n      lang: 'json',\n      phase: 'runtime',\n    });\n  }\n  if (docs.table) {\n    entries.push({\n      kind: 'table',\n      label: docs.table.label,\n      columns: docs.table.columns,\n      rows: docs.table.rows,\n      phase: 'runtime',\n    });\n  }\n  if (docs.link) {\n    entries.push({\n      kind: 'link',\n      label: docs.link.label,\n      url: docs.link.url,\n      phase: 'runtime',\n    });\n  }\n  if (docs.section) {\n    entries.push({\n      kind: 'section',\n      title: docs.section.title,\n      markdown: docs.section.markdown,\n      phase: 'runtime',\n    });\n  }\n  if (docs.mermaid) {\n    entries.push({\n      kind: 'mermaid',\n      code: docs.mermaid.code,\n      title: docs.mermaid.title,\n      phase: 'runtime',\n    });\n  }\n  if (docs.screenshot) {\n    entries.push({\n      kind: 'screenshot',\n      path: docs.screenshot.path,\n      alt: docs.screenshot.alt,\n      phase: 'runtime',\n    });\n  }\n  if (docs.custom) {\n    entries.push({\n      kind: 'custom',\n      type: docs.custom.type,\n      data: docs.custom.data,\n      phase: 'runtime',\n    });\n  }\n\n  return entries;\n}\n\nfunction attachDoc(entry: DocEntry): void {\n  const ctx = getContext();\n  if (ctx.currentStep) {\n    ctx.currentStep.docs ??= [];\n    ctx.currentStep.docs.push(entry);\n  } else {\n    ctx.meta.docs ??= [];\n    ctx.meta.docs.push(entry);\n  }\n}\n\n/**\n * Extract suite path from Cypress.currentTest.titlePath (describe blocks only).\n * titlePath is [describe1, describe2, ..., testTitle] — we want everything except the last.\n */\nfunction extractSuitePath(titlePath: string[]): string[] | undefined {\n  if (titlePath.length <= 1) return undefined;\n  const suitePath = titlePath.slice(0, -1);\n  return suitePath.length > 0 ? suitePath : undefined;\n}\n\n// ============================================================================\n// Step markers\n// ============================================================================\n\nfunction createStepMarker(keyword: StepKeyword) {\n  return function stepMarker(text: string, docs?: StoryDocs): void {\n    const ctx = getContext();\n    const step: StoryStep = {\n      id: `step-${ctx.stepCounter++}`,\n      keyword,\n      text,\n      docs: docs ? convertStoryDocsToEntries(docs) : [],\n    };\n    ctx.meta.steps.push(step);\n    ctx.currentStep = step;\n  };\n}\n\n// ============================================================================\n// story.init() - Cypress-specific\n// ============================================================================\n\nfunction init(options?: StoryOptions): void {\n  const currentTest = Cypress.currentTest;\n  const spec = Cypress.spec;\n  if (!currentTest) {\n    throw new Error(\"story.init() must be called inside an it() block so Cypress.currentTest is available.\");\n  }\n\n  const titlePath = currentTest.titlePath ?? [currentTest.title];\n  const scenario = currentTest.title;\n  const suitePath = extractSuitePath(titlePath);\n  const specRelative = spec?.relative ?? \"unknown\";\n\n  const meta: StoryMeta = {\n    scenario,\n    steps: [],\n    suitePath,\n    tags: options?.tags,\n    tickets: normalizeTickets(options?.ticket),\n    meta: options?.meta,\n    sourceOrder: sourceOrderCounter++,\n  };\n\n  activeContext = {\n    meta,\n    currentStep: null,\n    stepCounter: 0,\n    attachments: [],\n    activeTimers: new Map(),\n    timerCounter: 0,\n    specRelative,\n    titlePath,\n  };\n}\n\n/**\n * Get the current story meta and clear the active context.\n * Called by the support file after each test to send meta to Node via cy.task.\n * Returns null if story.init() was never called for this test.\n */\nexport function getAndClearMeta(): RecordMetaPayload | null {\n  if (!activeContext) return null;\n  const payload: RecordMetaPayload = {\n    specRelative: activeContext.specRelative,\n    titlePath: activeContext.titlePath,\n    meta: activeContext.meta,\n    attachments: activeContext.attachments.length > 0 ? activeContext.attachments : undefined,\n  };\n  activeContext = null;\n  return payload;\n}\n\n// ============================================================================\n// story.fn() and story.expect()\n// ============================================================================\n\n/**\n * Wrap a function as a step with timing and error capture.\n * Records the step with `wrapped: true` and `durationMs`.\n */\nfunction fn<T>(keyword: StepKeyword, text: string, body: () => T): T {\n  const ctx = getContext();\n  const step: StoryStep = {\n    id: `step-${ctx.stepCounter++}`,\n    keyword,\n    text,\n    docs: [],\n    wrapped: true,\n  };\n  ctx.meta.steps.push(step);\n  ctx.currentStep = step;\n\n  const start = performance.now();\n  try {\n    const result = body();\n    if (result instanceof Promise) {\n      return result.then(\n        (val) => {\n          step.durationMs = performance.now() - start;\n          return val;\n        },\n        (err) => {\n          step.durationMs = performance.now() - start;\n          throw err;\n        },\n      ) as T;\n    }\n    step.durationMs = performance.now() - start;\n    return result;\n  } catch (err) {\n    step.durationMs = performance.now() - start;\n    throw err;\n  }\n}\n\n/**\n * Wrap an assertion as a Then step with timing and error capture.\n * Shorthand for `story.fn('Then', text, body)`.\n */\nfunction storyExpect<T>(text: string, body: () => T): T {\n  return fn('Then', text, body);\n}\n\n// ============================================================================\n// Export story object\n// ============================================================================\n\nexport const story = {\n  init,\n\n  // BDD step markers\n  given: createStepMarker('Given'),\n  when: createStepMarker('When'),\n  then: createStepMarker('Then'),\n  and: createStepMarker('And'),\n  but: createStepMarker('But'),\n\n  // AAA pattern aliases\n  arrange: createStepMarker('Given'),\n  act: createStepMarker('When'),\n  assert: createStepMarker('Then'),\n\n  // Additional aliases\n  setup: createStepMarker('Given'),\n  context: createStepMarker('Given'),\n  execute: createStepMarker('When'),\n  action: createStepMarker('When'),\n  verify: createStepMarker('Then'),\n\n  // Standalone doc methods\n  note(text: string): void {\n    attachDoc({ kind: 'note', text, phase: 'runtime' });\n  },\n\n  tag(name: string | string[]): void {\n    const names = Array.isArray(name) ? name : [name];\n    attachDoc({ kind: 'tag', names, phase: 'runtime' });\n  },\n\n  kv(options: KvOptions): void {\n    attachDoc({ kind: 'kv', label: options.label, value: options.value, phase: 'runtime' });\n  },\n\n  json(options: JsonOptions): void {\n    const content = JSON.stringify(options.value, null, 2);\n    attachDoc({ kind: 'code', label: options.label, content, lang: 'json', phase: 'runtime' });\n  },\n\n  code(options: CodeOptions): void {\n    attachDoc({ kind: 'code', label: options.label, content: options.content, lang: options.lang, phase: 'runtime' });\n  },\n\n  table(options: TableOptions): void {\n    attachDoc({ kind: 'table', label: options.label, columns: options.columns, rows: options.rows, phase: 'runtime' });\n  },\n\n  link(options: LinkOptions): void {\n    attachDoc({ kind: 'link', label: options.label, url: options.url, phase: 'runtime' });\n  },\n\n  section(options: SectionOptions): void {\n    attachDoc({ kind: 'section', title: options.title, markdown: options.markdown, phase: 'runtime' });\n  },\n\n  mermaid(options: MermaidOptions): void {\n    attachDoc({ kind: 'mermaid', code: options.code, title: options.title, phase: 'runtime' });\n  },\n\n  screenshot(options: ScreenshotOptions): void {\n    attachDoc({ kind: 'screenshot', path: options.path, alt: options.alt, phase: 'runtime' });\n  },\n\n  custom(options: CustomOptions): void {\n    attachDoc({ kind: 'custom', type: options.type, data: options.data, phase: 'runtime' });\n  },\n\n  // Attachments\n  attach(options: AttachmentOptions): void {\n    const ctx = getContext();\n    const stepIndex = ctx.currentStep\n      ? ctx.meta.steps.indexOf(ctx.currentStep)\n      : undefined;\n    ctx.attachments.push({\n      ...options,\n      stepIndex: stepIndex !== undefined && stepIndex >= 0 ? stepIndex : undefined,\n      stepId: ctx.currentStep?.id,\n    });\n  },\n\n  // Step timing\n  startTimer(): number {\n    const ctx = getContext();\n    const token = ctx.timerCounter++;\n    const stepIndex = ctx.currentStep\n      ? ctx.meta.steps.indexOf(ctx.currentStep)\n      : undefined;\n    ctx.activeTimers.set(token, {\n      start: performance.now(),\n      stepIndex: stepIndex !== undefined && stepIndex >= 0 ? stepIndex : undefined,\n      stepId: ctx.currentStep?.id,\n      consumed: false,\n    });\n    return token;\n  },\n\n  endTimer(token: number): void {\n    const ctx = getContext();\n    const entry = ctx.activeTimers.get(token);\n    if (!entry || entry.consumed) return;\n\n    entry.consumed = true;\n    const durationMs = performance.now() - entry.start;\n\n    let step: StoryStep | undefined;\n    if (entry.stepId) {\n      step = ctx.meta.steps.find((s) => s.id === entry.stepId);\n    }\n    if (!step && entry.stepIndex !== undefined) {\n      step = ctx.meta.steps[entry.stepIndex];\n    }\n\n    if (step) {\n      step.durationMs = durationMs;\n    }\n  },\n\n  // Step wrappers\n  fn,\n  expect: storyExpect,\n};\n\nexport type Story = typeof story;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACwFA,IAAI,gBAAqC;AAGzC,IAAI,qBAAqB;AAKzB,SAAS,aAA2B;AAClC,MAAI,CAAC,eAAe;AAClB,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAMA,SAAS,iBAAiB,QAA6D;AACrF,MAAI,CAAC,OAAQ,QAAO;AACpB,SAAO,MAAM,QAAQ,MAAM,IAAI,SAAS,CAAC,MAAM;AACjD;AAEA,SAAS,0BAA0B,MAA6B;AAC9D,QAAM,UAAsB,CAAC;AAE7B,MAAI,KAAK,MAAM;AACb,YAAQ,KAAK,EAAE,MAAM,QAAQ,MAAM,KAAK,MAAM,OAAO,UAAU,CAAC;AAAA,EAClE;AACA,MAAI,KAAK,KAAK;AACZ,UAAM,QAAQ,MAAM,QAAQ,KAAK,GAAG,IAAI,KAAK,MAAM,CAAC,KAAK,GAAG;AAC5D,YAAQ,KAAK,EAAE,MAAM,OAAO,OAAO,OAAO,UAAU,CAAC;AAAA,EACvD;AACA,MAAI,KAAK,IAAI;AACX,eAAW,CAAC,OAAO,KAAK,KAAK,OAAO,QAAQ,KAAK,EAAE,GAAG;AACpD,cAAQ,KAAK,EAAE,MAAM,MAAM,OAAO,OAAO,OAAO,UAAU,CAAC;AAAA,IAC7D;AAAA,EACF;AACA,MAAI,KAAK,MAAM;AACb,YAAQ,KAAK;AAAA,MACX,MAAM;AAAA,MACN,OAAO,KAAK,KAAK;AAAA,MACjB,SAAS,KAAK,KAAK;AAAA,MACnB,MAAM,KAAK,KAAK;AAAA,MAChB,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACA,MAAI,KAAK,MAAM;AACb,YAAQ,KAAK;AAAA,MACX,MAAM;AAAA,MACN,OAAO,KAAK,KAAK;AAAA,MACjB,SAAS,KAAK,UAAU,KAAK,KAAK,OAAO,MAAM,CAAC;AAAA,MAChD,MAAM;AAAA,MACN,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACA,MAAI,KAAK,OAAO;AACd,YAAQ,KAAK;AAAA,MACX,MAAM;AAAA,MACN,OAAO,KAAK,MAAM;AAAA,MAClB,SAAS,KAAK,MAAM;AAAA,MACpB,MAAM,KAAK,MAAM;AAAA,MACjB,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACA,MAAI,KAAK,MAAM;AACb,YAAQ,KAAK;AAAA,MACX,MAAM;AAAA,MACN,OAAO,KAAK,KAAK;AAAA,MACjB,KAAK,KAAK,KAAK;AAAA,MACf,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACA,MAAI,KAAK,SAAS;AAChB,YAAQ,KAAK;AAAA,MACX,MAAM;AAAA,MACN,OAAO,KAAK,QAAQ;AAAA,MACpB,UAAU,KAAK,QAAQ;AAAA,MACvB,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACA,MAAI,KAAK,SAAS;AAChB,YAAQ,KAAK;AAAA,MACX,MAAM;AAAA,MACN,MAAM,KAAK,QAAQ;AAAA,MACnB,OAAO,KAAK,QAAQ;AAAA,MACpB,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACA,MAAI,KAAK,YAAY;AACnB,YAAQ,KAAK;AAAA,MACX,MAAM;AAAA,MACN,MAAM,KAAK,WAAW;AAAA,MACtB,KAAK,KAAK,WAAW;AAAA,MACrB,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AACA,MAAI,KAAK,QAAQ;AACf,YAAQ,KAAK;AAAA,MACX,MAAM;AAAA,MACN,MAAM,KAAK,OAAO;AAAA,MAClB,MAAM,KAAK,OAAO;AAAA,MAClB,OAAO;AAAA,IACT,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAEA,SAAS,UAAU,OAAuB;AACxC,QAAM,MAAM,WAAW;AACvB,MAAI,IAAI,aAAa;AACnB,QAAI,YAAY,SAAS,CAAC;AAC1B,QAAI,YAAY,KAAK,KAAK,KAAK;AAAA,EACjC,OAAO;AACL,QAAI,KAAK,SAAS,CAAC;AACnB,QAAI,KAAK,KAAK,KAAK,KAAK;AAAA,EAC1B;AACF;AAMA,SAAS,iBAAiB,WAA2C;AACnE,MAAI,UAAU,UAAU,EAAG,QAAO;AAClC,QAAM,YAAY,UAAU,MAAM,GAAG,EAAE;AACvC,SAAO,UAAU,SAAS,IAAI,YAAY;AAC5C;AAMA,SAAS,iBAAiB,SAAsB;AAC9C,SAAO,SAAS,WAAW,MAAc,MAAwB;AAC/D,UAAM,MAAM,WAAW;AACvB,UAAM,OAAkB;AAAA,MACtB,IAAI,QAAQ,IAAI,aAAa;AAAA,MAC7B;AAAA,MACA;AAAA,MACA,MAAM,OAAO,0BAA0B,IAAI,IAAI,CAAC;AAAA,IAClD;AACA,QAAI,KAAK,MAAM,KAAK,IAAI;AACxB,QAAI,cAAc;AAAA,EACpB;AACF;AAMA,SAAS,KAAK,SAA8B;AAC1C,QAAM,cAAc,QAAQ;AAC5B,QAAM,OAAO,QAAQ;AACrB,MAAI,CAAC,aAAa;AAChB,UAAM,IAAI,MAAM,uFAAuF;AAAA,EACzG;AAEA,QAAM,YAAY,YAAY,aAAa,CAAC,YAAY,KAAK;AAC7D,QAAM,WAAW,YAAY;AAC7B,QAAM,YAAY,iBAAiB,SAAS;AAC5C,QAAM,eAAe,MAAM,YAAY;AAEvC,QAAM,OAAkB;AAAA,IACtB;AAAA,IACA,OAAO,CAAC;AAAA,IACR;AAAA,IACA,MAAM,SAAS;AAAA,IACf,SAAS,iBAAiB,SAAS,MAAM;AAAA,IACzC,MAAM,SAAS;AAAA,IACf,aAAa;AAAA,EACf;AAEA,kBAAgB;AAAA,IACd;AAAA,IACA,aAAa;AAAA,IACb,aAAa;AAAA,IACb,aAAa,CAAC;AAAA,IACd,cAAc,oBAAI,IAAI;AAAA,IACtB,cAAc;AAAA,IACd;AAAA,IACA;AAAA,EACF;AACF;AAOO,SAAS,kBAA4C;AAC1D,MAAI,CAAC,cAAe,QAAO;AAC3B,QAAM,UAA6B;AAAA,IACjC,cAAc,cAAc;AAAA,IAC5B,WAAW,cAAc;AAAA,IACzB,MAAM,cAAc;AAAA,IACpB,aAAa,cAAc,YAAY,SAAS,IAAI,cAAc,cAAc;AAAA,EAClF;AACA,kBAAgB;AAChB,SAAO;AACT;AAUA,SAAS,GAAM,SAAsB,MAAc,MAAkB;AACnE,QAAM,MAAM,WAAW;AACvB,QAAM,OAAkB;AAAA,IACtB,IAAI,QAAQ,IAAI,aAAa;AAAA,IAC7B;AAAA,IACA;AAAA,IACA,MAAM,CAAC;AAAA,IACP,SAAS;AAAA,EACX;AACA,MAAI,KAAK,MAAM,KAAK,IAAI;AACxB,MAAI,cAAc;AAElB,QAAM,QAAQ,YAAY,IAAI;AAC9B,MAAI;AACF,UAAM,SAAS,KAAK;AACpB,QAAI,kBAAkB,SAAS;AAC7B,aAAO,OAAO;AAAA,QACZ,CAAC,QAAQ;AACP,eAAK,aAAa,YAAY,IAAI,IAAI;AACtC,iBAAO;AAAA,QACT;AAAA,QACA,CAAC,QAAQ;AACP,eAAK,aAAa,YAAY,IAAI,IAAI;AACtC,gBAAM;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,SAAK,aAAa,YAAY,IAAI,IAAI;AACtC,WAAO;AAAA,EACT,SAAS,KAAK;AACZ,SAAK,aAAa,YAAY,IAAI,IAAI;AACtC,UAAM;AAAA,EACR;AACF;AAMA,SAAS,YAAe,MAAc,MAAkB;AACtD,SAAO,GAAG,QAAQ,MAAM,IAAI;AAC9B;AAMO,IAAM,QAAQ;AAAA,EACnB;AAAA;AAAA,EAGA,OAAO,iBAAiB,OAAO;AAAA,EAC/B,MAAM,iBAAiB,MAAM;AAAA,EAC7B,MAAM,iBAAiB,MAAM;AAAA,EAC7B,KAAK,iBAAiB,KAAK;AAAA,EAC3B,KAAK,iBAAiB,KAAK;AAAA;AAAA,EAG3B,SAAS,iBAAiB,OAAO;AAAA,EACjC,KAAK,iBAAiB,MAAM;AAAA,EAC5B,QAAQ,iBAAiB,MAAM;AAAA;AAAA,EAG/B,OAAO,iBAAiB,OAAO;AAAA,EAC/B,SAAS,iBAAiB,OAAO;AAAA,EACjC,SAAS,iBAAiB,MAAM;AAAA,EAChC,QAAQ,iBAAiB,MAAM;AAAA,EAC/B,QAAQ,iBAAiB,MAAM;AAAA;AAAA,EAG/B,KAAK,MAAoB;AACvB,cAAU,EAAE,MAAM,QAAQ,MAAM,OAAO,UAAU,CAAC;AAAA,EACpD;AAAA,EAEA,IAAI,MAA+B;AACjC,UAAM,QAAQ,MAAM,QAAQ,IAAI,IAAI,OAAO,CAAC,IAAI;AAChD,cAAU,EAAE,MAAM,OAAO,OAAO,OAAO,UAAU,CAAC;AAAA,EACpD;AAAA,EAEA,GAAG,SAA0B;AAC3B,cAAU,EAAE,MAAM,MAAM,OAAO,QAAQ,OAAO,OAAO,QAAQ,OAAO,OAAO,UAAU,CAAC;AAAA,EACxF;AAAA,EAEA,KAAK,SAA4B;AAC/B,UAAM,UAAU,KAAK,UAAU,QAAQ,OAAO,MAAM,CAAC;AACrD,cAAU,EAAE,MAAM,QAAQ,OAAO,QAAQ,OAAO,SAAS,MAAM,QAAQ,OAAO,UAAU,CAAC;AAAA,EAC3F;AAAA,EAEA,KAAK,SAA4B;AAC/B,cAAU,EAAE,MAAM,QAAQ,OAAO,QAAQ,OAAO,SAAS,QAAQ,SAAS,MAAM,QAAQ,MAAM,OAAO,UAAU,CAAC;AAAA,EAClH;AAAA,EAEA,MAAM,SAA6B;AACjC,cAAU,EAAE,MAAM,SAAS,OAAO,QAAQ,OAAO,SAAS,QAAQ,SAAS,MAAM,QAAQ,MAAM,OAAO,UAAU,CAAC;AAAA,EACnH;AAAA,EAEA,KAAK,SAA4B;AAC/B,cAAU,EAAE,MAAM,QAAQ,OAAO,QAAQ,OAAO,KAAK,QAAQ,KAAK,OAAO,UAAU,CAAC;AAAA,EACtF;AAAA,EAEA,QAAQ,SAA+B;AACrC,cAAU,EAAE,MAAM,WAAW,OAAO,QAAQ,OAAO,UAAU,QAAQ,UAAU,OAAO,UAAU,CAAC;AAAA,EACnG;AAAA,EAEA,QAAQ,SAA+B;AACrC,cAAU,EAAE,MAAM,WAAW,MAAM,QAAQ,MAAM,OAAO,QAAQ,OAAO,OAAO,UAAU,CAAC;AAAA,EAC3F;AAAA,EAEA,WAAW,SAAkC;AAC3C,cAAU,EAAE,MAAM,cAAc,MAAM,QAAQ,MAAM,KAAK,QAAQ,KAAK,OAAO,UAAU,CAAC;AAAA,EAC1F;AAAA,EAEA,OAAO,SAA8B;AACnC,cAAU,EAAE,MAAM,UAAU,MAAM,QAAQ,MAAM,MAAM,QAAQ,MAAM,OAAO,UAAU,CAAC;AAAA,EACxF;AAAA;AAAA,EAGA,OAAO,SAAkC;AACvC,UAAM,MAAM,WAAW;AACvB,UAAM,YAAY,IAAI,cAClB,IAAI,KAAK,MAAM,QAAQ,IAAI,WAAW,IACtC;AACJ,QAAI,YAAY,KAAK;AAAA,MACnB,GAAG;AAAA,MACH,WAAW,cAAc,UAAa,aAAa,IAAI,YAAY;AAAA,MACnE,QAAQ,IAAI,aAAa;AAAA,IAC3B,CAAC;AAAA,EACH;AAAA;AAAA,EAGA,aAAqB;AACnB,UAAM,MAAM,WAAW;AACvB,UAAM,QAAQ,IAAI;AAClB,UAAM,YAAY,IAAI,cAClB,IAAI,KAAK,MAAM,QAAQ,IAAI,WAAW,IACtC;AACJ,QAAI,aAAa,IAAI,OAAO;AAAA,MAC1B,OAAO,YAAY,IAAI;AAAA,MACvB,WAAW,cAAc,UAAa,aAAa,IAAI,YAAY;AAAA,MACnE,QAAQ,IAAI,aAAa;AAAA,MACzB,UAAU;AAAA,IACZ,CAAC;AACD,WAAO;AAAA,EACT;AAAA,EAEA,SAAS,OAAqB;AAC5B,UAAM,MAAM,WAAW;AACvB,UAAM,QAAQ,IAAI,aAAa,IAAI,KAAK;AACxC,QAAI,CAAC,SAAS,MAAM,SAAU;AAE9B,UAAM,WAAW;AACjB,UAAM,aAAa,YAAY,IAAI,IAAI,MAAM;AAE7C,QAAI;AACJ,QAAI,MAAM,QAAQ;AAChB,aAAO,IAAI,KAAK,MAAM,KAAK,CAAC,MAAM,EAAE,OAAO,MAAM,MAAM;AAAA,IACzD;AACA,QAAI,CAAC,QAAQ,MAAM,cAAc,QAAW;AAC1C,aAAO,IAAI,KAAK,MAAM,MAAM,SAAS;AAAA,IACvC;AAEA,QAAI,MAAM;AACR,WAAK,aAAa;AAAA,IACpB;AAAA,EACF;AAAA;AAAA,EAGA;AAAA,EACA,QAAQ;AACV;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,173 @@
+import { StoryMeta as StoryMeta$1, StepKeyword } from 'executable-stories-formatters';
+export { DocEntry, StepKeyword, StoryMeta, StoryStep } from 'executable-stories-formatters';
+
+/**
+ * Shared types between browser (story-api) and Node (store, reporter).
+ * No Cypress or Node-only imports so both environments can use them.
+ */
+
+type StoryMeta = StoryMeta$1;
+/** Scoped attachment stored in context. */
+interface ScopedAttachment {
+    name: string;
+    mediaType: string;
+    path?: string;
+    body?: string | Buffer;
+    encoding?: 'BASE64' | 'IDENTITY';
+    charset?: string;
+    fileName?: string;
+    stepIndex?: number;
+    stepId?: string;
+}
+/** Payload sent from browser to Node via cy.task for the reporter to merge with run results */
+interface RecordMetaPayload {
+    specRelative: string;
+    titlePath: string[];
+    meta: StoryMeta;
+    attachments?: ScopedAttachment[];
+}
+/** All inline doc options that can be passed to step markers. */
+interface StoryDocs {
+    note?: string;
+    tag?: string | string[];
+    kv?: Record<string, unknown>;
+    json?: JsonOptions;
+    table?: TableOptions;
+    link?: LinkOptions;
+    code?: CodeOptions;
+    section?: SectionOptions;
+    mermaid?: MermaidOptions;
+    screenshot?: ScreenshotOptions;
+    custom?: CustomOptions;
+}
+/** Options for story.init(). */
+interface StoryOptions {
+    tags?: string[];
+    ticket?: string | string[];
+    meta?: Record<string, unknown>;
+}
+/** Options for story.attach(). */
+interface AttachmentOptions {
+    name: string;
+    mediaType: string;
+    path?: string;
+    body?: string | Buffer;
+}
+interface KvOptions {
+    label: string;
+    value: unknown;
+}
+interface JsonOptions {
+    label: string;
+    value: unknown;
+}
+interface CodeOptions {
+    label: string;
+    content: string;
+    lang?: string;
+}
+interface TableOptions {
+    label: string;
+    columns: string[];
+    rows: string[][];
+}
+interface LinkOptions {
+    label: string;
+    url: string;
+}
+interface SectionOptions {
+    title: string;
+    markdown: string;
+}
+interface MermaidOptions {
+    code: string;
+    title?: string;
+}
+interface ScreenshotOptions {
+    path: string;
+    alt?: string;
+}
+interface CustomOptions {
+    type: string;
+    data: unknown;
+}
+
+/**
+ * Cypress story.* API for executable-stories.
+ *
+ * Uses native Cypress describe/it with opt-in documentation.
+ * Story meta is flushed to Node via cy.task from the support file.
+ *
+ * @example
+ * ```ts
+ * import { story } from 'executable-stories-cypress';
+ *
+ * describe('Calculator', () => {
+ *   it('adds two numbers', () => {
+ *     story.init();
+ *
+ *     story.given('two numbers 5 and 3');
+ *     const a = 5, b = 3;
+ *
+ *     story.when('I add them together');
+ *     const result = a + b;
+ *
+ *     story.then('the result is 8');
+ *     expect(result).toBe(8);
+ *   });
+ * });
+ * ```
+ */
+
+declare function init(options?: StoryOptions): void;
+/**
+ * Get the current story meta and clear the active context.
+ * Called by the support file after each test to send meta to Node via cy.task.
+ * Returns null if story.init() was never called for this test.
+ */
+declare function getAndClearMeta(): RecordMetaPayload | null;
+/**
+ * Wrap a function as a step with timing and error capture.
+ * Records the step with `wrapped: true` and `durationMs`.
+ */
+declare function fn<T>(keyword: StepKeyword, text: string, body: () => T): T;
+/**
+ * Wrap an assertion as a Then step with timing and error capture.
+ * Shorthand for `story.fn('Then', text, body)`.
+ */
+declare function storyExpect<T>(text: string, body: () => T): T;
+declare const story: {
+    init: typeof init;
+    given: (text: string, docs?: StoryDocs) => void;
+    when: (text: string, docs?: StoryDocs) => void;
+    then: (text: string, docs?: StoryDocs) => void;
+    and: (text: string, docs?: StoryDocs) => void;
+    but: (text: string, docs?: StoryDocs) => void;
+    arrange: (text: string, docs?: StoryDocs) => void;
+    act: (text: string, docs?: StoryDocs) => void;
+    assert: (text: string, docs?: StoryDocs) => void;
+    setup: (text: string, docs?: StoryDocs) => void;
+    context: (text: string, docs?: StoryDocs) => void;
+    execute: (text: string, docs?: StoryDocs) => void;
+    action: (text: string, docs?: StoryDocs) => void;
+    verify: (text: string, docs?: StoryDocs) => void;
+    note(text: string): void;
+    tag(name: string | string[]): void;
+    kv(options: KvOptions): void;
+    json(options: JsonOptions): void;
+    code(options: CodeOptions): void;
+    table(options: TableOptions): void;
+    link(options: LinkOptions): void;
+    section(options: SectionOptions): void;
+    mermaid(options: MermaidOptions): void;
+    screenshot(options: ScreenshotOptions): void;
+    custom(options: CustomOptions): void;
+    attach(options: AttachmentOptions): void;
+    startTimer(): number;
+    endTimer(token: number): void;
+    fn: typeof fn;
+    expect: typeof storyExpect;
+};
+type Story = typeof story;
+
+export { type CodeOptions, type CustomOptions, type JsonOptions, type KvOptions, type LinkOptions, type MermaidOptions, type RecordMetaPayload, type ScreenshotOptions, type SectionOptions, type Story, type StoryDocs, type StoryOptions, type TableOptions, getAndClearMeta, story };