Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (57 loc) · 3.03 KB

AGENTS.md

File metadata and controls

72 lines (57 loc) · 3.03 KB
Raw

Repository Instructions — meow-memorizing

WXT + React 19 browser extension (Bun) that highlights words from the user's list on any page. The hot path — scanning page text for those words — is handled solely by a Rust→WASM Aho-Corasick backend (crates/wasm-matcher). There is no JS fallback: a browser without WASM is unsupported by design. The loader (src/wasm/matcherLoader.ts) throws on init failure rather than degrading.

Rust Rules

  • Module organization: no mod.rs; use folder-named files (e.g. src/matcher.rs, not src/matcher/mod.rs).
  • Error propagation: use ?; no bare unwrap(); expect("reason") when needed; document any forced unwrap() in ///.
  • unsafe disabled by default; document memory-safety guarantees inline if used.
  • Prefer traits, pattern matching, iterators; avoid unnecessary Clone.
  • Format with cargo fmt --all; pass cargo clippy -p wasm-matcher --target wasm32-unknown-unknown -- -D warnings.
  • Every .rs file: //! top comment for design intent. Public items: /// English doc covering intent and parameters.
  • The WASM boundary stays thin: only set_words / find_matches / find_deleted_matches cross it. Keep DOM work in JS.

Build mode

  • The wasm crate requires --release (browser payload size + runtime perf). Debug builds remain fine for cargo check/tests.
  • Browser artifacts: scripts/build-wasm.sh (cargo release wasm32 + wasm-bindgen --target web) → scripts/inline-wasm.ts embeds the .wasm as base64 so the content script is self-contained (no fetch / no web_accessible_resources). Generated files under src/wasm/ are gitignored and regenerated by bun run wasm.

Toolchain

  • wasm32-unknown-unknown target + wasm-bindgen-cli are required. The wasm-bindgen crate is pinned to =0.2.122 to match the CLI exactly; the build script verifies this.
  • On the NixOS host the toolchain is declarative (no rustup); rustup machines get the target via rust-toolchain.toml.
  • Frontend uses bun (not pnpm/npm).

Workflow

  • Atomic commits: one logical, runnable change per Conventional Commit.
  • When behavior/workflow changes, update the relevant README.md in the same commit. Every code directory has a README.md.

Tooling

  • Rust: bun run check:rust, bun run lint:rust, cargo test -p wasm-matcher.
  • Web: bun run dev|build|compile.
  • wasm: bun run wasm.
  • e2e: bun run test:e2e (Playwright, loads the built extension).

E2E environment

  • Headless Chrome (≥ ~128, host has 148) refuses --load-extension of an unpacked extension, so tests/e2e/highlight.spec.ts self-skips on a display-less sandbox/CI host. Run it for real with a display:
    • local desktop: headed system Chrome loads the extension (manual equivalent: bun run dev);
    • CI / headless host: xvfb-run -a bun run test:e2e.
  • tests/e2e/matcher.bench.spec.ts (WASM correctness + perf) does not load the extension and runs everywhere.

Communication

  • Communicate with the user in Chinese.
  • Surface ambiguity before risky or irreversible changes.