espai: Instructions file for Codex

Agent Guidelines

Coding conventions for this project. Follow these when writing or modifying code.

Kept plain

The native host is one main.rs with four dependencies; the extension is six files the browser loads as they are — no bundler, no npm, no build step beyond copying them next to the manifest rendered from the template in extension/. Anything you add should pay for the loss of "read one file, understand the system".

The style rules below favour locally-readable code over idiomatic density. They are choices, not oversights — do not "modernize" them into iterator chains, combinator pipelines, or extracted abstractions.

Generic primitives, never site adapters

No twitter.js, no instagram.js. Those sites regenerate their markup continuously, so a selector committed here breaks within weeks with nothing to warn us but a user reporting that likes silently stopped working. Snapshot-with-refs, trusted input and the network capture are site-agnostic and together they are enough. Anything site-shaped belongs in the agent's prompt, where it costs nothing to be wrong.

Never write to stdout

println! is a fatal bug. stdout is the native messaging channel: one stray byte desynchronises the length-prefixed frames, Chrome sees a garbage length and kills this process. The symptom is a silent disconnection, not an error.

Diagnostics go to stderr via eprintln!, prefixed espai:. We inherit Chrome's stderr, so they land wherever Chrome was started from — a terminal, or nowhere. Nothing may depend on a human seeing them.

How Chrome starts and kills this process

• One host process per connectNative(), not per tab or per browser, and lazily: nothing runs until the service worker connects. argv[1] is the calling extension's origin, and the working directory is unspecified, so never use a relative path.
• Chrome, Chromium, Edge and Brave each read the host manifest from their own profile root, and one in the wrong root is silently ignored — the extension loads fine and the host never starts. make install-chrome / install-chromium copy it where that browser looks.
• Those targets fail on a profile root that does not exist rather than creating one, since a manifest under ~/.config/google-chrome on a Chromium-only machine is a directory that looks installed and is never read. Edge and Brave get no target for the same reason. install.sh writes every root that already exists and creates none.
• Manifests point at bin/espai, which release copies out of target/. A path into target/ breaks on the next cargo clean, and a missing binary looks exactly like a missing manifest.
• version in Cargo.toml and in manifest.chromium.json.in are bumped in the same commit — the halves speak a private frame protocol and ship as one thing. make check-version enforces it, and Chrome refuses a version that goes backwards.
• Shutdown is EOF on stdin, so UnexpectedEof on the length read is the ordinary exit path, not an error to log loudly.