executable-stories-formatters 0.15.1 → 0.17.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { C as CIInfo, T as TestRunResult, a as TestCaseResult, S as StoryStep, D as DocEntry, b as TestStatus$1, N as NormalizedTicket, A as Attachment, c as DocPhase, O as OtelSpan, d as StepResult, e as CIProvider, R as RawStatus, f as RawAttachment, g as RawRun, h as RawCIInfo, i as StepKeyword$1, j as adaptJestRun, k as adaptPlaywrightRun, l as adaptVitestRun } from './index-CXrzCk9p.cjs';
 export { m as CIInfo, n as CoverageSummary, J as JestAdapterOptions, o as JestAggregatedResult, p as JestFileResult, q as JestTestResult, r as OtelAttributeValue, P as PlaywrightAdapterOptions, s as PlaywrightAnnotation, t as PlaywrightAttachment, u as PlaywrightError, v as PlaywrightLocation, w as PlaywrightStatus, x as PlaywrightTestCase, y as PlaywrightTestResult, z as RawStepEvent, B as RawTestCase, E as STORY_META_KEY, F as StepMode, G as StoryFileReport, H as StoryMeta, I as TestCaseAttempt, K as TestCaseEvidence, V as VitestAdapterOptions, L as VitestSerializedError, M as VitestState, Q as VitestTestCase, U as VitestTestModule, W as VitestTestResult, X as toCIInfo, Y as toRawCIInfo } from './index-CXrzCk9p.cjs';
+import * as http from 'node:http';
 
 /**
  * Notification types for webhook integrations (Slack, Teams).
@@ -502,7 +503,7 @@ interface ResolvedFormatterOptions {
     allowMissingAssets: boolean;
 }
 
-type ScenarioChangeKind = "added" | "removed" | "regressed" | "fixed" | "changed" | "unchanged";
+type ScenarioChangeKind = "added" | "removed" | "renamed" | "moved" | "regressed" | "fixed" | "changed" | "unchanged";
 interface ScenarioChangeFlags {
     status: boolean;
     steps: boolean;
@@ -541,12 +542,22 @@ interface ScenarioDiff {
     flags: ScenarioChangeFlags;
     changedFields: string[];
     durationDeltaMs?: number;
+    /** For `renamed`/`moved`: the baseline test-case id this behaviour was matched from. */
+    previousId?: string;
+    /** For `renamed`/`moved`: match confidence in 0..1 (1 = exact content fingerprint). */
+    matchConfidence?: number;
+    /** For `renamed`/`moved`: how the baseline/current pair was re-identified. */
+    matchedBy?: "fingerprint" | "similarity";
 }
 interface RunDiffSummary {
     totalBaseline: number;
     totalCurrent: number;
     added: number;
     removed: number;
+    /** Behaviours re-identified across a title change (content preserved). */
+    renamed: number;
+    /** Behaviours re-identified across a file move (content preserved). */
+    moved: number;
     changed: number;
     regressed: number;
     fixed: number;
@@ -1703,11 +1714,17 @@ interface RegenerateDeps {
     readFile?: (filePath: string) => string;
 }
 /**
- * Read a raw-run (or canonical) file and regenerate the requested agent
- * artifacts via the canonical {@link ReportGenerator}. Returns the written
- * file paths. This is the unit of work the watcher repeats; it is also useful
- * standalone for a one-shot regenerate.
+ * Read a raw-run (or canonical) file once, canonicalize it, and regenerate the
+ * requested agent artifacts via the canonical {@link ReportGenerator}. Returns
+ * both the written file paths and the canonical run, so a caller that also needs
+ * the run (e.g. `serve`, to diff it) does not read and canonicalize a second
+ * time. This is the unit of work the watcher repeats.
  */
+declare function regenerateRun(options: WatchOptions, deps?: RegenerateDeps): Promise<{
+    files: string[];
+    run: TestRunResult;
+}>;
+/** Regenerate artifacts and return just the written file paths. */
 declare function regenerateArtifacts(options: WatchOptions, deps?: RegenerateDeps): Promise<string[]>;
 interface WatchDeps extends RegenerateDeps {
     /** Watch a path, calling the listener on every change. Injectable for tests. */
@@ -1729,6 +1746,94 @@ interface WatchHandle {
  */
 declare function startWatch(options: WatchOptions, deps?: WatchDeps): WatchHandle;
 
+interface ServeOptions {
+    /** Path to the raw-run (or canonical) JSON the framework adapter writes. */
+    input: string;
+    outputDir: string;
+    outputName: string;
+    formats: OutputFormat[];
+    /** Input is "raw" (default) or already-canonical "canonical". */
+    inputType?: "raw" | "canonical";
+    /** Synthesize story metadata for plain tests (raw input only). Default true. */
+    synthesize?: boolean;
+    /** Port for the live server. Default 4321. */
+    port?: number;
+    /** Host to bind. Default "127.0.0.1". */
+    host?: string;
+    /** Coalesce rapid change events. Default 150ms. */
+    debounceMs?: number;
+}
+/**
+ * The realtime state the server renders. The session baseline is pinned to the
+ * first run we observe after boot, so the headline tracks the whole loop's
+ * trajectory rather than the noise between any two adjacent iterations.
+ */
+interface RunState {
+    /** First run observed this session — the trajectory anchor. */
+    sessionBaseline: TestRunResult | null;
+    /** The run immediately before {@link current} — the per-iteration anchor. */
+    previous: TestRunResult | null;
+    /** Latest run. */
+    current: TestRunResult | null;
+    /** How many runs we have observed since boot. */
+    runCount: number;
+}
+/**
+ * Fold a freshly-read run into the prior state. Pure so the trajectory logic is
+ * testable without a server or filesystem: the first run pins the session
+ * baseline; later runs shift `previous`/`current` forward.
+ */
+declare function advanceState(prev: RunState, run: TestRunResult): RunState;
+/** The two diffs the live view — and a portal payload — care about. */
+interface RunDeltas {
+    /** Versus the first run of the session: the loop's trajectory. */
+    session: RunDiffResult | null;
+    /** Versus the immediately-previous run: what the last iteration did. */
+    iteration: RunDiffResult | null;
+}
+/**
+ * Derive the session and per-iteration diffs from the run history. Both are null
+ * until there are two runs to compare. Pure, computed once per run — this is the
+ * single source the strip renders from and the same payload a portal sink would
+ * push, so neither re-runs the compare engine.
+ */
+declare function computeDeltas(state: RunState): RunDeltas;
+/**
+ * Render the delta strip that sits above the report. This is the one thing a
+ * dumb static server cannot do — it needs the prior runs and the compare
+ * engine. Pure, so the copy is unit-testable.
+ */
+declare function renderDeltaStrip(state: RunState): string;
+/**
+ * Inject the live bits into a generated (static) report without touching the
+ * file on disk: the strip after <body>, the style + reload client before
+ * </body>. The artifact stays a clean static file for the CI/Action path.
+ */
+declare function injectLiveBits(html: string, stripHtml: string): string;
+interface ServeDeps {
+    readFile?: (filePath: string) => string;
+    watch?: (filePath: string, listener: () => void) => {
+        close: () => void;
+    };
+    log?: (message: string) => void;
+    /** Inject a server factory for tests. */
+    createServer?: (handler: http.RequestListener) => http.Server;
+}
+interface ServeHandle {
+    /** Resolved listening port (useful when port 0 picks a free one). */
+    port: number;
+    close: () => void;
+}
+/**
+ * Serve the living docs at a URL and push a reload whenever the framework
+ * rewrites its raw-run. The watch loop (debounce, coalesce, initial build) is
+ * delegated to {@link startWatch}; `serve` only adds the HTTP surface and, on
+ * each run, the delta strip — "what changed since you started this loop" —
+ * rendered from the in-memory run history. That strip is the one thing a static
+ * file server cannot give you.
+ */
+declare function startServe(options: ServeOptions, deps?: ServeDeps): ServeHandle;
+
 interface BehaviorDiffEntry {
     id: string;
     title: string;
@@ -3531,4 +3636,4 @@ declare function normalizeVitestResults(testModules: Parameters<typeof adaptVite
  */
 declare function normalizePlaywrightResults(testResults: Parameters<typeof adaptPlaywrightRun>[0], adapterOptions?: Parameters<typeof adaptPlaywrightRun>[1], canonicalizeOptions?: CanonicalizeOptions): TestRunResult;
 
-export { type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, Attachment, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, CIProvider, type CanonicalizeOptions, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, DocEntry, DocPhase, ES_THEME_TOKENS_CSS, ES_THEME_TOKEN_VALUES, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type HtmlDocOptions, HtmlFormatter, type HtmlOptions, type HtmlTheme, type HtmlThemeName, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, NormalizedTicket, type NotificationSummary, type NotifyCondition, OtelSpan, type OtelTraceContext, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, type PerformanceTrend, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, RawAttachment, RawCIInfo, RawRun, RawStatus, type RecordDeploymentArgs, type RecordDeploymentResult, type ReleaseManifest, ReleaseManifestFormatter, type ReportAttachment, type ReportCIInfo, type ReportCoverageSummary, type ReportDocCode, type ReportDocCustom, type ReportDocEntry, type ReportDocKv, type ReportDocLink, type ReportDocMermaid, type ReportDocNote, type ReportDocScreenshot, type ReportDocSection, type ReportDocTable, type ReportDocTag, type ReportFeature, ReportGenerator, type ReportScenario, type ReportStep, type ReportSummary, type ReportTicket, type ResolvedFormatterOptions, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, STORY_REPORT_SCHEMA_MAJOR, STORY_REPORT_SCHEMA_VERSION, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StepKeyword$1 as StepKeyword, StepResult, type StoryReport, StoryReportJsonFormatter, type StoryReportJsonOptions, type StoryReportSchemaVersion, StoryStep, TestCaseResult, type TestHistory, type TestMetrics, TestRunResult, TestStatus$1 as TestStatus, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, CIInfo as TypedCIInfo, type ValidationResult, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, assertValidRun, buildCheck, buildGoal, buildHtmlDocEntry, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, canonicalizeRun, classifyStatusChange, clearVersionCache, computeTestMetrics, copyMarkdownAssets, createPrCommentSummary, createReportGenerator, deriveAudience, deriveChangeType, deriveStepResults, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, findGitDir, formatDuration, generateRunComparison, generateRunId, generateTestCaseId, getAvailableThemes, getCssOnlyThemes, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readPackageVersion, recordDeployment, regenerateArtifacts, renderCheck, renderGoal, renderTriage, resolveAttachment, resolveAttachments, resolveTheme, resolveTraceUrl, rewriteAssetPaths, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, signBody, slugify, startWatch, stripAnsi, toBehaviorManifest, toReleaseManifest, toScenarioIndex, toStoryReport, toTraceabilityMatrix, tryGetActiveOtelContext, updateHistory, validateCanonicalRun };
+export { type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, Attachment, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, CIProvider, type CanonicalizeOptions, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, DocEntry, DocPhase, ES_THEME_TOKENS_CSS, ES_THEME_TOKEN_VALUES, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type HtmlDocOptions, HtmlFormatter, type HtmlOptions, type HtmlTheme, type HtmlThemeName, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, NormalizedTicket, type NotificationSummary, type NotifyCondition, OtelSpan, type OtelTraceContext, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, type PerformanceTrend, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, RawAttachment, RawCIInfo, RawRun, RawStatus, type RecordDeploymentArgs, type RecordDeploymentResult, type ReleaseManifest, ReleaseManifestFormatter, type ReportAttachment, type ReportCIInfo, type ReportCoverageSummary, type ReportDocCode, type ReportDocCustom, type ReportDocEntry, type ReportDocKv, type ReportDocLink, type ReportDocMermaid, type ReportDocNote, type ReportDocScreenshot, type ReportDocSection, type ReportDocTable, type ReportDocTag, type ReportFeature, ReportGenerator, type ReportScenario, type ReportStep, type ReportSummary, type ReportTicket, type ResolvedFormatterOptions, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, type RunDeltas, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, type RunState, STORY_REPORT_SCHEMA_MAJOR, STORY_REPORT_SCHEMA_VERSION, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type ServeDeps, type ServeHandle, type ServeOptions, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StepKeyword$1 as StepKeyword, StepResult, type StoryReport, StoryReportJsonFormatter, type StoryReportJsonOptions, type StoryReportSchemaVersion, StoryStep, TestCaseResult, type TestHistory, type TestMetrics, TestRunResult, TestStatus$1 as TestStatus, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, CIInfo as TypedCIInfo, type ValidationResult, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, advanceState, assertValidRun, buildCheck, buildGoal, buildHtmlDocEntry, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, canonicalizeRun, classifyStatusChange, clearVersionCache, computeDeltas, computeTestMetrics, copyMarkdownAssets, createPrCommentSummary, createReportGenerator, deriveAudience, deriveChangeType, deriveStepResults, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, findGitDir, formatDuration, generateRunComparison, generateRunId, generateTestCaseId, getAvailableThemes, getCssOnlyThemes, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, injectLiveBits, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readPackageVersion, recordDeployment, regenerateArtifacts, regenerateRun, renderCheck, renderDeltaStrip, renderGoal, renderTriage, resolveAttachment, resolveAttachments, resolveTheme, resolveTraceUrl, rewriteAssetPaths, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, signBody, slugify, startServe, startWatch, stripAnsi, toBehaviorManifest, toReleaseManifest, toScenarioIndex, toStoryReport, toTraceabilityMatrix, tryGetActiveOtelContext, updateHistory, validateCanonicalRun };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { C as CIInfo, T as TestRunResult, a as TestCaseResult, S as StoryStep, D as DocEntry, b as TestStatus$1, N as NormalizedTicket, A as Attachment, c as DocPhase, O as OtelSpan, d as StepResult, e as CIProvider, R as RawStatus, f as RawAttachment, g as RawRun, h as RawCIInfo, i as StepKeyword$1, j as adaptJestRun, k as adaptPlaywrightRun, l as adaptVitestRun } from './index-CXrzCk9p.js';
 export { m as CIInfo, n as CoverageSummary, J as JestAdapterOptions, o as JestAggregatedResult, p as JestFileResult, q as JestTestResult, r as OtelAttributeValue, P as PlaywrightAdapterOptions, s as PlaywrightAnnotation, t as PlaywrightAttachment, u as PlaywrightError, v as PlaywrightLocation, w as PlaywrightStatus, x as PlaywrightTestCase, y as PlaywrightTestResult, z as RawStepEvent, B as RawTestCase, E as STORY_META_KEY, F as StepMode, G as StoryFileReport, H as StoryMeta, I as TestCaseAttempt, K as TestCaseEvidence, V as VitestAdapterOptions, L as VitestSerializedError, M as VitestState, Q as VitestTestCase, U as VitestTestModule, W as VitestTestResult, X as toCIInfo, Y as toRawCIInfo } from './index-CXrzCk9p.js';
+import * as http from 'node:http';
 
 /**
  * Notification types for webhook integrations (Slack, Teams).
@@ -502,7 +503,7 @@ interface ResolvedFormatterOptions {
     allowMissingAssets: boolean;
 }
 
-type ScenarioChangeKind = "added" | "removed" | "regressed" | "fixed" | "changed" | "unchanged";
+type ScenarioChangeKind = "added" | "removed" | "renamed" | "moved" | "regressed" | "fixed" | "changed" | "unchanged";
 interface ScenarioChangeFlags {
     status: boolean;
     steps: boolean;
@@ -541,12 +542,22 @@ interface ScenarioDiff {
     flags: ScenarioChangeFlags;
     changedFields: string[];
     durationDeltaMs?: number;
+    /** For `renamed`/`moved`: the baseline test-case id this behaviour was matched from. */
+    previousId?: string;
+    /** For `renamed`/`moved`: match confidence in 0..1 (1 = exact content fingerprint). */
+    matchConfidence?: number;
+    /** For `renamed`/`moved`: how the baseline/current pair was re-identified. */
+    matchedBy?: "fingerprint" | "similarity";
 }
 interface RunDiffSummary {
     totalBaseline: number;
     totalCurrent: number;
     added: number;
     removed: number;
+    /** Behaviours re-identified across a title change (content preserved). */
+    renamed: number;
+    /** Behaviours re-identified across a file move (content preserved). */
+    moved: number;
     changed: number;
     regressed: number;
     fixed: number;
@@ -1703,11 +1714,17 @@ interface RegenerateDeps {
     readFile?: (filePath: string) => string;
 }
 /**
- * Read a raw-run (or canonical) file and regenerate the requested agent
- * artifacts via the canonical {@link ReportGenerator}. Returns the written
- * file paths. This is the unit of work the watcher repeats; it is also useful
- * standalone for a one-shot regenerate.
+ * Read a raw-run (or canonical) file once, canonicalize it, and regenerate the
+ * requested agent artifacts via the canonical {@link ReportGenerator}. Returns
+ * both the written file paths and the canonical run, so a caller that also needs
+ * the run (e.g. `serve`, to diff it) does not read and canonicalize a second
+ * time. This is the unit of work the watcher repeats.
  */
+declare function regenerateRun(options: WatchOptions, deps?: RegenerateDeps): Promise<{
+    files: string[];
+    run: TestRunResult;
+}>;
+/** Regenerate artifacts and return just the written file paths. */
 declare function regenerateArtifacts(options: WatchOptions, deps?: RegenerateDeps): Promise<string[]>;
 interface WatchDeps extends RegenerateDeps {
     /** Watch a path, calling the listener on every change. Injectable for tests. */
@@ -1729,6 +1746,94 @@ interface WatchHandle {
  */
 declare function startWatch(options: WatchOptions, deps?: WatchDeps): WatchHandle;
 
+interface ServeOptions {
+    /** Path to the raw-run (or canonical) JSON the framework adapter writes. */
+    input: string;
+    outputDir: string;
+    outputName: string;
+    formats: OutputFormat[];
+    /** Input is "raw" (default) or already-canonical "canonical". */
+    inputType?: "raw" | "canonical";
+    /** Synthesize story metadata for plain tests (raw input only). Default true. */
+    synthesize?: boolean;
+    /** Port for the live server. Default 4321. */
+    port?: number;
+    /** Host to bind. Default "127.0.0.1". */
+    host?: string;
+    /** Coalesce rapid change events. Default 150ms. */
+    debounceMs?: number;
+}
+/**
+ * The realtime state the server renders. The session baseline is pinned to the
+ * first run we observe after boot, so the headline tracks the whole loop's
+ * trajectory rather than the noise between any two adjacent iterations.
+ */
+interface RunState {
+    /** First run observed this session — the trajectory anchor. */
+    sessionBaseline: TestRunResult | null;
+    /** The run immediately before {@link current} — the per-iteration anchor. */
+    previous: TestRunResult | null;
+    /** Latest run. */
+    current: TestRunResult | null;
+    /** How many runs we have observed since boot. */
+    runCount: number;
+}
+/**
+ * Fold a freshly-read run into the prior state. Pure so the trajectory logic is
+ * testable without a server or filesystem: the first run pins the session
+ * baseline; later runs shift `previous`/`current` forward.
+ */
+declare function advanceState(prev: RunState, run: TestRunResult): RunState;
+/** The two diffs the live view — and a portal payload — care about. */
+interface RunDeltas {
+    /** Versus the first run of the session: the loop's trajectory. */
+    session: RunDiffResult | null;
+    /** Versus the immediately-previous run: what the last iteration did. */
+    iteration: RunDiffResult | null;
+}
+/**
+ * Derive the session and per-iteration diffs from the run history. Both are null
+ * until there are two runs to compare. Pure, computed once per run — this is the
+ * single source the strip renders from and the same payload a portal sink would
+ * push, so neither re-runs the compare engine.
+ */
+declare function computeDeltas(state: RunState): RunDeltas;
+/**
+ * Render the delta strip that sits above the report. This is the one thing a
+ * dumb static server cannot do — it needs the prior runs and the compare
+ * engine. Pure, so the copy is unit-testable.
+ */
+declare function renderDeltaStrip(state: RunState): string;
+/**
+ * Inject the live bits into a generated (static) report without touching the
+ * file on disk: the strip after <body>, the style + reload client before
+ * </body>. The artifact stays a clean static file for the CI/Action path.
+ */
+declare function injectLiveBits(html: string, stripHtml: string): string;
+interface ServeDeps {
+    readFile?: (filePath: string) => string;
+    watch?: (filePath: string, listener: () => void) => {
+        close: () => void;
+    };
+    log?: (message: string) => void;
+    /** Inject a server factory for tests. */
+    createServer?: (handler: http.RequestListener) => http.Server;
+}
+interface ServeHandle {
+    /** Resolved listening port (useful when port 0 picks a free one). */
+    port: number;
+    close: () => void;
+}
+/**
+ * Serve the living docs at a URL and push a reload whenever the framework
+ * rewrites its raw-run. The watch loop (debounce, coalesce, initial build) is
+ * delegated to {@link startWatch}; `serve` only adds the HTTP surface and, on
+ * each run, the delta strip — "what changed since you started this loop" —
+ * rendered from the in-memory run history. That strip is the one thing a static
+ * file server cannot give you.
+ */
+declare function startServe(options: ServeOptions, deps?: ServeDeps): ServeHandle;
+
 interface BehaviorDiffEntry {
     id: string;
     title: string;
@@ -3531,4 +3636,4 @@ declare function normalizeVitestResults(testModules: Parameters<typeof adaptVite
  */
 declare function normalizePlaywrightResults(testResults: Parameters<typeof adaptPlaywrightRun>[0], adapterOptions?: Parameters<typeof adaptPlaywrightRun>[1], canonicalizeOptions?: CanonicalizeOptions): TestRunResult;
 
-export { type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, Attachment, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, CIProvider, type CanonicalizeOptions, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, DocEntry, DocPhase, ES_THEME_TOKENS_CSS, ES_THEME_TOKEN_VALUES, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type HtmlDocOptions, HtmlFormatter, type HtmlOptions, type HtmlTheme, type HtmlThemeName, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, NormalizedTicket, type NotificationSummary, type NotifyCondition, OtelSpan, type OtelTraceContext, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, type PerformanceTrend, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, RawAttachment, RawCIInfo, RawRun, RawStatus, type RecordDeploymentArgs, type RecordDeploymentResult, type ReleaseManifest, ReleaseManifestFormatter, type ReportAttachment, type ReportCIInfo, type ReportCoverageSummary, type ReportDocCode, type ReportDocCustom, type ReportDocEntry, type ReportDocKv, type ReportDocLink, type ReportDocMermaid, type ReportDocNote, type ReportDocScreenshot, type ReportDocSection, type ReportDocTable, type ReportDocTag, type ReportFeature, ReportGenerator, type ReportScenario, type ReportStep, type ReportSummary, type ReportTicket, type ResolvedFormatterOptions, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, STORY_REPORT_SCHEMA_MAJOR, STORY_REPORT_SCHEMA_VERSION, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StepKeyword$1 as StepKeyword, StepResult, type StoryReport, StoryReportJsonFormatter, type StoryReportJsonOptions, type StoryReportSchemaVersion, StoryStep, TestCaseResult, type TestHistory, type TestMetrics, TestRunResult, TestStatus$1 as TestStatus, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, CIInfo as TypedCIInfo, type ValidationResult, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, assertValidRun, buildCheck, buildGoal, buildHtmlDocEntry, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, canonicalizeRun, classifyStatusChange, clearVersionCache, computeTestMetrics, copyMarkdownAssets, createPrCommentSummary, createReportGenerator, deriveAudience, deriveChangeType, deriveStepResults, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, findGitDir, formatDuration, generateRunComparison, generateRunId, generateTestCaseId, getAvailableThemes, getCssOnlyThemes, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readPackageVersion, recordDeployment, regenerateArtifacts, renderCheck, renderGoal, renderTriage, resolveAttachment, resolveAttachments, resolveTheme, resolveTraceUrl, rewriteAssetPaths, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, signBody, slugify, startWatch, stripAnsi, toBehaviorManifest, toReleaseManifest, toScenarioIndex, toStoryReport, toTraceabilityMatrix, tryGetActiveOtelContext, updateHistory, validateCanonicalRun };
+export { type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, Attachment, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, CIProvider, type CanonicalizeOptions, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, DocEntry, DocPhase, ES_THEME_TOKENS_CSS, ES_THEME_TOKEN_VALUES, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type HtmlDocOptions, HtmlFormatter, type HtmlOptions, type HtmlTheme, type HtmlThemeName, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, NormalizedTicket, type NotificationSummary, type NotifyCondition, OtelSpan, type OtelTraceContext, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, type PerformanceTrend, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, RawAttachment, RawCIInfo, RawRun, RawStatus, type RecordDeploymentArgs, type RecordDeploymentResult, type ReleaseManifest, ReleaseManifestFormatter, type ReportAttachment, type ReportCIInfo, type ReportCoverageSummary, type ReportDocCode, type ReportDocCustom, type ReportDocEntry, type ReportDocKv, type ReportDocLink, type ReportDocMermaid, type ReportDocNote, type ReportDocScreenshot, type ReportDocSection, type ReportDocTable, type ReportDocTag, type ReportFeature, ReportGenerator, type ReportScenario, type ReportStep, type ReportSummary, type ReportTicket, type ResolvedFormatterOptions, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, type RunDeltas, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, type RunState, STORY_REPORT_SCHEMA_MAJOR, STORY_REPORT_SCHEMA_VERSION, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type ServeDeps, type ServeHandle, type ServeOptions, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StepKeyword$1 as StepKeyword, StepResult, type StoryReport, StoryReportJsonFormatter, type StoryReportJsonOptions, type StoryReportSchemaVersion, StoryStep, TestCaseResult, type TestHistory, type TestMetrics, TestRunResult, TestStatus$1 as TestStatus, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, CIInfo as TypedCIInfo, type ValidationResult, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, advanceState, assertValidRun, buildCheck, buildGoal, buildHtmlDocEntry, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, canonicalizeRun, classifyStatusChange, clearVersionCache, computeDeltas, computeTestMetrics, copyMarkdownAssets, createPrCommentSummary, createReportGenerator, deriveAudience, deriveChangeType, deriveStepResults, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, findGitDir, formatDuration, generateRunComparison, generateRunId, generateTestCaseId, getAvailableThemes, getCssOnlyThemes, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, injectLiveBits, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readPackageVersion, recordDeployment, regenerateArtifacts, regenerateRun, renderCheck, renderDeltaStrip, renderGoal, renderTriage, resolveAttachment, resolveAttachments, resolveTheme, resolveTraceUrl, rewriteAssetPaths, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, signBody, slugify, startServe, startWatch, stripAnsi, toBehaviorManifest, toReleaseManifest, toScenarioIndex, toStoryReport, toTraceabilityMatrix, tryGetActiveOtelContext, updateHistory, validateCanonicalRun };