Skip to content

docs: define target v1 core and engine contracts - #44

Open
thejustinwalsh wants to merge 16 commits into
mainfrom
feat/core-api-planning
Open

docs: define target v1 core and engine contracts#44
thejustinwalsh wants to merge 16 commits into
mainfrom
feat/core-api-planning

Conversation

@thejustinwalsh

@thejustinwalsh thejustinwalsh commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • define the target v1 renderer-neutral core: explicit loading, font stacks, retained paragraph batches, synchronous/asynchronous synchronization, capacity, variants, ownership, and disposal
  • define Three.js, React Three Fiber, and TypeGPU as independent integration packages over public core and portable raster-technique contracts
  • split portable raster data, canonical CPU glyph storage, reusable technique shaders, engine programs, and engine-owned GPU targets
  • validate the proposed public boundary against gpucat at pinned commit 11cf91b and add the external-package implementation/fitness plan
  • correct repository terminology throughout: milestones through 10 are the merged, unreleased v0 implementation; this work is the path toward v1; nothing has been published or declared v1

Boundary

bake/load -> shape/layout -> canonical glyph batches + ordered variant runs
          -> engine program compiles compatible draws -> engine target encodes them

Core owns shaping, fallback, source order, physical resource partitioning, stable slots, canonical CPU storage, and dirty/live ranges. Engine packages own transforms, shader/program composition, compatible draw planning, GPU resources, passes, fences, and retirement. Core imports no Three.js, TypeGPU, Wayfare, or gpucat API.

The gpucat source review found public typed buffers with partial update ranges, array/data textures, storage buffers, transform-bearing scene objects, ordered instanced multi-draw meshes, and sufficient renderer lifecycle hooks. That is enough to plan the integration without a core change. Visible Bitmap/MTSDF/Slug output and reusable canonical Slug shader access remain executable gates; the docs do not claim those proofs are complete.

Scope

Documentation and planning only. This draft deliberately stops before implementing or changing the API.

Validation

  • Oxfmt passed for all 30 changed Markdown files
  • OKF v0.2: 0 conformance errors, 0 producer-profile errors, 0 warnings
  • git diff --check
  • gpucat build passed at 11cf91b
  • focused gpucat tests: 55/56 passed; the remaining upstream assertion differed only in process-global generated GLSL suffixes (storage183 vs storage226) and is recorded as a limitation, not text-integration evidence

@thejustinwalsh thejustinwalsh changed the title docs: define core text API docs: define core and Three.js text APIs Aug 6, 2026
@thejustinwalsh thejustinwalsh changed the title docs: define core and Three.js text APIs docs: define core, Three.js, and TypeGPU text APIs Aug 7, 2026
@thejustinwalsh thejustinwalsh changed the title docs: define core, Three.js, and TypeGPU text APIs docs: define target v1 core and engine contracts Aug 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant