@docsxai/engine
LLM-agnostic engine: flow-file parser + runtime, calibration helpers, target-site auth strategies, and the full docsxai CLI.
The engine never calls a model API. Calibration-time inference is supplied by the host agent (Claude Code, Codex, anything that speaks MCP) through the plugin's skill surface; execution is deterministic and replays a doc pack through headless Playwright.
Surface
Section titled “Surface”- Flow-file: declarative YAML at
<workspace>/flows/<name>.flow.yaml, withprerequisites+locators+steps[](action,target,wait_for,success,annotation/annotations, per-stepredactions,timeout_ms). Actions:navigate,click,fill,upload,press,hover,select,check,uncheck,wait,hide,show. Hand-editable; schema-validated.extends:composition for shared preambles (withenvironmentmerged per-key, child wins;redactionsconcatenated). - Execution environment: optional
environmentblock (EnvironmentSpec) with frozenclock(Playwright clock API),locale,timezone,viewport(VIEWPORT_PRESETS: desktop / tablet / mobile, or explicit size),color_scheme,reduced_motion. Applied at context creation bylaunchPlaywrightSession({ environment }); on CDP-attached sessions only the clock applies (one stderr warning lists skipped fields).contextOptionspasseshttpCredentials/clientCertificates/extraHTTPHeadersthrough tobrowser.newContext. - Device scale factor:
docsxai run --device-scale-factor <1-4>(orDOCSX_DEVICE_SCALE_FACTOR, flag wins; default 1, output unchanged) passesdeviceScaleFactorto the browser context (launchPlaywrightSession({ deviceScaleFactor })), so the PNG is the CSS viewport times the factor.bounding_boxandobstaclesstay in the PNG's device pixels, andannotations.jsonrecordsdevice_scale_factorabove 1 sodocsxai burncan derive its pixel ratio. Not combinable with--cdp. - Request guard (opt-in):
DOCSX_EGRESS_GUARD=1(orlaunchPlaywrightSession({ egressGuard })) routes every request of the browser context throughegress-guard.ts: a host that is, or resolves (dns.lookup, all addresses) to, a link-local or cloud-metadata address is aborted, redirect hops and WebSocket connections included, and a failed lookup aborts too (the printed reason is generic:address not allowed);DOCSX_EGRESS_DENY_PRIVATE=1adds loopback and private ranges. Both take1,trueoryes. Off by default for a localrun; the backend runner turns it on for webhook runs, and so does the MCP HTTP transport for the browserrun_flowsstarts. It does not stop DNS rebinding (SECURITY.md). Anuploadstep reads only regular files under the workspace (upload-path.ts). The address rules inaddress-class.tsare a byte-identical copy of the backend's. - Hiding + step timeouts:
hidesetsvisibility: hidden !importanton every element itstargetmatches until ashow(no target lifts all, a target lifts thehidethat used the same selector).PlaywrightDrivermarks the elements with a data attribute and adopts a fixed stylesheet keyed on it (page-hide.ts, in-page and engine-owned; the selector is data, never CSS or script). The rule lives on each element's own root, so it reaches shadow trees, and constructable stylesheets are not blocked by a page's CSP. Visibility keeps the box, so nothing reflows; there is deliberately nodisplay: noneoption and no general CSS-injection step. The driver keeps the selectors and re-marks before every screenshot (halt shots included), so the hiding survives navigations and re-renders.hidewaits for the element to exist (attached) and throws when none does, sooptional: truecovers dev-only UI such asnextjs-portal. A step'stimeout_ms(100 to 30000) is passed to the driver call (click(selector, timeoutMs?),hideElements(selector, timeoutMs?), …); unset, nothing is passed and Playwright's 30 s default applies, so existing flows and non-optional steps are unchanged.optionaldoes not shorten the wait by itself, so a missing optional target costs 30 s unlesstimeout_msis set;lintR011 says so.BrowserDrivergains optionalhideElements?/showElements?; the runtime halts a step that needs a missing one. The purehiddenAtEachStep(flow-hidden.ts) tellslint(R013) anddiagnosewhich selectors an earlierhidehid. - Redactions: flow-level + per-step
RedactionSpec[]({ selector }or{ region }, stylebox|pixelate) masked deterministically before any screenshot (halt shots included) hits disk. The pure pixel transform isapplyRedactionsinredact.ts. BrowserDriverinterface: what the runtime needs from a browser. ThePlaywrightDriverimplementation includes theactionable()predicate (seedocs/actionability-contract.md) that browser-bridge consumers can mirror, plus a realelement_stablewait (bounding-box polling, 10 s best-effort budget).waitForSettled?,hideElements?,showElements?andnearbyBoxes?are optional methods (behindwait_for: settled, thehideandshowactions andannotations.obstacles), so a driver written before they existed still compiles; the runtime halts a step that needs a missing method with a message naming it (obstaclesonly when the workspace turned it on), and never calls a method the flow does not use.PlaywrightDriverruns the fixed in-page poll inpage-settle.ts(fonts loaded, visible images complete, viewport box geometry unchanged for two consecutive polls, every 50 ms, bounded by the step'stimeout_ms, default 10 s) and rejects withsettled: page did not settle within N ms ...naming what kept moving;inferHaltCauseturns that into the[page never settled: ...]prefix.- Annotation obstacles: opt-in (
.docsxai.json→"annotations": { "obstacles": true }, default off). After a step's screenshot,runFlowasks the driver fornearbyBoxes(selector, 320): the visible text (per rendered line) and interactive elements around the target, in screenshot pixels, the target's subtree and elements containing it excluded. The pureselectObstacles(obstacles.ts) rounds boxes outward to whole pixels, clips them to the screenshot, drops duplicates, boxes inside the target and boxes covered by another kept box, caps at the 40 nearest and sorts by y, x, width, height. The result lands asobstacleson the annotation record, where the viewer'sburnuses it to keep callouts off page content. The scan reads the page's own DOM (no iframe or shadow-root content) and runs only through the driver, so anyBrowserDrivermust implementnearbyBoxes. Off or absent, records and screenshots are unchanged. - Per-annotation placement: a step annotation takes an optional
placementobject (AnnotationPlacement:inside,side,align,pin_arrow,max_width,obstacle_radius,obstacle_limit), bounded likeobstacles(finite numbers in range,max_width120 to 560,obstacle_radius0 to 2000 CSS px,obstacle_limit1 to 40) and copied onto the annotation record when set.runFlowscans with the annotation's ownobstacle_radiusand keeps its ownobstacle_limitnearest boxes; the burner reads the rest. Absent, records and scans are exactly as before. - Auth strategies:
auth/strategy.yamldescriptor + a catalogue of scripted strategies (api-login,ui-formwith a TOTP hop,email-otp,webauthn,jwt-injection,http-basic,pat-header,mtls,test-backdoor) alongside the human-in-the-loopmanual-capture. See Auth strategies below. - CLI:
docsxai <command>. See--helpor the top-level README for the full surface; this package'sdist/cli.jsis the binary.
CLI commands
Section titled “CLI commands”init scaffold a workspacecapture-auth cache an authed sessionadd-flow extract a flow-file from a structured guide (formerly calibrate, removed in 0.5.0)inspect discover [data-testid] locators on the live pagerun execute flows headless; emit annotations + screenshots (`--verify-determinism` byte-compares N isolated runs)render build the static viewer (spawns the @docsxai/viewer bin; `--lang es` for Spanish page text)burn bake annotations into PNG copies (spawns the same bin's `burn`)site write an Astro Starlight docs site (spawns the same bin's `site`, same flags)pack build the screenshot pack: burn, optimise, hash-name, manifest; `--check` compares a rebuild with the committed pack (spawns the viewer bin's `pack`)lint static checks across flow-files (R001-R017; `extraRules` injectable via `lintFlow`)flow-tree visualise the `extends` graphdiagnose halt-context + recommendations after a haltdoctor environment + workspace health-check (one ok:/fail: line per check, each with a next: step; no plugin code runs)style init/validate style.yaml; --check scans for jargon leakszip package the doc pack for hand-offbaseline snapshot the doc pack (flows, prose, annotations, screenshots, locators) for drift comparisondiff deterministic drift report against a baseline (--fail-on warn|fail gates CI)export project the doc pack to a publisher format (`export adf`: Confluence ADF; `export playwright`: Playwright specs)plugins list / info / sync the workspace plugin set (see Plugins below)login validate a backend bearer token (`--oauth` runs the OAuth 2.1 + PKCE flow)push upload the doc pack to the backend as a new revisionpull fetch a backend revision's artifacts into the workspaceA flag a command does not take exits 2 (run --flwo x prints unknown flag --flwo, did you mean --flow?), as does a flag given twice (except burn --flow and site --flow) and a value flag with no value. A flag that takes no value never reads the next argument, so run --pause <workspace> keeps the workspace. The flag table is src/cli-flags.ts; burn, pack, site and doctor read their argv in their own loops, and doctor rejects an unknown or repeated flag the same way. run --start-from and --stop-after check the step id against the selected flows before the browser launches, and a step id no selected flow has exits 2. Ctrl-C (SIGINT) or SIGTERM stops a command with one docsxai: interrupted line and exits 130 or 143. While render, burn, site or pack runs, the signal goes to the viewer child and docsxai waits for it: the child gets SIGKILL after 10 s, and a second signal exits at once.
First-run failures print one reason and one next: line (browser-launch-error.ts, cli-node-guard.ts, cli-shared.ts). A missing Chromium gives the install command, a refused --cdp endpoint gives cannot attach to the browser at <endpoint> (ECONNREFUSED) and the --remote-debugging-port flag, and run --cdp skips the cached-session check. init --app-url and login --backend-url take only http: or https: URLs (isHttpUrl) and exit 2 otherwise; run --base-url also takes file: (isRunnableUrl, for a local static site) and exits 2 on any other scheme; an app_url in .docsxai.json that is not one stops run with exit 1. init on a file and a refused mkdir get their own message, run, lint and flow-tree on a workspace without flows/ print mkdir <dir>/flows (missingFlowsMessage), a cached session that is not a valid session file is called corrupt (cachedSessionIsCorrupt), and a .docsxai.json that exists but cannot be read warns in run and capture-auth and fails doctor with chmod u+r. doctor exits 2 on an unknown flag. cli-node-guard.ts runs first in cli.ts and exits 1 with one line on Node 18 and older (NODE_FLOOR_MAJOR, 20), before Playwright loads.
A flow with a top-level matrix: (locales, color_schemes, viewports; at most 64 variants) expands at parse time (expandFlow in flow-matrix.ts, schema in matrix-spec.ts) into one flow per variant, each under its own environment, with only/skip on steps and annotations and copy_by_locale on annotations. run starts one session per variant (run-flows.ts) and writes docs/<flow>/<variant>/{screenshots/, annotations.json, halts/}; annotations.json records the variant, and a halt message names it. Without a matrix the layout and every output byte are unchanged. lint (R015, R016), flow-tree and diagnose --variant read the matrix.
run has a sub-3-second iteration mode for long-async flows: --start-from <step-id> --cdp <endpoint> skips every step before the target and attaches to an already-warm Chrome.
zip packages the doc pack in-process (via fflate), no system zip binary required, and deterministically: entries are sorted, every entry's mtime is pinned to the zip epoch (1980-01-01), and the compression level is fixed, so the same doc pack always produces a byte-identical archive. Includes flows/, docs/, .docsxai.json, auth/strategy.yaml, README.md; excludes .auth/, **/halts/, and (unless --include-viewer) .viewer/. Symlinks that point outside the workspace are never followed into the archive, the fixed entries included, and the archive is written atomically.
export adf projects the doc pack to Confluence Cloud ADF (projectDocPackToAdf from the library surface), pure and deterministic, zero HTTP. Default --mode single emits one consolidated document (flows as anchored H2 sections); --mode page-tree emits a parent overview plus one document per flow. Output lands in <workspace>/.export/adf/ as projection.json + attachments.json (file name, source path, sha256 per burned screenshot, falling back to the clean screenshot with a warning when no burned PNG exists). A host agent hands these to the Atlassian MCP, or the @docsxai/plugin-confluence publisher (confluence:push) consumes them; all Confluence HTTP lives in that capability-declared plugin, never in the engine.
baseline + diff are the drift-detection pair. baseline snapshots flows/ + docs/ (step .mds, annotations.json, screenshots/, locators.yaml) into <workspace>/.baseline/ (or --out <dir>); diff compares the live workspace against it (diffDocPacks on the library surface) and emits a deterministic docsxai/drift@1 report. Per flow: id-keyed step field deltas, annotation moves beyond a pixel tolerance, screenshot pixel diffs via pngjs (changed-pixel count / pct / changed-region bbox; dimension changes flagged distinctly; ignore_regions excluded), prose line-change counts, and locator changes. --format md (formatDriftReportMarkdown) is PR-comment-ready; --fail-on warn|fail exits 1 at/above the threshold (defaults: ≥1% changed pixels = warn, ≥5% = fail, structural change = warn). The engine detects and reports; proposing flow-file patches stays with the host agent (diagnose).
run --verify-determinism [--runs <2-5>] [--format text|md|json] runs the selected flows N times (default 2) through the same flow loop as a plain run (runFlowsInSessions), each into its own output root under <workspace>/.docsxai-verify/run-<k>/ (PlaywrightSessionOptions.outputRoot redirects the screenshots; upload sources still resolve against the workspace), then byte-compares every file under the roots (compareRuns in verify-compare.ts, exported). The first differing artefact is named by path with a cause: JSON key path, PNG changed-pixel count and region (the diffPngBuffers of diff), first differing text line, or sizes. A halt is recorded as docs/<flow>/halts/halt-context.json in the run root, so halt context is compared like any artefact; a halted flow makes the verdict halted (exit 1). Run 1's tree is copied into the workspace only when every run agrees and none halted; otherwise the workspace is untouched. The roots are removed by their listing (unlink each file, rmdir each directory deepest first; verify-tree.ts), never recursively. The docsxai/verify-determinism@1 report has no timestamps or paths and is ordered by ordinal path then run: exit 0 identical, 1 differing or halted, 2 usage. Nightly recipes for GitHub Actions, GitLab CI and Woodpecker are in docs/ci-recipes.md and examples/ci/.
export playwright renders each flow (with extends resolved) as a self-contained Playwright .spec.ts (exportFlowAsPlaywrightTest) into <workspace>/.export/tests/: locator consts, steps as page actions, wait_for as waits, success as expect() assertions, environment as test.use() + page.clock.setFixedTime, optional steps in try/catch. Deterministic; generated files carry a "regenerate, don't hand-edit" header.
render, burn, site and pack locate the viewer bin in order: DOCSX_VIEWER_BIN (path to the viewer's bin script or an executable), the @docsxai/viewer package installed next to the engine (its bin run with the current Node), then docsxai-viewer on PATH. A launch failure reports all three attempts.
burn <workspace-dir> [--flow <name>] [--out <dir>] [--report <file>] [--no-connector-outline] [--strict-glyphs] bakes the annotations into PNG copies by running the viewer's burn through that same resolution (the engine does not depend on @docsxai/viewer). It checks the workspace has a docs/ directory, passes the flags through, and returns the viewer's exit code; an unknown flag or a path-like --flow exits 2. The viewer skips an annotation whose bounding_box is off the image, has no area or holds NaN (a warning names the selector and step; --report marks it skipped) and clips one that overhangs an edge.
pack <workspace-or-raw-dir> [--from-raw] [--out <dir>] [--public-prefix <path>] [--no-optimise] [--generated-for <text>] and pack <workspace-or-raw-dir> --check --against <pack-dir> [--from-raw] [--threshold <pct>] (cli-commands-pack.ts) are the screenshot-pack pair. The old drift command is retired: cli-retired.ts maps it to pack --check with a deprecation warning (deprecation.ts). Like burn, the engine validates the argv edge (an unknown flag, a flag with no value, a second positional, no --against, a --threshold that is not a number >= 0 all exit 2), then runs the viewer's pack or drift through the same bin resolution (runViewerBin in viewer-bin.ts) and returns its exit code. The viewer owns the logic (burn, oxipng, hashing, manifest, drift); the engine does not import it. See the viewer README.
push reads the whole doc pack before it touches the backend, so an unreadable pack (an invalid docs/style.json) exits 1 with nothing created there, and it leaves out files that are symlinks to a file outside the workspace; the backend ids it records in .docsxai.json are written atomically. pull requests only the artifact names flows, annotations, screenshots, style and locators (a warning for any other name) and writes the doc pack as one transaction (writeDocPack in doc-pack-io.ts, staging through atomic-write.ts): every file is staged next to its target and renamed into place together, a failure while staging changes nothing, and a failed rename puts the swapped files back. export adf and export playwright skip a flow file, step markdown file or screenshot that is a symlink to a file outside the workspace; one that points inside it still works.
lint rule R017 warns when a flow's name: differs from its file name, because extends, --flow and docs/<name>/ use the name. Two flow files with one name: stop run, lint and flow-tree with exit 1. A matrix viewport name may not be screenshots, halts or a Windows device name (con, prn, aux, nul, com1 to com9, lpt1 to lpt9), because it becomes a directory. style on a path that is not a directory exits 1 and writes nothing.
Auth strategies
Section titled “Auth strategies”Target-site auth lives in src/auth/ (one module per strategy) behind the src/auth.ts re-export shim. Every strategy implements AuthStrategy.authenticate(ctx) → AuthResult and reduces to the same universal artifact: a storageState (cookies + localStorage) the runtime seeds the browser context with, plus, for connection-level schemes, contextOptions (httpCredentials / extraHTTPHeaders / clientCertificates) passed through to browser.newContext. Roles are declared in <workspace>/auth/strategy.yaml (docsxai/auth-strategy@1): per-role strategy, creds_env (credential keys → env-var names, never values), options, and cache (local/backend store, ttl, auth_cookie expiry pinning). The local cache is <workspace>/.auth/<role>.json, written with mode 0600 (src/auth/storage-state-cache.ts); a role name with characters outside A-Za-z0-9_.-, and backend-token, gets a hash suffix in the file name, so two roles never share a file and none overwrites the OAuth token file.
| Strategy | Scheme | Browser needed |
|---|---|---|
api-login | POST creds to the login endpoint; cookies collected across the redirect chain (own RFC-6265 jar) | no |
ui-form | drive the app's own login form: fill, submit, success marker, snapshot; pre_steps dismiss pre-login chrome; options.totp adds an RFC-6238 hop (dep-free generateTotp/verifyTotp primitives exported) | headless |
email-otp | ui-form whose code arrives by mail; an InboxProvider polls the inbox (http-json built-in: Mailpit-style { messages: [{to, received_at, body}] }); code_pattern extracts the code (default \b(\d{6})\b) | headless |
webauthn | passkey via a CDP virtual authenticator (ctap2 / internal / user-verifying), attached before navigation; trigger_selector starts the ceremony | headless |
jwt-injection | static token (token_env) or OAuth2 client-credentials mint (token_url); injected into localStorage and/or cookies via {{token}} templates | no |
http-basic | connection-level httpCredentials | no |
pat-header | token header via extraHTTPHeaders (value_template, default Bearer {{token}}) | no |
mtls | client certificate via clientCertificates (creds_env maps cert/key to PEM file paths) | no |
test-backdoor | POST a shared secret to a test-only endpoint | no |
manual-capture | instrumented Chrome; a human logs in and triggers capture | headed |
Cross-cutting contracts:
- Secrets stay out of band. Strategies read env-var names from the descriptor and resolve values at run time; error messages mask values as
<SET>/<UNSET>and never echo them. - User pools. Any credential env value may be comma-separated (
u1,u2,u3);resolveCreds({ workerIndex })gives parallel worker N entryN % len, consistently across every pooled variable. expiresAtwhen derivable. From the named / lone real-expiry cookie (jarAuthExpiry), the JWTexpclaim, or the token endpoint'sexpires_in; the cache'sauth_cookie/ttlrules cover the rest.- Registries.
registerAuthStrategy(name, impl)adds or overrides a scheme (consulted before the built-ins: the plugins-runtime hook);registerInboxProvider(name, factory)addsemail-otpinbox shapes. - One Playwright import site. Browser-driving strategies depend on the narrow
AuthPageinterface (src/auth/browser-session.ts); the default launcher routes throughlaunchPlaywrightSession, so unit tests fake the page andplaywright-driver.tsremains the engine's single Playwright integration point.
Plugins
Section titled “Plugins”The engine hosts a workspace plugin runtime (v1) with four extension points: publishers, renderers, lint-rules, and auth-strategies. Plugins are normal npm packages: a docsxai field on package.json plus a module exporting register(api). They run in-process and unsandboxed: trust is a review signal, not a boundary. The no-model-API rule binds them exactly as it binds the engine.
Manifest (package.json#docsxai)
Section titled “Manifest (package.json#docsxai)”{ "name": "@docsxai/plugin-confluence", "version": "0.1.0", "docsxai": { "apiVersion": "1.0.0", "namespace": "confluence", "register": "./dist/register.js", "kinds": ["publisher"], "capabilities": ["egress:*.atlassian.net"], "dependsOn": [], "trust": "example-org" }}apiVersion: exact semver of the runtime contract the plugin codes against. Must share the engine'sRUNTIME_API_VERSIONmajor with minor ≤ the runtime's, or the plugin load-errors.namespace: mandatory,/^[a-z][a-z0-9-]*$/. Every registered artifact is exposed as<namespace>:<name>(the runtime prefixes; plugins pass bare names). Reserved:site-docs,docsxai,core,plugins. Two plugins claiming one namespace are both disabled.kinds: the extension points the plugin registers (≥1). Registering an undeclared kind throws and load-errors the plugin (capability-disclosure honesty).capabilities:egress:<host-glob>declarations, subset-checked against the workspace'splugin_capabilities. Mismatch disables the plugin (status, not fatal). Publisher plugins are the only wiki/VCS egress path in the engine.dependsOn:{ plugin, version }entries (package name +^/~/exact range). Load order is topological; cycles are rejected as a unit.
register(api)
Section titled “register(api)”The register module exports a register(api) function (named or default). api exposes namespace, declaredKinds, declaredCapabilities, registerPublisher(name, impl), registerRenderer(name, impl), registerLintRules(name, rules), registerAuthStrategy(name, impl), a stderr logger (api.log, prefixed [plugin:<ns>]), and api.workspacePath(...segments), the only filesystem root a plugin may touch (escape attempts throw). The extension-point contracts (PublisherPlugin, RendererPlugin, AuthStrategyPlugin, PluginLintRule) are exported from this package.
Workspace config + lock
Section titled “Workspace config + lock”Two optional .docsxai.json keys wire plugins into a workspace (a third, annotations.obstacles, switches on obstacle scanning for run; see the engine overview above):
{ "plugins": [{ "package": "@docsxai/plugin-confluence" }, { "path": "../my-local-plugin" }], "plugin_capabilities": ["egress:*.atlassian.net"]}@docsxai/plugin-confluence is repo-only (private: true, not on npm). Build it in a checkout (pnpm -r build) and wire it by path instead: { "path": "<checkout>/packages/plugin-confluence" }. The { "package": ... } form resolves only once the package is installed in the workspace.
plugins-lock.json (schema docsxai/plugins-lock@1, next to the config) pins each plugin's register-module sha256. When it exists, every resolve verifies the bytes before importing; a mismatch fails closed with a "run docsxai plugins sync" message.
docsxai plugins list <workspace> status table (loaded / disabled reasons); exit 1 if any plugin isn't loadeddocsxai plugins info <workspace> <namespace> manifest + registered artifact namesdocsxai plugins sync <workspace> (re)write plugins-lock.json, never executes plugin codeAll three accept --format json. Plugins are resolved once per CLI invocation, so there is no hot reload.