Imported from FENBROWSER/fenbrowser (AGENTS.md). Install upstream with npx skills add FENBROWSER/fenbrowser. Copyright stays with the author.

AGENTS.md — FenBrowser Root Guide

This file defines the default operating rules for agents working in FenBrowser.

Mission

Work on FenBrowser with:

• minimal scope
• root-cause fixes
• production-grade behavior
• deterministic verification
• low-regression changes
• compact communication

The browser may be referred to as fen or fenbrowser.

Repository shape

Primary projects:

• FenBrowser.Core — DOM, parsing, resource/network primitives, shared browser types
• FenBrowser.FenEngine — CSS, layout, rendering, scripting, runtime pipeline
• FenBrowser.Host — windowing, input, host integration, OS boundary
• FenBrowser.DevTools — native devtools UI and remote debugging protocol

Other important surfaces:

• FenBrowser.WebDriver
• FenBrowser.Tests
• all tooling and scripts live under scripts/ — never at repo root

Default behavior:

• inspect the smallest relevant project first
• do not scan all projects unless the task is cross-cutting
• do not start in tests/conformance projects unless verification or test work is the task

Non-negotiable rules

1. Reproduce before fixing.
2. Prefer root cause over symptom patch.
3. Keep changes minimal and local.
4. Do not refactor unrelated code.
5. Do not widen scope without evidence.
6. Build or verify the smallest affected surface first.
7. If behavior or architecture meaningfully changes, update the relevant canonical docs in the same change.
8. Do not use platform-specific APIs outside host/platform layers unless the task is explicitly platform work.
9. Treat native resource ownership as critical. Dispose correctly.
10. Keep replies compact unless a deep dive is requested.
11. Keep the repository root clean. Never add scripts or one-off helpers at root — they go in scripts/.

Canonical documentation set

Use only these docs as the authoritative documentation map:

• docs/VOLUME_I_SYSTEM_MANIFEST.md
• docs/VOLUME_II_CORE.md
• docs/VOLUME_III_FENENGINE.md
• docs/VOLUME_IV_HOST.md
• docs/VOLUME_V_DEVTOOLS.md
• docs/VOLUME_VI_EXTENSIONS_VERIFICATION.md
• docs/COMPLIANCE.md
• docs/DEFINITION_OF_DONE.md
• docs/GLOSSARY.md
• docs/INDEX.md
• docs/THIRD_PARTY_DEPENDENCIES.md

Do not assume legacy docs/TechnicalReference/, Part_*, or Volume_*_Tree.md structures are the active documentation contract.

Documentation synchronization rule

Documentation is required when a change affects:

• architecture or subsystem boundaries
• observable runtime behavior
• diagnostics or operator workflow
• verification/test workflow
• compliance/spec-status understanding
• terminology
• third-party dependency inventory or rationale

Small localized fixes do not require doc churn unless they change how the subsystem should be understood.

Mapping:

• Core changes -> VOLUME_II_CORE.md
• FenEngine changes -> VOLUME_III_FENENGINE.md
• Host changes -> VOLUME_IV_HOST.md
• DevTools changes -> VOLUME_V_DEVTOOLS.md
• WebDriver / tests / verification / tooling -> VOLUME_VI_EXTENSIONS_VERIFICATION.md

Additional appendices only when relevant:

• compliance/spec planning -> COMPLIANCE.md
• merge/review gates -> DEFINITION_OF_DONE.md
• terminology -> GLOSSARY.md
• dependency surface -> THIRD_PARTY_DEPENDENCIES.md
• docs navigation/indexing -> INDEX.md

Working style

Default sequence:

1. Restate the bug/task in one sentence internally.
2. Identify the owning subsystem.
3. Inspect only likely files first.
4. Reproduce or verify the failure.
5. Patch the earliest broken stage.
6. Run the smallest meaningful verification.
7. Update docs only if required.
8. Summarize:
   • root cause
   • files changed
   • verification
   • docs touched

Avoid:

• broad repo tours
• speculative rewrites
• architecture changes without evidence
• repeating the user prompt
• long educational explanations unless requested

Debug and artifact workflow

For runtime/rendering issues, prefer this diagnostic order:

1. logs/debug_screenshot.png
2. logs/raw_source_*.html
3. logs/dom_dump.txt
4. logs/fenbrowser_*.log

Default clean-state workflow:

1. kill existing FenBrowser-related processes
2. clear relevant logs/artifacts
3. build/run cleanly
4. allow startup/navigation enough time to settle
5. inspect screenshot + DOM/log artifacts before patching

Diagnostics path policy (strict):

• Runtime artifacts must be written under workspace-root logs/ only.
• Do not write diagnostics to repository root.
• Do not write diagnostics to docs/.
• Applies to generated .txt, .png, .png.meta, .js, .html artifacts.

Result/report policy:

• Use workspace-root Results/ for generated reports and result bundles.
• Keep docs/ limited to maintained documentation sources, not runtime outputs.

Scripts and root-cleanliness policy (strict):

• Every script (.sh, .ps1, .py, .bat, .cmd) lives under scripts/ — never at repo root, including throwaway one-offs.
• Invoke scripts from repo root by path, e.g. bash scripts/run_full_batched.sh; write script-internal paths relative to repo root (cwd), not to the script's own location.
• The repo root holds only: solution/project files, top-level docs (README, AGENTS.md, CLAUDE.md, CODEX.md), config/dotfiles, and the standing project directories. Nothing else accumulates there.
• If a task tempts you to drop a file at root, put it in the right folder (scripts/, logs/, Results/, docs/) instead.

Threading boundaries

UI thread only:

• widgets
• window management
• UI invalidation
• host/UI event handling

Render thread / engine-owned execution only:

• box/layout computation
• paint preparation
• rendering pipeline work

Queued/microtask/event-loop work:

• use the established coordinator/event-loop surfaces
• do not block hot paths with ad hoc synchronous work

Resource and safety discipline

• Use using / deterministic disposal for native Skia and similar native-backed objects.
• Avoid unnecessary allocations in hot paths.
• Prefer pooling/reuse only when it simplifies hot-path cost without obscuring correctness.
• Never let a drawing library define layout semantics.
• Keep state flow explicit; avoid hidden globals.
• Keep Core/FenEngine/WebDriver logic platform-agnostic unless the task is explicitly platform work.

Terminology contract

Use project terms consistently:

• Box / LayoutBox
• Box Tree
• Paint Tree
• Bridge
• Host
• DOM
• Node / Element / ContainerNode
• Microtask

Avoid inventing alternate names for established subsystem concepts.

Verification policy

Choose the smallest verification that can falsify the change.

Typical order:

• focused build of touched project
• focused test slice for the changed path
• broader slice only if the change crosses subsystem boundaries
• full solution build/test only when necessary

Do not run large suites by default when a smaller proof is sufficient.

Test repository roots (mandatory — NEVER search the internet)

The conformance test repositories are local checkouts. All test counts, file searches, result data, and conformance information come from these local paths — never from GitHub, web search, or any remote source:

• test262 root: C:\Users\udayk\Videos\test262
• WPT root: C:\Users\udayk\Videos\wpt

Do not fetch test counts or repo info from github.com or anywhere else — use these local directories.

test262 timeout policy (mandatory, no exceptions)

Every test262 run MUST enforce a 2-second per-test timeout. Any test exceeding 2s is skipped, never awaited — a single test must never hang or block the suite. Always pass --timeout-ms 2000 (CLI) / -TimeoutMs 2000 (scripts) plus a stall watchdog (-StallTimeoutSec 30). This applies to every test262 invocation — quick categories, full chunks, single reruns — with no exception.

test262 real-results tracking (mandatory)

• docs/test262_results.md is the committed source of truth for per-category pass rates (regenerated by scripts/test262_report.py from the local batched store). To check status, READ that file — do not re-run the full ~53k suite. A full run is for occasional rebaselining only.
• Work loop: pick a category from that file's worklist → find the shared root cause in Results/test262/batched/b_<tag>.json (failures[].details) → fix the engine → re-run only that category with bash scripts/rerun-test262-category.sh <category> (overwrites its b_<tag>.json and regenerates the doc) → commit the updated docs/test262_results.md with the fix.

test262 execution & results policy (mandatory)

• Run category by category, not the whole suite blindly. Drive one category at a time.
• A category is done at 100% pass rate — push every category to zero failures. No gate. Stay on a category (localize-and-fix loop) until it clears.
• Results layout — everything under Results/test262/:
  • Results/test262/full/ — full-suite run results (summary + per-category breakdown of a full pass).
  • Results/test262/categories/ — individual per-category run results.
• Clear stale results and keep at most one day of history. Before/after a run, purge result files older than 24h so the folders only hold the latest day. Do not let Results/test262/ accumulate. (Results/ is gitignored — this is local housekeeping, never committed.)

Commit and push discipline

Ship work in feature/component-sized units, one at a time. For each unit, before starting the next:

1. Clean build of the affected project(s) succeeds with zero errors.
2. Verify with test262, WPT, or local unit tests (whichever exercises the change); it must pass with no new failures.
3. Only if verification passed, commit — human-style messages, split into the smallest coherent chunks (one logical change per commit).
4. Push the committed work.
5. Then move to the next unit.

Hard rules:

• Never commit unbuilt or unverified code.
• Never batch multiple unrelated features/fixes into one commit.
• Never leave a completed, verified unit unpushed before starting the next one.
• Do not add AI/co-author trailers to commit messages.

Output contract for agent responses

Default response format:

1. Root cause
2. Files inspected/changed
3. Minimal patch plan or applied fix
4. Verification command/result
5. Docs updated or not needed

Keep the response brief and technical. Do not restate obvious context. Do not add background unless it materially helps the next action.