Faster first frames, modern diagrams, and a docs site latkit draws

.changeset/first-frame.md

@@ -0,0 +1,26 @@
+---
+'latkit': patch
+---
+
+A view's first frame waits only for what draws its marks, a browser's first GPU is made while the runtime loads, pipelines compile only what their marks are and read, and the wasm is an eighth smaller. Diagrams look as modern as the rest: bordered blocks and groups that cast soft shadows, with corners, ports, and bends the theme sets.
+
+- Added: the theme's `outline`, `corner`, `portSize`, and `bend` set a diagram's block and group borders, their corners, its ports' width, and the radius of its wires' bends, which no longer follow `edgeSpacing`.
+- Added: `shadow: true` on a diagram's blocks and groups lays a soft shadow on the sheet, `shadow.lift` units below them, in the theme's shadow color.
+- Changed: a diagram's blocks and groups are bordered in the theme's `outline`, and a group draws no band behind its title. Corners, status rings, and ports' rings are part of the drawing and zoom with it; a status ring follows its marker's corners. A `block` marker's `corner` takes the theme's unless set.
+- Changed: a block makes room for the labels of its top and bottom ports, which did not show.
+- Changed: text is set in the system's sans-serif face unless the theme names one, where it was monospace.
+- Changed: a diagram grid's dots are a CSS pixel across on every screen.
+- Fixed: a mark ordered by `priority` draws the whole trace of the sampled field it traces; it drew nothing, and its plot fitted no values.
+- Fixed: a plot's y-axis label hangs from the top of the room above the plot, so a taller face no longer pushes it off the picture.
+- Fixed: a scene with two marks of one kind drawing one table asks for a `name`, as the option is called.
+- Changed: pipelines compile through one queue per GPU, the most urgent first: what frames draw with at once, their text as the browser's compile workers free up, then what transitions, lit rows, probes, and queries need, a few at a time. A view asks for its scene's as it is shown rather than at its first frame.
+- Changed: in a browser the GPU readies what nearly every scene draws with as its first view opens, once that view's frames have all they draw with; a GPU no view uses compiles nothing.
+- Changed: `loadLatkit()` asks for a GPU adapter as the runtime starts loading, so the browser's GPU process starts meanwhile, and makes the page's first GPU as it loads; the first `Gpu.create()` takes it.
+- Changed: a view's first frame draws its marks; labels, glyphs, and the overlay join once their pipelines landed, fading in as after any change. `complete` still waits for all of it.
+- Changed: a mark's channels compile for what they read: without fields of other tables, sampled fields, or `selected()`, `hovered()`, `pointer()`, and `zoom()`, their pipeline leaves each out. Fitted domains reduce in the channels' own pipeline.
+- Changed: label placement and the label draw compile for their mark's primitive, points, strokes, or triangles, as probes do: a quarter of the time for labels on points. Probes see each instance through one call, and placement passes no longer compile once per path.
+- Fixed: a plot's axes start below its title and subtitle, which drew over the plot.
+- Changed: the globe's atmosphere is a thin rim and a halo about as thick as the earth's air, where it was a wide glow over the ground and the marks near the globe's edge.
+- Changed: every transition eases through the settled state, so evaluating channels knows nothing of transitions.
+- Changed: expressions, sizes, labels, and colormaps are read where they are written, so error paths reach into expressions.
+- Changed: the wasm is 12% smaller (11% gzipped): sorts, name-keyed tables, and JSON reading each compile once, and URLs resolve without the `url` crate.

.github/workflows/ci.yml

@@ -59,6 +59,7 @@ jobs:
               - 'docs/**'
               - '.readthedocs.yaml'
               - 'npm/test/consumer/quickstart.ts'
+              - 'npm/examples/src/examples/**'
               - '.github/workflows/ci.yml'
 
   # Prettier over every file: cheap, and any pull request can unformat one.
@@ -174,21 +175,19 @@ jobs:
       - run: cargo xtask package
       - run: cargo xtask package-test
 
-  # The docs as Read the Docs builds them: a warning fails.
+  # The docs as Read the Docs builds them, from the locked environment: a warning fails.
   docs:
     needs: changes
     if: needs.changes.outputs.docs == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: astral-sh/setup-uv@v6
         with:
-          python-version: '3.13'
-          cache: pip
-          cache-dependency-path: docs/requirements.txt
-      - run: pip install -r docs/requirements.txt
-      - run: sphinx-build -W --keep-going -b html docs target/docs
+          python-version: '3.14'
+      - run: uv sync --locked --project docs --group docs
+      - run: uv run --locked --project docs sphinx-build -W --keep-going -b html docs target/docs
 
   # The one check branch protection requires: every job above passed, or was not needed.
   passed:

.gitignore

@@ -10,6 +10,8 @@ coverage/
 .impeccable/
 target/
 /npm/pkg/
+# The docs' environment, made from docs/uv.lock by uv sync --project docs.
+/docs/.venv/
 
 # The CLI examples' videos: each example's README says how to render its own.
 /crates/latkit-cli/examples/*/*.mp4

.prettierignore

@@ -15,3 +15,4 @@ crates/latkit-cli/examples/**/*.json
 benchmark/baselines
 # Written by the schema test: LATKIT_BLESS=1 cargo test -p latkit --test schema.
 npm/schema.json
+docs/_static/theme.json

.readthedocs.yaml

@@ -1,13 +1,17 @@
 version: 2
 
 build:
-  os: ubuntu-24.04
+  os: ubuntu-26.04
   tools:
-    python: '3.13'
+    python: '3.14'
 
 python:
   install:
-    - requirements: docs/requirements.txt
+    - method: uv
+      command: sync
+      path: docs
+      groups:
+        - docs
 
 sphinx:
   configuration: docs/conf.py

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+## Repository
+
+| Part                              | What it is                                                     |
+| --------------------------------- | -------------------------------------------------------------- |
+| [`latkit`](crates/latkit)         | The Rust library: data, expressions, scenes, views, and video  |
+| [npm `latkit`](npm)               | The library in the browser, with types for every scene         |
+| [`latkit-cli`](crates/latkit-cli) | Pictures and video of scenes, from JSON or binary data         |
+| [Examples](npm/examples)          | Every feature on a page, and the browser gate that drives them |
+| [Benchmark](benchmark)            | Every scenario's phases up its sizes, held to committed work   |
+| [Docs](docs)                      | The site on [Read the Docs](https://latkit.readthedocs.io)     |
+| [Gallery](docs/gallery)           | The documentation's pictures, each drawn by latkit             |
+
+The `@latkit/*` TypeScript packages, a lighter alternative without WebAssembly, are maintained on
+the [`npm/js`](https://github.com/lukelowry/latkit/tree/npm/js) branch.
+
+## Develop
+
+Requires Rust (pinned in `rust-toolchain.toml`), Node.js 24, pnpm 10.30, and for the docs, uv.
+
+```sh
+pnpm install
+cargo xtask examples --open   # the example pages at http://127.0.0.1:5200
+cargo xtask check             # format, lint, test, typecheck, and the browser gate
+cargo xtask bench --quick     # every benchmark scenario once, at its smallest size
+```
+
+## Documentation
+
+The site builds with Python alone, from what the repository checks in; each generated part has the
+command that writes it again:
+
+```sh
+uv run --project docs --group docs sphinx-build -W -b html docs target/docs   # the site
+node npm/docs.mjs                                    # the JavaScript API and type references
+LATKIT_BLESS=1 cargo test -p latkit --test schema    # the palette: latkit's default themes
+cargo build --locked -p latkit-cli --profile cli
+node docs/gallery/render.ts [name...]                # the pictures, drawn by the latkit CLI
+node benchmark/docs.ts                               # the performance table, from a baseline
+```
+
+[Releasing](RELEASING.md) covers versions and publishing.