web-api-cat 0.2.0

# CLAUDE.md -- Rust Project Conventions

## Philosophy

Functional, type-driven, domain-driven.

## Architecture

- Modules by domain context.
- One module per concern (error, document, element, fetch, install).
- Thin lib.rs that exposes `install(env, heap, html_doc)`.

## Types

- Sum types for error variants.
- No public struct fields.
- `#[must_use]` on getters and constructors.

## Error Handling

- Single project-wide `Error` enum.
- Display + std::error::Error impls by hand; no thiserror, no anyhow.
- Never panic.

## Style

- Prefer match over if/else, except on bool.
- No `return` keyword.
- No `mut`.
- Combinators over loops.
- Never match on Option<_>; use combinators.
- No unwrap()/expect() anywhere.
- No loop or for.
- No scan.
- No Rc/Arc.
- No naked `as` casts.
- Exhaustive matches; no `_` wildcard arm on enums.

## Traits

- No dyn Trait.
- Implement standard traits over ad-hoc methods.

## Linting

```toml
[lints.clippy]
all = { level = "deny", priority = -1 }
pedantic = { level = "warn", priority = -1 }
needless_pass_by_value = "warn"
manual_map = "warn"
```

## Verification

- Always run `RUSTFLAGS="-D warnings" cargo clippy --all-targets`.
- Always run `cargo fmt`.

## Testing

- Tests return `Result<(), Error>` and propagate failures with `?`.
- No assert!, assert_eq!, panic!, unreachable!, unwrap, expect.

## Dependencies

- `boa-cat = "0.2"` -- JS engine.
- `html-cat = "0.1"` -- source DOM tree.
- `net-cat = "0.1"` -- HTTP transport for `fetch`.
- `proptest`, `ecma-lex-cat`, `ecma-parse-cat` dev-deps.
- No path dependencies.

## Documentation

- `///` doc comments on every public item.
- `# Examples` with runnable code blocks.

## Layer context

This crate is the **JS ↔ DOM/fetch bridge**:

1. `boa-cat` -- JS engine.
2. `html-cat`, `css-cat`, `dom-cat`, `layout-cat`, `paint-cat`, `net-cat` -- rendering + network.
3. **`web-api-cat`** -- exposes the DOM and fetch to scripts.
4. `tauri-runtime-servocat` -- meta-crate.

## Strategy

DOM data lives entirely in the boa-cat heap as a tree of Objects.  Native callables look up element data via the heap-handle passed as `this`, then return a new wrapping value.  Mutations create new heap objects (e.g. `setAttribute` returns the new element-object). Scripts hold the same handles before and after; the underlying boa-cat heap threads the new state through `evaluate_program_with`.

## v0.2 scope (current)

- `document.getElementById(id)` -- walks the document tree, returns the matching element-object or `null`.
- `document.querySelector(selector)` -- limited selector subset (`tag`, `.class`, `#id`, `tag.class`, `tag#id`).
- Element properties: `tagName`, `id`, `className`, `textContent`, `children` array.
- Element methods: `getAttribute(name)`, `setAttribute(name, value)`, `hasAttribute(name)`.
- `fetch(url)` -- synchronous net-cat call returning `{ ok, status, statusText, text, headers }` object.
- `extract_document(document_value, heap)` -- walks the post-script JS-side DOM tree and reconstructs a `dom_cat::Document`, so callers (e.g. `tauri-runtime-servocat`) can back-propagate scripted mutations into layout-cat / paint-cat.  Text content is synthesized as a single Text child of each leaf element; comments and original text-node positions are not preserved.

## Deferred to v0.3+

- Full CSS selector syntax in `querySelector` (combinators, attribute selectors, pseudo-classes).
- Async `fetch` (Promise-based; needs comp-cat-rs scheduler integration).
- `Element.appendChild`, `removeChild`, `insertBefore`.
- `Element.style` and computed styles.
- Event API.
- `XMLHttpRequest`, `WebSocket`.
- HTTPS support (waits on net-cat's TLS feature).
- Faithful round-trip of text-node positions and comments through `extract_document`.