@pikku/core 0.12.115 → 0.12.118

package/CHANGELOG.md

@@ -1,3 +1,84 @@
+## 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
+
+- 8a0ecb7: `pikku scenario run <env> --run browser --strict` now refuses every route off the run surface, rather than only reporting one at the end. An action step that would fall back to its `default` binding throws `ScenarioNoSurfaceBinding` even when it declares `default`, and a `then` witnessed only server-side throws the new `ScenarioUnwitnessedAssertion`. Without `--strict` nothing changes: the fallback still runs and the unwitnessed assertion is still counted into the coverage line.
+
+  It exists because a run is becoming a source of documentation. A docs build runs the suite `--run browser --strict`, so a feature that cannot be driven end to end through the UI cannot produce a page — no flow where three steps are screenshots and the fourth quietly happened over RPC with nothing to show. The refusal names the step, the surface the run asked for and the surfaces that did bind it, which turns "what still has no browser binding" into a worklist the run prints rather than something to go looking for.
+
+  `--strict` on `--run default` is accepted and does nothing, since nothing on the default surface can fall back or be witnessed elsewhere. `PikkuScenarioService.setRunSurface` takes the flag as a second argument, and `isStrictSurface()` reads it back.
+
+## 0.12.116
+
+### Patch Changes
+
+- 87971bd: `browser.screenshot('the order, confirmed', { showcase: true })` marks one shot as fit to publish outside the run, and the artifact ledger carries the flag. A gallery, a docs page or a marketing card can then be built from the scenario run itself instead of a second browser pass configured somewhere else, and the author of the step — the only one who knows the page is at a moment worth showing a stranger — is who decides.
+
+  Each filed screenshot also carries an `id`: the same shot under one key across runs. `path` leads with the order the run happened in, so inserting a step ahead of a shot renumbers it and anything meant to outlive one run (a caption override, a diff against last week's build) loses track of it.
+
+  Two supporting fixes in `@pikku/playwright`: contexts open at a pinned `viewport` (1440x900, overridable per config or via `E2E_VIEWPORT_WIDTH`/`E2E_VIEWPORT_HEIGHT`) and screenshots are taken with animations disabled, so two runs of the same scenario photograph the same thing. `{ fullPage: true }` is available for shots of a whole scrollable page.
+
+- b312867: A project can now serve several MCP endpoints, one per connector.
+
+  Until now every MCP tool in a project was pooled onto a single `/mcp`, so a hub offering three connectors offered one endpoint listing all three connectors' tools at once. A client pointed at it saw tools it had no business calling, and the only way to give a connector an endpoint of its own was to give it a deployment of its own — three deploys, three bills, three service graphs.
+
+  `wireAddon` gains `mcpEndpoint`. `true` serves that instance's tools at `/mcp/<name>`; a string is the path, used as given. Leaving it unset keeps the tools on the shared endpoint, which is where they have always been, so nothing existing moves.
+
+  A surfaced instance now gets its own manifest (`.pikku/mcp/mcp.<name>.gen.json`, carrying the path it answers on), its own deploy unit (`mcp-<name>`, routed on that path), and its own MCP server — with its own tool list, so a client pointed at one endpoint never sees another's tools. The plumbing for the per-surface manifest and unit already existed in `deploy apply`; nothing had ever produced one.
+
+  `pikku dev` mounts every endpoint the generated tree describes, not just the default one. Without that a project that moved its tools onto their own endpoints would have served nothing locally at all — the default manifest it reads is empty precisely because they moved — and the only way to try a connector would have been to deploy it.
+
+  The node and bun transports take `mcpSurfaces` alongside `mcpJson` and mount each at its own path, longest path first. `/mcp` claims everything beneath `/mcp/`, so without that ordering the default endpoint answers `/mcp/weather` and the surface's tools are unreachable.
+
+  OAuth discovery is split between the endpoints rather than duplicated across them. RFC 9728 folds a resource's path into its well-known route, so each endpoint's own document is already distinct, but the path-less `/.well-known/oauth-protected-resource` predates that and describes whichever resource answers it. Only the default endpoint claims it — otherwise every unit registers the same route and the provider's router decides which resource a client is told about, and in dev a client probing it is described whichever surface sorted first.
+
+- 51bd35a: Document five public keys that carried no JSDoc: `wireChannel`'s `onDisconnect`,
+  `wireRemoteAddon`'s `serverUrl` and `tags`, and `CoreUserSession`'s `userId` and
+  `orgId`. A key printed as a name and a type is a shape; what a caller needs is
+  what to put in it, and only the JSDoc where the type is declared carries that
+  into the IDE, the console and the shipped surface doc at once.
+
 ## 0.12.115
 
 ### Patch Changes

package/dist/types/core.types.d.ts

@@ -81,7 +81,9 @@ export type CoreConfig<Config extends Record<string, unknown> = {}> = {
     postgres?: PostgresConfig;
 } & Config;
 export interface CoreUserSession {
+    /** Who the session belongs to, as your own system identifies them. Pikku only carries it. */
     userId?: string;
+    /** The tenant the session is acting inside, when the project has more than one. */
     orgId?: string;
     /** True when the session belongs to a synthetic scenario actor — lets audits/analytics address synthetic traffic */
     actor?: boolean;

package/dist/wirings/addon/wire-addon.d.ts

@@ -16,6 +16,18 @@ export type WireAddonConfig = {
      * and is typed against the addon's function names.
      */
     mcp?: boolean | string[];
+    /**
+     * Serves this addon's MCP tools on an endpoint of their own rather than
+     * folding them into the project's single `/mcp`. `true` mounts them at
+     * `/mcp/<name>`; a string is the path, used as given.
+     *
+     * This is what lets one project expose several connectors: each wired
+     * instance becomes its own MCP server, with its own tool list, so a client
+     * pointed at one never sees another's tools. Leaving it unset keeps the
+     * addon's tools on the shared endpoint, which is where they have always
+     * been.
+     */
+    mcpEndpoint?: boolean | string;
     /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
     /** Required of every function in the addon, on top of the function's own. */

package/dist/wirings/addon/wire-remote-addon.d.ts

@@ -12,11 +12,13 @@ export type WireRemoteAddonConfig = {
     name: string;
     /** Must be installed as a devDependency — `pikku verify` enforces this. */
     package: string;
+    /** Where the addon is deployed, e.g. `https://registry.example.com`. A function when it varies per environment. */
     serverUrl: string | ((services: CoreServices) => string | Promise<string>);
     /** Omit when the addon declares its remote surface public. */
     auth?: RemoteAddonAuth;
     /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
     remoteName?: (fn: string) => string;
+    /** Applied to every function the addon contributes, so tag middleware and permissions reach them. */
     tags?: string[];
 };
 /**

package/dist/wirings/channel/channel.types.d.ts

@@ -68,6 +68,7 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
         func?: ChannelConnect;
         middleware?: PikkuMiddleware[];
     };
+    /** Runs once after the socket closes, however it closed. Nothing it returns reaches the client. */
     onDisconnect?: ChannelDisconnect | {
         func?: ChannelDisconnect;
         middleware?: PikkuMiddleware[];

package/dist/wirings/mcp/mcp.types.d.ts

@@ -21,12 +21,24 @@ export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func' | 'mid
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
+    /**
+     * The MCP endpoint this belongs to, when the project serves more than one.
+     * Absent means the project's default endpoint. Codegen splits the metadata
+     * by this key, so each endpoint's manifest lists only its own.
+     */
+    surface?: string;
 }>;
 export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func' | 'middleware'> & {
     pikkuFuncId: string;
     inputSchema: string | null;
     outputSchema: string | null;
     middleware?: MiddlewareMetadata[];
+    /**
+     * The MCP endpoint this belongs to, when the project serves more than one.
+     * Absent means the project's default endpoint. Codegen splits the metadata
+     * by this key, so each endpoint's manifest lists only its own.
+     */
+    surface?: string;
 }>;
 export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
     pikkuFuncId: string;
@@ -38,6 +50,12 @@ export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func' | 'middlew
         required: boolean;
     }>;
     middleware?: MiddlewareMetadata[];
+    /**
+     * The MCP endpoint this belongs to, when the project serves more than one.
+     * Absent means the project's default endpoint. Codegen splits the metadata
+     * by this key, so each endpoint's manifest lists only its own.
+     */
+    surface?: string;
 }>;
 export type CoreMCPResource<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
     /** How the client addresses this resource. `{name}` marks a parameter, and every parameter must be a key of the function's input schema. */

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, 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 { 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, 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';
@@ -92,6 +93,9 @@ export declare class ScenarioActorRequired extends PikkuError {
  * coverage gap. (A `then` that ran somewhere, just not on the run surface, is
  * the coverage gap; it is reported rather than thrown. See
  * {@link ScenarioNoWitness} for one that ran nowhere.)
+ *
+ * A strict run also throws it for a step that *could* fall back, because there
+ * the fallback is the thing being refused.
  */
 export declare class ScenarioNoSurfaceBinding extends PikkuError {
     readonly stepFunc: string;
@@ -114,6 +118,22 @@ export declare class ScenarioNoWitness extends PikkuError {
     readonly runSurface: ScenarioSurface;
     constructor(stepFunc: string, declared: ScenarioSurface[], runSurface: ScenarioSurface);
 }
+/**
+ * An assertion ran, but not on the surface the run targets.
+ *
+ * The sibling of {@link ScenarioNoWitness}: that one checked nothing anywhere,
+ * this one checked the system of record while the prose claims the actor saw it
+ * on the page. Ordinary runs count it as a coverage gap; a strict run refuses
+ * it, because a flow that cannot be observed end to end on the run surface is
+ * not a flow that surface can be documented from.
+ */
+export declare class ScenarioUnwitnessedAssertion extends PikkuError {
+    readonly stepFunc: string;
+    readonly declared: ScenarioSurface[];
+    readonly runSurface: ScenarioSurface;
+    readonly witnessedOn: ScenarioSurface[];
+    constructor(stepFunc: string, declared: ScenarioSurface[], runSurface: ScenarioSurface, witnessedOn: ScenarioSurface[]);
+}
 /**
  * The scenario capability, layered onto a workflow service rather than being
  * one.
@@ -142,16 +162,25 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     private readonly engine;
     private runActors;
     private runContexts;
+    private runVideoOffsets;
     private scenarioBrowserProvider?;
     private scenarioEnvironment?;
     private runSurface;
+    private strictSurface;
     constructor(engine: WorkflowRunEngine);
     /**
      * The surface every actor drives the system through for this run, set once by
      * the runner from `--run`. `default` is the server-side path — the fast suite.
+     *
+     * `strict` removes both routes off that surface: an action may not fall back
+     * to its `default` binding, and a `then` may not be witnessed anywhere else.
+     * It is what lets a run stand as evidence of the whole flow on one surface,
+     * which is what generating documentation from a run requires. On a `default`
+     * run it changes nothing, because nothing there can fall back.
      */
-    setRunSurface(surface: ScenarioSurface): void;
+    setRunSurface(surface: ScenarioSurface, strict?: boolean): void;
     getRunSurface(): ScenarioSurface;
+    isStrictSurface(): boolean;
     /**
      * Registered by `@pikku/playwright` (or any other driver) before a scenario
      * runs. Absent means browser steps cannot run, which the CLI checks up front
@@ -166,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

@@ -132,14 +132,21 @@ addError(ScenarioActorRequired, {
  * coverage gap. (A `then` that ran somewhere, just not on the run surface, is
  * the coverage gap; it is reported rather than thrown. See
  * {@link ScenarioNoWitness} for one that ran nowhere.)
+ *
+ * A strict run also throws it for a step that *could* fall back, because there
+ * the fallback is the thing being refused.
  */
 export class ScenarioNoSurfaceBinding extends PikkuError {
     stepFunc;
     declared;
     runSurface;
     constructor(stepFunc, declared, runSurface) {
-        super(`[scenario] step '${stepFunc}' declares no binding for '${runSurface}' and no 'default' to fall back to ` +
-            `(declares: ${declared.join(', ') || 'nothing'}).`);
+        const declares = `(declares: ${declared.join(', ') || 'nothing'})`;
+        super(declared.includes('default')
+            ? `[scenario] step '${stepFunc}' has no binding for '${runSurface}' and a strict run will not let it ` +
+                `fall back to 'default' ${declares}. Add a '${runSurface}' binding, or drop --strict.`
+            : `[scenario] step '${stepFunc}' declares no binding for '${runSurface}' and no 'default' to fall back to ` +
+                `${declares}.`);
         this.stepFunc = stepFunc;
         this.declared = declared;
         this.runSurface = runSurface;
@@ -175,6 +182,34 @@ addError(ScenarioNoWitness, {
     status: 500,
     message: 'Assertion has no witness for this surface.',
 });
+/**
+ * An assertion ran, but not on the surface the run targets.
+ *
+ * The sibling of {@link ScenarioNoWitness}: that one checked nothing anywhere,
+ * this one checked the system of record while the prose claims the actor saw it
+ * on the page. Ordinary runs count it as a coverage gap; a strict run refuses
+ * it, because a flow that cannot be observed end to end on the run surface is
+ * not a flow that surface can be documented from.
+ */
+export class ScenarioUnwitnessedAssertion extends PikkuError {
+    stepFunc;
+    declared;
+    runSurface;
+    witnessedOn;
+    constructor(stepFunc, declared, runSurface, witnessedOn) {
+        super(`[scenario] assertion '${stepFunc}' was checked on ${witnessedOn.join(', ')}, not on '${runSurface}'. ` +
+            `It held there — but nothing looked at '${runSurface}', which is what the step's prose claims the actor saw. ` +
+            `Add a '${runSurface}' witness (declares: ${declared.join(', ') || 'nothing'}), or drop --strict.`);
+        this.stepFunc = stepFunc;
+        this.declared = declared;
+        this.runSurface = runSurface;
+        this.witnessedOn = witnessedOn;
+    }
+}
+addError(ScenarioUnwitnessedAssertion, {
+    status: 500,
+    message: 'Assertion was checked, but not on the run surface.',
+});
 /**
  * The scenario capability, layered onto a workflow service rather than being
  * one.
@@ -208,22 +243,37 @@ 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';
+    strictSurface = false;
     constructor(engine) {
         this.engine = engine;
     }
     /**
      * The surface every actor drives the system through for this run, set once by
      * the runner from `--run`. `default` is the server-side path — the fast suite.
+     *
+     * `strict` removes both routes off that surface: an action may not fall back
+     * to its `default` binding, and a `then` may not be witnessed anywhere else.
+     * It is what lets a run stand as evidence of the whole flow on one surface,
+     * which is what generating documentation from a run requires. On a `default`
+     * run it changes nothing, because nothing there can fall back.
      */
-    setRunSurface(surface) {
+    setRunSurface(surface, strict = false) {
         this.runSurface = surface;
+        this.strictSurface = strict;
     }
     getRunSurface() {
         return this.runSurface;
     }
+    isStrictSurface() {
+        return this.strictSurface;
+    }
     /**
      * Registered by `@pikku/playwright` (or any other driver) before a scenario
      * runs. Absent means browser steps cannot run, which the CLI checks up front
@@ -246,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'
@@ -595,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(),
@@ -605,7 +692,8 @@ export class PikkuScenarioService {
                 });
             };
             if (resolution.kind === 'action') {
-                if (resolution.fellBack && !declared.includes('default')) {
+                if (resolution.fellBack &&
+                    (this.strictSurface || !declared.includes('default'))) {
                     throw new ScenarioNoSurfaceBinding(resolvedStepFunc, declared, this.runSurface);
                 }
                 return await runOnSurface(resolution.surface);
@@ -613,6 +701,9 @@ export class PikkuScenarioService {
             if (resolution.surfaces.length === 0) {
                 throw new ScenarioNoWitness(resolvedStepFunc, declared, this.runSurface);
             }
+            if (this.strictSurface && resolution.unwitnessed) {
+                throw new ScenarioUnwitnessedAssertion(resolvedStepFunc, declared, this.runSurface, resolution.surfaces);
+            }
             // A `then` runs every witness it has and they must agree. The surface
             // witness runs first so that when the page is the thing that is wrong,
             // it is the failure that surfaces.

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

@@ -31,6 +31,30 @@ export interface ScenarioArtifact {
     actor?: string;
     /** The caption the scenario author took a screenshot under. */
     name?: string;
+    /**
+     * The same shot across runs, under one key. `path` carries the order the run
+     * happened in, so it moves whenever a step is inserted before it — nothing
+     * that outlives a run (a caption override, a diff against last week) can key
+     * off it.
+     */
+    id?: string;
+    /** 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 {
@@ -45,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 {
@@ -67,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[];
@@ -94,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.
  *
@@ -107,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

@@ -166,11 +166,22 @@ export interface TestIdSelector {
  * interface via `declare module`, so `wire.browser.page` is a fully typed
  * Playwright `Page` in a project that installs it.
  */
+/** How one deliberate screenshot is taken, and what it is for. */
+export interface ScenarioScreenshotOptions {
+    /**
+     * Publish this one outside the run — a marketing card, a docs page, a
+     * gallery. Declared at the call site because only the author of the step
+     * knows the page is at a moment worth showing a stranger.
+     */
+    showcase?: boolean;
+    /** Photograph the whole scrollable page rather than the viewport. */
+    fullPage?: boolean;
+}
 export interface PikkuBrowserWire {
     /** The actor whose browser context this is */
     readonly actor: string;
     goto(url: string): Promise<void>;
-    screenshot(name?: string): Promise<Uint8Array>;
+    screenshot(name?: string, options?: ScenarioScreenshotOptions): Promise<Uint8Array>;
 }
 /**
  * What one actor's window looked like at the moment a scenario failed.
@@ -224,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

@@ -1,6 +1,6 @@
 import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
 export type { ScenarioStepInvocation, ScenarioStepMeta, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
-export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
+export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, PikkuBrowserWire, ScenarioScreenshotOptions, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
 export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
     scenario: CorePikkuFunctionConfig<any, any, any>;
     data: unknown;
@@ -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.115",
+  "version": "0.12.118",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/src/public-surface.json

@@ -82,6 +82,7 @@
     "ScenarioHookError",
     "ScenarioNoSurfaceBinding",
     "ScenarioNoWitness",
+    "ScenarioUnwitnessedAssertion",
     "ScenarioWitnessDisagreement",
     "addFeature",
     "composeStepProse",