ludic ui-preview: ludic.ui components previewed for a studio over stdio (R5)

A prebuilt tool, bin/ludic-ui-preview (built by ludic-dev build, shipped beside ludic-lsp, run as
`ludic ui-preview [--font DIR]`): ludic.ui with a backend that records every draw call as a line,
and mock component classes the studio describes (load / model / calls). frame t runs ui_show at
interface time t; text is measured on the CPU with the game's font.json metrics; locale goes
through ludic.i18n; tree / box / rules inspect the frame. No game code, no GPU, no network. The wire
protocol is frozen as tools/ui-preview/protocol-v1.md; smoke.txt is a transcript to run.

ludic.ui gains, all additive: UiClass.make_of, UiBackend.said / emitted, UiRule.text / at (with
comment line breaks kept so rule lines count true, and a class's styles read under its .lss path),
and ui_root, ui_find, ui_rules_of, ui_rule_value, ui_building, ui_class, ui_class_load,
ui_file_forget, ui_errors_clear; ui_nine_cuts_into exported.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

packages/ludic.ui/act.ludic

@@ -60,6 +60,7 @@ function act_run(ui_st: mut UiState, a: UiAct, e: UiEnv) -> void {
   }
 }
 function act_emit(ui_st: mut UiState, name: string, e: UiEnv) -> void {
+  if ui_st.ui_be != null and ui_st.ui_be.emitted != null { ui_st.ui_be.emitted(name) }
   var at = e
   while at != null {
     if at.on_names != null {

packages/ludic.ui/backend.ludic

@@ -20,6 +20,8 @@ export property UiBackend {
   read: fn(string) -> string = null        # a template file's text (else Fs.read_text)
   now: fn() -> float = null                # seconds, for animation (else frames at 60 a second)
   input: bool = true               # false: take no input from Input.* (a test drives it)
+  said: fn(string) -> void = null          # a template error, for a host that reports it itself (else printed)
+  emitted: fn(string) -> void = null       # `emit name` ran, whether or not a handler took it (a host's log)
 }
 # a renderer a program installs by importing it (render3d.ludic): the first one is the backend
 property UiRenderer {

packages/ludic.ui/class.ludic

@@ -8,6 +8,7 @@ export property UiClass {
   lss_path: string = ""
   lss: string = ""
   make: fn() -> pointer = null
+  make_of: fn(UiClass) -> pointer = null   # instead of make: one constructor a host's classes share, handed the class
   renew: fn(pointer) -> void = null   # a record `make` made, put back as new: an instance mounted again
   props: fn(pointer, Val) -> void = null
   model: fn(pointer, Val) -> Val = null   # fills the object it is given (the instance keeps one)
@@ -24,6 +25,8 @@ export function ui_register(ui_st: mut UiState, k: UiClass) -> int {
   push(ui_st.uc_list, k)
   return len(ui_st.uc_list)
 }
+# the class of that name, for a host that changes a class it registered (null: none)
+export function ui_class(ui_st: UiState, name: string) -> UiClass { return uc_find(ui_st, name) }
 function uc_find(ui_st: UiState, name: string) -> UiClass {
   if ui_st.uc_list == null { return null }
   for i in 0 .. len(ui_st.uc_list) {
@@ -37,7 +40,11 @@ function uc_load(ui_st: mut UiState, k: UiClass) -> void {
   if k.root != null { return }
   let f = lib_blank(k.xml_path)
   f.src = k.xml
-  if k.lss != "" { lss_text(ui_st, f, k.lss) }
+  if k.lss != "" {
+    if k.lss_path != "" { f.path = k.lss_path }   # its rules and errors say the stylesheet they are in
+    lss_text(ui_st, f, k.lss)
+    f.path = k.xml_path
+  }
   f.sheet = sheet_of(f)
   tp_lines(ui_st, k.xml)
   let doc = Xml.parse(k.xml)

packages/ludic.ui/draw_nine.ludic

@@ -4,7 +4,7 @@
 # x0 x1 x2 x3 then y0 y1 y2 y3: the columns' and the rows' edges
 export function ui_nine_cuts(x: float, y: float, w: float, h: float, dst: float) -> []float { return ui_nine_cuts_into(new []float, x, y, w, h, dst) }
 # the same into a list the caller keeps, emptied first
-function ui_nine_cuts_into(out: []float, x: float, y: float, w: float, h: float, dst: float) -> []float {
+export function ui_nine_cuts_into(out: []float, x: float, y: float, w: float, h: float, dst: float) -> []float {
   let dx = Math.max(Math.min(dst, w / 2.0), 0.0)
   let dy = Math.max(Math.min(dst, h / 2.0), 0.0)
   List.clear(out)

packages/ludic.ui/env.ludic

@@ -81,7 +81,7 @@ export function ui_err(ui_st: mut UiState, msg0: string) -> void {
     if ui_st.ui_errs[i] == msg { return }
   }
   push(ui_st.ui_errs, msg)
-  print(`ui: {msg}`)
+  if ui_st.ui_be != null and ui_st.ui_be.said != null { ui_st.ui_be.said(msg) } else { print(`ui: {msg}`) }
 }
 function ui_has(s: string, part: string) -> bool {
   let n = len(part)

packages/ludic.ui/index.ludic

@@ -108,3 +108,4 @@ import "draw_order.ludic"
 import "draw_nine.ludic"
 import "draw_gradient.ludic"
 import "dump.ludic"
+import "inspect.ludic"

packages/ludic.ui/inspect.ludic

@@ -0,0 +1,71 @@
+# inspect.ludic - what an inspector asks of the last frame shown (ludic ui-preview, a developer's
+# tools): a screen's root, an element by id, the rules that style it, and whether a build is running
+# the root of the screen `screen` as it was last shown, or null
+export function ui_root(ui_st: UiState, screen: string) -> UiNode {
+  for i in 0 .. len(ui_st.fb_roots) {
+    if ui_st.fb_roots[i].key == screen { return ui_st.fb_roots[i] }
+  }
+  return null
+}
+# the element with that id (or key) on any screen shown, or null
+export function ui_find(ui_st: UiState, id: string) -> UiNode {
+  for i in 0 .. len(ui_st.fb_roots) {
+    let n = fb_find(ui_st.fb_roots[i], id)
+    if n != null { return n }
+  }
+  return null
+}
+# true while a frame's tree is being built (a model read), false while an action runs (a press)
+export function ui_building(ui_st: UiState) -> bool { return ui_st.uv_on }
+# the rules that match the element now, in the order the cascade applies them: the default sheet's,
+# then its file's (merged with each user's sheet for a component's root); its style="..." is not one
+@alloc_ok("an inspector's question, never a frame")
+export function ui_rules_of(ui_st: mut UiState, n: UiNode, out: []UiRule) -> void {
+  List.clear(out)
+  ir_sheet(ui_st, n, ua_sheet(ui_st), out)
+  if n.ups == null {
+    if n.sheet != null { ir_sheet(ui_st, n, n.sheet, out) }
+    return
+  }
+  let at = len(out)
+  if n.sheet != null { ir_sheet(ui_st, n, n.sheet, out) }
+  for i in 0 .. len(n.ups) {
+    if n.ups[i].sheet != null and n.ups[i].sheet != n.sheet { ir_sheet(ui_st, n, n.ups[i].sheet, out) }
+  }
+  for i in at + 1 .. len(out) {        # one order by specificity, stable, as cs_merged applies them
+    let r = out[i]
+    var j = i
+    while j > at and out[j - 1].spec > r.spec {
+      out[j] = out[j - 1]
+      j -= 1
+    }
+    out[j] = r
+  }
+}
+@alloc_ok("an inspector's question, never a frame")
+function ir_sheet(ui_st: mut UiState, n: UiNode, sh: UiSheet, out: []UiRule) -> void {
+  for i in 0 .. len(sh.rules) {
+    let r = sh.rules[i]
+    if md_ok(ui_st, r) and sel_match(ui_st, r.sel, n) { push(out, r) }
+  }
+}
+# a declaration's value as written, when it is plain text (else "" - an expression, read per element)
+export function ui_rule_value(r: UiRule, k: int) -> string {
+  let x = r.vals[k]
+  if x.op == X_LIT { return vl_text(x.v) }
+  return ""
+}
+# a class's template and styles read now (else at its first show), so a host hears their errors at once
+export function ui_class_load(ui_st: mut UiState, k: UiClass) -> void { uc_load(ui_st, k) }
+# a file read again the next time anything imports it (a host changed its text): every class too
+@alloc_ok("an inspector's edit, never a frame")
+export function ui_file_forget(ui_st: mut UiState, path: string) -> void {
+  let keep = new []UiFile
+  for i in 0 .. len(ui_st.lib_files) {
+    if ui_st.lib_files[i].path != path { push(keep, ui_st.lib_files[i]) }
+  }
+  ui_st.lib_files = keep
+  uc_invalidate(ui_st)
+}
+# every error forgotten, so each is said again the next time it is made (a host that reloads a class)
+export function ui_errors_clear(ui_st: mut UiState) -> void { List.clear(ui_st.ui_errs) }

packages/ludic.ui/instance.ludic

@@ -41,7 +41,7 @@ function in_reuse(ui_st: mut UiState, k: UiClass) -> UiInst {
   }
   let it = new UiInst
   it.cls = k
-  it.ptr = k.make()
+  if k.make_of != null { it.ptr = k.make_of(k) } else { it.ptr = k.make() }
   it.fresh = true
   return it
 }

packages/ludic.ui/style.ludic

@@ -8,6 +8,8 @@ export property UiRule {
   md: UiMedia = null            # the @media it sits in, if any
   keys: []string = null
   vals: []UiExpr = null
+  text: string = ""             # its selector as written, and where: "file.lss:12" (for an inspector)
+  at: string = ""
 }
 export property UiSheet {
   rules: []UiRule = null
@@ -31,7 +33,7 @@ function lss_file(ui_st: mut UiState, src: string, path: string) -> UiFile {
 function lss_text(ui_st: mut UiState, f: UiFile, src: string) -> void {
   let err = new []string
   let body = lss_strip(src)            # a copy of its own, unless src had no comment (then src itself)
-  lss_block(ui_st, f, body, null, err)
+  lss_block(ui_st, f, body, null, err, 1)
   if lss_has_comment(src) {            # else lss_strip handed src itself back, the caller's to keep
     unsafe { free(body) }              # every rule, selector and value read from it is a copy
   }
@@ -39,13 +41,18 @@ function lss_text(ui_st: mut UiState, f: UiFile, src: string) -> void {
   for i in 0 .. len(err) { ui_err(ui_st, `{f.path}: <style> {err[i]}`) }
   unsafe { free(err) }
 }
-# rules, @imports and @media blocks; the rules in a @media block carry its condition
-function lss_block(ui_st: mut UiState, f: UiFile, src: string, md: UiMedia, err: []string) -> void {
+# rules, @imports and @media blocks; the rules in a @media block carry its condition. `line` is the
+# line src starts on, so each rule knows where it was written (a host's inspector asks)
+function lss_block(ui_st: mut UiState, f: UiFile, src: string, md: UiMedia, err: []string, line0: int) -> void {
   let r = new UiRd
   r.s = src
+  var line = line0
+  var seen = 0
   while r.err == "" {
     rd_ws(r)
     if r.i >= len(r.s) { break }
+    line = line + lss_lines(src, seen, r.i)
+    seen = r.i
     if rd_op(r, "@import") {
       lss_import(ui_st, f, lss_upto(r, 59))
       continue
@@ -59,15 +66,16 @@ function lss_block(ui_st: mut UiState, f: UiFile, src: string, md: UiMedia, err:
     }
     if rd_op(r, "@media") {
       let cond = md_parse(lss_upto(r, 123))
+      let mline = line + lss_lines(src, seen, r.i)
       let mb = lss_upto(r, 125)
-      lss_block(ui_st, f, mb, cond, err)
+      lss_block(ui_st, f, mb, cond, err, mline)
       unsafe { free(mb) }
       continue
     }
     let sels = lss_upto(r, 123)
     let body = lss_upto(r, 125)
     let at = len(f.own)
-    lss_rule(f, sels, body, err)
+    lss_rule(f, sels, body, err, line + lss_lead(sels))
     for i in at .. len(f.own) { f.own[i].md = md }
     unsafe {                           # a rule keeps what it parsed, never the text it was sliced from
       free(sels)
@@ -77,6 +85,22 @@ function lss_block(ui_st: mut UiState, f: UiFile, src: string, md: UiMedia, err:
   if r.err != "" { push(err, r.err) }
   unsafe { free(r) }                   # the reader only: its text is the caller's
 }
+# the line breaks in src between two offsets
+function lss_lines(src: string, from: int, to: int) -> int {
+  var n = 0
+  for i in from .. to {
+    if src[i] == 10 { n += 1 }
+  }
+  return n
+}
+# the line breaks before a selector's first word (rd_ws stops at the first non-space)
+function lss_lead(s: string) -> int {
+  var n = 0
+  for i in 0 .. len(s) {
+    if s[i] == 10 { n += 1 } else if s[i] != 32 and s[i] != 9 and s[i] != 13 { return n }
+  }
+  return n
+}
 # @import "base.lss"; - its rules come before this file's own
 function lss_import(ui_st: mut UiState, f: UiFile, what: string) -> void {
   var p = tpl_words(what)
@@ -112,7 +136,13 @@ function lss_strip(src: string) -> string {
   while i < len(src) {
     if i + 1 < len(src) and src[i] == 47 and src[i + 1] == 42 {
       var j = i + 2
-      while j + 1 < len(src) and not (src[j] == 42 and src[j + 1] == 47) { j += 1 }
+      while j + 1 < len(src) and not (src[j] == 42 and src[j + 1] == 47) {
+        if src[j] == 10 {                 # a comment's line breaks stay, so a rule's line is its own
+          unsafe { p[n] = 10 }
+          n += 1
+        }
+        j += 1
+      }
       i = j + 2
     } else {
       unsafe { p[n] = src[i] }

packages/ludic.ui/style_rule.ludic

@@ -1,10 +1,10 @@
 # style_rule.ludic - a rule read, the cascade a file sees, and a node's rules applied to it
-function lss_rule(f: UiFile, sels: string, body: string, err: []string) -> void {
+function lss_rule(f: UiFile, sels: string, body: string, err: []string, line: int) -> void {
   let decls = lss_decls(body, err)
   let each = lss_split(sels, 44)
   for i in 0 .. len(each) {
     let sel = tpl_words(each[i])
-    if len(sel) > 0 { lss_rule_add(f, decls, sel, err) }
+    if len(sel) > 0 { lss_rule_add(f, decls, sel, err, line) }
     unsafe {                           # a selector keeps its parsed parts, never its text
       if not tpl_clean(each[i]) { free(sel) }
       free(each[i])
@@ -15,10 +15,12 @@ function lss_rule(f: UiFile, sels: string, body: string, err: []string) -> void
     free(decls)                        # the holder only: each rule keeps its keys and values lists
   }
 }
-function lss_rule_add(f: UiFile, decls: UiRule, sel: string, err: []string) -> void {
+function lss_rule_add(f: UiFile, decls: UiRule, sel: string, err: []string, line: int) -> void {
   let r = new UiRule
   r.keys = decls.keys
   r.vals = decls.vals
+  r.text = `{sel}`                     # a copy: the selector's text is given back below
+  r.at = `{f.path}:{line}`
   r.sel = sel_parse(sel, err)
   if r.sel != null {
     r.spec = sel_spec(r.sel)