@ksp-gonogo/sitrep-sdk 0.0.1 → 0.2.0-rc.12

package/src/spine/contributed-channels.ts

@@ -0,0 +1,126 @@
+import type { DerivedChannelDefinition } from "./timeline-store";
+
+/**
+ * Derived channels contributed by an Uplink client, registered at module load
+ * the same way a reckoner is and drained into every `TelemetryProvider`-built
+ * store beside the first-party ones.
+ *
+ * ## Why this exists
+ *
+ * `PRODUCTION_DERIVED_CHANNELS` is a hardcoded array in core, so until now the
+ * only way to add a derived channel was to edit core. That is fine for the
+ * eight channels core owns and wrong for everything else, because a derived
+ * channel is the ONLY mechanism that can join two Topics, and the models that
+ * need to join two Topics are exactly the ones core must not own.
+ *
+ * A consumable projection is the case that surfaced it. Integrating a resource
+ * needs an amount, a capacity and a rate; `vessel.resources` carries the first
+ * two and the Uplink that models the consumption carries the third, a split the
+ * contract makes deliberately so the generic path keeps owning the amounts. A
+ * per-topic reckoner is handed one point and cannot see across it, so the model
+ * has to be a channel, and the channel has to belong to whoever knows the
+ * physics.
+ *
+ * ## Ownership, and why it is a stamped field
+ *
+ * Same rule and same mechanics as `reckoners.ts`: keyed by (topic, owner), and
+ * a topic two owners both claim is registered by NEITHER. A derived channel
+ * silently overwritten by import order is worse than an absent one, because a
+ * widget goes on reading it and gets another Uplink's model of a quantity it
+ * has never heard of.
+ */
+const contributed = new Map<
+  string,
+  Map<string, DerivedChannelDefinition<unknown>>
+>();
+
+/**
+ * Contribute `owner`'s derived channel. Prefer the bound
+ * `defineUplinkClient(...).registerDerivedChannel`, which supplies the owner.
+ *
+ * Takes effect for stores built AFTER this call, which is the ordinary case:
+ * an Uplink client's module graph is imported before a provider mounts. A
+ * store already built is not retrofitted, because a channel appearing
+ * mid-session would change what a topic means underneath a mounted widget.
+ */
+export function contributeDerivedChannel<Payload>(
+  def: DerivedChannelDefinition<Payload>,
+  owner: string,
+): void {
+  const byOwner =
+    contributed.get(def.topic) ??
+    new Map<string, DerivedChannelDefinition<unknown>>();
+  byOwner.set(owner, def as DerivedChannelDefinition<unknown>);
+  contributed.set(def.topic, byOwner);
+  for (const listener of listeners) listener();
+}
+
+const listeners = new Set<() => void>();
+
+/**
+ * Fires whenever the set of contributed channels changes. A station's Uplink
+ * bundles load only once it has a peer-backed client to read the roster off,
+ * which is after its store exists, so a provider that reads this registry once
+ * at construction sees an empty one. Returns an unsubscribe.
+ */
+export function onContributedChannelsChange(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** A topic two or more Uplinks both contribute a channel for. */
+export interface ContributedChannelConflict {
+  topic: string;
+  /** The competing owners, sorted, all of them withheld. */
+  owners: string[];
+}
+
+/**
+ * Every contested topic, for a host that wants to tell the operator which
+ * Uplinks disagree. Mirrors `getReckonerConflicts` exactly.
+ */
+export function getContributedChannelConflicts(): ContributedChannelConflict[] {
+  const conflicts: ContributedChannelConflict[] = [];
+  for (const [topic, byOwner] of contributed) {
+    if (byOwner.size >= 2) {
+      conflicts.push({ topic, owners: [...byOwner.keys()].sort() });
+    }
+  }
+  return conflicts;
+}
+
+/**
+ * The channels to actually register: every uncontested contribution. A
+ * contested topic is registered by nobody, so reads of it stay `pending`
+ * rather than resolving through a model chosen by import order.
+ */
+export function getContributedDerivedChannels(): DerivedChannelDefinition<unknown>[] {
+  const out: DerivedChannelDefinition<unknown>[] = [];
+  for (const byOwner of contributed.values()) {
+    if (byOwner.size !== 1) continue;
+    const [only] = byOwner.values();
+    out.push(only);
+  }
+  return out;
+}
+
+/**
+ * Every topic anyone contributes a channel for, with its owners. The
+ * enumeration twin of {@link getContributedDerivedChannels}, which withholds
+ * the contested ones and so cannot report that a topic was claimed at all.
+ * Same shape and same reason as `getReckonedTopics`.
+ */
+export function getContributedChannelTopics(): {
+  topic: string;
+  owners: string[];
+}[] {
+  return [...contributed.entries()]
+    .map(([topic, byOwner]) => ({ topic, owners: [...byOwner.keys()].sort() }))
+    .sort((a, b) => a.topic.localeCompare(b.topic));
+}
+
+/** Test-only: reset the registry to empty. */
+export function clearContributedDerivedChannels(): void {
+  contributed.clear();
+  for (const listener of listeners) listener();
+}

package/src/spine/contribution-scope.ts

@@ -0,0 +1,87 @@
+import { hasHost } from "../api/host";
+import { logger } from "../api/logger";
+
+/**
+ * Which contribution's `compute` is running, so an out-of-band read can name
+ * it.
+ *
+ * A contribution is recomputed only when one of its declared `deps` moves. A
+ * `compute` that also reads the view clock, or samples a topic it never
+ * declared, gets whatever that read said at its last recompute and nothing
+ * after, and nothing about that is visible from inside the contribution: it
+ * works for as long as something else happens to be recomputing it. The seams
+ * those reads go through call {@link noteUndeclaredRead}, which says so while
+ * a contribution is on the stack.
+ *
+ * A Processor is never in scope. It is evaluated every frame and compares its
+ * RESULT, so its answer stays current whatever it reads, and comparing the
+ * result needs no declaration of which inputs a compute really reads.
+ */
+interface ContributionScope {
+  id: string;
+  declaredTopics: ReadonlySet<string>;
+}
+
+let current: ContributionScope | null = null;
+const reported = new Set<string>();
+
+/** Run `compute` as contribution `id`, whose declared topic deps are `declaredTopics`. */
+export function runContributionCompute<Result>(
+  id: string,
+  declaredTopics: ReadonlySet<string>,
+  compute: () => Result,
+): Result {
+  const outer = current;
+  current = { id, declaredTopics };
+  try {
+    return compute();
+  } finally {
+    current = outer;
+  }
+}
+
+/**
+ * Run `evaluate` with no contribution in scope. A Processor evaluated on demand
+ * from inside a contribution's `compute` reads for itself, not for the
+ * contribution that asked.
+ */
+export function runOutsideContributionScope<Result>(
+  evaluate: () => Result,
+): Result {
+  const outer = current;
+  current = null;
+  try {
+    return evaluate();
+  } finally {
+    current = outer;
+  }
+}
+
+/**
+ * Report a read of `seam` from inside a contribution's `compute`, once per
+ * (contribution, seam). `topic` names the topic the read resolved to, and a
+ * topic the contribution declared is not reported.
+ *
+ * `console.error` under test, so the suite that exercises the contribution
+ * shows it; the host's `logger.warn` otherwise. It never throws: the read
+ * still answers, and the message names the fix.
+ */
+export function noteUndeclaredRead(seam: string, topic?: string): void {
+  const scope = current;
+  if (!scope) return;
+  if (topic !== undefined && scope.declaredTopics.has(topic)) return;
+  const what = topic === undefined ? seam : `${seam}("${topic}")`;
+  const key = `${scope.id}\u0000${what}`;
+  if (reported.has(key)) return;
+  reported.add(key);
+  const message = `contribution ${scope.id} read ${what} without declaring it; move it into a processor`;
+  if (process.env.NODE_ENV === "test") {
+    console.error(message);
+    return;
+  }
+  if (hasHost()) {
+    logger.warn(message);
+    return;
+  }
+  console.warn(message);
+}

package/src/spine/contributions.ts

@@ -0,0 +1,213 @@
+import { getHost, hasHost } from "../api/host";
+import type {
+  AnyContribution,
+  ContributionDefinition,
+  ContributionDep,
+  NamespacedAugmentSettings,
+} from "../api/types";
+import { assertSizeDelta } from "./size-delta";
+
+/**
+ * The contribution REGISTRATION seam: the
+ * live registry `registerContribution` writes and the per-frame aggregation
+ * reads.
+ *
+ * It was in `@ksp-gonogo/core`, which is `private: true`, so an Uplink could
+ * register a contribution through the published shim and then had no supported
+ * way to read back or reset what it had registered. Seven Uplink test files call
+ * `clearContributions`.
+ *
+ * Everything it named was already on this side of the line once
+ * `Contributed` and `UplinkClientIdentity` came down from
+ * `@ksp-gonogo/ui-kit`: the definition type, the settings shape and the logger are
+ * all sdk-side. The READ half (the per-widget store and the `useContributions`
+ * hooks) stays in ui-kit, which reaches this through the ordinary
+ * ui-kit-imports-sdk direction.
+ */
+
+/**
+ * One global slot rather than module statics, keyed by a string so two different
+ * builds of this package still find the same registry. A second copy of THIS one
+ * is a contribution registering into a Map the aggregation never reads, with no
+ * error anywhere, which is the failure mode the shim design existed to prevent.
+ * Same reasoning as `api/action-dispatch.ts`.
+ */
+const CONTRIBUTIONS_KEY = "__GONOGO_CONTRIBUTIONS__" as const;
+
+interface ContributionRegistryState {
+  entries: Map<string, { def: AnyContribution; order: number }>;
+  listeners: Set<() => void>;
+  counter: number;
+}
+
+function state(): ContributionRegistryState {
+  const slot = globalThis as typeof globalThis & {
+    [CONTRIBUTIONS_KEY]?: ContributionRegistryState;
+  };
+  slot[CONTRIBUTIONS_KEY] ??= {
+    entries: new Map(),
+    listeners: new Set(),
+    counter: 0,
+  };
+  return slot[CONTRIBUTIONS_KEY];
+}
+
+function notifyContributionChange(): void {
+  for (const cb of state().listeners) cb();
+}
+
+export function onContributionsChange(cb: () => void): () => void {
+  const listeners = state().listeners;
+  listeners.add(cb);
+  return () => {
+    listeners.delete(cb);
+  };
+}
+
+/**
+ * Register a contribution. An id collision throws
+ * synchronously AT this call site (no accumulate-then-flush frame), unless
+ * the exact same def is re-registering (a benign idempotent re-import).
+ */
+export function registerContribution<
+  Slot extends string,
+  const Deps extends readonly ContributionDep[] = readonly [],
+>(def: ContributionDefinition<Slot, Deps>): void {
+  assertSizeDelta(def.id, def.sizeDelta);
+  const s = state();
+  const existing = s.entries.get(def.id);
+  if (existing !== undefined) {
+    // Widened through `unknown` because `compute` puts `Deps` in a PARAMETER
+    // position (`DepTopics<Deps>`), so a precisely typed definition and the erased
+    // `AnyContribution` are not mutually assignable. The registry genuinely
+    // stores defs for many slots at once, so erasing `Slot` and `Deps` on the way in
+    // is the honest thing; every read hands the entries back to the
+    // aggregation, which re-narrows per slot.
+    if (existing.def === (def as unknown as AnyContribution)) return;
+    throw new Error(
+      `Contribution id "${def.id}" is already registered for slot "${existing.def.contributes}"; ` +
+        `cannot re-register for "${def.contributes}". Contribution ids must be globally unique ` +
+        `(use defineUplinkClient(...).registerContribution to auto-namespace by owner).`,
+    );
+  }
+  // Guarded, and straight from `./host` rather than `../api/logger`'s Proxy, for
+  // the same two reasons `api/registry.ts` does it: the Proxy would be a cycle
+  // (the barrel re-exports this module's callers), and an UNGUARDED read throws
+  // when no host is installed. Self-registration runs at module load, before any
+  // host exists: `packages/ui/src/FilterList.test.tsx` registers a contribution at
+  // import time and died on exactly this. A registration must not depend on the
+  // host merely because it logs.
+  if (hasHost())
+    getHost().logger.info(
+      `REGISTERED contribution ${def.id} -> ${def.contributes}`,
+    );
+  s.entries.set(def.id, {
+    def: def as unknown as AnyContribution,
+    order: s.counter++,
+  });
+  notifyContributionChange();
+}
+
+/**
+ * The band a contribution registers at when it says nothing, and the reason it
+ * is 1 rather than 0: 0 is left free BELOW every ordinary contributor, for a
+ * host widget filling its own slot with the answer it can read itself. See
+ * {@link getContributionsForSlot}.
+ */
+export const DEFAULT_CONTRIBUTION_PRIORITY = 1;
+
+/**
+ * Every contribution that WINS the slot: the highest priority band present, in
+ * registration order.
+ *
+ * <p>Equal priority is not a tie to break. Everyone in the winning band renders,
+ * which is what lets two mutually-unaware mods both put their vessels on one
+ * diagram; only a STRICTLY higher band displaces. Nothing sets a priority unless
+ * it means to, so the ordinary case is one band holding every contributor,
+ * exactly as before.</p>
+ *
+ * <p>What the band buys is a host widget filling its OWN slot. It contributes
+ * what it can read at one below {@link DEFAULT_CONTRIBUTION_PRIORITY}, so a
+ * career overhaul that can answer where the host cannot displaces it instead of
+ * appearing beside it as a second copy of the same list. It is the contribution
+ * twin of `AugmentDefinition.suppressesVanillaBase`, and it is declared by the
+ * contributor rather than by the host for the same reason: the host cannot know
+ * which of its guests supersedes it.</p>
+ *
+ * <p>A contribution that means to render ALONGSIDE the host's own rows says so
+ * by taking the host's band explicitly.</p>
+ *
+ * <p>Self-contributing has a cost, and it is worth knowing before choosing it: a
+ * widget that reads its own data this way no longer renders anything without a
+ * `WidgetMetaContext` and a `ContributionsProvider` above it, and it fails by
+ * drawing an empty widget rather than by raising. See `useContributions`
+ * (`@ksp-gonogo/ui-kit`) for what that costs a test, and `clearContributions`
+ * below for the other half of it.</p>
+ */
+export function getContributionsForSlot(slot: string): AnyContribution[] {
+  const inSlot = Array.from(state().entries.values()).filter(
+    (entry) => entry.def.contributes === slot,
+  );
+  if (inSlot.length === 0) return [];
+  const priorityOf = (entry: (typeof inSlot)[number]): number =>
+    entry.def.priority ?? DEFAULT_CONTRIBUTION_PRIORITY;
+  const winning = Math.max(...inSlot.map(priorityOf));
+  return inSlot
+    .filter((entry) => priorityOf(entry) === winning)
+    .sort((a, b) => a.order - b.order)
+    .map((entry) => entry.def);
+}
+
+/**
+ * Every registered contribution, whatever slot it feeds, in registration order.
+ *
+ * The unfiltered read `getAugments()` has had all along and this registry has
+ * not. Without it a contribution cannot be enumerated BY OWNER, so an Uplink's
+ * own docs generator could list the widgets and augments it adds and was
+ * structurally unable to mention its contributions: an asymmetry that showed up
+ * as a page quietly describing less than the Uplink does.
+ *
+ * Registration order, not priority order, deliberately: priority is a per-slot
+ * ordering and this read spans slots, so sorting by it would interleave two
+ * slots' entries into a sequence that means nothing.
+ */
+export function getContributions(): AnyContribution[] {
+  return Array.from(state().entries.values())
+    .sort((a, b) => a.order - b.order)
+    .map((entry) => entry.def);
+}
+
+export function getContributionSettings(
+  slot: string,
+): NamespacedAugmentSettings[] {
+  return getContributionsForSlot(slot)
+    .filter((def) => def.settings && def.settings.length > 0)
+    .map((def) => ({
+      augmentId: def.id,
+      namespace: def.id,
+      fields: def.settings ?? [],
+    }));
+}
+
+/**
+ * For use in tests only, resets the contribution registry to empty.
+ *
+ * <p><b>It empties the registry, which includes the contributions a HOST widget
+ * makes to its own slot.</b> Those register as a module side effect, at import,
+ * and nothing re-runs an import. So a test file that clears between cases leaves
+ * every case after the first rendering a host with none of its own data, which
+ * surfaces as a widget that draws its chrome and no content, and reads as a
+ * telemetry fault rather than as a registry that was emptied on purpose.</p>
+ *
+ * <p>A self-contributing widget therefore exports a function that performs its
+ * registration, for a test to call after clearing;
+ * `SpaceCenterStatus/facilitiesContribution.ts`'s
+ * `registerStockFacilityContribution` is the worked example. Re-registering the
+ * identical def is a no-op, so calling it when nothing was cleared is safe.</p>
+ */
+export function clearContributions(): void {
+  const s = state();
+  s.entries.clear();
+  s.counter = 0;
+  notifyContributionChange();
+}

package/src/spine/control-frame-to-read-frame.ts

@@ -0,0 +1,91 @@
+/**
+ * The live Control Frame, translated into the vocabulary a read frame already
+ * draws in.
+ *
+ * `system.frame` and `ReadFrameChoice` were built by different halves of the
+ * same idea and never introduced: `ControlFrameKind` names six states because
+ * it has to describe everything a producer might elect, including two
+ * (`BarycentricRotating`, `BodySurface`) and the target-relative flag that a
+ * `ReadFrameChoice` has no member for at all. So this is a partial map, and
+ * returning null for the frames it cannot represent is the honest answer
+ * rather than a guess at the nearest neighbour: {@link resolveReadFrame}
+ * already treats null as "nothing to follow" for exactly this reason.
+ */
+
+import type { ControlFrame } from "../__generated__/contract";
+import { ControlFrameKind } from "../__generated__/contract";
+import type { CelestialFacts } from "./celestial-facts";
+import type { ReadFrameChoice } from "./reference-frame";
+
+/**
+ * The Topic {@link controlFrameToReadFrameChoice} reads its argument off.
+ *
+ * @category Frames of reference
+ */
+export const CONTROL_FRAME_TOPIC = "system.frame";
+
+/** `facts.indexByName[name]`, folding a missing name and a missing catalogue into one null. */
+function indexFor(
+  facts: CelestialFacts,
+  name: string | null | undefined,
+): number | null {
+  if (!name) return null;
+  const index = facts.indexByName[name];
+  return index === undefined ? null : index;
+}
+
+/**
+ * Returns the player's selected frame, from the `system.frame` reading, as a
+ * {@link ReadFrameChoice} to pass to {@link resolveReadFrame}.
+ *
+ * Only three frame kinds have a matching choice: body-centred inertial,
+ * body-centred with the body direction, and rotating-pulsating. Every other
+ * frame, a frame relative to a target vessel, and a frame whose body is not
+ * in `facts` yet, return `null`. So does a missing frame or catalogue.
+ *
+ * @category Frames of reference
+ */
+export function controlFrameToReadFrameChoice(
+  frame: ControlFrame | null | undefined,
+  facts: CelestialFacts | undefined,
+): ReadFrameChoice | null {
+  if (frame == null || facts === undefined) return null;
+  if (frame.targetFrameSelected) return null;
+  switch (frame.kind) {
+    case ControlFrameKind.BodyCentredInertial: {
+      const bodyIndex = indexFor(facts, frame.centreBody);
+      return bodyIndex === null
+        ? null
+        : { kind: "body-centred-inertial", bodyIndex };
+    }
+    case ControlFrameKind.BodyCentredBodyDirection: {
+      const bodyIndex = indexFor(facts, frame.centreBody);
+      return bodyIndex === null
+        ? null
+        : { kind: "parent-direction", bodyIndex };
+    }
+    case ControlFrameKind.RotatingPulsating: {
+      const bodyIndex = indexFor(facts, frame.secondaryBody);
+      return bodyIndex === null
+        ? null
+        : { kind: "rotating-pulsating", bodyIndex };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Returns whether two frame choices would draw the same picture. Use it to
+ * hide a "follow the Control Frame" option when it matches a frame already
+ * offered, so the player does not see two entries that do the same thing.
+ *
+ * @category Frames of reference
+ */
+export function readFrameChoicesEqual(
+  a: ReadFrameChoice | null,
+  b: ReadFrameChoice | null,
+): boolean {
+  if (a === null || b === null) return a === b;
+  return a.kind === b.kind && (a.bodyIndex ?? null) === (b.bodyIndex ?? null);
+}