@wix/himalaya-cli 0.844.0 → 0.845.0

package/templates/community-club-owner/tier5-src/himi-owner-lite-analytics/report.ts

@@ -0,0 +1,690 @@
+// Tier-5 service: __HIMI_APP_NAME__ — Analytics REPORTS.
+//
+// The second service in this bundle. `index.ts` owns `ownerLiteAnalytics` (the
+// six-measure highlights strip off `site-analytics/data`); this owns
+// `ownerLiteAnalyticsReport`, which drives the public Semantic Model reporting
+// engine. They share a bundle because they are one screen family and the
+// contract scopes one built artifact; they share no state.
+//
+// WHY A GENERIC SCREEN. The Semantic Model API is a reporting engine, not an
+// endpoint: a site exposes N subject-area models (traffic, revenue,
+// `crm-people-subscribers`, ingested Google Search Console), each with its own
+// dimensions and measures. One screen per model would need a release per model.
+// This screen reads the list, so a model appearing on the site appears here with
+// no code change.
+//
+// FOUR THINGS HERE ARE NOT ARBITRARY. Every one is a documented sharp edge of
+// this API, and every one fails SILENTLY — a confident wrong number under a
+// green suite, which is the exact species of defect this screen family has been
+// paying down:
+//
+//   1. `missingFields` IS THE SCREEN'S POINT. A field name that does not exist
+//      in the model, or one whose `dependencies` were not also requested, is
+//      DROPPED FROM A 200 rather than rejected. A caller that ignores this
+//      renders a blank column and sees nothing wrong. So a non-empty
+//      `missingFields` is rendered as a named gap and never swallowed.
+//
+//   2. FIELD NAMES COME ONLY FROM `getSemanticModel`. They are not derivable
+//      from the model slug — `crm-people-subscribers` exposes
+//      `people.contacts_count`. Both pickers are populated from the model, and
+//      this worker never synthesises a field name.
+//
+//   3. THE ID COMES ONLY FROM `listSemanticModels`. A plausible GUID returns
+//      SEMANTIC_MODEL_NOT_FOUND, so `selectSubject` refuses an id it has not
+//      seen in the list rather than passing it through.
+//
+//   4. TOTALS ARE THE SERVER'S. We ask with `totalsIncluded` and render what
+//      comes back; we never sum the rows. Summing is wrong for any `unique`
+//      measure (unique visitors are not additive across buckets) and would
+//      double-count — plausibly, and in the direction that flatters.
+//
+// A fifth, inherited from #2356: a chart's `valuesPath` cannot be a `$item.`
+// placeholder, because both native substituters stringify a non-scalar to "".
+// This screen renders a DataTable rather than a per-row sparkline for that
+// reason; do not add one to a row template.
+
+import { defineService } from "@himalaya/state";
+import { formatNumber } from "../_shared/engine-intl.js";
+import { copyParam, stashCopy } from "../_shared/himi-copy.js";
+import {
+  getSiteTimeZone,
+  intervalForDays,
+  listSemanticModels,
+  getSemanticModel,
+  querySemanticModelData,
+  type SemanticModel,
+  type SemanticModelField,
+  type SemanticModelSummary,
+  type SemanticValue,
+} from "@himalaya/wix-analytics";
+
+/** One row of a picker list. `state` is the trailing marker the descriptor binds. */
+interface PickRow { id: string; label: string; state: string }
+
+/** One table row, keyed by the descriptor's declared `DataTableColumn.key`s. */
+interface ReportRow { dimension: string; measure: string }
+
+interface ReportState {
+  status: "loading" | "ready" | "error";
+
+  /** Subject-area models this site actually has. Never a hardcoded list. */
+  subjects: PickRow[];
+  subjectId: string;
+  subjectLabel: string;
+
+  /** Populated from `getSemanticModel(subjectId)`, never from a fixture. */
+  dimensions: PickRow[];
+  measures: PickRow[];
+  dimensionName: string;
+  dimensionLabel: string;
+  measureName: string;
+  measureLabel: string;
+
+  rangeId: string;
+  range: string;
+  /**
+   * "<measure> by <dimension>" — what the table is actually showing.
+   *
+   * The table's own column titles are declared literals (the proto field is not
+   * bindable), so this is the only place the chosen field names can reach the
+   * screen. Without it the table reads as two anonymous columns of numbers.
+   */
+  caption: string;
+
+  rows: ReportRow[];
+  /**
+   * NULL, not an empty row, when the owner has not asked for totals.
+   *
+   * `totalsPath` binds ONE ROW OBJECT, and the table is shown as soon as there
+   * are rows — so publishing `{dimension:"",measure:""}` here handed the
+   * renderer a present-but-blank totals row on every ordinary query. Absence
+   * has to be expressed as absence.
+   */
+  totals: ReportRow | null;
+  rowCount: string;
+
+  /**
+   * Rendered text for a non-empty `missingFields`, "" when the query answered
+   * what was asked. NOT a boolean: the owner needs the field NAME, because the
+   * remedy differs — an unknown name is a bad pick, an unmet dependency is a
+   * query this screen built wrong.
+   */
+  missingFields: string;
+
+  // Owner-lite's four-state gates are all INVERSES: `hiddenWhen` collapses on
+  // truthy, so each flag says "hide me". Every owner-lite screen emits exactly
+  // this set and the descriptor tests assert on it by name.
+  notLoading: boolean;
+  notErrored: boolean;
+  hideContent: boolean;
+  noEmpty: boolean;
+  /** No subject chosen yet ⇒ the field pickers have nothing to offer. */
+  noFields: boolean;
+  /** No `missingFields` gap to report ⇒ the callout collapses entirely. */
+  noGap: boolean;
+  /** No rows ⇒ collapse the table rather than render a lone header row. */
+  hideTable: boolean;
+  /** Totals are opt-in; also true when the server returned none. */
+  noTotals: boolean;
+  totalsState: string;
+  emptyText: string;
+  error: string;
+}
+
+/** The ranges this screen offers. Ids are the day counts the reducer parses. */
+const RANGES = [7, 30, 60];
+
+const empty: ReportState = {
+  status: "loading",
+  subjects: [], subjectId: "", subjectLabel: "",
+  dimensions: [], measures: [],
+  dimensionName: "", dimensionLabel: "", measureName: "", measureLabel: "",
+  rangeId: "30", range: "Last 30 days", caption: "",
+  rows: [], totals: null, rowCount: "",
+  missingFields: "",
+  notLoading: false, notErrored: true, hideContent: true, noEmpty: true,
+  noFields: true, noGap: true, hideTable: true, noTotals: true, totalsState: "Off",
+  emptyText: "", error: "",
+};
+
+function rangeLabel(days: number): string {
+  return copyParam(`ownerReport.range${days}`, `Last ${days} days`);
+}
+
+/**
+ * A field's display label.
+ *
+ * `description` first, because the model's own prose is what a human reads;
+ * the wire `name` is a dotted path (`people.contacts_count`) and is shown only
+ * when there is nothing better. The `id` stays the wire name either way — that
+ * is what goes back in `fields`, and the two must not drift.
+ */
+function fieldLabel(f: SemanticModelField): string {
+  const described = (f.description ?? "").trim();
+  if (described && described.length <= 40) return described;
+  const leaf = f.name.split(".").pop() ?? f.name;
+  return leaf.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+}
+
+function subjectLabelOf(m: SemanticModelSummary): string {
+  const described = (m.description ?? "").trim();
+  if (described && described.length <= 40) return described;
+  return (m.slug || m.id).replace(/[-_]/g, " ").replace(/^./, (c) => c.toUpperCase());
+}
+
+/**
+ * One decoded cell as display text.
+ *
+ * `formatted` wins when the server sent it — it carries the site's currency and
+ * locale, which this worker cannot reconstruct. Otherwise: key presence has
+ * already been resolved by the SDK, so `null` here means genuinely no value and
+ * renders as a dash rather than as 0. `formatNumber` and not `toLocaleString`,
+ * which is ECMA-402 and absent on QuickJS-ng (watchOS/Wear OS).
+ */
+function cellText(v: SemanticValue | undefined): string {
+  if (!v) return "—";
+  if (v.formatted !== undefined && v.formatted !== "") return v.formatted;
+  const raw = v.value;
+  if (raw === null || raw === undefined) return "—";
+  if (typeof raw === "number") return formatNumber(raw);
+  if (typeof raw === "boolean") return raw ? "Yes" : "No";
+  if (typeof raw === "string") return raw;
+  // A dimension can legitimately be an ARRAY or OBJECT field. Rendering
+  // `[object Object]` into a table cell is worse than admitting the shape, and
+  // "—" would claim there is no value when there is one this table cannot show.
+  if (Array.isArray(raw)) return copyParam("ownerReport.cellList", `${raw.length} values`);
+  return copyParam("ownerReport.cellObject", "(not shown)");
+}
+
+/**
+ * Read a string out of an action argument.
+ *
+ * The host dispatches with the `params` OBJECT, never a bare scalar, and a
+ * SegmentedControl carries no params of its own — the renderer injects the
+ * chosen option as `{ selectedId }` at dispatch time. A reducer that reads only
+ * one spelling ships an inert control that works under test. Same helper, same
+ * reason, as the highlights service.
+ */
+function argStr(arg: unknown, field: string): string {
+  if (typeof arg === "string") return arg;
+  const o = arg as Record<string, unknown> | undefined;
+  const v = o?.[field] ?? o?.selectedId ?? o?.value ?? o?.id ?? o?.text;
+  return v === undefined || v === null ? "" : String(v);
+}
+
+/**
+ * Publish a state and record it as the newest.
+ *
+ * `latest` has to mean "the newest state the screen has been given", because
+ * every staleness decision reads it. It was only assigned on a SUCCESSFUL
+ * query, so a state published by a decline — the range chip tapped before any
+ * subject exists — left `latest` older than the caller's own snapshot, and the
+ * next action then treated the newer edit as the stale one. Everything that
+ * returns a state to the host goes through here.
+ */
+function publish(next: ReportState): ReportState {
+  latest = next;
+  return next;
+}
+
+/**
+ * Generation guard. Tapping two subjects quickly starts two request chains and
+ * whichever RESOLVES last would win, leaving the picker, the table and the
+ * caption describing different queries. A superseded chain yields the newest
+ * state we have rather than its own stale snapshot.
+ */
+let seq = 0;
+let latest: ReportState | null = null;
+
+/** The models this worker has actually seen. Guard rail 3 reads this. */
+let known: SemanticModelSummary[] = [];
+/**
+ * The chosen model's schema, KEYED to the subject it describes.
+ *
+ * It was a bare singleton, and the `seq` guard deliberately permits overlapping
+ * actions — so `selectSubject(B)` assigned it before B's query published, and a
+ * range/field/totals action still dispatching from A's snapshot would read B's
+ * schema together with A's `subjectId`. That builds a MIXED query (A's model id,
+ * B's field metadata — wrong dependencies, wrong sortability) and, worse, bumps
+ * `seq` and cancels the subject switch the owner just made. Keyed, a stale
+ * dispatch simply finds no schema for its own subject and declines to query.
+ */
+let schema: { id: string; model: SemanticModel } | null = null;
+
+/**
+ * The subject a switch is in flight for, with the GENERATION that owns the
+ * latch; null when none.
+ *
+ * Keying the schema closed the late half of the switch window (B's schema
+ * assigned, B's query unpublished). This closes the EARLY half: between the tap
+ * on B and `getSemanticModel(B)` resolving, the schema is still A's, so an
+ * action carrying A's snapshot matched, bumped `seq`, and made B's pending
+ * `selectSubject` fail its own generation check — the switch the owner just made
+ * was cancelled and the screen stayed on A. A latch is needed because the state
+ * alone cannot say "a different subject is already on its way".
+ *
+ * Keyed by `seq`, not by id alone. Keying by the id looked sufficient and was
+ * not: tap the SAME subject twice while the first `getSemanticModel` is pending,
+ * and the superseded first action's `finally` saw its own id sitting in the
+ * latch and released the one the SECOND request owned — re-opening the very
+ * window the latch exists to close. Only the generation that took it may
+ * release it.
+ */
+let pendingSubject: { id: string; seq: number } | null = null;
+
+/** The schema ONLY if it describes `subjectId`; otherwise null. */
+function schemaFor(subjectId: string): SemanticModel | null {
+  return schema && schema.id === subjectId ? schema.model : null;
+}
+
+function markSelected(rows: PickRow[], selectedId: string): PickRow[] {
+  return rows.map((r) => ({
+    ...r,
+    state: r.id === selectedId ? copyParam("ownerReport.selected", "Selected") : "",
+  }));
+}
+
+function errorState(s: ReportState | undefined, message: string): ReportState {
+  return {
+    ...empty,
+    ...(s ?? {}),
+    status: "error",
+    notLoading: true,
+    notErrored: false,
+    hideContent: true,
+    rows: [], totals: null, rowCount: "", caption: "",
+    missingFields: "", noGap: true, hideTable: true,
+    error: message,
+  };
+}
+
+/**
+ * Run the query for the current selection.
+ *
+ * Returns `s` untouched when the selection is incomplete — a query needs a
+ * model id AND at least one field, and `querySemanticModelData` rejects on
+ * either, so firing early would paint an error the owner did not cause.
+ */
+/**
+ * Why a query did not run. `null` conflated these two and that was the bug: an
+ * INCOMPLETE selection means the caller's own edit is the newest thing there
+ * is and must be kept, while a STALE dispatch means something newer already
+ * exists and the caller's snapshot must not be republished over it.
+ */
+type Declined = "incomplete" | "stale";
+
+async function runQuery(s: ReportState, days: number): Promise<ReportState | Declined> {
+  // A string means DECLINED and says why; a state means a query ran, or was
+  // superseded and this is the WINNER's state. Three outcomes, because the
+  // right answer differs for each: keep the caller's edit, yield to what is
+  // newer, or take the result.
+  //
+  // Never a bare `s`. The host publishes whatever a reducer returns and `s` is
+  // the snapshot the dispatch was CREATED with, so republishing it reverts the
+  // screen to a state the owner has already left.
+  if (!s.subjectId || !s.dimensionName || !s.measureName) return "incomplete";
+
+  // A query is only safe to build from the schema of the subject in THIS state.
+  // Anything else is a mixed query, so a stale dispatch declines rather than
+  // guessing — and declining also leaves `seq` alone, so it cannot cancel a
+  // subject switch that is still in flight.
+  // A switch to a DIFFERENT subject is already under way: this dispatch belongs
+  // to the subject the owner is leaving, so it declines before touching `seq`.
+  // Advancing the generation here is what cancelled the switch.
+  if (pendingSubject && pendingSubject.id !== s.subjectId) return "stale";
+  // A subject IS selected in this snapshot but the schema is not its own, so
+  // the screen has moved on: stale, not incomplete.
+  const model = schemaFor(s.subjectId);
+  if (!model) return "stale";
+  const mine = ++seq;
+  const dimension = model.dimensions.find((f) => f.name === s.dimensionName);
+  const measure = model.measures.find((f) => f.name === s.measureName);
+
+  // DEPENDENCIES ARE REQUESTED, NOT ASSUMED. A field whose `dependencies` are
+  // absent from the same query returns no data and is dropped from the 200 —
+  // so omitting them would surface as a blank column, or (now) as a
+  // `missingFields` gap blaming the field the owner picked. Union, because a
+  // dependency can be shared and the API caps `fields` at 60.
+  const fields = [...new Set([
+    s.dimensionName,
+    s.measureName,
+    ...(dimension?.dependencies ?? []),
+    ...(measure?.dependencies ?? []),
+  ])].filter(Boolean);
+
+  try {
+    const tz = (await getSiteTimeZone()) ?? "UTC";
+    const result = await querySemanticModelData({
+      semanticModelId: s.subjectId,
+      interval: intervalForDays(days, tz),
+      fields,
+      // `nullsLast` only affects DESC, and without it a nullable measure sorts
+      // its NULLS FIRST — so a "top N" query returns a page of blanks and reads
+      // as a site with no data. Sorting is skipped entirely for a measure the
+      // model declares unsortable, rather than sent and silently ignored.
+      sort: measure?.sortable === false
+        ? undefined
+        : { fieldName: s.measureName, order: "DESC", nullsLast: true },
+      paging: { limit: 50 },
+      // The server's own formatting carries the site's currency and locale.
+      formattingEnabled: true,
+      // Opt-in totals. Asked for only when the owner wants them, and rendered
+      // from the RESPONSE — never summed here (guard rail 4).
+      totalsIncluded: !s.noTotals,
+    });
+    if (mine !== seq) return latest ?? s;
+
+    const rows: ReportRow[] = result.rows.map((r) => ({
+      dimension: cellText(r[s.dimensionName]),
+      measure: cellText(r[s.measureName]),
+    }));
+
+    // A non-empty `missingFields` means the query DID NOT ANSWER what was
+    // asked. It is reported as a failure of the query, with the names, and the
+    // rows that did come back are still shown — a blank column with no
+    // explanation is the one outcome this screen exists to prevent.
+    const gap = result.missingFields.length > 0
+      ? copyParam("ownerReport.missingFields", "No data returned for: ") + result.missingFields.join(", ")
+      : "";
+
+    // `noTotals` is the owner's REQUEST and stays theirs; only they change it.
+    // When they asked and the server sent no total, that is reported as a dash —
+    // an absent number the owner asked for must be visible, not silently dropped
+    // under a control still reading "On".
+    const totals: ReportRow | null = s.noTotals
+      ? null
+      : {
+          dimension: copyParam("ownerReport.totalsLabel", "Total"),
+          measure: result.totals ? cellText(result.totals[s.measureName]) : "—",
+        };
+
+    const out: ReportState = {
+      ...s,
+      status: "ready",
+      caption: copyParam("ownerReport.caption", "")
+        + `${s.measureLabel} ${copyParam("ownerReport.by", "by")} ${s.dimensionLabel}`,
+      rows,
+      totals,
+      rowCount: rows.length > 0
+        ? `${result.paging.count || rows.length} ${copyParam("ownerReport.rows", "rows")}`
+        : "",
+      missingFields: gap,
+      noGap: gap === "",
+      // Rows OR totals. The API can answer `results: []` WITH a `totals` object
+      // — the SDK has a test for exactly that shape — and gating on rows alone
+      // hid the server's total and put "Nothing to show" over it. Opting into
+      // Show total would then have thrown away the only answer that came back.
+      hideTable: rows.length === 0 && !totals,
+      notLoading: true,
+      notErrored: true,
+      hideContent: false,
+      // An empty result is a real answer — a quiet period, or a filter that
+      // matches nothing — and is shown as an empty state rather than an error.
+      // It is NOT conflated with a dropped field: the SDK reports no
+      // `missingFields` when nothing came back at all, precisely because the two
+      // are indistinguishable there, so this arm never accuses a field.
+      noEmpty: rows.length > 0 || totals !== null,
+      emptyText: rows.length === 0 && !totals
+        ? copyParam("ownerReport.empty", "No data for this range.")
+        : "",
+      // Carried through untouched: see the totals comment above.
+      noTotals: s.noTotals,
+      error: "",
+    };
+    latest = out;
+    return out;
+  } catch (e) {
+    if (mine !== seq) return latest ?? s;
+    const out = errorState(s, String((e as Error)?.message ?? e));
+    latest = out;
+    return out;
+  }
+}
+
+const svc = defineService<ReportState, {
+  load: (s: ReportState, arg?: unknown) => Promise<ReportState>;
+  selectSubject: (s: ReportState, arg?: unknown) => Promise<ReportState>;
+  selectDimension: (s: ReportState, arg?: unknown) => Promise<ReportState>;
+  selectMeasure: (s: ReportState, arg?: unknown) => Promise<ReportState>;
+  setRange: (s: ReportState, arg?: unknown) => Promise<ReportState>;
+  toggleTotals: (s: ReportState) => Promise<ReportState>;
+}>("ownerLiteAnalyticsReport", {
+  state: { ...empty },
+  actions: {
+    /**
+     * Step 1 — which subject areas this site has. Also the error state's retry,
+     * so it re-reads the list rather than assuming the previous one survived.
+     */
+    load: async (s, arg) => {
+      stashCopy(arg);
+      const mine = ++seq;
+      try {
+        const models = await listSemanticModels();
+        if (mine !== seq) return latest ?? s ?? { ...empty };
+        known = models;
+        const subjects = models.map((m) => ({ id: m.id, label: subjectLabelOf(m), state: "" }));
+        const base: ReportState = {
+          ...empty,
+          ...(s ?? {}),
+          subjects,
+          subjectId: "", subjectLabel: "",
+          dimensions: [], measures: [],
+          dimensionName: "", dimensionLabel: "", measureName: "", measureLabel: "",
+          rows: [], totals: null, rowCount: "", missingFields: "",
+          // Reset too: it names the fields of a query that no longer has a
+          // subject, so leaving it stands a stale caption over an empty table.
+          caption: "",
+          noGap: true, hideTable: true,
+          status: "ready",
+          notLoading: true, notErrored: true, hideContent: false,
+          noFields: true, noEmpty: true, error: "",
+          emptyText: subjects.length === 0
+            ? copyParam("ownerReport.noSubjects", "This site has no analytics reports yet.")
+            : "",
+        };
+        if (subjects.length === 0) {
+          latest = { ...base, noEmpty: false };
+          return latest;
+        }
+        latest = base;
+        return base;
+      } catch (e) {
+        // The guard covers the FAILURE path too. Without it a stale rejection —
+        // the module-scope boot load, or an older retry — lands after a newer
+        // load or query has advanced `seq` and paints the error arm over a ready
+        // report. `runQuery`'s catch already did this; these two did not, which
+        // made the failure path inconsistent with the success path right beside
+        // it. (AI-review finding on #2533.)
+        if (mine !== seq) return latest ?? s ?? { ...empty };
+        const out = errorState(s, String((e as Error)?.message ?? e));
+        latest = out;
+        return out;
+      }
+    },
+
+    /**
+     * Step 2 — read the chosen model's schema and query it.
+     *
+     * The id is checked against the list this worker actually fetched. A
+     * fabricated or stale id returns SEMANTIC_MODEL_NOT_FOUND, and refusing it
+     * here keeps that out of the error state, where it would read as the site
+     * being broken rather than as a bad pick.
+     */
+    selectSubject: async (s, arg) => {
+      stashCopy(arg);
+      const id = argStr(arg, "id");
+      if (!known.some((m) => m.id === id)) return latest ?? s;
+      const mine = ++seq;
+      pendingSubject = { id, seq: mine };
+      try {
+        const model = await getSemanticModel(id);
+        if (mine !== seq) return latest ?? s;
+        schema = { id, model };
+        // First dimension and first measure, so the screen shows a real report
+        // rather than a third empty picker. Both are the model's own, in its own
+        // order — never inferred from the slug (guard rail 2).
+        const dimension = model.dimensions[0];
+        const measure = model.measures[0];
+        const chosen: ReportState = {
+          ...s,
+          subjectId: id,
+          subjectLabel: s.subjects.find((r) => r.id === id)?.label ?? subjectLabelOf(model),
+          subjects: markSelected(s.subjects, id),
+          dimensions: markSelected(
+            model.dimensions.map((f) => ({ id: f.name, label: fieldLabel(f), state: "" })),
+            dimension?.name ?? "",
+          ),
+          measures: markSelected(
+            model.measures.map((f) => ({ id: f.name, label: fieldLabel(f), state: "" })),
+            measure?.name ?? "",
+          ),
+          dimensionName: dimension?.name ?? "",
+          dimensionLabel: dimension ? fieldLabel(dimension) : "",
+          measureName: measure?.name ?? "",
+          measureLabel: measure ? fieldLabel(measure) : "",
+          noFields: false,
+          rows: [], totals: null, rowCount: "", missingFields: "",
+          noGap: true, hideTable: true,
+        };
+        // A model with no measures cannot be queried. Say so instead of firing a
+        // request the SDK will reject for having no fields.
+        if (!dimension || !measure) {
+          const out: ReportState = {
+            ...chosen,
+            noEmpty: false,
+            emptyText: copyParam("ownerReport.noFieldsForModel", "This report has no measures to chart."),
+          };
+          latest = out;
+          return out;
+        }
+        // The range from the NEWEST state, not from our snapshot. `setRange`
+        // deliberately does not advance `seq` when no subject exists, so a chip
+        // tapped while this schema fetch was in flight lives in `latest` and
+        // not in `s` — resuming with `s.rangeId` published a 30-day report and
+        // repainted the chip the owner had already moved to 7.
+        const days = parseInt((latest ?? s).rangeId, 10) || 30;
+        const ranged = { ...chosen, rangeId: String(days), range: rangeLabel(days) };
+        const ran = await runQuery(ranged, days);
+        return typeof ran === "string" ? publish(ranged) : ran;
+      } catch (e) {
+        // Same hole, same reason: tap subject A then B, and A's rejection
+        // arriving late must not replace B's selection with the error arm.
+        if (mine !== seq) return latest ?? s;
+        const out = errorState(s, String((e as Error)?.message ?? e));
+        latest = out;
+        return out;
+      } finally {
+        // Only the generation that TOOK the latch may release it — comparing
+        // the id instead let a superseded same-subject tap clear a newer
+        // request's latch.
+        if (pendingSubject && pendingSubject.seq === mine) pendingSubject = null;
+      }
+    },
+
+    /** Step 3 — re-query on a dimension pick. Field names come from the schema. */
+    selectDimension: async (s, arg) => {
+      stashCopy(arg);
+      const name = argStr(arg, "id");
+      const field = schemaFor(s.subjectId)?.dimensions.find((f) => f.name === name);
+      if (!field) return latest ?? s;
+      const picked = {
+        ...s,
+        dimensionName: name,
+        dimensionLabel: fieldLabel(field),
+        dimensions: markSelected(s.dimensions, name),
+      };
+      const ran = await runQuery(picked, parseInt(s.rangeId, 10) || 30);
+      // Stale: something newer is already on screen, so yield to it rather than
+      // republishing this pick over it. Incomplete: this pick IS the newest.
+      if (ran === "stale") return latest ?? s;
+      return ran === "incomplete" ? publish(picked) : ran;
+    },
+
+    /** Step 3 — re-query on a measure pick. */
+    selectMeasure: async (s, arg) => {
+      stashCopy(arg);
+      const name = argStr(arg, "id");
+      const field = schemaFor(s.subjectId)?.measures.find((f) => f.name === name);
+      if (!field) return latest ?? s;
+      const picked = {
+        ...s,
+        measureName: name,
+        measureLabel: fieldLabel(field),
+        measures: markSelected(s.measures, name),
+      };
+      const ran = await runQuery(picked, parseInt(s.rangeId, 10) || 30);
+      if (ran === "stale") return latest ?? s;
+      return ran === "incomplete" ? publish(picked) : ran;
+    },
+
+    /**
+     * The range chips. `selectedId` is what the renderer injects (see argStr).
+     *
+     * The chosen window is the owner's and STICKS, whether or not a query was
+     * possible. Before a subject is picked `runQuery` declines — correctly,
+     * there is nothing to query — and returning its result alone dropped the
+     * new `rangeId`: the chip moved to "7 days" and the state stayed on 30, so
+     * the first report the owner ran came back as 30 days under a chip reading
+     * 7. That is the inert-control class this bundle's sibling documents, and
+     * the derived crawl flagged it the moment it appeared.
+     *
+     * A dispatch from a subject the owner has LEFT is the one case that must
+     * not move the chip, since the chip now belongs to a different report.
+     */
+    setRange: async (s, arg) => {
+      const n = parseInt(argStr(arg, "selectedId") || "30", 10);
+      const days = RANGES.includes(n) ? n : 30;
+      if (latest && s.subjectId !== latest.subjectId) return latest;
+      const next = { ...s, rangeId: String(days), range: rangeLabel(days) };
+      const out = await runQuery(next, days);
+      if (out === "stale") return latest ?? s;
+      // INCOMPLETE: nothing to query yet, so the owner's chip sticks on the
+      // newest state. RAN or SUPERSEDED: `out` already carries the window that
+      // actually produced the rows on screen — stamping this tap's label onto a
+      // newer result would show the newer query's rows under the older chip.
+      return out === "incomplete"
+        ? publish({ ...(latest ?? next), rangeId: next.rangeId, range: next.range })
+        : out;
+    },
+
+    /**
+     * Totals are opt-in and come from the server.
+     *
+     * Re-queries rather than summing the rows on hand: a `unique` measure is not
+     * additive (the same visitor in two buckets is one visitor), so a local sum
+     * would over-report — silently, and upward.
+     */
+    toggleTotals: async (s) => {
+      const next = { ...s, noTotals: !s.noTotals };
+      next.totalsState = next.noTotals
+        ? copyParam("ownerReport.off", "Off")
+        : copyParam("ownerReport.on", "On");
+      // Same rule as the range chip: the owner's toggle sticks when there is
+      // nothing to re-query, and yields when the screen has moved on.
+      const ran = await runQuery(next, parseInt(s.rangeId, 10) || 30);
+      if (ran === "stale") return latest ?? s;
+      return ran === "incomplete" ? publish(next) : ran;
+    },
+  },
+});
+
+// Boot the list, at module scope, exactly as the highlights service does.
+//
+// This was originally left out on the reasoning that both services share a
+// bundle, so a module-scope request here also fires when the HIGHLIGHTS screen
+// is the one on screen — a wasted `listSemanticModels()` per open. The derived
+// crawl rejected that, and it was right: it judges every service a bundle
+// registers, on every screen that bundle serves, and a service sitting at
+// `status: "loading"` forever is the stuck-skeleton class —
+//
+//   service "ownerLiteAnalyticsReport" never left its loading state
+//
+// on both `himi_owner_lite_analytics` and `himi_owner_lite_analytics_measure`.
+// The initial `loading` status is load-bearing for THIS screen's first paint
+// (there is no intermediate publish; the skeleton is what the pre-load snapshot
+// renders), so the state cannot simply start settled. One cheap list GET on a
+// sibling screen is the honest price of a service that always settles.
+svc.load();
+
+export { svc };
+export type { ReportState, ReportRow, PickRow };