AGENTS.md · Floorp-Projects/Floorp

Sections

1. Commands
2. Runtime changes
3. Architecture (5 Layers)
4. Tech Stack
5. Path Aliases (deno.json)
6. Coding Conventions
7. Testing
8. Dev Server Ports
9. dev-tool -- Browser Inspection CLI
10. Debugging
11. Further Reading

First lines (shown under the repo's MPL-2.0 license)

# AGENTS.md

Floorp is a Firefox-based web browser ("Noraneko") built on top of the Gecko engine. This repo contains the custom browser features that overlay Firefox — not the Firefox source itself.

## Commands

```bash
deno install                        # Install dependencies
deno task feles-build dev           # Dev mode with HMR (ports 5173–5186)
deno task feles-build build         # Production build (two-phase: --phase before-mach / --phase after-mach)
deno task feles-build stage         # Staging build
deno task feles-build test          # Launch browser with Marionette for automated testing
deno task feles-build misc patch    # Manage Firefox source patches (apply/create/init)
deno task test                      # Run unit tests (browser-integrated, uses colocated test runner)
deno task test -- --near <path>     # Run tests near a specific file/directory
deno task test -- --layer chrome    # Run only chrome-layer tests (also: esm, pages, all)
deno task test:host                 # Run tool tests (Deno native)
deno task test:smoke                # Smoke tests
deno task dev-tool                  # Development utility CLI
```

## Runtime changes

Runtime changes must be maintained as patches, not direct edits to a sibling
Floorp-Runtime checkout. Cross-platform source patches belong in
`.github/patches/floorp-runtime/common/` and are applied by `package.yml`.
Validate them against the source commit in `floorp-runtime.lock.json` in isolation.
The package workflow uses prebuilt native artifacts; changes requiring native
recompilation cannot be delivered through source patches in that step alone.

## Architecture (5 Layers)

```text
Firefox Base  <- patched Gecko, pref overrides (static/gecko/pref/override.ini)
     |
ESM Modules   <- .sys.mts files with direct Firefox API access, Window Actors
     |
Bridge        <- startup scripts that load features from Vite dev servers (HTTP) or chrome://noraneko/ (prod)
     |
Chrome UI     <- SolidJS -> XUL via custom solid-xul renderer, auto-discovered by import.meta.glob
     |
Pages         <- React + Tailwind full-page UIs (settings, new tab, welcome, notes, etc.)
```

The bridge (`bridge/startup/src/chrome_root.ts`) is the bootstrap: in dev/test mode it loads from `http://localhost:5181/loader/index.ts` with retry logic; in production it loads `chrome://noraneko/content/core.js`.

## Tech Stack

- **Runtime**: Deno 2.x (primary), Node.js 22 (some pages)
- **Browser Chrome UI**: SolidJS + `@nora/solid-xul` (custom renderer that uses `document.createXULElement()` via `solid-js/universal`'s `createRenderer`)
- **Settings/Pages UI**: React + Tailwind CSS
- **Build**: Vite via custom `feles-build` system (`tools/feles-build.ts`)
- **Language**: TypeScript (strict)

## Path Aliases (deno.json)

```typescript
#i18n/              -> ./i18n/
#chrome/            -> ./chrome/
#libs/              -> ./libs/
#features-chrome/   -> ./browser-features/chrome/
#modules/           -> ./browser-features/modules/
#ui/                -> ./src/ui/
#themes/            -> ./src/themes/
```

## Coding Conventions

### File Placement

| What               | Where                                                         | Framework   |
| ------------------ | ------------------------------------------------------------- | ----------- |
| Browser UI feature | `browser-features/chrome/common/{name}/`                      | SolidJS     |
| Firefox API module | `browser-features/modules/modules/{name}.sys.mts`             | Firefox ESM |
| Settings page      | `browser-features/pages-settings/src/app/{name}/`             | React       |
| Actor (IPC)        | `browser-features/modules/actors/{Name}Parent\|Child.sys.mts` | Firefox ESM |

### Feature Auto-Discovery

`browser-features/chrome/common/mod.ts` uses `import.meta.glob("./*/index.ts")` -- adding a directory with an `index.ts` under `common/` is sufficient. No manual registration needed.

Actor registration is manual: add entries to the `JS_WINDOW_ACTORS` object in `browser-features/modules/modules/BrowserGlue.sys.mts`.

### Type Definitions

Separate types into dedicated `types.ts` files. Exception: `.sys.mts` files may include inline types.

### No `any`

Never use `any`. Use explicit types or `unknown`.

### SolidJS Pattern (Browser Chrome)

```typescript
import { noraComponent, NoraComponentBase } from "#features-chrome/utils/base";
import { render } from "@nora/solid-xul";
import { createSignal } from "solid-js";

@noraComponent(import.meta.hot)
export default class MyFeature extends NoraComponentBase {
  init(): void {
    /* ... */
  }
}
```

- Always use `@noraComponent(import.meta.hot)` decorator for HMR support
- Use `createSignal` / `createMemo` for reactive state -- never mutate variables directly

### Firefox ESM Modules (.sys.mts)

```typescript
const { SomeService } = ChromeUtils.importESModule(
  "resource://floorp/lib/SomeService.sys.mjs",
);
```

### React Pattern (Settings Pages)

```typescript
export default function MyPage() {
  const [value, setValue] = useState("");
  return <div className="p-4">...</div>;
}
```

### i18n

Translations use i18next-style `{{variable}}` interpolation and `_plural` suffix keys. Add strings to at least `i18n/en-US/` and `i18n/ja-JP/`. Organized by feature namespace in `browser-chrome.json`.

### Error Handling

Use try/catch with `console.error("[FeatureName]", ...)` prefix for log messages.

## Testing

Tests run **inside the actual Firefox browser**, not in Deno/Node. They are plain TypeScript functions with a custom harness (`test_harness.ts` providing `assert`, `assertEquals`, `TestCase`), not `Deno.test()`.

```typescript
// @colocated-env browser
import { type TestCase, assert } from "../../../test/utils/test_harness.ts";

function testSomething(): void {
  assert(condition, "message");
}

export function runAllTests(): void {
  const tests: TestCase[] = [{ name: "something works", fn: testSomething }];
  // ...run and collect failures
}
```

Colocated in `test/` directories next to source. The runner discovers them automatically.

## Dev Server Ports

- 5173: Main features
- 5174-5177: Other pages
- 5178: Settings pages
- 5181: Feature loader (bridge)