Major refactor of composition model, and API

.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+updates:
+  # Zig package deps (build.zig.zon) aren't supported by Dependabot; the submodules
+  # carry the vendored catalogues. So the actionable surface here is the CI actions —
+  # keep them patched.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -29,6 +29,8 @@ jobs:
         uses: mlugg/setup-zig@v2
         with:
           version: 0.16.0
+      - name: Format check
+        run: zig fmt --check src/ tools/ build.zig
       - name: Build (native)
         run: zig build -Doptimize=ReleaseFast
       - name: Test

CLAUDE.md

@@ -0,0 +1,102 @@
+# tile57 — engine conventions
+
+## The API style
+
+The public surface (include/tile57.h, src/tile57.zig, bindings/go) follows one
+style. Hold every new or renamed symbol against it.
+
+**The pipeline is the organizing principle.** Everything is bake, then compose
+(or bake, then render): source charts bake once to per-chart archives; every
+output is produced from baked archives. Sections, in order: Version, Errors,
+Bake, Render (the chart), Compose, Style, Util. The header, the Zig public
+root, and the docs all follow that same section order.
+
+**The unit is a chart, never "cell" in prose.** An ENC cell IS one chart at one
+compilation scale. "Cell" survives only as spec-facing vocabulary: one
+first-use definition ("a *cell*, in the spec's vocabulary"), the `cell` tile
+property and other wire-format names, `<cell.000>` CLI placeholders and the
+`cell`/`cells` CLI commands, and the s57/geometry module internals (the domain
+that parses cells).
+
+**Everything is in a family, and the family token always leads.** The prefix
+names what a call runs against; never bury the family token mid-name.
+
+1. *Handles namespace under their noun and mirror each other.* `tile57_chart`
+   (one open baked archive) and `tile57_compose` (the runtime compositor) are
+   peers: `tile57_chart_open` / `_close` / `_get_info` / `_tile` / `_png` /
+   `_query` ↔ `tile57_compose_open` / `_close` / `_get_meta` / `_tile` /
+   `_png` / `_query`. A noun prefix means the first parameter is that handle —
+   the C spelling of a method.
+2. *Handle-free families lead with their section token, then what the call
+   acts on or yields* — the token's part of speech follows the section, so the
+   name reads naturally after it. `tile57_bake_*` is a verb family
+   (`bake_chart_bytes`, `bake_tree` — "bake the X"); `tile57_enc_*` is a domain
+   family (the raw S-57 source readers — ENC is the ONE vocabulary for raw
+   source data, never s57_/source_/scan_ variants); `tile57_style_*` is a
+   product family (`style_build` / `style_diff` / `style_template`, never
+   `build_style` — "the style's build/diff/template"). Small POD/domain noun
+   families follow the same shape: `pmtiles_metadata`, `status_str`,
+   `mariner_defaults`, `colortables_default`, `assets_free`.
+3. *Bare `tile57_` is the library itself* — process/library-level plumbing
+   only: `tile57_version`, `tile57_free`, `tile57_warmup`. No handle method is
+   ever bare.
+
+In Zig the namespace is the family, with the same two consequences: a member
+never repeats its namespace (`ComposeSource.openFiles`, never
+`compose.openComposeSourceFiles`; `compose.tile`, never `compose.composeTile`),
+and the two handles mirror (`Chart.openPmtilesPath` ↔ `ComposeSource.open` /
+`.openFiles`).
+
+**Outputs are named by what you get, never by how it's produced or served.**
+`tile`, `png`, `pdf`, `canvas`, `surface`, `query` — not serve/render/build/
+generate. The chart and the compositor offer the SAME output set, so the names
+mirror exactly: `tile57_chart_png` ↔ `tile57_compose_png`, `tile57_chart_tile`
+↔ `tile57_compose_tile`, and so on. The compositor is "many charts in, one
+chart out"; keep that symmetry when adding an output — it goes on both handles
+or has a stated reason not to.
+
+**The status model is universal.** Every call that can fail returns
+`tile57_status` (never a bare int, count, or bool) and takes an optional
+caller-owned `tile57_error*` as its LAST parameter. Out-parameters come after
+inputs and are ALWAYS defined on return — the result on TILE57_OK, NULL/0
+otherwise. "Nothing produced" is NOT a failure: OK with a NULL/zero out. Every
+pointer argument is BADARG-checked (no NULL derefs across the ABI). Counts and
+flags come back through optional out-pointers (NULL to ignore), not return
+values. Say "call that can fail" in docs, not "fallible".
+
+**Memory has one rule.** Calls that return bytes allocate `*out`; the caller
+releases with `tile57_free(ptr)` — buffers are length-prefixed at allocation,
+so the pointer is all it needs. POD across the seam: no Zig errors, slices, or
+optionals cross the ABI.
+
+**Ownership and borrowing are explicit.** The compositor BORROWS its charts
+(charts outlive it; close the compositor first). A path-opened chart mmaps its
+file (the file stays in place). No handle is internally synchronized; document
+lifetime + threading on every handle-producing call.
+
+**The Zig public root is curated, not a module mirror.** src/tile57.zig shapes
+the public namespace by the API sections; when module layering puts an
+implementation elsewhere (e.g. composed view renders live beside Chart because
+the `compose` module is a dependency leaf without the render path), the root
+still surfaces it under the name it belongs to (`tile57.compose.renderView`).
+Public surface trumps internal layering.
+
+**Go bindings track shape, not spelling.** Idiomatic Go names over the same
+structure: `Open`/`OpenBytes` on the archive, package-level `Charts`/`Features`/
+`FeaturesBytes`/`CatalogEntries` for the enc readers, `ComposeSource.Tile`
+mirroring `tile57_compose_tile`, errors as wrapped sentinels
+(`errors.Is(err, tile57.ErrParse)`).
+
+## Other repo rules
+
+- Never reference specs/*.md in code comments (specs/ is never committed);
+  describe designs inline.
+- Docs read standalone: present-tense capability statements, no prior-version
+  framing ("now supports", "anymore"), no "plain language", no "fallible", no
+  "seam" in user-facing docs.
+- Never `git add -A` (vendor/ submodules; charts/ + test/ hold huge untracked
+  local data). Stage explicit paths. Commit after every change.
+- Never hardcode machine-specific paths in code or tests; real-cell paths come
+  from args/env.
+- Validate conversion/portrayal changes on real ENC_ROOT cells, not just unit
+  tests.

README.md

@@ -1,9 +1,9 @@
 <h1 align="center">tile57</h1>
 
 <p align="center">
-  <b>⚓ A high-performance, low-memory S-57/S-101 chart engine: vector tiles, S-52 styles, PNG and PDF.</b><br>
-  tile57 turns IHO S-57 ENC cells into Mapbox Vector Tiles with a matching MapLibre S-52
-  style, or renders finished charts directly to PNG and PDF — one Zig library with a
+  <b>⚓ An S-57/S-101 chart engine: vector tiles, S-52 styles, PNG and PDF.</b><br>
+  tile57 turns IHO S-57 ENC cells into vector tiles (MLT or MVT) with a matching MapLibre
+  S-52 style, or renders finished charts directly to PNG and PDF — one Zig library with a
   C ABI, compiled natively or to WASM.
 </p>
 
@@ -48,11 +48,10 @@ entirely with AI assistance. A few specific goals shape its design:
 - **Language-agnostic embedding.** A thin C ABI (`libtile57.a`) bridges the Zig core to any
   language with C FFI. Go bindings ship in the repo; others are straightforward additions.
 
-- **An engine anyone can build on.** The end goal is an easy-to-use S-57/S-100 chart
-  rendering engine that anyone can use to build their marine app ideas — without first
-  becoming an IHO spec expert. Open a chart, get tiles, PNGs, or PDFs; the S-52 rules,
-  portrayal catalogue, and mariner settings are the engine's problem. Ideas it should make
-  easy:
+- **An engine to build on.** The goal is an S-57/S-100 chart engine you can use to build
+  a marine app without first becoming an IHO spec expert. Open a chart, get tiles, PNGs,
+  or PDFs; the S-52 rules, portrayal catalogue, and mariner settings are the engine's
+  problem. It aims to support:
   - an **anchor alarm** that draws your swing circle over a real chart,
   - a **Windy plugin** overlaying forecast weather on ENC charts,
   - a **native cross-platform Qt6 C++ chartplotter**,
@@ -61,46 +60,49 @@ entirely with AI assistance. A few specific goals shape its design:
 ---
 
 **tile57** decodes NOAA/IHO **S-57** ENC cells and generates **vector tiles** by
-`(z, x, y)` — MapLibre Tiles (MLT, the default bake format; MapLibre GL JS ≥ 5.12
-decodes them natively) or Mapbox Vector Tiles (`--format mvt`) — running the
+`(z, x, y)` — MapLibre Tiles (MLT, the default; MapLibre GL JS ≥ 5.12
+decodes them natively) or Mapbox Vector Tiles — running the
 official IHO **S-101 Portrayal Catalogue** in embedded Lua to produce S-52
 nautical portrayal. Alongside the tiles it emits a **MapLibre GL style** and the
 portrayal **assets** it references — colour tables, line styles, and the sprite
 + area-fill pattern atlases — so a renderer like
 [MapLibre](https://github.com/maplibre/maplibre-native) can draw a chart directly.
 
-It is **high-performance and low-memory** by design:
+It holds only its working set:
 
 - **Lazy, per-cell work.** A multi-cell ENC_ROOT is indexed cheaply (band + bbox);
   cells are parsed and portrayed only when a requested tile needs them, then held
   under an LRU bound. A **streaming** open reads a cell's bytes on demand (and
   frees them on eviction), so a host holds only the working set — not the whole
   catalogue.
-- **Band-streamed bakes.** Baking an ENC_ROOT to one PMTiles archive streams
-  band-by-band (finest → coarsest, best-band dedup), so peak memory tracks the
-  largest single band.
+- **Per-cell bakes.** Each ENC cell bakes to its own PMTiles at its compilation
+  scale, so a bake holds one cell at a time; the runtime compositor stitches the
+  cells by `(z, x, y)` on demand.
 - **Pure-Zig core.** The foundational format/encode packages have no libc; only
   the Lua portrayal + sprite rasterizer pull in C.
 
 ## Pipeline
 
 ```
 S-57 ENC cell (.000)
-   │  ISO 8211 decode                    src/s57/iso8211.zig
+   │  ISO 8211 decode                    src/iso8211/
    ▼
 S-57 feature + geometry model            src/s57/
-   │  S-101 portrayal (embedded Lua)     src/portray/ + src/s100/
+   │  adapt S-57 → S-101 features        src/s101/ (adapter)
    ▼
-portrayal instruction stream
+S-101 feature records
+   │  S-101 portrayal (embedded Lua)     src/portray/ + rules
+   ▼
+portrayal instruction stream             src/s101/ (instructions)
    │  scene generation                   src/scene/  (project + clip + draw calls)
    ▼
 render Surface ──► MVT / MLT tiles (src/tiles/)  +  MapLibre style.json + assets
              └───► PNG raster / vector PDF / terminal text (src/render/)
 ```
 
-The stages are separate Zig modules — `s57` (including its ISO 8211 decoder),
-`s100`, `tiles`, `render`, `scene`, `assets` — pure Zig with no libc; only the
-Lua portrayal (`portray`) and the sprite rasterizer (`sprite`) pull in C. See
+The stages are separate Zig modules — `iso8211`, `s57`, `s101`, `tiles`,
+`render`, `scene`, `style` — pure Zig with no libc; only the Lua portrayal
+(`portray`) and the sprite rasterizer (`sprite`) pull in C. See
 [the architecture docs](docs/docs/architecture.md).
 
 ## Use it from Zig
@@ -114,41 +116,45 @@ const tile57 = @import("tile57");
 var chart = try tile57.Chart.openPath("ENC_ROOT/", null, true);
 defer chart.deinit();
 
-if (try chart.tile(z, x, y)) |mvt| {   // decompressed MVT bytes, or null if empty
-    defer tile57.freeBytes(mvt);
-    // … hand to your renderer …
-}
+const bbox = chart.bounds();   // geographic extent [w, s, e, n], or null
+// … render a view (chart.renderView), query features, or bake an archive …
 ```
 
-`Chart.openPath` streams cells on demand (working-set only); `Chart.openBytes` opens a
-single in-memory cell. See [the Zig API docs](docs/docs/zig-api.md).
+`Chart` renders views, queries features, and reads metadata. The runtime tile
+path — bake each cell, then compose by `(z, x, y)` on demand — is exposed through
+the [C ABI](include/tile57.h). See [the Zig API docs](docs/docs/zig-api.md).
 
 ## Use it from C
 
-The same engine behind a thin C ABI ([`include/tile57.h`](include/tile57.h)):
+The same engine behind a thin C ABI ([`include/tile57.h`](include/tile57.h)).
+Tiles are made one way — bake each cell to its own PMTiles, then compose on
+demand — the structure `tile57 bake ENC_ROOT -o out/` writes:
 
 ```c
-// Open an on-disk ENC_ROOT directory (or a single .000 file).
-tile57_chart *chart = tile57_chart_open("ENC_ROOT/");
-uint8_t *mvt; size_t n;
-if (tile57_chart_tile(chart, z, x, y, &mvt, &n) == TILE57_TILE_OK) {
-    /* … render mvt … */
-    tile57_free(mvt, n);
+// out/ holds tiles/<CELL>.pmtiles (one per cell) + partition.tpart
+const char *paths[] = { "out/tiles/US5MD1MC.pmtiles" };
+tile57_compose_source *src = tile57_compose_open(paths, 1, "out/partition.tpart");
+
+uint8_t *tile; size_t n;
+if (tile57_compose_serve(src, z, x, y, &tile, &n) == 1) {   /* decompressed MLT */
+    /* … hand the tile to your renderer … */
+    tile57_free(tile, n);
 }
-tile57_chart_close(chart);
+tile57_compose_close(src);
 ```
 
-`libtile57.a` also exposes the ENC_ROOT bake, the MapLibre style builder, and the
-asset/atlas generators. See [the C API docs](docs/docs/c-api.md).
+A separate `tile57_chart` handle renders finished PNG/PDF views and answers
+metadata + object queries; `libtile57.a` also exposes the MapLibre style builder
+and the asset/atlas generators. See [the C API docs](docs/docs/c-api.md).
 
 ## The `tile57` CLI
 
 The offline tool bakes charts and emits portrayal assets:
 
 ```sh
 zig build                                    # builds zig-out/bin/tile57
-tile57 bake CELL.000 -o out/                 # one cell -> bundle (tiles + style + assets + manifest)
-tile57 bake ENC_ROOT -o out/                 # whole catalogue, band-streamed -> same bundle
+tile57 bake CELL.000 -o out/                 # one cell -> out/tiles/<CELL>.pmtiles + partition.tpart
+tile57 bake ENC_ROOT -o out/                 # whole catalogue -> per-cell tiles/ + partition.tpart
 tile57 assets   -o assets/                   # colortables + linestyles + sprite + patterns
 tile57 png ENC_ROOT --view -76.48,38.974,15 --size 1600x1200 -o chart.png
 tile57 pdf ENC_ROOT --view -76.48,38.974,15 --size 1600x1200 -o chart.pdf
@@ -172,7 +178,7 @@ Docs source lives in [`docs/`](docs/): [intro](docs/docs/intro.md),
 [getting started](docs/docs/getting-started.md), the
 [Zig API](docs/docs/zig-api.md), the [C API](docs/docs/c-api.md),
 the [architecture](docs/docs/architecture.md), and the
-[tile schema](docs/docs/tile-schema.md). See also [`CHANGELOG.md`](CHANGELOG.md).
+[tile schema](docs/docs/tile-schema.md).
 
 ## License
 

bindings/go/README.md

@@ -34,25 +34,39 @@ replace github.com/beetlebugorg/tile57/bindings/go => /path/to/chartplotter-nati
 ```go
 import tile57 "github.com/beetlebugorg/tile57/bindings/go"
 
-// Bake a single cell.000 or a whole ENC_ROOT dir into a self-contained bundle.
-cells, bbox, err := tile57.BakeBundle("/enc/ENC_ROOT", "/out/bundle", "", "", "", 0, 16, nil)
+// Bake an ENC_ROOT: each cell becomes its own PMTiles under <out>/tiles/, plus
+// an ownership partition at <out>/partition.tpart.
+n, err := tile57.BakeTree("/enc/ENC_ROOT", "/out", 4, nil)
 
-// Or serve tiles live, and publish the SCAMIN manifest for the style.
-src, _ := tile57.Open("/enc/ENC_ROOT")
+// Open the compositor over the baked archives + partition, and serve tiles.
+src, _ := tile57.OpenCompose([]string{"/out/tiles/US5MD1MC.pmtiles"}, "/out/partition.tpart")
 defer src.Close()
-mvt, _ := src.Tile(13, 2359, 3139)
-manifest := src.Scamin() // []uint32, ascending
+body, owned, _ := src.Tile(13, 2359, 3139) // owned=false, body=nil => open ocean
+
+// Or open one baked archive as a chart (bounds, scale, coverage, SCAMIN).
+chart, _ := tile57.Open("/out/tiles/US5MD1MC.pmtiles")
+defer chart.Close()
+info := chart.Info()     // zoom range, bounds, embedded 1:N scale
+scamin := chart.Scamin() // []uint32, ascending
+
+// Raw S-57 reading is handle-free (cell inventory, feature extraction).
+charts, _ := tile57.Charts("/enc/ENC_ROOT")
+water, _ := tile57.Features("/enc/ENC_ROOT/US5MD1MC/US5MD1MC.000", "DEPARE", "DRGARE")
 ```
 
 ## Surface
 
-- **Charts** — `Open` (path, streaming), `OpenChartBytes` (one in-memory cell),
-  `OpenPMTiles` (baked bundle); `Source.Tile`, `Info`, `Meta`, `Scamin`,
-  `ClearCache`, `Close`.
-- **Bake** — `BakeCells` (→ one PMTiles archive in memory), `BakeBundle` (→ a full
-  on-disk bundle: tiles + assets + per-scheme styles + manifest).
-- **Assets / style** — `ColortablesDefault`, `Colortables`, `Linestyles`,
-  `SpriteAtlas`, `PatternAtlas`, `StyleTemplate`, `BuildStyle`, `Style`,
+- **Charts (a baked archive: metadata + query)** — `Open` (path, mmap'd),
+  `OpenBytes`; `Source.Info`, `Meta`, `Scamin`, `Coverage`, `Close`.
+- **S-57 source readers (handle-free)** — `Charts` (per-chart metadata of a .000 or
+  ENC_ROOT), `Features` / `FeaturesBytes` (GeoJSON extraction), `CatalogEntries`
+  (CATALOG.031 decode).
+- **Bake** — `BakeChart` (one chart → PMTiles bytes), `BakeTree` (an ENC_ROOT → per-chart
+  archives), `BakeAssets` (portrayal assets in memory).
+- **Compose** — `OpenCompose` (paths; owns its charts) / `OpenComposeCharts`
+  (borrows yours); `ComposeSource.Serve` (a tile, with an ownership flag), `Meta`,
+  `SavePartition`, `Close`.
+- **Style** — `ColortablesDefault`, `Style`, `BuildStyle`, `StyleDiff`,
   `MarinerDefaults`.
 
 `libtile57` is not internally synchronized; every `Source` method is mutex-guarded,

bindings/go/asset.go

@@ -9,7 +9,6 @@ package tile57
 import "C"
 
 import (
-	"fmt"
 	"unsafe"
 )
 
@@ -19,8 +18,9 @@ import (
 func ColortablesDefault() ([]byte, error) {
 	var out *C.uint8_t
 	var n C.size_t
-	if C.tile57_colortables_default(&out, &n) != 1 {
-		return nil, fmt.Errorf("tile57: colortables_default failed")
+	var cerr C.tile57_error
+	if st := C.tile57_colortables_default(&out, &n, &cerr); st != C.TILE57_OK {
+		return nil, statusError(st, &cerr)
 	}
 	return tileBytes(out, n), nil
 }
@@ -39,8 +39,9 @@ func BakeAssets(catalogDir string) (Assets, error) {
 	cdir, free := cStringOrNil(catalogDir)
 	defer free()
 	var ca C.tile57_assets
-	if C.tile57_bake_assets(cdir, &ca) != 1 {
-		return Assets{}, fmt.Errorf("tile57: bake_assets failed")
+	var cerr C.tile57_error
+	if st := C.tile57_bake_assets(cdir, &ca, &cerr); st != C.TILE57_OK {
+		return Assets{}, statusError(st, &cerr)
 	}
 	defer C.tile57_assets_free(&ca)
 	return Assets{