@wix/himalaya-cli 0.923.0 → 0.925.0

package/dist/cli.mjs

@@ -5241,7 +5241,6 @@ function resolveTranslation(value, catalog, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
-    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s) => s !== "t").join("|")})\\b|^\\$t:`
@@ -18526,6 +18525,7 @@ function shouldRevealError(args) {
 var EMAIL_RE, URL_HOST_RE, INTEGER_RE, NUMBER_RE;
 var init_validation = __esm({
   "../../core/ts/src/validation.ts"() {
+    "use strict";
     EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
     URL_HOST_RE = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]+)?$/;
     INTEGER_RE = /^[+-]?[0-9]+$/;
@@ -21949,6 +21949,7 @@ function validateWorkerSubtree(raw, slotId, policy, actionCatalog) {
 var WORKER_SUBTREE_CEILINGS, ID_PART, ACTION_ID;
 var init_worker_subtree = __esm({
   "../../core/ts/src/worker-subtree.ts"() {
+    "use strict";
     init_worker_subtree_safe_types_generated();
     WORKER_SUBTREE_CEILINGS = Object.freeze({
       maxEncodedBytes: 65536,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.923.0",
+  "version": "0.925.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -64,5 +64,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "262349f863d8ab9c7b65ca75bd82e84b2c0943fc0e412bdfa9eeb40c"
+  "falconPackageHash": "f7e299bf4530163cb8143700d0c7ad83fed1966b5f6f73a47e960356"
 }

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-ask/blocks.ts

@@ -20,7 +20,7 @@ import type { EmptyStateProps } from "@himalaya/core";
 import type { AskBlock, AskPlan, Tone } from "./grammar.js";
 import { MAX_DETAIL_FIELDS, MAX_ROWS, MAX_STATS } from "./grammar.js";
 import {
-  DETAIL_SCREEN, ENTITY_FIELDS, ENTITY_MEDIA, IMAGE_KEY, hasField, isEntity, titleFieldFor, type QueryResult,
+  DETAIL_SCREEN, ENTITY_FIELDS, ENTITY_MEDIA, IMAGE_KEY, STRICT_ENTITIES, hasField, isEntity, titleFieldFor, type QueryResult,
 } from "./catalog.js";
 
 /** Typed pass-through so `tsc` checks EmptyState's prop NAMES against the schema.
@@ -256,7 +256,94 @@ function statsBlock(
     .map((stat) => {
       const label = cleanCopy(stat.label);
       const named = queryNameOf(stat.valuePath);
-      if (named && results[named]) return { label, path: rewritePath(stat.valuePath), tone: stat.tone };
+      if (named && results[named]) {
+        // A ROW-INDEXED stat (`$q.x.rows.0.value`) is only honest when that row
+        // exists AND is unambiguous. Two ways it used to lie, both silent:
+        //
+        //   * The query returned NOTHING. `stats` is not in DATA_KINDS, so the
+        //     empty-state swap below never fires for it — the card bound to a
+        //     row that is not there and the renderer painted its "—" boot
+        //     placeholder for ever. Every refusal path in this worker produces
+        //     an empty result, so every refusal rendered as three dashes.
+        //   * The query returned MANY. `rows.0` is then whichever row the
+        //     fetch happened to build first, presented as the answer. For
+        //     metrics that is always the 7-day sessions row, so an unnarrowed
+        //     "how did sales do over 60 days" answered with 7-day traffic.
+        //
+        // Both are dropped with a named repair instead, which the owner sees.
+        // ANCHORED to the whole path, not a substring match on `.rows.<n>.`.
+        // An unanchored test matched anywhere, so `$q.traffic.groups.0.rows.0.value`
+        // entered the row branch, `field` came out as "value", `hasField` passed,
+        // and a binding was emitted through a `groups.0.rows` path the result does
+        // not have — recreating the blank stat this guard exists to prevent.
+        // The accepted shape is exactly `$q.<query>.rows.<n>.<field>`, and the
+        // capture groups give the index and the field directly rather than being
+        // sliced back out of the string.
+        const rowRef = /^\$q\.[A-Za-z][A-Za-z0-9_-]{0,63}\.rows\.(\d+)\.([A-Za-z][A-Za-z0-9_]*)$/
+          .exec(stat.valuePath ?? "");
+        const result = results[named];
+        // MATCHES, not `rows.length`. `runQuery` computes `count` BEFORE
+        // applying `limit` and slices `rows` after, so `limit:1` made a query
+        // that matched all three windows look like a single unambiguous row —
+        // and `rows.0` then rendered the 7-day figure as the answer to a
+        // 60-day question. Judging cardinality on the post-limit array is the
+        // same bug the guard was added to close, one layer down.
+        const matches = result.count;
+        const strict = STRICT_ENTITIES.includes(result.entity);
+        if (rowRef) {
+          const wanted = Number(rowRef[1]);
+          if (matches === 0) {
+            repairs.push(`stat "${label}": that query found nothing — dropped`);
+            return { label, path: "", tone: stat.tone };
+          }
+          // ANY index, not just 0. The invariant is "no row-indexed stat over
+          // a multi-row strict result" — `rows.1` of a broad metrics query is
+          // exactly as arbitrary as `rows.0`, and scoping the guard to index 0
+          // left `limit:2` as a way back in.
+          if (strict && matches > 1) {
+            repairs.push(`stat "${label}": ${matches} rows matched, so no single figure — dropped`);
+            return { label, path: "", tone: stat.tone };
+          }
+          if (wanted >= result.rows.length) {
+            repairs.push(`stat "${label}": row ${wanted} of ${result.rows.length} does not exist — dropped`);
+            return { label, path: "", tone: stat.tone };
+          }
+          // The FIELD has to exist too. `$q.traffic.rows.0.typo` is
+          // syntactically valid, so `rewritePath` happily emits a binding for
+          // it and the renderer draws a blank where the figure belongs — a
+          // missing number that reports itself as nothing rather than as a
+          // dropped figure. The declared contract is the authority, exactly as
+          // it is for a list's `titleField`.
+          const field = rowRef[2];
+          if (!hasField(result.entity, field)) {
+            repairs.push(`stat "${label}": no field "${field}" on ${result.entity || "that query"} — dropped`);
+            return { label, path: "", tone: stat.tone };
+          }
+        } else if (strict) {
+          // NOT A ROW PATH, on a strict entity — refused, whatever shape it is.
+          //
+          // This is an ALLOWLIST, and it is deliberately the third revision of
+          // this guard rather than a fourth special case. Each earlier version
+          // blocked the bad shape it had just been shown and left the next one
+          // open: `.count` was refused by name, so `$q.traffic.value` walked
+          // straight past it — `named` resolves, there is no row reference, it
+          // does not end in `.count`, and `rewritePath` emitted a binding for a
+          // top-level field the result does not have. Another blank where the
+          // figure belongs.
+          //
+          // A strict entity keeps its figure at `rows.<n>.<field>` and nowhere
+          // else, so that is the ONLY shape accepted. `.count` keeps its own
+          // message because it is the mistake the response schema actively
+          // invites, and saying "that is a row count" is more use than "wrong
+          // shape".
+          const why = /\.count$/.test(stat.valuePath ?? "")
+            ? ".count is a row count, not a measure"
+            : "a measure lives at rows.<n>.<field>, not at the top level";
+          repairs.push(`stat "${label}": ${why} — dropped`);
+          return { label, path: "", tone: stat.tone };
+        }
+        return { label, path: rewritePath(stat.valuePath), tone: stat.tone };
+      }
       const why = named ? `unknown query "${named}"` : "malformed valuePath";
       if (names.length === 1) {
         repairs.push(`stat "${label}": ${why} → bound to ${names[0]}`);

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-ask/catalog.ts

@@ -18,7 +18,7 @@ import {
   DEMO_PRODUCTS, DEMO_SERVICES, DEMO_ORDERS, DEMO_POSTS, DEMO_EVENTS, DEMO_APPOINTMENTS, demoOrderDate, demoAppointmentWindow,
 } from "../_shared/owner-preview-demo.js";
 import { ENTITIES, QUERY_LIMIT, type AskQuery, type EntityName } from "./grammar.js";
-import { compareText, formatWeekdayDateTime } from "../_shared/engine-intl.js";
+import { compareText, formatWeekdayDateTime, formatNumber } from "../_shared/engine-intl.js";
 
 export type Row = Record<string, string>;
 
@@ -31,6 +31,13 @@ export const ENTITY_FIELDS: Record<EntityName, string[]> = {
   posts: ["id", "title", "status", "category", "published"],
   events: ["id", "title", "date", "location", "status", "registration"],
   appointments: ["id", "service", "client", "time", "status"],
+  // Site analytics. One row PER MEASURE, not per day: the row carries
+  // its own provenance, because the acceptance bar is that an answer "names the
+  // window it used and the measure it read" — carrying those as FIELDS makes
+  // that structural instead of something the prompt has to remember to say.
+  // `value` is the formatted figure a `stats` block binds via
+  // `$q.<name>.rows.0.value`; `amount` is the same number unformatted, for sorting.
+  metrics: ["id", "measure", "value", "amount", "window", "days"],
 };
 
 /**
@@ -58,6 +65,9 @@ export const ENTITY_FIELDS: Record<EntityName, string[]> = {
 export const ENTITY_MEDIA: Record<EntityName, { image?: string; badge?: string }> = {
   products: { image: "image" },
   services: {},
+  // A measure has no image and no status. `value` is the figure itself, not a
+  // badge — styling it as one would read as a state rather than a number.
+  metrics: {},
   orders: { badge: "payment" },
   posts: { image: "image", badge: "status" },
   events: { image: "image", badge: "status" },
@@ -77,14 +87,113 @@ export const DETAIL_SCREEN: Record<EntityName, string> = {
   posts: "himi_owner_lite_post",
   events: "himi_owner_lite_event",
   appointments: "",
+  // A measure has no per-record detail screen; `openEntity` already resolves an
+  // empty value to nothing rather than a dead push.
+  metrics: "",
 };
 
 /** Human label per entity, used in summaries and the "open" affordance. */
 const SINGULAR: Record<EntityName, string> = {
   products: "product", services: "service", orders: "order",
   posts: "post", events: "event", appointments: "appointment",
+  metrics: "measure",
 };
 
+/**
+ * The measures Ask can answer for, and the windows it can answer over.
+ *
+ * Deliberately the SAME six measures and the SAME 7/30/60 windows as
+ * `himi_owner_lite_analytics`, off the same endpoint. That is what makes "the
+ * number can be reconciled against the Analytics screen" true by construction
+ * rather than by coincidence — two engines answering one question differently
+ * is the worst outcome an analytics feature can have.
+ *
+ * No 90-day window: the endpoint retains 62 days, so it was never servable.
+ */
+export const METRIC_MEASURES: { key: string; api: string; label: string; money?: boolean }[] = [
+  { key: "sessions", api: "TOTAL_SESSIONS", label: "Site sessions" },
+  { key: "visitors", api: "TOTAL_UNIQUE_VISITORS", label: "Unique visitors" },
+  { key: "sales", api: "TOTAL_SALES", label: "Total sales", money: true },
+  { key: "orders", api: "TOTAL_ORDERS", label: "Total orders" },
+  { key: "forms", api: "TOTAL_FORMS_SUBMITTED", label: "Forms submitted" },
+  { key: "contacts", api: "CLICKS_TO_CONTACT", label: "Clicks to contact" },
+];
+
+export const METRIC_WINDOWS = [7, 30, 60];
+
+/**
+ * Shape fetched measurements into metric rows. PURE, and separate from the
+ * fetch in live.ts precisely so the rule below is testable without a network.
+ *
+ * A measure the site does not report is OMITTED, never zeroed. "0 sales" and
+ * "we have no sales figure" are different answers and only one of them is true
+ * — this is the same rule the Semantic Model expresses as `missingFields`, and
+ * it is the one that keeps a silent gap from rendering as a real zero.
+ */
+export function metricRowsFrom(
+  windows: { days: number; data: { type?: string; total?: unknown; values?: { value?: unknown }[] }[] }[],
+): Row[] {
+  const rows: Row[] = [];
+  for (const { days, data } of windows) {
+    for (const m of METRIC_MEASURES) {
+      const found = data.find((d) => d?.type === m.api);
+      if (!found) continue;
+      // `total` is OPTIONAL on the wire and some measures arrive as the daily
+      // series alone. The Analytics screen sums the series in that case
+      // (`total()`, himi-owner-lite-analytics/index.ts:224); omitting the
+      // measure here instead would make the two screens disagree about the
+      // same window, which is the one thing reading this endpoint rules out.
+      const hasTotal = typeof found.total === "number";
+      // At least one FINITE NUMERIC point, not merely a non-empty array. A
+      // series of entries whose `value` is absent or non-numeric summed to 0,
+      // `Number.isFinite(0)` passed, and Ask rendered 0 as though the endpoint
+      // had reported it — reintroducing the exact omission-vs-reported-zero
+      // confusion this rule exists to prevent, one layer in.
+      const points = (found.values ?? [])
+        .map((v) => v?.value)
+        .filter((v): v is number => typeof v === "number" && Number.isFinite(v));
+      if (!hasTotal && points.length === 0) continue;
+      const total = hasTotal
+        ? (found.total as number)
+        : points.reduce((sum, v) => sum + v, 0);
+      // A NaN/Infinity scalar total is not a figure either.
+      if (!Number.isFinite(total)) continue;
+      rows.push({
+        id: `${m.key}-${days}`,
+        measure: m.label,
+        // Rounded EXACTLY as himi_owner_lite_analytics rounds it, so the two
+        // screens cannot disagree in the last digit about the same measure.
+        // NO currency symbol, and that is not an omission. The Analytics
+        // screen's fmtMoney is `formatNumber(round(n*100)/100)` with no symbol
+        // (himi-owner-lite-analytics/index.ts:241). Adding one here would make
+        // the two screens render the SAME number differently — breaking the
+        // reconciliation this endpoint choice exists to guarantee — and would
+        // show a euro sign to a USD, GBP or ILS site. Every other money value
+        // in this bundle comes from the API's own formattedAmount for that
+        // same reason.
+        value: m.money
+          ? formatNumber(Math.round(total * 100) / 100)
+          : String(Math.round(total)),
+        // The same number unformatted, so orderBy:amount sorts numerically
+        // rather than lexically ("9" > "1,240" as text).
+        amount: String(total),
+        window: `Last ${days} days`,
+        days: String(days),
+      });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Entities whose queries must FAIL rather than broaden (see `runQuery`).
+ *
+ * The test is "would an over-broad answer still look like an answer?" A list
+ * shows its rows and the owner can see it is wider than they asked. A single
+ * figure shows one number and nothing about it says which window produced it.
+ */
+export const STRICT_ENTITIES: readonly string[] = ["metrics"];
+
 export function isEntity(name: string): name is EntityName {
   return (ENTITIES as readonly string[]).includes(name);
 }
@@ -93,6 +202,7 @@ export function isEntity(name: string): name is EntityName {
 const TITLE_FIELD: Record<EntityName, string> = {
   products: "name", services: "name", orders: "number",
   posts: "title", events: "title", appointments: "service",
+  metrics: "measure",
 };
 
 export function titleFieldFor(entity: EntityName): string {
@@ -114,6 +224,14 @@ export function singular(entity: EntityName): string {
  *  (web preview, RFC 0049). On a device this is never what the owner sees. */
 export function demoRows(entity: EntityName): Row[] {
   switch (entity) {
+    // NO sample metrics, and this is the point rather than an omission.
+    // A sample product reads as a sample product; a sample "1,240 sessions"
+    // is indistinguishable from the owner's real traffic, and inventing one
+    // is the single failure this screen family refuses — the Analytics screen
+    // deliberately has no demo mode for the same reason. An empty result
+    // renders the honest empty block instead.
+    case "metrics":
+      return [];
     case "products":
       return DEMO_PRODUCTS.map((p) => ({
         id: p.id, name: p.name, price: p.price, sku: p.sku,
@@ -194,8 +312,10 @@ function matches(row: Row, field: string, op: string, value: string): boolean {
 }
 
 /** Execute one declared query against ALREADY-LOADED rows. Unknown entity →
- *  EMPTY_RESULT; unknown field in a where/orderBy/groupBy → that clause is
- *  ignored (fail-soft, never guess).
+ *  EMPTY_RESULT. Unknown field in a where/orderBy/groupBy → that clause is
+ *  ignored (fail-soft, never guess) for an ordinary entity, and the whole query
+ *  returns empty for a STRICT_ENTITIES one, where broadening would read as an
+ *  answer rather than as a wider list.
  *
  *  Pure and synchronous BY DESIGN: fetching is `loadEntityRows`, one call per
  *  distinct entity per turn (`index.ts`), so three queries over `orders` cost
@@ -205,14 +325,45 @@ export function runQuery(query: AskQuery, all: Row[]): QueryResult {
   if (!isEntity(query.entity)) return EMPTY_RESULT;
   const fields = ENTITY_FIELDS[query.entity];
 
+  // STRICT ENTITIES FAIL CLOSED ON AN UNKNOWN CLAUSE.
+  //
+  // The default below is permissive: an undeclared `where` field is skipped and
+  // the query BROADENS. For a product list that is a mildly over-wide list. For
+  // a measure it is a total for the wrong window rendered as the answer — and
+  // invisibly, because nothing records the skip (`QueryResult` has no repair
+  // channel, and `repairs`/`dropped` are populated only in blocks.ts, which
+  // never sees the clause). Worse, `summary` below reads `filtered` off
+  // `count !== all.length`, so a dropped filter makes it say "12 orders"
+  // instead of "3 of 12", concealing that a filter was asked for at all.
+  //
+  // That is precisely the "confident wrong number" this screen family exists to
+  // refuse, so `metrics` refuses instead: an unsatisfiable clause yields NO
+  // rows, and the block renders its honest empty state.
+  const strict = STRICT_ENTITIES.includes(query.entity);
+  /** A strict refusal, worded so it reaches the provenance line. An empty
+   *  `summary` contributes nothing to `index.ts`'s note, which would leave a
+   *  refusal indistinguishable on screen from the broadening it replaced. */
+  const refuse = (why: string): QueryResult => ({
+    ...EMPTY_RESULT, entity: query.entity, summary: `no ${SINGULAR[query.entity]} matched ${"—"} ${why}`,
+  });
+
+  // A clause the GRAMMAR could not parse never reaches the loop below, so it
+  // has to be refused here or the query silently runs unfiltered.
+  if (strict && query.malformed) return refuse("that filter isn't expressible");
+
   let rows = all;
   for (const clause of query.where ?? []) {
-    if (!fields.includes(clause.field)) continue;
+    if (!fields.includes(clause.field)) {
+      if (strict) return refuse(`no such field "${clause.field}"`);
+      continue;
+    }
     rows = rows.filter((row) => matches(row, clause.field, clause.op ?? "eq", clause.value));
   }
   const count = rows.length;
 
   const order = query.orderBy;
+  if (order && strict && !fields.includes(order.field)) return refuse(`no such field "${order.field}"`);
+  if (query.groupBy && strict && !fields.includes(query.groupBy)) return refuse(`no such field "${query.groupBy}"`);
   if (order && fields.includes(order.field)) {
     const dir = order.direction === "asc" ? 1 : -1;
     rows = rows.slice().sort((a, b) => {

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-ask/grammar.ts

@@ -22,7 +22,7 @@
 // what doesn't hold). Robustness beats schema elegance at the model boundary.
 
 /** Entity names the model may query. Mirrors ENTITY_FIELDS in catalog.ts. */
-export const ENTITIES = ["products", "services", "orders", "posts", "events", "appointments"] as const;
+export const ENTITIES = ["products", "services", "orders", "posts", "events", "appointments", "metrics"] as const;
 export type EntityName = (typeof ENTITIES)[number];
 
 /** The action ids a GENERATED tree may reference. Deliberately narrower than the
@@ -84,6 +84,10 @@ export interface AskWhere {
 }
 
 export interface AskQuery {
+  /** A `where` segment the grammar could not parse. Fail-soft entities ignore
+   *  it; STRICT ones refuse, because a filter that silently disappeared is the
+   *  difference between the answer asked for and a wider one. */
+  malformed?: boolean;
   /** Referenced by blocks as `$q.<name>.…`. */
   name: string;
   entity: EntityName;
@@ -118,11 +122,24 @@ export function parseQueryLine(line: unknown): AskQuery | null {
     if (colon < 0) continue;
     const key = segment.slice(0, colon).trim().toLowerCase();
     const value = segment.slice(colon + 1).trim();
-    if (!value) continue;
+    if (!value) {
+      // An empty value on a NARROWING key is a filter the model meant to apply
+      // and did not manage to express — `where:` with nothing after it. Skipping
+      // it silently (as this did) drops the constraint before `runQuery` can see
+      // it, which is the same hole the unparseable-segment case had: a strict
+      // entity cannot refuse what never reached it, so the query broadens.
+      if (key === "where" || key === "orderby" || key === "groupby") query.malformed = true;
+      continue;
+    }
     if (key === "where") {
       // field=value | field!=value | field~value (contains)
       const match = value.match(/^([A-Za-z][A-Za-z0-9_]*)\s*(!=|~|=)\s*(.+)$/);
-      if (!match) continue;
+      // A segment this grammar cannot express (`days>=30`, `days > 30`,
+      // `measure contains sessions`) used to vanish here, BEFORE `runQuery`
+      // could see it — so a strict entity could not refuse what it never knew
+      // was asked for, and the query ran unfiltered. Record it instead; the
+      // fail-soft entities still ignore it exactly as before.
+      if (!match) { query.malformed = true; continue; }
       const op = match[2] === "!=" ? "ne" : match[2] === "~" ? "contains" : "eq";
       (query.where ??= []).push({ field: match[1], op, value: match[3] });
     } else if (key === "groupby") {
@@ -228,7 +245,14 @@ export const ASK_RESPONSE_SCHEMA: Record<string, unknown> = {
                 label: { type: "string" },
                 // Descriptions carry real weight in structured output — without
                 // these the model invented its own path syntax (`@queries[0]`).
-                valuePath: { type: "string", description: "Must be exactly $q.<queryName>.count" },
+                valuePath: {
+                  type: "string",
+                  description:
+                    "Either $q.<queryName>.count (how many rows matched) or "
+                    + "$q.<queryName>.rows.0.<field> (a field of the single matching row). "
+                    + "For a metrics query ALWAYS use rows.0.value — count is the number of "
+                    + "matching rows, not the measurement, and is never the answer.",
+                },
                 tone: { type: "string", enum: [...TONES] },
               },
             },
@@ -291,7 +315,9 @@ export const ASK_SYSTEM_PROMPT = [
   "   (where also supports field!=value and field~value for contains). Give each a short `name`.",
   "2. Reference query results from blocks with `$q.<name>.<field>`, where <field> is",
   "   one of: count (a number), rows (the records), groups (present only when the",
-  "   query sets groupBy), summary (a short human string).",
+  "   query sets groupBy), summary (a short human string). A single row's field is",
+  "   `$q.<name>.rows.0.<field>` — this is how a stats block shows a measure,",
+  "   because count is a ROW COUNT and is never the figure a measure question wants.",
   "3. NEVER put record values, names, numbers or dates in your output. Those come",
   "   from the query at render time. Only labels, headings and explanatory prose",
   "   are yours to write. Inventing an order number or a customer name is a bug.",
@@ -311,6 +337,25 @@ export const ASK_SYSTEM_PROMPT = [
   "- callout — the finding itself when it needs to outrank the data ('2 unpaid orders').",
   "- note    — explanation or a caveat.",
   "",
+  "Analytics questions (traffic, visitors, sales, orders, forms, clicks to contact):",
+  "use the `metrics` entity. It holds ONE ROW PER MEASURE PER WINDOW, and the only",
+  "windows that exist are days=7, days=30 and days=60 — the endpoint retains 62 days,",
+  "so anything longer has no answer and you must say so rather than approximate it.",
+  "Select with BOTH a measure and a window, e.g.:",
+  '  "traffic;metrics;where:measure=Site sessions;where:days=30;limit:1"',
+  "then bind the figure with `$q.traffic.rows.0.value`, and name the window and the",
+  "measure in your own label — `$q.traffic.rows.0.window` and `.measure` carry them,",
+  "so the owner can reconcile the number against the Analytics screen.",
+  "To compare measures, order by `amount` and never by `value`: `value` is the",
+  "display string (\"1,240\"), and sorting it numerically stops at the group",
+  "separator, so it would rank 1,240 below 9. `amount` is the same number raw.",
+  "NEVER write a date into a metrics query. `where:days=30` is relative and stays",
+  "correct when this plan is replayed tomorrow; `where:date=2026-09-21` would be",
+  "replayed as yesterday's window while the screen says the figures are live.",
+  "If the question needs a measure or a window that is not in the list above, say so",
+  "in a `note` and do not substitute a nearer one — a number for a window the owner",
+  "did not ask about is worse than telling them it is not available.",
+  "",
   "Proposing a change: set onTap.verb on a list block when the owner would",
   "plausibly want to act on those rows (`delete` for junk, `hide` for a product",
   "that shouldn't be on sale). You are only SUGGESTING it — the app asks the",

package/templates/beauty-salon-owner/tier5-src/himi-owner-lite-ask/live.ts

@@ -26,8 +26,12 @@ import { queryServices, queryBookings, deleteService, type WixService, type WixB
 import { queryPosts, queryDraftPosts } from "@himalaya/wix-blog";
 import { queryEvents, type WixEvent } from "@himalaya/wix-events";
 import { QUERY_LIMIT, type EntityName } from "./grammar.js";
-import { demoRows, type Row } from "./catalog.js";
+import { demoRows, metricRowsFrom, METRIC_MEASURES, METRIC_WINDOWS, type Row } from "./catalog.js";
 import { formatMonthDay } from "../_shared/engine-intl.js";
+import {
+  getSiteAnalytics, getSiteTimeZone, localDateRange,
+  type WixAnalyticsMeasurement, type WixMeasure,
+} from "@himalaya/wix-analytics";
 
 //
 // One fetch per entity, mapped onto the DECLARED fields. Deliberately flatter
@@ -207,8 +211,74 @@ function bookingRow(b: WixBooking): Row {
 
 /* eslint-enable @typescript-eslint/no-explicit-any */
 
+/**
+ * WHY EVERY COMBINATION IS FETCHED, rather than the one the question asked for.
+ *
+ * `fetchRows` receives an entity and nothing else — the query's `where` clauses
+ * are applied CLIENT-SIDE by `runQuery` afterwards. For a product list that is
+ * harmless. For a measure it would be a disaster: the window is a SERVER-side
+ * parameter, so a `where:window=…` clause filtered client-side over rows fetched
+ * for some other window would answer the wrong period while looking right.
+ *
+ * So every (measure × window) pair is materialised — 6 × 3 = 18 rows, far under
+ * QUERY_LIMIT — and `where:days=…` then selects among rows that are each
+ * genuinely what they claim. A window we do not serve matches no row, and
+ * `metrics` being strict (STRICT_ENTITIES) makes an unknown field refuse
+ * outright rather than broaden.
+ *
+ * Shaping lives in catalog.ts (`metricRowsFrom`) so it is testable without a
+ * network; this function is only the fetch.
+ */
+async function metricRows(): Promise<{ rows: Row[]; failed: number[] }> {
+  // The SITE's zone on every query. The endpoint buckets by whatever zone the
+  // query names and defaults to UTC, so an owner in UTC+3 asking at 01:00 would
+  // otherwise see three hours credited to yesterday — plausibly, and silently.
+  // A FAILED lookup rejects into loadEntityRows' catch; only an ABSENT zone
+  // legitimately falls back to UTC, which is the API's own default.
+  const tz = (await getSiteTimeZone()) ?? "UTC";
+  const types = METRIC_MEASURES.map((m) => m.api as WixMeasure);
+
+  // Per-window, NOT all-or-nothing. `Promise.all` rejects whole on one failure,
+  // which sent every measure to "metrics couldn't be read" — including the
+  // window the owner actually asked about, whose request had succeeded. The
+  // Analytics screen faced the same choice for its comparison window and rode
+  // an ok-flag with the response rather than letting one failure poison the
+  // rest (himi-owner-lite-analytics/index.ts:408). Same here. A window that
+  // fails simply has no rows, so `where:days=<it>` finds nothing and the
+  // answer is refused for THAT window only.
+  const windows = await Promise.all(METRIC_WINDOWS.map(async (days) => {
+    // End-EXCLUSIVE: passing today as the end returns days-1 under an "n days"
+    // label. `localDateRange` also reports the zone it could actually honour
+    // (UTC where there is no ECMA-402), and we send THAT.
+    const { startDate, endDate, effectiveZone } = localDateRange(days, tz);
+    try {
+      const res = await getSiteAnalytics({ startDate, endDate, measurementTypes: types, timeZone: effectiveZone });
+      return { days, data: (res.data ?? []) as WixAnalyticsMeasurement[], ok: true };
+    } catch {
+      // Swallowing this to `[]` made a transient, auth or server failure
+      // indistinguishable from a site with genuinely no traffic: the rows were
+      // simply missing and the turn reported no error at all. The window is
+      // carried out as FAILED so the provenance can say which one could not be
+      // read, while the windows that succeeded still answer.
+      return { days, data: [] as WixAnalyticsMeasurement[], ok: false };
+    }
+  }));
+
+  return {
+    rows: metricRowsFrom(windows.filter((w) => w.ok)),
+    failed: windows.filter((w) => !w.ok).map((w) => w.days),
+  };
+}
+
 async function fetchRows(entity: EntityName): Promise<Row[]> {
   switch (entity) {
+    // Unreachable: `loadEntityRows` branches on metrics BEFORE calling this,
+    // because a metric fetch has a second return channel (which windows
+    // failed) that `Promise<Row[]>` cannot carry. The arm stays so the switch
+    // remains exhaustive over EntityName — that exhaustiveness is what forces
+    // a new entity to be implemented rather than silently returning nothing.
+    case "metrics":
+      throw new Error("metrics rows load through loadEntityRows, not fetchRows");
     case "orders": {
       const res = await searchOrders({
         search: { filter: { archived: false }, sort: [{ fieldName: "createdDate", order: "DESC" }], cursorPaging: { limit: QUERY_LIMIT } },
@@ -263,11 +333,36 @@ async function fetchRows(entity: EntityName): Promise<Row[]> {
  *  An empty LIVE vertical returns [] and stays empty: "you have no unpaid
  *  orders" is a correct answer, and faking rows to avoid it would be a lie. */
 export async function loadEntityRows(entity: EntityName): Promise<{ rows: Row[]; demo: boolean; error: string }> {
-  if (isOwnerPreviewDemo()) return { rows: demoRows(entity), demo: true, error: "" };
+  // `metrics` opts out of BOTH sample arms, not just the bridge one. Returning
+  // zero rows flagged `demo:true` made the turn announce "sample data — sign in
+  // as the site owner…" while nothing had been read and no error was reported:
+  // the owner was told samples were being shown when none existed.
+  if (isOwnerPreviewDemo()) {
+    return entity === "metrics"
+      ? { rows: [], demo: false, error: "analytics needs your real site" }
+      : { rows: demoRows(entity), demo: true, error: "" };
+  }
   try {
+    if (entity === "metrics") {
+      const { rows, failed } = await metricRows();
+      return {
+        rows,
+        demo: false,
+        // Partial availability is reported, not hidden. A window that could not
+        // be read is NOT a window with no traffic, and the difference is the
+        // whole point of this entity.
+        error: failed.length
+          ? `analytics for the ${failed.join(" and ")} day window${failed.length > 1 ? "s" : ""} couldn't be read`
+          : "",
+      };
+    }
     return { rows: await fetchRows(entity), demo: false, error: "" };
   } catch (e) {
-    if (isBridgeUnavailable(e)) return { rows: demoRows(entity), demo: true, error: "" };
+    // `metrics` opts OUT of the sample fallback. For every other entity a
+    // labelled demo row keeps the web preview useful; for a measure it would be
+    // fabricated traffic and revenue, which is the one thing this screen family
+    // refuses. It takes the error arm below instead, exactly as a timeout does.
+    if (isBridgeUnavailable(e) && entity !== "metrics") return { rows: demoRows(entity), demo: true, error: "" };
     return { rows: [], demo: false, error: `${entity} couldn't be read` };
   }
 }