GlyphRazor

GlyphRazor is a deterministic, pluggable large-context text execution pipeline for persistent text surfaces, especially large DOM-based LLM chat workloads. Update cost scales with local change, not accumulated history.

---

The problem

You are in a Claude or ChatGPT session. The conversation is 40,000 tokens long. A new message streams in. Why does any work proportional to those 40,000 tokens happen? It should not.

Only the new tokens should cost anything. The rest is retained history: it does not move, it does not change, and it has already been laid out.

GlyphRazor exists to make that cost model real.

---

What GlyphRazor is

GlyphRazor sits between shaping and rendering. It retains LayoutArtifacts, computes deterministic ExecutionPlans, and ensures unchanged history stays reusable.

Diagram A — pipeline boundary

App / DOM / text model
        ↓
Segmentation / bidi
        ↓
HarfBuzz or equivalent
        ↓
GlyphRuns / shaped input
        ↓
GlyphRazor LayoutArtifact
        ↓
ExecutionPlan
        ↓
Renderer backend

GlyphRazor begins after shaping. GlyphRazor ends before renderer realization.

Diagram B — internal layering

glyphrazor
  ├─ foundation
  ├─ layout
  ├─ render
  ├─ adapters
  ├─ ffi        (feature-gated)
  └─ wasm       (feature-gated)
      ↓
optional reference backends under labs

No upward arrows. No backend logic in retained artifacts.

---

What GlyphRazor is not

• GlyphRazor is not a shaping engine.
• GlyphRazor is not a UI framework.
• GlyphRazor is not a scene graph.
• GlyphRazor is not primarily a generic GPU text renderer.

HarfBuzz, rustybuzz, Skrifa, and platform shapers handle shaping. Proven renderers handle draw realization. GlyphRazor handles retained large-context execution between them.

---

Primary workload

The canonical GlyphRazor workload is a long-lived LLM conversation surface:

• Message history grows continuously.
• New output streams in token by token.
• Scroll is constant.
• Cursor, selection, highlights, and citations change independently.
• Retained history must not be re-traversed on each update.

Run the primary proof:

cargo run --example llm_dom_surface -p glyphrazor --release

Expected result:

• each append recomputes exactly 1 artifact
• scroll recomputes 0 artifacts
• overlay updates recompute 0 artifacts

That is the large-context guarantee.

---

Pluggable by design

GlyphRazor exposes the shaping seam above the retained core and the renderer seam below it.

ShapingBackend     ← external shaping systems
       ↓
GlyphRazor         ← retained large-context execution
       ↓
RendererBackend    ← your renderer backend

Both seams are available from the public facade:

use glyphrazor::{RendererBackend, ShapingBackend};

labs/crates/glyphrazor-wgpu is the optional reference wgpu backend crate and the working end-to-end draw path. It is not the product. The product is the retained execution architecture inside the single glyphrazor crate.

See docs/architecture/renderer_adapter.md for the backend contract.

---

Architectural guarantees

Guarantee	Invariant
Backends consume plans only: no shaping, no layout mutation	INV-1
LayoutArtifact remains backend-neutral and CPU-resident	INV-2
Equivalent inputs and mutation sequences produce equivalent plans	INV-3
Pre-shaped input is preserved exactly	INV-4
Scroll and viewport transforms do not relayout unchanged content	INV-5
Overlay changes do not invalidate base text artifacts	INV-6
Glyph representation policy is separate from retained execution	INV-7
Large-context workloads outrank generic rendering polish	INV-8

Canonical source: docs/architecture/invariants.md

---

Canonical proof suite

Each canonical example has the same structure:

• one-sentence purpose
• architecture diagram
• exact input/output boundary
• live metrics
• what this proves

The real HarfBuzz preservation proof lives in:

• proof_harfbuzz_preservation
• proof_coretext_bridge
• proof_directwrite_bridge

Example	Proves
harfbuzz_large_context	GlyphRazor begins after shaping and retains large pre-shaped surfaces
terminal_surface	Append-heavy streams scale with new lines, not scrollback history
editor_surface	Local edits stay bounded and overlays stay isolated
llm_dom_surface	Large DOM / LLM chat workloads remain O(change), not O(history)

Supporting examples:

• preshaped_input
• pluggable_surface
• glyphrazor_health_check

---

Crate responsibilities

Crate	Contract
glyphrazor	Canonical core crate: retained execution, layout geometry, renderer seams, shaping adapters, and optional ffi / wasm surfaces
labs/crates/glyphrazor-render	Labs-side render-style, shader, and effect ownership for reference backends
labs/crates/glyphrazor-font	Labs-side reference font crate for parsing, metrics, outlines, color, SVG, and variation work
labs/crates/glyphrazor-wgpu	Optional reference wgpu backend crate
labs/crates/glyphrazor-msdf	Optional distance-field glyph representation policy
labs/crates/glyphrazor-atlas	Optional atlas packing and residency utilities for backend crates

The core crate does not depend on the labs crates above. Labs backends and font experiments depend on glyphrazor, not the other way around.

---

Docs

• QUICKSTART.md — current live entry points
• docs/why-glyphrazor-exists.md — the long-lived LLM / DOM pain point this project exists to solve
• docs/adoption-guide.md — recommended adoption path
• docs/architecture/invariants.md — canonical guarantees
• docs/architecture/renderer_adapter.md — backend contract
• docs/architecture/pluggability.md — shaping boundary
• docs/adapters/README.md — adapter support matrix and usage
• docs/determinism.md — deterministic planning contract
• docs/proof/adapter-target-selection.md — why these integration targets were chosen
• docs/proof/proof-suite.md — integration proof commands, baselines, and interpretation
• docs/proof/llm-dom-proof.md — the long-lived LLM / DOM workload evaluation
• docs/benchmarks.md — benchmark methodology and published bundles
• docs/examples/reference_examples.md — proof-example index

---

labs/ contains archived demos, phase-era examples, research notes, reference backends, and the non-canonical archive cut from core. It is not required to understand the retained large-context architecture.