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 > `#ifdef __STARKERNEL__`, or elsewhere is an open question for that later item, not
> decided here. > 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* ⋯ *(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* *item, developed on the fly per §25.0. 4.4 below is unaffected by anything added above*
*this marker.)* *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 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 one that actually matters for that item, though the runtime formula above holds regardless
of slot. 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).