zenith: Instructions file for Codex

Repository Guidelines

This file is the source of truth for working in the Zenith repository — for human contributors and AI agents alike. Read it before making changes.

Project Structure & Module Organization

Zenith is a Rust workspace (edition = "2024"). Each crate owns one concern and exposes a stable contract; zenith-geometry depends on no other Zenith crate; zenith-core may depend only on pure zenith-geometry for path math (validation / fill queries).

• zenith-core/ — KDL parser adapter, semantic AST, canonical formatter, tokens, validation, the full diagnostic set. May depend on pure zenith-geometry only among Zenith crates.
• zenith-fonts-fallback/ — the fallback font chain (Noto Sans Arabic, Hebrew, CJK SC subset, monochrome Noto Emoji) as embedded bytes behind the embed feature. Depends on no Zenith crate. ABOUT.txt records the subset commands.
• zenith-geometry/ — pure geometry (paths, contours, booleans). C-free; depends on no other Zenith crate; used by core, layout, scene, and tx.
• zenith-layout/ — text shaping & font metrics (rustybuzz + ttf-parser); all third-party shaping types confined here.
• zenith-raster/ — raster surface, blend modes, adjustments used by perception and render.
• zenith-perception/ — visual QA / perception reports over geometry + raster.
• zenith-scene/ — backend-neutral scene IR and compilation (geometry, text wrap, anchors, opacity/clip, text outlines).
• zenith-render/ — CPU PNG backend (tiny-skia) and vector PDF backend; raster-time determinism rules.
• zenith-tx/ — transaction op set, apply/dry-run engine, diffs, audit-record contract. Pure AST; no scene/layout dependency.
• zenith-session/ — local doc identity (ULID), ephemeral session DAG, durable content-addressed version store. Never on the render path.
• zenith-zpx/ — packaged design export (manifest + bake).
• zenith-producers/ — higher-level produce/export helpers (SVG native, ZPX bake).
• zenith-pipeline/ — config policy, imports, fonts, assets, validate, compile, and render over host I/O traits (SourceFs, ConfigSource, LocalFontSource, PageRunner). Shared by the CLI and the wasm editor. NEVER std::fs / std::thread / time in it; the CLI's native host lives in zenith-cli/src/native.rs.
• zenith-editor/ — the editor engine: stateless execute(env, session, request) over a serializable Session (selection, gestures to tx ops, text-delta history, render). Shared by the browser module, zenith edit, and MCP; wasm-safe like zenith-pipeline.
• zenith-editor-wasm/ — wasm32-wasip1 command module of the editor engine: one JSON request on stdin, one JSON response on stdout. Backs the static browser editor. publish = false.
• zenith-editor/benches/ — zenith-editor-bench: fluxbench benches of the editor loops. publish = false.
• zenith-cli/ — the zenith binary (crate package name zenith-tool): command dispatch, clap, JSON/human output, MCP; render/validate logic goes in zenith-pipeline, not here. src/main.rs is thin; logic lives in src/lib.rs and src/commands/.
• examples/ — runnable .zen documents (keep them valid against the current parser).
• assets/ — bundled fonts (zenith-core/assets/fonts/) and embedded library presets (assets/libraries/). Committed.
• conformance/ — regenerable rendered proof of simulation scenarios. Gitignored; never stage it.
• resource/, .agents/, .claude/, .codex/ — local planning/research/session scratch. Gitignored.