BloomDesktop: Instructions file for Codex

This project has a web front-end at src/BloomBrowserUI. The front-end uses pnpm 11.5.2. Never ever use npm or yarn.

Architecture

• C# backend
• web front-end in React/Typescript
• WebView2 for hosting the web front-end in the desktop app
• We strictly control both ends of the API.
  • Don't worry about legacy API support. If you need to change the API, just change it on both sides.
  • Don't be overly defensive about error handling. If the API is used incorrectly, it's fine for it to throw an error. We want to know about it so we can fix it.

Code Style

• React components are arrow function components (see the example below); src/BloomBrowserUI/AGENTS.md covers other functions

• do not destructure props

• do not define a props data type unless it is huge

• example: export const SomeComponent: React.FunctionComponent<{initiallySelectedGroupIndex: number;}> = (props) => {...}

• Avoid removing existing comments unless your changes make them inaccurate/obsolete

• Avoid adding a comment like "// add this line".

• Style elements using the css macro from @emotion/react directly on the element being styled, using the css prop. E.g. <div css={csscolor:red}>

• Where possible style things using @emotion/react rather than using sx objects.

• Avoid stacking/nesting ternary (? :) operators (e.g. a ? x : b ? y : z). They're too hard for humans to read. Use an if/else-if chain (or a switch) instead. A single, non-nested ternary is fine.

• For Typescript coding style, see ./src/BloomBrowserUI/AGENTS.md

Testing

• Fail Fast. Don't write code that silently works around failed dependencies. If a dependency is missing we should fail. Javascript itself will fail if we try to use a missing dependency, and that's fine. E.g. if you expect a foo to be defined, don't write "if(foo){}". Just use foo and if it's null, fine, we'll get an error, which is good.
• Try to make it so that test failures indicate what went wrong. For example, fail("An error occurred in setup; we should not have gotten here") would be better than expect(false).toBeTruthy(); and expect(foo).toBe(3); would be better than expect(foo === 3).toBe(true);.
• Add sanity checks to guard against falsely passing tests. For example, when unit testing a method, sanity check that the test data values are as expected before you call the method, and then after you call the method you can verify that those values have changed as expected.
• Never accept a flaky test. A test that fails without a code change to explain it is flaky from its first failure; it is reporting a real race, in Bloom or in the test: find out which and fix the cause. Waiting to see whether it fails again is accepting it. Any way of working around the flakiness instead (retries, re-running until it passes, waiting to see if it recurs, a longer timeout, a fixed delay, looser assertions, skipping the test, a test hook added to Bloom) needs the developer's permission first.
• Nightly CI failures: docs/nightly-failures/README.md records what is already known about each one. To look at recent nightlies, follow .claude/skills/nightly-triage/SKILL.md, which keeps that doc up to date.