ebox-playground

ebox-playground is the independent, generic file runner for Ebox DSL examples. It uses only public Ebox APIs; concrete layouts live in readable .ebox fixtures under examples/. flex-reference.ebox, grid-reference.ebox, and size-reference.ebox demonstrate layout and sizing with a restrained terracotta, sage, blue, violet, ochre, and teal visual language. interaction-reference.ebox demonstrates native Ebox interaction and retained updates.

ECSS 0.1.0 and TP 1.0.1 are independent packages and may be installed in either order. Install both before Ebox 2.0.1, then install Ebox Playground 0.1.1. ebox-playground never reaches into those packages' private APIs.

Standalone gallery entry points default to a definite 720 px canvas so nested examples have stable space in batch renders and one-window demos. Split-window .ebox previews instead resolve (vw 100) to the preview window's display-safe width. Section separators use their containing Column's available width, so they also fit a narrower root. etaf-playground remains the separate higher-level Component and Runtime showcase.

Standalone and batch fixture renders use the same compact 720 px default viewport unless the caller dynamically binds ebox-viewport-width; viewport-based references therefore stay inside the example canvas. When C-c C-c renders an .ebox source buffer, the command keeps the source on the left, opens the preview on the right, and resolves (vw 100) to Ebox's shared display-safe window width. Ebox's single serialized viewport controller publishes every window change immediately through its retained path; the Playground owns no second resize hook or timer.

(require 'ebox-playground)
(ebox-playground-open)

Open examples/size-reference.ebox and press C-c C-c for Ebox Size Reference. It demonstrates the six length units on their permitted axes, the supported keyword values for all six size constraints, calc/min/max/clamp, and combinations with fonts, spacing, Flex, and Grid. Resize the preview to compare percentages with viewport units and see fluid sizes change. Precision and buffer-renderer limitations are stated in the example rather than presented as browser-equivalent behavior. Constrained long-text samples separate intrinsic widths; Row samples separate auto from stretch. Height content keywords are explicitly marked equivalent in the current renderer. Shared low/middle/high inputs show how min, max, and clamp respond at their boundaries. Solid rectangles mark the measured Box's full extent, including empty space; pale rulers show available parent width, while white cards contain the labels.

Run make size-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs to check the core size contracts and the actual example declarations, known arithmetic results, painted sizing differences, complete rendering, and retained viewport updates. make check also includes the example's regression tests.

Native interaction lab

Open the interaction reference with the existing file runner:

(require 'ebox-playground)
(ebox-playground-open-file
 (expand-file-name "examples/interaction-reference.ebox"
                   ebox-playground-directory))

You can also visit examples/interaction-reference.ebox and press C-c C-c for a source/preview split. Ebox Native Interaction Lab first separates help text and pointer shapes from hover paint, then combines :help-echo, :pointer, :hover-style, and :keymap in a live counter and event log.

• Hover the bordered cards, including their padding, to compare static help, dynamic help, native pointers, and color/text-decoration changes.
• Click ADD / [+] to add or the separate [-] Text to subtract. Move point into an action to use RET / SPC, or use its + / - shortcuts. SWITCH STEP 1 / 5 replaces its keymap with commands for the chosen step.
• SWITCH HOVER PALETTE replaces hover paint. REMOVE / RESTORE clears all four capabilities with explicit nil, then restores them. The Text reset action resets the count.
• UPDATE STATUS GROUP updates the three .demo-status Boxes together through one public ebox-update-selector call.
• The nested surface demonstrates parent coverage, a Text child with its own commands, and an explicit-nil child that blocks enclosing capabilities. The event log records which command ran.

Box help, pointer, and keymap include content, padding, and border, excluding that Box's margin and structural newlines. A hover owner's text and padding share one native mouse-face within a rendered line; unspecified attributes use that owner's base style, including when child text normally differs. Physical left/right borders are excluded from hover; horizontal border strokes keep their paint. Native pointer appearance and help display depend on Emacs settings and the window system. See the public capability contract.

interaction-reference.el owns the business functions and state; interaction-reference.ebox owns the layout. The runner reloads the matching .el before each preview. Ebox's ebox-help-create supplies the native help adapter; ebox-keymap-create binds zero-argument callbacks and updates named regions with ebox-region-update. Mouse callbacks automatically run in the event window's buffer. Ebox adds no application state or focus navigation system; use ordinary point motion for keyboard bindings. Keymaps are snapshotted, so publishing new bindings requires replacing :keymap. Each evaluation creates a fresh demo.

Run the interaction checks from this directory:

make interaction-tests EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs

The target verifies the core interaction contracts and this fixture's rendered capabilities, command effects, replacements, and removal/restoration. make check also includes the Playground interaction regression tests.

For repeated-key behavior and command timing, use the shared interaction evaluator:

emacs -Q --batch -L . -L ../ebox -L ../ecss -L ../tp \
  -l scripts/ebox-playground-flex-resize-evaluator.el \
  --eval '(pp (ebox-playground-interaction-evaluator-run "examples/interaction-reference.ebox" "ADD " "RET" 30 720 200))'

The signature is (FILE LABEL &optional KEY STEPS WIDTH HEIGHT). It opens a fresh temporary preview, finds the visible label once, and repeats native key lookup at the resulting point without repositioning after updates. Losing the node's binding fails the run. KEY accepts a key-description string or event vector; defaults are RET, 30 commands, 720 px width, and 200 lines of height. Sample count and dimensions must be positive integers.

The returned plist reports mean/p95/max command milliseconds, GC count/time, allocated cons cells (:cons-cells, to track allocation pressure), publication count, final plain text, and parity with an independent render of the committed snapshot. Work counters :layout-calls, :surface-plans, :fragment-scans, and :node-registrations count calls to layout rendering, surface planning, fragment extraction (including local slices), and node-tree registration. :fragment-characters sums the characters passed to fragment extraction. Read the call counts alongside this character total to distinguish local work from full-surface scanning; call counts are not affected-node counts. A parity mismatch fails.

Timing includes synchronous command execution, publication, and GC. Timings, GC, publication counts, and work counters cover only the command loop; initial mounting and the final parity render are excluded. The evaluator excludes GUI redisplay, OS key-repeat latency, and idle prewarming. The sampling loop checks a 30-second deadline between commands. Temporary preview and owned timer cleanup runs on success, error, timeout, or interruption, preserving existing previews and windows. Reuse this entry point for interaction regressions instead of ad hoc key-repeat timing scripts.

For native click dispatch in an already visible preview, load the same evaluator and call (ebox-playground-interaction-evaluator-click BUFFER LABEL &optional OFFSET). BUFFER is a live buffer or its name; the first matching label must be visible in a displaying window. OFFSET is a zero-based integer within the label and defaults to zero. For example, evaluate from the preview buffer:

(load (expand-file-name "scripts/ebox-playground-flex-resize-evaluator.el"
                        ebox-playground-directory) nil t t)
(ebox-playground-interaction-evaluator-click (current-buffer) "ADD " 0)
(ebox-playground-interaction-evaluator-click (current-buffer) "[-]" 1)

This constructs an Emacs mouse event, resolves the native binding, and uses call-interactively; it does not inject an OS mouse click. The helper does not select a window or move point itself. It returns the clicked position; check the counter or event log separately to verify the business result.

Author and render .ebox files

The package also owns the .ebox file boundary. Visiting an Ebox DSL file selects ebox-dsl-mode; its header line shows C-c C-c Render preview. Press C-c C-c to evaluate the file's single Elisp expression, build its resulting layout data through ebox-build, and automatically display the source and preview side by side.

(add-to-list 'auto-mode-alist '("\\.ebox\\'" . ebox-dsl-mode))

Write the same expression in .ebox that you would pass as the argument to (ebox-build ...) in Elisp. Quote a whole static layout; its list and symbol properties do not need additional quotes:

'(column :padding ((lh 1) (ch 2))
         :cross-align center
         (box :width (px 240) "Hello"))

Keep necessary business functions and variables in an optional same-basename .el file beside the .ebox. Before each preview evaluation, the runner loads that exact .el source if it exists, then evaluates the .ebox expression. This applies to C-c C-c, ebox-playground-open-file, and file rendering; saved .el edits are loaded on the next preview without require caching or selecting stale bytecode. A missing companion is allowed; a companion load error stops evaluation. Ordinary Elisp variable definitions control state retention or reset on reload.

For example, put the data and action in notes.el:

;;; notes.el --- Notes example behavior -*- lexical-binding: t; -*-
(defvar notes-body "A long article.")

(defun notes-help ()
  "Return business help for the article."
  (format "Article: %s" notes-body))

(defun notes-activate ()
  "Mark the article in the current Ebox buffer."
  (ebox-region-update "article" :color "#166534"))

Keep notes.ebox focused on the layout:

`(column :padding ((lh 1) (ch 2))
         (box :id "article" :width (px 480)
              :help-echo ,(ebox-help-create #'notes-help)
              :pointer hand
              :keymap ,(ebox-keymap-create :activate #'notes-activate)
              ,notes-body))

ebox-help-create adapts a zero-argument business function returning a string or nil to native help with the hovered buffer as context. ebox-keymap-create handles RET, [return], SPC, and [mouse-1] through :activate. Its optional :bindings alist pairs key-description strings or event vectors with zero-argument callbacks. Raw native keymaps are also accepted. See the public helper contract.

The runner evaluates one .ebox expression with lexical bindings on each render. Backquote preserves layout data, , inserts a value, and ,@ inserts a list of children. Properties and children in the result are data; the runner does not evaluate them separately. Keep business definitions in the companion; use Ebox's public adapters for native help and command plumbing, and do not add helpers merely to hide repeated DSL property lists.

Prefer concise DSL: omit redundant defaults, put common inheritable text styles on an existing parent, and write child overrides only. Keep explicit values in panels that teach those properties. The authoring rules explain which properties inherit. Empty Boxes have zero automatic content height; give one-line separators an explicit :height (lh 1).

For example simplifications, compare a saved baseline directory with the current examples directory using the existing evaluator:

emacs -Q --batch -L . -L ../ebox -L ../ecss -L ../tp \
  -l scripts/ebox-playground-flex-resize-evaluator.el \
  --eval '(ebox-playground-compare-example-directories "/path/to/baseline" "examples")'

The optional third and fourth arguments select viewport widths and file names. Defaults cover both references at 720 and 1000 px, including their complete documents. The comparison checks text, effective faces, display and interaction properties, and line widths; a mismatch fails the batch command. It creates no files or GUI windows and supersedes one-off comparison probes for this task.

For scrolling regressions across examples, use the same evaluator's generic scroll entry point:

emacs -Q --batch -L . -L ../ebox -L ../ecss -L ../tp \
  -l scripts/ebox-playground-flex-resize-evaluator.el \
  --eval '(ebox-playground-scroll-evaluator-run (directory-files "examples" t "\\.ebox$") 721 20 45)'

The arguments are one file path or a list of paths, viewport width in pixels, sample count, and viewport height in lines. Each file needs a scrollable root. Content is fully cached before alternating one-line motions at the top and midpoint. Results report mean/p95/max milliseconds, full root renders, node style visits, style computations, and fresh-render parity; incomplete motion or changed output fails the run. The independent render comparison ignores runtime identity and zero-pixel spacers beside identical font faces; height carriers are retained. This measures retained TP scroll publication, excluding native window scrolling, idle prewarming, and redisplay. To compare GUI font metrics, load this evaluator and call the same function in the existing GUI Emacs. It uses undisplayed temporary buffers, preserves live previews and windows, and cleans its mounts, advice, and timers even on errors or interruption. This entry point supersedes temporary per-example scroll timing probes.

Size data uses (unit number) with px, %, vw, vh, ch, and lh, plus calc, min, max, and clamp. The shared unit-constraint table defines which units each property accepts; the axes cannot be mixed, including in nested function branches. Ebox rejects invalid combinations when it builds the tree. For example, the preview can stay one line shorter than the viewport with :height (calc (- (vh 100) (lh 1))); the expression is resolved by Ebox on each layout. fit-content stays a bare keyword and does not take an argument. Border thickness has its own paint-unit rule in the same table. Ebox's buffer backend quantizes vertical content to complete lines. See the Ebox sizing contract.

To migrate an old unquoted .ebox layout, quote the whole static list and remove the quotes around its list and symbol properties, for example :padding '(1 2) becomes :padding ((lh 1) (ch 2)). For dynamic values, use backquote and an explicit comma: a computed pixel width becomes :width (px ,(+ 200 40)). Bare lengths, singleton pixel lists, and the old viewport keywords must also be migrated. The runner does not auto-detect the legacy format.

The reference fixtures live directly under examples/. For example:

(ebox-playground-open-file
 (expand-file-name "examples/grid-reference.ebox"
                   ebox-playground-directory))

Run make check EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs from this directory.

Run make performance for the committed Flex resize gate. It prepares ECSS, TP, Ebox, Playground bytecode, and the Rust module, then renders a read-only HEAD:examples/flex-reference.ebox snapshot without touching the working-tree fixture. The GUI driver performs five warmups followed by 30 accepted viewport updates; requested and published widths must match exactly, and both p95 and max must remain at or below 50ms. For uncontaminated repeated samples, run make performance-prepare, let compilation activity settle, then run make performance-evaluator without rebuilding.