4.3 KiB
Ebox repository guidance
This repository is the standalone low-level Ebox package. It owns box nodes, style normalization, measurement, layout, rendering, semantic update planning, selector integration, Grid, and the optional Rust reflow module. Ebox plans publication scope and projects retained surface inputs; TP owns live buffer publication, diff execution, revisions, and rollback. ECSS owns selector parsing, matching, and cascade semantics while Ebox adapts nodes and candidate indexes. The sibling etaf repository owns the higher-level text-application framework; etaf-playground and ebox-playground are separate example packages.
Keep this repository independent from ETAF. Do not add Components, Runtime state, Data Controllers, UI controls, or application examples here. Ebox may call ECSS and TP only through their public APIs; private ebox--* functions remain internal to this package.
When authoring Ebox DSL, prefer the shortest declaration that preserves the intended behavior: omit redundant defaults, put shared inheritable text styles on an existing common parent, and declare only child differences. Keep explicit overrides and properties that an example is teaching. Check the actual layout context before omitting sizes; auto and stretch are not universal aliases, and background paint showing through is not property inheritance. Follow the authoring rules in docs/user/ebox-user-guide.en.md and verify example simplifications at multiple viewport sizes.
Use apply_patch for hand-edited changes. Keep each file lexically bound, document public APIs, preserve deterministic rendering, and add a focused regression test for behavior changes. Run make check EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs before claiming completion. Run make native-rust-tests when changing native/ and run make docs-contract-tests when changing documentation or the active file boundary.
The old emacs-box checkout is a historical full-stack source tree. It is intentionally not a dependency of this package and should not be edited as part of Ebox work unless a separate task explicitly targets that legacy repository.
For legacy public CSS size migrations, use python3 scripts/migrate-css-sizes.py PATH... first, then the same invocation with --write for reviewed public DSL/style callers. The tool preserves comments, strings, and source formatting, and reports dynamic/ambiguous values for manual review. Do not apply it to measured engine structs merely because they use the same property names. See its --help for input, exit-status, and cleanup contracts; use python3 -m unittest discover -s scripts -p 'test_migrate_css_sizes.py' to verify the tool. Extend this entry point instead of creating ad hoc migration probes.
For mixed test/implementation files, add --callers ebox-build,ebox-create (or the actual public API names) to restrict migration to those call subforms. ETAF (styles ...) blocks are recognized as literal data; native Emacs (space ...) and image display specs retain their own size grammar.
For standalone packaging or clean installation verification, use make release-check RELEASE_DIR=/tmp/ebox-release EMACS=/path/to/emacs; the output directory must not exist. The shared scripts/ebox-release.py entry point fetches exact public commits from release-dependencies.json, creates deterministic package.el source archives, and installs them in a temporary profile without sibling load paths. Add RELEASE_OPTIONS=--with-ekp for the optional KP provider. Use make release-deps RELEASE_DEPS_DIR=/tmp/ebox-deps for CI checkouts, or --dependencies /absolute/deps to reuse explicit clean pinned checkouts during a build. Use make native-integration RELEASE_DIR=/tmp/ebox-release NATIVE_MODULE=/absolute/module EMACS=/path/to/emacs to require actual module loading and native rendering, or make release-native-check RELEASE_DIR=/tmp/ebox-release EMACS=/path/to/emacs to build the installed package's bundled native source first. Temporary resources are removed on completion, failure, interruption, or subprocess timeout; output archives and requested dependency checkouts are retained. Extend this entry point instead of adding per-release install scripts. Unit coverage is make release-tool-tests; never publish, tag, or replace an existing output directory implicitly.