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

kui_core/schema/
doors.rs
