@ripplo/testing 0.3.9 → 0.4.0

package/dist/actions.d.ts

@@ -191,6 +191,11 @@ interface HandleDialogOptions {
     readonly promptText: string | undefined;
     readonly uiOnly?: boolean;
 }
+/**
+ * Respond to a native browser dialog (`alert`, `confirm`, `prompt`). Set
+ * `uiOnly: true` only when the dialog has no backend side effect — if it
+ * triggers a mutation, wire an observer and keep `uiOnly` off.
+ */
 declare function handleDialog({ action, promptText, uiOnly }: HandleDialogOptions): UnlabeledStep<{
     action: "accept" | "dismiss";
     promptText: string | undefined;
@@ -202,6 +207,12 @@ interface ClipboardOptions {
     readonly target: Variable<string> | undefined;
     readonly value: StringOrVariable | undefined;
 }
+/**
+ * Read from or write to the browser clipboard. Use when a flow depends on
+ * copy/paste (share links, invite tokens) — pair `write` to seed the
+ * clipboard before a paste action, or `read` into a `variable()` to assert
+ * what the app copied.
+ */
 declare function clipboard({ action, target, value }: ClipboardOptions): UnlabeledStep<{
     action: "read" | "write";
     type: "clipboard";
@@ -212,6 +223,10 @@ interface SetPermissionOptions {
     readonly permission: string;
     readonly state: "granted" | "prompt";
 }
+/**
+ * Pre-answer a browser permission prompt (geolocation, camera, notifications,
+ * clipboard-read, etc.) so the test doesn't stall on the native dialog.
+ */
 declare function setPermission({ permission, state }: SetPermissionOptions): UnlabeledStep<{
     permission: string;
     state: "granted" | "prompt";
@@ -221,6 +236,11 @@ interface SetViewportOptions {
     readonly height: number;
     readonly width: number;
 }
+/**
+ * Resize the browser viewport mid-test. Use to cover responsive breakpoints
+ * (mobile nav, collapsed sidebars) within the same flow rather than
+ * duplicating the test per size.
+ */
 declare function setViewport({ height, width }: SetViewportOptions): UnlabeledStep<{
     height: number;
     type: "setViewport";

package/dist/assert.d.ts

@@ -1,8 +1,7 @@
-import { O as ObserverHandle, a as ObserverInput, b as ObserverBudgetTier } from './types-Do4o4Y_c.js';
+import { O as ObserverHandle, a as ObserverInput, b as ObserverBudgetTier } from './types-B7YljrTz.js';
 import { Variable, StaticStringRef, VariableRef } from './control.js';
 import { U as UnlabeledStep } from './step-De52hTLd.js';
 import { CheckLocator, AnyLocator } from './locators.js';
-import 'zod';
 import '@ripplo/spec';
 
 type StringOrVariable = string | Variable<string>;
@@ -67,6 +66,12 @@ declare const assert: {
         operator: "equals";
         type: "assertAttribute";
     }>;
+    /**
+     * Verify a backend side effect by polling an observer. The server-side
+     * observer impl returns `ctx.retry(reason)` for transient states (keep
+     * polling) and `ctx.fail(reason)` only for invariant violations (stop
+     * early). The observer's `.budget()` governs poll interval and timeout.
+     */
     backend<THandle extends ObserverHandle>(observer: THandle, params: ObserverInput<THandle> & Record<string, string>): UnlabeledStep<{
         budget: ObserverBudgetTier;
         observer: string;

package/dist/assert.js

@@ -1,7 +1,7 @@
 import {
   readObserverBudget,
   readObserverName
-} from "./chunk-D7DRM7AG.js";
+} from "./chunk-SBZJDJP4.js";
 import {
   toSpecLocator,
   toStringValueRef
@@ -37,6 +37,13 @@ var assert = {
       type: "assertAttribute"
     });
   },
+  // eslint-disable-next-line no-comments/disallowComments
+  /**
+   * Verify a backend side effect by polling an observer. The server-side
+   * observer impl returns `ctx.retry(reason)` for transient states (keep
+   * polling) and `ctx.fail(reason)` only for invariant violations (stop
+   * early). The observer's `.budget()` governs poll interval and timeout.
+   */
   backend(observer, params) {
     return createStep({
       budget: readObserverBudget(observer),

package/dist/{builder-CNJmzJVe.d.ts → builder-0oT23S0W.d.ts}

@@ -1,4 +1,4 @@
-import { O as ObserverHandle, P as Precondition, l as PreconditionData, j as TestDefinition, e as DslConfig, g as ObserverDefinition, k as PreconditionDefinition, U as UnimplementedItems, f as ObserverContext, h as ObserverOutcome, S as SetupContext, m as TestValue, T as TeardownContext, n as UserDslConfig } from './types-Do4o4Y_c.js';
+import { O as ObserverHandle, P as Precondition, k as PreconditionData, i as TestDefinition, f as ObserverDefinition, j as PreconditionDefinition, U as UnimplementedItems, e as ObserverContext, g as ObserverOutcome, S as SetupContext, l as TestValue, T as TeardownContext } from './types-B7YljrTz.js';
 import { ObserverBudget } from '@ripplo/spec';
 import { S as Step } from './step-De52hTLd.js';
 
@@ -6,6 +6,12 @@ interface ObserverNeedsDescription {
     readonly description: (text: string) => ObserverNeedsBudget;
 }
 interface ObserverNeedsBudget {
+    /**
+     * Polling envelope: interval + total timeout the runner uses when calling
+     * `assert.backend()`. Pick by where the side effect lands — fast for
+     * same-request DB reads, slow for job-queue settle, async for
+     * webhook/email delivery. Too tight = flaky; too loose = slow suite.
+     */
     readonly budget: (tier: ObserverBudget) => ObserverNeedsInput;
 }
 interface ObserverNeedsInput {
@@ -37,6 +43,13 @@ interface TestNeedsName {
 }
 interface TestNeedsRequires {
     readonly description: (text: string) => TestNeedsRequires;
+    /**
+     * Declare the preconditions this test needs. The object keys become the
+     * destructured parameter in `.startsAt` / `.steps`, and each precondition's
+     * return data flows through as a typed proxy — interpolate proxy fields
+     * directly (e.g. `` `/workspaces/${workspace.id}` ``); never hand-write
+     * `{{namespace.key}}` template strings (lint blocks this).
+     */
     readonly requires: <TReqs extends PreconditionRecord>(reqs: TReqs) => TestNeedsOutcome<ResolveDeps<TReqs>>;
 }
 interface TestNeedsOutcome<TVars extends Record<string, Record<string, string>>> {
@@ -44,13 +57,33 @@ interface TestNeedsOutcome<TVars extends Record<string, Record<string, string>>>
 }
 
 interface TestNeedsStartsAt<TVars extends Record<string, Record<string, string>>> {
+    /**
+     * Skip implementation — compiles as a planning stub and is reported in
+     * `getUnimplemented()`. The test appears in the lockfile but is not run.
+     */
     readonly notImplemented: () => TestDefinition;
+    /**
+     * Starting URL for the test, derived from precondition data. The function
+     * receives the `.requires()` object destructured as typed proxies; it runs
+     * at compile time, not at test-author time.
+     */
     readonly startsAt: (fn: (vars: TVars) => string) => TestNeedsSteps<TVars>;
 }
 interface TestNeedsSteps<TVars extends Record<string, Record<string, string>>> {
+    /**
+     * Declare the ordered step list. Receives destructured precondition data as
+     * typed proxies (same as `.startsAt`). Every step must be labeled with
+     * `.as("…")` — lint enforces it.
+     */
     readonly steps: (fn: (vars: TVars) => ReadonlyArray<Step>) => TestNeedsCoverage;
 }
 interface TestNeedsCoverage {
+    /**
+     * Finalize the test and declare which mutation/AST branches it covers.
+     * Coverage IDs feed LLM-driven test scoping on diffs so only relevant tests
+     * run for a change. `.coverage()` (or `.notImplemented()`) is the only way
+     * to terminate the chain into a runnable `TestDefinition`.
+     */
     readonly coverage: (...ids: ReadonlyArray<CoverageStatementId>) => TestDefinition;
 }
 
@@ -73,20 +106,44 @@ interface RipploRegistries<P extends PreconditionRegistry, O extends ObserverReg
     readonly tests: ReadonlyArray<TestDefinition>;
 }
 interface RipploInstance<P extends PreconditionRegistry = PreconditionRegistry, O extends ObserverRegistry = ObserverRegistry> {
-    readonly config: DslConfig;
     readonly observers: O;
     readonly preconditions: P;
     readonly tests: ReadonlyArray<TestDefinition>;
-    readonly getConfig: () => DslConfig;
     readonly getObservers: () => ReadonlyArray<ObserverDefinition>;
     readonly getPreconditions: () => ReadonlyArray<PreconditionDefinition>;
     readonly getTests: () => ReadonlyArray<TestDefinition>;
     readonly getUnimplemented: () => UnimplementedItems;
 }
 type RipploBuilder = RipploInstance;
+/**
+ * Declare a precondition — a named, reusable piece of test data setup. Returns
+ * a pure handle (no side effects at definition time); the setup/teardown impl
+ * is wired once in `createEngine`. Depend on other preconditions via
+ * `.requires()` so the DAG can resolve independents in parallel, giving every
+ * test a clean, isolated slate.
+ */
 declare function precondition(name: string): PreconditionNeedsSetup;
+/**
+ * Declare a backend assertion — checked from tests via `assert.backend()`.
+ * The impl runs on your server (where DB/queue access lives) and is polled
+ * until pass/fail; `.budget()` picks the polling envelope. Use this instead
+ * of sleeps when verifying async side effects (jobs, webhooks, emails, DB rows).
+ */
 declare function observer(name: string): ObserverNeedsDescription;
+/**
+ * Start a test definition. `id` is a stable kebab-case key persisted in the
+ * lockfile and used for run history — changing it renames the test and loses
+ * history. Set `options.uiOnly` only for genuinely read-only flows (no
+ * mutations); do not use it to silence observer lint on flows that mutate
+ * state — wire the observer instead.
+ */
 declare function test(id: string, options?: TestOptions): TestNeedsName;
-declare function createRipplo<P extends PreconditionRegistry, O extends ObserverRegistry>(rawConfig: UserDslConfig, registries: RipploRegistries<P, O>): RipploInstance<P, O>;
+/**
+ * The single registration point for the DSL graph. Collects the three
+ * registries into an instance consumed both by `ripplo compile` (to write
+ * `.ripplo/ripplo.lock`) and by `createEngine` on the server, where
+ * TypeScript exhaustiveness-checks that every handle has exactly one impl.
+ */
+declare function createRipplo<P extends PreconditionRegistry, O extends ObserverRegistry>(registries: RipploRegistries<P, O>): RipploInstance<P, O>;
 
 export { type CoverageRegistry as C, type ObserverImplFn as O, type PreconditionImpl as P, type ResolveDeps as R, type ObserverRegistry as a, type PreconditionRecord as b, type PreconditionRegistry as c, type RipploBuilder as d, type RipploInstance as e, type RipploRegistries as f, createRipplo as g, observer as o, precondition as p, test as t };

package/dist/{chunk-5AGV4KQA.js → chunk-GWSEDWEF.js}

@@ -25,7 +25,7 @@ function compile(ripplo) {
     };
   });
   const tests = testDefs.map((def) => compileTest(def, preconditionDefs));
-  return { config: ripplo.getConfig(), observers, preconditions, tests };
+  return { observers, preconditions, tests };
 }
 function validateUniqueIds(defs) {
   const seen = /* @__PURE__ */ new Map();

package/dist/{chunk-D7DRM7AG.js → chunk-SBZJDJP4.js}

@@ -1,5 +1,4 @@
 // src/types.ts
-import { z } from "zod";
 var DEFAULT_WATCH_PATHS = [
   "**/src/**",
   "**/app/**",
@@ -60,17 +59,6 @@ var DEFAULT_IGNORE_PATHS = [
   "**/prisma/migrations/**",
   "**/scripts/**"
 ];
-var dslConfigSchema = z.object({
-  appUrl: z.string(),
-  engineUrl: z.string(),
-  ignorePaths: z.array(z.string()).optional(),
-  projectId: z.string(),
-  watchPaths: z.array(z.string()).optional(),
-  webhookSecret: z.string()
-});
-var userDslConfigSchema = dslConfigSchema.extend({
-  webhookSecret: z.string().optional()
-});
 function readTestValue(value) {
   return value.value;
 }
@@ -109,7 +97,6 @@ function makeObserverHandle({
 export {
   DEFAULT_WATCH_PATHS,
   DEFAULT_IGNORE_PATHS,
-  userDslConfigSchema,
   readTestValue,
   createTestValue,
   readPreconditionName,

package/dist/{chunk-TO3T2D2Y.js → chunk-UFHSNW4E.js}

@@ -1,6 +1,15 @@
 // src/adapters/shared.ts
 import { Webhook, WebhookVerificationError } from "standardwebhooks";
 import { z } from "zod";
+function readAdapterWebhookSecret() {
+  const value = process.env.RIPPLO_WEBHOOK_SECRET;
+  if (value == null || value.length === 0) {
+    throw new Error(
+      "ripplo: RIPPLO_WEBHOOK_SECRET is not set. The adapter needs it to verify precondition calls. Run `ripplo init` to generate one, or unset `enabled` to disable the adapter."
+    );
+  }
+  return value;
+}
 var batchRequestSchema = z.object({
   preconditions: z.array(z.string().min(1))
 });
@@ -75,6 +84,7 @@ function buildSetCookieHeader(cookie) {
 }
 
 export {
+  readAdapterWebhookSecret,
   batchRequestSchema,
   teardownRequestSchema,
   observerRequestSchema,

package/dist/compiler.d.ts

@@ -1,11 +1,9 @@
 import { Observer, Precondition, WorkflowSpec } from '@ripplo/spec';
-import { d as RipploBuilder } from './builder-CNJmzJVe.js';
-import { e as DslConfig } from './types-Do4o4Y_c.js';
+import { d as RipploBuilder } from './builder-0oT23S0W.js';
+import './types-B7YljrTz.js';
 import './step-De52hTLd.js';
-import 'zod';
 
 interface CompileResult {
-    readonly config: DslConfig;
     readonly observers: Record<string, Observer>;
     readonly preconditions: Record<string, Precondition>;
     readonly tests: ReadonlyArray<CompiledTest>;

package/dist/compiler.js

@@ -1,6 +1,6 @@
 import {
   compile
-} from "./chunk-5AGV4KQA.js";
+} from "./chunk-GWSEDWEF.js";
 import "./chunk-MGATMMCZ.js";
 import "./chunk-4MGIQFAJ.js";
 export {

package/dist/control.d.ts

@@ -6,6 +6,12 @@ declare const VARIABLE_INTERNAL: unique symbol;
 interface Variable<_TName extends string> {
     readonly [VARIABLE_INTERNAL]: _TName;
 }
+/**
+ * Declare a runtime placeholder, bound later by `extract()` and consumed by
+ * actions/assertions. Use for values produced mid-test (e.g. an ID rendered
+ * into the DOM). Precondition data is already typed and injected — reach for
+ * `variable` only when the value isn't known until the test runs.
+ */
 declare function variable<TName extends string>(name: TName): Variable<TName>;
 declare function readVariable(v: Variable<string>): string;
 declare function isVariable(v: unknown): v is Variable<string>;
@@ -18,6 +24,11 @@ interface VariableRef {
     readonly type: "variable";
 }
 declare function toStringValueRef(value: string | Variable<string>): StaticStringRef | VariableRef;
+/**
+ * Capture the text of the matched element into `target` (a `variable()`).
+ * Pairs by name — downstream steps referencing the same `variable` see the
+ * extracted value.
+ */
 declare function extract(locator: AnyLocator, target: Variable<string>): UnlabeledStep<{
     locator: {
         by: "testId";

package/dist/elysia.d.ts

@@ -1,8 +1,7 @@
 import { Elysia } from 'elysia';
-import { R as RipploEngine } from './engine-U84UJ0sj.js';
-import './builder-CNJmzJVe.js';
-import './types-Do4o4Y_c.js';
-import 'zod';
+import { R as RipploEngine } from './engine-BdKDGBYw.js';
+import './builder-0oT23S0W.js';
+import './types-B7YljrTz.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/elysia.js

@@ -2,10 +2,11 @@ import {
   batchRequestSchema,
   buildSetCookieHeader,
   observerRequestSchema,
+  readAdapterWebhookSecret,
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-TO3T2D2Y.js";
+} from "./chunk-UFHSNW4E.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/elysia.ts
@@ -18,7 +19,7 @@ function build({ enabled, engine }) {
   if (!enabled) {
     return app.put("/execute-preconditions", () => notFoundResponse()).put("/execute-observer", () => notFoundResponse()).put("/teardown-preconditions", () => notFoundResponse());
   }
-  const webhookSecret = engine.getConfig().webhookSecret;
+  const webhookSecret = readAdapterWebhookSecret();
   return app.put("/execute-preconditions", async ({ request }) => {
     const gate = await verifyAndReadBody(request, webhookSecret);
     if ("response" in gate) {

package/dist/{engine-U84UJ0sj.d.ts → engine-BdKDGBYw.d.ts}

@@ -1,5 +1,5 @@
-import { c as PreconditionRegistry, a as ObserverRegistry, O as ObserverImplFn, P as PreconditionImpl, e as RipploInstance } from './builder-CNJmzJVe.js';
-import { h as ObserverOutcome, C as CookieEntry, e as DslConfig, g as ObserverDefinition, k as PreconditionDefinition, U as UnimplementedItems, O as ObserverHandle, P as Precondition } from './types-Do4o4Y_c.js';
+import { c as PreconditionRegistry, a as ObserverRegistry, O as ObserverImplFn, P as PreconditionImpl, e as RipploInstance } from './builder-0oT23S0W.js';
+import { g as ObserverOutcome, C as CookieEntry, f as ObserverDefinition, j as PreconditionDefinition, U as UnimplementedItems, O as ObserverHandle, P as Precondition } from './types-B7YljrTz.js';
 
 interface EngineResult {
     readonly cookies: ReadonlyArray<CookieEntry>;
@@ -20,7 +20,6 @@ interface ObserverExecutionResult {
 interface RipploEngine {
     readonly executeObserver: (name: string, params: Record<string, string>) => Promise<ObserverExecutionResult>;
     readonly executePreconditions: (names: ReadonlyArray<string>, options?: ExecuteBatchOptions) => Promise<EngineResult>;
-    readonly getConfig: () => DslConfig;
     readonly getObservers: () => ReadonlyArray<ObserverDefinition>;
     readonly getPreconditions: () => ReadonlyArray<PreconditionDefinition>;
     readonly getUnimplemented: () => UnimplementedItems;

package/dist/express.d.ts

@@ -1,8 +1,7 @@
 import { Router } from 'express';
-import { R as RipploEngine } from './engine-U84UJ0sj.js';
-import './builder-CNJmzJVe.js';
-import './types-Do4o4Y_c.js';
-import 'zod';
+import { R as RipploEngine } from './engine-BdKDGBYw.js';
+import './builder-0oT23S0W.js';
+import './types-B7YljrTz.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/express.js

@@ -1,10 +1,11 @@
 import {
   batchRequestSchema,
   observerRequestSchema,
+  readAdapterWebhookSecret,
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-TO3T2D2Y.js";
+} from "./chunk-UFHSNW4E.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/express.ts
@@ -14,13 +15,9 @@ function createExpressHandler({ enabled, engine }) {
   if (!enabled) {
     return router;
   }
-  const webhookSecret = engine.getConfig().webhookSecret;
+  const webhookSecret = readAdapterWebhookSecret();
   router.use(json());
   router.use((req, res, next) => {
-    if (webhookSecret.length === 0) {
-      res.status(403).json({ error: "Webhook secret not configured" });
-      return;
-    }
     const payload = JSON.stringify(req.body);
     const headers = extractWebhookHeaders(req);
     if (!verifyWebhookSignature(payload, headers, webhookSecret)) {

package/dist/fastify.d.ts

@@ -1,8 +1,7 @@
 import { FastifyInstance } from 'fastify';
-import { R as RipploEngine } from './engine-U84UJ0sj.js';
-import './builder-CNJmzJVe.js';
-import './types-Do4o4Y_c.js';
-import 'zod';
+import { R as RipploEngine } from './engine-BdKDGBYw.js';
+import './builder-0oT23S0W.js';
+import './types-B7YljrTz.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/fastify.js

@@ -2,10 +2,11 @@ import {
   batchRequestSchema,
   buildSetCookieHeader,
   observerRequestSchema,
+  readAdapterWebhookSecret,
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-TO3T2D2Y.js";
+} from "./chunk-UFHSNW4E.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/fastify.ts
@@ -17,12 +18,9 @@ function registerFastifyHandler({
     return async () => {
     };
   }
-  const webhookSecret = engine.getConfig().webhookSecret;
+  const webhookSecret = readAdapterWebhookSecret();
   return async (fastify) => {
     fastify.addHook("preHandler", async (req, reply) => {
-      if (webhookSecret.length === 0) {
-        return reply.code(403).send({ error: "Webhook secret not configured" });
-      }
       const payload = JSON.stringify(req.body);
       const headers = {
         "webhook-id": extractHeader(req, "webhook-id"),

package/dist/hono.d.ts

@@ -1,8 +1,7 @@
 import { Hono } from 'hono';
-import { R as RipploEngine } from './engine-U84UJ0sj.js';
-import './builder-CNJmzJVe.js';
-import './types-Do4o4Y_c.js';
-import 'zod';
+import { R as RipploEngine } from './engine-BdKDGBYw.js';
+import './builder-0oT23S0W.js';
+import './types-B7YljrTz.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/hono.js

@@ -2,10 +2,11 @@ import {
   batchRequestSchema,
   buildSetCookieHeader,
   observerRequestSchema,
+  readAdapterWebhookSecret,
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-TO3T2D2Y.js";
+} from "./chunk-UFHSNW4E.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/hono.ts
@@ -15,7 +16,7 @@ function createHonoHandler({ enabled, engine }) {
   if (!enabled) {
     return app;
   }
-  const webhookSecret = engine.getConfig().webhookSecret;
+  const webhookSecret = readAdapterWebhookSecret();
   app.use("*", createWebhookMiddleware(webhookSecret));
   app.put("/execute-preconditions", async (c) => {
     const body = tryParseJson(c.get("rawBody"));

package/dist/index.d.ts

@@ -1,12 +1,11 @@
-export { C as CoverageRegistry, O as ObserverImplFn, a as ObserverRegistry, P as PreconditionImpl, b as PreconditionRecord, c as PreconditionRegistry, R as ResolveDeps, d as RipploBuilder, e as RipploInstance, f as RipploRegistries, g as createRipplo, o as observer, p as precondition, t as test } from './builder-CNJmzJVe.js';
+export { C as CoverageRegistry, O as ObserverImplFn, a as ObserverRegistry, P as PreconditionImpl, b as PreconditionRecord, c as PreconditionRegistry, R as ResolveDeps, d as RipploBuilder, e as RipploInstance, f as RipploRegistries, g as createRipplo, o as observer, p as precondition, t as test } from './builder-0oT23S0W.js';
 import { CompileResult } from './compiler.js';
 export { CompiledTest, compile } from './compiler.js';
-export { E as EngineImpls, a as EngineResult, b as ExecuteBatchOptions, N as NotImplemented, O as ObserverImplFnFor, P as PreconditionImplFor, R as RipploEngine, c as createEngine, n as notImplemented } from './engine-U84UJ0sj.js';
-import { C as CookieEntry } from './types-Do4o4Y_c.js';
-export { c as CookieOptions, D as DEFAULT_IGNORE_PATHS, d as DEFAULT_WATCH_PATHS, e as DslConfig, f as ObserverContext, g as ObserverDefinition, O as ObserverHandle, a as ObserverInput, h as ObserverOutcome, P as Precondition, i as PreconditionDeps, S as SetupContext, T as TeardownContext, j as TestDefinition } from './types-Do4o4Y_c.js';
+export { E as EngineImpls, a as EngineResult, b as ExecuteBatchOptions, N as NotImplemented, O as ObserverImplFnFor, P as PreconditionImplFor, R as RipploEngine, c as createEngine, n as notImplemented } from './engine-BdKDGBYw.js';
+import { C as CookieEntry } from './types-B7YljrTz.js';
+export { c as CookieOptions, D as DEFAULT_IGNORE_PATHS, d as DEFAULT_WATCH_PATHS, e as ObserverContext, f as ObserverDefinition, O as ObserverHandle, a as ObserverInput, g as ObserverOutcome, P as Precondition, h as PreconditionDeps, S as SetupContext, T as TeardownContext, i as TestDefinition } from './types-B7YljrTz.js';
 export { D as DslNodeInput } from './step-De52hTLd.js';
 import '@ripplo/spec';
-import 'zod';
 
 interface LintDiagnostic {
     readonly message: string;

package/dist/index.js

@@ -10,18 +10,17 @@ import {
   readPreconditionDependsOn,
   readPreconditionDescription,
   readPreconditionName,
-  readTestValue,
-  userDslConfigSchema
-} from "./chunk-D7DRM7AG.js";
+  readTestValue
+} from "./chunk-SBZJDJP4.js";
 import {
   compile
-} from "./chunk-5AGV4KQA.js";
+} from "./chunk-GWSEDWEF.js";
 import "./chunk-MGATMMCZ.js";
 import {
   buildSetCookieHeader,
   serializeCookie,
   verifyWebhookSignature
-} from "./chunk-TO3T2D2Y.js";
+} from "./chunk-UFHSNW4E.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/observer.ts
@@ -63,26 +62,16 @@ function test(id, options) {
   validateTestId(id);
   return buildTestName(id, options?.uiOnly);
 }
-function createRipplo(rawConfig, registries) {
-  const parsed = userDslConfigSchema.parse(rawConfig);
-  const webhookSecret = parsed.webhookSecret ?? process.env["RIPPLO_WEBHOOK_SECRET"] ?? "";
-  if (webhookSecret.length === 0) {
-    throw new Error(
-      "RIPPLO_WEBHOOK_SECRET is required. Set it in .ripplo/.env or pass webhookSecret to createRipplo()."
-    );
-  }
-  const config = { ...parsed, webhookSecret };
+function createRipplo(registries) {
   const { observers, preconditions, tests } = registries;
   validateUniqueNames(preconditions, observers, tests);
   const preconditionDefs = Object.values(preconditions).map((p) => stubPreconditionDef(p));
   const observerDefs = Object.values(observers).map((o) => stubObserverDef(o));
   const testDefs = [...tests];
   return {
-    config,
     observers,
     preconditions,
     tests: testDefs,
-    getConfig: () => config,
     getObservers: () => observerDefs,
     getPreconditions: () => preconditionDefs,
     getTests: () => testDefs,
@@ -777,7 +766,6 @@ function createEngine(ripplo, impls) {
   return {
     executeObserver: (name, params) => executeObserver(observersByName, name, params),
     executePreconditions: (names, options) => executePreconditions({ defsByName: preconditionsByName, names, options }),
-    getConfig: () => ripplo.getConfig(),
     getObservers: () => observerDefs,
     getPreconditions: () => preconditionDefs,
     getUnimplemented: () => ({

package/dist/koa.d.ts

@@ -1,8 +1,7 @@
 import { Middleware } from 'koa';
-import { R as RipploEngine } from './engine-U84UJ0sj.js';
-import './builder-CNJmzJVe.js';
-import './types-Do4o4Y_c.js';
-import 'zod';
+import { R as RipploEngine } from './engine-BdKDGBYw.js';
+import './builder-0oT23S0W.js';
+import './types-B7YljrTz.js';
 import './step-De52hTLd.js';
 import '@ripplo/spec';
 

package/dist/koa.js

@@ -2,10 +2,11 @@ import {
   batchRequestSchema,
   buildSetCookieHeader,
   observerRequestSchema,
+  readAdapterWebhookSecret,
   serializeCookie,
   teardownRequestSchema,
   verifyWebhookSignature
-} from "./chunk-TO3T2D2Y.js";
+} from "./chunk-UFHSNW4E.js";
 import "./chunk-4MGIQFAJ.js";
 
 // src/adapters/koa.ts
@@ -15,7 +16,7 @@ function createKoaHandler({ enabled, engine }) {
       await next();
     };
   }
-  const webhookSecret = engine.getConfig().webhookSecret;
+  const webhookSecret = readAdapterWebhookSecret();
   return async (ctx, next) => {
     if (ctx.method !== "PUT") {
       await next();
@@ -26,11 +27,6 @@ function createKoaHandler({ enabled, engine }) {
       await next();
       return;
     }
-    if (webhookSecret.length === 0) {
-      ctx.status = 403;
-      ctx.body = { error: "Webhook secret not configured" };
-      return;
-    }
     const body = await readBody(ctx);
     const headers = {
       "webhook-id": headerString(ctx.get("webhook-id")),

package/dist/locators.d.ts

@@ -24,7 +24,17 @@ type AnyLocator = Locator<"role" | "testId">;
 type InputLocator = Locator<"testId"> | RoleLocator<"combobox" | "searchbox" | "spinbutton" | "textbox">;
 type SelectLocator = Locator<"testId"> | RoleLocator<"combobox" | "listbox">;
 type CheckLocator = Locator<"testId"> | RoleLocator<"checkbox" | "switch">;
+/**
+ * Preferred locator: targets an element by its ARIA role and accessible name.
+ * Survives DOM churn and doubles as an accessibility check — if a role query
+ * can't find your element, real users likely can't either.
+ */
 declare function role<TRole extends AriaRole>(ariaRole: TRole, name?: string): RoleLocator<TRole>;
+/**
+ * Escape hatch for elements without a semantic role (decorative wrappers,
+ * non-interactive panels). Prefer `role()` when the element has one; a
+ * test-id locator has no accessibility signal.
+ */
 declare function testId(id: string): Locator<"testId">;
 
 export { type AnyLocator, type AriaRole, type CheckLocator, type InputLocator, type Locator, type LocatorSpec, type RoleLocator, type SelectLocator, readLocator, role, testId };

package/dist/lockfile.d.ts

@@ -1,8 +1,8 @@
 import { Codec } from '@ripplo/spec';
 import { z } from 'zod';
 import { CompileResult } from './compiler.js';
-import './builder-CNJmzJVe.js';
-import './types-Do4o4Y_c.js';
+import './builder-0oT23S0W.js';
+import './types-B7YljrTz.js';
 import './step-De52hTLd.js';
 
 declare const LOCKFILE_RELATIVE_PATH = ".ripplo/ripplo.lock";