kui_core/schema/
doors.rs

1//! The verb table: one row per call an app or host makes (register a
2//! resource, move focus, open a menu, size a window) with its spelling in
3//! Rust, C, Odin, Node and Lua, or the reason a binding has none.
4//!
5//! A Rust caller uses the methods on `Ui`, `Core` and friends directly;
6//! this table exists so the bindings stay in step with them and with each
7//! other. Each binding's test checks its names against [`DOORS`], so a
8//! verb added to one binding is a row here with its other cells, or a red
9//! test. A [`Cell::No`] says once why a binding lacks a verb instead of
10//! every reader re-deriving it: Lua is a guest with a view-time env,
11//! Node's `Ctx` is a driver and its `KuiWindow` refuses input, C is both,
12//! and Odin's doors are C's. The Odin column is checked by the Odin
13//! binding's generator (packages/odin/gen), which reads this table through
14//! `examples/rust/tools/schema-dump.rs`.
15//!
16//! ```rust
17//! use kui_core::schema::{Cell, DOORS};
18//!
19//! let open_menu = DOORS.iter().find(|d| d.rust == "Ui::open_menu").expect("a verb");
20//! assert!(matches!(open_menu.c, Cell::Is(_)));
21//! ```
22
23/// One binding's cell.
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25pub enum Cell {
26    /// The binding has the verb under this name: a `kui_*` function in C;
27    /// a procedure of package `kui` in Odin; a method in Node, on both
28    /// classes unless prefixed `Ctx.` or `KuiWindow.`; a function on `env`
29    /// in Lua. Checked by the binding's test.
30    Is(&'static str),
31    /// The binding has the same thing in another form — a prop, a
32    /// reading of `env`, a callback, a constructor option — and the text
33    /// says which.
34    As(&'static str),
35    /// The binding does not have it, and this is why.
36    No(&'static str),
37}
38
39/// One verb.
40pub struct Door {
41    /// The Rust spelling: `Ui::x` (view-time), `Core::x` (a host between
42    /// frames), `SharedResources::x` (the session's registry, reached as
43    /// `core.resources`), `Tokens::x` (a table), `Launcher::x` (the runner).
44    pub rust: &'static str,
45    pub c: Cell,
46    /// A procedure in the Odin binding's package `kui` (packages/odin),
47    /// checked by its generator. Odin's doors are kui.h's, so its column
48    /// follows C's: the same function under its name without `kui_`, the
49    /// Odin spelling of what C has another way, and `No` where C has none.
50    pub odin: Cell,
51    pub node: Cell,
52    pub lua: Cell,
53    pub doc: &'static str,
54}
55
56use Cell::{As, Is, No};
57
58/// The reason most of Lua's column is `No`: a script's env is a *reading*
59/// the host hands it for one `view`, not a handle on the host.
60/// It declares a tree and answers events; what it registers, drives,
61/// times or reads back is the host's.
62pub const GUEST: &str = "a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's";
63
64/// The reason for Lua's `No` on the resource rows.
65const NO_HANDLE: &str = "a script owns no handle: the host registers and the script names the id it was given (`image { id = }`, `font = id`, `audio { src = id }`)";
66
67/// The reason for Odin's `No`: every Odin door is a kui.h function, so
68/// what C has no door for, Odin has none for either - for C's reason, in
69/// C's cell.
70const ODIN_IS_C: &str =
71    "Odin's doors are kui.h's (packages/odin): C has none, for the reason in C's cell";
72
73/// The reason for Node's `No` on the renderer rows (not done
74/// here).
75const NEVER_PAINTS: &str = "a Node host never paints: the renderer behind `KuiWindow` is the runner's, and a headless `Ctx` has none";
76
77pub const DOORS: &[Door] = &[
78    // -- Resources ---------------------------------------------------------
79    Door {
80        rust: "SharedResources::add_image",
81        c: Is("kui_image_add"),
82        odin: Is("image_add"),
83        node: Is("addImage"),
84        lua: No(NO_HANDLE),
85        doc: "Registers RGBA pixels and mints an id for `<image src>`.",
86    },
87    Door {
88        rust: "Core::update_image",
89        c: Is("kui_image_update"),
90        odin: Is("image_update"),
91        node: Is("updateImage"),
92        lua: No(NO_HANDLE),
93        doc: "Replaces the pixels behind a live id, keeping the id (ADR 0025).",
94    },
95    Door {
96        rust: "Core::remove_image",
97        c: Is("kui_image_remove"),
98        odin: Is("image_remove"),
99        node: Is("removeImage"),
100        lua: No(NO_HANDLE),
101        doc: "Drops an image; every window's atlas lets it go (backlog AR8).",
102    },
103    Door {
104        rust: "Core::image_pixels",
105        c: Is("kui_image_pixels"),
106        odin: Is("image_pixels"),
107        node: No(NEVER_PAINTS),
108        lua: No(NO_HANDLE),
109        doc: "The pixels behind a handle, for a renderer meeting a texture quad.",
110    },
111    Door {
112        rust: "Core::parse_path",
113        c: Is("kui_path_parse"),
114        odin: Is("path_parse"),
115        node: As("`d` on `<path>` is the string; the addon hands it to this parser"),
116        lua: As("`d` on `path { }` is the string; the host hands it to this parser"),
117        doc: "SVG path data to the flat op form a `path` draws (ADR 0040): one parser, so every binding draws the same shape.",
118    },
119    Door {
120        rust: "Core::add_fragment",
121        c: Is("kui_fragment_add"),
122        odin: Is("fragment_add"),
123        node: Is("addFragment"),
124        lua: No(NO_HANDLE),
125        doc: "Registers a WGSL function and mints an id for `<fragment src>` (ADR 0015).",
126    },
127    Door {
128        rust: "Core::remove_fragment",
129        c: Is("kui_fragment_remove"),
130        odin: Is("fragment_remove"),
131        node: Is("removeFragment"),
132        lua: No(NO_HANDLE),
133        doc: "Drops a fragment; the renderer drops its pipelines (backlog AR8).",
134    },
135    Door {
136        rust: "Core::fragment_module_source",
137        c: Is("kui_fragment_source"),
138        odin: Is("fragment_source"),
139        node: No(NEVER_PAINTS),
140        lua: No(NO_HANDLE),
141        doc: "The whole WGSL module behind a handle, which is what a renderer compiles.",
142    },
143    Door {
144        rust: "Core::add_font_data",
145        c: Is("kui_font_add"),
146        odin: Is("font_add"),
147        node: Is("addFont"),
148        lua: No(NO_HANDLE),
149        doc: "Registers a font's bytes and mints an id for `font`.",
150    },
151    Door {
152        rust: "Core::add_system_font",
153        c: Is("kui_font_add_system"),
154        odin: Is("font_add_system"),
155        node: Is("addSystemFont"),
156        lua: No(NO_HANDLE),
157        doc: "Registers an installed family by name.",
158    },
159    Door {
160        rust: "Core::load_font_file",
161        c: Is("kui_font_load_file"),
162        odin: Is("font_load_file"),
163        node: Is("loadFontFile"),
164        lua: No(NO_HANDLE),
165        doc: "Registers a font file by path.",
166    },
167    Door {
168        rust: "Core::load_fonts_dir",
169        c: Is("kui_font_load_dir"),
170        odin: Is("font_load_dir"),
171        node: Is("loadFontsDir"),
172        lua: No(NO_HANDLE),
173        doc: "Registers every font file in a directory.",
174    },
175    Door {
176        rust: "Core::reload_system_fonts",
177        c: Is("kui_font_reload_system"),
178        odin: Is("font_reload_system"),
179        node: Is("reloadSystemFonts"),
180        lua: No(GUEST),
181        doc: "Scans the system's fonts again, so a font installed while the app runs is found (the scan is otherwise once a process); returns how many faces came and went.",
182    },
183    Door {
184        rust: "Core::set_fallback_fonts",
185        c: Is("kui_font_set_fallback"),
186        odin: Is("font_set_fallback"),
187        node: Is("setFallbackFonts"),
188        lua: No(NO_HANDLE),
189        doc: "The fonts asked, in order, for a character the text's own family lacks, before the platform's fallback list (backlog F121).",
190    },
191    Door {
192        rust: "Core::fallback_fonts",
193        c: No("the list is the one the host set"),
194        odin: No(ODIN_IS_C),
195        node: No("the list is the one the host set"),
196        lua: No(NO_HANDLE),
197        doc: "The families `set_fallback_fonts` named, in order.",
198    },
199    Door {
200        rust: "Core::remove_font",
201        c: Is("kui_font_remove"),
202        odin: Is("font_remove"),
203        node: Is("removeFont"),
204        lua: No(NO_HANDLE),
205        doc: "Drops a font.",
206    },
207    Door {
208        rust: "Core::system_font_families",
209        c: Is("kui_font_families"),
210        odin: Is("font_families"),
211        node: Is("systemFontFamilies"),
212        lua: No(NO_HANDLE),
213        doc: "The installed family names `add_system_font` accepts.",
214    },
215    Door {
216        rust: "Core::system_fonts",
217        c: Is("kui_system_fonts"),
218        odin: Is("system_fonts"),
219        node: Is("systemFonts"),
220        lua: No(NO_HANDLE),
221        doc: "The same families, each with what the font database read off its faces: `monospaced` (every face fixed-pitch), `weights`, `italic` (backlog F97) — a font picker's monospaced-first list without a file loaded or a glyph shaped.",
222    },
223    Door {
224        rust: "Core::add_sound",
225        c: Is("kui_sound_add"),
226        odin: Is("sound_add"),
227        node: Is("addSound"),
228        lua: No(NO_HANDLE),
229        doc: "Registers a sound's bytes and mints an id for `<audio src>`, `clickSound` and `play`.",
230    },
231    Door {
232        rust: "Core::remove_sound",
233        c: Is("kui_sound_remove"),
234        odin: Is("sound_remove"),
235        node: Is("removeSound"),
236        lua: No(NO_HANDLE),
237        doc: "Drops a sound.",
238    },
239    Door {
240        rust: "Core::set_text_cache_budget",
241        c: Is("kui_set_text_cache_budget"),
242        odin: Is("set_text_cache_budget"),
243        node: Is("setTextCacheBudget"),
244        lua: No(GUEST),
245        doc: "The shaped-text cache's byte budget (backlog C16).",
246    },
247    Door {
248        rust: "Core::text_cache_bytes",
249        c: Is("kui_text_cache_bytes"),
250        odin: Is("text_cache_bytes"),
251        node: Is("textCacheBytes"),
252        lua: No(GUEST),
253        doc: "What the shaped-text cache holds.",
254    },
255    // -- Audio -------------------------------------------------------------
256    Door {
257        rust: "Ui::play",
258        c: Is("kui_play"),
259        odin: Is("play"),
260        node: Is("play"),
261        lua: No(
262            "a script owns no sound handle, and its env is the view's: a playback started there would start again every frame — `audio { src = id }` is the declarative form, and what a script has",
263        ),
264        doc: "Starts a playback of a registered sound, outside any node; answers the playback id.",
265    },
266    Door {
267        rust: "Core::stop",
268        c: Is("kui_stop"),
269        odin: Is("stop"),
270        node: Is("stop"),
271        lua: No("as `play`: a script declares `audio { }` and stops it by not declaring it"),
272        doc: "Stops a playback, with an optional fade.",
273    },
274    Door {
275        rust: "Core::set_volume",
276        c: Is("kui_set_volume"),
277        odin: Is("set_volume"),
278        node: Is("setVolume"),
279        lua: As("`audio { volume = }` applies live"),
280        doc: "A playback's volume, with an optional tween.",
281    },
282    Door {
283        rust: "Core::pause",
284        c: Is("kui_pause"),
285        odin: Is("pause"),
286        node: Is("pause"),
287        lua: As("`audio { paused = true }` applies live"),
288        doc: "Pauses a playback.",
289    },
290    Door {
291        rust: "Core::resume",
292        c: Is("kui_resume"),
293        odin: Is("resume"),
294        node: Is("resume"),
295        lua: As("`audio { paused = false }`"),
296        doc: "Resumes a paused playback.",
297    },
298    Door {
299        rust: "Core::set_master_volume",
300        c: Is("kui_set_master_volume"),
301        odin: Is("set_master_volume"),
302        node: Is("setMasterVolume"),
303        lua: No(GUEST),
304        doc: "The device's master volume, with an optional tween.",
305    },
306    // -- Assistive ---------------------------------------------------------
307    Door {
308        rust: "Ui::announce",
309        c: Is("kui_announce"),
310        odin: Is("announce"),
311        node: Is("announce"),
312        lua: Is("announce"),
313        doc: "Says something once with no node behind it (ADR 0001).",
314    },
315    Door {
316        rust: "Core::take_announcements",
317        c: Is("kui_take_announcements"),
318        odin: Is("take_announcements"),
319        node: Is("Ctx.announcements"),
320        lua: No(GUEST),
321        doc: "Drains what was announced, for a host bridging assistive technology; a `KuiWindow`'s bridge is the runner's.",
322    },
323    Door {
324        rust: "Core::access_tree",
325        c: Is("kui_access_tree"),
326        odin: Is("access_tree"),
327        node: Is("accessTree"),
328        lua: No(GUEST),
329        doc: "The access tree of the last finished frame (ADR 0001).",
330    },
331    // -- Focus -------------------------------------------------------------
332    Door {
333        rust: "Ui::focus",
334        c: Is("kui_focus"),
335        odin: Is("focus"),
336        node: Is("focus"),
337        lua: Is("set_focus"),
338        doc: "Moves focus to a node now; an app's move stands over a modal's restore (backlog AR17). `keyFocus` is the declarative, edge-triggered form.",
339    },
340    Door {
341        rust: "Ui::blur",
342        c: As("`kui_focus(ctx, 0)`"),
343        odin: As("`focus(ui, 0)`"),
344        node: Is("blur"),
345        lua: Is("blur"),
346        doc: "Drops focus.",
347    },
348    Door {
349        rust: "Ui::focus_next",
350        c: Is("kui_focus_next"),
351        odin: Is("focus_next"),
352        node: Is("focusNext"),
353        lua: Is("focus_next"),
354        doc: "Steps the Tab ring forward (ADR 0002).",
355    },
356    Door {
357        rust: "Ui::focus_prev",
358        c: As("`kui_focus_next(ctx, false)`"),
359        odin: As("`focus_next(ui, false)`"),
360        node: Is("focusPrev"),
361        lua: Is("focus_prev"),
362        doc: "Steps the Tab ring backward.",
363    },
364    Door {
365        rust: "Ui::focus_region",
366        c: Is("kui_focus_region"),
367        odin: Is("focus_region"),
368        node: Is("focusRegion"),
369        lua: Is("focus_region"),
370        doc: "Enters a `focusRegion`'s ring, or leaves it for the main one (ADR 0022).",
371    },
372    Door {
373        rust: "Ui::region",
374        c: Is("kui_region"),
375        odin: Is("region"),
376        node: Is("region"),
377        lua: As("`env.region`, a reading"),
378        doc: "The region in effect.",
379    },
380    Door {
381        rust: "Ui::focused",
382        c: Is("kui_focused"),
383        odin: Is("focused"),
384        node: Is("focused"),
385        lua: As("`env.focus`, a reading"),
386        doc: "The focused node's key.",
387    },
388    Door {
389        rust: "Ui::is_focused",
390        c: Is("kui_is_focused"),
391        odin: Is("is_focused"),
392        node: Is("isFocused"),
393        lua: Is("is_focused"),
394        doc: "Whether a node has focus.",
395    },
396    Door {
397        rust: "Ui::focus_visible",
398        c: Is("kui_focus_visible"),
399        odin: Is("focus_visible"),
400        node: Is("focusVisible"),
401        lua: As("`env.focus_visible`, a reading"),
402        doc: "Whether focus came from the keyboard and the ring should show.",
403    },
404    Door {
405        rust: "Ui::key_of",
406        c: Is("kui_key_of"),
407        odin: Is("key_of"),
408        node: Is("keyOf"),
409        lua: As("every query and verb takes the label itself (`key_query`)"),
410        doc: "The key a label names this frame.",
411    },
412    Door {
413        rust: "Core::label_of",
414        c: No(
415            "the label is the app's own word for the node, and every door names a node by it or by the key an event carried; the one reader is the devtools' inspector, in the core",
416        ),
417        odin: No(ODIN_IS_C),
418        node: No("the same reason as C's"),
419        lua: No("the same reason as C's"),
420        doc: "The label a key was opened under.",
421    },
422    Door {
423        rust: "Ui::caret_visible",
424        c: Is("kui_caret_visible"),
425        odin: Is("caret_visible"),
426        node: Is("caretVisible"),
427        lua: As("`env.caret_visible`, a reading"),
428        doc: "The blink phase a custom editor draws its caret on.",
429    },
430    Door {
431        rust: "Core::set_caret_visible",
432        c: Is("kui_set_caret_visible"),
433        odin: Is("set_caret_visible"),
434        node: Is("setCaretVisible"),
435        lua: No(GUEST),
436        doc: "The host's blink clock writes the phase.",
437    },
438    Door {
439        rust: "Core::has_caret",
440        c: Is("kui_has_caret"),
441        odin: Is("has_caret"),
442        node: Is("hasCaret"),
443        lua: No(GUEST),
444        doc: "Whether anything focused draws a caret to blink — a `caretSolid` line's is not one — which arms a host's blink clock.",
445    },
446    Door {
447        rust: "Core::caret_stamp",
448        c: Is("kui_caret_stamp"),
449        odin: Is("caret_stamp"),
450        node: As(
451            "the loop in `index.js` runs the blink from `nextDeadlineMs`; a headless `Ctx` never blinks",
452        ),
453        lua: No(GUEST),
454        doc: "Changes when the caret moves or focus does, which re-arms the clock solid.",
455    },
456    // -- Queries -----------------------------------------------------------
457    Door {
458        rust: "Ui::is_hovered",
459        c: Is("kui_is_hovered"),
460        odin: Is("is_hovered"),
461        node: Is("isHovered"),
462        lua: Is("is_hovered"),
463        doc: "Whether the pointer is over a node.",
464    },
465    Door {
466        rust: "Ui::is_pressed",
467        c: Is("kui_is_pressed"),
468        odin: Is("is_pressed"),
469        node: Is("isPressed"),
470        lua: Is("is_pressed"),
471        doc: "Whether a press started on a node and the pointer is still over it.",
472    },
473    Door {
474        rust: "Ui::is_drop_target",
475        c: Is("kui_is_drop_target"),
476        odin: Is("is_drop_target"),
477        node: Is("isDropTarget"),
478        lua: Is("is_drop_target"),
479        doc: "Whether files dragged in from the OS are over a node (ADR 0031) — for drop-dependent layout; the colour is `drop_bg`.",
480    },
481    Door {
482        rust: "Core::drop_target",
483        c: Is("kui_drop_target"),
484        odin: Is("drop_target"),
485        node: Is("dropTarget"),
486        lua: Is("drop_target"),
487        doc: "The drop zone the dragged files are over, if any — what a driver answers the OS with, and what a test reads to say a zone was found (ADR 0031, decision 5).",
488    },
489    Door {
490        rust: "Ui::is_group_hovered",
491        c: As(
492            "`hoverBg` / `pressedBg` on a `hoverGroup` member paint it; the reader is what the Rust widgets ask when they paint by hand",
493        ),
494        odin: As("`hover_bg` / `pressed_bg` on a `hover_group` member paint it"),
495        node: As("the same form as C's"),
496        lua: As("the same form as C's"),
497        doc: "Whether any member of a hover group is hovered (`is_group_pressed` the same for a press).",
498    },
499    Door {
500        rust: "Core::cursor",
501        c: No("the pointer's position is the driver's own fact — it injected it"),
502        odin: No(ODIN_IS_C),
503        node: No("the same reason as C's"),
504        lua: No("the same reason as C's, one step removed"),
505        doc: "Where the pointer is, in logical viewport px.",
506    },
507    Door {
508        rust: "Core::cursor_shape",
509        c: Is("kui_cursor_shape"),
510        odin: Is("cursor_shape"),
511        node: Is("cursorShape"),
512        lua: No(GUEST),
513        doc: "The pointer shape the frame asks for, which the host sets on its window.",
514    },
515    Door {
516        rust: "Ui::layout_of",
517        c: Is("kui_layout_of"),
518        odin: Is("layout_of"),
519        node: Is("layoutOf"),
520        lua: Is("layout_of"),
521        doc: "Where layout put a node last frame (backlog C26).",
522    },
523    Door {
524        rust: "Ui::scroll_offset",
525        c: Is("kui_scroll_offset"),
526        odin: Is("scroll_offset"),
527        node: Is("scrollOffset"),
528        lua: Is("scroll_offset"),
529        doc: "A scrolling node's offset.",
530    },
531    Door {
532        rust: "Ui::scroll_geometry",
533        c: Is("kui_scroll_geometry"),
534        odin: Is("scroll_geometry"),
535        node: Is("scrollGeometry"),
536        lua: Is("scroll_geometry"),
537        doc: "A scrolling node's viewport and content sizes.",
538    },
539    Door {
540        rust: "Ui::set_scroll",
541        c: Is("kui_set_scroll"),
542        odin: Is("set_scroll"),
543        node: Is("setScroll"),
544        lua: Is("set_scroll"),
545        doc: "Scrolls a node to an offset.",
546    },
547    Door {
548        rust: "Ui::shift_scroll",
549        c: Is("kui_shift_scroll"),
550        odin: Is("shift_scroll"),
551        node: Is("shiftScroll"),
552        lua: Is("shift_scroll"),
553        doc: "Moves a node's scroll by content that moved under it, with no ease: a variable-height list's anchor (backlog C46).",
554    },
555    Door {
556        rust: "Ui::reveal",
557        c: Is("kui_reveal"),
558        odin: Is("reveal"),
559        node: Is("reveal"),
560        lua: Is("reveal"),
561        doc: "Scrolls whatever encloses a node until it is in view.",
562    },
563    Door {
564        rust: "Ui::text_hit",
565        c: Is("kui_text_hit"),
566        odin: Is("text_hit"),
567        node: Is("textHit"),
568        lua: Is("text_hit"),
569        doc: "The byte and line under a point in a node's text (backlog C18).",
570    },
571    Door {
572        rust: "Ui::caret_rect",
573        c: Is("kui_caret_rect"),
574        odin: Is("caret_rect"),
575        node: Is("caretRect"),
576        lua: Is("caret_rect"),
577        doc: "The caret rect for a byte offset in a node's text.",
578    },
579    Door {
580        rust: "Core::ime_rect",
581        c: Is("kui_ime_rect"),
582        odin: Is("ime_rect"),
583        node: Is("imeRect"),
584        lua: No(GUEST),
585        doc: "Where the OS candidate window goes, which the host hands to the platform (backlog C17).",
586    },
587    Door {
588        rust: "Ui::measure_text",
589        c: Is("kui_measure_text"),
590        odin: Is("measure_text"),
591        node: Is("measureText"),
592        lua: Is("measure_text"),
593        doc: "Shapes text in a style at a width and answers its size and line count.",
594    },
595    Door {
596        rust: "Ui::measure_rich_text",
597        c: Is("kui_measure_rich_text"),
598        odin: Is("measure_rich_text"),
599        node: As("`measureText` takes spans too"),
600        lua: As("`measure_text` takes spans too"),
601        doc: "The same for spans, shaped as one paragraph.",
602    },
603    Door {
604        rust: "Ui::edit_text",
605        c: Is("kui_edit_text"),
606        odin: Is("edit_text"),
607        node: Is("editText"),
608        lua: Is("edit_text"),
609        doc: "An editor's text, by key or by label.",
610    },
611    Door {
612        rust: "Ui::set_edit_text",
613        c: Is("kui_edit_set_text"),
614        odin: Is("edit_set_text"),
615        node: Is("setEditText"),
616        lua: Is("set_edit_text"),
617        doc: "Replaces an editor's text, caret at the end.",
618    },
619    Door {
620        rust: "Ui::set_edit_text_by_label",
621        c: Is("kui_edit_set_text_label"),
622        odin: Is("edit_set_text_label"),
623        node: As("`setEditText` takes the label too"),
624        lua: As("`set_edit_text` takes the label too"),
625        doc: "The same by the label an editor's `key` declares, which reaches one the frame is about to declare (backlog AR26).",
626    },
627    Door {
628        rust: "Core::animating",
629        c: Is("kui_animating"),
630        odin: Is("animating"),
631        node: Is("animating"),
632        lua: No(GUEST),
633        doc: "Whether the last frame left a transition mid-flight, so the host draws another without waiting for input.",
634    },
635    Door {
636        rust: "Core::owed",
637        c: Is("kui_owed"),
638        odin: Is("owed"),
639        node: Is("owed"),
640        lua: No(GUEST),
641        doc: "The same by kind — a finite transition, a keyframe cycle, a departing ghost, a requested frame, an autoscroll — so a test can wait for the transitions to run out under a cycle that never ends; Node's loop has `quiet()` for that wait (backlog F64).",
642    },
643    Door {
644        rust: "Core::set_frame_trace",
645        c: Is("kui_set_frame_trace"),
646        odin: Is("set_frame_trace"),
647        node: Is("setFrameTrace"),
648        lua: No(GUEST),
649        doc: "Turns on the trace of why frames run: who holds an owed frame, and whether a frame changed what is drawn (backlog F111).",
650    },
651    Door {
652        rust: "Core::frame_cause",
653        c: Is("kui_frame_cause"),
654        odin: Is("frame_cause"),
655        node: Is("frameCause"),
656        lua: No(GUEST),
657        doc: "Why the frame being built runs: the input it answers by kind, what the driver noted, and `owed` after a frame that owed one (backlog F111).",
658    },
659    Door {
660        rust: "Core::begin_frame_cause",
661        c: No(
662            "a C host's view runs between `kui_frame_begin` and `kui_frame_finish`, inside the frame it builds, so it reads that frame already",
663        ),
664        odin: No(ODIN_IS_C),
665        node: Is("Ctx.beginFrameCause"),
666        lua: No(GUEST),
667        doc: "Starts the next frame's record ahead of its `begin_frame`, for a driver whose view runs before the frame it is for — Node's loop — so `frame_cause` and `owed_by` read from the view answer that frame (backlog RG81).",
668    },
669    Door {
670        rust: "Core::note_frame_cause",
671        c: Is("kui_note_frame_cause"),
672        odin: Is("note_frame_cause"),
673        node: No(
674            "the drivers that note a reason are kui-native's, which a `KuiWindow` runs on; a `Ctx` driven by hand has nothing but the input the core already records",
675        ),
676        lua: No(GUEST),
677        doc: "A driver adds a reason the core cannot see — a wake, a resize, a blink, a retry — to the next frame's (backlog F111).",
678    },
679    Door {
680        rust: "Core::owed_by",
681        c: No(
682            "lists of named holders are strings the library would own across calls, an [out-array] struct and an ABI bump for a reading that is a debugging aid; a C host reads the kinds from `kui_owed`",
683        ),
684        odin: No(ODIN_IS_C),
685        node: Is("owedBy"),
686        lua: No(GUEST),
687        doc: "Who holds the frame the last one left owed: `owed` with the nodes, slots and calling lines named (backlog F111).",
688    },
689    Door {
690        rust: "Core::frame_unchanged",
691        c: Is("kui_frame_unchanged"),
692        odin: Is("frame_unchanged"),
693        node: Is("frameUnchanged"),
694        lua: No(GUEST),
695        doc: "Whether the last finished frame drew exactly what the one before drew, traced (backlog F111).",
696    },
697    Door {
698        rust: "Ui::request_frame",
699        c: As("`animate` on a node, and `kui_animating` for the driver to read"),
700        odin: As("`animate` on a node, and `animating` for the driver to read"),
701        node: As("the same form as C's"),
702        lua: As("the same form as C's"),
703        doc: "Asks for a frame after this one; the driver paces off `animating()`.",
704    },
705    Door {
706        rust: "Ui::modifiers",
707        c: No(
708            "the held modifiers ride on every key and pointer event's `mods`; the reader is what the stock editor's Shift-drag asks, inside the core",
709        ),
710        odin: No(ODIN_IS_C),
711        node: No("the same reason as C's"),
712        lua: No("the same reason as C's"),
713        doc: "The modifier keys held now.",
714    },
715    // -- Selection ---------------------------------------------------------
716    Door {
717        rust: "Ui::selection_text",
718        c: Is("kui_selection_text"),
719        odin: Is("selection_text"),
720        node: Is("selectionText"),
721        lua: Is("selection_text"),
722        doc: "The window's selected text — a scope's, a grid's or the focused editor's.",
723    },
724    Door {
725        rust: "Ui::selection_html",
726        c: Is("kui_selection_html"),
727        odin: Is("selection_html"),
728        node: Is("selectionHtml"),
729        lua: Is("selection_html"),
730        doc: "The same with the formatting the text declared.",
731    },
732    Door {
733        rust: "Ui::selection_ends",
734        c: Is("kui_selection_ends"),
735        odin: Is("selection_ends"),
736        node: Is("selectionEnds"),
737        lua: Is("selection_ends"),
738        doc: "A text selection's anchor and focus as row indices and bytes (ADR 0029).",
739    },
740    Door {
741        rust: "Ui::cell_selection",
742        c: Is("kui_cell_selection"),
743        odin: Is("cell_selection"),
744        node: Is("cellSelection"),
745        lua: Is("cell_selection"),
746        doc: "A `cells` grid's selection: its ends as absolute lines and columns, and whether it is a block (ADR 0017 §4).",
747    },
748    Door {
749        rust: "Ui::select_all_in",
750        c: Is("kui_select_all_in"),
751        odin: Is("select_all_in"),
752        node: Is("selectAllIn"),
753        lua: Is("select_all_in"),
754        doc: "Select All, scoped to a `selectable` node or a grid.",
755    },
756    Door {
757        rust: "Ui::clear_selection",
758        c: Is("kui_clear_selection"),
759        odin: Is("clear_selection"),
760        node: Is("clearSelection"),
761        lua: Is("clear_selection"),
762        doc: "Drops the window's selection.",
763    },
764    Door {
765        rust: "Ui::request_copy",
766        c: Is("kui_request_copy"),
767        odin: Is("request_copy"),
768        node: Is("requestCopy"),
769        lua: Is("request_copy"),
770        doc: "Asks for the selection as a copy, which may come back as a `selectionrange` question.",
771    },
772    Door {
773        rust: "Ui::answer_selection_range",
774        c: Is("kui_answer_selection_range"),
775        odin: Is("answer_selection_range"),
776        node: Is("answerSelectionRange"),
777        lua: Is("answer_selection_range"),
778        doc: "The app's answer to that question.",
779    },
780    Door {
781        rust: "Ui::set_clipboard",
782        c: Is("kui_set_clipboard"),
783        odin: Is("set_clipboard"),
784        node: Is("setClipboard"),
785        lua: Is("set_clipboard"),
786        doc: "A key sink's own Ctrl-C: posts a clipboard action for the host (backlog C33).",
787    },
788    Door {
789        rust: "Ui::set_clipboard_secret",
790        c: Is("kui_set_clipboard_secret"),
791        odin: Is("set_clipboard_secret"),
792        node: Is("setClipboardSecret"),
793        lua: Is("set_clipboard_secret"),
794        doc: "Posts a secret for the clipboard, which the host writes marked concealed and transient the way a password manager does, so no clipboard manager shows or keeps it (backlog F84).",
795    },
796    Door {
797        rust: "Ui::request_paste",
798        c: Is("kui_request_paste"),
799        odin: Is("request_paste"),
800        node: Is("requestPaste"),
801        lua: Is("request_paste"),
802        doc: "A key sink's own Ctrl-V: the clipboard comes back as a commit, marked `concealed` / `transient` when the pasteboard said so (backlog F84). One ask at a time — a second while one is unanswered is dropped.",
803    },
804    Door {
805        rust: "Ui::awaiting_paste",
806        c: Is("kui_awaiting_paste"),
807        odin: Is("awaiting_paste"),
808        node: Is("awaitingPaste"),
809        lua: Is("awaiting_paste"),
810        doc: "Whether a paste asked for is still unanswered (backlog AR34).",
811    },
812    Door {
813        rust: "Ui::request_files",
814        c: Is("kui_request_files"),
815        odin: Is("request_files"),
816        node: Is("requestFiles"),
817        lua: Is("request_files"),
818        doc: "Asks for the platform's Open, Save or folder dialog; the answer is a `files` event to whoever asked. One at a time — a second while one is out is dropped (backlog C51).",
819    },
820    Door {
821        rust: "Ui::awaiting_files",
822        c: Is("kui_awaiting_files"),
823        odin: Is("awaiting_files"),
824        node: Is("awaitingFiles"),
825        lua: Is("awaiting_files"),
826        doc: "Whether a file dialog asked for is still unanswered.",
827    },
828    Door {
829        rust: "Core::take_file_requests",
830        c: As("`kui_take_file_request`, then `kui_file_request_filter` per filter"),
831        odin: As("`take_file_request`, then `file_request_filter` per filter"),
832        node: Is("takeFileRequests"),
833        lua: No(GUEST),
834        doc: "Drains the dialog asked for, for a host that shows it itself; the runner does. The answer goes back as input (`Ctx.answerFiles`, `kui_input_files`).",
835    },
836    Door {
837        rust: "Core::set_lookup_available",
838        c: Is("kui_set_lookup_available"),
839        odin: Is("set_lookup_available"),
840        node: Is("setLookupAvailable"),
841        lua: No(GUEST),
842        doc: "Whether the host can show the platform's definition panel, which decides whether Look Up is offered.",
843    },
844    // -- Menus -------------------------------------------------------------
845    Door {
846        rust: "Ui::open_menu",
847        c: Is("kui_open_menu"),
848        odin: Is("open_menu"),
849        node: Is("openMenu"),
850        lua: Is("open_menu"),
851        doc: "Opens a context menu on a node at a point.",
852    },
853    Door {
854        rust: "Ui::close_menu",
855        c: Is("kui_close_menu"),
856        odin: Is("close_menu"),
857        node: Is("closeMenu"),
858        lua: Is("close_menu"),
859        doc: "Closes it.",
860    },
861    Door {
862        rust: "Core::take_menu_actions",
863        c: Is("kui_take_menu_action"),
864        odin: Is("take_menu_action"),
865        node: Is("takeMenuActions"),
866        lua: As(
867            "a chosen row comes back as a `menu` event on the node; the clipboard actions are the host's",
868        ),
869        doc: "Drains what a menu (or a chord, or the standard bar) asked of the host: a clipboard write, a paste, a Look Up.",
870    },
871    Door {
872        rust: "Core::menu",
873        c: As("`kui_menu_item_count` / `kui_menu_item`, one row at a time"),
874        odin: As("`menu_item_count` / `menu_item`, one row at a time"),
875        node: Is("menu"),
876        lua: No(GUEST),
877        doc: "The open menu, for a host showing it natively.",
878    },
879    Door {
880        rust: "Core::set_native_menus",
881        c: Is("kui_set_native_menus"),
882        odin: Is("set_native_menus"),
883        node: Is("setNativeMenus"),
884        lua: No(GUEST),
885        doc: "Whether the host shows menus itself; the core then draws none.",
886    },
887    Door {
888        rust: "Core::activate_menu_item",
889        c: Is("kui_activate_menu_item"),
890        odin: Is("activate_menu_item"),
891        node: Is("activateMenuItem"),
892        lua: No(GUEST),
893        doc: "Reports that the host's own menu chose a row; a row that cannot be chosen (disabled, a separator) is refused and the menu stays open.",
894    },
895    Door {
896        rust: "Core::menu_bar",
897        c: As(
898            "`kui_menu_bar_menu_count` / `kui_menu_bar_menu` / `kui_menu_bar_item`, one row at a time",
899        ),
900        odin: As("`menu_bar_menu_count` / `menu_bar_menu` / `menu_bar_item`, one row at a time"),
901        node: Is("menuBar"),
902        lua: No(GUEST),
903        doc: "The declared menu bar, for a host handing it to the OS.",
904    },
905    Door {
906        rust: "Core::set_native_menu_bar",
907        c: Is("kui_set_native_menu_bar"),
908        odin: Is("set_native_menu_bar"),
909        node: Is("setNativeMenuBar"),
910        lua: No(GUEST),
911        doc: "Whether the host owns the bar; the core then draws no strip.",
912    },
913    Door {
914        rust: "Core::activate_menu_bar_item",
915        c: Is("kui_activate_menu_bar_item"),
916        odin: Is("activate_menu_bar_item"),
917        node: Is("activateMenuBarItem"),
918        lua: No(GUEST),
919        doc: "Reports that the OS bar chose a row.",
920    },
921    // -- Windows -----------------------------------------------------------
922    Door {
923        rust: "Ui::window",
924        c: Is("kui_window_declare"),
925        odin: Is("window_declare"),
926        node: As("the root's `windows` prop"),
927        lua: As("the root's `windows` field"),
928        doc: "Declares that a named window exists this frame (ADR 0003 step 3).",
929    },
930    Door {
931        rust: "Core::windows",
932        c: As("the ids arrive on `KUI_CMD_OPEN`; a host keeps the list it opened"),
933        odin: As(
934            "the ids arrive on `take_window_command`'s `.Open`; a host keeps the list it opened",
935        ),
936        node: Is("windows"),
937        lua: No(GUEST),
938        doc: "The names of the windows open now.",
939    },
940    Door {
941        rust: "Ui::window_name",
942        c: Is("kui_ctx_window_name"),
943        odin: Is("ctx_window_name"),
944        node: Is("windowName"),
945        lua: As("`env.window.name`, a reading"),
946        doc: "The name of the window this context draws.",
947    },
948    Door {
949        rust: "Ui::set_window_size",
950        c: Is("kui_set_window_size"),
951        odin: Is("set_window_size"),
952        node: Is("setWindowSize"),
953        lua: Is("set_window_size"),
954        doc: "Asks the driver to resize a window.",
955    },
956    Door {
957        rust: "Ui::focus_window",
958        c: Is("kui_focus_window"),
959        odin: Is("focus_window"),
960        node: Is("focusWindow"),
961        lua: Is("focus_window"),
962        doc: "Asks the driver to bring a window to the front.",
963    },
964    Door {
965        rust: "Ui::window_title",
966        c: Is("kui_window_title"),
967        odin: Is("window_title"),
968        node: As("the root's `title` prop"),
969        lua: As("the root's `title` field"),
970        doc: "Declares the window's title this frame.",
971    },
972    Door {
973        rust: "Ui::always_on_top",
974        c: Is("kui_set_always_on_top"),
975        odin: Is("set_always_on_top"),
976        node: As("the root's `alwaysOnTop` prop"),
977        lua: As("the root's `always_on_top` field"),
978        doc: "Declares that the window sits above every other app's this frame (backlog C30).",
979    },
980    Door {
981        rust: "Ui::secure_input",
982        c: Is("kui_set_secure_input"),
983        odin: Is("set_secure_input"),
984        node: As("the root's `secureInput` prop"),
985        lua: As("the root's `secure_input` field"),
986        doc: "Declares that this frame wants secure keyboard entry while the window has the keyboard — a password prompt (backlog F85).",
987    },
988    Door {
989        rust: "Ui::option_as_alt",
990        c: Is("kui_set_option_as_alt"),
991        odin: Is("set_option_as_alt"),
992        node: As("the root's `optionAsAlt` prop"),
993        lua: As("the root's `option_as_alt` field"),
994        doc: "Declares which Option keys act as Alt in this window on macOS, so a dead key like ⌥u arrives as `<A-u>` (backlog F113).",
995    },
996    Door {
997        rust: "Ui::ime_off",
998        c: Is("kui_set_ime_off"),
999        odin: Is("set_ime_off"),
1000        node: As("the root's `imeOff` prop"),
1001        lua: As("the root's `ime_off` field"),
1002        doc: "Declares that this window takes the keyboard as keys, with the input method off — no composition, and on a Mac no dead keys and no press-and-hold, so a held letter repeats (backlog F125).",
1003    },
1004    Door {
1005        rust: "Ui::window_command",
1006        c: As(
1007            "the chrome roles (`KuiSpec.window_role`) are the door; the verb is what `widgets::window_buttons` lowers to",
1008        ),
1009        odin: As("`window` on a node (`Spec.window`, the chrome roles) is the door"),
1010        node: As(
1011            "`KuiWindow.close()` for the one command the runner takes from outside a frame; the rest are `windowRole`",
1012        ),
1013        lua: As("`window_role`"),
1014        doc: "Minimize, toggle-maximize, start-drag, close — what a chrome node asks for on a press.",
1015    },
1016    Door {
1017        rust: "Core::window_title",
1018        c: Is("kui_window_title_get"),
1019        odin: Is("window_title_get"),
1020        node: Is("Ctx.windowTitle"),
1021        lua: No(GUEST),
1022        doc: "What the frame declared, for a driver applying it; a `KuiWindow` applies its own.",
1023    },
1024    Door {
1025        rust: "Core::always_on_top",
1026        c: Is("kui_always_on_top_get"),
1027        odin: Is("always_on_top_get"),
1028        node: Is("Ctx.alwaysOnTop"),
1029        lua: As("`env.window.always_on_top`, a reading"),
1030        doc: "The same for the level.",
1031    },
1032    Door {
1033        rust: "Core::secure_input",
1034        c: Is("kui_secure_input_get"),
1035        odin: Is("secure_input_get"),
1036        node: Is("Ctx.secureInput"),
1037        lua: No(GUEST),
1038        doc: "The same for the secure-input ask: what a driver with its own loop reads to make the platform call; the runner makes it for a `KuiWindow` and `kui_run`.",
1039    },
1040    Door {
1041        rust: "Core::option_as_alt",
1042        c: Is("kui_option_as_alt_get"),
1043        odin: Is("option_as_alt_get"),
1044        node: Is("Ctx.optionAsAlt"),
1045        lua: No(GUEST),
1046        doc: "The same for the Option-as-Alt ask: what a driver with its own loop reads to apply it to its window; the runner applies it for a `KuiWindow` and `kui_run`.",
1047    },
1048    Door {
1049        rust: "Core::ime_off",
1050        c: Is("kui_ime_off_get"),
1051        odin: Is("ime_off_get"),
1052        node: Is("Ctx.imeOff"),
1053        lua: No(GUEST),
1054        doc: "The same for the input-method ask: what a driver with its own loop reads to apply it to its window; the runner applies it for a `KuiWindow` and `kui_run`.",
1055    },
1056    Door {
1057        rust: "Core::take_window_commands",
1058        c: Is("kui_take_window_command"),
1059        odin: Is("take_window_command"),
1060        node: Is("Ctx.windowCommands"),
1061        lua: No(GUEST),
1062        doc: "Drains what the frame asked of the driver: open, close, resize, focus, redraw.",
1063    },
1064    Door {
1065        rust: "Core::window_closed",
1066        c: Is("kui_window_closed"),
1067        odin: Is("window_closed"),
1068        node: Is("Ctx.windowClosed"),
1069        lua: No(GUEST),
1070        doc: "The driver reports a window gone.",
1071    },
1072    Door {
1073        rust: "Core::dismiss_window",
1074        c: Is("kui_window_dismissed"),
1075        odin: Is("window_dismissed"),
1076        node: Is("Ctx.windowDismissed"),
1077        lua: No(GUEST),
1078        doc: "The driver reports a popup dismissed, with why (ADR 0003 step 4).",
1079    },
1080    // -- Theme, metrics, tokens --------------------------------------------
1081    Door {
1082        rust: "Core::set_theme",
1083        c: Is("kui_theme_set"),
1084        odin: Is("theme_set"),
1085        node: Is("setTheme"),
1086        lua: No("read-only: the palette is the host's (ADR 0019)"),
1087        doc: "Pins a whole palette.",
1088    },
1089    Door {
1090        rust: "Core::set_accent",
1091        c: Is("kui_theme_set_accent"),
1092        odin: Is("theme_set_accent"),
1093        node: Is("setAccent"),
1094        lua: No("as `set_theme`"),
1095        doc: "Pins an accent and keeps the OS's base.",
1096    },
1097    Door {
1098        rust: "Ui::theme",
1099        c: Is("kui_theme"),
1100        odin: Is("theme"),
1101        node: Is("theme"),
1102        lua: As("`env.theme`, a reading"),
1103        doc: "The palette in effect (`THEME_ROLES`).",
1104    },
1105    Door {
1106        rust: "Core::set_metrics",
1107        c: Is("kui_metrics_set"),
1108        odin: Is("metrics_set"),
1109        node: Is("setMetrics"),
1110        lua: No("as `set_theme` (backlog T2)"),
1111        doc: "Pins the stock widgets' sizes.",
1112    },
1113    Door {
1114        rust: "Ui::metrics",
1115        c: Is("kui_metrics"),
1116        odin: Is("metrics"),
1117        node: Is("metrics"),
1118        lua: As("`env.metrics`, a reading"),
1119        doc: "The sizes in effect (`METRIC_ROLES`).",
1120    },
1121    Door {
1122        rust: "Ui::set_tokens",
1123        c: Is("kui_tokens_set"),
1124        odin: Is("tokens_set"),
1125        node: Is("setTokens"),
1126        lua: Is("set_tokens"),
1127        doc: "Declares the origin's colour and length tokens (ADR 0027).",
1128    },
1129    Door {
1130        rust: "Tokens::derive",
1131        c: Is("kui_tokens_derive"),
1132        odin: Is("tokens_derive"),
1133        node: As("a colour with `from` in `setTokens`"),
1134        lua: As("a colour with `from` in `set_tokens`"),
1135        doc: "Adds derived colours to the declared ones (ADR 0028).",
1136    },
1137    Door {
1138        rust: "Ui::tokens",
1139        c: As("`kui_token_color` / `kui_token_length`, one name at a time"),
1140        odin: As("`token_color` / `token_length`, one name at a time"),
1141        node: Is("tokens"),
1142        lua: As("`env.tokens`, a reading"),
1143        doc: "The tokens in effect, resolved for the appearance.",
1144    },
1145    Door {
1146        rust: "Core::tokens_declared",
1147        c: No(
1148            "a plugin declares in every `kui_ext_view` and pays the parse; a reader that lets it skip the second is one line, once a plugin asks for it",
1149        ),
1150        odin: No(ODIN_IS_C),
1151        node: No("an app declares once, before its loop"),
1152        lua: No("the `tokens` global is declared once, at load"),
1153        doc: "Whether an origin declared tokens.",
1154    },
1155    // -- Diagnostics and devtools ------------------------------------------
1156    Door {
1157        rust: "Core::set_diagnostics",
1158        c: Is("kui_set_diagnostics"),
1159        odin: Is("set_diagnostics"),
1160        node: Is("setDiagnostics"),
1161        lua: No(GUEST),
1162        doc: "Turns the per-frame checks on.",
1163    },
1164    Door {
1165        rust: "Core::take_warnings",
1166        c: Is("kui_take_warnings"),
1167        odin: Is("take_warnings"),
1168        node: Is("warnings"),
1169        lua: No("the host drains and the Lua runner prints"),
1170        doc: "Drains the warnings raised since the last call.",
1171    },
1172    Door {
1173        rust: "Core::warnings_raised",
1174        c: No(
1175            "the C smoke round drains `kui_take_warnings` after each frame; a non-draining reader waits for a C harness that needs one",
1176        ),
1177        odin: No(ODIN_IS_C),
1178        node: Is("warningsRaised"),
1179        lua: No(GUEST),
1180        doc: "The warnings raised so far, undrained, which is what an example's self-check reads (ADR 0021).",
1181    },
1182    Door {
1183        rust: "Core::set_devtools",
1184        c: Is("kui_set_devtools"),
1185        odin: Is("set_devtools"),
1186        node: Is("setDevtools"),
1187        lua: No(GUEST),
1188        doc: "Turns the devtools panel on.",
1189    },
1190    Door {
1191        rust: "Core::devtools",
1192        c: Is("kui_devtools"),
1193        odin: Is("devtools"),
1194        node: Is("devtools"),
1195        lua: No(GUEST),
1196        doc: "Whether it is on.",
1197    },
1198    Door {
1199        rust: "Core::set_devtools_dock",
1200        c: Is("kui_set_devtools_dock"),
1201        odin: Is("set_devtools_dock"),
1202        node: Is("setDevtoolsDock"),
1203        lua: No(GUEST),
1204        doc: "Where it sits.",
1205    },
1206    Door {
1207        rust: "Core::devtools_dock",
1208        c: Is("kui_devtools_dock"),
1209        odin: Is("devtools_dock"),
1210        node: Is("devtoolsDock"),
1211        lua: No(GUEST),
1212        doc: "Where it sits, read back.",
1213    },
1214    Door {
1215        rust: "Core::host_rect",
1216        c: Is("kui_host_rect"),
1217        odin: Is("host_rect"),
1218        node: Is("hostArea"),
1219        lua: No(GUEST),
1220        doc: "Where the frame laid the host out in the window, logical px: the viewport with its origin, which is what tells the app's quads from the dock's (backlog F92).",
1221    },
1222    Door {
1223        rust: "Core::set_devtools_theme",
1224        c: Is("kui_set_devtools_theme"),
1225        odin: Is("set_devtools_theme"),
1226        node: Is("setDevtoolsTheme"),
1227        lua: No(GUEST),
1228        doc: "Seeds the panel's theme override.",
1229    },
1230    Door {
1231        rust: "Core::set_devtools_key",
1232        c: Is("kui_set_devtools_key"),
1233        odin: Is("set_devtools_key"),
1234        node: Is("setDevtoolsKey"),
1235        lua: No(GUEST),
1236        doc: "Respells the chord that moves the keyboard into the panel (`Ctrl+Shift+I` by default).",
1237    },
1238    Door {
1239        rust: "Core::devtools_key",
1240        c: Is("kui_devtools_key"),
1241        odin: Is("devtools_key"),
1242        node: Is("devtoolsKey"),
1243        lua: No(GUEST),
1244        doc: "That chord, read back in its portable spelling.",
1245    },
1246    Door {
1247        rust: "Ui::devtools_tab",
1248        c: Is("kui_devtools_tab"),
1249        odin: Is("devtools_tab"),
1250        node: As("`<devtoolsTab name label slot/>`"),
1251        lua: As("`devtools_tab { name=, label=, slot= }`"),
1252        doc: "Declares a devtools tab an extension fills through the slot named (ADR 0032).",
1253    },
1254    Door {
1255        rust: "Ui::devtools_tab_with",
1256        c: Is("kui_devtools_tab_open"),
1257        odin: Is("devtools_tab_open"),
1258        node: As(
1259            "`<devtoolsTab name label>{() => …}</devtoolsTab>`, the function child called only while the tab is on show",
1260        ),
1261        lua: As(
1262            "`devtools_tab { name=, label=, view = function(env) … end }`, called only while the tab is on show",
1263        ),
1264        doc: "Declares a devtools tab the host draws itself, and draws it only while it is on show.",
1265    },
1266    Door {
1267        rust: "Core::devtools_shown_tab",
1268        c: No(
1269            "a C host's open answers whether the tab is on show (`kui_devtools_tab_open`); nothing encodes ahead of the core there",
1270        ),
1271        odin: No(ODIN_IS_C),
1272        node: Is("devtoolsShownTab"),
1273        lua: No("the runner's converter reads it for the script (ADR 0032, decision 3)"),
1274        doc: "The declared devtools tab on show, which a data binding reads once a frame to call the tab's function.",
1275    },
1276    Door {
1277        rust: "Core::devtools_selected",
1278        c: Is("kui_devtools_selected"),
1279        odin: Is("devtools_selected"),
1280        node: Is("devtoolsSelected"),
1281        lua: No(GUEST),
1282        doc: "The node the panel's tree tab has selected (ADR 0032, decision 4).",
1283    },
1284    Door {
1285        rust: "Core::devtools_hovered",
1286        c: Is("kui_devtools_hovered"),
1287        odin: Is("devtools_hovered"),
1288        node: Is("devtoolsHovered"),
1289        lua: No(GUEST),
1290        doc: "The tree row under the pointer.",
1291    },
1292    Door {
1293        rust: "Core::devtools_picked",
1294        c: Is("kui_devtools_picked"),
1295        odin: Is("devtools_picked"),
1296        node: Is("devtoolsPicked"),
1297        lua: No(GUEST),
1298        doc: "The node the picker is over.",
1299    },
1300    Door {
1301        rust: "Core::set_devtools_pick",
1302        c: Is("kui_set_devtools_pick"),
1303        odin: Is("set_devtools_pick"),
1304        node: Is("setDevtoolsPick"),
1305        lua: No(GUEST),
1306        doc: "Raises the panel's picker from outside it, or puts it away; raised from a declared tab, the pick lands in `devtools_selected` and the tab stays up.",
1307    },
1308    Door {
1309        rust: "Core::devtools_picking",
1310        c: Is("kui_devtools_picking"),
1311        odin: Is("devtools_picking"),
1312        node: Is("devtoolsPicking"),
1313        lua: No(GUEST),
1314        doc: "Whether the picker is up.",
1315    },
1316    Door {
1317        rust: "Core::set_devtools_selected",
1318        c: Is("kui_set_devtools_selected"),
1319        odin: Is("set_devtools_selected"),
1320        node: Is("setDevtoolsSelected"),
1321        lua: No(GUEST),
1322        doc: "Selects and reveals a node in the tree tab from outside the panel.",
1323    },
1324    Door {
1325        rust: "Core::set_devtools_tab",
1326        c: Is("kui_set_devtools_tab"),
1327        odin: Is("set_devtools_tab"),
1328        node: Is("setDevtoolsTab"),
1329        lua: No(GUEST),
1330        doc: "Shows the panel's tab named — one of its own, in any case, or a declared one, as declared — from outside the panel, as the strip's click does; a hidden panel comes back docked.",
1331    },
1332    Door {
1333        rust: "Core::devtools_current_tab",
1334        c: Is("kui_devtools_current_tab"),
1335        odin: Is("devtools_current_tab"),
1336        node: Is("devtoolsCurrentTab"),
1337        lua: No(GUEST),
1338        doc: "The tab the panel is on, by name.",
1339    },
1340    Door {
1341        rust: "Core::set_devtools_legend",
1342        c: Is("kui_set_devtools_legend"),
1343        odin: Is("set_devtools_legend"),
1344        node: Is("setDevtoolsLegend"),
1345        lua: No(GUEST),
1346        doc: "The key legend the panel's facts tab shows.",
1347    },
1348    Door {
1349        rust: "Core::set_inspect",
1350        c: Is("kui_set_inspect"),
1351        odin: Is("set_inspect"),
1352        node: Is("setInspect"),
1353        lua: No(GUEST),
1354        doc: "Turns the per-frame node snapshot behind `nodes` on.",
1355    },
1356    Door {
1357        rust: "Core::nodes",
1358        c: Is("kui_nodes"),
1359        odin: Is("nodes"),
1360        node: Is("nodes"),
1361        lua: No(GUEST),
1362        doc: "The last frame's nodes with what layout and the declarations made of them — a tree view's and an inspector's data.",
1363    },
1364    // -- Extensions --------------------------------------------------------
1365    Door {
1366        rust: "Ui::add_extension",
1367        c: Is("kui_ctx_add_extension"),
1368        odin: Is("ctx_add_extension"),
1369        node: Is("Ctx.addExtension"),
1370        lua: Is("add_extension"),
1371        doc: "Loads a plugin under a namespace; a `KuiWindow` takes its list at construction (`extensions`).",
1372    },
1373    Door {
1374        rust: "Launcher::extensions",
1375        c: As("`kui_ctx_extension_count` / `kui_ctx_extension_namespace`, one at a time"),
1376        odin: As("`ctx_extension_count` / `ctx_extension_namespace`, one at a time"),
1377        node: Is("Ctx.extensionNamespaces"),
1378        lua: Is("extension_namespaces"),
1379        doc: "The namespaces loaded.",
1380    },
1381    // -- The driver's half: what a host does to run a core ----------------
1382    // Lua has none of these, for the one reason `GUEST` states; Node's are
1383    // on `Ctx` alone because a `KuiWindow`'s driver is the runner.
1384    Door {
1385        rust: "Core::frame",
1386        c: As("`kui_frame_begin` … `kui_frame_finish`"),
1387        odin: As("`frame_begin` … `frame_finish`, or `kui.frame` around a view"),
1388        node: Is("Ctx.frame"),
1389        lua: No(GUEST),
1390        doc: "Runs one frame: the view, layout, the draw list; `KuiWindow.setView` is the windowed form, the runner calling it.",
1391    },
1392    Door {
1393        rust: "Core::output",
1394        c: Is("kui_draw_data"),
1395        odin: Is("draw_data"),
1396        node: Is("quads"),
1397        lua: No(GUEST),
1398        doc: "The draw list: quads, clips, fragment and texture draws (`clips`, `fragmentDraws`, `textureDraws` beside `quads` in Node) and the frame's stats.",
1399    },
1400    Door {
1401        rust: "Core::take_pending_events",
1402        c: Is("kui_poll_event"),
1403        odin: Is("poll_event"),
1404        node: Is("pollEvents"),
1405        lua: As("`on_event(ev)`, pushed after each frame"),
1406        doc: "What the frame and the input since produced, for `update`.",
1407    },
1408    Door {
1409        rust: "Core::set_time",
1410        c: Is("kui_set_time"),
1411        odin: Is("set_time"),
1412        node: Is("Ctx.setTime"),
1413        lua: No(GUEST),
1414        doc: "The clock the tweens read; a window's runner sets it from the display.",
1415    },
1416    Door {
1417        rust: "Core::env",
1418        c: As("`kui_env_set` and its four siblings, `ENV_FIELDS`' C column"),
1419        odin: As("`env_set` and its four siblings"),
1420        node: Is("Ctx.setEnv"),
1421        lua: No(GUEST),
1422        doc: "The host facts written in (the `env` field); a `KuiWindow`'s runner writes its own.",
1423    },
1424    Door {
1425        rust: "Ui::env",
1426        c: No("C is the host, so it writes the facts and has no reading (`ENV_FIELDS`)"),
1427        odin: No(ODIN_IS_C),
1428        node: Is("env"),
1429        lua: As("`env`, the view's argument"),
1430        doc: "The facts read back, `ENV_FIELDS` row for row.",
1431    },
1432    Door {
1433        rust: "Core::handle_input",
1434        c: As("`kui_input_cursor` … `kui_input_access`, one per `InputEvent`"),
1435        odin: As(
1436            "`input_cursor` … `input_access`, one per input event; `click` and `press` for a drive",
1437        ),
1438        node: As(
1439            "`Ctx.cursor` … `Ctx.access`, one per `InputEvent`; a `KuiWindow` refuses injection",
1440        ),
1441        lua: No(GUEST),
1442        doc: "Pointer, wheel, key, text, IME, assistive and OS file-drag input; a wheel gesture's latching is `scroll_gesture` (`kui_input_scroll_gesture`, `Ctx.scrollGesture`, backlog F107); `press` / `release` are a click by label (`kui_input_press`, `Ctx.press`); the file drag is `drag_files` / `drop_files` / `drag_cancel` (ADR 0031); a file dialog's answer is `answer_files` (`kui_input_files`, `Ctx.answerFiles`, backlog C51); the documents the OS asked the app to open are `InputEvent::Open` (`kui_input_open`, `Ctx.openDocuments`, backlog F124).",
1443    },
1444    Door {
1445        rust: "Core::modifiers",
1446        c: Is("kui_input_modifiers"),
1447        odin: Is("input_modifiers"),
1448        node: Is("Ctx.modifiers"),
1449        lua: No(GUEST),
1450        doc: "The modifier state, reported on its own when the OS does (backlog AR22).",
1451    },
1452    Door {
1453        rust: "Core::release_held_keys",
1454        c: Is("kui_release_held_keys"),
1455        odin: Is("release_held_keys"),
1456        node: As(
1457            "`Ctx.setEnv({focused: false})` releases, as losing the keyboard does for every driver (ADR 0020)",
1458        ),
1459        lua: No(GUEST),
1460        doc: "Lets go of every key the focused sink holds.",
1461    },
1462    Door {
1463        rust: "Core::set_subpixel_text",
1464        c: Is("kui_set_subpixel_text"),
1465        odin: Is("set_subpixel_text"),
1466        node: No(NEVER_PAINTS),
1467        lua: No(GUEST),
1468        doc: "LCD subpixel coverage for outline glyphs, for a renderer that blends per channel.",
1469    },
1470    Door {
1471        rust: "Core::take_audio_commands",
1472        c: Is("kui_take_audio_commands"),
1473        odin: Is("take_audio_commands"),
1474        node: Is("Ctx.audioCommands"),
1475        lua: No(GUEST),
1476        doc: "Drains what the frame asked of the audio device; a `KuiWindow`'s device is the runner's.",
1477    },
1478    Door {
1479        rust: "Core::audio_ended",
1480        c: Is("kui_audio_ended"),
1481        odin: Is("audio_ended"),
1482        node: Is("Ctx.audioEnded"),
1483        lua: No(GUEST),
1484        doc: "The device reports a playback over.",
1485    },
1486    Door {
1487        rust: "Core::audio_truncated",
1488        c: Is("kui_audio_truncated"),
1489        odin: Is("audio_truncated"),
1490        node: Is("Ctx.audioTruncated"),
1491        lua: No(GUEST),
1492        doc: "The device reports a stop that cut a playback short — a one-shot node's removal becomes `truncated-playback`.",
1493    },
1494    Door {
1495        rust: "Core::audio_refused",
1496        c: Is("kui_audio_refused"),
1497        odin: Is("audio_refused"),
1498        node: Is("Ctx.audioRefused"),
1499        lua: No(GUEST),
1500        doc: "The device reports a play it would not take — a `refused` sound event and `playback-refused`.",
1501    },
1502    // -- The runner's options (`Launcher` in Rust, `WindowOptions` in Node,
1503    // `kui_run_with` in C). One row for the set, since they are one
1504    // decision: what a window opens as.
1505    Door {
1506        rust: "Launcher::size",
1507        c: As("`width` / `height` in the `KuiRunConfig` `kui_run_with` takes"),
1508        odin: As("`width` / `height` in the `Run_Config` `kui.run` takes"),
1509        node: As("`width` / `height` in `WindowOptions`"),
1510        lua: No(GUEST),
1511        doc: "The window's opening size; `min_size` / `max_size` / `chrome` / `text_aa` / `diagnostics` / `frame_latency` are the rest of the set, and each binding's form carries them all (`min_w`, `chrome`, `text_aa`, `diagnostics`, `frame_latency` in C; `minWidth`, `chrome`, `textAa`, `diagnostics`, `frameLatency` in Node). `Launcher::devtools` and `Launcher::core` are the two the others reach another way: `kui_set_devtools` / `setDevtools` on the context, and the context handed to `kui_run_with` *is* the core.",
1512    },
1513    Door {
1514        rust: "Launcher::icon",
1515        c: Is("kui_set_icon"),
1516        odin: Is("set_icon"),
1517        node: As("`icon` in `WindowOptions`"),
1518        lua: No(GUEST),
1519        doc: "The icon every window of the app is created with — RGBA pixels and their size — shown by Windows in the title bar, Alt-Tab and the taskbar and by X11's window manager; macOS (the bundle's `.icns`) and Wayland (the `.desktop` file's) have no window icon (backlog F86). `Launcher::icon_resource` is the Windows executable's own icon resource, which wins there — C's `resource` argument, Node's `icon.resource`. C's is a free function called before `kui_run`, for `kui_on_teardown`'s reason.",
1520    },
1521    Door {
1522        rust: "App::teardown",
1523        c: Is("kui_on_teardown"),
1524        odin: As("the `teardown` procedure `kui.run` takes"),
1525        node: Is("KuiWindow.onTeardown"),
1526        lua: No(GUEST),
1527        doc: "The window going for good — its close button, Quit from the menu or the dock, a close command on it, a pumped runner ended — heard once, before `run` returns or the process exits, with nothing drawing: the place to keep what the app would lose with the window (backlog F74, the other two hosts under RG1). On macOS a Quit ends the process from inside the loop, so this is the only thing an app runs on ⌘Q — nothing after `run`, `kui_run` or `await runWindowed(...)` does, not even `process.on('exit')`. C's is a free function called before `kui_run`, with the run's `user`, since `kui_run`'s app is three arguments and not a struct. Node's is the window's door, called from inside the pump that saw the window go; `runWindowed` registers its config's `teardown(model)` there, and `createApp`'s `app.teardown()` runs the same one for a headless drive.",
1528    },
1529];
1530
1531#[cfg(test)]
1532mod tests {
1533    use super::*;
1534
1535    /// A row's Rust spelling is a `pub fn` in the file its prefix names —
1536    /// `Ui::` in `ui.rs`, `Core::` under `runtime/`, `SharedResources::`
1537    /// in `session.rs`, `Tokens::` in `tokens.rs`, `Launcher::` in the
1538    /// `kui-native` crate, and `App::` a method of that crate's `App` trait (a
1539    /// trait's `fn` is public without the word) — so a renamed or
1540    /// removed verb is a red row and not a stale one, which is the pin
1541    /// Rust's column can have without reflection.
1542    #[test]
1543    fn every_rust_spelling_is_a_public_fn() {
1544        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
1545        let read = |p: std::path::PathBuf| std::fs::read_to_string(&p).unwrap_or_default();
1546        let mut runtime = read(root.join("runtime.rs"));
1547        for dir in ["runtime", "runtime/devtools"] {
1548            for entry in std::fs::read_dir(root.join(dir)).unwrap() {
1549                let p = entry.unwrap().path();
1550                if p.extension().is_some_and(|e| e == "rs") {
1551                    runtime.push_str(&read(p));
1552                }
1553            }
1554        }
1555        let ui = read(root.join("ui.rs"));
1556        let session = read(root.join("session.rs"));
1557        let tokens = read(root.join("tokens.rs"));
1558        let launcher = read(root.join("../../kui-native/src/lib.rs"));
1559        // The `App` trait's body: a method of it is a callback the app
1560        // writes, spelled `fn name(` and public by being the trait's.
1561        let app_trait = launcher
1562            .split_once("pub trait App {")
1563            .map(|(_, rest)| rest.split_once("\n}\n").map_or(rest, |(body, _)| body))
1564            .unwrap_or_default();
1565        for d in DOORS {
1566            let (ty, name) = d.rust.split_once("::").expect(d.rust);
1567            let src = match ty {
1568                "Ui" => &ui,
1569                "Core" => &runtime,
1570                "SharedResources" => &session,
1571                "Tokens" => &tokens,
1572                "Launcher" => &launcher,
1573                "App" => app_trait,
1574                other => panic!("{}: {other} is not a prefix the table knows", d.rust),
1575            };
1576            let (public, any) = (
1577                format!("{}fn {name}(", if ty == "App" { "" } else { "pub " }),
1578                format!("fn {name}("),
1579            );
1580            assert!(
1581                src.contains(&public) || (ty == "Core" && name == "env"),
1582                "{}: no `{public}` in {ty}'s sources{}",
1583                d.rust,
1584                if src.contains(&any) {
1585                    " (a private fn is)"
1586                } else {
1587                    ""
1588                }
1589            );
1590        }
1591    }
1592
1593    /// The table is one row per verb, and a `No` says why in a sentence
1594    /// rather than in a word — the reasons are what ADR 0020 said a table
1595    /// would be made of, and the point of building one.
1596    #[test]
1597    fn rows_are_unique_and_every_no_has_a_reason() {
1598        let mut seen = std::collections::BTreeSet::new();
1599        for d in DOORS {
1600            assert!(seen.insert(d.rust), "{} is two rows", d.rust);
1601            assert!(!d.doc.is_empty(), "{} has no doc", d.rust);
1602            for (binding, cell) in [("C", d.c), ("Node", d.node), ("Lua", d.lua)] {
1603                match cell {
1604                    Is(name) => assert!(
1605                        !name.is_empty() && !name.contains(' '),
1606                        "{} in {binding}: {name:?} is not a name",
1607                        d.rust
1608                    ),
1609                    As(how) | No(how) => assert!(
1610                        how.len() >= 12,
1611                        "{} in {binding}: {how:?} is not a reason",
1612                        d.rust
1613                    ),
1614                }
1615            }
1616        }
1617    }
1618
1619    /// The C column's spellings are the header's: `kui_` and snake case.
1620    /// Node's are camelCase, optionally under one of the two classes;
1621    /// Lua's snake case. A cell in the wrong column's spelling is a pasted
1622    /// row.
1623    #[test]
1624    fn cells_are_spelled_in_their_bindings_case() {
1625        let snake = |s: &str| {
1626            s.bytes()
1627                .all(|b| b.is_ascii_lowercase() || b == b'_' || b.is_ascii_digit())
1628        };
1629        for d in DOORS {
1630            if let Is(c) = d.c {
1631                assert!(
1632                    c.starts_with("kui_") && snake(c),
1633                    "{}: C cell {c:?}",
1634                    d.rust
1635                );
1636            }
1637            if let Is(n) = d.node {
1638                let n = n
1639                    .strip_prefix("Ctx.")
1640                    .or_else(|| n.strip_prefix("KuiWindow."))
1641                    .unwrap_or(n);
1642                assert!(
1643                    !n.contains('_') && n.starts_with(|c: char| c.is_ascii_lowercase()),
1644                    "{}: Node cell {n:?}",
1645                    d.rust
1646                );
1647            }
1648            if let Is(l) = d.lua {
1649                assert!(snake(l), "{}: Lua cell {l:?}", d.rust);
1650            }
1651        }
1652    }
1653}
kui_core/schema/doors.rs

kui_core/schema/
doors.rs
