From 13c4005afcfe3d5208173ecf18e6d3d5d1466755 Mon Sep 17 00:00:00 2001 From: Justin Walsh Date: Thu, 20 Aug 2026 12:58:05 -0400 Subject: [PATCH] docs: route readers to the current engine contract Both indexes presented `engine-integration-contract.md` and `raster-technique-api.md` as authoritative while each document self-marks `status: deprecated` and opens with "Historical design record". Someone building a custom renderer from the index would implement a superseded TypeScript storage and packing contract. The two documents were not the problem: each already routes readers on to `packages/glyph.md` and `rust-layout-engine.md`. Only the indexes misrouted, and they did so because the actual authority was missing from them -- `rust-layout-engine.md` is what `README.md:315` sends custom-renderer integrators to, and it appeared in neither `docs/index.md` nor `docs/planning/index.md`. Both now list it first among the engine entries, so the working path is reachable from the index rather than only from the README. `api-shapes.md` claimed "merged v0 surfaces are implemented but unreleased" across 1,277 lines describing a surface `roadmap.md:827` records as deleted, and its own note pointed at the deprecated engine-integration contract. The status now says superseded and the note points at the current reference. Superseded entries follow the wording already used for `text-effect-composition.md`: name what replaced them rather than removing the link, so the retired design stays discoverable. --- docs/index.md | 7 ++++--- docs/planning/api-shapes.md | 8 ++++---- docs/planning/index.md | 7 ++++--- 3 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index f5be8f32..86e50fba 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,11 +9,12 @@ okf_version: '0.2' - [Project README](../README.md) — product overview, API preview, implementation order, and local setup. - [Project brief](planning/project-brief.md) — product outcome, scope, non-goals, and success criteria. - [Canonical roadmap](roadmap/roadmap.md) — implementation sequence, issue-sized milestones, dependencies, and exit gates. -- [Merged v0 runtime and bake API](planning/api-shapes.md) — migration fixture for the implemented, unreleased package boundaries and explicitly deferred additions. +- [Merged v0 runtime and bake API](planning/api-shapes.md) — superseded migration fixture; it describes the merged v0 surface that the Rust render-plan cutover deleted. - [Three.js text API](planning/three-api.md) — authoritative Three-native loader, explicit `TextGroup` batching, reusable text across group disposal, retained non-throwing errors, ordering, and lifecycle contract. - [Core text API](planning/core-api.md) — authoritative API for ordered font stacks, batch-owned paragraph handles, identity-preserving capacity changes, fixed-capacity failure, synchronized updates, and renderer-ready glyph batches. -- [Engine integration contract](planning/engine-integration-contract.md) — exact storage, batching, submission, ownership, staging, and frame-publication boundary for custom renderers. -- [Raster technique and engine resource API](planning/raster-technique-api.md) — portable artifact loading, CPU raster data, glyph-resource binding, reusable shader-backend programs, and engine target ownership. +- [Rust layout engine contract](planning/rust-layout-engine.md) — authoritative engine ABI, render-plan policy, and publication boundary for custom renderers. +- [Engine integration contract](planning/engine-integration-contract.md) — superseded historical record; the Rust command buffer replaced this storage and batching contract. +- [Raster technique and engine resource API](planning/raster-technique-api.md) — superseded historical record; the Rust render-plan cutover replaced these TypeScript binding and packing interfaces. - [TypeGPU-first shader authority](planning/typegpu-first-shader-authority.md) — exploratory TypeGPU-first shader/program architecture, Three and gpucat bridge limits, fallback authority models, and proof gates. - [Merged v0 raster and baker plugin guide](planning/raster-baker-plugin.md) — build against the implemented combined runtime/renderer module before the target v1 extraction replaces it. - [External gpucat integration fitness plan](planning/gpucat-integration.md) — source-validated proof plan for consuming the target v1 core without private imports or core changes. diff --git a/docs/planning/api-shapes.md b/docs/planning/api-shapes.md index 8a8cf635..74854a47 100644 --- a/docs/planning/api-shapes.md +++ b/docs/planning/api-shapes.md @@ -40,13 +40,13 @@ generated: # Merged v0 runtime and bake API fixture -Status: merged v0 surfaces are implemented but unreleased; sections labeled deferred remain proposals +Status: superseded; the merged v0 surface described here was deleted by the Rust render-plan cutover Scope: baked-first loading, lazy Worker baking, HarfRust Wasm shaping, JavaScript paragraph layout, and explicit raster loading > [!NOTE] -> This page is retained for migration and regression comparison. The root [README](../../README.md), -> [core text API](core-api.md), and [engine integration contract](engine-integration-contract.md) define the -> authoritative extraction API. +> This page is retained for migration and regression comparison only. The root [README](../../README.md), +> [core text API](core-api.md), and [Rust layout engine contract](rust-layout-engine.md) define the +> authoritative API. ## Milestone 0.1 acceptance evidence diff --git a/docs/planning/index.md b/docs/planning/index.md index 189f7320..faae898e 100644 --- a/docs/planning/index.md +++ b/docs/planning/index.md @@ -3,11 +3,12 @@ ## Product, API, and execution - [Project brief](project-brief.md) — product intent, merged v0, target v1, and later horizon. -- [Merged v0 runtime and bake API](api-shapes.md) — public and internal TypeScript migration fixture. +- [Merged v0 runtime and bake API](api-shapes.md) — superseded migration fixture; describes the merged v0 surface deleted by the Rust render-plan cutover. - [Three.js text API](three-api.md) — authoritative `FontLoader`, `TextGroup`, and `Text` surface, including late binding, group disposal/rebinding, font leases, retained non-throwing errors, ordering, and render-loop synchronization. - [Core text API](core-api.md) — authoritative API and rationale for ordered font stacks, batch-owned paragraph handles, identity-preserving capacity changes, font leases, fixed-capacity failure, physical batching, and cascading disposal. -- [Engine integration contract](engine-integration-contract.md) — exact prepared glyph-batch/run, variant, target storage, transform, draw compilation, staging, attachment ownership, and disposal contract. -- [Raster technique and engine resource API](raster-technique-api.md) — authoritative split between portable baker/artifact/CPU technique data, reusable backend technique shaders, variant-aware programs, and engine GPU targets. +- [Rust layout engine contract](rust-layout-engine.md) — authoritative engine ABI, render-plan policy, and publication boundary for custom renderers. +- [Engine integration contract](engine-integration-contract.md) — superseded historical record; the Rust command buffer replaced this storage and batching contract. +- [Raster technique and engine resource API](raster-technique-api.md) — superseded historical record; the Rust render-plan cutover replaced these TypeScript binding and packing interfaces. - [TypeGPU raster programs and text engine](typegpu-api.md) — complete direct TypeGPU API for typed technique shaders, programs, variants, caller-owned render passes, transforms, synchronization, and disposal. - [TypeGPU-first shader authority](typegpu-first-shader-authority.md) — exploratory package shape and falsifiable proof ladder for sharing complete raster kernels with direct WebGPU hosts, Three.js, and gpucat without changing core. - [Three material authority for text draws](three-material-authority.md) — **work in progress.** Fixes the Rust `material_id` route and shared-storage/draw-split contract while leaving the exact Three material-factory types for a later design pass.