@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.21

package/scripts/lib/intent_screen.rb

@@ -0,0 +1,309 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+# IntentScreen (intent 316) - fills templates/intent-screen.md from one intent's
+# record: the intent file, the tier's INDEX.md, savepoint.md and checklist.md.
+# Every number on the screen comes from here so the session never writes one by
+# eye. Pure: explicit paths in, a Markdown string out; no ENV, no Dir.pwd.
+#
+# Intent 316a fixed three defects the field code inherited into both the plain
+# renderer and the ANSI renderer (scripts/lib/intent_screen_ansi.rb): the
+# Insight row dumping a multi-clause remainder into the note column, an empty
+# "What this means" heading rendering bold with nothing under it, and step
+# text cut mid-sentence. `step_text`, `insight_fields` and `next_fields` are
+# public so the ANSI renderer reuses the exact same trims (D3) rather than
+# re-deriving them and drifting.
+#
+# Harness-agnostic core: no harness assumption lives here.
+module IntentScreen
+  BAR_WIDTH = 20
+  ON = "█"
+  OFF = "░"
+  PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
+  SECTIONS = %w[Active Future Completed Abandoned].freeze
+  ITEM_RE = /^\s*- \[([ xX])\]\s+(.*)$/
+  # Em dash and en dash added (intent 316a O1e): a checklist item written
+  # "S1 — text" (the em dash every checklist this intent writes, and the one a
+  # reviewer reads, uses) kept its prefix under the old character class and
+  # rendered "S1  [ open ]  S1 — text" on screen. Intent 317a (A1) made the
+  # separator optional with required whitespace: "S1 text" (the shape real
+  # checklists use) kept its label and doubled in next_fields; a bare "S1"
+  # has no following text and stays prose.
+  STEP_PREFIX_RE = /\A(?:Step|S)\s*\d+\s*(?:[-:·—–]\s*|\s+)(?=\S)/i
+  INSIGHT_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s+·\s+\S+\s+·\s+.+?\s+—\s+(.+)\z/
+  SAVEPOINT_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s{2,}(\S+)\s{2,}(.+?)\s*\z/
+  # Intent 317, D6: field-2 tokens that are genuine lifecycle stages. A ledger
+  # can also carry non-lifecycle lines (`Lock  takeover: ...`, and 317's own
+  # `Review`/`Commit`); those must never be mistaken for the current stage.
+  # Placed here, clear of STEP_PREFIX_RE above (316a edits that one).
+  LIFECYCLE_STAGES = %w[What Why How Exec Done].freeze
+
+  # True iff a raw savepoint ledger line's field 2 is a genuine lifecycle
+  # stage (post-execution-review finding 5: centralizes what spawn-preamble
+  # and agent-report used to each copy-paste beside the constant above).
+  def self.lifecycle_line?(line)
+    parts = line.to_s.split(/\s{2,}/)
+    parts.length >= 2 && LIFECYCLE_STAGES.include?(parts[1])
+  end
+
+  # Word-boundary truncation caps (intent 316a D3/O1a/O1c). Never a clause
+  # trim: a clause trim on step text destroys a pinned `OPEN:` row
+  # (test/intent_screen_test.rb:171-178) that a mid-sentence cut would eat.
+  INSIGHT_VALUE_MAX = 72
+  INSIGHT_NOTE_MAX = 96
+  NEXT_VALUE_MAX = 72
+  STEP_TEXT_MAX = 110
+
+  # Where a resume lands, from the ledger's last line (the boarding matrix).
+  def self.landing_stage(stage, milestone)
+    case stage
+    when "Done" then "Done"
+    when "What" then "Why"
+    when "Why" then milestone.to_s.include?("spec.md") ? "How" : "Why"
+    when "How" then milestone.to_s.include?("checklist.md") ? "Exec" : "How"
+    when "Exec" then milestone.to_s.include?("outcome.md") ? "ready to complete" : "Exec"
+    else "Why"
+    end
+  end
+
+  def self.intent_dir?(dir)
+    return false unless dir && File.directory?(dir)
+
+    base = File.basename(dir)
+    return false unless base.match?(/\A[0-9][0-9a-z]*--[\w-]+\z/)
+
+    File.exist?(File.join(dir, "#{base}.md"))
+  end
+
+  def self.render(intent_dir:, store_root:, template:)
+    base = File.basename(intent_dir)
+    id = base.split("--", 2).first
+    intent_text = File.read(File.join(intent_dir, "#{base}.md"))
+
+    fields = {}
+    fields.merge!(store_fields(store_root))
+    status, title = index_fields(store_root, id)
+    fields["status"] = status
+    fields["status.note"] = status == "unlisted" ? "no INDEX.md line names this id" : "listed under ## #{status} in INDEX.md"
+    fields["id"] = id
+    fields["name"] = title || fallback_name(intent_text)
+    fields.merge!(savepoint_fields(intent_dir, intent_text))
+    items = checklist_items(intent_dir)
+    fields.merge!(progress_fields(items))
+    fields.merge!(next_fields(items, status, checklist_present: items_present?(intent_dir)))
+    fields.merge!(insight_fields(intent_text))
+    fields["steps.rows"] = steps_rows(items)
+
+    out = template.dup
+    fields.each { |k, v| out = out.gsub("{{#{k}}}", v.to_s) }
+    out.gsub(/\n{3,}/, "\n\n")
+  end
+
+  # --- store ---------------------------------------------------------------------
+
+  def self.store_fields(store_root)
+    parent = File.basename(File.dirname(store_root))
+    if parent == "projects"
+      slug = File.basename(store_root)
+      { "store" => "project:#{slug}", "store.note" => "the #{slug} project store" }
+    else
+      { "store" => "global", "store.note" => "the global store" }
+    end
+  end
+
+  # --- INDEX.md -----------------------------------------------------------------
+
+  def self.index_fields(store_root, id)
+    path = File.join(store_root, "INDEX.md")
+    return ["unlisted", nil] unless File.exist?(path)
+
+    section = nil
+    File.foreach(path) do |line|
+      if line.start_with?("## ")
+        name = line[3..].strip
+        section = SECTIONS.include?(name) ? name : nil
+        next
+      end
+      next unless section && line.strip.start_with?("- [")
+
+      m = line.match(/\A\s*- \[#{Regexp.escape(id)}\s+[-—]\s+(.+?)\]\(/)
+      return [section, m[1].strip] if m
+    end
+    ["unlisted", nil]
+  end
+
+  def self.fallback_name(intent_text)
+    m = intent_text.match(/^intent:\s*["']?(.+?)["']?\s*$/)
+    text = m ? m[1] : ""
+    text.length > 60 ? "#{text[0, 57]}..." : text
+  end
+
+  # --- savepoint.md ---------------------------------------------------------------
+
+  def self.savepoint_fields(intent_dir, intent_text)
+    path = File.join(intent_dir, "savepoint.md")
+    lines = File.exist?(path) ? File.readlines(path).map(&:strip).reject(&:empty?) : []
+    matched = lines.reverse.map { |l| l.match(SAVEPOINT_RE) }.compact
+    last = matched.first
+    unless last
+      return { "stage" => "Why", "stage.note" => "no savepoint line yet",
+               "savepoint" => "none", "savepoint.note" => "" }
+    end
+
+    # D6: the STAGE PICK is guarded to the last LIFECYCLE line (What/Why/How/
+    # Exec/Done), so a trailing Lock/Review/Commit line cannot be mistaken for
+    # the stage. The Savepoint field below still shows the TRUE last line,
+    # whatever its kind - that is what a savepoint is.
+    lifecycle_last = matched.find { |m| LIFECYCLE_STAGES.include?(m[2]) }
+    stage_source = lifecycle_last || last
+
+    ts, stage, milestone = last[1], last[2], last[3]
+    landing = landing_stage(stage_source[2], stage_source[3])
+    delivered = lines.map { |l| l.match(SAVEPOINT_RE) }.compact.map { |m| m[2] }.uniq
+    delivered &= %w[What Why How Exec]
+    note = if landing == "Done"
+             "delivered; the record is immutable"
+           elsif landing == "ready to complete"
+             "outcome.md is real; run the ending procedure"
+           else
+             "#{delivered.join(', ')} delivered; the work is open"
+           end
+    { "stage" => landing, "stage.note" => note,
+      "savepoint" => "#{stage} · #{milestone}", "savepoint.note" => human_time(ts) }
+  end
+
+  def self.human_time(ts)
+    m = ts.match(/\A(\d{4}-\d\d-\d\d)T(\d\d:\d\d)/)
+    m ? "#{m[1]} #{m[2]} UTC" : ts
+  end
+
+  # --- checklist.md --------------------------------------------------------------
+
+  def self.items_present?(intent_dir)
+    path = File.join(intent_dir, "checklist.md")
+    return false unless File.exist?(path)
+
+    !File.read(path).lstrip.start_with?(PLACEHOLDER_SENTINEL)
+  end
+
+  def self.checklist_items(intent_dir)
+    return [] unless items_present?(intent_dir)
+
+    File.readlines(File.join(intent_dir, "checklist.md")).filter_map do |line|
+      m = line.match(ITEM_RE)
+      next unless m
+
+      text = m[2].strip
+      next if text == "..."
+
+      { done: m[1] != " ", text: text.sub(STEP_PREFIX_RE, "") }
+    end
+  end
+
+  def self.progress_fields(items)
+    total = items.length
+    done = items.count { |i| i[:done] }
+    on = total.zero? ? 0 : (done * BAR_WIDTH) / total
+    bar = (ON * on) + (OFF * (BAR_WIDTH - on))
+    note = if total.zero?
+             "no checklist yet"
+           elsif done == total
+             "all steps done"
+           else
+             "#{total - done} steps open"
+           end
+    { "progress.bar" => bar, "progress.done" => done.to_s, "progress.total" => total.to_s,
+      "progress.note" => note }
+  end
+
+  # `escape_pipes:` (intent 316a O1d, default true) keeps the plain Markdown
+  # table's pipe-escaping; the ANSI renderer, which never emits a table,
+  # passes `escape_pipes: false` to get the raw value instead of a literal
+  # `\|`. Named to not shadow the module's own `escape` method.
+  def self.next_fields(items, status, checklist_present:, escape_pipes: true)
+    return { "next" => "", "next.note" => "" } if %w[Completed Abandoned].include?(status)
+    return { "next" => "write checklist.md", "next.note" => "How" } unless checklist_present
+
+    idx = items.index { |i| !i[:done] }
+    return { "next" => "", "next.note" => "all steps done" } unless idx
+
+    head, = split_first_clause(items[idx][:text])
+    head = truncate_words(head, NEXT_VALUE_MAX)
+    head = escape(head) if escape_pipes
+    { "next" => "S#{idx + 1} · #{head}", "next.note" => "first open step" }
+  end
+
+  def self.steps_rows(items)
+    return "| | | no steps yet |" if items.empty?
+
+    items.each_with_index.map do |item, i|
+      "| S#{i + 1} | #{item[:done] ? 'done' : 'open'} | #{escape(step_text(item[:text]))} |"
+    end.join("\n")
+  end
+
+  # Public (intent 316a O1c) so the ANSI renderer trims step text identically:
+  # word-boundary truncation only, never a clause trim, at STEP_TEXT_MAX.
+  def self.step_text(text)
+    truncate_words(text, STEP_TEXT_MAX)
+  end
+
+  def self.escape(text)
+    text.gsub("|", "\\|")
+  end
+
+  # --- ## Insights ----------------------------------------------------------------
+
+  def self.insight_fields(intent_text, escape_pipes: true)
+    section = intent_text.split(/^## Insights\s*$/, 2)[1].to_s.split(/^## /, 2)[0].to_s
+    entry = section.lines.map(&:strip).reverse.map { |l| l.match(INSIGHT_RE) }.compact.first
+    return { "insight" => "none yet", "insight.note" => "" } unless entry
+
+    ts, text = entry[1], entry[2].strip
+    head, tail = split_first_clause(text)
+    value = truncate_words(head, INSIGHT_VALUE_MAX)
+    tail = tail.empty? ? "" : truncate_words(tail, INSIGHT_NOTE_MAX)
+    note = tail.empty? ? human_time(ts) : "#{human_time(ts)} · #{tail}"
+    if escape_pipes
+      { "insight" => escape(value), "insight.note" => escape(note) }
+    else
+      { "insight" => value, "insight.note" => note }
+    end
+  end
+
+  # First clause of `text`, and at most one following clause as the tail.
+  # Anything past the second clause is discarded (intent 316a O1a): the old
+  # behavior dumped the ENTIRE remainder into the note (an 800-character
+  # real-world tail starting mid-list). Boundary is a `.` or `;` immediately
+  # followed by whitespace-then-more or end of string, so "alpha.2" and "2.0"
+  # are never mistaken for clause ends.
+  def self.split_first_clause(text)
+    head, rest = clause_and_rest(text)
+    return [head, ""] unless rest
+
+    second, more = clause_and_rest(rest)
+    tail = more ? second : rest
+    [head, tail]
+  end
+
+  # Returns [clause_without_terminal_punctuation, remainder_or_nil]. `nil` for
+  # the remainder means either no boundary exists at all, or the boundary
+  # sits at the absolute end of `text` (a single trailing clause with nothing
+  # after it) — both cases where there is no SECOND clause to fold in.
+  def self.clause_and_rest(text)
+    m = text.match(/\A(.+?)[.;](\s+(.*)|\z)/m)
+    return [text, nil] unless m
+
+    remainder = m[2].to_s.strip
+    remainder.empty? ? [m[1], nil] : [m[1], remainder]
+  end
+
+  # Word-boundary truncation with a trailing "…" when cut, never mid-word and
+  # never a clause trim (intent 316a D3).
+  def self.truncate_words(text, max)
+    return text if text.length <= max
+    return "…" if max <= 1
+
+    cut = text[0, max - 1].rindex(" ")
+    cut = max - 1 if cut.nil? || cut.zero?
+    "#{text[0, cut].rstrip}…"
+  end
+end

package/scripts/lib/intent_screen_ansi.rb

@@ -0,0 +1,262 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "intent_screen"
+
+# IntentScreenAnsi (intent 316a, O2) - renders one intent screen with raw
+# truecolor ANSI escapes, productionizing 318's mockup--render.rb. Standard
+# library only. Calls the SAME public IntentScreen.* field methods
+# scripts/intent-screen calls (store_fields, index_fields, savepoint_fields,
+# checklist_items, progress_fields, next_fields, insight_fields,
+# items_present?, fallback_name, step_text) and re-derives nothing, so every
+# field the ANSI block prints is the identical value the plain screen prints
+# (D3), just carried through a different layout.
+#
+# `color:` is a constructor/call argument, never an environment read (D18):
+# the plain path (`color: false`) is one call away and testable without
+# touching NO_COLOR or a TTY. No ENV, no Dir.pwd, no Dir.home.
+#
+# Harness-agnostic core: no harness assumption lives here. `markdown_safe:`
+# (intent 316a1, D3/D5) is the one choice a caller supplies rather than a
+# choice this module makes for itself: a display surface that passes raw
+# ANSI through untouched should not inherit a concession it never needed.
+# See docs/reference/harness-adapters.md for which caller asks for it and
+# why.
+module IntentScreenAnsi
+  ESC = "\e"
+  RESET = "#{ESC}[0m".freeze
+  BOLD = "#{ESC}[1m".freeze
+  TEAL = "#{ESC}[38;2;45;212;191m".freeze
+  AMBER = "#{ESC}[38;2;245;158;11m".freeze
+  GRAPHITE_BG = "#{ESC}[48;2;31;41;55m".freeze
+  MIDGREY = "#{ESC}[38;2;148;163;184m".freeze
+  NEARWHITE = "#{ESC}[38;2;243;244;246m".freeze
+
+  BAR_CELLS = 24
+  EIGHTHS = [" ", "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"].freeze
+
+  # Intent 317a1 (D14): the approved design is a 115-column layout, measured
+  # from design--terminal-output.html:52-58 with its tags stripped.
+  DEFAULT_WIDTH = 115
+
+  ELLIPSIS = "…"
+
+  # Intent 317a1 (D9-D11, D15): the three-column field table's geometry.
+  # ANSI_RE strips escapes so padding measures what the terminal actually
+  # draws (D10); VALUE_COL_MAX is the design's own value-column figure and
+  # the owner's "50 chars" (mockup--report-screen.md:74); NOTE_FLOOR is the
+  # minimum note length that earns the own-line fallback when the note alone
+  # (not the value) is what overflows the same-line budget.
+  ANSI_RE = /\e\[[0-9;]*m/.freeze
+  VALUE_COL_MAX = 50
+  NOTE_FLOOR = 24
+
+  def self.visible_width(text)
+    text.to_s.gsub(ANSI_RE, "").length
+  end
+
+  def self.render(intent_dir:, store_root:, color: true, width: DEFAULT_WIDTH, markdown_safe: false)
+    base = File.basename(intent_dir)
+    id = base.split("--", 2).first
+    intent_text = File.read(File.join(intent_dir, "#{base}.md"))
+
+    fields = {}
+    fields.merge!(IntentScreen.store_fields(store_root))
+    status, title = IntentScreen.index_fields(store_root, id)
+    fields["status"] = status
+    fields["status.note"] = status == "unlisted" ? "no INDEX.md line names this id" : "listed under ## #{status} in INDEX.md"
+    fields["id"] = id
+    fields["name"] = title || IntentScreen.fallback_name(intent_text)
+    fields.merge!(IntentScreen.savepoint_fields(intent_dir, intent_text))
+    items = IntentScreen.checklist_items(intent_dir)
+    fields.merge!(IntentScreen.progress_fields(items))
+    fields.merge!(IntentScreen.next_fields(items, status, checklist_present: IntentScreen.items_present?(intent_dir), escape_pipes: false))
+    fields.merge!(IntentScreen.insight_fields(intent_text, escape_pipes: false))
+    fields.transform_values! { |v| markdown_safe ? clean(v) : v }
+
+    done_n = fields["progress.done"].to_i
+    total_n = fields["progress.total"].to_i
+
+    out = +""
+    out << fit("▶ #{fields['id']} · #{fields['name']}", width) { |t| styled(t, color, BOLD, NEARWHITE) }
+    out << "\n\n"
+
+    # The 4th column marks a row whose value is already a finished, pre-fit
+    # string (the Progress bar, built above from styled glyphs plus a count)
+    # rather than raw field text still needing `fit_plain`. Naming that
+    # explicitly here reads better than testing the value for a leading ESC
+    # byte further down, which is really just asking "is this the Progress
+    # row?" through a type check.
+    field_rows = [
+      ["Store", fields["store"], fields["store.note"], false],
+      ["Status", fields["status"], fields["status.note"], false],
+      ["Stage", fields["stage"], fields["stage.note"], false],
+      ["Savepoint", fields["savepoint"], fields["savepoint.note"], false],
+      ["Progress", "#{render_bar(done_n, total_n, color)}  #{done_n} / #{total_n}", fields["progress.note"], true],
+      ["Next", fields["next"], fields["next.note"], false],
+      ["Insight", fields["insight"], fields["insight.note"], false],
+    ]
+    key_width = field_rows.map { |k, _, _, _| k.length }.max
+
+    out << field_table_lines(field_rows, width: width, color: color, key_width: key_width)
+
+    out << "\n"
+    out << fit("Steps", width) { |t| styled(t, color, BOLD, NEARWHITE) }
+    out << "\n\n"
+
+    if items.empty?
+      out << "  no steps yet\n"
+    else
+      # Padded to the widest label (matrix B2): at 10+ steps "S10" is one
+      # column wider than "S1..S9", and without padding every badge past S9
+      # drifts out of column with the rows above it.
+      label_width = "S#{items.size}".length
+      items.each_with_index do |item, i|
+        num = "S#{i + 1}".ljust(label_width)
+        badge = status_cell(item[:done], color)
+        prefix_plain = "  #{num}  [ #{item[:done] ? 'done' : 'open'} ]  "
+        text_budget = [width - prefix_plain.length, 0].max
+        step = IntentScreen.step_text(item[:text])
+        text = fit_plain(markdown_safe ? clean(step) : step, text_budget)
+        out << "  #{num}  [#{badge}]  #{text}\n"
+      end
+    end
+
+    out
+  end
+
+  # --- shared field-table geometry (D9-D12, D14, D15) ------------------------
+
+  # The field table's basis, cap, budget arithmetic, both fallbacks, and the
+  # right-strip, shared by `render` above and `ScreenPaint.paint_table`'s
+  # `**Key**` branch, so the two renderers can never drift apart (D12) - the
+  # duplication this replaced was character-for-character identical apart
+  # from the module prefix. `rows` is `[key, value, note]`, or `[key, value,
+  # note, true]` when `value` is already a finished, pre-fit string (the
+  # Progress bar) rather than raw text still needing `fit_plain`.
+  #
+  # Notes become a third column, padded to the widest RENDERED noted value
+  # (capped at VALUE_COL_MAX, D15) so every note starts at one raw-text
+  # position; a row whose value or note will not fit drops to the
+  # note-on-its-own-line form instead of squeezing anything invisibly. When
+  # the same-line budget has already collapsed to zero or less, the note
+  # falls straight to its own line rather than being fed to `fit` and
+  # silently returning "" - the note must be cut with a visible ellipsis or
+  # kept whole, never dropped outright (317a1 post-exec review, finding 4).
+  def self.field_table_lines(rows, width:, color:, key_width:)
+    prefix_width = key_width + 4 # "  " + key.ljust + "  "
+
+    rendered_rows = rows.map do |key, value, note, prebuilt|
+      value_budget = [width - prefix_width, 0].max
+      value_text = prebuilt ? value : fit_plain(value.to_s, value_budget)
+      [key.to_s, value_text, note.to_s]
+    end
+
+    noted_widths = rendered_rows.filter_map { |_, value_text, note| visible_width(value_text) unless note.empty? }
+    value_col = [noted_widths.max.to_i, VALUE_COL_MAX].min
+    note_budget = width - prefix_width - value_col - 2
+
+    out = +""
+    rendered_rows.each do |key, value_text, note|
+      row = "  #{styled(key.ljust(key_width), color, BOLD)}  #{value_text}"
+      if note.empty?
+        out << row.rstrip << "\n"
+        next
+      end
+
+      value_fits = visible_width(value_text) <= value_col
+      note_width = visible_width(note)
+      note_overflows = note_width > note_budget
+      note_fits = !note_overflows || (note_budget.positive? && note_width <= NOTE_FLOOR)
+      if value_fits && note_fits
+        pad = value_col - visible_width(value_text)
+        out << row << (" " * pad) << "  " << fit(note, note_budget) { |t| styled(t, color, MIDGREY) } << "\n"
+      else
+        out << row.rstrip << "\n"
+        own_budget = [width - prefix_width, 0].max
+        out << (" " * prefix_width) << fit(note, own_budget) { |t| styled(t, color, MIDGREY) } << "\n"
+      end
+    end
+    out
+  end
+
+  # --- markdown-noise stripping, adapter-optional (intent 316a1, D3/D5) ------
+  #
+  # Not every display surface passes text through a Markdown renderer, so
+  # stripping is not this module's call to make (see `markdown_safe:` on
+  # `render` above; the justification for WHY a caller would ever ask for
+  # this lives with that caller, in scripts/lib/message_display.rb). When
+  # asked, strips backticks and neutralises `*`/`_` runs from a value.
+  # Single underscores are left alone: they are common inside ordinary words
+  # (`intent_screen.rb`) and GFM does not treat an intraword underscore as
+  # emphasis; only a run of 2+ (the bold marker `__`) is markdown-active.
+  def self.clean(text)
+    text.to_s.delete("`*").gsub(/_{2,}/, "")
+  end
+
+  # --- width cap (D15, matrix 18) --------------------------------------------
+
+  # Truncates `text` to `max` visible columns with a trailing ellipsis when
+  # cut, then yields the truncated plain text to the block for coloring.
+  # Coloring never adds visible width. The cap itself is harness-neutral: a
+  # fixed width, not a re-flow, is what lets a column layout survive whatever
+  # display eventually shows it — no display's own wrapping is assumed here.
+  def self.fit(text, max)
+    plain = fit_plain(text, max)
+    block_given? ? yield(plain) : plain
+  end
+
+  def self.fit_plain(text, max)
+    return "" if max <= 0
+    return text if text.length <= max
+    return ELLIPSIS[0, max] if max <= 1
+
+    "#{text[0, max - 1]}#{ELLIPSIS}"
+  end
+
+  # --- palette ----------------------------------------------------------------
+
+  def self.styled(text, color, *codes)
+    return text unless color
+
+    "#{codes.join}#{text}#{RESET}"
+  end
+
+  def self.status_cell(done, color)
+    label = done ? " done " : " open "
+    return label unless color
+
+    hue = done ? TEAL : AMBER
+    "#{hue}#{BOLD}#{label}#{RESET}"
+  end
+
+  # `.dup` matters, not just style (318's own note, carried forward): these
+  # constants are built via string interpolation, which frozen_string_literal
+  # does NOT freeze automatically — only static literals get that. `.freeze`
+  # above makes them immutable, but `bar << ...` below still needs its OWN
+  # mutable copy or it would raise (or, without the freeze, silently corrupt
+  # the shared constant for every later call in the same process — matrix 16).
+  def self.render_bar(done, total, color)
+    ratio = total.zero? ? 0.0 : done.to_f / total
+
+    unless color
+      on = total.zero? ? 0 : (done * BAR_CELLS) / total
+      return ("#" * on) + ("." * (BAR_CELLS - on))
+    end
+
+    units = (ratio * BAR_CELLS * 8).round.clamp(0, BAR_CELLS * 8)
+    full, rem = units.divmod(8)
+    full = [full, BAR_CELLS].min
+
+    bar = TEAL.dup
+    bar << ("█" * full)
+    if full < BAR_CELLS && rem.positive?
+      bar << EIGHTHS[rem]
+      full += 1
+    end
+    track = BAR_CELLS - full
+    bar << GRAPHITE_BG << (" " * track) if track.positive?
+    bar << RESET
+    bar
+  end
+end