docs: scope glyph rendering (4.3.6-4.3.6g), next after 4.3.5f

Punch list \xc2\xa725.5 additions (4.3.6-4.3.6g, unchecked) and new \xc2\xa727.6
rationale section, scoped per the 2026-08-07 sequencing note. Captures
requirements dictated this session: UTF-8-aware decoding, ASCII + Latin-1
typographic repertoire for v1, i18n-ready codepoint-indexed design, one
capsule per font-set (not per glyph), a default system font wired into
init.4th's boot chain as early as the capsule/VM bootstrap allows, with
user-font-override support -- additive to, not replacing, the existing
font_8x16.c VT100 console path. Flags two open items found while scoping
rather than deciding them unilaterally: an unused encoding field on
block_subsystem.h, and the open call on which capsule file eventually
houses the glyph data. No implementation yet -- scoping only, per \xc2\xa725.0
rule 2.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-09 16:55:01 -04:00
co-authored by Claude Sonnet 5
parent 40f3e3ab44
commit b69dcfd050
+83
View File
@@ -4388,6 +4388,53 @@ document and committing that amendment as its own item.*
> `#ifdef __STARKERNEL__`, or elsewhere is an open question for that later item, not
> decided here.
- [ ] **4.3.6 — Em-square glyph coordinate convention.** Define the normalized coordinate
space glyph strokes are authored in and the scale/translate step into `CART-PLOT` screen
coordinates, parallel to 4.3.3's `PROJECT`. Prerequisite for every glyph-drawing word that
follows. *Done when:* a normalized test shape scales/translates correctly onto raster
coordinates at two different requested sizes, verified live via screendump against
hand-calculated pixel positions. *Refs:* §27.6.
- [ ] **4.3.6a — UTF-8 decoder.** A FORTH word (or small wordset) walking a byte string and
yielding one Unicode codepoint at a time, composed in FORTH per the compose-in-FORTH-first
rule — no existing UTF-8 decoding anywhere in this tree (checked). *Done when:* correctly
decodes a test string mixing 1-byte ASCII and 2-byte Latin-1 sequences (e.g. `é` U+00E9),
verified live against hand-computed expected codepoints. *Refs:* §27.6.
- [ ] **4.3.6b — Codepoint → glyph dispatch.** Lookup mapping a decoded codepoint to its
stroke-drawing word within the active font-set capsule. *Done when:* dispatch correctly
invokes the right stroke word for at least 3 codepoints spanning ASCII and Latin-1, and
fails safely (defined, non-crashing behavior) for a codepoint outside the v1 repertoire.
*Refs:* §27.6.
- [ ] **4.3.6c — Default system font-set capsule.** ASCII printable + the agreed Latin-1
typographic set, each glyph a stroke-drawing word in the 4.3.6 em-square convention, one
capsule. *Done when:* every glyph in the v1 repertoire is defined, lint-clean
(`mkcapsule --lint`), individually verified to render a recognizable shape via screendump.
*Refs:* §27.6.
- [ ] **4.3.6d — Boot-time loading.** Wire `fabric.4th` and the 4.3.6c font capsule into
`init.4th`'s boot chain. *Done when:* standard three-arch QEMU boot shows both capsules
`EXEC`'d cleanly as part of the normal boot sequence (not manual injection), no errors,
logs committed. *Refs:* §27.6.
- [ ] **4.3.6e — User font override.** Mechanism to load and activate a replacement font-set
capsule over the default without redefining every caller. *Done when:* TBD — scoped in
detail once 4.3.6c exists (a second font-set is needed to test "override" against).
*Refs:* §27.6.
- [ ] **4.3.6f — TEXT-drawing entry point.** Decode a UTF-8 string, dispatch each codepoint
through 4.3.6b, draw via its stroke word, advance the cursor by glyph width. *Done when:*
a string containing both ASCII and at least one Latin-1 character renders correctly on the
CANVAS in one call, verified via screendump, no overlapping/misspaced glyphs. *Refs:* §27.6.
- [ ] **4.3.6g — Checkpoint: render every v1 glyph on the CANVAS.** Same posture as
4.3.4/4.3.5f — stop and review here before scoping REPL wiring (M8). *Done when:* a single
screendump shows every glyph in the v1 repertoire rendered legibly and correctly
positioned, on all three architectures, matching the 4.3.3b/4.3.4 completion pattern
(screendump-verified, not just non-crashing). Three-arch acceptance boot clean, logs
committed. *Refs:* §27.6.
⋯ *(4.3.x is open-ended — more items get appended here as Console work is scoped item by*
*item, developed on the fly per §25.0. 4.4 below is unaffected by anything added above*
*this marker.)*
@@ -4895,3 +4942,39 @@ source = 32 + ((slot + pin - 1) % 4) /* 32..35 */
relying on QEMU's auto-assignment — deterministic, and keeps this table's slot-3 row as the
one that actually matters for that item, though the runtime formula above holds regardless
of slot.
### 27.6 Glyph rendering, UTF-8 Latin, capsule-loaded (4.3.64.3.6g)
Scoped 2026-08-09, next after the 4.3.5f checkpoint, per the 2026-08-07 sequencing note
(§25.5): keyboard input → glyph rendering → REPL, before the 4.4 Artemis boundary.
**Purpose and boundary.** Render text onto the CANVAS region of the Stadium UI (per the
reviewed mockup: a fixed REPL strip at the bottom of the screen, a separate large CANVAS
region above it) using the stroke-drawing primitives 4.3.3b already built (`LINE`/`CIRCLE`/
`ARC`/`ELLIPSE` in `capsules/fabric.4th`). Additive, not a modification of the VT100 console
text path. **Non-goal, explicitly deferred:** the CANVAS's actual scrollable framebuffer
viewport (sizing, e.g. a 640×480 region) is REPL-wiring scope (M8), not this item.
**Why `font_8x16.c` stays, structurally, not by preference.** The new font system is
FORTH-capsule-based, so it only exists once the VM is up — `sk_vm_bootstrap.c`'s capsule/VM
bootstrap is milestone M7, after console/PMM/VMM/interrupts/timer/kmalloc (M1M6,
`kernel_main.c`). Anything rendered before or during that window — early boot messages, the
REPL itself — has no capsule system to draw from yet, so the baked-in `font_8x16.c` raster
font remains the only thing that can render text that early. It stays, unchanged, as the
VT100/REPL path's font regardless of what this item builds.
**Boot wiring — resolved 2026-08-09.** The font capsule (and its `fabric.4th` dependency, not
currently `EXEC`'d anywhere in `init.4th`) gets wired into `init.4th`'s boot chain, loading as
early as the capsule/VM bootstrap allows — reversing 4.3.3's "Console isn't a fleet VM yet,
not wired in" stance for this specific capsule pair. This is 4.3.6d, below.
**Found, not wired — flagged, not built on.** `include/block_subsystem.h:168` declares a
per-block `encoding` field (`0=ASCII, 1=UTF-8, 2=binary`) that nothing in the tree reads or
writes — dead metadata. Not assumed functional; a ruling on wiring it up vs. ignoring it is
still open, not blocking anything below.
**Block namespace.** `fabric.4th` claims blocks 49004915 (confirmed against
`capsules/BLOCK_MAP.md`); 4916+ in that family is free. Whether glyph work extends
`fabric.4th` or lands in a new capsule file is an open call for whichever item creates it.
*Refs:* §25.5 (punch list).