Tier 4: BMP/GIF export, builder_recipe unification, hidden presets

[zeidalidiez]

Closes the deferred v1 spec work that tier 3 didn't fit: finish the v1 export-format matrix (BMP + GIF), wire the UI Builder recipe back into generateJob so a builder-authored asset ships as the actual bytes, and move presets behind a button so users don't trample in-progress work.

In this PR

1. BMP export (5bd2c52) — the spec calls PNG/JPG/JPEG/SVG/BMP/GIF the v1 export targets. New packages/core/src/bmp.ts is a pure BGRA encoder that both web OffscreenCanvas and CLI @napi-rs/canvas backends route image/bmp through (neither backend supports BMP natively).

2. GIF export (8beb124) — same gap for GIF. New packages/core/src/gif.ts is a GIF89a single-frame encoder with a 6×6×6 web-safe palette + 40 grayscale, LZW compression with dictionary reset at 4096 codes, and a Graphics Control Extension for transparent pixels.

3. Manifest/Builder unification (d7b5f21) — the spec says a manifest asset can reference a builder recipe (embedded or external). Until now builder_recipe wasn't on the manifest schema and generateJob ignored it.

   • Added optional builder_recipe to all four image-style asset kinds in both schema and TS types.
   • New packages/core/src/builderRender.ts is an env-agnostic layer renderer (rect, circle, line, text, filled-shape; image/pattern fills degrade to the fallback color in Node because we don't have OffscreenCanvas there).
   • generateJob branches on asset.builder_recipe and routes through renderBuilderRecipe instead of drawAsset. The recipe's own width/height override the asset's nominal bounds.

4. UI Builder: presets behind a button (5bd2c52) — engine-aware presets used to be inline in the right sidebar where one mis-click trampled in-progress work. Now they're behind a "Presets" button next to "Clear"; clicking opens an absolute-positioned popover with engine-grouped buttons, click-outside dismisses.

Verification

• pnpm -r build → green
• pnpm test → 53 core + 22 CLI = 75 tests pass (5 builderRender, 5 GIF, 6 BMP, 1 builder_recipe e2e, plus all existing)
• pnpm e2e → 4 Playwright tests pass (includes a new test that asserts the Presets button is hidden by default and the popover opens with engine-grouped preset buttons)

Notes

• New CI workflow timeouts untouched; the previous round bumped them to 20 min and the build is well under that.
• Greptile-friendly: each commit is self-contained and the diff stays in shape — schema changes, new encoder modules, one-off UI bit, then the recipe wiring at the end.

Greptile Summary

This PR closes the deferred v1 export-format work (BMP + GIF encoders), wires builder_recipe into generateJob so manifest assets can ship recipe-rendered bytes, and moves the UI Builder's engine presets behind a popover button to prevent accidental overwrites.

• BMP/GIF encoders (packages/core/src/bmp.ts, gif.ts) — pure-TS implementations used by both web and CLI backends; previous reviewer issues (opaque-black transparency, LZW code-size desync) are fully addressed with regression tests.
• Builder recipe unification (generate.ts, builderRender.ts, schema) — builder_recipe is now a validated optional field on image, tileset, and ui_panel assets; sprite_sheet is explicitly excluded at schema level, and generateJob throws early if it somehow reaches runtime.
• Presets popover (UIBuilder.tsx) — presets moved from the always-visible sidebar into an absolute-positioned dialog; the trigger button is included in the outside-click boundary so it correctly toggles without double-fire.

Confidence Score: 5/5

The PR is safe to merge; all three new subsystems are well-tested and the GIF/BMP encoders have been corrected from prior review rounds.

All previously identified issues are resolved with both code fixes and dedicated regression tests. The only remaining finding is a stale module-level comment that misrepresents the error-handling model — it doesn't affect runtime behavior.

The module-level comment in packages/core/src/builderRender.ts should be corrected before this file accumulates more callers that rely on it for error-handling semantics.

Important Files Changed

Filename	Overview
packages/core/src/bmp.ts	New pure-TypeScript BMP encoder; correct 14-byte file header, 40-byte BITMAPINFOHEADER, bottom-up BGRA rows with 4-byte row padding. Input validation and row-padding math are sound.
packages/core/src/gif.ts	New GIF89a single-frame encoder. Transparent slot moved to index 255 (fixing opaque-black transparency regression), LZW bump threshold corrected to (1 << codeSize) + 1 (fixing stream desync), GCE only emitted when transparent pixels are present.
packages/core/src/builderRender.ts	New core recipe renderer that throws on unsupported features (image/pattern fills, raster layers); module-level comment incorrectly describes a catch-and-skip behaviour that is not implemented.
packages/core/src/generate.ts	Routes recipe-backed assets through renderBuilderRecipe; sprite_sheet + builder_recipe combination throws early (caught by existing per-asset catch block) so the rest of the job continues cleanly.
packages/schemas/src/manifest.schema.json	Refactored from allOf+$ref to flat per-kind objects with additionalProperties:false; spriteSheetAsset correctly omits builder_recipe, and bmp/gif added to all image-style format enums.
apps/web/src/UIBuilder.tsx	Presets moved behind a popover button; outside-click handler correctly exempts the trigger via data-presets-trigger, so clicking the button while open toggles it closed without double-fire.
packages/core/src/validation.ts	Adds ajv.addSchema(builderRecipeSchema) before compiling the manifest schema, correctly enabling $ref resolution for the builder_recipe property at compile time.
apps/cli/src/canvas.ts	CLI canvas backend intercepts image/bmp and image/gif before toBuffer, routing them through the new core encoders since @napi-rs/canvas does not support those MIME types natively.
packages/schemas/src/types.ts	Adds bmp and gif to the Format union and adds builder_recipe to ImageAsset, TilesetAsset, and UiPanelAsset; SpriteSheetAsset correctly excluded with an explanatory comment.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[generateJob asset loop] --> B{asset.kind === audio?}
    B -- yes --> C[generateAudio]
    B -- no --> D{asset has builder_recipe?}
    D -- yes --> E{asset.kind === sprite_sheet?}
    E -- yes --> F[throw Error sidecar mismatch]
    E -- no --> G[createCanvas recipe dimensions]
    G --> H[renderBuilderRecipe layer stack]
    H --> I{layer type}
    I -- rect/circle/line/text/filled-shape --> J[draw to ctx]
    I -- raster or object fill --> K[throw unsupported layer]
    J --> L[handle.encode formatToMime]
    K --> M[per-asset error in report]
    F --> M
    D -- no --> N[createCanvas asset dimensions]
    N --> O[drawAsset standard grid]
    O --> L
    C --> L
    L -- image/bmp --> P[encodeBmp]
    L -- image/gif --> Q[encodeGif]
    L -- other --> R[native canvas encode]
    P --> S[zip.file]
    Q --> S
    R --> S

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[generateJob asset loop] --> B{asset.kind === audio?}
    B -- yes --> C[generateAudio]
    B -- no --> D{asset has builder_recipe?}
    D -- yes --> E{asset.kind === sprite_sheet?}
    E -- yes --> F[throw Error sidecar mismatch]
    E -- no --> G[createCanvas recipe dimensions]
    G --> H[renderBuilderRecipe layer stack]
    H --> I{layer type}
    I -- rect/circle/line/text/filled-shape --> J[draw to ctx]
    I -- raster or object fill --> K[throw unsupported layer]
    J --> L[handle.encode formatToMime]
    K --> M[per-asset error in report]
    F --> M
    D -- no --> N[createCanvas asset dimensions]
    N --> O[drawAsset standard grid]
    O --> L
    C --> L
    L -- image/bmp --> P[encodeBmp]
    L -- image/gif --> Q[encodeGif]
    L -- other --> R[native canvas encode]
    P --> S[zip.file]
    Q --> S
    R --> S

Loading

Comments Outside Diff (1)

1. General comment

   Base already accepts builder_recipe on image-style assets, so the claimed validation behavior change is not demonstrated

   • Bug
     • The validation objective expected base to reject or not know builder_recipe and head to accept it. Runtime validation showed both base 13c1aaf and head 472f940 return valid:true with no errors for builder_recipe on image, sprite_sheet, tileset, and ui_panel. This means the schema validation behavior at this scope is indistinguishable before and after the change.
   • Cause
     • The base manifest schema did not reject additional properties on the concrete image-style asset schemas, so builder_recipe was already permitted even before the head schema/types changes explicitly modeled it.
   • Fix
     • If explicit validation was intended to be newly introduced, tighten base/head schema behavior with additionalProperties:false or unevaluatedProperties:false on concrete asset schemas and add regression tests that prove unknown fields are rejected while builder_recipe is accepted only where intended. If accepting arbitrary extra fields is intentional, update the PR claim/test objective to state that the change documents/types an already-accepted schema field rather than changing validation behavior.

   _{Ran code and verified through T-Rex}

_{Reviews (4): Last reviewed commit: "Tighten manifest schema so sprite_sheet ..." | Re-trigger Greptile}

[greptile-apps]

Schema allows combination that generateJob always rejects

builder_recipe is declared as a valid optional property for spriteSheetAsset, but generate.ts unconditionally throws when it encounters this combination. Any manifest that includes a sprite-sheet asset with a builder_recipe will pass validateManifest cleanly, then consistently fail at generation with an asset-level error. The schema is advertising support for a pairing the runtime intentionally forbids, so callers have no way to know from validation alone that their manifest will not fully execute.