Node is pinned in .node-version (the supported minimum) and pnpm in package.json.
Tool dependencies have exact versions; pnpm-lock.yaml is committed. CI tests
only that minimum Node version; newer versions are expected to work but are not
tested.
pnpm install --frozen-lockfile
pnpm exec playwright install chromium webkit
pnpm build
pnpm format:check
pnpm lint
pnpm typecheck
pnpm check:docs
pnpm test
pnpm test:publish
pnpm test:consumers
pnpm test:runtime
pnpm test:todo
pnpm test:ui
pnpm checkpnpm check runs format, lint, docs, typecheck, unit, publish, consumer, runtime,
TODO and UI checks in that order; pnpm check:base is the same without the UI
checks. pnpm build:examples bundles the examples for
manual runs; it is not part of pnpm check, because typecheck already compiles
them.
Linux CI runs the same checks in parallel jobs: pnpm check:base with Chromium,
and pnpm test:ui --lanes=3 once each in Chromium, WebKit and Firefox.
--lanes=<n> (default 1) runs a browser's suites in n lanes side by side,
longest first, each lane against its own loopback Pod and browser instance;
locally, pnpm test:ui --lanes=3 shortens the run too. The required
status check Packages and consumers passes only when all of them do. They run
for pull requests, for pushes to main and for merge-queue groups; the DCO check
runs for pull requests and is skipped in a merge group, whose commits it has
already checked on the pull request. These
jobs run in the official Playwright image of the pinned Playwright version
instead of installing browsers through apt. A Playwright bump must update that
image in .github/workflows/check.yml too, and a CI step fails while the two
differ. In the UI gate, a check that does not settle within 120s fails under its
own name, and so does a suite that does not end within 6 minutes. The
release workflow runs pnpm check in one job. CI reads .node-version; libraries emit ESM plus declarations with plain
tsc -b project references. Exports resolve built files, with no source aliases.
Tests are typechecked too. skipLibCheck is false throughout.
-
format:checkandlint: Prettier and ESLint over packages, scripts, tests and examples. -
test:publish: runsscripts/publish-packages.mjsagainst a fake npm registry (fresh, resumed, conflicting and failing releases); nothing is sent to npm. -
check:docs: offline local Markdown file/heading validation, including agent and skill files, plus reachability from README and AGENTS. Regression fixtures prove failures for missing targets/anchors and isolated documents, valid unstaged moves, and package README links staying within the package or matching its release revision. See documentation strategy for deliberately separate checks and limits. -
build: strict library compilation, explicit.jsESM imports and a one-way app-sdk → client-sdk dependency. Test sources are not part of library output. It also writes app-sdk's app-author reference (scripts/package-docs.mjs): the AI entry and the guides and examples it links, without SDK contributor instructions, with links to anything not shipped pinned to the release tag.check:docsruns its fixtures, including a missing entry, a missing linked document, a broken anchor, a link leaving the package and shipped contributor instructions. -
typecheck: portable client source in Node-only and DOM-only environments, plus unit test sources and example sources. Browser policy options remain in the transport type even when Node's RequestInit declaration lacks them. -
test: retained catalogue/discovery validation cases (including real loopback HTTP), locale/date formatting and React draft preservation. These are fixture tests, not live Kotlin interoperability evidence. Runtime scenarios also cover durable storage, callbacks, scope/identity continuity, refresh (including renewal before expiry and the one resend after a lost answer: online, offline within and beyond the grace period, a page left mid-refresh, a resend refused or lost too), a discovery that never settles (beside a healthy Pod, a late answer after the deadline or a sign-out, explicit retry, other connections' actions meanwhile), target races and remembered Pods (sign-out and session end across a reload,forget,rememberPods: false, 0.7 records). -
test:consumers: packs client-sdk and app-sdk and installs their tarballs together in fresh directories outside the workspace. Checks packed file allowlists and rewritten workspace dependency, rejects linked workspace packages, and verifies that the plain installation contains neither React nor its types. The installed app-sdk reference is checked on its own: entry present, no contributor instructions, every local link and anchor inside the package. -
Packed client root: a separate root-only browser bundle retains every export with tree-shaking disabled. Its import graph excludes oauth4webapi, React, app-sdk and client OAuth/session entry paths. Importing that bundle in Node with traps checks for calls to
fetchand access towindow,document,navigator,localStorage,sessionStorage,indexedDB,location,history,XMLHttpRequest,WebSocketandEventSource. Caught accesses also fail the probe. OAuth remains an installed dependency used by the separate./oauthentry. -
Packed Node: NodeNext, no DOM lib, strict declaration checking, actual execution; discovery, Pod SELECT/CONSTRUCT and a bearer read plus conditional writes hit a loopback HTTP fixture. A separate packed type check disables
noUncheckedIndexedAccessand still requires a guard for absent SELECT bindings; all portable client README examples are compiled verbatim. Portable did:web authorization preparation needs no browser session fields. Import starts no requests. -
Packed browser: DOM only, no Node globals, esbuild browser bundle and Chromium execution; real loopback discovery, Pod SELECT/CONSTRUCT, a bearer read and a conditional write; verifies ambient cookies are omitted and the bearer reaches only data requests.
-
Packed React: separately installs React/ReactDOM and their types, compiles and renders a provider/hook consumer in Chromium; language change retains the draft. Both bundles resolve installed artifacts, not workspace aliases.
-
Documented apps: compiles the quickstart and its PWA adaptation, read from the installed app-sdk reference, against packed SDKs, and the React guide's custom sharing action. Chromium checks startup and, with a registration spy, verifies that importing the PWA
Appcomponent registers no worker while the production entry registers exactly once. Native worker behavior is covered bytest:todo. -
test:ui: the browser gate of@sempods/app-ui(scripts/test-ui-consumer.mjs). It packs client-sdk, app-sdk and app-ui, checks the app-ui tarball's files and its packed peer range (the same minor as app-sdk), installs them outside the workspace, compiles the reference screen intests/ui-browserstrictly against the packed declarations (React Aria's included,skipLibCheckoff). Its task dialog and its address model are the installed README'stask-dialog.tsxandplaces.tsexamples as shipped, so every check below runs the documented recipe; its compact quick edit is the README'squick-edit.tsx, its view links on?screen=tabsthe README'sview-tabs.tsx, its confirmation on?screen=confirmthe README'sconfirm-dialog.tsx; the screen routes with the package'suseNavand uses the README's stylesheet setup. The README's other TSX examples are compiled. It is built with Vite and Tailwind CSS 4. The app's CSS has no@sourceline and its Vite config nooptimizeDepshint; the build must contain classes that only the package's JavaScript uses. A loopback fixture Pod (scripts/ui-pod.mjs) serves the build. Each browser runs against its own Pod, side by side: Chromium and WebKit, plus Firefox on Linux (--browsers=overrides;--keepleaves the build and a Pod running). The checks (scripts/ui-checks.mjs, ported from the template's spike #120):- the interop gate: Escape in a dirty field, in the SDK's leave and delete confirmations, on Close and in the heading menu and date chooser; Close then Cancel (question on top, centred, Tab kept); focus trap with the page behind inert; focus restored to the opener; Save after a cancelled close; closing the dialog, a menu and the date chooser right after opening; 1280 → 375 → 1280px with a draft; Back and Forward, and Back with a dirty draft, staying and discarding;
- the compact
Dialogaround an SDK editor: Close, then Cancel or Escape in the SDK's question, and Cancel in its delete question, keep the dialog and the draft; a press beside it asks, and discarding closes it unsaved; an unreadable source Context shows its problem instead of an editor; its close button is named in German; its corner Close is a 44px target around a 16px glyph, inside the dialog and clear of its title and fields, at 375px and 1280px in light and dark, and closes it by pointer anywhere in the target and by keyboard; - a short confirmation (#368), the README's and one with
ActionButtonpills, labelled "Abbrechen" and "Gekaufte Artikel löschen" around a long unbroken list name, at 1280, 375 and 320px (1280px at 400% zoom) in light and dark: the dialog, its footer and every line of text inside the screen and the dialog, no sideways scroll, room for the focus rings, 44px targets (56px pills), Cancel before the answer and, for the README's buttons, side by side at 1280px; Tab reaches Cancel, then the answer, which Enter gives; ScreenDialogfull screen with safe-area insets, emulated through the DevTools protocol in Chromium only (other engines report a skip): Close below a 47px top inset, the last action after scrolling above a 34px bottom inset, heading, Close and fields beside 44px landscape side insets; the ordinary phone padding without insets in every engine, and the centred dialog unmoved by insets; and, in every engine, a keyboard opening over a typed draft, as a shrinking viewport: 915px wide from 340 to 150px high and 375px wide from 700 to 260px, the dialog full screen before and after, the field still focused, holding its draft and not under the heading, the last action reachable (#314);- the calendar-date roundtrip with the SDK's
datefield in Europe/Berlin, UTC+14 and UTC−11: storedxsd:dateafter Apply and Save, nothing written after a cancelled chooser or edit, a zonedxsd:dateTimekept until a day is applied; - keyboard use of the header menu and the calendar; focus back on the menu button after Pods & sharing, opened from the menu, closes by Escape or by Close once the menu has gone, with its ring after Escape (also after a Tab inside) and none after Close; a decorative leading icon in the menu that leaves the label as the item's name and typeahead, with all labels in one column, also right to left in an Arabic browser locale, and 44px rows; menu focus styles by input modality in light, dark and forced colors (a hovered row filled without a ring and neutral over the separator, no ring on the button after a pointer dismissal, one solid outline inside the row and around the button after Escape); 44px calendar targets at 375 × 812 and 375 × 560 with Apply and Remove date visible as the chooser opens, German texts and locale, removing an optional date; filter chips by keyboard at 375px (one Tab stop, arrows, Space, filled and marked when chosen, 44px, no overflow); the action group at 375 and 1280px; and, on a page taller than the screen with a scrollbar that takes width, the routed screen and the SDK's Pods & sharing sheet inside the visible width (#216). An engine without such a scrollbar (headless Chromium hides it) reports that check as skipped, and the summary counts skips apart from passes;
- the cascade: package classes win over the SDK's element rules inside an SDK editor, and the token bridge reaches the SDK's own controls;
- the packed theme checker on the default and fresh palettes across all six action combinations in both schemes, including rest and hover parity with the reference buttons and controls with known failing roles;
- rendered contrast (
scripts/ui-contrast.js): 19 controls that must pass or fail as stated, then seven states × two palettes with every action and secondary variant × light and dark × 375 and 1280px, including hovered, pressed and focused controls; the List state measures the filter chips, the Tabs state both view links. Each of these loads its own state, so four signed-in pages measure them side by side; - the routing matrix of the template's routing spike (#114), 29 checks with
the package's router: a resource link, one with a named source Context and
an invalid legacy link keep their address through sign-in; direct entry,
plain and Ctrl/Cmd clicks on links, the action route and the menu route;
Close to the in-app opener, or in place to the start after a direct entry;
Back with a dirty draft, staying and discarding, and clean Back and
Forward; Forward and a second Back while the SDK's question is open, kept
and discarded;
history.go(±2); reload, then Back and Forward; legacy links become canonical by replacement while invalid ones keep their error page; the creation route wins over the resource pattern; unknown and invalid addresses show explicit pages; links name the source Context, a named source is read and written (the other Context's copy stays) also on the action route and after reload, and an unreadable one is an explicit error without an editor. Five more checks from the reviews of #208: an address with a source opens right after sign-in without a Context choice, and an unreadable source shows its error there too; after a fragment link's entry, staying after two entries back returns to the task screen and Close still returns to the opener, also after a replaced fragment; and a path with two leading slashes shows the not-found page; - views as links (#342, #343):
nav.linkmarks the link to the shown view witharia-current="page"after a click and Back, a task's screen over a view marks neither view's link, and the current ghost link keeps the other link's text colour on a surface of its own with an underline, rest and hovered, apart from the other link hovered, on both palettes in all six action combinations, light and dark.
Sizes and contrast are measured with reduced motion, so a zoom or fade that headless WebKit on Linux stretches over seconds cannot catch an overlay halfway; the behaviour checks keep the animations, and one check proves that reduced motion turns them off. WebKit on macOS moves the focus with Option+Tab, as Safari does by default for buttons. These are fixture checks in browser engines, not evidence from a real Pod, iOS, an installed PWA or people.
-
test:runtime: a separate packed DOM-only consumer in Chromium, using native IndexedDB/Web Locks and real loopback Code + PKCE redirects/exchanges. Checks dynamic/did:web identity, durable reload, sequential multi-Pod, reactive refresh, second-tab exclusion and cookie omission. Uses the production client by default, including one/set/free Pod restrictions, excluded saved sessions and callbacks, and restoring preserved sessions after widening the policy. Also covers editor composition, conditional saves, conflicts and an applied write whose answer is withheld at the test network boundary (no SDK resend). A Pod issuing four-second tokens refuses expired ones with and without a Bearer challenge; the overview recipe renews expired tokens before dispatch, so the Pod never receives one, and a refused renewal ends in a visible sign-in that recovers. Renewal within the margin before expiry is covered by unit tests.
The consumer harness uses npm to install exact SDK tarballs and exact direct test versions; normal workspace development uses pinned pnpm. Consumer directories are removed after the run. Installing tools may use the registry; runtime fixtures and page traffic stay on loopback. Chromium is the automated browser target; see the support matrix for the public support scope. Live Kotlin validation and independent human authoring remain follow-up work. The runnable TODO/Node examples and React authoring layer are described in React/headless authoring.
React editor-lifetime regressions combine useSelection with
useResourceEditor: after an actual screen unmount/remount, reopening the same
subject keeps its draft or unconfirmed outcome. Other row/Context changes and
unrelated guards still ask, pending writes block navigation, old commands cannot
follow a replacement target, and recovery never replays the write.
The packed customized consumer also unmounts a dirty editor screen, opens the
same row after remount and checks the retained draft without a prompt or write.
test:todo installs packed SDKs and the packed UI kit, plus the TODO
example's own registry packages (such as the public RDF recipe's parsers),
compiles the actual examples and builds the TODO stylesheet with Tailwind CSS 4
against the installed kit; the React consumer of test:consumers installs the
same packages for the shipped examples. The TODO's standard screen covers EN/DE sign-in,
320px light/dark presentation, explicit context choice, creation and guarded
management with a retained draft, and the full CRUD, conflict/unknown-outcome,
guard, keyboard/mobile and second-tab checks, plus the shared Node domain/edit
path.
It also enables native BFCache in full Chromium and checks repeated returns,
sign-in afterwards, saved session/Context restoration and exactly one creation
after return. The verbatim quickstart from the installed package is bundled and
checked for an explained network read failure, explicit retry and recovered data.
An empty result stays visible during a held background refresh, while initial
read and refresh failures show recovery instead of an empty-state message.
It also loses the answer to an applied row update, removes that row on the
fixture, refreshes the list and checks that comparison/acknowledgement remain
reachable without another write.
The remaining browser scenarios keep their isolated Headless Shell setup.
test:todo also checks the standard screen, editor and recovery controls without an app
stylesheet at 320/375px in EN/DE and light/dark, including host-controlled color schemes, transparent embedded surfaces, inherited token overrides,
44px targets, keyboard focus, and isolation from app-owned list styling.
test:runtime also covers packed AppAccess one/set/free Pod choices, keyboard
sign-in and focus recovery, a provider answering login_required (specific EN/DE
cause without the provider's text, cleared by selecting another Pod or
disconnecting), and the widget host with retained drafts/uncertain
writes. EN/DE retry cases check native inert: failed re-authorization preparation
keeps retry/error feedback visible without moving focus to the host control.
With one permitted Pod and Contexts on demand, slow discovery keeps AppAccess
in its loading state (after the callback and during restore) until it hides; an
ended session or missing required scopes show their recovery view at once. When
the Context catalogue is slow (in 'required' mode, or on demand under a mounted
TargetScreen), only the loading state shows: it hides if a preset Context
settles the target, otherwise the Context chooser or the catalogue failure view
appears. These are Chromium fixture checks, not live-Pod or installed-PWA
evidence. See browser runtime for the implemented API and
its limits.
No implementation or test command publishes packages; the three packages are publishable, the workspace root and examples stay private, and a version tag runs the publish workflow. Preserve per-package PROVENANCE.md.
Runtime Pod-reader regressions cover catalogue-free direct binding/SELECT/CONSTRUCT,
independent read revisions through Context changes, session/grant invalidation,
required scopes, policy, refusal and cancellation. Selected-label fixtures cover
catalogues of 1, 50, 51 and 10,000 entries, restoration, cache/coalescing and stale
responses, including manage-only grants/revocations for cached, failed and pending
label attempts while Pod reads remain valid. Packed React-free declarations include BoundPod and AppSnapshot.pod;
the Chromium runtime consumer verifies bound SELECT/CONSTRUCT with no dataset
parameters and no accompanying catalogue requests. These are client/runtime
fixture checks; scale evidence against a local reference server is recorded in
#40.
React/headless on-demand regressions cover catalogue/description-free startup,
restore, reads and recovery (including preset/remembered targets and saved Pods),
StrictMode/concurrent Context demand before/after login, explicit retry after
empty/failed discovery, label fallback and obsolete Pod results. Packed consumer
types preserve Context/Pod callback inference, including explicit result generics
and rejection of mismatched handles. test:runtime executes the copyable
Pod-overview recipe against installed archives in Chromium: native storage/PKCE,
catalogue-free overview restore and 401 recovery, later validated Context demand,
draft-preserving revalidation, and editing an overview row in its own Context
(fresh read, If-Match write). These fixtures do not establish server dataset
semantics or deployed scale.
Scale fixtures (packages/app-sdk/src/runtime/pod-scale.test.ts) assert request
counts for Pod reads at catalogues of 1, 101 and 20,001 Contexts. Each read is one
query, and no catalogue or description is requested without Context demand. This
holds through restore, 401 renewal, 403 refusal, Context switches and
on-demand startup with a preset Context, while required mode loads one catalogue
and one selected description. SEMPODS_SCALE_TIMING=1 (with --silent=false)
reports the in-process load time of the complete broad catalogue. The fixtures
prove client request behaviour, not backend scale.
scripts/measure-pod-reads.mjs records live Pod-read evidence through the built
client:
- Run
pnpm buildfirst. POD_READ_CREDENTIALSnames a local JSON file of sempods service-client credentials. Never commit that file.- The script sends client secrets only to the Pod's own token endpoint, and rejects redirects.
- Options:
--clients,--runs,--warmup,--timeout,--catalogue. - Raw evidence goes to the git-ignored
test-results/pod-reads/.
The script is not part of pnpm check. Follow live validation
for the Pod and data it runs against;
#52 tracks evidence on
a deployed Pod and in a browser.
Pod/label regressions and the packed Chromium runtime also run with
AbortSignal.any unavailable. Signal tests verify cancellation propagation and
listener cleanup, and controller regressions keep unexpected binding defects
visible. Removing an API in Chromium is compatibility regression evidence, not
a test on an older Safari/iOS device.
These notes back the React/headless authoring guide; they are fixture evidence, not live Kotlin compatibility or independent usability evidence.
pnpm test:todoinstalls packed SDKs and the UI kit outside the workspace, typechecks and bundles both examples, and drives the standard screen through real loopback PKCE redirects, CRUD, conflict and unknown outcomes, guarded selection, EN/DE, keyboard, mobile width and a busy second tab. It also runs the Node CRUD loop. Unit and React tests cover access and draft preservation, lifecycle and cancellation.- React tests run the guide's several-resources-from-one-input handler against fixtures, including a target change during a creation; keep the test and the guide in step.
- The packed browser test runs the overview recipe with installed archives, including an edit beside a creation draft in another Context. Evidence on a deployed Pod and in a real browser is tracked in #52.
- TODO and Node share portable field definitions, typed lists, captured creation commands and partial changes. Live Pod evidence belongs to the quickstart validation; the provisional Action profile does not settle the outstanding task-vocabulary or mixed-Action collection decisions.