Repository navigation
feat: graphics substrate (registry, tier engine, cell integration) - #141
Draft
natemoo-re wants to merge 4 commits into
Draft
natemoo-re wants to merge 4 commits into
natemoo-re wants to merge 4 commits into
Conversation
Contributor
No changeset neededThis pull request is classified as no_release_impact: no published package |
![bombshell-cooper[bot]](https://avatars.githubusercontent.com/in/4226441?s=60&v=4){kind=small}
natemoo-re
added this pull request to stack #143
October 9, 2026 20:10
natemoo-re
marked this pull request as draft
October 9, 2026 20:11
|
Size Increased — +11.5 KB 134.2 KB unpacked |
commit: |
The Graphics Specification's engine, in C: - Memory carve (§5): a dimension-independent graphics region beside the per-dimension clayterm carve - fixed-capacity entry table (256), compaction-only pixel pool (imagePoolBytes, 4 MiB default), double- buffered placements tables (64). setImage/removeImage never grow linear memory; the region survives resize untouched, which is what makes future zero-copy surface views sound (§4.5). - Registry surface (§7.2): two-phase image_begin/image_commit (the host writes pixels at the reserved absolute address between calls; video's same-size path allocates nothing), image_remove emitting the data- freeing d=I block and reconciling covered cells, graphics_capability with immediate deletion bytes on capability denial (§11.2), and graphics_resize_prepare emitting deletions before the dimension state is discarded (§10.5). - Tier engine (§9): pre-layout resolution (variant/omission/liveness/ evidence/line-mode cap) into a Clay element - the alt tier expands to a wrapped, clipped text child; pixel tiers attach the op wire as customData. The render-command walk then applies the footprint- preserving demotions (clip containment §8.5, placement-id collision §9.2.1, overlap §10.3, table capacity §5.4), records kitty placements, and paints ascii art. - Frame phases (§9.2.6): coverage pass, repair precheck, scoped stale deletions (lowercase d=i,p=), delete-before-re-transmit chunked transmission (4096-char chunks, q=2 everywhere), placements after cell writes with the §7.6 cursor restore, byte-silent steady state. - ASCII art (§9.3): per-cell circle sampling from the pool, pinned power-of-two contrast exponents (exact repeated squaring, no libm), and build-time shape vectors generated from the public-domain 8x8 bitmap font by tasks/gen-shape-vectors.ts (deno task gen-shape). Existing 328 test steps pass; the engine is exercised end to end (ascii art, kitty transmission/placement/steady state/removal) in a scratch smoke run; the public TypeScript surface and the §14 test suite land in the img PR.
- input.c: the kitty graphics APC recognition required the response
shape - replies never carry an action key, so frames beginning with
a= (the renderer's own quiet q=2 emissions relayed through a mux,
or another client's commands) no longer surface as spurious
CapabilityEvents. INV-I5's input-stream cleanliness now holds even
when output bytes reach the input parser.
- clayterm.c: the img element's declared bg forces the color's alpha
to opaque at decode (cells cannot be transparent; the value space
is open({bg})'s rgba()) - Clay skips a=0 rectangles, which silently
dropped the declared background.
natemoo-re
force-pushed
the
feat/graphics-substrate
branch
from
October 9, 2026 20:17
8813820 to
30aa8fa
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the Graphics Specification engine in C (stacked on the spec PR; the public TypeScript surface + test suite land in the img PR after this).
What lands here
Memory (§5). The engine gains a second, dimension-independent carve beside the per-dimension clayterm carve:
[gfx: entry table (256) | pixel pool (4 MiB default) | placements tables (64×2 double-buffered)]. Because the region never moves or re-initializes, the registry survives resize untouched (§10.5) — and this is exactly the property §4.5 calls out for the future zero-copy canvas surface views.setImage/removeImageMUST NOT grow linear memory (INV-I8); capacity failures are closedRangeErrorcodes, compaction is the only reclamation.Registry surface (§7.2). Two-phase native calls:
image_beginvalidates and reserves (returning the absolute address the host writes pixels at — video's same-size-per-frame path allocates nothing),image_commitbumps the data version.image_removeemits the protocol's data-freeingd=Ideletion block into the output buffer and reconciles covered cells to their blank state (INV-I6) so the next diff emits nothing redundant.Tier engine (§9). Pre-layout resolution (variant, omission, liveness, evidence mirror, line-mode cap) expands the void
imgop into a Clay element: the alt tier is a wrapped, vertically-clipped text child (so alt's fit sizing and wrap come from the layout engine's own text machinery); pixel tiers attach the op's wire address ascustomData. The render-command walk then applies the four footprint-preserving demotions (clip containment §8.5, placement-id collision §9.2.1, pixel-overlap §10.3, table capacity §5.4) — kitty→ascii only, same painted footprint, no re-measurement — then records the placement or paints the art.Frame phases (§9.2.6). Coverage pass (pixel coverage asserts blanks over the back buffer, later element wins shared cells) → repair precheck (a placement whose covered cells will receive writes re-places; runs before any dirty-marking) → scoped stale deletions (lowercase
d=i,i=…,p=…, data retained) → delete-before-re-transmit chunked transmission (4096-char base64 chunks,m=1/m=0,q=2on every block) → cell writes (the ordinary diff) → placements after, with the §7.6 cursor-restore carve-out. Steady state is byte-silent.Ascii art (§9.3). Per-cell circle sampling (6 internal + 10 external, geometry in the source and mirrored in the generator), directional-then-global contrast with power-of-two exponents (γd=4, γg=2 — exact repeated squaring, no libm, bit-identical everywhere), 95-character nearest-match against shape vectors generated at build time from the public-domain font8x8 bitmap font (
deno task gen-shape, golden-lockable).Capability mirror.
graphics_capability(ct, kitty)— the renderer's private capability state (terminfo-spec §4.2); the true→false transition emits the §11.2 denial bytes immediately (TINV-5). Wired to theupdate()capability fold in the img PR.Verification
makebuilds clean; the full existing suite passes (27 tests / 328 steps — post-feat: term.update() folds CapabilityEvents into runtime capabilities #133 main, this branch is rebased onto it).d=Iremoval bytes.