@pikku/core 0.12.117 → 0.12.118

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## 0.12.118
+
+### Patch Changes
+
+- b4a895e: A scenario step row now carries where it fell inside each actor's recording, and a scenario result now says which feature it came from by id as well as by title.
+
+  The video offset is recorded rather than estimated. Documentation built out of a run has to turn a step sentence into an exact moment — a chapter marker, or a still pulled with `ffmpeg -ss` — and the only number available until now was the scenario clock summed out of the ladder. That clock is not the video's: recording starts when the actor's browser context opens, which is somewhere after step one, and every RPC step before or between the browser ones burns scenario time while the file sits still. The two drift apart by however much of the scenario happened off camera, and a still forty seconds out is a picture of the wrong screen with nothing to say it is wrong.
+
+  So `ScenarioStepRow.video` is stamped at the moment the step runs, from the driver's own clock: `ScenarioBrowserProvider.videoStartedAt(actor)` reports when that actor's context was opened with `recordVideo`, and the runner subtracts. It is a list of `{ actor, offsetMs }` rather than one number, because a video belongs to an actor and not to the scenario — one step touching two windows falls at a different moment in each, and an offset that does not name its file cannot be seeked to. A run without video, a step with no actor, and a step that never ran all carry nothing, which is what keeps the console's existing estimate as the fallback for runs recorded before this.
+
+  `ScenarioResult.featureId` is the other half of the same problem. `feature` is a title written for people to read and rewritten whenever the wording improves, so nothing downstream could key off it; the id `addFeature` registered the feature under does not move. The runner threads it from the plan, which read it off the registry, instead of deriving it from the label. `scenarioName` already carried the registration id and keeps it.
+
+- b4a895e: `pikku scenario guide` writes the user guide a scenario suite already contains. A feature reads as a page and a scenario as a section, and a run leaves screenshots behind with the captions their author took them under — the command joins that to the editorial prose a project checks in under `docs/` and writes markdown. It renders no HTML, ships no components, resolves no asset URLs and calls no model: an image is an ordinary relative `![caption](path)`, and whoever consumes the markdown rewrites the paths.
+
+  A page cites a feature by leaving the marker pair where the block belongs:
+
+  ```markdown
+  ---
+  title: Deployments
+  ---
+
+  A deployment is one tracked shipment of your app.
+
+  <!-- pikku:guide feature=deploymentsFeature -->
+  <!-- /pikku:guide -->
+
+  ## Does my app go down during a deploy?
+  ```
+
+  That one line does both halves of the job. It says _where_ the block goes, which a frontmatter list cannot express, and it is what the coverage gate counts to decide _whether_ a feature is documented at all. The mapping stays many-to-many and falls out of the union of every marker in the tree. A rebuild rewrites exactly the regions between the markers, so every sentence a human wrote around them survives.
+
+  **The steps are evidence, not content.** A generated block is the scenario's title, the description its author wrote, and the shots it filed — never a numbered Given/When/Then ladder, which is a test report and not something anybody arrives at a documentation page wanting. The sentences are still what the guide is kept honest against: `docs/.guide.lock` records a hash of each feature's step sentences and artifact ids, deliberately not of the image bytes. Restyling a UI changes every screenshot and no sentence; inserting or renaming a step changes what the prose was describing, and the page is reported stale. The lock is generated and checked in, so no hash is ever typed or merged by hand — and a tree whose lock is untracked reports every page as current forever.
+
+  Every registered feature has to be cited by some page, and a feature that is pure plumbing says so rather than being written about — `pikkuFeature({ document: false })`, threaded through the inspector and `FeatureMeta`. An uncited feature fails the command by name; `--allow-undocumented` downgrades that one failure to a report. A page citing a feature id that is not registered stays an error either way.
+
+  A guide is only written out of a run that can stand behind it. A run that failed or was killed halfway is refused, because a page is a claim that the product does what it says. So is a narrowed one: `pikku scenario run --flows`/`--features`/`--tags` leaves out scenarios the suite has, and a guide built from it would describe those flows as though they do not exist. `ScenarioRunRecord.selection` records the filters a run was selected with, since nothing in the results afterwards can tell a suite of forty from forty that were asked for.
+
+  Results are joined to features by `featureId`, falling back to the display name only for records written before that field existed — a title is rewritten freely and two features may share one.
+
+  Emission is deterministic — identical inputs give byte-identical output, and no timestamp goes in that did not come from the run record. Frontmatter the compiler does not own (`slug`, `draft`, `sidebar_position`, anything else a docs site reads) passes through untouched, and a source written with CRLF line endings is read as having frontmatter.
+
 ## 0.12.117
 
 ### Patch Changes

package/dist/wirings/workflow/pikku-scenario-service.d.ts

@@ -3,11 +3,12 @@ import { InMemoryWorkflowService } from '../../services/in-memory-workflow-servi
 import type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 import type { ScenarioPersonas } from '../../services/personas-service.js';
+import type { ScenarioStepVideoOffset } from './scenario-run.types.js';
 import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } from './scenario-step.types.js';
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
 export { addFeature, resolveFeatureScenarios } from './feature.js';
 export type { CoreFeature, CoreFeatureScenario, FeatureMeta, FeaturesMeta, PikkuBrowserWire, PikkuScenarioWire, ScenarioBrowserFailure, ScenarioBrowserProvider, ScenarioEnvironment, ScenarioStepKind, ScenarioStepMeta, ScenarioStepOptions, ScenarioScreenshotOptions, ScenarioStepPhase, ScenarioSurface, TestIdSelector, } from './scenario.types.js';
-export type { ScenarioArtifact, ScenarioFailureDetail, ScenarioResult, ScenarioRunRecord, ScenarioRunReport, ScenarioRunStatus, ScenarioRunStore, ScenarioRunSummary, ScenarioStepRow, } from './scenario-run.types.js';
+export type { ScenarioArtifact, ScenarioFailureDetail, ScenarioResult, ScenarioRunRecord, ScenarioRunReport, ScenarioRunSelection, ScenarioRunStatus, ScenarioRunStore, ScenarioRunSummary, ScenarioStepRow, ScenarioStepVideoOffset, } from './scenario-run.types.js';
 export { SCENARIO_SURFACES } from './scenario-step.types.js';
 export { resolveScenarioSurfaces } from './scenario-surface.js';
 export { pollUntil, type PollOptions } from './scenario-poll.js';
@@ -161,6 +162,7 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     private readonly engine;
     private runActors;
     private runContexts;
+    private runVideoOffsets;
     private scenarioBrowserProvider?;
     private scenarioEnvironment?;
     private runSurface;
@@ -193,6 +195,23 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
      */
     setScenarioEnvironment(env: ScenarioEnvironment | undefined): void;
     getScenarioEnvironment(): ScenarioEnvironment | undefined;
+    /**
+     * Where each of a run's browser steps fell in its actor's video, keyed by the
+     * durable step name, handed over and forgotten in one call.
+     *
+     * Taken rather than read because the runner joins these onto the step rows
+     * after the run has finished — which is past the point anything else would
+     * clear them, and the only moment they are still wanted.
+     */
+    takeStepVideoOffsets(runId: string): Map<string, ScenarioStepVideoOffset[]>;
+    /**
+     * Stamp where a step began inside one actor's recording.
+     *
+     * First write per actor wins: a `then` step runs once per witness, and the
+     * moment the reader wants is when the sentence started, not when its last
+     * witness got around to the browser.
+     */
+    private recordVideoOffset;
     attachRunContext(runId: string, workflowMeta: any, options?: {
         actors?: ScenarioPersonas;
     }): Promise<void>;

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -243,6 +243,10 @@ export class PikkuScenarioService {
     // so the body and its hooks share one object rather than reading it back off
     // the persisted wire.
     runContexts = new Map();
+    // Where each browser step landed in its actor's recording, per run. Held
+    // apart from the run context because the runner reads it once the run has
+    // ended, which is exactly when `detachRunContext` has cleared that.
+    runVideoOffsets = new Map();
     scenarioBrowserProvider;
     scenarioEnvironment;
     runSurface = 'default';
@@ -292,6 +296,39 @@ export class PikkuScenarioService {
     getScenarioEnvironment() {
         return this.scenarioEnvironment;
     }
+    /**
+     * Where each of a run's browser steps fell in its actor's video, keyed by the
+     * durable step name, handed over and forgotten in one call.
+     *
+     * Taken rather than read because the runner joins these onto the step rows
+     * after the run has finished — which is past the point anything else would
+     * clear them, and the only moment they are still wanted.
+     */
+    takeStepVideoOffsets(runId) {
+        const offsets = this.runVideoOffsets.get(runId);
+        this.runVideoOffsets.delete(runId);
+        return offsets ?? new Map();
+    }
+    /**
+     * Stamp where a step began inside one actor's recording.
+     *
+     * First write per actor wins: a `then` step runs once per witness, and the
+     * moment the reader wants is when the sentence started, not when its last
+     * witness got around to the browser.
+     */
+    recordVideoOffset(runId, stepName, actor, offsetMs) {
+        let byStep = this.runVideoOffsets.get(runId);
+        if (!byStep) {
+            byStep = new Map();
+            this.runVideoOffsets.set(runId, byStep);
+        }
+        const offsets = byStep.get(stepName) ?? [];
+        if (offsets.some((offset) => offset.actor === actor)) {
+            return;
+        }
+        offsets.push({ actor, offsetMs });
+        byStep.set(stepName, offsets);
+    }
     async attachRunContext(runId, workflowMeta, options) {
         const actors = options?.actors ??
             (workflowMeta.source === 'scenario'
@@ -641,6 +678,10 @@ export class PikkuScenarioService {
                     // The dispatch guard above already refused an actor-less call, and a
                     // browser binding always requires one.
                     wire.browser = await this.scenarioBrowserProvider.sessionFor(actor.name);
+                    const videoStartedAt = this.scenarioBrowserProvider.videoStartedAt?.(actor.name);
+                    if (videoStartedAt !== undefined) {
+                        this.recordVideoOffset(runId, stepName, actor.name, Math.max(0, Date.now() - videoStartedAt));
+                    }
                 }
                 return await runPikkuFunc('workflow', workflowName, resolvedStepFunc, {
                     singletonServices: getSingletonServices(),

package/dist/wirings/workflow/scenario-run.types.d.ts

@@ -41,6 +41,21 @@ export interface ScenarioArtifact {
     /** Fit to show outside the run: a marketing card, a docs page, a gallery. */
     showcase?: boolean;
 }
+/**
+ * Where a step falls inside one actor's recording.
+ *
+ * Measured from the moment that actor's browser context opened — which is when
+ * Playwright starts the file — rather than from the start of the scenario, so
+ * it addresses the video's own clock. The two differ by however long the
+ * scenario spent before that window existed, plus every non-browser step since,
+ * which is why the offset is recorded at the moment the step runs instead of
+ * being summed back out of the ladder afterwards.
+ */
+export interface ScenarioStepVideoOffset {
+    /** Whose recording this offset is into: one actor, one video file. */
+    actor: string;
+    offsetMs: number;
+}
 /** One step of a run, already joined to the prose that declared it. */
 export interface ScenarioStepRow {
     sentence: string;
@@ -54,6 +69,16 @@ export interface ScenarioStepRow {
     status: string;
     durationMs?: number;
     error?: string;
+    /**
+     * Where this step lands in each actor's video, for the actors whose window
+     * was being recorded when it ran. Absent for a step with no actor, a run
+     * without video, and a step that never ran at all.
+     *
+     * A list rather than one number because a video belongs to an actor, not to
+     * the scenario: a step touching two windows falls at a different moment in
+     * each, and an offset that does not name its file cannot be seeked to.
+     */
+    video?: ScenarioStepVideoOffset[];
 }
 /** Everything known about why one scenario failed. */
 export interface ScenarioFailureDetail {
@@ -76,10 +101,22 @@ export interface ScenarioResult {
     error?: string;
     steps?: ScenarioStepRow[];
     failure?: ScenarioFailureDetail;
-    /** The scenario registration this ran, which the label alone does not give. */
+    /**
+     * The registered scenario this ran, by the id it is registered under — the
+     * same id `FeatureMetaEntry.scenario` references. The label alone does not
+     * give it, and unlike the label it is not rewritten when the prose is.
+     */
     scenarioName?: string;
-    /** The feature that grouped it, when one did. */
+    /** The feature that grouped it — its display name, which is freely renamed. */
     feature?: string;
+    /**
+     * The registered feature that grouped it, by id.
+     *
+     * `feature` is a title someone writes for people to read, so nothing that
+     * outlives a run can key off it. This is what `addFeature` registered the
+     * feature under, and it is what survives the title being rewritten.
+     */
+    featureId?: string;
     tags?: string[];
     /** Images and footage this scenario produced, filed under the run. */
     artifacts?: ScenarioArtifact[];
@@ -103,6 +140,21 @@ export interface ScenarioRunReport {
     hookFailures: string[];
 }
 export type ScenarioRunStatus = 'running' | 'passed' | 'failed';
+/**
+ * The filters a run was selected with, recorded when it was narrowed at all.
+ *
+ * A narrowed run is a partial record of the suite: scenarios a feature owns can
+ * be missing from it, and whole features can be absent, with nothing in the
+ * results to say so. Anything that reads a run as evidence of what the suite
+ * does — rather than of what happened that afternoon — has to be able to tell
+ * the two apart, and it cannot be inferred from the results afterwards.
+ */
+export interface ScenarioRunSelection {
+    flows?: string[];
+    features?: string[];
+    tags?: string[];
+    excludeTags?: string[];
+}
 /**
  * A whole run, as it is stored and read back.
  *
@@ -116,6 +168,8 @@ export interface ScenarioRunRecord extends ScenarioRunReport {
     status: ScenarioRunStatus;
     /** The surface the run targeted: `default`, `browser`, … */
     surface: string;
+    /** Absent on a run of the whole suite; see {@link ScenarioRunSelection}. */
+    selection?: ScenarioRunSelection;
     startedAt: string;
     finishedAt?: string;
 }

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -235,6 +235,15 @@ export interface ScenarioBrowserProvider {
      * scenario's reset, long after the outcome that decides whether to keep them.
      */
     endScenario?(outcome: 'passed' | 'failed'): void;
+    /**
+     * When this actor's recording started, as epoch milliseconds.
+     *
+     * The seam that keeps the video clock out of `@pikku/core`: a driver knows
+     * when it opened the context it passed `recordVideo` to, and the runner turns
+     * that into a per-step offset. Absent for an actor with no window open, and
+     * for a run recording nothing — both of which leave the step's offset off.
+     */
+    videoStartedAt?(actorName: string): number | undefined;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must

package/dist/wirings/workflow/scenario.types.d.ts

@@ -9,6 +9,14 @@ export type CoreFeature = {
     name: string;
     description?: string;
     tags?: string[];
+    /**
+     * Whether this feature is guide material. Defaults to true: a feature is a
+     * page of the user guide unless it says otherwise, so a feature nobody has
+     * written about is a gap `pikku scenario guide` reports rather than a page
+     * silently missing. Pure plumbing — a wire, a validation layer, a bearer
+     * auth handshake — sets it false and stops being a coverage problem.
+     */
+    document?: boolean;
     scenarios: readonly CoreFeatureScenario[];
     before?: CorePikkuFunctionHook;
     after?: CorePikkuFunctionHook;
@@ -22,6 +30,8 @@ export type FeatureMeta = {
     name: string;
     description?: string;
     tags: string[];
+    /** Present only when the feature opted out; absent means documented. */
+    document?: boolean;
     entries: FeatureMetaEntry[];
     unresolvedEntries: number;
     hasBefore: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.117",
+  "version": "0.12.118",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",