FABRIC.md: split 4.3.1 into 4.3.1-4.3.4, one task per checkbox

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.
This commit is contained in:
Robert Allan James
2026-08-07 10:33:13 -04:00
parent f3967fa596
commit d4282eb87b
+39 -41
View File
@@ -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.14.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.14.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.14.3.4 is recorded once, at the 4.3 punch-list entry itself (§25.5), not repeated
per sub-item.