CLAUDE.md · Floorp-Projects/Floorp

Sections

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

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

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

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
```

## Architecture (5 Layers)

```notes
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)
- 5186: New tab page

## dev-tool — Browser Inspection CLI

`deno task dev-tool` communicates with a running Floorp instance via the **Marionette protocol** (Firefox's TCP-based WebDriver). All browser commands require the browser to be running (started via `dev-tool start` or `feles-build dev`).

### Process Management