Added README to all crates

Author: jaytaph

crates/gosub_config/README.md

@@ -0,0 +1,36 @@
+# gosub_config
+
+The runtime settings store of the Gosub engine. Schema-agnostic by design: the caller
+supplies the schema (known keys, defaults, constraints) and only known keys can be read
+or written — this crate ships no settings of its own. The engine's schema lives in
+`gosub_engine` (`settings.json` / `useragent-settings.json`), which seeds a `Config` via
+`gosub_engine::default_settings()`.
+
+Not to be confused with compile-time component selection (`ModuleConfiguration` /
+`DefaultRenderConfig`) — that is a different mechanism, documented in
+[docs/configuration.md](../../docs/configuration.md). This crate is for values that
+change at runtime.
+
+## Entry points
+
+- `Config` — cheap-to-clone handle (`Arc<RwLock<ConfigStore>>`); `Config::new(schema)`
+  or `with_storage(schema, storage)`. Typed getters (`get_bool`, `get_uint`, ...),
+  wildcard `find`, namespaced `merge`, and change **subscriptions**
+  (`subscribe`/`unsubscribe` with wildcard patterns).
+- `StorageAdapter` — the pluggable persistence trait, with three implementations:
+  `MemoryStorageAdapter` (default), `JsonStorageAdapter`, and `SqliteStorageAdapter`
+  (not available on wasm32).
+- `settings::{Setting, SettingInfo, Constraint}` — the value model: typed settings with
+  a wire format (`b:true`, `u:1000`, `s:...`) and constraints (enums, numeric ranges).
+- `HasConfig` — accessor bound so subsystems depend on `T: HasConfig` rather than a
+  concrete context type.
+
+## Trying it
+
+The `config-store` example in the workspace root demonstrates the store:
+`cargo run --example config-store`.
+
+## Further reading
+
+- [docs/configuration.md](../../docs/configuration.md) — the two configuration layers
+  and where this store fits

crates/gosub_css3/README.md

@@ -0,0 +1,48 @@
+# gosub_css3
+
+The CSS3 system of the Gosub browser engine: tokenizer, parser, selector matcher, cascade,
+and property-value validation. Parsing follows the csstree (MIT) parser design. A stylesheet
+goes from text to a `CssStylesheet` (rules, selectors, declarations), and `Css3System`
+implements the `CssSystem` trait from `gosub_interface` — selector matching, cascade, and
+computed-value resolution for the rest of the engine.
+
+## Entry points
+
+- `Css3::parse_str(data, config, origin, source_url)` / `Css3::parse_stream(...)` —
+  stylesheet text → `CssStylesheet`.
+- `system::Css3System` — the `CssSystem` implementation; the main integration point
+  (`Stylesheet = CssStylesheet`, `Property = CssProperty`, `Value = CssValue`).
+- `load_default_useragent_stylesheet()` — the embedded `resources/useragent.css`.
+- `matcher::syntax_matcher` — validates property values against their formal grammar
+  (definitions embedded from `resources/definitions/*.json`).
+
+## What lives here
+
+| Module | Role |
+|--------|------|
+| `tokenizer`, `parser` | CSS text → AST, one parser module per construct (selectors, at-rules, calc, ...) |
+| `ast`, `node` | The AST and `convert_ast_to_stylesheet` |
+| `stylesheet` | The flattened `CssStylesheet` model and `CssValue` |
+| `matcher` | Selector matching, cascade, shorthand expansion, value-grammar validation |
+| `system` | `Css3System`, property computation, vendor-prefix normalization |
+| `functions` | `var()`, `attr()`, and the math functions (`calc`, `clamp`, `min`, `max`) |
+| `colors`, `walker` | Color parsing (named colors, hex, hsl, oklab/oklch) and an AST pretty-printer |
+
+## Known limitations
+
+- Most at-rules are dropped during AST → stylesheet conversion; only `@font-face` and
+  `@layer` survive (the latter without layer-cascade semantics), and `@media` is not
+  yet honored.
+- Not every longhand has a value-grammar definition, and the `background` shorthand is
+  only partially recovered.
+
+A recursion guard (`MAX_RECURSION_DEPTH = 64`) protects the parser against
+stack-overflowing input. The `unresolved_syntax` feature gates experimental
+syntax-matcher paths.
+
+## Further reading
+
+- [docs/css.md](../../docs/css.md) — the full parse → match → cascade → computed-value flow
+- [docs/interface.md](../../docs/interface.md) — the `CssSystem` trait contract
+- [docs/binaries.md](../../docs/binaries.md) — the `css3-parser` tool (run from the repo
+  root: `cargo run --bin css3-parser`; note it parses without validating values)

crates/gosub_engine/README.md

@@ -0,0 +1,50 @@
+# gosub_engine
+
+The primary public API of the Gosub browser engine — the crate you depend on to build a
+user agent or embed the engine. It ties the parser, CSS, layout, and rendering crates
+together behind an async, channel-driven surface: the engine emits `EngineEvent`s, and
+the embedder drives it with `EngineCommand` (engine/zone level) and `TabCommand` (per
+tab, via `TabHandle`). Work in progress; not yet production-ready.
+
+## The model
+
+- **`GosubEngine`** — create, `start()`/`run()`, `subscribe_events()`, `create_zone()`.
+- **Zones** — separate profiles. Each `Zone` owns its cookie jar and storage isolation;
+  tabs live inside a zone.
+- **Tabs** — browsing contexts driven through `TabHandle`; per-tab runtime state
+  (DOM, render pipeline caches) lives in a `BrowsingContext`.
+- **`EngineConfig`** — set-once engine configuration via `EngineConfig::builder()`;
+  the dynamic settings store (`default_settings()`, backed by `gosub_config`) handles
+  runtime-changeable values.
+- **`DefaultRenderConfig<Backend, FontSystem, Sink>`** — the zero-sized marker type that
+  wires the standard `gosub_html5` + `gosub_css3` stack to your chosen render backend and
+  font system. The default is headless (`NullBackend` + `ParleyFontSystem`).
+
+## What lives here
+
+| Area | Contents |
+|------|----------|
+| `engine/` | `GosubEngine`, zones, tabs, events, `BrowsingContext`, UA policy, settings store |
+| `net` | The engine side of networking: dedicated Tokio I/O thread, routing and content decisions, streaming bodies. The fetcher core is the external [gosub-sonar](https://github.com/gosub-io/gosub-sonar) crate |
+| `cookies` | `CookieJar` with in-memory, JSON, and SQLite stores (feature `sqlite_cookie_store`, on by default) |
+| `storage` | localStorage/sessionStorage services with partitioning policies |
+| `resource_pipeline` | Per-asset-kind fetch/parse pipelines (html, css, js, image, font) |
+| `html` | `DefaultRenderConfig`, `RenderConfiguration`, document parsing entry points |
+
+Other features: `metrics` (engine metrics module), `ui_eframe` / `winit` / `wayland` /
+`x11` (GUI-toolkit integration glue).
+
+## Getting started
+
+Start from [`examples/hello-world.rs`](../../examples/hello-world.rs), then the
+[tutorial](../../docs/tutorial.md). The headless path is documented in
+[docs/headless.md](../../docs/headless.md) with `gosub-screenshot` as the reference.
+
+## Further reading
+
+- [docs/tutorial.md](../../docs/tutorial.md) — engine / zone / tab concepts, first integration
+- [docs/zones-and-tabs.md](../../docs/zones-and-tabs.md) — the runtime model
+- [docs/configuration.md](../../docs/configuration.md) — choosing backend and font system
+- [docs/cookies.md](../../docs/cookies.md), [docs/datastores.md](../../docs/datastores.md) — isolation and persistence
+- [docs/network/](../../docs/network/) — the networking architecture
+- [docs/resource-pipeline.md](../../docs/resource-pipeline.md) — async resource loading

crates/gosub_fontmanager/README.md

@@ -0,0 +1,36 @@
+# gosub_fontmanager
+
+Concrete font-system implementations for the Gosub browser engine: font registration,
+CSS-query resolution (including raw font bytes), shaping into positioned glyph runs, and
+measurement. The `FontSystem` trait itself lives in `gosub_interface`; this crate only
+provides implementations. None of them draws glyphs — painting is each render backend's
+job.
+
+## The implementations
+
+| Type | Backing libraries | Availability | Typical pairing |
+|------|-------------------|--------------|-----------------|
+| `ParleyFontSystem` | Parley + Fontique | always | default; used with the Vello backend |
+| `CosmicFontSystem` | cosmic-text + rustybuzz + swash | always | pure-Rust alternative, not wired into any default config |
+| `PangoFontSystem` | fontconfig + Pango/HarfBuzz | feature `pango` | the Cairo configs |
+| `SkiaFontSystem` | Skia textlayout | feature `skia` | the Skia configs |
+
+Each maps the shared `gosub_interface` value types (`TextStyle`, `FontQuery` /
+`ResolvedFont` / `FontBlob`, `ShapedText` / `ShapedRun` / `ShapedGlyph`) onto its backing
+library. Examples pick a font system in their `type AppConfig` alias via
+`DefaultRenderConfig<Backend, FontSystem>`.
+
+## Notes
+
+- No default features; only Parley and Cosmic compile without opting in. `pango` pulls in
+  GTK4/pangocairo/fontconfig; `skia` pulls in `skia-safe`.
+- The Pango system uses raw fontconfig FFI serialized behind a global mutex (concurrent
+  fontconfig configuration mutation can segfault) — this is why the crate relaxes the
+  workspace `unsafe_code` lint from forbid to deny.
+
+## Further reading
+
+- [docs/fonts.md](../../docs/fonts.md) — the full picture: font systems vs text
+  rasterizers, and the comparison table
+- [docs/configuration.md](../../docs/configuration.md) — how a config pairs a backend
+  with a font system

crates/gosub_html5/README.md

@@ -0,0 +1,44 @@
+# gosub_html5
+
+The HTML5 tokenizer and parser of the Gosub browser engine, plus the DOM it produces. The
+tokenizer implements the WHATWG state machine (74 states, character references, error
+recovery), the tree builder implements the 23 insertion modes, and the result is a
+`DocumentImpl` — an arena-backed DOM addressed by `NodeId` handles, implementing the
+`Document` trait from `gosub_interface`.
+
+## Entry points
+
+- `Html5Parser::parse_document(&mut stream, &mut doc, options)` — parse a full document
+  from a `ByteStream`; `parse_fragment(...)` for the fragment case.
+- `html_compile::<C>(html)` — one-call convenience: string in, document out.
+- `DocumentBuilderImpl::new_document(url)` — create an empty document to parse into.
+- `writer` — serialize a document back to HTML.
+
+## What lives here
+
+| Module | Role |
+|--------|------|
+| `tokenizer` | WHATWG tokenizer state machine, tokens, named character references |
+| `parser` | Tree construction: insertion modes, quirks handling, foreign content |
+| `document` | `DocumentImpl` + `NodeArena` storage, builder, fragments, task queue |
+| `node` | `NodeImpl` node payloads, arena, element data, visitors |
+| `writer` | DOM → HTML serialization |
+| `testing` | Harness for the vendored WHATWG html5lib-tests suite |
+
+## Features and testing
+
+- Cargo features `debug_parser` / `debug_parser_verbose` gate extra parser tracing.
+- Conformance tests run against the vendored html5lib-tests suite in `tests/data/`;
+  the `html5-parser-test` and `parser-test` binaries live in the root package, so run
+  them from the repo root: `cargo run --bin html5-parser-test`.
+- Criterion benches: `tokenizer`, `tree_construction`, `html_parser` (the latter installs
+  a counting allocator, which is why this crate relaxes the workspace `unsafe_code` lint).
+
+## Further reading
+
+- [docs/html5.md](../../docs/html5.md) — tokenizer/tree-builder structure and the
+  html5lib test harness
+- [docs/binaries.md](../../docs/binaries.md) — the `gosub-parser`, `html5-parser-test`
+  and `display-text-tree` component tools
+- [docs/interface.md](../../docs/interface.md) — the `Html5Parser` / `Document` trait
+  contracts this crate implements

crates/gosub_jsapi/README.md

@@ -0,0 +1,22 @@
+# gosub_jsapi
+
+Implementations of browser Web APIs for Gosub, written as plain Rust with no knowledge of
+any JavaScript engine — the `gosub_webinterop` macros are the intended path for exposing
+them into a script context.
+
+Currently exactly one API exists: **`console`**, per the
+[WHATWG console spec](https://console.spec.whatwg.org/).
+
+## Entry points
+
+- `console::Console` — `new(Box<dyn Printer>)`; implements `log` / `info` / `warn` /
+  `error` / `debug`, `assert`, `trace`, `dir`, counting (`count` / `count_reset`),
+  grouping (`group` / `group_collapsed` / `group_end`), and timers (`time` / `time_log` /
+  `time_end`).
+- `console::Printer` — the pluggable output sink; `WritablePrinter<W>` adapts any
+  `std::io::Write`, and `Buffer` is an in-memory sink used by the tests.
+
+## Further reading
+
+- [docs/javascript.md](../../docs/javascript.md) — where the Web APIs sit in the
+  scripting stack and the current integration status

crates/gosub_lattice/README.md

@@ -0,0 +1,43 @@
+# gosub_lattice
+
+The CSS table layout engine of the Gosub workspace — the table algorithm (CSS 2.1 §17)
+that general-purpose flex/grid layouters don't cover. The crate is deliberately
+standalone: its only dependency is `anyhow`, and it talks to the host layout engine
+exclusively through the `TableTree` adapter trait.
+
+## How it plugs in
+
+The host implements `TableTree` (node traversal, `table_role`, CSS property access, a
+`layout_cell` callback for measuring cell content, and `set_layout` write-back), then
+calls `compute_table_layout` once per table. The live adapter is `PipelineTableTree` in
+`gosub_render_pipeline`; `mock::MockTable` provides a DOM-free implementation for tests
+and experiments.
+
+## What lives here
+
+| Module | Role |
+|--------|------|
+| `model` | Walks the subtree into a typed `TableModel`, with CSS 2.1 anonymous-box fixups |
+| `grid` | Grid placement: resolves cells to `(row, col)` honoring colspan/rowspan |
+| `sizing` | Column-width algorithm and row heights (via the `layout_cell` callback) |
+| `compute` | `compute_table_layout`: section ordering, placement, write-back |
+| `types` | The flat data types crossing the adapter boundary (`CellLayout`, `CssLength`, ...) |
+| `mock` | `MockTable` builder for standalone use |
+
+## Trying it
+
+`cargo run --bin table_console -p gosub_lattice` renders demo tables as ASCII grids.
+
+## Known limitations
+
+`rowspan > 1` heights are not distributed yet; `border-collapse`, `table-layout: fixed`,
+and captions are parsed into the model but not consumed (layout always uses
+separate-borders + auto sizing); column widths scan only the first non-empty row.
+
+## Further reading
+
+- [docs/lattice.md](../../docs/lattice.md) — the algorithm and the `TableTree` contract
+- [docs/render-pipeline/layout.md](../../docs/render-pipeline/layout.md) — the lattice
+  write-back into the pipeline's layouter
+- [docs/two-worlds.md](../../docs/two-worlds.md) — why lattice cooperates with the
+  general layouter instead of replacing it