Conversation
commit: |
taras
force-pushed
the
docs/add-clayterm-spec
branch
from
4158ad1 to
e31bd93
Compare
cowboyd
left a comment
cowboyd
left a comment
There was a problem hiding this comment.
This is good. Left the feedback, I think we need to use "directive" instead of "descriptor" because they are command-like open() / close()
| **Descriptor (op).** A plain object that declares one element of the UI tree for a single frame. Descriptors are typed by an identifier field and carry layout, styling, and content properties. The set of descriptors for a frame is ordered and forms an implicit tree via open/close pairing. | ||
|
|
||
| **Descriptor array.** An ordered array of descriptors constituting a complete frame description. The array is the input to the rendering transaction. |
There was a problem hiding this comment.
not sure these are really things. we don't mention descriptors, the core primitive is the Op. There are three: open(), close(), and text()
|
|
||
| **Term.** An instance of the Clayterm renderer, bound to specific terminal dimensions. A Term is the object through which the caller performs render transactions. | ||
|
|
There was a problem hiding this comment.
Thinking of changing this to Screen, Region
|
|
||
| ### 4.4 Double-buffered diffing | ||
|
|
||
| The renderer maintains two cell buffers: a front buffer (the previously rendered frame) and a back buffer (the frame being rendered). After populating the back buffer from the current frame's render commands, the renderer compares it against the front buffer and emits ANSI bytes only for cells that differ. The buffers are then swapped. This mechanism is internal to the renderer and not directly observable to the caller. |
There was a problem hiding this comment.
The buffers are then swapped.
implementation detail (as the spec mentions), but this is not true. cells where a diff is detected is copied from back to front so that at the end, they are the same.
| open(name: string, props?): OpenElement | ||
| ``` | ||
|
|
||
| Creates an element-open descriptor. The `name` parameter provides a tag name for the element. The optional `props` parameter carries configuration for layout, styling, and behavior. |
There was a problem hiding this comment.
we should probably rename name to id so that it is clear that this should be unique, or call the parameter "unique name" or some such
| ### 11.4 The renderer does not own input parsing | ||
|
|
||
| Input parsing (keyboard events, mouse events, escape sequence decoding) is an independent concern. It is not part of the rendering contract defined by this specification. The renderer MUST NOT depend on input-parsing state, types, or API. | ||
|
|
||
| Clayterm currently provides input-parsing functionality alongside the renderer in the same package. This co-location is an implementation detail, not an architectural coupling. Section 12.4 describes the current input surface. | ||
|
|
There was a problem hiding this comment.
worth noting that this is handled by the clay term input interface.
Also, hit detection (pointerenter, pointerleave) requires the render loop to participate. You can pass the current x,y position of the pointer and it will tell you the ids of every element that it is over. This is how the PointerEvents[] array is populated in the render output.
|
|
||
| The `output` field is the ANSI byte output specified normatively in Section 7.3 and Section 8.2. | ||
|
|
||
| The `events` field contains pointer events (enter, leave, click) derived from the underlying layout engine's element hit-testing. This field was added during a pointer-events feature implementation. The pointer event model is functional but has acknowledged gaps (no modifier keys on click events) and its interaction protocol (calling `setPointer(x, y, down)` before rendering, then reading events from the return value) was arrived at through iteration rather than upfront design. |
There was a problem hiding this comment.
This is how Clay says that you're supposed to do things.
| **WASM loading.** The current implementation loads the WASM binary relative to the module's location, compiles it once, and instantiates it per Term or Input with fresh memory. The loading mechanism has changed and may change again. | ||
|
|
||
| **WASM co-location.** The WASM binary file is expected to be co-located with the JavaScript module files. Both JSR and npm package builds include the artifact. |
|
|
||
| **Memory layout.** WASM linear memory is initialized with 256 pages (16MB). The renderer state struct and the transfer buffer are allocated in WASM linear memory. The specific layout is an implementation detail. | ||
|
|
||
| **Output buffer lifetime.** The ANSI byte output resides in WASM linear memory. The `Uint8Array` returned by `render()` is a view over this memory. The output is valid until the next `render()` call on the same Term instance, at which point the buffer may be reused. Callers who need to retain the output beyond the next render SHOULD copy it. |
There was a problem hiding this comment.
I can't imagine this ever changing, so it can be added to the normative section.
|
|
||
| 3. **Is the input API part of the Clayterm specification?** This specification describes it in Section 12.4 but does not specify it normatively. The input API may become a separate package or specification. | ||
|
|
||
| 4. **Are `pack()` and `validate()` public API?** Both are currently exported. Neither is specified normatively here. |
Adds the v0.1 draft specification covering the architectural model, core invariants, public rendering API, descriptor model, and boundary responsibilities. Non-normative sections document settling surfaces (transfer encoding, input parsing, pointer events) separately from the stable rendering core.
taras
force-pushed
the
docs/add-clayterm-spec
branch
from
e31bd93 to
30b0eef
Compare
2 participants
Summary
specs/clayterm-spec.md) documenting Clayterm's rendering contract, architectural model, core invariants, and public API surfaceTest plan