docs+install: post-rename docs polish, install script, d2 architecture diagram (#26)

* docs: add sanderling bird artwork to README and docs index

* chore: add one-line install script for macOS and Linux

Detects os/arch, resolves latest (or pre-)release, verifies sha256,
and installs the binary into $HOME/.sanderling/bin.

* docs: use the one-line installer in getting-started

Replaces the broken `<version>` placeholder snippets with the
install.sh one-liner.

* docs: drop filler line under the install one-liner

* docs: rename index heading to Sanderling Manual

* docs(style): adopt JetBrains Mono and uppercase brand mark

* docs(getting-started): use justfile flow for folio sample

* docs(writing-specs): drop 'coming soon' notes for eventually and implies

* docs(inspect): rewrite layout for tabbed state panels and metrics chart

* docs(inspect): add UI screenshot

* docs: add Inspect to sidebar and index

* docs: restore mermaid bootstrap script in page template

* docs(style): constrain article images to content width

* docs(inspect): drop layout prose, keep what the screenshot doesn't show

* docs(architecture): add d2 source for architecture diagram

Replaces the in-page mermaid block with a d2-rendered SVG. Generated
outputs (svg/png) stay out of git; only the .d2 source is checked in.

* build(docs): render d2 diagrams into build/site/_assets/diagrams

* docs(architecture): swap mermaid block for rendered d2 svg

* ci(docs): install d2 before building the site

* docs(architecture): tighten layout and reroute label-crossing edges

Flip device/sidecar order so trace writer drops cleanly to runs/
without cutting through the JVM cell, right-align the inspect row
via a pad column, and tune grid gaps to keep gRPC and Unix socket
labels off the SANDERLING boundary.
This commit is contained in:
pj authored and GitHub committed 2026-04-21 15:05:00 +07:00
1 parent 8ccf95c1cf
commit 08288202cb
15 files changed
+250 -109

No files matched your search

+9 -19
View File
@@ -7,7 +7,7 @@ title: Writing specs
A spec has three parts: extractors, properties, and actions.
```ts
import { extract, always, actions, weighted, Tap, taps, swipes } from "@sanderling/spec";
import { extract, always, now, actions, weighted, Tap, taps, swipes } from "@sanderling/spec";
// 1. Extractors pull values from each observed state.
const loggedIn = extract((s) => !!s.ax.find("id:home-tab-bar"));
@@ -105,39 +105,29 @@ Session state (tokens, keychain, prefs) persists through the rest of the run. If
## Pattern: conditional properties
Use gating extractors the same way inside properties. Express "only check X when Y holds":
Use gating extractors the same way inside properties. Express "only check X when Y holds" with `now(...).implies(...)`:
```ts
const loggedIn = extract((s) => !!s.ax.find("id:home-tab-bar"));
export const properties = {
cartPersistsWhenLoggedIn: always(() => {
if (!loggedIn.current) return true;
return state.snapshots.cart_count !== undefined;
}),
cartPersistsWhenLoggedIn: always(
now(() => loggedIn.current).implies(now(() => cartCount.current !== undefined)),
),
};
```
When `implies` ships in v0.1.0, this becomes:
`implies`, `and`, `or`, and `not` are methods on any formula. Combine them freely.
```ts
cartPersistsWhenLoggedIn: always(() =>
implies(loggedIn.current, () => cartCount.current !== undefined)
),
```
## Pattern: eventually (once the operator lands)
## Pattern: eventually
`always` asserts something holds at every step. `eventually` asserts it holds at some step, usually with a time bound:
```ts
// v0.1.0+
loginSucceedsWithin30s: eventually(
() => loggedIn.current
).within(30, "seconds"),
loginSucceedsWithin30s: eventually(() => loggedIn.current).within(30, "seconds"),
```
Useful for liveness checks: the loading spinner eventually goes away, the deep link eventually lands on `/home`.
`within` takes `"milliseconds"`, `"seconds"`, or `"steps"`. Useful for liveness checks: the loading spinner eventually goes away, the deep link eventually lands on `/home`.
## Pattern: snapshot-backed properties