cloudlands-fe
AGENTS.md9 starsChanged 2 days agoApache-2.0View on GitHub
Quick routing guide for AI agents. Start here, then open the smallest relevant doc. Assistant app guide: a user-facing change updates the affected section of packages/intentd/crates/intent-services/resources/assistant-app-guide.md in the same change, coordinating the companion intentd change (also from standalone frontend checkouts; companion merges need not be simultaneous). Do not promote unfinished, Labs-only or unreleased features as normal options. Before opening a PR, record the affected guide section or explain why there is no user-help impact. Full rule: root AGENTS.md. Merge permission:…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- electronSkill
- pr-descriptionSkill
- redux-sagaSkill
- themisSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
50 rules. About 0 are common, 23 are distinctive, and 27 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈23
Distinctive · estimate
This author's own choices. Worth a look.
27
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
Use pnpm, not npm; create agents via agentFactory.createAgent().
- Distinctive: line 30
Start with the “I need to…” decision tree, not raw markup.
- Distinctive: line 31
Use the generated pattern cheatsheet for imports and API summaries.
- Very specific: line 33
Use public $lib/components/patterns/* or $lib/components/ui/* subpaths.
- Very specific: line 34
Follow the Never list, enforced by eslint-rules/design-system/.
- Very specific: line 35
Never hand-write motion durations or physical colors.
- Distinctive: line 36
Never pause, stop, or disable animations app-wide on your own (window blur, battery, visibility, performance).
- Distinctive: line 40
Never add a raw control, direct toast/native dialog, bespoke settings row, or feature-owned dialog root.
- Very specific: line 45
Run pnpm run lint:design-cheatsheet (part of pnpm run lint) with the focused lint/tests.
- Very specific: line 100
Put renderer product work in src/features/.
- Very specific: line 101
Keep shared app state in src/store/renderer/, not ad-hoc component state.
- Distinctive: line 115
All user-facing strings (labels, aria-labels, placeholders, tooltips, toasts, errors, menu items) go through Paraglide message functions — …
- Very specific: line 117
Messages: call m.*() (import from src/shared/paraglide/messages.js).
- Very specific: line 120
Dates/numbers: only via $lib/i18n/format (renderer) or src/shared/i18n/formatters.ts (main/shared) — never ad-hoc toLocaleString, direct …
- Very specific: line 166
Use dev:ui for component-only work.
- Distinctive: line 176
Use these exact state names in direct URLs:
- Very specific: line 180
Add theme=system|light|dark, an integer width=240..1600, and motion=full|reduced.
- Distinctive: line 194
Use before/after geometry probes when they help explain a layout change, and include the useful evidence in the task report:
- Very specific: line 226
Follow the root Observe and Prove steps with a fixed viewport.
- Very specific: line 231
Prefer sandbox:shot, verify the resulting PNG, save it with ws.note.saveAsset, and embed the returned workspace asset URL in chat or a note.
- Very specific: line 234
If the command cannot reach the preview, use an owned hidden embedded-browser tab as the fallback.
- Very specific: line 251
Before linking any generated image or video, verify that the actual file exists in the message's owning workspace.
- Very specific: line 278
Start with the monorepo root Developing on a remote host loop.
- Very specific: line 311
When the change touches Electron main/preload/native/sidecar, Loop A cannot see it — run the dev Electron FE on a machine with a display …
- Distinctive: line 367
Test behavior shipped in a prior release, including its requested feed filenames and architecture selection.
- Very specific: line 369
Keep these regression tests in required verification.
- Distinctive: line 373
If a compatibility break is unavoidable, identify the exact affected installations and obtain explicit human authorization for that break.
- Very specific: line 379
Use pnpm run verify:changed -- <paths...> during local work.
- Very specific: line 425
Do not write protocol version numbers in src/ (v10.1, or 10.1 on a line mentioning protocol/intentd/daemon).
- Very specific: line 429
Never hand-edit src/preload/index.ts.
- Very specific: line 441
Before every push, and after any structural change, run pnpm run verify:static (a few minutes.
- Distinctive: line 458
Keep business/domain logic out of the renderer.
- Distinctive: line 476
When pairing broke, the FE selector was corrected to match the contract — the BE was not coerced into emitting a renamed field.
- Distinctive: line 495
Single-flight: all triggers share one in-flight promise — never start a second concurrent refetch of the same data.
- Very specific: line 502
Do not fan out per-workspace daemon RPC loops from an event handler — e.g.
- Distinctive: line 549
Do not assert literal source, class, or markup spelling, source order, exact copy, or unconditional visual presence.
- Distinctive: line 551
Do not stub or assign dimensions, values, or state and then assert those same inputs.
- Distinctive: line 553
Do not duplicate production values in a fixture and test only that duplicate.
- Distinctive: line 568
Delete tooltip-only cases, suites, snapshots, and orphan test fixtures/helpers.
- Distinctive: line 587
Delete checked-in violations.
- Distinctive: line 603
Do not hide these checks in helpers, custom matchers, canvas redraws, or renamed "visual" tests.
- Distinctive: line 639
Keep real-browser checks for clipping or overlap that hides content or controls, scroll ownership/anchoring, focus and keyboard access, …
- Distinctive: line 663
Remove violations; never record new measurements or adjust expected values to pass.
- Distinctive: line 665
Do not recreate these tests under another name, add exemptions, or regenerate their baselines.
- Distinctive: line 670
Keep independent behavioral assertions: content stays within its live container, controls remain reachable, and scrolling preserves the …
- Very specific: line 725
Before an outside click that should dismiss a bits-ui menu, popover, select, combobox or dialog, call expectDismissibleLayerArmed(layer) …
- Very specific: line 741
Wait for motion, never a fixed page.waitForTimeout: Playwright hit-tests only pointerdown, so a target still moving at mouseup loses the …
- Very specific: line 762
Do not use clock stepping to check animation choreography.
- Distinctive: line 786
Every feature and every bug fix that touches the wire MUST ship with tests that:
- Very specific: line 808
Run the targeted suite with pnpm vitest run <files> (see Verification above) before opening a PR.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agents
Quick routing guide for AI agents. Start here, then open the smallest relevant doc.
Assistant app guide: a user-facing change updates the affected section of
packages/intentd/crates/intent-services/resources/assistant-app-guide.md
in the same change, coordinating the companion intentd change (also from standalone
frontend checkouts; companion merges need not be simultaneous). Do not promote unfinished,
Labs-only or unreleased features as normal options. Before opening a PR, record the
affected guide section or explain why there is no user-help impact. Full rule:
root AGENTS.md.
Merge permission: never merge a PR or arm auto-merge without explicit permission from a human — approved + green is not enough. See the monorepo root
AGENTS.mdfor the full rule.
Tech stack
- Electron + SvelteKit + TypeScript desktop app
- Svelte 5 runes for UI rendering only; ALL shared/domain state MUST use Redux + sagas
- Svelte stores (
*.store.svelte.ts) are DEPRECATED — every one is a migration target. Do not create, expand or entrench them (including new reads of an existing one); ephemeral component-local UI state is fine without Redux. Move toward removal with the Migration Guide andSTATE_MANAGEMENT.md. - Use
pnpm, notnpm; create agents viaagentFactory.createAgent().
UI rules
- Start with the “I need to…” decision tree, not raw markup.
- Use the generated pattern cheatsheet for imports and API summaries.
- Inspect live fixtures and copyable compositions at
/sandboxand/sandbox/recipesviapnpm run dev:ui. - Use public
$lib/components/patterns/*or$lib/components/ui/*subpaths; do not deep-import implementations. - Follow the Never list, enforced by
eslint-rules/design-system/. - Never hand-write motion durations or physical colors; use
$lib/motionand semantic tokens. - Never pause, stop, or disable animations app-wide on your own (window blur, battery, visibility,
performance). Gate it behind an existing setting — OS reduced motion and "Reduce motion on
battery" via
prefersReducedMotion()/data-reduce-motion, or "Pause animations when not in focus" viadata-window-blurred— or add a new Appearance setting that defaults to off. - Never add a raw control, direct toast/native dialog, bespoke settings row, or feature-owned dialog root.
- Popover menus hold short labels, not prose. Never add sentences that explain options, instructions, or captions under items; if an option needs explaining, rename it or move the explanation out of the menu.
- Ratchets only shrink: do not raise
scripts/ui-component-guardrails.tsceilings or expand lint baselines. - Run
pnpm run lint:design-cheatsheet(part ofpnpm run lint) with the focused lint/tests; regenerate the cheatsheet withpnpm exec tsx scripts/generate-design-cheatsheet.ts.
Project layout
src/
├── shared/ # Cross-process utilities (main + renderer)
├── lib/ # Renderer-only shared utilities & components
├── main/ # Main-process code & utilities
├── preload/ # Electron preload scripts
├── features/ # Feature-first renderer modules
│ └── <name>/
│ ├── utils/ # Feature-local utilities
│ └── main/ # Feature's main-process code
├── routes/ # SvelteKit pages
└── test/Where to look
FE docs live in the monorepo's docs/fe/ — the ../../docs/fe/ paths below resolve
in a monorepo checkout, where this repo mounts at packages/cloudlands-fe/.
| Working on… | Open |
| agents | ../../docs/fe/agent-message-dedup-and-stream-sagas.md, ../../docs/fe/RULES_SYSTEM.md |
agent.list requests (unbounded on a large workspace) | pnpm run lint:agent-list-scope — scripts/check-agent-list-scope.mjs fails any non-test agent.list request (wire literal, agents.list / listWithMeta, saga call / tuple) without retiredOnly: true or a scope literal / variable (false, undefined, '' and words inside strings do not bound it); the file-level ALLOWLIST in the script needs a one-line reason and stale entries fail; CI runs it via lint:architecture (intent-hq/intent#5531) |
| state/store | ../../docs/fe/STATE_MANAGEMENT.md, src/store/renderer/docs/ |
| chat row shows sent before confirmed (or flips back to the queue) | Three sources draw it: pending conversation submissions and processing rows (src/store/renderer/slices/pending-submissions/pending-submissions-projection.ts) and predicted queue drains (src/lib/components/chat/queue-drain-prediction.ts); pendingConversationMessages in src/lib/components/chat/ChatPanel.svelte merges them (cloudlands-fe#4312) |
| component design | ../../docs/fe/COMPONENTS_DESIGN.md |
| UI invariant gates | pnpm run test:ui-invariants — ratchets + catalog *.meta.ts ledgers, see below |
Electron test helpers (test/electron*.ts, test/fixtures/**/*.ts) | pnpm run lint:electron-test-paths (in lint:architecture) — tsconfig.electron-tests.json type-checks them and scripts/check-electron-test-paths.mjs checks their src/ path strings and Vite resolveId stubs; they otherwise run only in the merge queue (cloudlands-fe#4050) |
root spec virtual-module stubs (test/**/*.spec.ts) | pnpm run lint:root-spec-stubs (in lint:architecture) — scripts/check-root-spec-stubs.mjs fails a stub that no longer exports a name the mounted component graph imports, or that nothing imports; root specs otherwise run only nightly (intent-hq/intent#9311) |
| adding a ratcheted lint rule | eslint-rules/lib/baseline-ratchet.js — lintRuleFromRepoConfig derives scope from eslint.config.js (same rule entries and global ignores as pnpm lint); the baseline is one entry file per tolerated source file, eslint-rules/baselines/<rule>/<source path>.json (loadBaseline), so parallel debt-reduction PRs delete disjoint files instead of conflicting on one document; per-file counts only shrink vs LINT_BASELINE_BASE_REF (CI sets it to the PR / queue base; falls back to HEAD) |
| deps freshness | pnpm run deps:check — gates refuse to run on a stale node_modules install |
| Node version | pnpm install and gates refuse to run on a Node outside engines.node (the one range) |
| panels/layout | ../../docs/fe/panel-system-refactoring.md, ../../docs/fe/PANEL_TAB_UX_SPEC.md |
| PR descriptions | .agents/skills/pr-description/SKILL.md |
| browser/CDP | ../../docs/fe/BROWSER_PANEL_SPEC.md, ../../docs/fe/CDP_MCP_TOOLS.md |
browser tab contract (ws.browser.* actions, errorCode, displayed) | src/features/browser/main/browser-action-executor.ts, embedded-browser-cdp-service.ts, the browser-tab-registry saga, src/shared/types/browser-clients.ts (BrowserTabInput / BrowserTab own the displayed wire field) — change together with intentd crates/intent-acp/src/mcp_server/bindings/browser_docs/*.md (the ws.browser.docs text) and ../../docs/protocol/methods/files-terminal-browser.md; monorepo make docs-check cross-checks the shared tokens |
| module boundaries | ../../docs/fe/MODULE_BOUNDARY_GUIDE.md |
| motion perf traces | pnpm perf:chat-motion — ../../docs/fe/DEVELOPER_GUIDE.md#chat-motion-performance-traces |
| alignment / text-rebase perf claims | pnpm perf:text-rebase --base <ref> — paired head/base runs of src/lib/notes/text-rebase-bench.runner.ts in fresh processes, interleaved with the pair order alternating per run so drift hits both sides (--head <ref>, --runs, --repeats, --shapes, --json); cite its table in the PR. Bare packages resolve from the current node_modules for both trees; the header labels each tree's mapper mode and warns when a pre-#2740 base (legacy-two-mapper) is not comparable like-for-like |
| debugging | ../../docs/fe/TROUBLESHOOTING_GUIDE.md, ../../docs/fe/IPC_DEBUG_GUIDE.md |
| prod stack traces | pnpm resolve-stack <tag> < stack.txt — rebuilds the tag with sourcemaps, maps frames |
| CT run failures (nightly triage) | pnpm ct:failures <run-id | run-url> — every failed/flaky CT case of a Nightly Browser Tests run (or an older Intent PR Checks run), per shard, from the shard's JSON report artifact (list-log summary fallback); --attempt N, --json |
| full local CT run (all shards) | pnpm run test:ct:full — the four CT shards in sequence via test:ct (CI's @quarantine filter, one ct-<CT_PORT> lock); per-shard log, JSON, HTML and traces in ct-full-runs/<stamp>/shard-<i>/, then one line per shard, failed/flaky cases, a total and summary.json; every shard runs, exit 0 only if all pass. About 2h15m (shards 25-40 min): give a monitor a 3h+ TTL. -- --list checks wiring |
| error handling | ../../docs/fe/ERROR_HANDLING_SYSTEM.md |
| TypeScript/types | ../../docs/fe/TYPE_SYSTEM_GUIDE.md |
| events/IPC | ../../docs/fe/EVENT_SYSTEM.md |
| keybindings | ../../docs/fe/KEYBINDINGS.md |
| deploying/releasing | ../../docs/fe/DEPLOYING.md |
Key conventions
- Put renderer product work in
src/features/; shared utilities live insrc/lib/. - Keep shared app state in
src/store/renderer/, not ad-hoc component state. - Selector readables belong at component init only —
selector()uses Svelte context and must not run in event handlers or callbacks. Dispatch actions and perform one-time selector reads through the configured appStoreinstance, e.g.store.dispatch(action)andselector.select(store.state, ...args). See../../docs/fe/STATE_MANAGEMENT.mdfor details. - Never import from a feature's
main/subtree in renderer code (or vice-versa). - Don't export utility functions from orchestration modules — extract to a dedicated
utils/file. - Keep utilities dependency-light — no stores, services, or side effects.
- Never quote the literal breaking-change footer token — release-please treats
BREAKING CHANGE:/BREAKING-CHANGE:(andRelease-As:) anywhere in a commit body, including any branch commit folded into the squash body, as a real footer (this cut a false v3.0.0, intent-hq/intent#2988). Never write the literal token in commit messages, PR titles/bodies, or review comments unless a breaking change is intended; write "the breaking-change footer token" instead (rootAGENTS.md).
Internationalization (i18n)
All user-facing strings (labels, aria-labels, placeholders, tooltips, toasts, errors, menu items) go through Paraglide message functions — never hardcode them.
- Messages: call
m.*()(import fromsrc/shared/paraglide/messages.js); keys live inmessages/en.json. Key naming:{feature}_{component}_{purpose}, camelCase segments, role suffixes_label/_description/_placeholder/_ariaLabel/_tooltip/_error(e.g.settings_wsApi_port_invalid). - The compiled output (
src/shared/paraglide/) is gitignored —verify:changed,test:unit,lint:dead-code, andtest:ctregenerate it on demand when it is missing or stale; runpnpm run generate:i18nto rebuild it by hand after editingmessages/en.json. - Interpolation over concatenation: named params (
"Configure {name} path"); sentences split by inline markup use_before/_middle/_afterkey pairs; plurals as_one/_manykey pairs. Gotcha: literal{/}in a message parses as a parameter — rephrase such strings. - Dates/numbers: only via
$lib/i18n/format(renderer) orsrc/shared/i18n/formatters.ts(main/shared) — never ad-hoctoLocaleString, directdate-fnsformat calls, or string-built numbers/percentages. - Module-scope constants holding localized text use property getters (
get description() { return m.…() }) so strings re-evaluate on locale change; identifier-bearing fields stay literal. - Exemptions — log lines, wire/IPC constants, agent-generated content, brand names, file paths, URLs, shell commands — mark with
// i18n-ignore (reason)or<!-- i18n-ignore (reason) -->on the same line or the line above. - Enforcement:
scripts/check-hardcoded-strings.mjs(chained intopnpm run lint) blocks hardcoded strings insideENFORCED_DIRS. New features in enforced dirs must be string-free from day one; when you migrate a directory to messages, add it toENFORCED_DIRS. - Catalog completeness:
scripts/check-i18n-completeness.mjs(also chained intopnpm run lint) fails CI when any locale catalog diverges frommessages/en.json— missing keys, extra keys, per-key{param}placeholder mismatches, unpaired_one/_manyplurals — or whenmessages/*.jsonfiles and theproject.inlang/settings.jsonlocale registration disagree. It also flags non-base values byte-identical to the English value when they contain letters (letter-free values are auto-exempt): translate them, or record intentional invariants (brand names, placeholder-only strings, etc.) inscripts/i18n-equal-allowlist.json(per key,"*"or a locale array); stale allowlist entries fail the check. - Merging catalogs:
pnpm installregisters a key-level git merge driver formessages/*.json(scripts/i18n-json-merge.mjs), so keys appended on both branches merge cleanly; a key changed differently on both sides still conflicts. If a merge already conflicted (driver not registered), runpnpm run i18n:resolve. - Reference example:
src/lib/components/settings(the pilot extraction).
Common commands
corepack pnpm run dev:ui # Fast named-state UI preview
corepack pnpm run dev:web # Complete plain-browser renderer
corepack pnpm run dev # Standard Electron launcher
corepack pnpm run dev:cdp # Electron launcher with CDP support
corepack pnpm run build # Production build
corepack pnpm run check # Svelte + TypeScript checks
corepack pnpm run lint # ESLint + i18n string/completeness + package-script pnpm nesting + knip dead code + Prettier check
corepack pnpm run format # Prettier write pass
corepack pnpm run format:check # Prettier check (also runs inside `lint`)
corepack pnpm run test:unit # Vitest suite
corepack pnpm run test:playwright.git-blame-ignore-revs lists the repo-wide Prettier reformat commit so git blame skips it (GitHub honors it automatically; opt in locally with git config blame.ignoreRevsFile .git-blame-ignore-revs).
A test that budgets wall time (perf guards, alignment work bounds) must fit its timeout
under CI runner load, not just in isolation — the local 30 s testTimeout by default
(vitest.config.ts raises it to 60 s on CI, from scripts/vitest-timeouts.mjs) or the documented per-test budget; catalog contract entries derive theirs from their snapshot size (src/lib/component-catalog/catalog-contract-budget.ts).
Testing Library waits and vi.waitFor / vi.waitUntil default to half that budget
(src/test-setup.ts). intent/no-fixed-wait-timeout-in-tests (in pnpm run lint) flags a
fixed timeout on them, and a fixed per-test limit that would cut off such a wait, and
names the escape hatches; deliberate cases are baselined under
eslint-rules/baselines/no-fixed-wait-timeout-in-tests/.
intent/no-wall-clock-assertions-in-tests (in pnpm run lint) flags a raw
performance.now() / Date.now() elapsed-time assertion against a millisecond budget and
names the alternatives; today's offenders are baselined under
eslint-rules/baselines/no-wall-clock-assertions-in-tests/, and counts only shrink. Before
pushing such a test, run pnpm test:loaded <file or filter> [-- <extra vitest args>]: one
worker pinned to a single core (taskset, Linux only; unpinned on macOS) shared with three
busy loops, exiting with vitest's code. LOADED_CORE=<n> / LOADED_BUSY=<n> override the
core and loop count; CI is inherited from your shell, so the run uses the local 30 s
timeout unless you export CI yourself.
Fast UI preview loop
Use dev:ui for component-only work. It skips Electron, native helpers, the daemon,
and production application sagas. Use dev:web when the full browser renderer or a
client connection is required. Use dev:cdp for Electron main, preload, native,
window, or shell behavior.
For remote-host lifecycle, browser, evidence, and hand-off steps, follow the monorepo
root Developing on a remote host loop.
Choose make dev-sandbox-ui for this recipe. UI mode intentionally has no daemon bridge
or /__sandbox/health; wait for its component-ready marker instead.
Use these exact state names in direct URLs:
/sandbox/button?state=default,loading,disabled, ordestructive/sandbox/mention-agent-avatar?state=idle,waiting, orerror- Add
theme=system|light|dark, an integerwidth=240..1600, andmotion=full|reduced. Example:/sandbox/button?state=loading&theme=dark&width=420&motion=reduced.
On the sandbox page, use window.__INTENT_PREVIEW__.list() to find preview IDs,
await window.__INTENT_PREVIEW__.states('button') to find states, and
window.__INTENT_PREVIEW__.current() to inspect the active ready state. Wait for
[data-preview-ready=true] before capture. For a cold renderer launch, use the
self-checking readiness hook
instead of polling or rescheduling an expired hook.
Visual verification
For a component change that has a sandbox scene, capture and inspect a screenshot. Use before/after geometry probes when they help explain a layout change, and include the useful evidence in the task report:
pnpm sandbox:probe workspace-hover-card --state landscape-wide
pnpm sandbox:shot workspace-hover-card --state landscape-wideBoth commands require the scene as the first argument and --state <name>. They start
an in-process Vite server with INTENT_UI_PREVIEW=1 and INTENT_BUILD_TARGET=web, use
fit=component, and wait for both the ready and stable markers. To reuse a running
dev:ui server, pass its root URL with --base-url http://127.0.0.1:<DEV_PORT>.
Shared options (--theme, --width, --motion, --scale, --timeout, --out,
--allow-console-errors), font stability and the per-harness optimizer cache are in
Sandbox probe and shot options.
sandbox:shot captures the complete component frame without shell chrome or scrolling.
By default it writes
.demo-artifacts/sandbox/<scene>--<state>--<theme>--<width>.png and prints its path,
pixel dimensions, and URL. sandbox:probe prints stable JSON to stdout; pass
--selector <css> to measure custom descendants or --out
.demo-artifacts/sandbox/<name>.json to save it. .demo-artifacts/sandbox/ is
git-ignored; never commit these visual-review artifacts.
Probe output is manual review evidence, not a checked-in pixel baseline or an automated
pass/fail contract. Register sandbox scenes for visual review without blanket coordinate
or size snapshot tests. Add browser assertions only for the user-visible contracts in
Testing. See
../../docs/fe/DEVELOPER_GUIDE.md#fast-ui-preview-workflow for the manual preview loop.
Put a preview screenshot in user chat
Follow the root Observe and Prove steps with a fixed viewport. For this preview, require
[data-preview-ready=true] and confirm window.__INTENT_PREVIEW__.current() has the
expected state and status: 'ready' before capture. Keep the returned image block in the
user response; a local path alone does not display an image in chat.
Prefer sandbox:shot, verify the resulting PNG, save it with ws.note.saveAsset, and
embed the returned workspace asset URL in chat or a note.
If the command cannot reach the preview, use an owned hidden embedded-browser tab as
the fallback. Call ws.browser.listTabs first and reuse a matching tab; otherwise call
ws.browser.openTab with the preview URL under
http://daemon.localhost:<DEV_PORT>/. Wait no more than 15 seconds for
[data-preview-ready=true]. Confirm that
window.__INTENT_PREVIEW__.current() has the expected state and status: 'ready', then
call the browser screenshot action and keep its image block in the user response.
playwright-cli is typically absent on remote hosts; use it only as a local fallback if
the browser screenshot call reaches its 30-second limit. Do not retry the same stalled
browser call. In a new,
clean local session, set a fixed viewport, wait up to 15 seconds for the ready marker,
and write one PNG under .demo-artifacts/<timestamp>-<flow>/. Check that the PNG is
non-empty and has the expected dimensions, inspect it with an image-capable file
viewer, and close the clean session. Do not commit the media, load saved browser state,
or inspect cookies, credentials, or unrelated tabs.
Before linking any generated image or video, verify that the actual file exists in the
message's owning workspace. Embed 
or the exact URL returned by ws.note.saveAsset; absolute filesystem paths do not render
as workspace media. Never invent an artifacts/... path, substitute a similarly named
file, or read a sibling workspace. If the artifact is absent, report it as missing.
For focused browser validation, run:
corepack pnpm run test:ct -- src/features/agent/components/agent-avatar/__tests__/agent-avatar-waiting.ct.spec.tsWithout CT_PORT, each worktree gets its own CT port, hashed from its package path into
10100-14099 (CI keeps 3100); the run's waiting … for ct-<port> lock line names it. An
explicit CT_PORT always wins. A run holds
the host-wide ct-<port> lock, so a second run on the same port waits for the first
instead of reusing its server (see Verification). An explicit port also keys the generated bundle cache
(playwright/.cache-<CT_PORT>; bare playwright/.cache when unset), so per-port runs are
isolated for server, lock, and cache — including within one worktree. The run exits with Playwright's
status as soon as the tests finish — the HTML report is written to playwright-report/
but never served automatically. To browse it after the run, opt in from an interactive
terminal with CT_HTML_REPORT=open (or -- --open-report); node
scripts/run-ct-tests.mjs --help lists the options. The full workflow is in
../../docs/fe/DEVELOPER_GUIDE.md#fast-ui-preview-workflow.
Dogfooding a dev FE against a daemon
Start with the monorepo root
Developing on a remote host loop. It owns
the canonical status, sandbox lifecycle, health wait, browser, evidence, and hand-off
steps. The deeper implementation contract is in the
Remote Sandbox Internals.
Loop A — web build in an embedded tab (primary; renderer/UI work)
The app and stack sandboxes enable the Vite dev server's same-origin daemon bridge. The
renderer reaches /intentd/ws on the page origin through INTENTD_SOCKET or the platform
default socket; /__sandbox/health checks the same socket plus Vite warm-up. The browser
therefore needs one tunnel for the page, daemon RPC, and HMR.
During the first page load, the health probe returns 503 quickly while warm-up is pending
rather than blocking on the import crawl.
A first tunneled open of a fresh, pre-warmed app takes roughly one to three minutes to hydrate depending on host load. If the splash remains after health is ok, keep waiting rather than restarting; later loads are fast.
To land on a chosen chat or note, open /workspace/<workspaceId>?agent=<agentId> or
?note=<noteId> (both may be combined). Do not use /agent/<id>: on a cold load it shows
an empty placeholder, not the workspace chat panel. Recipe:
Open a chat or note in the app sandbox.
The bridged daemon API is unauthenticated. Keep Vite on loopback and reach it only through the Intent client's authenticated tunnel.
Tunneled Chromium treats daemon.localhost as a remote origin. Consequently,
workspace-file:// media do not load in that embedded tab even though they load in
Electron; validate such media in an Electron build.
Loop B — dev Electron FE + CDP (Electron shell work)
When the change touches Electron main/preload/native/sidecar, Loop A cannot see it —
run the dev Electron FE on a machine with a display using pnpm run dev:cdp (sets
ENABLE_CDP_DEBUG=true; remote-debugging port 9223 by default — the launcher picks the
first free port from 9223, so read the actual value from its output, e.g.
CDP targets: http://127.0.0.1:<port>/json/list — and every webContents — app window
and embedded tabs — is a target) and attach CDP locally. See
../../docs/fe/CDP_MCP_TOOLS.md.
On a headless remote host, run the built app instead: pnpm run build, then
pnpm run electron:headless -- --route '/settings?tab=devices'
(scripts/headless-electron.mjs). On Linux without a
display it re-runs under xvfb-run -a (install the xvfb package if missing). It
launches the production build with a throwaway --user-data-dir profile, connects to the
existing daemon (--socket, else INTENTD_SOCKET or the platform default; no sidecar is
spawned), prints screenshot: <path> and exits 0. --wait-for <css> gates the capture,
and --check <module> runs a default-exported async ({ app, page, route }) against the
live app (a throw exits 1); --help lists the rest. The renderer talks to the real daemon,
so actions in a check change real daemon state. This found three main-process bugs that
unit tests missed during the Browser access work (cloudlands-fe#4017).
Caveats
- The web build has no Electron preload: daemon RPCs work over the WS transport, but Electron-only capabilities (native dialogs, window management, some IPC-bridged channels) are absent or mocked — Loop A covers renderer/UI work only.
browser.execreaches embedded tabs only, never the app's own chrome — inspecting the Electron shell itself is always Loop B/CDP.
PR test builds
.github/workflows/manual-signed-build.yml ("Manual Signed Build") is dispatch-only and
builds any branch/ref — e.g. a PR branch — into platform-specific installers for testing:
gh workflow run manual-signed-build.yml --ref <pr-branch> -f build_macos=true (also
build_windows / build_linux; sign defaults to true — macOS Developer ID +
notarization, Windows Azure Artifact Signing). A signed Windows request first runs the
windows-signing-preflight job, which fails in seconds — naming every missing
INTENT_WINDOWS_AZURE_* / INTENT_WINDOWS_PUBLISHER_* / AZURE_* setting — when the
repository's Azure signing is not configured; re-run with -f sign=false for an unsigned
Windows build. Add -f intentd_ref=<hash> (any intent-hq/intentd git
ref — full 40-char commit SHA, branch, or tag; actions/checkout cannot resolve an
abbreviated SHA from git log --oneline) to build the intentd sidecar from source at
that ref instead of fetching the pinned release (all legs: macOS, Windows, and both
Linux arches); the run summary reports the resolved intentd SHA. Empty/omitted
intentd_ref keeps today's pinned-release fetch.
Output is installers + blockmaps only, uploaded as
short-lived workflow artifacts (7-day retention), version-suffixed -manual.<run_number>.
Nothing publishes to intent-hq/cloudlands-releases and no auto-updater manifest is
produced — manual install/testing only.
Update compatibility
Released clients are part of the compatibility contract. Changes to update feed filenames or URLs, channel metadata, installers, or architecture support must preserve an automatic upgrade path for existing supported installations within each channel. A migration must not require users to install the migration code manually first.
Test behavior shipped in a prior release, including its requested feed filenames and
architecture selection. New-client tests and successful builds/uploads are insufficient.
Keep these regression tests in required verification. For Mac feeds, extend
scripts/mac-channel-feeds.test.ts: latest-mac.yml, used by released beta/stable
clients, must advertise the selected release for each channel independently.
If a compatibility break is unavoidable, identify the exact affected installations and obtain explicit human authorization for that break. Documenting a workaround is not authorization; ending Intel support does not authorize stranding native Apple Silicon.
Verification
Use pnpm run verify:changed -- <paths...> during local work. With no paths it reads
staged, unstaged, deleted, and untracked frontend files, plus the commits since
git merge-base <ref> HEAD. <ref> is --base <ref> when given, otherwise origin/main
whenever HEAD is ahead of it, even with uncommitted edits, so the bare command also covers
files already auto-committed on the branch (cloudlands-fe#4431 skipped one and failed CI).
The first line names the mode used, also when an empty change set exits 2.
--dry-run lists the commands. --resolved-plan runs prerequisites and Vitest discovery
only, printing every selected unit-test file per lane; normal runs resolve the same plan
first, and discovery failures stop before any check (fix the reported config or source
error and retry). --max-unit-files N rejects (never truncates) a plan over N files —
combine it with --resolved-plan for a budgeted preview, then raise or omit the limit.
pnpm run test:unit --maxWorkers=1 runs the full unit suite.
verify:changed runs changed component test specs once with retries on. CI runs no
component tests on PRs or in the merge queue (only nightly at 02:17 UTC and on manual
dispatch), so to catch a broken or flaky new or edited spec before it merges, run
pnpm run test:ct:changed-repeat before pushing: it builds the CT bundle under
CI's 12 GiB heap, then repeats the changed specs (including uncommitted ones) up to 20 times
each with --retries=0 --fail-on-flaky-tests and two workers. --dry-run prints the filters and
repeat count; --workers N, --repeat-each N and Playwright args after a second --
(e.g. -- --grep "<title>") tune stress runs (--help lists the rest).
Each run prints record: <path> for its attempt under .dev/verify-changed/attempts/
and passes only when every check and resolved unit file is satisfied. To continue after a
failure or interruption, rerun with --resume (--resolved-plan --resume previews it);
never hand-pick stages. A run stops at its first failed check; --keep-going still runs and
records every remaining check, then fails listing them all (prerequisites still stop it). Each
check's output lands in <record>/logs/<check id>.log; a failure prints that path and its last
lines, so read the log instead of rerunning the check. Receipt files and resume-credit rules:
Changed-file verification receipts.
It runs scoped Prettier and ESLint, related Vitest tests, colocated component tests one
.svelte hop away, the changed TypeScript boundaries, knip repo-wide, test:ui-invariants
for renderer changes, and lint:architecture for src/, AGENTS.md and
scripts/check-*.mjs changes; ambiguous or high-risk files select a conservative suite.
Lane selection in detail: What verify:changed selects.
Rules that follow from it:
- A suite that reads the tree from disk (directly or via the IPC source scanner) is invisible
to
vitest related: declare// @verify-changed-triggers: <paths or globs>in its leading comments or opt out with// @verify-changed-exempt: <reason>(lint:verify-changed-triggers; cloudlands-fe#2256, #2314, #4017). - Mark any new component-inventory or
*.metaledger suite// @ui-invariant(or// @ui-invariant-exempt: <reason>);node scripts/ui-invariant-suites.mjs --list/--check. - New architecture gates go into
lint:architectureinpackage.json, never a separate workflow step (scripts/check-ci-architecture-gate.test.ts). - Do not write protocol version numbers in
src/(v10.1, or10.1on a line mentioning protocol/intentd/daemon); cite the method, field,§section or capability.lint:protocol-version-literalsaccepts// protocol-version-ok: <reason>on the line or// protocol-version-ok-file: <reason>in a file's first 10 lines. - Never hand-edit
src/preload/index.ts;pnpm run generate:ipc-channelsgenerates it. - Workflow edits:
pnpm run lint:workflows(part oflint:architecture) runs the pinned actionlint with shellcheck; add path-scoped ignores with a reason there.verify:changedruns it only when.github/workflows/**, local action metadata, the actionlint config orscripts/check-workflows.mjschange (actionlint can hang on a loaded host; #4332).
Playwright CT holds a host-wide ct-<port> lock (per-worktree port by default; see above) and the full Vitest
fallback holds vitest-full. A second run waits (240 s / 120 s by default,
VERIFY_CHANGED_LOCK_TIMEOUT_MS up to 300000 ms) and then fails naming the owner's pid and
worktree; never stop a lock owner — two runs in one worktree share its port, so pick a free
CT_PORT to run CT concurrently there (intent-hq/intent#4964).
Before every push, and after any structural change, run pnpm run verify:static (a few
minutes; same paths and --base as verify:changed). It runs Prettier and ESLint on the
changed files, then knip, pnpm run check and the renderer, main and preload tsc checks
repo-wide, with no tests: the static failures CI's Type Check & Lint reports most often
(cloudlands-fe#4491). Update onto origin/main first; ESLint max-lines counts the merged file.
Frontend philosophy & testing
The renderer is a thin presenter over the daemon. Correctness, business rules, and
persistence live in intentd; the FE renders what the daemon sends and dispatches user
intent back. The wire contract is the monorepo's
docs/protocol/ (the relative link resolves in a
monorepo checkout, where this repo mounts at packages/cloudlands-fe/);
treat it as the single source of truth.
Less logic on the client
- Keep business/domain logic out of the renderer. Selectors, components, and sagas should shape and route data — not re-derive things the BE already decides.
- New behaviour that affects domain state belongs in
intent-services(or the relevant crate) on the BE, not in a renderer transform. - Reducers/sagas exist to coordinate UI flows around wire calls; they are not a place to re-implement server semantics.
Faithfully reproduce BE state
- Render exactly what the daemon sends. Do not heal, patch, normalize, or transform BE-owned payloads on the way in — no defensive defaults to mask missing fields, no client-side "fixups" of shapes, no quiet renames.
- Any wire mismatch is resolved at the diverging side versus the monorepo's
docs/protocol/: the BE is the preferred fix-site (it owns the contract), or the protocol doc is updated when the documented shape itself is wrong. The FE is never bent to silently absorb a divergence. - Recent example:
tool_useandtool_resultblocks must pair bytoolCallId ↔ tool_use_idper protocol §7 (chat.subscribesynthesized blocks). When pairing broke, the FE selector was corrected to match the contract — the BE was not coerced into emitting a renamed field.
Transient client state
- Renderer state is transient/UI-only: panel layout, selection, drafts, hover/focus, open menus, in-flight optimistic ticks. None of it is canonical.
- The BE owns persistence and durable identity. After a reload, the FE rehydrates by asking the daemon — it does not reconstruct domain state from local caches as if those caches were authoritative.
- Caches in the renderer are read-through views of BE responses, invalidated by BE-driven events, never an alternative source of truth.
Event-driven refetches — single-flight and coalesced
Daemon events arrive in bursts (agent lifecycle, file changes, task updates). Any handler that refetches state in response to daemon events MUST be single-flight with trailing coalesce:
- Single-flight: all triggers share one in-flight promise — never start a second concurrent refetch of the same data.
- Trailing coalesce: events arriving while a refetch is in flight collapse into at most one trailing refetch after the current one settles. The leading edge stays immediate (the first event triggers a fetch right away) so freshness is not sacrificed.
- N events during a fetch must produce at most 1 follow-up fetch, not N.
Do not fan out per-workspace daemon RPC loops from an event handler — e.g.
workspace.list followed by a per-workspace RPC for each result multiplies every event
burst into O(workspaces) daemon calls (precedent:
intent-hq/intent#1395, the
active-streams fan-out). Prefer a targeted query for the affected workspace, or a
daemon-side aggregate that returns everything in one RPC — if none exists, request one
on the BE rather than looping on the client.
Saga-owned mutations & soft-hide-then-commit
Agent lifecycle mutations are owned by agentMutationSaga in
src/store/renderer/slices/agent-session/sagas/agent-mutation-saga.ts, registered once
in src/store/renderer/sagas.ts. Creation is owned by agentCreationSaga and routes
through agentFactory.createAgent(). Extend these owners, not a mutation middleware
or a second runtime. Existing async-action callers (*Requested actions with a
.promise) remain supported: settle through the originating action's
action.success/action.failure helpers so each dispatch retains its correlation.
New UI consumers dispatch intent and read correlated selector outcomes; the saga
owns transport calls, rollback and notifications.
Agent deletion uses the daemon-owned delete grace window (protocol §5.5,
agent.delete { undoDelayMs }; the handlers live in the agent mutation saga):
deleteAgentWithUndoRequestedsoft-hides the session locally (drops it from the visible list) and sendsagent.delete { undoDelayMs: 15000 }immediately, so the daemon owns the 15s window and commits at the deadline even if the FE quits or crashes mid-window. The action resolves with the removed session once the daemon acks the schedule; a wire failure un-hides the session and rejects.undoAgentDeletionRequestedissues the race-safeagent.cancelDelete:{ cancelled: true }un-hides the session;{ cancelled: false }(already committed) surfaces a "could not undo" toast without resurrecting it.- There is no FE-side commit timer or flush — the daemon commits at the deadline and
emits
agent:deleted(inAGENT_LIFECYCLE_EVENTS), so the reactivesubscriberefetch reconciles the list — the FE does not hand-roll list mutation.
The pending deletions are transient UI-only state (a module-level Map), never Redux.
During the window (and for a tombstone grace period after the deadline, so stale
refetches cannot resurrect the agent) read paths consult isAgentDeletionPending() and
drop wire rows carrying the additive pendingDeleteAt field.
Test observable behavior, not presentation
- Tests MUST cover observable logic: state transitions, inputs/outputs and wire payloads, validation, conditional behavior, routing, error/retry handling, persistence, and accessibility interactions/state.
- Tests MUST establish runtime or behavioral evidence against an independent oracle. Expectations derived from the implementation under test are circular and prohibited.
- Do not assert literal source, class, or markup spelling, source order, exact copy, or unconditional visual presence.
- Do not stub or assign dimensions, values, or state and then assert those same inputs. Exercise production behavior and observe its resulting output or runtime state.
- Do not duplicate production values in a fixture and test only that duplicate. A fixture must drive production code or independently model the external contract.
- Exact-value assertions are appropriate for intentional stable contracts, including wire payloads, schemas, public identifiers, and accessibility state.
- Accessible text may locate a control in a behavioral test; assert the resulting interaction or state, not the exact wording as the contract.
- For copy-only changes, do not update unit tests. Run
pnpm run generate:i18n,pnpm run lint:i18n-completeness, andpnpm run lint:i18n-stringsinstead.
Tooltip tests are forbidden
Never add, restore, stabilize, quarantine, or replace tooltip or cosmetic hover-help
tests. This applies to unit, component, integration, Playwright/Electron, and snapshot
tests: no assertions for tooltip copy, presence, visibility, hover/focus reveal,
dismissal, positioning, animation, or timing, including native title help and hover cards.
Delete tooltip-only cases, suites, snapshots, and orphan test fixtures/helpers. In mixed
tests, remove tooltip assertions and setup while retaining independent actions,
navigation, data/state contracts, and accessible names of actual controls. Keep tooltip
selectors only when needed to locate a functional control. Do not replace deleted tests
with checks proving they were deleted, and do not change product tooltip behavior.
The Untitled hover test blocked unrelated delegation work and passed only on retry
(cloudlands-fe#3895 queue failure).
Do not check in browser gesture choreography tests
Do not check in browser drag-and-drop or pointer/animation choreography tests.
This applies to component, E2E, and Electron suites: mouse move/down/up sequences,
dragTo, coordinate-driven gestures, cancelled,
Escape or outside drops, hover-triggered drag affordances, resizing, reordering, and
mid-flight animation frame sampling or reversal sequences.
Temporary local probes are allowed while building or debugging a feature. They are
development evidence: remove their code, exclusive fixtures/helpers, assertions, and
gesture-only settling waits before committing or opening a PR. Screenshots and traces
may accompany review as evidence; existing tooltip and pixel-comparison bans still apply.
Delete checked-in violations; never restore, stabilize, quarantine, or replace them with
timing waits, retries, pixel comparisons, or equivalent gestures. Split mixed tests to
retain independent actions, keyboard access, navigation, and data contracts. Keep
deterministic unit tests for ordering, persistence, state transitions, and payloads.
Ordinary clicks, functional hover controls, scrolling, and live containment/accessibility
checks remain valid when independent of this choreography. Leave production behavior
unchanged.
The Set aside drag test delayed unrelated work when opening a detail pane resized its
coordinate target (cloudlands-fe#3895 queue failure).
Pixel comparison tests are forbidden
Never add, restore, run, or regenerate pixel comparison tests. There are no exceptions for a component, feature, platform, theme, zoom level, or CI runner. This ban covers screenshot/image snapshots, golden images, rendered pixel or alpha sampling, image similarity scores, and byte/hash comparisons of rendered images. Do not hide these checks in helpers, custom matchers, canvas redraws, or renamed "visual" tests. Do not add reference images, comparison tolerances, baseline update commands, or image-diff dependencies. Remove an existing violation; never refresh its baseline or loosen its threshold to make it pass.
Enforce these bans during review. Do not add source-scanning scripts or fixture tests to enforce the pixel comparison or DOM measurement baseline policies.
Manual screenshots and probes remain required for visual review where applicable. They are review evidence only: never compare their pixels or use them as automated pass/fail baselines. Test observable behavior with independent assertions instead.
Do not write decorative appearance tests
These rules apply to unit tests and browser tests alike:
- Do not pin decorative choices: exact colors, font families/sizes/weights, spacing, border widths/radii, shadows, or icon alignment. A browser measurement does not make a decorative assertion a behavioral contract.
- Do not use source text, markup order, or CSS-class strings to prove appearance.
Those checks constrain implementation spelling without establishing browser behavior.
intent/no-class-name-assertions-in-testsrejects newclassName/classList/toHaveClassassertions insrc/**/*.test.ts; existing ones are counted ineslint-rules/baselines/no-class-name-assertions-in-tests/, which may only shrink. - Do not claim layout coverage from jsdom dimensions. jsdom does not perform layout; assigning a width or mocking a bounding box and checking it cannot prove containment.
- Do not build circular style oracles: importing a production class constant and checking for those same classes, or copying production spacing into a fixture and measuring that fixture, does not independently verify the app.
- Delete an appearance-only test when its useful assertions are gone. Do not keep it alive with prop echoes, unconditional render checks, direct focus assignment checks, or expectations derived from its own mock. Every retained test needs an independent behavioral failure it can detect.
- Do not multiply themes, widths, or zoom levels without a named behavioral reason for each variation. Use the smallest set that exercises distinct contracts.
Keep real-browser checks for clipping or overlap that hides content or controls, scroll ownership/anchoring, focus and keyboard access, usable hit areas, accessibility contrast, and reduced-motion behavior. Name the user-visible failure the assertion prevents. DOM geometry and computed styles are valid evidence for those contracts. This permits measurements of live elements, never pixel sampling or comparison of rendered images.
| Do not write | Write or retain instead |
Assert rounded-lg, an 8px radius, or an exact shadow. | Exercise opening, dismissal, and focus restoration of the actual dialog. |
| Assert an icon is centered within 1px or text uses a particular font size. | Verify long or zoomed content leaves the control readable and operable. |
| Assert a warning equals an imported color token. | Check the warning appears for the relevant state and meets accessibility contrast requirements. |
| Read a Svelte file and expect padding classes or their source order. | Exercise the production component in a browser and check content is not clipped or obscured. |
Set a jsdom container width and compare its scrollWidth to clientWidth. | Mount the real component at a meaningful narrow viewport and check overflow and interaction. |
| Import a style constant and assert every token occurs in the rendered classes. | Dispatch an action or change a prop and assert the resulting state, content, or interaction. |
| Repeat an appearance assertion across every theme × width × zoom combination. | Select named cases such as narrow keyboard access or zoomed control containment. |
DOM measurement baselines are forbidden
Never measure DOM elements and compare their size, position, or spacing with hard-coded or generated appearance baselines. No exceptions. This includes a single width or height, inline numeric expectations, arrays or JSON of bounding boxes, saved coordinates, snapshots, and expected values imported or generated from CSS, tokens, fixtures, or a previous run. A tolerance, range, rounded value, ratio, renamed helper, or claim of "geometry coverage" does not make an appearance baseline acceptable. Remove violations; never record new measurements or adjust expected values to pass.
Do not recreate these tests under another name, add exemptions, or regenerate their baselines. Capturing all boxes or path coordinates during a test and requiring the same layout later is also a generated appearance baseline. Review must reject equivalent custom comparisons.
Keep independent behavioral assertions: content stays within its live container, controls remain reachable, and scrolling preserves the user's position. Accessibility minimum target sizes are standards-based bounds, not decorative baselines. Small rounding tolerances may support these relationships; they must not pin an ornamental dimension or spacing value. Pure layout algorithm input/output contracts are also valid. Manual probes and screenshots remain review evidence only; never turn their measurements into automated pass/fail baselines.
Component tests (Playwright CT) — when and how
scripts/ct-browser.mjs owns the CT browser pin (the exact Chromium supplied by the
ct-browser alias); install it with node scripts/run-ct-tests.mjs --install-browsers
chromium and use the same PLAYWRIGHT_BROWSERS_PATH for install and tests. Traces use
retain-on-first-failure. Pin, patch and diagnostic configs:
Component test browser pin.
Playwright CT (*.ct.spec.ts, run by pnpm run test:ct) is for behavior that only a
real browser can observe: functional layout/geometry, focus and keyboard handling, native
browser APIs, and settled-state/reduced-motion contracts under the rules above. State,
wire, validation, and routing logic belong in Vitest — a CT spec
is roughly 10× the cost of a jsdom test and the CT job is sharded and time-boxed on CI.
- Matrix cells must map to a named contract. Loop over a width only when that width is a real breakpoint under test, over both themes only when color/theme is under test, over both zooms only when scaling is under test. A cross-product "for completeness" is not a contract and multiplies CI time.
- One
test()is one retry unit. A loop of assertions inside a singletest()callback, or a file undertest.describe.configure({ mode: 'serial' }), is retried and reported as a block — one bad cell reruns the whole block and hides which cell broke. Generate onetest()per cell instead, and do not use serial mode unless tests truly share ordered state. - A pass-on-retry fails the CT lane (
--fail-on-flaky-tests). Fix the flake or tag the individual test{ tag: '@quarantine' }— never a whole file — with an open tracking issue and an owner. Quarantined tests still run as an advisory step on shard 1; the PR that fixes the flake removes the tag. - Component tests never run on PRs or in the merge queue (PRs run type/lint, unit tests
and static checks). The full CT suite (four shards,
browser-tests.ymlsuite: ct) runs nightly at 02:17 UTC (nightly-browser-tests.yml) and on manual dispatch, so a CT regression surfaces after merge. Before pushing a change to a component or a spec, run the specs it touches withverify:changedand stress new or edited ones withpnpm run test:ct:changed-repeat; run all four shards locally withpnpm run test:ct:full(about 2h15m; see Where to look). Merge-queue entries touching root Playwright or Electron lifetime test/harness/config paths run those suites; both also run nightly.pnpm ct:failures <run-id>lists failed/flaky cases, andnightly-browser-report.ymlfiles or updatesintent-hq/intentissues for nightly failures (Nightly browser-test reporting). - For permitted settled-state or reduced-motion assertions, check "no animation is
running" with the
src/test/ct-test.tshelpers, never a one-timegetAnimations()count: a child's short fade caught mid-flight ejected cloudlands-fe#3651 from the merge queue.expectAnimationsToSettle(locator)waits for motion to finish (includeFinishedalso requiresfill: 'forwards'leftovers to be removed).expectNoAnimations(locator, opts)asserts nothing animates;opts.ignorenames a component ({ within: selector }) whose own short finite fades are allowed. Both list what is still running. Lint (intent/no-one-shot-animation-count) rejects the one-time count in CT specs; disable it on the line, with the reason, only when zero animations is the deliberate contract. - Before an outside click that should dismiss a bits-ui menu, popover, select, combobox or
dialog, call
expectDismissibleLayerArmed(layer)(src/test/dismissible-layer.ts): bits-ui listens for outside pointers only after anafterSleep(1)timer, so an early click is ignored (cloudlands-fe#3696 failed 3 of 20 runs). Any element inside the layer works aslayer. Lint (intent/no-unarmed-outside-click-in-ct) flags an unguarded dismissing click; disable it on the line, with the reason, for a click inside the layer or on a non-bits-ui popup. Prove a wait withCT_DELAY_DISMISSIBLE_LAYER=1(1 ms timers become 500 ms, no rebuild): the spec must pass, then fail with the wait removed (cloudlands-fe#3718 patched the fixture). - Scroll with
wheelUntilScrolled(scroller, { deltaY })(src/test/ct-test.ts), never a singlepage.mouse.wheel: Chromium can drop a wheel routed by a stale compositor frame, so the element never scrolls (cloudlands-fe#3733 failed 4 of 320 runs). The helper checks the element has room to scroll, hovers it (orpointer), and resends until it moves in the wheel's direction; keep your own end-position assertion after it. Lint (intent/no-raw-mouse-wheel-in-ct) rejects the raw call; disable it on the line, with the reason, only when the test checks that a wheel does NOT scroll. - Wait for motion, never a fixed
page.waitForTimeout: Playwright hit-tests only pointerdown, so a target still moving at mouseup loses the click (cloudlands-fe#3955).clickAndSettle(control, region)(src/test/ct-test.ts) clicks, waits forregionto change, then for its box, scroll and finite animations to stay still;expectMotionToSettle(region, { changedFrom: await motionSnapshot(region) })does the same after another trigger. Lint (intent/no-wait-for-timeout-in-ct) caps each spec's sleeps at its baseline (eslint-rules/baselines/, shrink-only); keep a sleep, disabled on the line with the reason, only to observe a quiet period. - Activate a hover-only action (a row toolbar that takes pointer events only while its row
is hovered) with
activateHoverAction(action, region)(src/test/ct-test.ts), neverrow.hover()then a click: Playwright checks the hit target before it moves the pointer, so a row that moves after the hover leaves every retry hitting the row text until the timeout (cloudlands-fe#4112; ejected cloudlands-fe#4078 from the queue). The helper waits forregionto settle, presses Enter on the action, then waits forregionto change and settle (requireChange: falsewhen it may not). Lint (intent/no-hover-then-click-in-ct) caps each spec's sites at its shrink-only baseline; retain an ordinary click only for independent control behavior on a row that cannot move. - For permitted timer/state tests, pause the fake clock:
page.clock.install()alone keeps time moving with real time, so a slow step can advance the state (cloudlands-fe#4148: 56 of 80 loaded runs failed). UseinstallPausedClock(page, beforePause?)orpauseClock(page)(src/test/ct-test.ts), then step withpage.clock.runFor. Do not use clock stepping to check animation choreography. Lint (intent/no-unpaused-clock-in-ct) rejects an install whose test never pauses; keep one, disabled on the line with the reason, only to skip a delay and check settled state. - Press a registered shortcut with
shortcutChord(SHORTCUT_DEFAULTS[id], isMac)(src/test/shortcut-chords.ts;.pressor theKeyboardEventinit.event), never its keys typed out: a moved shortcut leaves the spec pressing the old keys (cloudlands-fe#4205; nightly intent-hq/intent#8681, #8682). ImportSHORTCUT_DEFAULTSin the spec itself, since changed-test selection follows direct imports only. Lint (intent/no-hand-typed-shortcut-in-ct) flags a literal chord equal to a binding; disable it on the line, with the reason, when a hard-coded handler only shares the keys. - Every CT spec imports
test/expectfromsrc/test/ct-test.ts— lint-enforced (no-restricted-imports; only type imports may come from@playwright/experimental-ct-svelte). The module gives every test a fresh browser context, because ct-core's per-worker context reuse raced the nextmount()(a pass-on-retry "Execution context was destroyed" atmount().CT_CONTEXT_REUSE=1is for local wall-time measurement only, never CI. If the auto Guard fixture fails withbrowser context <id> was already used …, fix the module, not the spec. A destroyed-context failure with the guard passing is a residual incident to investigate, never to quarantine or retry away; the Recorder attachescdp-lifecycle.jsonto the HTML report for it. How to read both: Component test fresh-context guard.
Testing — every feature/fix against a mock BE
Every feature and every bug fix that touches the wire MUST ship with tests that:
- Assert the exact request sent on the wire — channel/method plus the params payload
— matching the request shape
docs/protocol/defines for that method. - Feed a protocol-shaped mock response back through the same channel and assert the FE handles it (state updates, rendered output, downstream events).
Responses that diverge from the protocol docs are fixed at the BE (or the doc is updated); the FE never silently absorbs a wire mismatch in a test fixture either — mock payloads must mirror the documented contract.
Reuse the existing infrastructure instead of inventing parallel harnesses:
| Use… | For… |
src/shared/ipc-mock-router.ts | Single in-memory mock router — register per-channel invoke handlers and emit mock events. |
src/shared/ipc/request-validation.ts (+ schemas) | Zod schemas + validateIpcRequest / tryValidateIpcRequest to assert the request matches contract. |
src/shared/ipc/__tests__/contracts.test.ts | Reference pattern for asserting IPC contracts and request schemas — extend it for new methods. |
src/test-setup.ts | Vitest global setup (Electron mocks, jsdom shims, temp workspace dir). New suites get this for free. |
src/test/layer-exit.ts | Unit tests closing menus/dialogs: waitForLayerExit(el), pressOutsideLayer(el) (jsdom-safe). |
src/test/animation-frames.ts | Unit tests stepping rAF: installAnimationFrames() honors cancels and flushes effects per callback. |
Run the targeted suite with pnpm vitest run <files> (see Verification
above) before opening a PR.
Filing issues
File bugs on intent-hq/intent with labels
component:fe + agent-filed; never track issues in markdown files. Put Fixes
intent-hq/intent#N on every fix PR: the release notifier
(scripts/notify-fixed-issues.sh) comments on a closed issue only once at least one
linked fix PR has merged, every merged one across cloudlands-fe and intentd is in a
release, and none is still open (PRs closed without merging are ignored); a plain mention
never earns a comment. Dedup and cross-referencing: root AGENTS.md → Filing
Issues.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

