DONE The reference's shape, with its constants as knobs #3YHNO3

Read against the 2026 reference shaders and the retrospective, luv's Slug had the algorithm -- eligibility, two rays, weighted combination, sorted bands -- but not the reference's shape around it. This figure closes the gaps and names what the reference hard-codes.

• Early exit. The reference leaves a band's loop at the first curve whose largest x (or y) is more than half a pixel behind the sample; the band is sorted descending for exactly that. luv's serializer had sorted, and its shader had walked every curve. The shared language gained a termination test on its fold -- (counted-fold (index count state initial :until test) update) -- lowered to if (...) break; in Metal and to a LogicalAnd of the counter test in the SPIR-V loop header, and the band folds now carry a third done lane that slug-horizontal-band-step sets from the curve's reach. #8RQOF0's fold thereby learned what #45K8GR's loops always had.
• Fill rule and optical weight. SLUG_EVENODD and SLUG_WEIGHT are compile-time switches in the reference; slug-finish-coverage holds both as values, an even-odd blend and an exponent (one half is the reference's square root).
• Footprint. The reference measures the pixel with fwidth; luv measured the gradient length. Both are available and blend.
• Dynamic dilation. #J0H590 is now real for world text: the vertex stage in block-world-text-vertex-specification knows a vertex's depth and, from two spare frame lanes, the target's height in pixels, so it sizes each em edge in pixels and slides the corner outward by the dilation over that length, moving the em coordinate with it. The 0.035-em constant padding of #9G0Z19 became *slug-static-padding*, zero by default; the flat McCLIM path, which knows its pixel size when it lays out, takes slug-dilation-em instead.
• Band data. The band count per axis is now chosen by choose-slug-band-count as the reference advises -- the fewest bands that minimize the fullest band -- and serialize-slug-outline lets a band whose sorted list is a contiguous run of one already written point into it, which the reference recommends for cache and size (a DejaVu W falls from 157 to 79 band texels, an O from 172 to 122). The overlap epsilon and the maximum band count are values too.
• Cap-height alignment. slug-cap-height-aligned-size reads sCapHeight from the OS/2 table (which ZPB-TTF does not) and returns the size nearest a request at which capitals land on whole pixels: the reference's substitute for hinting. DejaVu's OS/2 table is version 1 and carries none, so it answers the request unchanged there.

The values live in luv.slug as specials -- *slug-filter-width*, *slug-fill-rule*, *slug-optical-weight*, *slug-footprint-norm*, *slug-early-exit*, *slug-root-epsilon*, *slug-debug-view*, *slug-dilation-pixels* -- and stand in shader source by their unstarred names, folded through shader-source-value. For that to be live, the two band shaders are define-live-shader forms, reparsed on every pipeline build, where define-shader parses once at load; luvcraft wraps each value in a :text knob in make-world-text-run's file, so the metabar turns them and the terminal walls rebuild at the next frame. *slug-debug-view* paints every quad with its two bands' loads, red and green over sixteen, which is the quickest way to see what a band count buys.

What was studied and left alone: the reference's packed vertex record and its 8-bit band maxima (luv's instance record already carries the counts and bounds it needs), and the multi-layer emoji path, which luv has no outlines for yet. The reference's CalcRootCode bit trick and luv's arithmetic eligibility (#S2F8SA) are the same table.

DONE One fixed contour proves luv's pixel-stage mathematics #OWR8OZ

Intent: prove that luv's shader DSL can state, lower, compile, and actually draw the numerically important pixel-stage core before designing texture and font-data machinery.

Evidence:

• slug-quadratic-outline is now a typed shader function over the eight points of a connected four-curve contour. It composes ordinary typed slug-axis-contribution, root-eligibility, and coverage functions with lexical let*; no Slug helper constructs or returns shader source forms. The calculation still implements the eight-class eligibility table, quadratic/linear roots, both ray directions, intersection weights, and the current coverage combination. #RO74NL records the language distinction.
• The ordinary Lisp function slug-root-eligibility exposes the same table to focused tests. All eight classes and the strict treatment of zero are checked.
• The DSL's open operator protocol now admits Common Lisp signum and lowers it directly to SPIR-V FSign and MSL sign. Both generated shaders pass spirv-val and Apple's Metal 4 compiler.
• Refactoring from form-generating source abstraction to typed function calls leaves the actual 256 by 256 Metal readback byte-identical.
• The cold Metal probe draws a two-triangle quad into a 256 by 256 RGBA8 texture, reads the real GPU result back, and writes this image:

Done when (met): a fixed four-quadratic heart crosses the normal mathematical shader path, both backend compilers accept it, root classification has an executable table oracle, and a Metal pixel shader produces the expected antialiased outline from Bézier data rather than a sampled image.

Mentioned in: One distance function draws the roundrect family analytically

DONE Teach the shared language Slug's structured band fold #HMNMBU

Intent: add the smallest shared control-flow and indexed-data vocabulary that states one Slug band traversal without burying its concrete data contract in a generic scene abstraction.

Evidence needed: after shared function application #YZS04W, add represented integer/index values, exact loads, comparison and conditional expressions, and a counted value-producing loop with early termination. Execute a CPU realization over a small curve array, lower the same body to valid MSL and SPIR-V structured control flow, and keep the current fixed shader as the pixel oracle.

The neutral loop skeleton is now present: counted-fold accepts a runtime count and one carried scalar or vector state, executes as dotimes on the CPU, as an ordinary for loop in direct Metal, and as validated structured SPIR-V with phi-carried index and state. Its update is an expression body rather than an artificially single call: a leading let* produces per-iteration lexical bindings in the common AST, an inner Lisp let*, loop-local SSA values, and named locals inside the emitted Metal loop.

Conditional accumulation is shared too. if is a first-class value node in the common expression graph, with checked scalar comparisons <, <=, >, >=, and ===. Lisp retains ordinary branch semantics; SPIR-V emits the ordered comparison plus OpSelect; and direct Metal emits a ternary inside the same for loop. A bounded triangular fold executes on the CPU and compiles from the same shape on both GPU targets.

The shader representation layer now supplies uint and uvec2/3/4 values plus an exact texel-load extension. A count loaded from a uint-texture-2d selects an unsigned fold index automatically; address addition, unsigned division and the common mod operation stay typed throughout. The same probe emits OpImageFetch, OpULessThan, OpUDiv, OpUMod, OpIAdd, and OpConvertUToF in SPIR-V, while Metal emits texture2d<uint>.read(uint2) and a for (uint ...) loop with readable address locals. Both spirv-val and the Metal 4 compiler accept those generated products. mod itself belongs to the shared arithmetic vocabulary and executes through Common Lisp's ordinary mod; the texture resource and exact load remain properly shader-specific.

slug-banded-fragment-specification now supplies the Slug-shaped traversal. Two runtime unsigned curve counts control two counted-fold values. Each iteration reads its RG16U curve location and two adjacent RGBA16F curve texels, creates ordinary lexical let* bindings for the reusable axis-contribution function, and carries coverage plus maximum weight. There is no host unrolling and no form-generating Slug macro.

This exercised one subtle language rule that the scalar loop probes did not: function-local bindings called from a fold belong to that iteration. Direct MSL lowering now materializes them inside the for body, while SPIR-V only reuses a cached resource load in the basic block that owns it. The latter rule prevents a value defined inside one loop from being reused in another loop where it does not dominate. Regression tests inspect both generated products; spirv-val and Apple's Metal 4 compiler accept them.

The first correctness shader intentionally uses one complete band per axis. Sorted-coordinate early exit and multiple spatial bands are culling optimizations over this same value-producing traversal, not prerequisites for rendering an arbitrary outline.

Done when: a runtime curve count rather than source unrolling controls the number of evaluated quadratics; CPU and GPU results agree at edge, shared-endpoint, empty-band, and early-exit cases; and source/lowering tools retain the loop, carried values, and emitted block provenance.

DONE Pack arbitrary quadratic contours into Slug bands #TTE5JG

Intent: turn arbitrary connected quadratic contours into dense curve and band data suitable for the shared Slug fold.

Evidence needed: a Lisp outline model preserving contour boundaries and orientation, line-to-quadratic encoding, conservative band overlap, omission of parallel straight lines, per-axis descending sort, and visible band-length statistics. Exercise an outer contour plus an inner contour before involving a font loader.

The CPU-owned model and the first preprocessing boundary are now concrete. slug-outline keeps closed contours, validates every curve junction, computes quadratic contour orientation from the exact area integral, and flattens curves in contour order. Lines use {p1,p2,p2}. pack-slug-outline builds horizontal and vertical bands with the reference 1/1024 conservative overlap, omits curves parallel to the relevant ray, and retains both descending-maximum and ascending-minimum orders. Tests exercise a counterclockwise outer square with a clockwise inner hole and reject a disconnected contour.

The serialization boundary now preserves the released shader's exact texture contract. Luv first rounds every point through binary16, decodes those actual shader-visible values, and only then recomputes bounds, bands, and sort keys. The 4096-wide RGBA16F curve texture stores one {p1,p2} texel per quadratic; the following texel supplies the shared p3, with one endpoint sentinel after each contour. The 4096-wide RG16U band texture stores all horizontal headers, then all vertical headers, followed by their descending-maximum (curve-texture-x, curve-texture-y) lists. Tests deliberately use a one-third coordinate to prove that packing observes the half-quantized value rather than the original Lisp rational.

The portable GPU vocabulary now names the exact storage formats too: :rg16-uint is four bytes per texel and :rgba16-float is eight. The Metal backend maps those names to MTLPixelFormatRG16Uint 63 and MTLPixelFormatRGBA16Float 115; Vulkan maps them to VK_FORMAT_R16G16_UINT 81 and VK_FORMAT_R16G16B16A16_SFLOAT 97. Both upload paths accept the serializer's two-dimensional specialized arrays directly and compute row length, byte size, alignment, and foreign element width from the format instead of assuming RGBA8.

The first serializer still describes one glyph beginning at texture origin zero. Atlas allocation and relocation remain open, but the complete one-glyph data is now uploaded and rendered from those resources while preserving the fixed-width addressing assumed by the released pixel shader.

Done when: several differently sized and holed quadratic outlines render from uploaded data without changing shader source, and a CPU winding oracle agrees with GPU pixels around extrema, shared endpoints, and contour holes.

DONE Shape and draw a HarfBuzz text run through Slug #DTBI99

Intent: join HarfBuzz shaping to the proven zpb-ttf outline boundary and render a run as placed Slug glyph quads without a software rasterizer.

Evidence: #4G7064 records the owned HarfBuzz binding, ffi ligature and cluster regression, glyph-ID-to-outline join, one-quad-per-glyph Metal draw, and visually inspected office affinity image. The complete luvcraft suite passes with the per-vertex pixels-per-em shader input.

The font boundary is now working before any rasterizer. The shader module in :luv depends directly on zpb-ttf and converts its resolved (start,control,end) segments into luv contours; a nil control becomes the standard Slug line quadratic. A slug-glyph also retains advance width, left side bearing, and units per em, and the converter accepts an already selected zpb glyph so a later HarfBuzz glyph index need not be turned back into a character. The reproducible test font is cl-dejavu's DejaVu Sans: its “O” produces two opposite-winding contours, 16 quadratics, a 1612-unit advance, and packs through the same arbitrary-outline path. No cl-vectors, cl-aa, or McCLIM raster object enters this system.

The Metal mark now crosses the complete boundary. normalize-slug-glyph-outline converts the font-unit points to em units while preserving the TrueType origin. The cold glyph probe loads DejaVu Sans “O”, serializes its 16 quadratics and two contours, uploads its exact band and curve arrays, binds the two texture views, draws the em-square quad through the public mathematical shader specifications, reads back the GPU target, and writes this image:

Changing the outline changes only the uploaded arrays. The fragment shader contains no “O” points, contour count, or source-unrolled curve calls. The generated SPIR-V has two structured loops and at least six exact image fetches; the generated MSL has two unsigned for loops with the reusable Slug function's lexical locals scoped inside them.

Done when: HarfBuzz-selected glyph IDs and placements render as a legible run through indexed Slug outlines, including a ligature that cannot be reproduced by one cmap lookup per character.

DONE Put a shaped run into the moving world #QW7P96

Intent: cross #4G7064 from an isolated target into the actual luvcraft scene, with world placement, camera projection, scene depth, and alpha composition all participating in the same frame as terrain.

make-world-text-run is now a semantic owner around dense HarfBuzz placement and vertex data. Its initial model transform fixes the text plane in world space from the camera's initial right and up basis. The :slug-world-text vertex stage then applies the scene frame uniform's camera view and perspective projection; the existing Slug fragment stage still owns coverage. The pipeline uses :less depth testing with depth writes disabled and premultiplied-alpha blending. It is encoded after opaque chunks and before the always-visible crosshair.

The fragment stage now derives pixels-per-em from the horizontal and vertical screen derivatives of the interpolated outline coordinate. Perspective, rotation, and camera distance therefore participate at the actual fragment; there is no run-center approximation or per-frame instance-buffer rewrite.

Evidence: the Metal validation layer accepts the complete hidden luvcraft frame, including its pipeline-layout transitions and teardown. This capture is the ordinary world smoke path, not an isolated text target:

The label's transparent quad exterior preserves sky and blocks; the pipeline's :less comparison puts terrain in front whenever their projections overlap. Frame metrics count six unit-quad vertices instanced across the run in one draw. The cache and atlas iterations below remove the original literal bind-and-draw-per-glyph baseline.

Done when: a HarfBuzz-shaped run is legible in the real scene, changes screen position and scale with its camera relationship, obeys terrain depth, and survives a full Metal-validation frame without a bind-state or lifetime error.

Mentioned in: A terminal is a world-native interactive surface, Bridge styled Ghostty render-state rows into the block wall

DONE Cache shaping and device glyph outlines #U5X6DY

Intent: make text runs cheap to reconstruct without hiding GPU lifetime inside glyph occurrences.

make-world-text-glyph-cache is owned by the luvcraft session and tied to one device. It retains HarfBuzz results by canonical font path and exact string, and retains normalized, serialized Slug outlines by canonical font path and HarfBuzz glyph ID. Atlas objects own the uploaded textures; a run owns placement, dense instance data, layout, and pipeline. Stopping the session destroys frame bind groups, then runs, then atlas textures, then the device.

Repeated occurrences share the same serialized resource object. The "hello, world" proof has 11 drawable occurrences but only 8 cached outlines. That banner is a proof rather than scenery, so a caller asks for it by passing :world-text-string; the ordinary game sky carries no text at all. A second identical run reuses the slug-shaped-text, all eight outlines, and the matching atlas. Metal regressions construct both runs and exercise the ownership-order teardown.

Done when: duplicate glyph IDs within a run and across runs resolve to the same per-device outline, identical shaping is not repeated, and Metal teardown is clean.

Mentioned in: A terminal is a world-native interactive surface, The terminal grid remains authoritative through Slug, Draw McCLIM text as world geometry

DONE Pack one atlas and issue one instanced text draw #AT7L3S

Intent: remove the command and allocation multiplication caused by treating each glyph occurrence as an independently bound texture pair.

create-world-text-glyph-atlas concatenates each distinct serialized outline into one RG16U band texture and one RGBA16F curve texture. Its location table maps the cached outline object to linear band and curve bases. Each run has a six-vertex unit quad and one 96-byte instance record per drawable glyph: world origin, right/up edge vectors, outline bounds and band counts, and atlas bases. The final two lanes separately retain the exact packed band bounds; quad geometry can therefore stay padded without changing spatial band selection. The vertex stage expands these records; the render pass binds the two buffers and one atlas group, then calls draw once with the glyph count as the instance count.

The exact proof-run comparison is deliberately about owned objects and encoded commands, not a noisy whole-frame timing claim:

The 24-to-5 encode count includes pipeline, vertex-buffer, bind-group, and draw calls. Texture allocation falls by 87.5 percent because every former glyph pair paid the 4096-texel minimum row; vertex data falls by 52.5 percent. The new spatial bands intentionally increase used band payload from 202 to 996 texels while curve payload remains 121 texels: roughly 4.8 KiB of useful data inside the 48 KiB allocated atlas. A 30-frame Apple M2 Pro steady run records 165 whole-scene draws, 0.173 ms median scene encoding, and 0.011 ms median uniform update. It is a current-path health measurement, not an A/B timing, because upstream terrain, particles, overlays, and lighting changed across the saved pre-atlas commit.

Done when: repeated glyphs share atlas storage, one run emits one instanced draw and one bind call, the backend validation layer accepts the frame, and the ordinary world capture remains legible.

Mentioned in: The terminal grid remains authoritative through Slug, A terminal is sharp at any distance because its glyphs are geometry, Draw McCLIM text as world geometry

DONE Select spatial bands and scale coverage from fragment derivatives #D4R1VX

The shared shader language now carries derivative-x and derivative-y through direct Metal dfdx/dfdy and SPIR-V OpDPdx/OpDPdy. The fragment shader forms a screen gradient for each em axis and takes its reciprocal length as pixels-per-em. The same fragment normalizes its x/y outline coordinate, chooses one of the serialized horizontal and vertical bands, and relocates that band's local curve addresses through the atlas bases. Default outlines use min(curve-count, 16) bands per axis rather than the one-band correctness fallback.

The generated MSL and SPIR-V are compiled and validated in the normal build, unit tests require derivative instructions and selected header addressing, and the Metal debug layer renders the multi-band world capture above. The default eight outlines use band counts from 4 through 16; the inspected atlas contains 996 band texels and 121 curve texels.

The remaining efficiency goblins are now explicit. Atlases and live pipelines are shared only by runs with the same exact glyph set, so many overlapping labels can duplicate storage and pipeline state. Tiny sets still pay one 4096-wide texture row. The sorted band lists do not yet early-exit their GPU fold, and multiple runs are not coalesced into a world-wide draw or culled as a batch. A terminal-scale client should next move atlas pages and pipeline ownership into the per-device cache, then measure whether page locality or world-wide instance aggregation wins before adding a generic text manager.

Done when: projected scale has no CPU estimate or frame upload, fragments select real spatial bands, both shader backends validate the derivative path, and an ordinary-distance debug-layer world frame is visually intact. The first close-up in #9G0Z19 subsequently falsified the bounds crossing; its corrected close-up now verifies that fragment selection agrees with preprocessing at the enlarged proof scale.

Mentioned in: The terminal grid remains authoritative through Slug

DONE One distance function draws the roundrect family analytically #LDAHBP

Intent: reuse the proof discipline learned from Slug without pretending that a fixed GUI primitive is an arbitrary outline.

The distinction is now executable. Slug's first proof #OWR8OZ puts reusable pixel mathematics in a typed function, exposes it through tiny portable shader specifications, inspects both generated targets, and finally demands a real GPU readback. The roundrect proof follows exactly that path while omitting curve textures, bands, winding traversal, and device outline identity.

roundrect-signed-distance is one shared arithmetic definition. It executes as an ordinary Lisp function for the scalar oracle and lowers into the same mathematical shader graph for both backends. A radius of zero is a rectangle; radius equal to the shorter half-extent yields capsules and circles. The shared arithmetic vocabulary gained raw abs and sqrt realization on this evidence, without claiming quantity semantics for either operation.

roundrect-coverage evaluates that distance in the fragment shader, uses derivative-x and derivative-y to measure its screen-space gradient, and maps the signed result through a one-pixel coverage ramp. One padded quad record carries clip position, local coordinate, half-size plus radius, opacity, and premultiplied colour. The cold Metal proof sends four such records through one resource-free pipeline: a roundrect, a capsule, a circle, and a rotated affine ellipse.

Evidence: the Lisp distance oracle checks straight edges, circle points, and radius normalization. The generated SPIR-V contains both fragment derivative instructions and validates under spirv-val. Generated MSL contains direct dfdx, dfdy, and sqrt calls and compiles under Metal 4. The image above is a 768 by 480 native Metal render and readback, not a software reconstruction. The complete luv, luvcraft, and wiki suites pass.

Done when (met): one shared distance definition produces exact scalar oracle values, both backend products compile, and a real GPU draw preserves smooth coverage across a card, capsule, circle, and non-uniform rotated transform.

NEXT Compare Slug coverage at glyph edges #9G0Z19

Intent: distinguish “a shaped run renders” from evidence that Slug's edge coverage and geometry expansion are correct across backends.

Evidence needed: exercise the portable draw on Vulkan, compare boundary pixels with a small CPU winding oracle, and test dynamic dilation on geometry whose undilated quad actually loses edge coverage. Atlas allocation and outline reuse are separate performance work and should follow measurement.

capture-hidden-luvcraft-text-closeup renders a 1280 by 360 logical Metal frame with the text enlarged in world space, producing a 2560 by 720 Retina image without post-render scaling. The elevated camera leaves enough world context to exercise the real depth path while giving the outline an unobstructed sky background:

The first native close-up was falsifying evidence: horizontal cuts through h and e and vertical slivers in h, r, and d coincided with band transitions, not font extrema or terrain edges. The instance record had sent the quad's 0.035-em padded outline bounds to the fragment shader, while pack-slug-outline partitioned the unpadded packed-outline bounds. The shader consequently mapped fragments into different spatial partitions than the serializer used to build their curve lists.

The corrected record carries both meanings. Padded low/high values still expand and parameterize the quad, while two additional attributes carry the exact packed min/max used only for band selection. The image above is the same close-up after that change: all transition-aligned cuts have disappeared, including the former horizontal break across h/e and the vertical breaks in h/r/d. A focused regression requires those padded and exact lanes to remain distinct. Metal validation accepts the enlarged Retina world render, and a cold Vulkan capture through the same shared specification produces the same continuous glyphs at its native 1280 by 360 drawable extent.

The world terminal #NMAD2U is a particularly demanding next client: repeated grid-aligned glyphs make edge quality, outline reuse, and batching visible, but the terminal should consume this evidence rather than silently becoming its oracle.

Done when: representative extrema, shared endpoints, holes, and clipped edges agree with the oracle on Metal and Vulkan, and dilation demonstrably recovers coverage rather than merely enlarging an already sufficient quad.

Mentioned in: The reference's shape, with its constants as knobs, Select spatial bands and scale coverage from fragment derivatives