A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.
#nullable enable
using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using System.Text.RegularExpressions;
using UnityEngine;
using UnityEngine.UIElements;
namespace Statecraft.Game.UI
{
/// <summary>One-way WebGL mirror of the presenter's words. It never receives game commands or changes focus. Opt-in
/// (<see cref="On"/>): the Settings switch or "?companion=1" turns it on, and only while <see cref="Available"/>, which is
/// false for now (owner, 2 November 2026).
/// It publishes in the frame after a sim change, an End Turn, a refused order, a click, a submit or a focus move, once
/// the presenters have rendered; periodic sampling also catches toast writes and controls rebuilt without any of those.
/// Nothing is published before the first frame. Owned by GameRoot: a restart/language switch disposes it without clearing
/// the page, and the next mirror's first snapshot replaces the panel; turning it off or disabling GameRoot clears it.</summary>
public sealed class WebCompanion : IDisposable
{
[Serializable]
public sealed class Choice
{
public string text = "", note = "";
public bool available;
}
[Serializable]
public sealed class Snapshot
{
public string lang = "", heading = "", help = "", focusHeading = "", statusHeading = "", choicesHeading = "", empty = "", unavailable = "";
public string title = "", focus = "", status = "", reportTitle = "";
/// <summary>The game turn: the page announces the same status again when it comes on a new turn.</summary>
public int turn;
public string[] body = Array.Empty<string>();
/// <summary>The open turn report's introduction, then one entry a row: its heading and its causes, one a line.</summary>
public string[] report = Array.Empty<string>();
public Choice[] choices = Array.Empty<Choice>();
}
/// <summary>Whether this build offers the companion at all. The owner's ruling of 2 November 2026, "Remove it from the
/// game (Recommended)": "A small PR before tonight's nightly hides it entirely: no Settings row, and ?companion=1 does
/// nothing. The code stays in, switched off by one flag, so it can come back later." While false, nothing turns it on
/// (<see cref="On"/>), GameRoot gives Settings no switch, so its row stays hidden, and nothing reaches the page.</summary>
public const bool Available = false;
/// <summary><see cref="Available"/>, read where it applies. A seam: a test sets it to exercise the companion with the
/// flag on, and puts it back.</summary>
internal static Func<bool> Offered = () => Available;
// "?companion=1": a whole query parameter with a whole value (UrlFlags' rule), so "?companion=10" and "?xcompanion=1"
// are not it.
static readonly Regex Asked = new Regex(@"[?&]companion=1(?=&|#|$)", RegexOptions.CultureInvariant);
/// <summary>Whether the mirror runs: off unless asked for. The owner's ruling of 1 November 2026, "Opt-in for now
/// (Recommended)", until the VoiceOver test and the phone layout are done. <paramref name="picked"/> is the Settings
/// switch pressed in this page's session, which wins; else the stored choice (<see cref="SettingsPresenter.CompanionKey"/>
/// "on") or "?companion=1" in the page address turns it on. The address wins over a stored "off" for that visit and
/// writes nothing: the owner's ruling of 2 November 2026, "Link wins, that visit (Recommended)". None of them counts
/// while the build does not offer it (<see cref="Available"/>).</summary>
public static bool On(bool? picked, string? stored, string? url) => Offered() && (picked ?? (stored == "on" || Asked.IsMatch(Boot.UrlFlags.BeforeFragment(url))));
readonly VisualElement root;
readonly UiText text;
readonly SimBridge? bridge;
readonly Func<bool> hasEvent;
readonly Action<string> send;
readonly IVisualElementScheduledItem poll;
readonly Action later;
readonly Action<IReadOnlyList<Statecraft.Sim.Rejection>> onTurn;
readonly Action<string> onRefused;
readonly EventCallback<ClickEvent> onClick;
readonly EventCallback<NavigationSubmitEvent> onSubmit;
readonly EventCallback<FocusInEvent> onFocus;
IVisualElementScheduledItem? next;
string? previous;
bool disposed;
/// <param name="bridge">The game's bridge, for the turn and its events; null in tests of a bare tree.</param>
public WebCompanion(VisualElement root, UiText text, SimBridge? bridge, Func<bool> hasEvent, Action<string>? send = null)
{
this.root = root; this.text = text; this.bridge = bridge; this.hasEvent = hasEvent; this.send = send ?? Publish;
// One publication in the next frame however many notifications arrive in this one (as UiDirection schedules).
later = () => { if (disposed) return; next?.Pause(); next = root.schedule.Execute(Refresh); };
onTurn = _ => later(); onRefused = _ => later();
onClick = _ => later(); onSubmit = _ => later(); onFocus = _ => later();
if (bridge != null) { bridge.Changed += later; bridge.TurnEnded += onTurn; bridge.Refused += onRefused; }
root.RegisterCallback(onClick, TrickleDown.TrickleDown);
root.RegisterCallback(onSubmit, TrickleDown.TrickleDown);
root.RegisterCallback(onFocus, TrickleDown.TrickleDown);
poll = root.schedule.Execute(Refresh).Every(100);
later();
}
/// <summary>Copies rendered/localised strings, not event IDs or an independently formatted sim projection.
/// A collapsed/covered current event stays readable; hasEvent prevents the presenter's retained labels from
/// leaking the previous event after the final answer. Disabled choices remain ordinary readable list items.</summary>
internal Snapshot Capture(VisualElement? focused = null)
{
var snapshot = new Snapshot
{
lang = text["ui.lang"], heading = text["companion.title"], help = text["companion.help"],
focusHeading = text["companion.focus"], statusHeading = text["companion.status"],
choicesHeading = text["companion.choices"], empty = text["companion.empty"], unavailable = text["companion.unavailable"],
turn = bridge?.State.Turn ?? 0,
};
var toast = root.Q<Label>("toast");
if (Visible(toast) && toast!.text.Length > 0) snapshot.status = toast.text;
// The End Turn result, whether or not a decision waits: the report section carries its rows as the panel shows
// them, and the status line names the open report while no toast is showing. Never both: the line is one atomic
// live region, read whole on any change: a toast joined to the title would read the title when the toast came
// and again when it went.
var report = root.Q(TurnReportPresenter.ElementName);
if (Visible(report))
{
snapshot.reportTitle = Words("turn-report-title");
if (snapshot.status.Length == 0) snapshot.status = snapshot.reportTitle;
var lines = new List<string>();
var intro = Words("turn-report-intro");
if (intro.Length > 0) lines.Add(intro);
var rows = report!.Q<ScrollView>("turn-report-rows");
if (rows != null)
foreach (var row in rows.Children())
{
var words = new List<string>();
row.Query<Label>().ForEach(l => { if (l.text.Length > 0) words.Add(l.text); });
if (words.Count > 0) lines.Add(string.Join("\n", words));
}
snapshot.report = lines.ToArray();
}
focused ??= root.focusController?.focusedElement as VisualElement;
if (focused != null && root.Contains(focused) && Visible(focused))
{
if (focused == root.Q("map-focus")) snapshot.focus = text["companion.map"];
else if (focused.name == "event-card" && hasEvent()) snapshot.focus = Words("event-title");
else if (!string.IsNullOrEmpty(focused.tooltip)) snapshot.focus = focused.tooltip;
else if (focused is TextElement label) snapshot.focus = label.text;
else
{
var labels = new List<string>();
focused.Query<Label>().ForEach(l => { if (Visible(l) && l.text.Length > 0) labels.Add(l.text); });
snapshot.focus = string.Join("\n", labels);
}
}
if (!hasEvent()) return snapshot;
snapshot.title = Words("event-title");
var body = new List<string>();
foreach (var name in new[] { "event-draft", "event-office", "event-alt-banner", "event-text", "event-objective", "event-delegate", "event-count" })
{
var label = root.Q<Label>(name);
// Test only the label itself: collapsing the event must not erase its text from the companion.
if (label != null && label.style.display.value != DisplayStyle.None && label.text.Length > 0) body.Add(label.text);
}
snapshot.body = body.ToArray();
var choices = new List<Choice>();
var options = root.Q("event-options");
if (options != null)
foreach (var child in options.Children())
{
if (child is Button b) choices.Add(new Choice { text = b.text, available = b.enabledInHierarchy });
else if (child is Label note && note.ClassListContains(EventCardPresenter.RejoinClass) && choices.Count > 0)
choices[choices.Count - 1].note = note.text;
}
snapshot.choices = choices.ToArray();
return snapshot;
}
string Words(string name) => root.Q<Label>(name)?.text ?? "";
static bool Visible(VisualElement? element)
{
if (element == null) return false;
for (var e = element; e != null; e = e.parent)
if (e.style.display.value == DisplayStyle.None || e.resolvedStyle.display == DisplayStyle.None ||
e.style.visibility.value == Visibility.Hidden || e.resolvedStyle.visibility == Visibility.Hidden) return false;
return true;
}
internal void Refresh()
{
if (disposed) return;
var json = JsonUtility.ToJson(Capture());
if (json == previous) return;
send(json);
previous = json; // only once it has gone out: a publication that threw is tried again
}
public void Dispose() => Dispose(clearPage: true);
/// <param name="clearPage">False for GameRoot's rebuild (a language switch, New Game): the next mirror's first
/// snapshot replaces the panel, so the page neither blinks nor reads its status again.</param>
internal void Dispose(bool clearPage)
{
if (disposed) return;
disposed = true;
poll.Pause(); next?.Pause(); next = null;
if (bridge != null) { bridge.Changed -= later; bridge.TurnEnded -= onTurn; bridge.Refused -= onRefused; }
root.UnregisterCallback(onClick, TrickleDown.TrickleDown);
root.UnregisterCallback(onSubmit, TrickleDown.TrickleDown);
root.UnregisterCallback(onFocus, TrickleDown.TrickleDown);
// Last, and never thrown on: GameRoot disposes its owned presenters in one loop, and a page or test transport
// that throws here must not leave the rest of them undisposed.
if (!clearPage) return;
try { send("null"); }
catch (Exception e) { Debug.LogException(e); }
}
#if UNITY_WEBGL && !UNITY_EDITOR
[DllImport("__Internal")] static extern void StatecraftCompanion(string json);
#endif
static void Publish(string json)
{
#if UNITY_WEBGL && !UNITY_EDITOR
StatecraftCompanion(json);
#endif
}
}
}