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

kui_core/schema/
doors.rs
