wlgol/openspec/changes/input-and-placement/design.md

Design

Context

Current application (wlgol.c) renders an animated stripe pattern into a fixed 400x400 shm buffer, handles only Escape, and ignores configure size and output scale. Input modules (tkeyboard, tpointer) exist but pointer motion/buttons are unimplemented and keyboard callbacks do not carry modifiers. HiDPI is unsupported. See proposal.md for motivation.

Goals / Non-Goals

Goals:

• Configurable, modifier-aware key bindings with TOML merge over defaults.
• Interactive pattern placement with preview, rotation, click placement, cancellation.
• HiDPI-correct rendering (fractional and integer).
• Cell grid storage/rendering with resize preservation and wall boundaries.

Non-Goals:

• Game of Life simulation rules (future change).
• Text rendering/HUD (status via stdout).
• Persistent grid save/load.
• Fractional scaling on compositors lacking the protocol beyond integer fallback.

Decisions

D1: TOML config via vendored tomlc99

• Choice: Vendor tomlc99 (single .c/.h) for parsing ~/.config/wlgol/keys.conf.
• Rationale: User requested TOML; no system TOML library available; vendoring avoids new system dependency.
• Alternative: Hand-rolled subset parser (less code, but TOML edge cases and maintenance burden).

D2: Binding representation

• Choice: Store bindings as array of {mods_mask, keysym, action}. Lookup by exact modifier mask (ignoring lock mods) and keysym on key press.
• Rationale: Simple, fast enough for single-threaded event loop.
• Alternative: Hash table keyed by (mods, keysym) — premature; linear scan over ~20 bindings is trivial.

D3: Keyboard callback carries modifiers

• Choice: Extend keyboard_key_handler_t to (..., uint32_t mods, void *user_data), computed in tkeyboard.c from xkb state.
• Rationale: Binding matching needs modifier state; centralizes xkb modifier queries.

D4: HiDPI via fractional scale + viewporter

• Choice: Prefer wp_fractional_scale_v1; render physical buffer = ceil(logical * scale); set buffer_scale=1 and wp_viewport destination = logical size. Fallback to wl_output.scale integer (treat as scale value).
• Rationale: Exact fractional scaling; unifies rendering path through viewporter.
• Alternative: Integer-only scaling (simpler but blurry/wrong at 125%/150%).

D5: Logical canvas and grid

• Choice: Logical surface size from xdg configure (default 400x400). Grid dimensions = logical / 8. Cell size in logical pixels fixed at 8.
• Rationale: Consistent interaction across scales; HiDPI keeps physical cell size proportional.

D6: Grid storage and resize

• Choice: struct grid { int cols, rows; unsigned char *cells; } (0/1). On resize, allocate new buffer, copy overlapping region, free old.
• Rationale: Preserves user work on window resize; simple.

D7: Pattern definitions and rotation

• Choice: Each pattern stores base cell offsets and a rotation (0..3). Transform offsets at use time; bounding box computed from transformed offsets. Anchor = top-left of bounding box at cursor cell.
• Rationale: Avoids duplicating 4 variants per pattern; rotation stays consistent.

D8: Placement state machine

• Choice: States IDLE and ARMED. Key select → ARMED; motion updates preview cell; rotate increments rotation; left click places if in-bounds (stays ARMED); Escape → IDLE.
• Rationale: Matches requested UX; tool remains active for repeated placement.

D9: Protocols generation

• Choice: Vendor/copy viewporter.xml and fractional-scale-v1.xml into repo (from system wayland-protocols) and generate headers/sources via wayland-scanner in CMake, mirroring xdg-shell.
• Rationale: Reproducible builds without depending on system protocol paths.

Risks / Trade-offs

• [Fractional scaling complexity] → Mitigation: isolate in scale.c; integer fallback ensures basic functionality.
• [Resize resets grid partially] → Mitigation: preserve overlapping region; document behavior.
• [tomlc99 vendoring licensing] → Mitigation: verify license (MIT) before commit.
• [No font rendering] → Status via stdout; acceptable for this change.
• [Placement near edges] → Mitigation: reject invalid placement; preview indicates invalid state (e.g., red tint).

Migration Plan

1. Add generated protocol files and CMake changes.
2. Vendor tomlc99.
3. Implement modules and integrate into wlgol.c.
4. Update tests (hashtable unchanged; add config/grid unit tests if feasible).
5. Run ctest and build.

Open Questions

None — all blocking decisions resolved during exploration.