agentleFS
intent-hqintent-hq/cloudlands-fe/AGENTS.md

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.

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
  1. Very specific:

    Use pnpm, not npm; create agents via agentFactory.createAgent().

    line 26
  2. Distinctive:

    Start with the “I need to…” decision tree, not raw markup.

    line 30
  3. Distinctive:

    Use the generated pattern cheatsheet for imports and API summaries.

    line 31
  4. Very specific:

    Use public $lib/components/patterns/* or $lib/components/ui/* subpaths.

    line 33
  5. Very specific:

    Follow the Never list, enforced by eslint-rules/design-system/.

    line 34
  6. Very specific:

    Never hand-write motion durations or physical colors.

    line 35
  7. Distinctive:

    Never pause, stop, or disable animations app-wide on your own (window blur, battery, visibility, performance).

    line 36
  8. Distinctive:

    Never add a raw control, direct toast/native dialog, bespoke settings row, or feature-owned dialog root.

    line 40
  9. Very specific:

    Run pnpm run lint:design-cheatsheet (part of pnpm run lint) with the focused lint/tests.

    line 45
  10. Very specific:

    Put renderer product work in src/features/.

    line 100
  11. Very specific:

    Keep shared app state in src/store/renderer/, not ad-hoc component state.

    line 101
  12. Distinctive:

    All user-facing strings (labels, aria-labels, placeholders, tooltips, toasts, errors, menu items) go through Paraglide message functions — …

    line 115
  13. Very specific:

    Messages: call m.*() (import from src/shared/paraglide/messages.js).

    line 117
  14. Very specific:

    Dates/numbers: only via $lib/i18n/format (renderer) or src/shared/i18n/formatters.ts (main/shared) — never ad-hoc toLocaleString, direct …

    line 120
  15. Very specific:

    Use dev:ui for component-only work.

    line 166
  16. Distinctive:

    Use these exact state names in direct URLs:

    line 176
  17. Very specific:

    Add theme=system|light|dark, an integer width=240..1600, and motion=full|reduced.

    line 180
  18. Distinctive:

    Use before/after geometry probes when they help explain a layout change, and include the useful evidence in the task report:

    line 194
  19. Very specific:

    Follow the root Observe and Prove steps with a fixed viewport.

    line 226
  20. Very specific:

    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.

    line 231
  21. Very specific:

    If the command cannot reach the preview, use an owned hidden embedded-browser tab as the fallback.

    line 234
  22. Very specific:

    Before linking any generated image or video, verify that the actual file exists in the message's owning workspace.

    line 251
  23. Very specific:

    Start with the monorepo root Developing on a remote host loop.

    line 278
  24. Very specific:

    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 …

    line 311
  25. Distinctive:

    Test behavior shipped in a prior release, including its requested feed filenames and architecture selection.

    line 367
  26. Very specific:

    Keep these regression tests in required verification.

    line 369
  27. Distinctive:

    If a compatibility break is unavoidable, identify the exact affected installations and obtain explicit human authorization for that break.

    line 373
  28. Very specific:

    Use pnpm run verify:changed -- <paths...> during local work.

    line 379
  29. Very specific:

    Do not write protocol version numbers in src/ (v10.1, or 10.1 on a line mentioning protocol/intentd/daemon).

    line 425
  30. Very specific:

    Never hand-edit src/preload/index.ts.

    line 429
  31. Very specific:

    Before every push, and after any structural change, run pnpm run verify:static (a few minutes.

    line 441
  32. Distinctive:

    Keep business/domain logic out of the renderer.

    line 458
  33. Distinctive:

    When pairing broke, the FE selector was corrected to match the contract — the BE was not coerced into emitting a renamed field.

    line 476
  34. Distinctive:

    Single-flight: all triggers share one in-flight promise — never start a second concurrent refetch of the same data.

    line 495
  35. Very specific:

    Do not fan out per-workspace daemon RPC loops from an event handler — e.g.

    line 502
  36. Distinctive:

    Do not assert literal source, class, or markup spelling, source order, exact copy, or unconditional visual presence.

    line 549
  37. Distinctive:

    Do not stub or assign dimensions, values, or state and then assert those same inputs.

    line 551
  38. Distinctive:

    Do not duplicate production values in a fixture and test only that duplicate.

    line 553
  39. Distinctive:

    Delete tooltip-only cases, suites, snapshots, and orphan test fixtures/helpers.

    line 568
  40. Distinctive:

    Delete checked-in violations.

    line 587
  41. Distinctive:

    Do not hide these checks in helpers, custom matchers, canvas redraws, or renamed "visual" tests.

    line 603
  42. Distinctive:

    Keep real-browser checks for clipping or overlap that hides content or controls, scroll ownership/anchoring, focus and keyboard access, …

    line 639
  43. Distinctive:

    Remove violations; never record new measurements or adjust expected values to pass.

    line 663
  44. Distinctive:

    Do not recreate these tests under another name, add exemptions, or regenerate their baselines.

    line 665
  45. Distinctive:

    Keep independent behavioral assertions: content stays within its live container, controls remain reachable, and scrolling preserves the …

    line 670
  46. Very specific:

    Before an outside click that should dismiss a bits-ui menu, popover, select, combobox or dialog, call expectDismissibleLayerArmed(layer) …

    line 725
  47. Very specific:

    Wait for motion, never a fixed page.waitForTimeout: Playwright hit-tests only pointerdown, so a target still moving at mouseup loses the …

    line 741
  48. Very specific:

    Do not use clock stepping to check animation choreography.

    line 762
  49. Distinctive:

    Every feature and every bug fix that touches the wire MUST ship with tests that:

    line 786
  50. Very specific:

    Run the targeted suite with pnpm vitest run <files> (see Verification above) before opening a PR.

    line 808

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.md for 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 and STATE_MANAGEMENT.md.
  • Use pnpm, not npm; create agents via agentFactory.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 /sandbox and /sandbox/recipes via pnpm 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/motion and 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" via data-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.ts ceilings or expand lint baselines.
  • Run pnpm run lint:design-cheatsheet (part of pnpm run lint) with the focused lint/tests; regenerate the cheatsheet with pnpm 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 gatespnpm 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 ruleeslint-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 freshnesspnpm run deps:check — gates refuse to run on a stale node_modules install
Node versionpnpm 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 tracespnpm perf:chat-motion — ../../docs/fe/DEVELOPER_GUIDE.md#chat-motion-performance-traces
alignment / text-rebase perf claimspnpm 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 tracespnpm 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 in src/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 app Store instance, e.g. store.dispatch(action) and selector.select(store.state, ...args). See ../../docs/fe/STATE_MANAGEMENT.md for 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: (and Release-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 (root AGENTS.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 from src/shared/paraglide/messages.js); keys live in messages/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, and test:ct regenerate it on demand when it is missing or stale; run pnpm run generate:i18n to rebuild it by hand after editing messages/en.json.
  • Interpolation over concatenation: named params ("Configure {name} path"); sentences split by inline markup use _before / _middle / _after key pairs; plurals as _one / _many key pairs. Gotcha: literal {/} in a message parses as a parameter — rephrase such strings.
  • Dates/numbers: only via $lib/i18n/format (renderer) or src/shared/i18n/formatters.ts (main/shared) — never ad-hoc toLocaleString, direct date-fns format 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 into pnpm run lint) blocks hardcoded strings inside ENFORCED_DIRS. New features in enforced dirs must be string-free from day one; when you migrate a directory to messages, add it to ENFORCED_DIRS.
  • Catalog completeness: scripts/check-i18n-completeness.mjs (also chained into pnpm run lint) fails CI when any locale catalog diverges from messages/en.json — missing keys, extra keys, per-key {param} placeholder mismatches, unpaired _one/_many plurals — or when messages/*.json files and the project.inlang/settings.json locale 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.) in scripts/i18n-equal-allowlist.json (per key, "*" or a locale array); stale allowlist entries fail the check.
  • Merging catalogs: pnpm install registers a key-level git merge driver for messages/*.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), run pnpm 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, or destructive
  • /sandbox/mention-agent-avatar?state=idle, waiting, or error
  • Add theme=system|light|dark, an integer width=240..1600, and motion=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-wide

Both 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 ![alt](intent://local/file/<percent-encoded-workspace-relative-path>) 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.ts

Without 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.exec reaches 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 *.meta ledger suite // @ui-invariant (or // @ui-invariant-exempt: <reason>); node scripts/ui-invariant-suites.mjs --list / --check.
  • New architecture gates go into lint:architecture in package.json, never a separate workflow step (scripts/check-ci-architecture-gate.test.ts).
  • Do not write protocol version numbers in src/ (v10.1, or 10.1 on a line mentioning protocol/intentd/daemon); cite the method, field, § section or capability. lint:protocol-version-literals accepts // 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-channels generates it.
  • Workflow edits: pnpm run lint:workflows (part of lint:architecture) runs the pinned actionlint with shellcheck; add path-scoped ignores with a reason there. verify:changed runs it only when .github/workflows/**, local action metadata, the actionlint config or scripts/check-workflows.mjs change (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_use and tool_result blocks must pair by toolCallId ↔ tool_use_id per protocol §7 (chat.subscribe synthesized 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):

  • deleteAgentWithUndoRequested soft-hides the session locally (drops it from the visible list) and sends agent.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.
  • undoAgentDeletionRequested issues the race-safe agent.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 (in AGENT_LIFECYCLE_EVENTS), so the reactive subscribe refetch 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, and pnpm run lint:i18n-strings instead.

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-tests rejects new className / classList / toHaveClass assertions in src/**/*.test.ts; existing ones are counted in eslint-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 writeWrite 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 single test() callback, or a file under test.describe.configure({ mode: 'serial' }), is retried and reported as a block — one bad cell reruns the whole block and hides which cell broke. Generate one test() 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.yml suite: 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 with verify:changed and stress new or edited ones with pnpm run test:ct:changed-repeat; run all four shards locally with pnpm 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, and nightly-browser-report.yml files or updates intent-hq/intent issues 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.ts helpers, never a one-time getAnimations() count: a child's short fade caught mid-flight ejected cloudlands-fe#3651 from the merge queue. expectAnimationsToSettle(locator) waits for motion to finish (includeFinished also requires fill: 'forwards' leftovers to be removed). expectNoAnimations(locator, opts) asserts nothing animates; opts.ignore names 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 an afterSleep(1) timer, so an early click is ignored (cloudlands-fe#3696 failed 3 of 20 runs). Any element inside the layer works as layer. 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 with CT_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 single page.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 (or pointer), 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 for region to 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), never row.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 for region to settle, presses Enter on the action, then waits for region to change and settle (requireChange: false when 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). Use installPausedClock(page, beforePause?) or pauseClock(page) (src/test/ct-test.ts), then step with page.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; .press or the KeyboardEvent init .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). Import SHORTCUT_DEFAULTS in 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 / expect from src/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 next mount() (a pass-on-retry "Execution context was destroyed" at mount(). CT_CONTEXT_REUSE=1 is for local wall-time measurement only, never CI. If the auto Guard fixture fails with browser 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 attaches cdp-lifecycle.json to 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:

  1. Assert the exact request sent on the wire — channel/method plus the params payload — matching the request shape docs/protocol/ defines for that method.
  2. 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.tsSingle 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.tsReference pattern for asserting IPC contracts and request schemas — extend it for new methods.
src/test-setup.tsVitest global setup (Electron mocks, jsdom shims, temp workspace dir). New suites get this for free.
src/test/layer-exit.tsUnit tests closing menus/dialogs: waitForLayerExit(el), pressOutsideLayer(el) (jsdom-safe).
src/test/animation-frames.tsUnit 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.