From d4282eb87b452ef8505c9f239b5d89ab459d2f9e Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Fri, 7 Aug 2026 10:33:13 -0400 Subject: [PATCH] FABRIC.md: split 4.3.1 into 4.3.1-4.3.4, one task per checkbox MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prior commit bundled four separate tasks (test pattern, screenshot capability, coordinate machinery, cube checkpoint) into a single numbered list inside one checkbox, violating the punch list's own convention of one task per box. Split into four checkboxes and updated §27 to match. --- FABRIC.md | 80 +++++++++++++++++++++++++++---------------------------- 1 file changed, 39 insertions(+), 41 deletions(-) diff --git a/FABRIC.md b/FABRIC.md index cdef9e4..db8aae8 100644 --- a/FABRIC.md +++ b/FABRIC.md @@ -3646,27 +3646,30 @@ document and committing that amendment as its own item.* > > **Discussion held 2026-08-07.** `.claude/CONSOLE.md` is a rough prior working draft, > superseded — not edited further, not treated as authoritative. Console's design lives - > in this document from here on. First slice scoped below as 4.3.1. + > in this document from here on. First slice broken out below as 4.3.1–4.3.4. Explicitly + > out of scope for all four: raster image (PNG/JPEG) rendering as fabric backgrounds — + > real direction, raised 2026-08-07, deliberately deferred past this slice; also fonts, + > scrolling, cursor/VT100 semantics, the Hermes message protocol, and Console as a fleet + > VM under Hera's birth protocol — later 4.3.x items, scoped once this slice is reviewed. -- [ ] **4.3.1 — Framebuffer sanity and the coordinate fabric.** First real work on Console: - prove the raw hardware boundary before anything Stadium- or VM-shaped touches it. *Refs:* - §27. Scope: - 1. Confirm `framebuffer.c` is wired to the real UEFI GOP `BootInfo` and draw a simple - orientation-revealing test pattern (raw pixel primitives only — no coordinate/Z - machinery yet). - 2. Add QEMU monitor/QMP screenshot capability (`screendump`) so the result can actually - be inspected — none exists today; all three `qemu` targets currently run with - `-display none` and no monitor attached. - 3. Stand up Cartesian coordinate machinery: origin bottom-left `(0,0)`, Y-up, plus a new - Z axis — depth-into-screen, not height. Fixed orthographic projection for now (angle - TBD — true 45° cavalier vs. 2:1 isometric, still open); explicitly a placeholder, not - the final projection — this is heading toward real 3D animation later, not a static - scene. - 4. Draw a cube using the new machinery. Stop here for review — first real exercise of the - coordinate/projection math, not expected to be fast. +- [ ] **4.3.1 — Framebuffer sanity: draw a test pattern.** Confirm `framebuffer.c` is wired + to the real UEFI GOP `BootInfo` and draw a simple orientation-revealing test pattern, using + the existing raw pixel primitives only — no coordinate/Z machinery yet. *Refs:* §27.1. - **Explicitly out of scope for 4.3.1:** raster image (PNG/JPEG) rendering as fabric - backgrounds — real direction, deliberately deferred past this slice. +- [ ] **4.3.2 — QEMU screenshot capability.** Add a monitor/QMP socket to the `qemu` targets + (mirroring the existing serial-socket pattern) so `screendump` can be issued and the 4.3.1 + test pattern actually inspected. None exists today — all three targets currently run with + `-display none` and no monitor attached. *Refs:* §27.2. + +- [ ] **4.3.3 — Cartesian coordinate machinery.** Origin bottom-left `(0, 0)`, Y-up, plus a + new Z axis (depth-into-screen, not height) and a fixed orthographic projection as a + placeholder — not the final projection, no perspective/camera work yet. Angle open: true + 45° cavalier vs. 2:1 pixel-art isometric; settle when this item is actually implemented. + *Refs:* §27.3. + +- [ ] **4.3.4 — Checkpoint: draw a cube.** First real exercise of the 4.3.3 coordinate/ + projection machinery. Stop and review here before scoping the next 4.3.x item — not + expected to be fast. *Refs:* §27.4. - [ ] **4.4 — Artemis last.** It works today; it is the thing that cannot be broken. *Refs:* §10. @@ -3978,29 +3981,29 @@ sites). **STATUS: design-stage, 2026-08-07.** Supersedes `.claude/CONSOLE.md` as the authoritative Console design document. `CONSOLE.md` was a rough prior working draft and is not edited further; nothing in it should be treated as decided just because it is written down there. -This section covers 4.3.1 only — the groundwork slice: verify the hardware boundary works -and stand up the coordinate machinery. It is explicitly *not* the full Console specification -(fonts, scrolling-as-a-VM-behavior, message protocol from Hermes, etc.) — those are later -items under 4.3, scoped once 4.3.1's checkpoint is reviewed. +This section covers 4.3.1–4.3.4 only — the groundwork slice: verify the hardware boundary +works and stand up the coordinate machinery. It is explicitly *not* the full Console +specification (fonts, scrolling-as-a-VM-behavior, message protocol from Hermes, etc.) — +those are later items under 4.3, scoped once this slice's checkpoint (4.3.4) is reviewed. -### 27.1 The hardware boundary already exists +### 27.1 The hardware boundary already exists (4.3.1) `console_fb_init()` (`hal/console.c:269`) calls `fb_init()` with real UEFI GOP data from `boot_info->framebuffer`, but only after POST completes, immediately before the REPL starts (`kernel_main.c:800-807`). `include/starkernel/framebuffer.h` already exposes raw pixel primitives: `fb_put_pixel`, `fb_fill_rect`, `fb_draw_glyph` (8×16 cells), `fb_scroll_rows`. -There is nothing to build to get pixels on screen — 4.3.1's first task is *verification*, -not construction: draw a simple, orientation-revealing test pattern with the existing -primitives and confirm it displays right-side up. +There is nothing to build to get pixels on screen — 4.3.1's task is *verification*, not +construction: draw a simple, orientation-revealing test pattern with the existing primitives +and confirm it displays right-side up. -### 27.2 No screenshot capability exists today +### 27.2 No screenshot capability exists today (4.3.2) All three `qemu` targets in `Makefile.starkernel` run with `-display none` and attach only a serial chardev socket (for the log) — no monitor, no QMP socket. There is no way today to -issue QEMU's `screendump` command. 4.3.1 adds a monitor/QMP socket (mirroring the existing +issue QEMU's `screendump` command. 4.3.2 adds a monitor/QMP socket (mirroring the existing serial-socket pattern) so the framebuffer can actually be inspected as a `.ppm` after a run. -### 27.3 Coordinate system +### 27.3 Coordinate system (4.3.3) - **Origin bottom-left**, `(0, 0)`. Traditional Cartesian, not raster/top-left-Y-down. The framebuffer's native memory layout is top-left origin, Y-down — the Y-flip transform must @@ -4015,15 +4018,10 @@ serial-socket pattern) so the framebuffer can actually be inspected as a `.ppm` cleanly on a pixel grid). Not settled; settle it when the projection math is actually written, not speculatively here. -### 27.4 Checkpoint: a cube +### 27.4 Checkpoint: a cube (4.3.4) -4.3.1's acceptance is a cube rendered on screen using the coordinate/projection machinery -above — the first real exercise of that math, expected to take real effort, not a quick -add. Stop and review here before scoping the next 4.3.x item. - -### 27.5 Explicitly out of scope for 4.3.1 - -- **Raster image rendering** (PNG/JPEG decode, composited onto the fabric as backgrounds). - Real direction, raised 2026-08-07, deliberately deferred past this slice. -- Fonts, scrolling, cursor/VT100 semantics, the Hermes message protocol, Console as a fleet - VM under Hera's birth protocol — all later 4.3.x work, not 4.3.1. +Acceptance for this whole slice is a cube rendered on screen using the 4.3.3 coordinate/ +projection machinery — the first real exercise of that math, expected to take real effort, +not a quick add. Stop and review here before scoping the next 4.3.x item. Out-of-scope list +for 4.3.1–4.3.4 is recorded once, at the 4.3 punch-list entry itself (§25.5), not repeated +per sub-item.