@pikku/core 0.12.69 → 0.12.71

package/dist/wirings/workflow/scenario-cookie-jar.d.ts

@@ -0,0 +1,29 @@
+/** A session held the way a browser holds one, for code driving a real target. */
+export interface ScenarioCookieJar {
+    /** `fetch`, but it sends what the target has set and keeps what it sets. */
+    fetch: typeof fetch;
+    /** Forgets the session — what an actor does before signing in again. */
+    clear(): void;
+    /**
+     * Whether the target has set anything yet. This is a fact about the jar, not
+     * about the session: a target that sets a CSRF or locale cookie before anyone
+     * signs in fills the jar without establishing one. Whoever needs to know
+     * whether a sign-in happened has to track the sign-in.
+     */
+    readonly empty: boolean;
+}
+/**
+ * A `fetch` that remembers cookies.
+ *
+ * A browser persists the session cookie on its own; anything driving a target
+ * from this process has to. Every response is read, not just the sign-in, so a
+ * cookie the target rotates mid-session is followed rather than dropped.
+ *
+ * The jar is a closure local, so two jars never share a session — which is what
+ * lets one scenario sign in as several people without one of them inheriting
+ * the other's session.
+ *
+ * It also stamps `Origin`, because Better Auth rejects a state-changing POST
+ * whose Origin does not match its baseURL.
+ */
+export declare const createCookieJar: (apiUrl: string) => ScenarioCookieJar;

package/dist/wirings/workflow/scenario-cookie-jar.js

@@ -0,0 +1,51 @@
+/**
+ * A `fetch` that remembers cookies.
+ *
+ * A browser persists the session cookie on its own; anything driving a target
+ * from this process has to. Every response is read, not just the sign-in, so a
+ * cookie the target rotates mid-session is followed rather than dropped.
+ *
+ * The jar is a closure local, so two jars never share a session — which is what
+ * lets one scenario sign in as several people without one of them inheriting
+ * the other's session.
+ *
+ * It also stamps `Origin`, because Better Auth rejects a state-changing POST
+ * whose Origin does not match its baseURL.
+ */
+export const createCookieJar = (apiUrl) => {
+    const jar = new Map();
+    const origin = new URL(apiUrl).origin;
+    return {
+        fetch: async (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set('origin', origin);
+            const held = [...jar].map(([name, value]) => `${name}=${value}`);
+            const caller = headers.get('cookie');
+            if (held.length > 0 || caller) {
+                headers.set('cookie', [caller, ...held].filter(Boolean).join('; '));
+            }
+            const response = await fetch(input, { ...init, headers });
+            for (const raw of response.headers.getSetCookie()) {
+                const [pair] = raw.split(';');
+                const separator = pair.indexOf('=');
+                if (separator > 0) {
+                    const name = pair.slice(0, separator);
+                    const value = pair.slice(separator + 1);
+                    // An empty value is how a target deletes a cookie — drop the name
+                    // rather than holding a cookie whose value says it is gone.
+                    if (value) {
+                        jar.set(name, value);
+                    }
+                    else {
+                        jar.delete(name);
+                    }
+                }
+            }
+            return response;
+        },
+        clear: () => jar.clear(),
+        get empty() {
+            return jar.size === 0;
+        },
+    };
+};

package/dist/wirings/workflow/scenario-poll.d.ts

@@ -0,0 +1,20 @@
+/** How long to keep trying, and how long to wait between tries. */
+export interface PollOptions {
+    /** Total time to keep attempting before giving up. Default 15s. */
+    timeoutMs?: number;
+    /** Gap between attempts. Default 250ms. */
+    intervalMs?: number;
+}
+/**
+ * Attempt something until it answers, or the deadline passes.
+ *
+ * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
+ * answers, because a probe asking whether something happened reports `false`
+ * when it did not. Answering `undefined` at the deadline rather than throwing
+ * leaves the error to the caller, who is the only one who knows what was being
+ * waited for.
+ *
+ * A step that polls its target — a delivery reaching a terminal status, a run
+ * finishing — reaches for this rather than writing the deadline loop again.
+ */
+export declare const pollUntil: <T>(attempt: () => Promise<T | undefined> | T | undefined, { timeoutMs, intervalMs }?: PollOptions) => Promise<T | undefined>;

package/dist/wirings/workflow/scenario-poll.js

@@ -0,0 +1,25 @@
+/**
+ * Attempt something until it answers, or the deadline passes.
+ *
+ * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
+ * answers, because a probe asking whether something happened reports `false`
+ * when it did not. Answering `undefined` at the deadline rather than throwing
+ * leaves the error to the caller, who is the only one who knows what was being
+ * waited for.
+ *
+ * A step that polls its target — a delivery reaching a terminal status, a run
+ * finishing — reaches for this rather than writing the deadline loop again.
+ */
+export const pollUntil = async (attempt, { timeoutMs = 15_000, intervalMs = 250 } = {}) => {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const answer = await attempt();
+        if (answer !== undefined) {
+            return answer;
+        }
+        if (Date.now() >= deadline) {
+            return undefined;
+        }
+        await new Promise((done) => setTimeout(done, intervalMs));
+    }
+};

package/dist/wirings/workflow/scenario-prose.d.ts

@@ -0,0 +1,38 @@
+import type { ScenarioStepPhase } from './scenario-step.types.js';
+/**
+ * Renders the English sentence a reporter shows for a scenario step.
+ *
+ * This is the inversion of cucumber: rather than parsing English into a call,
+ * we render English out of a typed call, so the readable report survives
+ * without a regex registry paying for it.
+ *
+ * Lives in core so the CLI reporter and the console render identically.
+ */
+/**
+ * Fill a step's `template` from the input that step was actually called with,
+ * so the reported sentence names the values under test — "sees @pikku/addon-todos"
+ * rather than "sees an addon in the gallery" repeated three times.
+ *
+ * A placeholder with no recorded value renders as nothing and the surrounding
+ * whitespace collapses, so an optional input that was omitted reads as a shorter
+ * sentence rather than a literal `{state}` leaking into the report.
+ */
+export declare const renderStepTemplate: (template: string, input: unknown) => string;
+export declare const composeStepProse: ({ phase, description, template, input, actor, keywordWidth, }: {
+    phase: ScenarioStepPhase;
+    description: string;
+    /**
+     * The prose this step renders, with `{placeholders}` filled from `input`.
+     * Unlike `description`, which documents what the step does, this is what a
+     * reader of the report sees. Falls back to `description` when absent.
+     */
+    template?: string;
+    /** The input this step was called with, as recorded on the run. */
+    input?: unknown;
+    actor?: string;
+    /**
+     * Pad the keyword to this width so a ladder of steps lines its sentences up
+     * under each other. Omit for inline prose.
+     */
+    keywordWidth?: number;
+}) => string;

package/dist/wirings/workflow/scenario-prose.js

@@ -0,0 +1,45 @@
+/**
+ * Renders the English sentence a reporter shows for a scenario step.
+ *
+ * This is the inversion of cucumber: rather than parsing English into a call,
+ * we render English out of a typed call, so the readable report survives
+ * without a regex registry paying for it.
+ *
+ * Lives in core so the CLI reporter and the console render identically.
+ */
+/**
+ * Fill a step's `template` from the input that step was actually called with,
+ * so the reported sentence names the values under test — "sees @pikku/addon-todos"
+ * rather than "sees an addon in the gallery" repeated three times.
+ *
+ * A placeholder with no recorded value renders as nothing and the surrounding
+ * whitespace collapses, so an optional input that was omitted reads as a shorter
+ * sentence rather than a literal `{state}` leaking into the report.
+ */
+export const renderStepTemplate = (template, input) => {
+    const values = input && typeof input === 'object' ? input : {};
+    return template
+        .replace(/\{(\w+)\}/g, (_match, key) => formatValue(values[key]))
+        .replace(/\s+/g, ' ')
+        .trim();
+};
+const formatValue = (value) => {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+};
+export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
+    const keyword = phase === 'step' ? '' : capitalise(phase);
+    const subject = actor ? `the ${actor}` : '';
+    const rendered = template ? renderStepTemplate(template, input) : description;
+    const sentence = [subject, rendered].filter(Boolean).join(' ');
+    if (keywordWidth === undefined) {
+        return [keyword, sentence].filter(Boolean).join(' ');
+    }
+    return `${keyword.padEnd(keywordWidth)} ${sentence}`;
+};
+const capitalise = (value) => value.charAt(0).toUpperCase() + value.slice(1);

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

@@ -0,0 +1,16 @@
+import type { PikkuScenarioStepWire, ScenarioEnvironment } from './scenario-step.types.js';
+/**
+ * The actor this step was called with, or a loud error naming the step.
+ *
+ * A step that talks to the target app needs an identity, but `actor` is
+ * optional on the wire because a pure assertion step needs none. This is the
+ * one place that narrowing happens, so every step file stops writing its own
+ * `actorOf(...)` guard.
+ */
+export declare const requireActor: <TActor>(scenarioStep: PikkuScenarioStepWire<TActor> | undefined) => TActor;
+/**
+ * The environment this run targets, or a loud error naming the step. A run
+ * started outside `pikku scenario run` only carries one when the server has
+ * `API_URL` configured.
+ */
+export declare const requireScenarioEnv: (scenarioStep: PikkuScenarioStepWire<unknown> | undefined) => ScenarioEnvironment;

package/dist/wirings/workflow/scenario-step-guards.js

@@ -0,0 +1,29 @@
+/**
+ * The actor this step was called with, or a loud error naming the step.
+ *
+ * A step that talks to the target app needs an identity, but `actor` is
+ * optional on the wire because a pure assertion step needs none. This is the
+ * one place that narrowing happens, so every step file stops writing its own
+ * `actorOf(...)` guard.
+ */
+export const requireActor = (scenarioStep) => {
+    const actor = scenarioStep?.actor;
+    if (!actor) {
+        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' was called without an actor. ` +
+            `Pass { actor: actors.<name> } so it runs as that persona.`);
+    }
+    return actor;
+};
+/**
+ * The environment this run targets, or a loud error naming the step. A run
+ * started outside `pikku scenario run` only carries one when the server has
+ * `API_URL` configured.
+ */
+export const requireScenarioEnv = (scenarioStep) => {
+    const env = scenarioStep?.env;
+    if (!env) {
+        throw new Error(`[scenario] step '${scenarioStep?.name ?? 'unknown'}' needs the target environment, but this run carries none. ` +
+            `Run it through 'pikku scenario run <environment>' with scenarios.environments.<environment> declared in pikku.config.json.`);
+    }
+    return env;
+};

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

@@ -0,0 +1,148 @@
+import type { ScenarioActor } from '../../services/scenario-actors-service.js';
+/**
+ * Scenario steps: named, typed units of scenario behaviour.
+ *
+ * A step's body is an ordinary pikku function, so it may drive a browser, call
+ * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
+ * `step` — they only change the prose the reporter renders.
+ */
+/**
+ * Which Gherkin-style keyword the reporter prefixes this step with. `step`
+ * renders no prefix at all.
+ */
+export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then';
+/**
+ * Options accepted by `scenario.step/given/when/then`.
+ *
+ * Note the retry default differs from an ordinary workflow step: retrying a
+ * failed assertion is the wrong behaviour for a test primitive, so steps
+ * default to no retries.
+ */
+export interface ScenarioStepOptions {
+    /** The actor this step runs as. Required for steps declaring `browser: true`. */
+    actor?: unknown;
+    /** Overrides the step's own `description` for this call site only. */
+    description?: string;
+    /** Defaults to 0 for steps — a failed assertion must not be retried. */
+    retries?: number;
+    retryDelay?: number | string;
+}
+/**
+ * The environment a scenario run targets, as declared in pikku.config.json
+ * under `scenarios.environments`.
+ */
+export interface ScenarioEnvironment {
+    /** Base API URL of the target app, INCLUDING the HTTP prefix. */
+    apiUrl: string;
+    /** Base URL of the app's UI, for environments with browser steps. */
+    appUrl?: string;
+}
+/**
+ * The `scenarioStep` wire, present on every scenario step invocation.
+ *
+ * `TActor` is the project's own actor type, so a step reaches only the RPCs its
+ * actors can actually call. It defaults to the open `ScenarioActor` for a
+ * project that declares no registry.
+ */
+export interface PikkuScenarioStepWire<TActor = ScenarioActor> {
+    /** Registered step name (also its pikkuFuncId) */
+    name: string;
+    /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
+    stepName: string;
+    runId: string;
+    phase: ScenarioStepPhase;
+    /**
+     * The actor this step runs as, when one was given. Call RPCs through it
+     * (`actor.invoke(...)`) so they run against the target environment as that
+     * persona.
+     */
+    actor?: TActor;
+    /**
+     * The environment this run targets. A step runs in the CLI process, where
+     * there is no `variables` service — this is how a raw-HTTP step learns the
+     * target's URL without reaching for `process.env`.
+     */
+    env?: ScenarioEnvironment;
+}
+/**
+ * How a browser step names an element.
+ *
+ * A `data-testid` on its own is rarely enough to name exactly one: `where`
+ * matches the element's own data attributes (so a step asserts a status
+ * without reading translated copy back to the app), `prefix` matches a family
+ * of ids, `containing` picks the match holding a piece of text, and `within`
+ * scopes the lookup to one row or section.
+ *
+ * Declared here so a step's input type is structural; the driver
+ * (`@pikku/playwright`) is what resolves it against a real page.
+ */
+export interface TestIdSelector {
+    testId: string;
+    /** Match every test id beginning with `testId`, e.g. every `flow-card-*`. */
+    prefix?: boolean;
+    /** Data attributes the element must also carry, e.g. `{ 'data-open': 'true' }`. */
+    where?: Record<string, string>;
+    /** Narrow to the one match holding this text. */
+    containing?: string;
+    /** Scope the lookup to one enclosing element, e.g. the row for one user. */
+    within?: TestIdSelector;
+}
+/**
+ * Structural browser handle, present only when the runner provisioned a
+ * browser for this step (`browser: true` on the step config).
+ *
+ * `@pikku/core` deliberately never imports playwright — it must stay
+ * dependency-free for edge runtimes. `@pikku/playwright` augments this
+ * interface via `declare module`, so `wire.browser.page` is a fully typed
+ * Playwright `Page` in a project that installs it.
+ */
+export interface PikkuBrowserWire {
+    /** The actor whose browser context this is */
+    readonly actor: string;
+    goto(url: string): Promise<void>;
+    screenshot(name?: string): Promise<Uint8Array>;
+}
+/**
+ * What one actor's window looked like at the moment a scenario failed.
+ *
+ * A browser step fails with a selector timeout that says nothing about *why*
+ * the page never rendered. The answer is almost always in the page's own
+ * errors, which the driver has been collecting all along.
+ */
+export interface ScenarioBrowserFailure {
+    /** The actor whose window this is. */
+    actor: string;
+    /** Where the window was pointed, when the driver can still report it. */
+    url?: string;
+    /** Path the screenshot was written to; absent when none could be taken. */
+    screenshot?: string;
+    consoleErrors: string[];
+    pageErrors: string[];
+    failedRequests: string[];
+    apiErrors: string[];
+}
+/**
+ * Supplied by `@pikku/playwright` (or any other driver) and consumed by the
+ * scenario runner. Declared here so the CLI depends only on core.
+ *
+ * `reset` and `captureFailure` are optional so a driver written against an
+ * earlier version keeps compiling; the runner treats a driver without them as
+ * one that simply offers no isolation and no diagnostics.
+ */
+export interface ScenarioBrowserProvider {
+    /** Resolve — creating on first use — the browser session for an actor. */
+    sessionFor(actorName: string): Promise<PikkuBrowserWire>;
+    /**
+     * Discard every actor's per-scenario state — cookies, storage, open pages —
+     * while keeping the browser itself. Called between scenarios, so one
+     * scenario cannot leave the next signed in as somebody else.
+     */
+    reset?(): Promise<void>;
+    /**
+     * Snapshot every open window for a failed scenario. `label` identifies the
+     * scenario in artifact filenames. Never throws: a failure to capture must
+     * not replace the failure being captured.
+     */
+    captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>;
+    close(): Promise<void>;
+}

package/dist/wirings/workflow/scenario-step.types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,8 +1,9 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
-import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
+import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
+export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
+export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, PikkuBrowserWire, ScenarioBrowserProvider, } from './scenario-step.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;
@@ -181,11 +182,6 @@ export interface WorkflowRunService {
         graph: any;
         source: string;
     } | null>;
-    getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
     deleteRun(id: string): Promise<boolean>;
 }
 /**
@@ -235,6 +231,77 @@ export type CoreWorkflow<PikkuFunctionConfig extends CorePikkuFunctionConfig<any
     /** Tags for organization and filtering */
     tags?: string[];
 };
+/**
+ * A scenario as a feature references it: either the scenario itself, or the
+ * scenario paired with the input to run it with. The paired form is gherkin's
+ * `Examples:` — the same scenario run once per row, written as an ordinary
+ * loop rather than a table.
+ */
+export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
+    scenario: CorePikkuFunctionConfig<any, any, any>;
+    data: unknown;
+};
+/**
+ * A feature: an ordered group of scenarios, mirroring gherkin's Feature ↔
+ * Scenario structure. Scenarios are referenced by imported identifier, so a
+ * renamed or deleted scenario is a compile error rather than a silent skip.
+ *
+ * Hooks run **once around the whole group** (`before → a → b → c → after`),
+ * not per scenario — per-scenario setup is the scenario's own `before`. That
+ * is the one thing a feature deliberately cannot express: gherkin's
+ * `Background:` runs per scenario.
+ */
+export type CoreFeature = {
+    /** Human-readable name. The export identifier is the id. */
+    name: string;
+    description?: string;
+    tags?: string[];
+    /** Readonly because `pikkuFeature`'s `const` generic infers a readonly tuple. */
+    scenarios: readonly CoreFeatureScenario[];
+    before?: CorePikkuFunctionHook;
+    after?: CorePikkuFunctionHook;
+};
+/** One entry of a feature's scenario list, as extracted from the source. */
+export type FeatureMetaEntry = {
+    /** The scenario's declared export name — its key in `WorkflowsMeta`. */
+    scenario: string;
+    /** The input this entry runs the scenario with — gherkin's `Examples:`. */
+    data?: unknown;
+};
+/**
+ * A feature as the console reads it: the document structure around a group of
+ * scenarios. Generated to `scenarios/features.gen.json` and read off disk, so
+ * nothing app-facing has to import the scenario bootstrap to describe one.
+ */
+export type FeatureMeta = {
+    /** The export identifier. */
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    /** In declared order — a feature's reading order is its declaration order. */
+    entries: FeatureMetaEntry[];
+    /**
+     * Entries that could not be read statically (a spread, a `.map()`). Their
+     * membership is only known once the scenario bootstrap has been evaluated,
+     * so a non-zero count means this listing is partial.
+     */
+    unresolvedEntries: number;
+    /** Hooks are runtime-only; only their presence is knowable from meta. */
+    hasBefore: boolean;
+    hasAfter: boolean;
+};
+export type FeaturesMeta = Record<string, FeatureMeta>;
+/** One planned scenario run, resolved from a feature's scenario list. */
+export type FeaturePlanEntry = {
+    featureId: string;
+    featureName: string;
+    scenarioName: string;
+    /** The input this entry runs the scenario with, if the feature supplied one. */
+    data?: unknown;
+    /** The scenario's own tags unioned with the containing feature's. */
+    tags: string[];
+};
 /**
  * Workflow client interface
  */
@@ -274,6 +341,13 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     expose?: boolean;
     /** True for pikkuScenario workflows (complex + actor steps). */
     scenario?: boolean;
+    /**
+     * Why a scenario is held out of a default run. Stating the reason in code
+     * keeps the quarantine next to the scenario it applies to, rather than in
+     * a CI invocation nobody reads. Naming the scenario with `--flows` runs it
+     * regardless.
+     */
+    skip?: string;
     /** Actor names a scenario declares (personas it runs steps as). */
     actors?: string[];
 }>;
@@ -288,7 +362,7 @@ export interface WorkflowRuntimeMeta {
     /** Pikku function name (for execution) */
     pikkuFuncId: string;
     /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph', 'scenario' (complex + actor steps) */
-    source: 'dsl' | 'complex' | 'graph' | 'dynamic-workflow' | 'scenario';
+    source: 'dsl' | 'complex' | 'graph' | 'scenario';
     /** Optional description */
     description?: string;
     /** Tags for organization */

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.69",
+  "version": "0.12.71",
+  "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -22,6 +23,7 @@
     "./function": "./dist/function/index.js",
     "./channel": "./dist/wirings/channel/index.js",
     "./workflow": "./dist/wirings/workflow/index.js",
+    "./scenario": "./dist/wirings/workflow/pikku-scenario-service.js",
     "./workflow/timeline": "./dist/wirings/workflow/run-timeline.js",
     "./workflow/types": "./dist/wirings/workflow/workflow.types.js",
     "./actor-flow": "./dist/wirings/actor-flow/index.js",

package/src/function/functions.types.ts

@@ -248,6 +248,17 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
   | Record<string, PikkuPermission | PikkuPermission[]>
   | undefined
 
+/**
+ * A lifecycle hook: the same call signature as the function it hangs off, but
+ * its return value is discarded. A hook is setup/teardown, not a step — it has
+ * no id, no meta and no schema, so it is never recorded and never replayed.
+ */
+export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (
+  services: Services,
+  data: Data,
+  wire: Wire
+) => Promise<void> | void
+
 export type CorePikkuFunctionConfig<
   PikkuFunction extends
     | CorePikkuFunction<any, any, any, any, any>
@@ -282,6 +293,8 @@ export type CorePikkuFunctionConfig<
   workflowRetries?: number
   /** Timeout for this function when used as a workflow step (e.g. '30s', '5m'). */
   workflowTimeout?: string
+  /** Scenario steps only: this step drives a browser, so the runner must provision one before calling it. */
+  browser?: boolean
   audit?:
     | boolean
     | {
@@ -289,6 +302,25 @@ export type CorePikkuFunctionConfig<
       }
   approvalDescription?: any
   func: PikkuFunction
+  /**
+   * Scenarios only: runs before the scenario body, with the scenario's own
+   * signature. Throwing skips the body and fails the run, but `after` still
+   * runs.
+   */
+  before?: CorePikkuFunctionHook
+  /**
+   * Scenarios only: always runs after the scenario body, in a `finally`.
+   * Throwing fails a run that would otherwise have passed; on an
+   * already-failed run it attaches as the `cause` and never replaces the
+   * original error.
+   */
+  after?: CorePikkuFunctionHook
+  /**
+   * Scenarios only: why this scenario is held out of a default run. It is
+   * reported as skipped rather than quietly omitted, and naming it directly
+   * with `--flows` runs it anyway.
+   */
+  skip?: string
   auth?: boolean
   /**
    * Scopes the session must hold to run this function. All of them are

package/src/index.ts

@@ -55,6 +55,7 @@ export type {
   CorePikkuAuthConfig,
   CorePikkuFunction,
   CorePikkuFunctionConfig,
+  CorePikkuFunctionHook,
   CorePikkuPermission,
   CorePikkuPermissionConfig,
   CorePikkuPermissionFactory,

package/src/internal.ts

@@ -1,4 +1,8 @@
-export { pikkuState, resetPikkuState } from './pikku-state.js'
+export {
+  pikkuState,
+  resetPikkuState,
+  getAllPackageStates,
+} from './pikku-state.js'
 export { httpRouter } from './wirings/http/routers/http-router.js'
 export type {
   CreateSingletonServices,

package/src/pikku-state.ts

@@ -104,6 +104,7 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   },
   workflows: {
     registrations: new Map(),
+    features: new Map(),
     meta: {},
   },
   trigger: {