# ETAF Module Responsibilities and Target Architecture (Design Proposal, Not Implemented) > Status: design proposal. This document does not describe the currently delivered API. > Current behavior remains defined by > [`architecture.en.md`](../architecture.en.md), > [`user-guide.en.md`](../user-guide.en.md), and passing tests. > The public Component vocabulary is synchronized with the > [Chinese proposal](module-boundaries.zh.md); both describe `:view`, `:render`, > optional `:setup`, opaque `etaf-state`, and the single public `etaf-node` > constructor at the target boundary. This document defines only the target model, module owners, dependency direction, and completion criteria. Implementation order belongs in a separate delivery plan; historical names and compatibility policy do not shape the target architecture. User mental cost is a hard constraint of this proposal: one capability has one canonical identity, canonical name, and recommended spelling. A small set of aliases may exist only as parse-time input sugar and must not become peer public concepts. Internal algorithms, backend nodes, wrappers, and compatibility aliases must not become peer public concepts. Ordinary applications need to learn only Text, Box, and Component; Fragment, layout details, and lower-level packages enter through progressive disclosure. ## 0. Design Decision Summary Ordinary ETAF users learn only Text, Box, Component, and these structural forms: ```elisp "plain text" (text PROPS "styled text") (box PROPS CHILD...) (row PROPS CHILD...) (column PROPS CHILD...) (flex PROPS CHILD...) (grid PROPS CHILD...) ``` `row/column/flex/grid` are only layout forms of Box. User properties fall into metadata, semantics/events, visual style, and parent participation. They use semantically aligned standard CSS names, a small set of explicit ETAF/Ebox-specific properties, and a small set of parse-time aliases. Users do not interact with the Ebox, TP, or Emacs backend. Standalone Ebox users access the same visual forms as inert data syntax through `ebox-build`, but have no Component, Fragment, expr, slot, or lifecycle. Framework integrators use only typed Text/Box constructors, LayoutConfig, and the render and commit boundaries. They do not reconstruct DSL, rerun cascade, or generate Emacs text properties. Internal execution has only four layers: ```text Author API → Canonical Model → Render Plan (Ebox geometry + TP paint + ETAF semantics) → Emacs Adapter commit ``` Core ownership remains unchanged: ETAF Runtime owns identity/lifecycle/reactivity; ECSS owns selectors/cascade/computed style; Ebox owns measurement/geometry; TP owns paint priority/transactions; only the final adapter owns Emacs text properties such as `face`, `display`, and `keymap`. Ordinary user documentation does not mention NormalizedView, PropertyDefinition, ProjectionPlan, node IDs, RangeAnchor, or TP slots. The framework integration reference describes typed constructors; only internal architecture sections describe facts, plans, patches, and journals. ## 1. Final Model The ETAF/Ebox representation pipeline is layered by responsibility: ```text AuthorView ↓ parse / desugar / string normalization NormalizedView = Text | Box | Fragment | ComponentCall ↓ ETAF Runtime resolves ComponentCall Resolved candidate + source facts ↓ exactly one style adapter is selected for the current surface ETAF Style Adapter | Ebox Standalone Style Adapter ↓ ECSS selector / cascade / inheritance (exactly once) Computed property facts + impact sets ├─ structure/geometry impact │ ↓ Fragment projection preserves RangeAnchors │ CanonicalEboxInput = Forest + RangeAnchors │ ↓ Ebox measure / layout │ LayoutPlan → GeometryPatch │ └─ paint impact ↓ shared property projector TP ContributionPlan → PaintPatch GeometryPatch and PaintPatch join the existing TP transaction ↓ Emacs adapter commit / rollback Published generation ``` These layers are not competing trees, nor do they repeatedly materialize the same tree. Each lowering step consumes the identity, computed properties, and child order already retained by the preceding layer; no fact is parsed or derived twice. LayoutPlan and ContributionPlan are independent derivations of the same candidate transaction. A paint-only path neither constructs CanonicalEboxInput nor runs layout. The two paths join at the existing transaction participant. Plans own neither author identity nor DSL nodes. Illegal canonical node states must be unrepresentable: ```text TextNode = { value: String, measurementProps, sourceHandle, eboxNodeId } BoxNode = { outer: inline | block, layout: Normal | RowConfig | ColumnConfig | FlexConfig | GridConfig, geometryProps, parentParticipationProps, children: [TextNode | BoxNode], sourceHandle, eboxNodeId } ``` TextNode has no children, outer, or layout. BoxNode has no content or value. A BoxNode stores its participation fields, but only its direct parent formatting context may validate and interpret them. `sourceHandle` is an opaque handle owned by the source layer: on the ETAF path it points to a Runtime Text/Box/Range source; on the standalone Ebox DSL path it points to an Ebox author source. `eboxNodeId` identifies only a retained Ebox geometry node. The Renderer/surface retains the mapping between them. Ebox reconciliation must not assume ownership of Component, Fragment, Range, or lifecycle identity. The primary concepts a user needs to understand are only `Text`, `Box`, and `Component`. `Fragment` is advanced structural syntax; `Host` is an internal Renderer term; and `Ebox Node` is a backend object. None constitutes a second component model. The complete NormalizedView shape is: ```text View = Text | Box | Fragment | ComponentCall ``` Author syntax and normalized View are separate layers. ETAF and Ebox share this visual author syntax: ```text AuthorNode = String | TextForm | BoxForm | RowSugar | ColumnSugar | FlexSugar | GridSugar ``` `String` normalizes to Text. The five Box forms normalize to Box with the corresponding typed Layout. Form names do not enter Runtime identity, diff, style, layout, or paint protocols. ETAF additionally provides Fragment, ComponentCall, `expr`, and `slot`; the Ebox DSL does not own those semantics. The two author syntaxes share structural vocabulary and normalized results, but need not share an evaluation environment: ETAF properties are Elisp expressions; the `.ebox` DSL uses data forms. Quoting and expression differences belong only to their parsers and do not create two canonical schemas. A Flex/Grid item is the role a material child Box acquires in its parent formatting context. It is neither another View nor a parent-child edge type. Participation properties are stored on the child Box; their direct parent Flex/Grid Box owns validation, computation, and dirty propagation. `expr` and `slot` are computation/projection mechanisms, not visual nodes. The target public View does not accept raw Ebox nodes. A missing rendering capability must first become a typed View/Ebox capability with identity and impact contracts; it must not bypass framework semantics through an opaque escape hatch. ## 2. Text, Box, and Fragment ### 2.1 Text `Text` is a text leaf responsible for: - exactly one payload that evaluates to a string; - text paint such as font, foreground/background, and underline; - text measurement, wrapping, and text-alignment input; - optional identity, semantic, and event properties. `Text` is always inline and does not expose `:outer`. It has no View children, cannot nest Text, and cannot establish any layout context. Multiple styled runs are adjacent Text nodes, not a Text subtree. Use an outer Box when block participation, padding, border, dimensions, or child layout is required. The Text grammars for the two authoring entry points differ precisely in evaluation capability: ```text ETAF TextForm = (text TEXT-PROP VALUE) VALUE = String | (expr :value Expr) Ebox TextForm = (text TEXT-PROP String) ``` All property key-value pairs must precede the one payload. Zero payloads, multiple payloads, nested Text, or a non-string payload are errors. A bare string is only sugar for an unstyled Text and has this one interpretation in every position. ### 2.2 The Two Orthogonal Box Axes `Box` has both an external participation mode and an internal layout mode: ```text :outer = inline | block layout = Normal | RowConfig | ColumnConfig | FlexConfig | GridConfig ``` - `:outer`: how this Box participates in its parent's `normal` layout; - `layout` variant: how this Box arranges its own children. The defaults are: ```text Box :outer block :layout Normal Text :fixed inline ``` The author layer does not expose a `:layout` property. Instead, exactly one layout is selected by the form name: ```elisp (box ...) ; Normal (row ...) ; RowConfig (column ...) ; ColumnConfig (flex ...) ; FlexConfig (grid ...) ; GridConfig ``` Inline flex is therefore written `(flex :outer 'inline ...)`, not represented as a new node type. `:outer` is a common property of every Box author form; each form's closed property set constructs its corresponding layout config. To switch layout dynamically, use `expr` to choose between View forms rather than treating `:layout` as an ordinary dynamic style. Canonical Box uses a typed Layout variant; it does not expose `:inner` or Ebox's backend representation `(:display (block flow))`. ### 2.3 Explicit Scope of normal `normal` is a real but deliberately bounded layout context: - consecutive inline `Text` or inline `Box` nodes enter one line flow and wrap to the available width; - a block `Box` begins on a new line and establishes an independent block; - inline lines before and after a block end at the block boundary; - child order remains stable. The target does not implement full browser CSS: it has no floats, tables, absolute/fixed positioning, run-in, list-item, or arbitrary anonymous-box rules. Ebox may map `normal` to an internal flow algorithm, but `flow` is not public ETAF vocabulary. When the parent Layout is Row, Column, Flex, or Grid, the parent algorithm directly owns child placement; a child's `:outer` does not change ordering. `:outer` determines inline or block participation only when a node enters a `normal` parent. ### 2.4 Other Layout Modes | Mode | Responsibility | | --- | --- | | `row` | simple horizontal sequential layout without Flex space distribution | | `column` | simple vertical sequential layout without Flex space distribution | | `flex` | Flex sizing, direction, wrapping, alignment, and gaps | | `grid` | two-dimensional tracks, placement, spans, and gaps | These are `Box` Layout variants, not Components, and they do not register a second set of Runtime node names for `row`, `column`, `flex`, or `grid`. Author forms have exactly one normalization mapping: ```text box → Box(layout = Normal) row → Box(layout = RowConfig) column → Box(layout = ColumnConfig) flex → Box(layout = FlexConfig) grid → Box(layout = GridConfig) ``` ETAF and Ebox share these five Box author forms. The term “layout form” denotes only an input spelling and its config schema; it does not imply a retained Host, node type, or runtime dispatch. The table above is the only normative lowering table. Ebox owns the canonical Layout variants and config schemas. The ETAF parser evaluates Elisp and selects the variant with the same name; it does not duplicate value rules. Cross-interface conformance tests must prove that the two entry points produce the same canonical shape, computed defaults, and errors for the same structure. ### 2.5 Ebox DSL Primitives and Sugar ETAF View and the Ebox DSL are separate interfaces, but they share one visual author syntax: Text is the text leaf, and Box is the structural/geometric container. The complete visual syntax of the Ebox DSL is: ```elisp "plain text" (text TEXT-PROPS "styled text") (box BOX-PROPS CHILD...) (row BOX-PROPS CHILD...) (column BOX-PROPS CHILD...) (flex BOX-PROPS CHILD...) (grid BOX-PROPS CHILD...) ``` A string always normalizes to Text. `text` accepts only textual content and Text properties; `box` accepts only children and Box properties. The Ebox DSL does not accept `:content`, so a string is never ambiguous between “Box content” and “child.” An empty `(box :width ... :height ...)` is a valid empty geometry container. `ebox-build` is the parse/desugar entry point for the author DSL. The public programmatic port provides two typed constructors: `ebox-text-create` constructs a TextNode, while `ebox-box-create` accepts a typed Layout variant and constructs a BoxNode. Constructors accept neither author forms nor a flat bag of properties spanning multiple layouts. The ETAF Renderer calls them directly; it does not reconstruct DSL. `:class`, `:id`, and author `:key` all belong to the source layer, but `:key` is an identity fact and never enters visual source. Standalone Ebox DSL and ETAF View produce isomorphic StyleSourceFact values; each surface selects exactly one adapter to invoke ECSS. ETAF Style Adapter owns Component-scope assembly and stylesheet lifetime on an ETAF surface, while Ebox Standalone Style Adapter owns them on a standalone surface. Both reuse the same ECSS implementation and Ebox property registry/projector, so one surface never runs cascade twice. The same parsed `:id` fact may also project to ETAF semantic metadata, but it is not reparsed or recascaded. Typed Text/Box constructors accept only an opaque `sourceHandle` plus already-computed owned facts. They neither accept nor retain `:class/:id/:key`, and Ebox measurement/layout core never reads source metadata. StyleEnvironment belongs to the current surface/runtime and must not be implemented as a process-global stylesheet or metadata table. The target public port does not retain untyped `(ebox-create :content ...)`. If the runtime fuses a Text payload into adjacent Box storage for performance, that optimization may occur only after canonical Text identity, range, and impact have been established, and it must reversibly preserve those facts. A private storage encoding must not become an author or public programmatic API. A Range descriptor is likewise an incremental backend protocol, not a DSL node. At the DSL boundary, each of the five Box author forms must immediately and statelessly construct its typed Layout variant. They must not establish distinct node types, identities, caches, validation paths, or rendering branches. Every author form rejects `:layout`; layout-specific properties are accepted only by the corresponding form. Other current DSL tags must be classified explicitly rather than presented beside the primitives: | Current tag | Classification | Target expression | | --- | --- | --- | | `ebox` | compatibility alias for `box` | remove; always write `box` | | `spacer` | empty-Box convenience sugar | remove; use a childless `box` | | `row` | Box layout form | retain and construct RowConfig | | `column` | Box layout form | retain and construct ColumnConfig | | `flex` | Box layout form | retain and construct FlexConfig | | `grid` | Box layout form | retain and construct GridConfig | | `item` | Flex wrapper/sugar | remove; put participation properties directly on the child Box | | `grid-item` | Grid wrapper/sugar | remove; put placement properties directly on the child Box | A direct child of Flex/Grid automatically acquires the item role; item is not a node type. The only recommended path for nondefault participation is an explicit child Box: ```elisp (flex (box :flex-grow 1 "Flexible") "Fixed") (grid (box :grid-column '(1 :span 2) "Header") (box "Body")) ``` Participation/placement properties are stored on the child Box, but only its direct parent Flex/Grid validates and consumes them; they must be rejected under the wrong parent. A property change sends the parent layout owner through the geometry path, but does not change the child Component/Text identity, lifecycle, or paint ownership. A direct Text uses default item parameters; wrap it in an explicit Box when nondefault parameters are needed. The target Ebox DSL removes `ebox`, `spacer`, `item`, and `grid-item`, retaining Text, Box, and the four layout sugars. Ebox still implements the layout algorithms separately, but the canonical visual nodes remain only TextNode and BoxNode. Author syntax, canonical tree, layout plan, and runtime storage are separate layers. ### 2.6 Fragment `Fragment` is a nonvisual structural Range: - it may carry zero, one, or many sibling Views; - it creates no Box, dimensions, background, or layout context; - Runtime may retain a stable Range identity for it and replace it locally; - it accepts only children and an optional stable `:key`, not visual or event properties. Fragment resolution does not discard Range identity. It splices material children into the CanonicalEboxInput forest in order while producing a `{range-id, before, after}` RangeAnchor. An empty Fragment still has an insertion anchor; a root Fragment may map to zero or multiple forest roots. ETAF Runtime owns Range identity. Ebox consumes only the descriptor to produce a local geometry patch. RangeAnchor is not a visual node and does not participate in measurement. A Component call itself has neither `:outer` nor Layout. Its root Text/Box determines how it participates in parent layout. A transparent Component that returns a Fragment may produce multiple siblings, so there is no single “Component outer box.” ### 2.7 Strings, Content, and Empty Boxes A string child of a Box normalizes to Text: ```elisp (box "this is text") ``` is equivalent to: ```elisp (box (text "this is text")) ``` Neither the ETAF nor Ebox author DSL provides `(box :content "...")`. `:content` belongs only to the existing untyped runtime storage; the target public programmatic port does not retain it either. Exposing `:content` through the author DSL or a canonical constructor would recreate two models—content and Text children. ETAF also provides no `spacer` type. A Box with no children is an empty Box. ## 3. Property Contract Properties form closed sets and are validated by owner. Unknown properties and inapplicable combinations are errors. | Owner | Property category | Representative properties | | --- | --- | --- | | ETAF Runtime metadata | identity/semantics/events/Behavior | `:key`, `:ref`, `:role`, `:disabled`, `:tab-index`, `:aria-*`, `:on-*`, `:use` | | ECSS author style source | selector/inline declarations | `:class`, `:id`, style declarations | | Ebox TextNode | canonical text measurement | font metrics, wrap policy, intrinsic constraints | | Ebox BoxNode | external/internal layout | `:outer`, typed Layout variant | | Ebox BoxNode | geometry | width/height/min/max, margin, padding, border widths, box sizing, overflow | | Flex container | layout | `:flex-direction`, `:flex-wrap`, `:justify-content`, `:align-items`, `:align-content`, `:gap` | | Flex child Box | parent participation | `:order`, `:flex-grow`, `:flex-shrink`, `:flex-basis`, `:align-self` | | Grid container | layout | track templates, auto flow, gaps, item/content alignment | | Grid child Box | parent participation | `:grid-row`, `:grid-column`, row/column spans, self alignment | | TP contribution | paint | color/background, underline/overline, border paint, visibility paint | Rules: - impact is a set, not a mutually exclusive enumeration; - `:key` belongs to identity, not visual properties; - `:class` enters only the ECSS selector; `:id` is one author input that may project to both the ECSS selector and semantic metadata, but two modules must not define its meaning independently; - contributions such as color/background that do not alter metrics are paint-only; - metric properties such as font family/size/weight are geometry + paint; - padding, border width, and similar properties are geometry + paint; - `:outer` and the Layout variant are structure + geometry; - Flex/Grid participation is stored on the child Box, but a change dirties only the corresponding parent layout owner for geometry; - ECSS cascade output must retain the impact set above; - ETAF/Ebox candidate normalization parses the author plist once and produces canonical declarations/metadata facts; ECSS computes the computed facts once; projection then passes them by owner/impact to Runtime, Ebox, and TP, and no owner reparses the original plist; - a multi-impact fact such as border or font may project to both geometry and paint fields, but its computed value materializes only once and paint-only state is not duplicated in the Ebox node; - TP consumes only already-parsed paint contributions and does not determine layout validity; - a structural property change must transactionally rebuild the corresponding layout context and cannot take the paint-only fast path. Validation has two deterministic phases: 1. Normalization performs form-local schema validation. `box` accepts only Normal/Common Box properties; only `flex` accepts Flex container config; only `grid` accepts Grid container config. Other layout-specific properties fail immediately. 2. After Component/Fragment resolution and ECSS cascade, Ebox performs parent-context validation on the candidate final tree. Flex participation (grow/shrink/basis/order/self alignment) is allowed only on a child Box whose direct parent is Flex. Grid placement/self alignment is allowed only on a child Box whose direct parent is Grid. A root or wrong parent is an error. The same Box may establish one Layout internally while participating in a different parent Layout externally—for example, `(flex :grid-column ... )` under Grid. These are two orthogonal fields, not a property conflict. When a dynamic transaction changes both parent Layout and child participation, only the final candidate is validated; any failure preserves the previous generation. Unlike browsers, which commonly treat an inapplicable CSS property as having no effect, this framework does not silently ignore invalid combinations. ### 3.1 Canonical Property Composition of Author Forms The following compositions are the normative public schemas. Shorthands expand immediately upon entering the canonical registry and do not create a second set of owner or impact rules. ```text SharedSourceMetadata = :key :class :id ETAFOnlyMetadata = :ref :role :disabled :tab-index :aria-* :on-* :use ETAFSourceMetadata = SharedSourceMetadata + ETAFOnlyMetadata EboxSourceMetadata = SharedSourceMetadata TextStyle = :font-family :font-size :font-weight :font-style :color :background-color :text-decoration-line :text-decoration-color :text-decoration-style BoxFrame = :outer :width/:min-width/:max-width :height/:min-height/:max-height :box-sizing margin/padding shorthands and logical/physical longhands border shorthands and width/style/color longhands :wrap-mode (word | char | kp | none) :overflow :visibility inherited standard text style source such as font/color non-inherited surface source such as :background-color NormalConfig = :text-align RowConfig = :item-gap :cross-align ColumnConfig = :item-gap :cross-align FlexConfig = :flex-direction :flex-wrap :flex-flow :justify-content :align-items :align-content :gap :row-gap :column-gap GridConfig = :grid-template-columns :grid-template-rows :grid-auto-columns :grid-auto-rows :grid-auto-flow :justify-items :align-items :justify-content :align-content :gap :row-gap :column-gap FlexParticipation = :order :flex :flex-grow :flex-shrink :flex-basis :align-self GridParticipation = :order :grid-column :grid-row :align-self :justify-self ``` The six visual forms are produced only through composition: ```text text = SurfaceSourceMetadata + TextStyle + one String box = SurfaceSourceMetadata + BoxFrame + NormalConfig + ParentParticipation + children row = SurfaceSourceMetadata + BoxFrame + RowConfig + ParentParticipation + children column = SurfaceSourceMetadata + BoxFrame + ColumnConfig + ParentParticipation + children flex = SurfaceSourceMetadata + BoxFrame + FlexConfig + ParentParticipation + children grid = SurfaceSourceMetadata + BoxFrame + GridConfig + ParentParticipation + children ``` `SurfaceSourceMetadata` resolves to ETAFSourceMetadata on an ETAF surface and to EboxSourceMetadata on a standalone Ebox surface. `:item-gap` and `:cross-align` are Ebox Row/Column extensions, not CSS `gap`/`align-items`: the former inserts fixed spacing along the main axis; the latter accepts `start|center|end|stretch` and controls the cross axis. Flex/Grid `:gap` retains standard CSS shorthand semantics and expands to both row-gap and column-gap. The final direct parent selects `ParentParticipation` as Default, FlexParticipation, or GridParticipation. A candidate cannot carry mutually exclusive Flex-only and Grid-only fields simultaneously. Text accepts neither BoxFrame, LayoutConfig, nor Participation; wrap it in an explicit Box when those capabilities are required. The Ebox DSL does not accept ETAFOnlyMetadata. ### 3.2 Naming Layers and Backend Projection Names in the author layer belong to four namespaces: CSS, ETAF, Ebox, and the optional Emacs adapter. A standard CSS name is adopted only when its applicable objects, value grammar, defaults/inheritance, impact, and observable behavior match CSS or form an explicit subset. A capability that is conceptually similar but semantically different retains a precise ETAF/Ebox name; familiarity does not justify an incorrect standard name. The target public API classifies historical and backend names as follows: ```text :bgcolor → exact alias of :background-color :font-height → removed from core; optional Emacs adapter source only :font-slant → exact alias of :font-style with identical value grammar :border-top-p → retained Ebox boolean shorthand for top width/style :grid-column-span → Ebox positive-integer shorthand for :grid-column (span N) :grid-row-span → Ebox positive-integer shorthand for :grid-row (span N) :face → not a core canonical property :display → private Ebox/Emacs lowering field :content → private legacy runtime storage field ``` `:wrap-mode` is not equivalent to CSS `white-space`, `overflow-wrap`, `word-break`, or `line-break`. It therefore remains the sole public name in the Ebox namespace, with its value restricted to `word`, `char`, `kp`, or `none`. `char` breaks only at complete grapheme-cluster boundaries, while `kp` selects Knuth–Plass paragraph layout. If complete, semantically equivalent CSS properties are implemented in the future, one explicit migration must replace it; the two naming systems must not be retained indefinitely. Only Box author forms accept `:wrap-mode`; it specifies the soft-wrapping policy for that Box's content. Text forms do not expose a second author path. During computation, the Box policy is inherited as Text measurement input: Text executes line breaking but does not own the declaration. `none` disables only automatic soft breaks and preserves explicit newlines. The independent `:overflow` property decides what happens after layout when unbroken content exceeds the Box; wrapping never implies clipping or scrolling. Standard CSS shorthands have exactly one expansion rule, including `:margin`, `:padding`, `:border`, `:gap`, `:flex`, `:flex-flow`, `:grid-column`, and `:grid-row`. The canonical registry uses namespaced IDs such as `ebox/font-size` and `ebox/background-color`; authors write only keywords and never see internal IDs. Every definition records its naming domain and relationship to standards explicitly: ```text PropertyDefinition { authorName canonicalId aliases namespace: css | etaf | ebox | emacs-adapter standardReference semanticSubset acceptedContexts valueGrammar initial inherits impactSet owner projections } ``` An alias must have exactly the same contexts, value grammar, owner, impact, and projections as its canonical property, and it cannot transform the value. A shorthand performs one-to-many expansion; an adapter source resolves a composite backend value. An alias resolves to canonicalId immediately at the parse entry point, so computed style, caches, diff, Ebox, TP, and Rust never see it. PropertyDefinition registration rejects canonical/alias collisions. Writing both the canonical name and an alias—or repeating an alias—in the same declaration is an error rather than an implicit last-wins rule. The source spelling may be retained only in diagnostic provenance. Property references list aliases under the canonical property, for example: ```text background-color Canonical: :background-color Aliases: :bgcolor ``` They do not list `bgcolor` as a second capability. In the first phase, aliases are registered by the owning package's schema; process-global user aliases are not exposed. An upper-level package that needs an alias must scope it to its own schema and must not pollute the global Ebox visual-property domain. `:border-top-p` is not an alias but a retained Ebox boolean shorthand: `t` expands to `:border-top-width 1` + `:border-top-style solid`, while `nil` expands to width 0 + style none. Color comes independently from `:border-top-color`, `:border-color`, or the default foreground. Use standard `:border-top` or its longhands when full control is required. Mixing `:border-top-p` with its width/style outputs in the same declaration is an error; different cascade sources still override one another normally through ECSS. Canonical border widths are always nonnegative integer pixels, and `style=none` has a used width of zero. Every successful adapter projection must be exact; it may not collapse width to a boolean or character column. The current Emacs text adapter can exactly express arbitrary left/right widths and 0/1px top/bottom lines. Thicker horizontal borders raise a capability error before publication and preserve the old generation instead of degrading silently. Core retains all four width/style/color facts so a future pixel-coordinate adapter can widen the success domain. `:grid-column-span` and `:grid-row-span` are likewise not aliases. They accept only a positive integer and respectively expand to the corresponding Grid shorthand's `span N` value; mixing either with `:grid-column` or `:grid-row` in the same declaration is an error. `:font-slant` is an exact alias only when its value grammar is identical to `:font-style`. The Emacs face-height semantics of `:font-height` must not masquerade as CSS `font-size`. The Emacs text property names `face`, `display`, `keymap`, `mouse-face`, `help-echo`, `invisible`, `line-prefix`, `wrap-prefix`, and sticky properties belong only to the final adapter. Ebox core, ETAF Runtime, ECSS, and Rust neither produce nor consume these names directly. Reuse of a named Emacs face, when needed, is available only through an optional adapter's explicit `:emacs-face` source input. That input immediately resolves to standard font/paint facts and computes their impact; the raw face symbol does not enter the canonical IR. A typical projection is: ```text :font-weight bold → ebox/font-weight, impact {geometry, paint} → Ebox Text measurement weight + TP face-weight contribution → Emacs adapter emits face :weight :width 120 → ebox/width, impact {geometry} → Ebox GeometryPatch → Emacs adapter may emit display space width ``` ### 3.3 Unified Property Facts and Projection Layer The unified layer is not a direct `author keyword → Emacs text property` dictionary. One property may affect both measurement and paint; several properties may merge into one Emacs `face`; and a `display` produced by layout may have no direct author property. The internal stages must therefore distinguish: ```text CanonicalDeclaration { propertyId specifiedValue sourceSpelling sourceProvenance } SelectorSubjectFact { classList id sourceHandle } StyleSourceFact { sourceHandle selectorSubjectFact declarations scopeHandle provenance } StyleEnvironment { stylesheet schemaSet scopeIndex computedCache } RuntimeMetadataFact { propertyId value sourceHandle } ComputedPropertyFact { propertyId computedValue winningProvenance impactSet sourceHandle } ProjectionPlan { metadataFacts measurementFacts geometryFacts paintFacts } ``` Normalization parses author input once and simultaneously produces immutable CanonicalDeclaration, SelectorSubjectFact, and RuntimeMetadataFact artifacts. `:class/:id` do not enter CSS declarations; SelectorSubjectFact constructs the ECSS subject directly before cascade. Selector and semantic projection share the same parsed source value for `:id` rather than rereading the plist independently. ETAF Style Adapter and Ebox Standalone Style Adapter produce isomorphic StyleSourceFact values, but exactly one adapter assembles StyleEnvironment for a surface. ECSS cascade/inheritance then receives SelectorSubjectFact + declarations and produces immutable ComputedPropertyFact artifacts. `:key`, `:ref`, `:on-*`, and similar properties do not enter ECSS and appear only in RuntimeMetadataFact. “Materialize once” means that each stage produces its own immutable artifact once, not that one object mutates across stages. A pure property projector consumes computed-style facts and metadata facts and generates ProjectionPlan according to the PropertyDefinition owner/impact/projections fields. Every consumer references the same fact rather than reparsing or copying its computed value. The TP paint projector is the only module that converts paintFacts into ContributionPlan. The ETAF semantic projector converts metadataFacts into Runtime/SemanticPlan. A registry is not one process-global universal table. Each owning package supplies an immutable SchemaRegistry conforming to the same schema protocol; a surface composes a SurfaceSchemaSet: ```text ETAF SurfaceSchemaSet = ETAF registry + Ebox registry Ebox SurfaceSchemaSet = Ebox registry ETAF + Emacs adapter = ETAF registry + Ebox registry + adapter registry ``` Each canonicalId has exactly one owning definition. Canonical/alias collisions are checked when composing the SchemaSet. This avoids both reverse dependencies and duplicate sources of truth. Logical modules remain small and complete: - package property schema: a package-scoped PropertyDefinition registry; - SurfaceSchemaSet: conflict-free composition of package registries; - property normalizer: author names, shorthands, and value grammar; - property projector: computed/metadata facts → backend-neutral ProjectionPlan; - Ebox layout projector: measurement/geometry facts → LayoutPlan; - TP paint projector: paint facts → ContributionPlan; - ETAF semantic projector: metadata facts → Runtime/SemanticPlan; - Emacs adapter: GeometryPatch + PaintPatch + SemanticPlan → text-property operations. Consequently, an Ebox canonical node stores no paint-only field; TP stores no geometry; the Emacs adapter does not reinterpret CSS; and Rust receives only canonical facts/plans, not `face`, `display`, or an Elisp plist. Debugging and performance tools must expose the complete chain, for example: ```text :font-weight → ebox/font-weight → {geometry, paint} → measurement/font-weight + paint/font-weight → face :weight ``` ## 4. Module Owners ### 4.1 ETAF Core `etaf-view`: - defines and normalizes Text, Box, Fragment, and ComponentCall; - normalizes strings to Text; - normalizes the `row`, `column`, `flex`, and `grid` author sugars to Box; - validates closed property sets, slots, `:key`, and expression boundaries; - does not measure, lay out, or write buffers. `etaf-component`: - defines Component props, mutually exclusive `:view`/`:render` frontends, optional `:setup` returning opaque state, the sole `etaf-state` accessor, and `:styles`; - defines the `etaf-node` code frontend at the same typed View ABI boundary; - does not schedule Runtime or call Ebox. `etaf-runtime`: - owns Component/Fragment/Range identity, reactive dependencies, Context, Theme, Action, Behavior, Data, Resource, and lifecycle; - owns candidate generation, transactions, commit authority, rollback, and disposal; - decides which Component, Range, structural property, or paint contribution a change affects; - does not compute pixels or layout. `etaf-renderer`: - is the only ETAF → Ebox lowering adapter; - consumes computed/projection facts already produced by ETAF Style Adapter and turns the structure/geometry projection into CanonicalEboxInput forest, RangeAnchors, and typed Ebox facts; - does not rerun selector/cascade or copy a second computed visual representation; - does not execute Component lifecycle or access Ebox private state. `etaf-style` (a logical module that may remain in the same distribution): - owns Component-style scope assembly and one independent StyleEnvironment per Runtime/Surface, including its lifetime; - uses Ebox's public property registry/projector and invokes ECSS directly for the one cascade on an ETAF surface; - does not measure, lay out, write buffers, or own Runtime commit authority. `etaf-theme-tp`: - is only the optional TP-palette to ETAF semantic Theme token/value adapter; - does not produce ContributionPlan, participate in selector/cascade, or own paint commit authority. Theme semantic tokens and inheritance belong to ETAF Context. TP does not own business meaning such as “dark theme.” ### 4.2 Ebox Ebox owns: - normalization of String/Text/Box and layout-sugar expansion in the Ebox DSL; - the canonical Ebox property registry and pure computed-fact to geometry/paint-fact projector; - a Standalone Style Adapter used only by standalone Ebox surfaces; it invokes ECSS directly, while the ETAF typed path bypasses it and never runs a second cascade; - contextual validation, parent-layout consumption, and dirty propagation of child Box participation; - typed TextNode/BoxNode constructors and canonical property schemas; - text measurement, wrapping, and line layout; - the `normal`, `row`, `column`, `flex`, and `grid` geometry algorithms; - width/height, the box model, overflow, scrolling, and viewport behavior; - stable Ebox node identity, geometry snapshots, and structural patch plans. Ebox does not understand Component, slot, Context, Action, Behavior, Data, or Resource, and does not determine paint-contribution priority. ETAF Style Adapter and Ebox Standalone Style Adapter share the same pure property projector. The former handles ETAF Theme/Component/state/inline provenance; the latter handles standalone Ebox inline/stylesheet provenance. They never coexist on one surface, never put paint-only properties back into CanonicalEboxInput, and never own TP priority, journal, or commit authority. `ebox-build` exclusively owns parsing/desugaring author forms. `ebox-text-create` and `ebox-box-create` accept already evaluated canonical parameters and validate only typed node invariants. All three ultimately consume the same canonical property schema and enter the same layout implementation. The ETAF Renderer calls the typed programmatic port directly; it must not reconstruct DSL and trigger a second parse. Existing untyped `ebox-create :content` is not part of the target public port. Logical boundaries: ```text ebox-core pure measurement, layout, snapshots, and structural patches ebox-emacs font/window capabilities, buffer positions, and structural commit ``` These boundaries need not immediately become two distribution packages, but pure layout and Emacs side effects must be independently testable. Measuring the CanonicalEboxInput forest produces a LayoutPlan. The plan contains only measurement results, coordinates, dimensions, layout owners, and geometry deltas needed by the candidate. It introduces no author-visible node type and owns no Component/Text/Box identity. After commit or rollback, it may be retained as input to the next incremental update or released. ### 4.3 ECSS ECSS owns selectors, cascade, inheritance, and computed properties. Its output must carry each property's structure/geometry/paint impact. ECSS neither performs layout nor writes buffers. ### 4.4 TP and the Commit Boundary TP owns: - the priority of paint contributions from Theme, Component style, state, inline style, and other sources; - paint-operation merging; - the Emacs text-property journal, apply, and rollback. The authority order for one update is fixed: ```text ETAF Runtime creates the candidate and owns commit authority ↓ Ebox candidate stage produces the structure/geometry patch ↓ Ebox surface adds a rollback-capable participant to the existing TP transaction ↓ TP precommits paint; Ebox commit publishes the Emacs surface ↓ Only after all succeed does ETAF Runtime promote the generation Any failure rolls back through the existing Ebox/TP/Runtime journals ``` Ebox does not own TP paint priority; TP does not own node layout; neither may promote a Runtime generation independently. The target introduces no second cross-package coordinator. The existing transaction participant is the sole mechanism aligning the Ebox surface with TP/Emacs commit. ### 4.5 Upper-Level Packages | Package | Owns | Does not own | | --- | --- | --- | | `etaf-ui` | ordinary Components such as Button, Checkbox, Label, Panel, and DataGrid | a second Widget Runtime or layout engine | | `etaf-sqlite` | SQLite Data Source, queries, mutations, transactions, and disposal | Data Controller, View, or UI | | `etaf-performance` | application-neutral operations/stages, environment, statistics, and reports | example semantics, layout rules, or scheduling authority | | `ebox-playground` | examples and verification of the public Ebox layout API | ETAF | | `etaf-playground` | ETAF/UI/SQLite composition examples, loading commands, and status display | Core syntax, Runtime, or performance protocols | `etaf-performance` is an independent optional package. ETAF, Ebox, TP, and SQLite do not depend on it; it observes and correlates stages only through public boundaries. The Playground `.etaf` manifest belongs to the Playground. If a general compiler exists in the future, it must lower to the same View/Component contract and must not create a second Runtime. ### 4.6 Public Surfaces Layered by Consumer - Ordinary ETAF users use only `etaf-view`, Component, Text/Box forms, ETAF metadata/ events, canonical CSS-aligned properties, explicitly listed ETAF/Ebox extensions such as `:outer` and `:wrap-mode`, and parse-time aliases; they do not call Ebox, TP, or the Emacs adapter. - Standalone Ebox users use inert data forms with the same visual structural vocabulary through `ebox-build`; they do not own Component, slot, expr, or lifecycle. - Framework integrators use `ebox-text-create`, `ebox-box-create`, typed LayoutConfig, RangeAnchor, and the TP contribution contract; they do not reconstruct DSL, pass shorthands, or run a second cascade. Typed constructors accept only an opaque `sourceHandle`, not source-layer `:class/:id/:key`. - The optional Emacs adapter is an explicit opt-in, independent schema namespace. Only a surface that loads the adapter accepts `:emacs-face`; otherwise normalization reports the unknown namespace/property precisely. - `ebox--*`, `etaf--*`, `tp--*`, `:ebox-type`, `:node-id`, `:region-id`, Emacs text properties, and runtime storage fields are all private. The user guide describes only the first layer; the Ebox DSL guide describes the second; the integration reference describes the third; only architecture documentation describes canonical IR, identity owners, impact projection, and the commit protocol. ## 5. Dependency Direction ```text etaf-ui ─────────────▶ ETAF Core ─────────────▶ Ebox public port etaf-sqlite ─────────▶ ETAF Data contract etaf-playground ─────▶ ETAF + optional UI/SQLite ebox-playground ─────▶ Ebox only etaf-performance ────▶ public observation boundaries only ETAF Style Adapter ──▶ ECSS + Ebox property registry/projector Ebox Standalone Style Adapter ─▶ ECSS + same registry/projector ETAF Renderer ───────▶ Ebox typed core port ETAF Runtime ───────▶ Ebox/TP transaction participants etaf-theme-tp ───────▶ ETAF semantic Theme values only Ebox surface ────────▶ TP contribution + transaction participant ``` Reverse dependencies are forbidden: Ebox does not depend on ETAF; TP does not parse View; ECSS does not write buffers; UI does not call Ebox private functions; SQLite does not know UI; and Playground does not inject protocols into Core. ## 6. Rust and Elisp Module boundaries precede implementation language. Deterministic computation moves to Rust only after interfaces and equivalence tests are frozen: ```text Rust candidates: normalized View validation and structural diff (over opaque stable IDs only) ECSS cascade Text measurement input processing and Ebox layout pure-data computation of geometry/paint patches Elisp / Emacs: execute user Components, refs, Context, Action, Data, Resource, and lifecycle database and external I/O Emacs events, font/window capabilities, and final commit ``` Component identity, dependency ownership, TP priority, and generation authority do not move merely because implementation moves to Rust. Rust may at most compute side-effect- free candidate paint operations; TP continues to own contribution slots, priority, journaling, and commit/rollback. Elisp does not repeat diff, cascade, layout, or text scans already completed by Rust. ## 7. Correctness and Performance Invariants - View, computed properties, geometry snapshots, and paint contributions each materialize once per transaction; - a Text paint-only contribution change neither executes unrelated Components nor runs layout; - changes to `:outer`, the Layout variant, or geometry run only the affected layout owner; - Fragment/slot/list changes replace only the corresponding Range; - failure of any Ebox/TP/Emacs participant preserves the previous committed generation; - resize reflows immediately from current window facts and does not change interaction semantics through hidden debouncing; - the performance recorder does not change the measured path. The final gates must cover: - structural equivalence of Text/Box/Fragment; - rejection of canonical/alias collisions when package registries compose a SurfaceSchemaSet; - exact aliases disappear after normalization, while each shorthand expands exactly once and conflicts with its owned outputs in the same declaration; - the optional adapter namespace is accepted only by explicitly opted-in surfaces and reports a precise error when the adapter is not loaded; - CanonicalDeclaration, SelectorSubjectFact, RuntimeMetadataFact, and ComputedPropertyFact remain immutable across stages, and the selector subject is produced exactly once before cascade; - ProjectionPlan contains only paintFacts, and only the TP projector may produce ContributionPlan; - Row/Column accept only the `:item-gap/:cross-align` extensions rather than borrowing the different semantics of CSS `:gap/:align-items`; - a multi-impact computed value such as geometry + paint materializes once and is referenced by both paths; - strings normalize only to Text, and both author DSLs reject `box :content`; - Text is always inline and has exactly one string payload; nested, empty, or multiple payloads are errors; - canonical shape, defaults, and errors of the five ETAF/Ebox Box forms agree across interfaces; - the five Box author forms each produce their one corresponding Layout, and every author `:layout` is an error; - Flex/Grid participation is permitted only on a child Box under the matching parent; the wrong context reports a precise error; - a participation change runs only the parent layout and does not rebuild child identity or lifecycle; - typed Text/Box constructors reject mutually exclusive fields and layout sugar, and share their result with `ebox-build`; - CanonicalEboxInput contains no paint-only fields; the ETAF and standalone Ebox paint adapters each project exactly once; - sourceHandle and eboxNodeId have independent lifetimes, and reconciliation does not change source identity; - legal and failing `outer × layout` combinations; - GUI behavior of normal inline/block, row, column, flex, and grid; - layout participation of Component roots and transparent Fragments; - empty, single-root, and multi-root Fragments all retain RangeAnchor and support local replacement; - a paint-only candidate does not construct LayoutPlan, while geometry and paint patches join in the existing transaction; - style/Theme/TP priority and transactional rollback; - continuous resize of Research Shelf and Flex reference; - both p95 and max at or below 50 ms in fixed real scenarios. ## 8. Current Implementation Gaps and Non-Goals The current code still registers `text`, `fragment`, `container`, `row`, `column`, `stack`, `flex`, `grid`, and `spacer`, and provides `raw-ebox`. Target `box`, `:outer`, and typed Layout are not yet implemented; the target public View also does not retain `raw-ebox`. The current Ebox DSL still encodes `box :content` and bare strings directly as untyped `ebox-create :content`, and constructs `item` and `grid-item` as runtime wrappers. The target adds an explicit TextNode/BoxNode canonical IR and typed constructors; retains Text, Box, and the five Box author forms; and removes `:content` from author/public constructor syntax as well as removing `ebox`, `spacer`, `item`, and `grid-item`. ### 8.1 Atomic migration order and gates This migration does not keep a tag-by-tag compatibility route. The current verified baselines are Ebox `6d9f2a4` and Ebox Playground `f571c89`; uncommitted experiments are never functional or performance baselines. Work proceeds in the following dependency order, and the author-boundary cutover is committed as one cross-repo atomic objective: 1. Complete the typed core first: Normal supports zero or many inline/block children; Row/Column fully implement `:item-gap/:cross-align`; Normal/Row/Column/Flex/Grid are all one BoxNode with a typed LayoutConfig. Text may be a direct Flex/Grid child with default participation, but it cannot carry nondefault participation. 2. Switch `ebox-build` once to the sole grammar: String, `text`, `box`, `row`, `column`, `flex`, and `grid`. The five Box forms directly construct typed Box/LayoutConfig values; remove `ebox/spacer/item/grid-item`, and reject author `:content/:layout` plus raw runtime nodes. 3. In the same objective, remove the complete legacy public creation surface: `ebox-create`, `ebox-concat/ebox-stack/ebox-spacer/ebox-grid-fr`, the public and autoload identity of the old `ebox-row/ebox-column/ebox-flex/ebox-grid` constructors, and their public inventories, help, README, documentation, and examples. Lowering still required by a backend may remain private temporarily, but it must not be canonical output, a public concept, or a second author path. 4. Migrate every actual consumer together: Ebox, ETAF, ETAF UI, Ebox Playground, ETAF Playground, and their README files, documentation, examples, and tests. Public material and examples must not expose private backend fields such as `:ebox-content-node`, `:display`, or `:ebox-type`. Verification uses a minimal decisive matrix rather than duplicating legacy tests: one table-driven grammar/negative contract covers seven author entries, five Layouts, Normal multi-child behavior, Text default participation, and wrong-parent failures; existing identity, final-candidate, and commit/rollback gates are reused; tests that only prove removed wrappers or aliases are deleted. Each candidate first runs targeted checks and then every affected repository's full static and test gates. Continuous GUI resize checks every step for no unexpected full-root fallback, requires final text and all text properties to equal a fresh render, and retains stable identity. Performance comparison interleaves the committed baseline and candidate under the same Emacs, frame, width sequence, and action sequence: warm up each operation five times, then measure each side at least thirty times; use the general recorder to compare operation latency, cross-package stages, p95, and max. Affected real scenarios must keep p95 and max at or below 50ms, and any reproducible stage regression must be root-caused first. Any functional, GUI, or performance failure stops the commit; it must not be hidden by compatibility branches or a large set of synonymous tests. This is a clean redesign. It does not require old Host names or old `.etaf` files to continue working, and it adds no long-lived compatibility layer. Until implementation is complete, the formal architecture and user guide must not describe target syntax as the current API. Non-goals: - implementing full browser CSS; - providing `spacer`, public `flow`, or `(box :content ...)` in the author DSL; - making Flex/Grid item an author node, visual wrapper, or independent identity; - allowing applications to inject raw Ebox Nodes into View; - making layout modes Components or a second set of Runtime nodes; - retaining old Host/layout-form aliases in Core; property aliases follow only the unified mechanism in Section 3.2; - allowing Playground, UI, or database packages to own Core protocols; - adding App precompilation artifacts before real compile cost and runtime benefit exist.