feat(packages): ludic.hints - a rail of things that are true now and can be acted on now: cards as an open registry (urgency, a glyph or an item's picture, the chip's line, three steps and how not to be here again) asked through a port whether each is true, the most urgent few once a pass in registry order within an urgency, a card opened off the rail, walked along it and put down when its subject stops being true, and "I know this" muting kept by the card's key (a key this build lacks is carried through); opened, closed, muted and unmuted as facts

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

packages/ludic.hints/card.ludic

@@ -0,0 +1,62 @@
+# card.ludic - a card read off the rail: the key opens the picked chip and puts it down, the arrows
+# walk the rail with the card up, and "I know this" mutes the card being read
+export function hints_card() -> int { return hn_card }
+
+# the key: the picked card opened, or the open one put down
+export function hints_key() -> void {
+  if hn_card >= 0 {
+    hints_close()
+    return
+  }
+  hints_open(hn_pick)
+}
+
+# the k-th chip on the rail opened as a card
+export function hints_open(k: int) -> void {
+  if k < 0 or k >= hn_n { return }
+  hn_pick = k
+  hn_card = hn_top[k]
+  hn_fact(HINTS_F_OPENED, hn_card)
+}
+
+export function hints_close() -> void {
+  if hn_card < 0 { return }
+  let c = hn_card
+  hn_card = -1
+  hn_fact(HINTS_F_CLOSED, c)
+}
+
+# the arrows, with a card up: the next chip along (d = 1) or the one before, round the ends
+export function hints_move(d: int) -> void {
+  if hn_card < 0 or hn_n <= 1 { return }
+  hints_open((hn_pick + hn_n + d) % hn_n)
+}
+
+# "I know this - do not show it again": the card off the rail until the mutes are given back
+export function hints_mute_card() -> void {
+  if hn_card < 0 { return }
+  let c = hn_card
+  hints_mute(c, true)
+  hn_card = -1
+  hn_t = 0.0
+  hn_fact(HINTS_F_MUTED, c)
+}
+
+# a step's words and its picture (n 1..3): the glyph's name, or the item (-1 when it is a glyph)
+export function hints_step_text(id: int, n: int) -> string {
+  if n == 1 { return Hints[id].s1 }
+  if n == 2 { return Hints[id].s2 }
+  return Hints[id].s3
+}
+
+export function hints_step_icon(id: int, n: int) -> string {
+  if n == 1 { return Hints[id].pic1 }
+  if n == 2 { return Hints[id].pic2 }
+  return Hints[id].pic3
+}
+
+export function hints_step_item(id: int, n: int) -> int {
+  if n == 1 { return Hints[id].item1 }
+  if n == 2 { return Hints[id].item2 }
+  return Hints[id].item3
+}