S3-010: Implement textured sprites, terrain triangles, and text

Parent and ownership

Parent epic: https://github.com/stacksjs/the-settlers-iii-remake/issues/6 Source owner: craft-native/craft. Master roadmap: https://github.com/stacksjs/the-settlers-iii-remake/issues/4.

Problem and observable result

Render atlas regions and player tint. Support clipping, transforms, ordering, and text. Bound asset and frame memory.

The current application is a browser prototype. Passing the Riverlands campaign does not establish original-game or native parity. This issue is complete only when its stated behavior has retained evidence.

Evidence and interfaces

Craft owns graphics, native hosting, and platform capabilities. stx owns compilation/reactivity. ts-css owns style semantics. Stacks owns build and release orchestration. The game consumes published contracts.

• https://github.com/craft-native/craft/tree/cfde9ae33285d0697182fc794f799e108c11db32
• https://github.com/stacksjs/stx/tree/c5db290664
• https://github.com/home-lang/home-os/tree/151269666bc09aa15a271f1c1f4603f681132e65

Pin the inspected revisions and fixture hashes in the implementation evidence. Original-game observations govern rules and timing. JSettlers is implementation evidence, not an authoritative balance specification. Unknown values remain explicitly unverified.

Acceptance criteria

• Render atlas regions and player tint.
• Support clipping, transforms, ordering, and text.
• Bound asset and frame memory.
• The visible result agrees with the underlying simulation or platform state, including failure paths.
• Tests exercise the maintained public interface and retain reproducible fixtures or execution receipts.

Test matrix

• Compare actual sprite and triangle pixels.
• Exercise invalid UVs, fonts, and allocation failure.
• Exercise invalid input, cancellation or interruption, and repeated execution where this interface permits them.
• Verify determinism/conservation for simulation changes and resource ownership/disposal for platform changes.
• Run owning-repository lint, relevant type checks and tests. Capture actual native output for native capability claims.

Scope constraints

Implement this behavior as a complete verifiable slice. Do not silently expand into adjacent tickets or substitute simplified gameplay. Keep the shared TypeScript simulation, shared stx signals, and ts-css conventions. Native gameplay and HUD must not depend on a WebView. HomeOS reuse must not introduce a kernel dependency into the game. Existing unrelated edits and authored guidance must be preserved.

Blocked by

• https://github.com/craft-native/craft/issues/390

Upstream release and adoption

Fix and test the owning source repository, run its existing bun run release:patch when it is a Bun package repository, verify published artifacts, then install into Stacks and release Stacks when affected. Update the game from verified published packages. HomeOS uses its own build/source provenance.

No node_modules edits, copied runtimes, generated-source string patches, fabricated globals, successful no-op implementations, or skipped release gates. Push tested conventional commits as Chris to the owning origin/main without coauthor trailers or force pushes.

Completion evidence

• Implementation commits and relevant upstream issue links.
• Exact checks and results, fixture hashes, and screenshots/native execution evidence where applicable.
• Published package versions, downstream lockfile identity, and release receipts when affected.
• Remaining limitations stated explicitly. Partial work does not close this issue.

CPU graphics source is implemented and independently reviewed, with the issue remaining open for publication, adoption and the source-level asset-accounting follow-up below.

Source commits:

• 7a357cf: borrowed affine atlas sprites, player-mask tint, textured triangles, validated bitmap-font UTF-8 text and ordered atomic frames.
• 4bbbcc7: public contracts and limits.
• Integrated current main 189980c and normally pushed 94fe67f as Chris, without coauthor trailers.

The standalone graphics module allocates no scene/frame storage and retains no borrowed pointers. Validation rejects invalid UVs/fonts/transforms, writable-canvas aliases and exceeded budgets before writes. Family/system-font lookup remains explicitly unavailable. This establishes CPU pixel behavior, without claiming native presentation, GPU execution or original-game fidelity.

Two independent review regressions are retained: extreme finite inverse coefficients overflowing during evaluation, and fractional shared edges rounding both directions negative. Inverse evaluation is preflighted before any writes; shared edges use canonical endpoint evaluation and orientation sign, without an epsilon. The fractional case now produces exactly 0x80FFFFFF once across both windings, both command orders and immediate/frame interfaces.

Verification on pinned Zig 0.18.0-dev.146+35accc0:

• 73 focused Debug tests (52 renderer + 21 graphics) and 21 native ReleaseSafe graphics tests passed.
• Integrated full Zig/build contracts 204/204 steps passed; 4880/4904 executed tests passed with 24 existing platform skips and remaining targets cached. Native ReleaseSafe CLI build passed.
• SDK 767 tests / 2012 assertions, all 3 package type checks, npm package builds / 43 export checks, Zig formatting and docs links passed.
• Pickier reports 0 errors / 61 unchanged baseline warnings.
• Standalone x86_64Linux ReleaseSafe ELF compiled; Linux execution is not claimed from that compilation.

Reproducible synthetic RGBA8 fixture SHA256s, also retained in the public tests:

• Opaque 2x2 red/green/blue/white atlas: c21b35e3f28e676cedf24c13575a7346682e101a2d26aad9598d0cdbcee9ee3b
• White alpha 128 shared-edge texel: 1d89d17ddf37084f28b17459d47ac655f2f82929c7c537b5210e48fefb659aee
• White alpha 255 glyph texel: ad95131bc0b799c0b1af477fb14fcf26a6a9f76079e48bf090acb7e8367bfd0e

Remaining adoption constraint: frame asset accounting conservatively charges repeated atlas references again. A 64 MiB default therefore permits only 64 commands sharing a 1 MiB atlas. Before the game adopts this API, improve unique borrowed-asset accounting at this source using bounded deduplication and atomic-preflight regressions. Raising the game's budgets is not the planned remedy.

Release publication is held while the existing v0.0.282 acceptance/publication finishes and this source CI runs. The game has not adopted these APIs. No completion or platform-parity claim is made yet.

The owning source now accounts repeated borrowed asset views once per frame: https://github.com/craft-native/craft/commit/614c55512813109458c70063f14124f886e0892f

The allocation-free preflight uses an explicitly bounded table for up to 1024 exact typed views. Identical atlas, mask and glyph-metadata views deduplicate. Different roles, offsets, lengths and overlapping nonidentical views remain conservatively distinct. Full atlases remain charged. Invalid limits and late table exhaustion fail before pixels change; command, text and pixel-work limits still apply to every command. Game budgets have not been raised.

Independent source review and all 31 graphics tests passed. Local focused graphics/renderer tests passed 83/83; native ReleaseSafe graphics passed 31/31. The final full Zig graph passed 203/203 steps after an unchanged rerun following a documented local disk-space failure. Cross-target stack compilation is recorded separately from execution: the fixed table alone uses 48 KiB of entries plus counters and call frames.

This issue remains open. The v0.0.282 release failed its actual native acceptance gate; no successful publication or game adoption is claimed. The hybrid-navigation failure is being diagnosed from its retained simulator result bundle before a source correction.

Follow-up evidence for the remaining publication gate:

• 7a357cf2 covers atlas sprites, player-mask tint, textured triangles, validated bitmap-font UTF-8 text and ordered atomic frames.
• 614c5551 now charges repeated borrowed atlas/mask/glyph views once per frame through a bounded 1024-entry table, with atomic preflight and regression tests for table exhaustion and late invalid commands.
• Graphics/renderer/GPU targets pass on pinned Zig 0.18.0-dev.146+35accc06e; the full Zig suite exits 0, SDK 777/782 tests pass (5 intentional skips), typecheck/build/package-surface verification pass, and Pickier has 0 errors.

This remains open only until v0.0.296 is published and a downstream adoption receipt exists. Release run 39804169474 is still running iOS acceptance; the sole failed job is the stock Android software-emulator boot/ADB timeout, unrelated to the graphics implementation.

Completed and published in v0.0.296.\n\nThe implementation and remaining accounting follow-up are verified: covers atlas sprites, tint, textured triangles, bitmap-font UTF-8 text and ordered frames; deduplicates repeated borrowed atlas/mask/glyph views through a bounded 1024-entry table with atomic preflight regressions. Graphics/renderer/GPU, full Zig, SDK, typecheck, package-surface and Pickier checks pass. Release run 39804169474 passed after the Android emulator retry, and all platform archives are public in v0.0.296.

Correction to the release receipt above: the implementation commits are 7a357cf and 614c555. v0.0.296 is public with all platform archives and the release run passed after the targeted Android emulator rerun.

Reopening this slice because a clean consumer cannot use the published graphics package. The native pixel tests and implementation remain useful evidence, but they do not establish the published interface required by this issue.

I downloaded https://pantry.dev/zig/packages/craft/0.0.301/tarball and verified SHA-256 039b0838e927d8f766f4cc9a1aa1241b317fee353479fa0d985b2698f1f2789b against the original successful publication receipt. With the declared compiler 0.18.0-dev.146+35accc06e:

1. A clean graphics consumer using the advertised registry dependency fails with invalid hash: incomplete. The registry advertises raw archive SHA-256 prefixed with 1220; native zig fetch computes craft-0.0.301-HIz1i26FpwB5p2UfBnczFbQAKnsNdBZDtjreAS7l9UL-. The owning registry correction is /pantry-pm/pantry/issues/248.
2. A separate diagnostic consumer using the compiler-derived hash reaches the next real failure: dependency path outside project. The published Craft manifest still declares zig_js at ../../../../Libraries/zig-js, and zig-js itself declares sibling zig-gc and zig-regex paths. This requires portable upstream dependency declarations, not copied sibling trees in the consumer.

Neither probe qualifies the public Zig library. They retain the actual failure rather than skipping JavaScript runtime construction or patching package caches. Completion still needs the maintained release flow, original published artifact verification, and successful clean public-package consumption before downstream adoption can support this graphics claim.