ebox-playground/AGENTS.md

Ebox Playground guidance

Keep this package a readable collection of public Ebox DSL examples and a generic file runner. Use only public Ebox APIs in examples and runner code; keep test and diagnostic access separate.

Default authoring rule: use the shortest declaration that preserves the intended effect. Omit redundant defaults, place shared inheritable text styles on an existing common parent, and write only child differences. Do not add helper functions, macros, or wrappers merely to hide repeated property lists. Keep values explicit when the panel teaches that property or when they override another declaration. Backgrounds do not inherit, and auto and stretch are only interchangeable in specific layout contexts. See the Ebox authoring rules.

Before simplifying examples, preserve the current files as a comparison baseline and run the existing tests. Keep text, teaching coverage, layout behavior, effective colors, and the user's root viewport settings. Verify rendered output at multiple viewport sizes and inspect the existing GUI preview without changing its font, frame geometry, or application focus. Use make check EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs for package validation. Extend existing test/evaluator helpers for repeated comparison work rather than writing competing scripts.

For before/after example comparisons, use ebox-playground-compare-example-directories from scripts/ebox-playground-flex-resize-evaluator.el; it accepts baseline/current example directories and optional viewport widths/file names. This is the shared entry point for future example simplification checks. See README for the batch invocation.

For scrolling performance across examples, use ebox-playground-scroll-evaluator-run from that same evaluator. Pass one .ebox path or a list, viewport width, sample count, and viewport height; it measures cached top/midpoint publication and verifies fresh-render parity while preserving existing GUI previews. Consult this entry point before adding another scroll probe, and extend it when the diagnostic coverage is missing. See README for the invocation and measurement boundaries.

For repeated interaction behavior or command performance, use ebox-playground-interaction-evaluator-run from scripts/ebox-playground-flex-resize-evaluator.el. Pass the .ebox file and visible control label, with optional key, sample count, width, and height. It performs native key lookup without repositioning after updates, reports command-loop timings/GC/publications and layout/projection work counters, and verifies committed-snapshot render parity. Read fragment call counts with their input-character totals to distinguish local slices from full-surface work. For native click dispatch in an already visible buffer, use the same file's ebox-playground-interaction-evaluator-click with buffer, label, and optional in-label offset; it resolves an Emacs event and calls the interactive command, not an OS mouse click. Consult and extend these entry points before adding another interaction probe; see README for inputs, cleanup, the between-sample deadline, and measurement limits.

Keep intentional spacer height explicit: use (box :height (lh 1)) for a one-line separator, omitting width when ordinary block sizing already fills its parent. An otherwise empty Box with automatic height has zero content height.

For size declarations, consult the shared Ebox unit-constraint table. Do not duplicate its matrix in a Playground-specific parser or guideline. Check the property's axis, every nested function branch, both axes after shorthand expansion, and the separate border-paint rule. Invalid combinations must fail at initial construction; examples must not depend on cross-axis conversion.

For size, unit, keyword, or sizing-function demonstration work, maintain examples/size-reference.ebox and run make size-tests (with EMACS set to the intended executable). Extend tests/ebox-playground-size-tests.el for coverage or numeric regressions instead of creating another size gallery or verification script.

Keep necessary business functions and variables in a same-basename .el file beside the .ebox layout. The generic runner loads that exact companion source, when present, before every preview evaluation, including C-c C-c and ebox-playground-open-file. Keep the .ebox focused on layout and its data references; do not add helpers merely to hide repeated property lists. Reload state according to ordinary Elisp definitions, and keep each companion lexically bound.

For native help, pointer, hover-style, or keymap demonstration work, maintain examples/interaction-reference.el and examples/interaction-reference.ebox, then run make interaction-tests (with EMACS set to the intended executable). Extend tests/ebox-playground-interaction-tests.el for capability, command, replacement, and removal regressions. Use ebox-help-create and ebox-keymap-create for zero-argument business callbacks and native help/command buffer context, and use ebox-region-update with semantic IDs in that buffer. These reusable adapters belong to Ebox; moving local adapters into the companion is not a substitute. Raw native callbacks and keymaps remain supported and own their event-context handling. Extend the generic runner tests for companion reload behavior rather than adding an example-specific loading mechanism.