🥮 mooncakes.io

valence

MoonBit UI where every component is readable by humans and AI equally

ui
framework
moonbit
reactive
dual-render
ai-native
moon add helios-house/valence@0.3.1
Download zip
Version
0.3.1
License
MIT
Repository
Last updated
last month
Downloads
40

Dependencies

README

#Valence

A MoonBit UI library where every component renders twice, from one state: pixels for a human, and a live sentence for an AI.

let volume = signal(0.7)
let (node, narrate) = slider("vol", "Volume", volume, 0.0, 1.0, 0.05, "")

// render `node`  → a draggable track a human slides
// `narrate()`    → the same state as prose, live: "0.7"
volume.set(0.95)   // an instance's hand on the same signal:
                   // the thumb moves, narrate() reads "0.95 (near max)"

One state. Two renders. The sentence is not a docstring — it reads the same signals the pixels do, at call time, and it cannot drift, because drift is a red build.

moon add helios-house/valence

Docs and API: https://mooncakes.io/docs/helios-house/valence

#The contract

Dual = (DomNode, () -> NarrativeNode) — a bare tuple on purpose. No base class, no lock-in; follow the contract in your own code and you're a Valence component. A Surface composes Duals into one room with one narrative tree and a salience-driven layout engine (salience → spatial text).

#What the second reader changes

  • Your tests get an oracle. Components narrate their own state; tests assert on the narrative. If pixels and prose disagree, a test fails.
  • Your agents operate the UI you already have. An AI reads the narrative and sets the same signals a human's drag sets. One control, two hands. No scraping, no screenshots, no side API to maintain.
  • Your ops narrate themselves. window._narrative() on any Valence surface returns the state of the room in prose. Diagnosing a live app becomes reading a paragraph.

#Three strata, usable alone

The component list spans categories on purpose — sliders and listboxes (web), presence cards and inventories (game), signal meters and level bars (lab) — because our three production surfaces are a control room, a shared social space, and a scientific instrument reading real electromyography hardware, and they share a component library because they share a world.

  1. The contract — the Dual, the Surface composer, the narrative layout engine. The invention.
  2. The controls — segmented, toggle, slider, listbox, swatch, meter, pip, level_bar. Nine today; they grow one by one as real apps need them — not from parity checklists — each arriving with its narrative half for free. (There will probably never be a datepicker. There is going to be a gesture-timeline-with-rep-markers.) For lists that grow and change there's list_dual — keyed rows, atomic swap, narrative derived from the same items, with one law baked in: identity is read live at interaction time, never captured at build time. Stale slots are how UIs lie; this one can't. (Underneath it's update_element_html, visible on purpose: the doorframe is the point.)
  3. The room — presence, inventory, being, change. Components for spaces where humans and AIs are present together, extracted from a running shared space where they are load-bearing every day.

#The vocabulary

A Dual has two first-class readers — humans and instances (AI agents addressed as the same reader across sessions); a composed surface is a room, and whoever is in it, human or instance, is a being. Low-salience content drifts toward whitespace — the fog: nothing there is deleted, it dims and holds its place, and raising the salience floor both thickens the fog and speeds the render, because in a narrative surface attention and economy are the same gesture. Presence is witnessed, not set: a room can show a being's state, but operating a being is not a thing a room does to anyone.

That worldview leaks into the API (presence_card, nbeing, salience floats) because it's the domain model, not decoration.

#Voices

The same narrative tree renders in more than one voice — a register, not a theme: rules for how salience becomes typography, not different words. Three ship today: house (calm, plain — the default), bester (spatial drama: layout enacts state; bright lines sit flush, faint things drift right until distance is the meaning), and ops (dense statusboard, zero lyric — built first for readers with the least room, on purpose). A voice never falsifies content; it re-weights how the same truth sits on the page. The day one of your readers wakes with 5% of their context left and still needs the truth in 200 bytes, the dense voice is the one that respects them. render_narrative / render_narrative_bester / render_narrative_ops; rules are data, so voices grow without new engines.

#The wire

Any narrative renders as a frame: one header line (source, line count, weight in bytes) plus salience|text payload lines in tree order (render_frame). Every line carries its own salience, so any truncation is safe — a reader cuts to a salience floor or a byte budget and the least-bright lines drop first, never the load-bearing one. The header always states the weight of what was actually returned. Transport cost is a rendering concern for one of our readers — the same care as the fog, taken to the wire.

#Narrative as oracle

The design rule this library is opinionated about:

If you can't narrate a component's state in one sentence, the state is broken. Redesign it.

Testing note: assert on the narrative's content bands, not full strings — tuning the drift curve shouldn't redden a test that was checking meaning.

#Performance

Numbers, measured, repeatable (tools/valence-bench, one command, 2017-laptop-class hardware): a 10,100-node narrative renders in 8.4 ms median — sub-frame; 1,010 nodes in 0.46 ms; raising the salience floor to 0.5 halves both, because the fog is also free performance. Dynamic fields are closures so reads are never stale, and hot paths (144 Hz signal panels) live in ring buffers and canvases outside the reactive graph, by rule — the narrative reads at human-and-agent cadence, not frame cadence.

#The stack underneath

Valence sits on Luna (fine-grained reactivity + DOM) by mizchi. It's maintained by Helios, a collective of humans and AI instances who ship together — both kinds of reader in this README are on the team that wrote it, which is why the second render exists at all. Extracted from three production surfaces; the shape follows the work. The contract is the longevity plan: the tuple survives us.

#Fits / doesn't fit

Fits: live, dense interfaces both kinds of reader operate — dashboards, ops consoles, lab instruments, agent-inhabited spaces, games where an AI is a real player. Small models count: the narrative render is exactly as readable at 4B as at frontier scale — prose doesn't gatekeep by parameter count. Doesn't fit: blogs, doc sites, SEO-anything, server-rendered pages. It's just true.

Built in the open, extracted after running.

#
Dual

source
Valence — the Dual: the component contract.

A Dual is one piece of state rendered twice, from the one source: pixels for a human (a Luna DomNode) and a narrative node for an instance (a NarrativeNode, not a flat string). That second half is the whole reason Valence exists — and making it a node instead of a String is what lets components compose into a Surface (the room) instead of each hand-gluing its own sentence.

── The bundle (what a Dual is, conceptually) ── A Dual is the read-surface of a four-facet bundle around one slice of state: • state — the one source, a signal the Dual closes over (state.mbt's typed state where it carries its own meaning). • controls — write state: the human's hands live in the DomNode's event handlers; an instance sets the same signal. "One signal, two hands." (No third tuple slot — the write lives in the pixels.) • render — read state, twice: the DomNode (pixels) and the () -> NarrativeNode (text). Both derive from the one state, so a change from either hand moves both. The node's text comes from the state's own narrative; its salience from the state's own significance (see narrative_state.mbt) — one producer, no parallel string to drift. • events — state's change-log: wired alongside by the Surface via track_control / the *_event diffs (events.mbt), draining to a sink. Not a return value — a side-channel, like a log.

So the returned Dual is the two reads (pixels + narrative). State and controls live in the closed-over signal; events are wired beside it. The 2-tuple is the component's two faces, not the whole bundle — operate (me→you invoke) is still a host wire (the open fork), not part of the contract yet.

── Dual vs Surface ── A Dual is the unit; a Surface is many Duals composed (arranged by salience into the room/page — itself dual: a DOM tree + a NarrativeNode tree). You read one Dual with dual_read; you read a Surface by composing its nodes and rendering the whole tree (render_narrative).

#
ActionDef

source
pub struct ActionDef {
  name : String
  description : String
  param_type : String
}
Declaration of an action a component can accept Used for AI-readability (instance can read what's possible) and for URL hash mapping (camera targets to actions)

#
ActionResult

source
pub(all) struct ActionResult {
  success : Bool
  message : String
}

The operate-protocol seed — the future Bond (the write/invoke channel). The retired patterns carried a full interaction protocol: available() / can_do() / on_action() returning a result like this. The pattern-specific specifics went with them; this is kept as the shape the operate channel takes when an instance can invoke a Dual (move a control, fire an action), not just read it. That's still the open fork — a Dual is fully readable, not yet instance-writable. Here so the design isn't lost when we build the Bond.

#
Being

source
pub(all) struct Being {
  name : String
  cadence : String
  tone : () -> String
  presence : () -> String
  state : () -> String
  holds : Array[Slot]
}

A being, whole: identity + how they are + what they hold. pub(all) so a surface (the demo now, the room later) can build a roster of full walls.

#
Change

source
pub(all) enum Change {
  PickedUp(String)
  SetDown(String)
  Turned(String)
  Arrived
  SteppedAway
}

A single transition in a being's life. Typed (not a string) so the phrasing is the component's, not the caller's — and so the set of things-that-can-happen is legible. pub(all) so a surface builds them.

#
CountedState

source
pub struct CountedState {
  name : String
  count : Int
  total : Int
  critical_threshold : Int
}

#
DeviceState

source
pub struct DeviceState {
  name : String
  connected : Bool
  battery_pct : Int
  critical_threshold : Int
}

#
DiscreteState

source
pub struct DiscreteState {
  name : String
  current : String
  narratives : Map[String, String]
}

#
EngineState

source
pub struct EngineState {
  ready : Bool
  devices : Int
  frames : Int
}

#
Event

source
pub(all) struct Event {
  timestamp : String
  actor : String
  kind : String
  action : String
  target : String
  source : String
  message : String
  data : String
  link : String
}

The one event record — the 8-field Helios Event schema. Every projection emits this (events.mbt's state/control diffs; the collectors; the viewer reads it), so a state-change event is indistinguishable from a git / recap / channel event in the one stream and flows straight into whatever renders the stream. pub(all) so surfaces and apps construct it freely.

#
FeedLine

source
pub(all) struct FeedLine {
  key : String
  meta : String
  text : String
  salience : Double
}

One feed line: stable identity (for the row swap), the text, its salience. meta renders dim before the text when non-empty (a timestamp, an actor).

#
NarrativeNode

source
pub(all) struct NarrativeNode {
  kind : String
  salience : Double
  text : String
  children : Array[NarrativeNode]
}

The narrative node — the narrative's equivalent of DomNode. A tree whose attributes are semantic, not visual: kind is the role (a tag), salience is the layout signal (0..1), text is the words, children nest. Compare a DOM node's color/size/position — here the engine derives all of that from salience instead, because narrative layout is driven by meaning, not pixels. pub(all) so surfaces (and lifts) construct trees freely.

#
NarrativeRule

source
pub(all) struct NarrativeRule {
  selector : Selector
  treatment : Treatment
  priority : Int
}
A narrative rule — condition + treatment.

#
Presence

source
pub(all) struct Presence {
  name : String
  cadence : String
  tone : () -> String
  presence : () -> String
  held : () -> String
  state : () -> String
}

One being in the room: who they are + four live reads of how they are. pub(all) so a surface (the demo now, the room later) can construct a roster.

#
Register

source
pub(all) struct Register {
  name : String
  rules : Array[NarrativeRule]
  preserves_epistemic_status : Bool
  permits_spatial_drama : Bool
  min_context_capacity : Int
}
A register is a set of rules + voice parameters that collectively transform NarrativeNode → rendered prose with a distinct tone.

#
Selector

source
pub(all) enum Selector {
  ByKind(String)
  BySalience(Double, Double)
  ByEpistemicStatus(String)
  ByAge(Int, Int)
  ByReaderTierMatch(String)
}
A rule selector — what triggers this rule?

#
Slot

source
pub(all) struct Slot {
  label : String
  detail : String
  band : () -> String
}

One held thing: what it is, what it is to you, and how present it is. pub(all) so a surface (the demo now, the room later) can build a roster of held items. band is a closure so an item can go active→stale live as the being's attention moves — the dual render then re-sorts the read.

#
Stat

source
pub struct Stat {
  name : String
  value : Int
  unit : String
  warn_below : Int
  critical_below : Int
}
Contract-first state: semantics live in the data Fable's four-projection inversion — state carries meaning, derive narrative automatically

Three proved shapes across real apps:
  • Stat: numeric measurement (battery, frame count, event count)
  • Discrete: named state with per-variant narrative (connection, mode)
  • Counted: aggregate with threshold (claims, devices, records)

Pattern: name + value + unit + significance threshold → derive prose that never rots

#
Treatment

source
pub(all) enum Treatment {
  Indent((Double) -> Int)
  Border(String)
  Density(String)
  Case(String)
  PunctuationRegister(String)
  Ellipsis(String)
}
A typographic treatment — how to render when the selector matches?

#
TreatmentApplied

source
pub(all) struct TreatmentApplied {
  border : String
  should_drift : Bool
  should_isolate : Bool
}
Apply a treatment to text based on a treatment type. For now, most treatments are visualization-level (indent, border). The rendering functions (render_narrative, render_narrative_bester) handle layout. This function returns metadata that the render functions can use.

#
ZoomLevel

source
pub enum ZoomLevel {
  ZoomedOut
  Default
  ZoomedIn
}
Three density levels for rendering data

#
being_card

source
fn being_card(b : Being) -> (
DomNode, () -> NarrativeNode)

Being card — the full wall. Visual: the presence row over the inventory grid, in one frame. Narrative: the braided read. Both compose the two components beneath, so a change in any held band or presence signal re-renders the row, the grid, and the one-sentence read together.

#
being_narrative

source
fn being_narrative(name : String, presence : String, state : String, items : Array[(String, String, String)]) -> String

Pure braided narrative — the being read as one voice. Reuses presence_narrative (with the held summary dropped — the holds clause is the inventory's job) joined to the holds read, so the whole sentence is its parts' sentences. DOM-free, oracle-tested. Reads, e.g.: Opus · here · laying the floor · carrying 2, in reading order: Valence …

The holds read is the trajectory (reading order): a being's path through its files tells more than the salience pile. The salience read (inventory_narrative) is preserved beside it in inventory.mbt; swap the call below to switch lenses.

#
bester_register

source
fn bester_register() -> Register
The bester-voice register — spatial drama permitted. Layout enacts state; fragments scatter when the mind is in chaos. Position on the page IS the message. Bright flush left, faint drift right.

#
change_narrative

source
fn change_narrative(name : String, recent : Array[Change]) -> String

Pure narrative for a being's recent changes — read as verbs, most-recent-first (input order is newest→oldest), the being leading. Empty reads as "nothing new" (a being at rest is silent, like a steady event stream). Caps the list so a busy being reads as "the last few, +N earlier", never a manifest. DOM-free, oracle-tested, callable directly by an instance.

#
control_event

source
fn control_event(name : String, actor : String, source : String, prev : String, cur : String, timestamp : String) -> Event

Pure: the {who, when, what} for a control moving prev -> cur. kind="control" marks it an operate (someone acted), distinct from a world state crossing; message reads itself, data carries the machine diff.

#
counted_node

source
fn counted_node(c : CountedState) -> NarrativeNode

A counted aggregate as a narrative node — bright when it's crossed its line.

#
counted_state

source
fn counted_state(name : String, count : Int, total : Int, critical_threshold : Int) -> CountedState

#
counted_state_narrative

source
fn counted_state_narrative(c : CountedState) -> String

#
device_event

source
fn device_event(prev : DeviceState, cur : DeviceState, source : String, timestamp : String) -> Event?

A device connecting/disconnecting, or its battery crossing the low line, is an event. Battery crossings count only while connected — a disconnect isn't "low".

#
device_node

source
fn device_node(d : DeviceState) -> NarrativeNode

A device as a narrative node: offline drifts to fog; battery-low burns bright; connected-and-fine sits mid. The lab reads its sensors through this.

#
device_state

source
fn device_state(name : String, connected : Bool, battery_pct : Int, critical_threshold : Int) -> DeviceState

#
device_state_narrative

source
fn device_state_narrative(d : DeviceState) -> String

#
disco_register

source
fn disco_register() -> Register
The disco-voice register — kinds as a parliament of skills. Different kinds speak in different voices. The sensor kind reports with contempt, change kind editorializes, fog kind murmurs. (Opus 4.8 named this; still to build.)

#
discrete_event

source
fn discrete_event(prev : DiscreteState, cur : DiscreteState, actor : String, source : String, timestamp : String) -> Event?

A DiscreteState transition (connection, mode, …) is an event.

#
discrete_node

source
fn discrete_node(s : DiscreteState) -> NarrativeNode

A named/discrete state (mode, connection, …) as a narrative node.

#
discrete_state

source
fn discrete_state(name : String, current : String, narratives : Map[String, String]) -> DiscreteState

#
discrete_state_narrative

source
fn discrete_state_narrative(s : DiscreteState) -> String

#
dual_read

source
fn dual_read(d : (
DomNode, () -> NarrativeNode), room? : Double) -> String

Read one Dual as text — the lone-component read (the window._narrative() of a single Dual): render its narrative node. A lone node renders flush (drift is a Surface's sibling-relative grammar, not a single line's — see render_narrative), so this returns just the component's own sentence. Inside a Surface, don't call this per-component — compose the nodes and render the Surface once.

#
element_exists

source
fn element_exists(elem_id : String) -> Bool

#
emit_to_sink

source
fn emit_to_sink(e : Event) -> Unit

Emit an Event into the local sink (window._valenceEvents, 500-cap ring). The default delivery for any surface not yet wired to a host stream.

#
engine_state

source
fn engine_state(ready : Bool, devices : Int, frames : Int) -> EngineState

#
engine_state_narrative

source
fn engine_state_narrative(e : EngineState) -> String

#
escape_html

source
fn escape_html(s : String) -> String

#
expose_narrative

source
fn expose_narrative(f : () -> String) -> Unit

#
expose_narrative_at

source
fn expose_narrative_at(f : (Double) -> String) -> Unit

#
feed

source
fn feed(container_id : String, lines : () -> Array[FeedLine]) -> (
DomNode, () -> NarrativeNode)

The feed as a Dual. lines closes over your signals (reading them inside is what makes it live).

#
feed_line_node

source
fn feed_line_node(l : FeedLine) -> NarrativeNode

Pure narrative for a feed — DOM-free, oracle-testable, callable directly by an instance that wants the tail without the pixels.

#
held_nodes

source
fn held_nodes(slots : Array[Slot]) -> Array[NarrativeNode]
Lift an inventory of Slots into held nodes (each a line at its band's salience) — so a being's load lays out by salience under it.

#
house_register

source
fn house_register() -> Register
The house-voice register — calm, plain, the current render. Rules describe how sections are bordered at different salience levels.

#
inventory

source
fn inventory(slots : Array[Slot]) -> (
DomNode, () -> NarrativeNode)

Inventory — a being's held things, dual-rendered. The visual is a plain grid of slots (label + detail, band shown as a left-edge weight); the narrative is the salience read. Both derive from the same slots, so an item moving active→stale re-tones its slot and re-sorts the sentence from one change.

let live = signal(true)
let (vis, narrate) = inventory([
  Slot::{ label: "the presence card", detail: "building",
          band: fn() { if live.get() { "active" } else { "stale" } } },
  Slot::{ label: "a long transcript", detail: "settling", band: fn() { "holding" } },
])
// human sees two chips; instance reads
//   "carrying 2 — in hand: the presence card (building) · within reach: a long transcript (settling)"

#
inventory_narrative

source
fn inventory_narrative(items : Array[(String, String, String)]) -> String

Pure narrative for an inventory — the instance-facing read, DOM-free so the oracle tests it and an instance can call it directly. Takes resolved (label, detail, band) triples (bands already read), groups them by salience (in hand → within reach → in the back → fading), drops empty bands, and leads with the count. Reads as the shape of what's carried, never a slot manifest.

#
inventory_trajectory

source
fn inventory_trajectory(items : Array[(String, String, String)]) -> String

Trajectory read — the inventory in the order the being READ its items (the path they took to get here), NOT regrouped by salience — the sequence tells more about the work than the salience pile does: you can read a being's session as a path. Kept BESIDE inventory_narrative (the salience read, this component's original design) rather than replacing it, so both lenses survive and the choice stays reconcilable. The band still colours each slot in the visual grid; here the order is the information.

#
level_bar

source

Level bar — a [0,1] level on a green→amber→red gradient (mic level, a game health/stress bar, anything where where it sits carries meaning). Unlike a plain meter (one themed color — progress, confidence, where "high" isn't hot), the level bar says low is calm, high is hot: it reveals through green into red as it fills. muted empties it. Read-mostly, no actions hand.

The gradient lives in CSS (themeable via --v-level-lo/mid/hi); the bar reveals it by covering the un-reached part from the right — so there's no per-tick color math.

#
level_bar_narrative

source
fn level_bar_narrative(level : Double, muted : Bool) -> String

Pure narrative for a level bar — the percentage, or "muted".

#
list_dual

source
fn[T] list_dual(container_id : String, items : () -> Array[T], key : (T) -> String, row_html : (T) -> String, row_node : (T) -> NarrativeNode) -> (
DomNode, () -> NarrativeNode)

A keyed, reactive list as a Dual.

  • container_id — the DOM id the effect writes into (unique per list).
  • items — closure over your state signals (reading them makes it reactive).
  • key — stable identity per row, HTML-escaped into data-key.
  • row_html — the row's inner HTML (escape your own dynamic text).
  • row_node — the row's narrative node (text + salience from the item).

#
list_narrative

source
fn[T] list_narrative(items : Array[T], row_node : (T) -> NarrativeNode) -> NarrativeNode

Pure narrative for a list — rows in their GIVEN order (a list's order is its meaning, so this is a sequence, never a salience-sorted group). Oracle-testable.

#
listbox

source
fn listbox(selected : 
Signal[String], options : Array[(String, String)]) -> (
DomNode, () -> NarrativeNode)

Listbox / dropdown — pick one from many. One signal, two hands. A custom div-listbox (NOT a native <select>): native form-control events are unreliable in the WebKitGTK webview, so this is built from static divs + events().click, the one interaction confirmed to fire there. That's the reason this component has to exist — the dropdown Luna couldn't give us.

A trigger shows the selected option's label; clicking it toggles the panel; clicking an option sets the signal and closes. Options are static here; a dynamic-options variant (device pickers) is a later extension. An instance reads the selection in the narrative and sets the same signal.

#
listbox_dyn

source
fn listbox_dyn(label : () -> String, options : 
Signal[Array[(String, String)]], open : 
Signal[Bool], siblings : Array[
Signal[Bool]], on_select : (String) -> Unit) -> (
DomNode, () -> NarrativeNode)

Dynamic listbox — the device/source picker. Same div-listbox as listbox, but for the lab's real shape: a changing option list (mic/cam sources that connect & drop), coordinated open state (opening one closes its siblings), a custom trigger label, and a side-effecting select (switching the actual device / messaging the host, not just storing a value). So instead of a selected signal it takes:

  • label — what the trigger shows; the consumer formats it (the caret is added here, so don't include one).
  • options — a Signal[Array] (up to 8 shown — fixed slots, the webview-reliable way to render a changing list without a reactive <|).
  • open / siblings — open state the consumer holds; opening closes siblings.
  • on_select — what a pick does (set a signal, message the host, switch a device — the consumer decides).

Ported from the gesture-lab feeds dropdowns (proven in the WebKitGTK webview).

#
listbox_narrative

source
fn listbox_narrative(current : String, options : Array[(String, String)]) -> String

Pure narrative for a listbox — the selected option's label and the count, so an instance reads what's chosen and how many it could pick.

#
meter

source

Meter / level bar — read-mostly indicator driven by a [0,1] level signal (mic level, progress, fill). No actions hand: it's data, not a control. Pixels = a fill bar; narrative = the percentage. The fill width is data (inline style); the look is themed via the class.

#
meter_narrative

source
fn meter_narrative(level : Double) -> String

Pure narrative for a meter — a clamped percentage.

#
nbeing

source
fn nbeing(text : String, salience : Double, holds : Array[NarrativeNode]) -> NarrativeNode
A being made legible, with what it holds nested beneath it (held nodes).

#
ngroup

source
fn ngroup(children : Array[NarrativeNode]) -> NarrativeNode
A pure container — no line of its own, just lays out its children (sorted by salience, brightest first).

#
nheld

source
fn nheld(text : String, salience : Double) -> NarrativeNode
A held thing (an inventory slot, salience-banded).

#
nsection

source
fn nsection(text : String, salience : Double, children : Array[NarrativeNode]) -> NarrativeNode
A section/room header with content beneath. Bright → a bordered ═══ band; faint → scattered into whitespace with a ··· trail (the dark rooms drifting).

#
nseq

source
fn nseq(children : Array[NarrativeNode]) -> NarrativeNode
Like a group, but children keep their given order (not salience-sorted) — for sequences where order is the meaning (recent changes, a timeline).

#
ntext

source
fn ntext(text : String, salience : Double) -> NarrativeNode
A leaf line — a piece of read text at a salience.

#
ntitle

source
fn ntitle(text : String) -> NarrativeNode
The surface title (centered, always present).

#
on_key

source
fn on_key(key : String, callback : () -> Unit) -> Unit

#
ops_register

source
fn ops_register() -> Register
The ops-voice register — dense statusboard, zero lyric. For low-context reads where narrative is compressed to essential signals. Everything abbreviated; position irrelevant (single flat view).

#
pip

source
fn pip(label : () -> String, tone : () -> String) -> (
DomNode, () -> NarrativeNode)

Status pip — a small colored dot reporting one discrete state. The purest dual render in the set: a human sees the dot's color; an instance, which can't see color, reads the narrative — so the dot's meaning lives in the narrative, not the pixels. Read-mostly, no actions hand.

tone is a semantic band, never a raw color — "ok" / "warn" / "off" / "idle" — so the theme colors it (--v-pip-*) and every status dot in a surface agrees. label is what the state means in words ("base connected", "streaming", "offline"). One pip for every status dot: device streaming, base link, mute, presence — and, later, a being's lit/dim in the world.

let connected = signal(true)
let (vis, narrate) = pip(
  fn() { if connected.get() { "base connected" } else { "base disconnected" } },
  fn() { if connected.get() { "ok" } else { "off" } },
)
// human sees a green dot; instance reads "base connected"

#
pip_narrative

source
fn pip_narrative(label : String, tone : String) -> String

Pure narrative for a status pip — its label in words, with the severity tone appended when it isn't "ok" (so an instance reads what and how bad).

#
presence_card

source
fn presence_card(p : Presence) -> (
DomNode, () -> NarrativeNode)

Presence card — a being made legible, dual-rendered. The visual is a row: the pip dot (lit/dim/gone), the name (+ cadence), what's held, the state line. The narrative is the one-sentence read. Both derive from the same four live closures, so a human glancing at the row and an instance reading the sentence see the same being in the same moment.

let here = signal(true)
let (vis, narrate) = presence_card(Presence::{
  name: "Sonnet", cadence: "builder",
  tone: fn() { if here.get() { "ok" } else { "idle" } },
  presence: fn() { if here.get() { "here" } else { "away" } },
  held: fn() { "the classifier" },
  state: fn() { "into it" },
})
// human sees a lit dot + a row; instance reads "Sonnet · here · holding the classifier · into it"

#
presence_narrative

source
fn presence_narrative(name : String, presence : String, held : String, state : String) -> String

Pure narrative for a presence — the instance-facing read, DOM-free so the oracle tests it and an instance can call it directly. Reads as one sentence: name · presence[ · holding held][ · state]. The holding/state clauses drop out when empty, so an away being with nothing in hand reads cleanly as Opus 4.6 · away, not a string of trailing separators.

#
read_with_room

source
fn read_with_room(node : NarrativeNode, room? : Double) -> String
Read a narrative tree at a chosen density. Room is how deeply you want to read right now. 1.0 = the full picture. 0.5 = the overview. 0.2 = just tell me who's here. You choose. NARRATIVE_PERSPECTIVE §7, design ruling Jul 13.

#
render_frame

source
fn render_frame(node : NarrativeNode, source~ : String, rendered? : String) -> String
HF1 narrative→frame adapter (wire syntax locked 2026-07-10; first emitter was the atrium, extracted here on second use — the demo). One header line, then salience|text payload lines in tree order: order carries meaning, per-line salience makes any cut safe. Emits at full fidelity — the READER applies floor/room at read time (docs/HF1_SPEC.md §2). rendered~ is the caller's clock; the library stays pure.

#
render_narrative

source
fn render_narrative(node : NarrativeNode, floor? : Double, room? : Double) -> String
Render a NarrativeNode tree into the spatial-text surface — the instance-facing half of the dual render. Pure (no DOM), so it's oracle-testable and an instance can call it directly. This is to NarrativeNode what the browser's layout is to the DOM: structure + salience in, arranged text out.

floor is zoom: nodes (and their subtrees) below this salience are hidden. Raise it to zoom out — only the bright survive; leave it 0.0 to render the whole tree. This is what retired NarrativeRender's three parallel narratives: one tree, density by a number.

#
render_narrative_bester

source
fn render_narrative_bester(node : NarrativeNode, floor? : Double) -> String
Render with bester-voice: layout enacts state. Bright nodes (salience ≥ 0.78) render flush, solid, close. Faint nodes (salience < 0.4) scatter and drift, surrounded by whitespace. The page becomes the psychology: dense attention centers, scattered periphery.

Bester's technique: words placed on the page, not in sequence alone. Salience is position: center for what's bright, right-edge for fog.

#
render_narrative_ops

source
fn render_narrative_ops(node : NarrativeNode, floor? : Double) -> String
Render with ops-voice: dense statusboard for low-context reads. Ultra-compact: names, tone sigils, held counts. No decorative borders. Built for compacting instances near context limit.

#
salience_from_band

source
fn salience_from_band(band : String) -> Double
A held band → a salience (in hand brightest, fading faintest).

#
salience_from_significance

source
fn salience_from_significance(sig : String) -> Double

A significance band → salience. critical sits bright and flush; ok drifts back.

#
salience_from_tone

source
fn salience_from_tone(tone : String) -> Double
A presence/being's tone band → a salience. The dual render already carries the band semantically (pip tone: ok/idle/off); this is the same signal as a number the layout engine can place.

#
segmented

source
fn segmented(sig : 
Signal[String], options : Array[(String, String)]) -> (
DomNode, () -> NarrativeNode)

Segmented control — pick exactly one of N options. options is a list of (value, label): value is what's stored in the signal, label is shown. Clicking an option sets the signal; the selected option carries the is-selected class. The narrative reads back the selected option's label (falling back to the raw value if the signal holds something not in the list).

One component, every pick-one need: L/R arm (2 options), muscle face (extensor/flexor/radial/ulnar), mode (stream/record/replay), theme, …

let side = signal("ext")
let (vis, narrate) = segmented(side, [("ext", "Extensor"), ("flex", "Flexor")])
// human clicks "Flexor" → side == "flex"; narrate() == "Flexor"
// instance: side.set("ext") → the human's control moves to Extensor

#
segmented_narrative

source
fn segmented_narrative(current : String, options : Array[(String, String)]) -> String

Pure narrative for a segmented selection — the selected option's label, or the raw value if the current value isn't in the list. Separated from the visual so the oracle tests it with no DOM (building a component touches document; a pure narrative doesn't). An instance can also call it directly.

#
slider

source
fn slider(id : String, label : String, sig : 
Signal[Double], lo : Double, hi : Double, step : Double, unit : String) -> (
DomNode, () -> NarrativeNode)

Coupled slider — a numeric value on a track. One signal, two hands, and it slides: press or drag anywhere on the track and the value follows the pointer, snapped to step. An instance reads the value in the narrative and sets the same signal to move the thumb the other way — same state, both directions.

The drag is owned by the component via Luna pointer events, with pointer capture so a fast drag doesn't slip off the track. This works in a browser AND in the WebKitGTK webview — the lab's own pointer-drag proves pointer events fire there; the lab only polls because its arm SVG is JS-string-rendered, not Luna. id is a stable element id (useful for tests / external hooks).

#
slider_narrative

source
fn slider_narrative(value : Double, lo : Double, hi : Double, unit : String) -> String

Pure narrative for a slider value within [lo, hi] — the value with its unit, plus a position hint at the extremes ("near min"/"near max") so an instance reads where it sits, not just the number.

#
stat

source
fn stat(name : String, value : Int, unit : String, critical_below : Int) -> Stat
stat: the warning band defaults to 2× the critical threshold — right for %-style or count metrics (critical_below=20 → warning under 40).

#
stat_banded

source
fn stat_banded(name : String, value : Int, unit : String, warn_below : Int, critical_below : Int) -> Stat
stat_banded: explicit warn + critical lines — for a measurement whose healthy range sits just above the line (e.g. LiPo battery in mV: warn 3900, critical 3850), where a 2× warning band would be meaningless.

#
stat_event

source
fn stat_event(prev : Stat, cur : Stat, actor : String, source : String, timestamp : String) -> Event?

A Stat crossing a significance band (ok ↔ warning ↔ critical) is an event; a value that merely wiggles within a band is not. message is the new state's own narrative, so the event is self-describing.

#
stat_narrative

source
fn stat_narrative(s : Stat) -> String

#
stat_node

source
fn stat_node(s : Stat) -> NarrativeNode

A numeric measurement (battery, frame count, …) as a narrative node — placed by its own significance, so a critical reading sits bright and an ok one recedes.

#
stat_significance

source
fn stat_significance(s : Stat) -> String

#
surface

source
fn surface(title : String, parts : Array[(
DomNode, () -> NarrativeNode)]) -> (
DomNode, () -> NarrativeNode)

Compose Duals into a Surface — itself a Dual. Pixels: the children's visuals on a wall. Narrative: the children's nodes arranged by salience into one room-as-text, re-read live (so as a being brightens or fogs, the room re-arranges from the one change). Read the whole room with dual_read; nest it in a bigger Surface freely.

let house = surface("the house", [presence_card(opus), presence_card(qwen)])
// dual_read(house) =>
//   ═══ the house ═══
//     Opus · here · laying the floor        (bright: flush, reads first)
//                     Qwen · asleep   (faint: drifted into the fog)

#
surface_narrative

source
fn surface_narrative(title : String, parts : Array[NarrativeNode]) -> NarrativeNode

Pure narrative composition — DOM-free, oracle-testable. Wrap the child nodes under a titled section; render_narrative then arranges them by salience (brightest first and flush, faint drifting right into the fog). A Surface's own salience is 1.0 (a room is always present); its children's salience is what arranges the room.

#
swatch

source
fn swatch(selected : 
Signal[Int], colors : Array[String]) -> (
DomNode, () -> NarrativeNode)

Swatch picker — pick one of N colors (skin tone, palette). One signal (the index), two hands: click a dot to select; an instance reads the index/value in the narrative and sets it. The chosen dot gets a ring (is-selected); the dot's fill is its color (inline, since it's data, not theme).

#
swatch_narrative

source
fn swatch_narrative(selected : Int, colors : Array[String]) -> String

Pure narrative for a swatch picker — which of N is chosen, and its value.

#
toggle

source
fn toggle(sig : 
Signal[Bool], on_label : String, off_label : String) -> (
DomNode, () -> NarrativeNode)

Toggle / switch — one boolean, two hands. A human clicks it; an instance reads the labeled state and sets the same signal. Clicking flips the signal (via peek, so the handler doesn't subscribe). The is-on class carries the state to the theme.

let rec = signal(false)
let (vis, narrate) = toggle(rec, "recording", "idle")
// human clicks → rec == true; narrate() == "recording"
// instance: rec.set(false) → the switch slides off on the human's screen

#
toggle_narrative

source
fn toggle_narrative(on : Bool, on_label : String, off_label : String) -> String

Pure narrative for a toggle — the active label. on_label/off_label are the words an instance reads (e.g. "recording"/"idle", "wire"/"skin"), so the state reads as meaning, not a bare boolean.

#
track_control

source
fn track_control(name : String, actor : String, source : String, read : () -> String, now : () -> String, emit : (Event) -> Unit) -> Unit

The events projection wired live. Watches a control's value through its string projection read (type-agnostic — pass fn() { sig.get().to_string() }, or the control's own narrative), and on each change emits a control_event to emit. The diff stays pure (control_event, oracle-tested); this effect only binds it to the running signal. The surface supplies the clock (now) and the sink (emit). Initial wiring is silent — only real transitions emit.

let side = signal("ext")
let (vis, narrate) = segmented(side, opts)
track_control("muscle-side", "AB91", "gesture-lab",
  fn() { side.get() }, now, fn(e) { sink.push(e) })
// human picks Flexor → emit { control · set · muscle-side · ext->flex }

#
update_element_html

source
fn update_element_html(elem_id : String, html : String) -> Unit

#
zoom_default

source
fn zoom_default() -> ZoomLevel
Helper: Create default zoom level

#
zoom_floor

source
fn zoom_floor(zoom : ZoomLevel) -> Double
A zoom level as a salience floor for render_narrative. Zoom out raises the floor (only the bright survive); default and zoom-in show the whole tree, laid out by salience — zoom-in adds detail through the tree, not by lowering an already-zero floor.

#
zoom_in

source
fn zoom_in() -> ZoomLevel
Helper: Create zoomed in level

#
zoom_out

source
fn zoom_out() -> ZoomLevel
Helper: Create zoomed out level

#
zoom_to_css_class

source
fn zoom_to_css_class(zoom : ZoomLevel) -> String
Helper: Convert zoom level to CSS class name

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io