Skip to content

feat: scripts, steps that are code - #23

Merged
ajaishankar merged 7 commits into
mainfrom
feature/scripting
Oct 26, 2026
Merged

ajaishankar merged 7 commits into
mainfrom
feature/scripting

Conversation

@ajaishankar

Copy link
Copy Markdown
Member

What

A script is a step of a flow that is code instead of a request, such as a payment SDK that needs a browser or a library that runs anywhere. It is modelled on a request: with(), withMock(), capture, assert, tags and safe.

  • Contract. scripts/<name>.script.ts holds the inputs (the same controls a flow uses), where it runs, and the body.
  • Output. There is no output field. What the body returns is the output type, so the next step reads it as ctx.captured.<name> and the compiler checks the name.
  • Mock. withMock returns what the mock environment answers, from the inputs. A script without one fails on mock, and specbook check warns.
  • Body. Inline with run, or in its own file with load: () => import('./x.browser'). That file exports run, so the portal fetches an SDK's code only when the step runs and a bundle leaves it out.
  • Where it runs. The portal runs browser and isomorphic scripts. specbook test and bundles run node and isomorphic ones. A flow that needs another host is skipped as a whole and counts as passed. On mock every script answers, so CI still checks the flow.
  • On its own. A script is also a target: specbook test runs scripts/**/*.script.ts, the catalog lists it under Scripts, and an embed opens it with data-specbook-script.
  • h.loadScript(url, { global, integrity, once }). Loads a file once per address by default, for the page's life or one test run. once: false loads it again on that call.

Commits

Six commits by area (core, vite, cli, ui, example, docs), plus one that orders the reference sidebar and gives the custom pages the same section link icon as Starlight. Squash is fine.

Testing

  • Typecheck, lint, and the unit and slow suites pass. specbook check and specbook test pass on the example app.
  • One browser test, "edits sequence controls in the same grid as request parameters", timed out once under load and passed when run alone.
  • Not run by hand: the Turnstile demo in a real browser after the last refactor.

🤖 Generated with Claude Code

ajaishankar and others added 7 commits October 25, 2026 20:13
…s, run in flows or on their own

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… embed them

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e, in flows

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…nstile demo

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…icon

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@ajaishankar
ajaishankar merged commit 56faa7e into main Oct 26, 2026
4 checks passed
@ajaishankar
ajaishankar deleted the feature/scripting branch October 26, 2026 01:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant