@valbuild/shared 0.148.2 → 0.148.6

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @valbuild/shared
 
+## 0.148.6
+
+### Patch Changes
+
+- [#902](https://github.com/valbuild/val/pull/902) [`b580292`](https://github.com/valbuild/val/commit/b580292ac3c335b055f5ed5f18d6a12d075169c7) Thanks [@freekh](https://github.com/freekh)! - The demo has a script: `<ValApp demo={{ tours, audiences }}>`. Instead of a tour that opens by itself, the demo card asks "What brings you here?" and lists short tours for the answer, each ticked off once done. `/val?tour=<id>` starts one from a link.
+
+  A tour can start on a page of its own (`start`). A step can ask for a new page (`moveOn: { newPage }`), write any value or add one (`moveOn: { edit, value, add }`), and show the code behind what it is about (`code`).
+
+## 0.148.3
+
+### Patch Changes
+
+- [#881](https://github.com/valbuild/val/pull/881) [`0139436`](https://github.com/valbuild/val/commit/0139436426142d91cbb29ec6c696dfb86f34ab9d) Thanks [@freekh](https://github.com/freekh)! - The content analytics script. With analytics on (it is off by default, and turned on in a hosted project's settings), a TanStack site counts which content each visitor's page **rendered** and which they actually **viewed** (at least half on screen for a second), and sends it to `/api/val/analytics`.
+
+  - No cookies, no storage, no visitor IDs. Each page view also says where it came from (the referring site's host and any `utm_source` / `utm_medium` / `utm_campaign`) and whether it was a phone, tablet or desktop.
+  - A page is sent as its route's pattern (`/posts/$postId`), never its address, so a path that holds something about one visitor (an order number, a token) is never stored. `startValAnalytics` takes this as `routeFor`; `ValProvider` passes TanStack's matched route.
+  - Editors are never counted: nothing is sent in draft mode, in the Studio, with Val enabled, or at a proposal's address, and nothing from automated browsers. A page the browser prerenders counts nothing until it is shown.
+  - The script is the new `@valbuild/react/analytics` entry, loaded only for visitors of a site with analytics on, after the page has hydrated. It imports nothing else from Val.
+  - Storing the counts and showing them is part of Val's hosting, which takes these beacons before they reach the site. Anywhere else, `/api/val/analytics` checks each beacon and stores nothing; in local development, with `VAL_DEBUG=1`, it logs a line per beacon, so you can see it working.
+  - `ValProvider`'s Studio check now matches `/val` and what is below it only, not every route starting with those letters (`/values`). The same fix is in `@valbuild/next`.
+
+- [#896](https://github.com/valbuild/val/pull/896) [`5eff8a0`](https://github.com/valbuild/val/commit/5eff8a055a4ef50d476797c28f9c3e50deb73c89) Thanks [@freekh](https://github.com/freekh)! - A demo's tour can now be written by the site: `<ValApp demo={{ tour }}>`, with each step as data (`ValDemoTourStep`), so what it says changes with the site rather than with a Val release.
+
+  It is drawn as a ring around what a step is about, with nothing dimmed and the Studio usable underneath, and a step can move on by itself once the visitor has done what it asks:
+
+  ```ts
+  const tour: ValDemoTourStep[] = [
+    {
+      id: "click",
+      title: "This is Val",
+      body: "Click the heading on the page.",
+      target: "canvas",
+      page: HEADING, // outlined on the page
+      moveOn: { open: HEADING },
+    },
+    {
+      id: "type",
+      title: "Change a word",
+      body: "The page changes as you type.",
+      field: HEADING, // ringed wherever the field is shown
+      moveOn: {
+        edit: true,
+        path: HEADING,
+        value: "Coffee, roasted this weekend",
+      },
+    },
+  ];
+  ```
+
+  A step that moves on has **Do it for me**, which does it the way the Studio would, and **Skip**. On a phone the card is a sheet along the bottom. The Studio's own tour is unchanged.
+
 ## 0.148.2
 
 ### Patch Changes

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -45,6 +45,27 @@ type CookieValue = EnableCookieValue | {
  * this. Shared so client and server agree on the limit.
  */
 export declare const JSON_ENTRIES_BATCH_MAX = 100;
+export declare const AnalyticsBeacon: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    route: z.ZodString;
+    cv: z.ZodOptional<z.ZodString>;
+    view: z.ZodOptional<z.ZodObject<{
+        ref: z.ZodOptional<z.ZodString>;
+        utm: z.ZodOptional<z.ZodObject<{
+            source: z.ZodOptional<z.ZodString>;
+            medium: z.ZodOptional<z.ZodString>;
+            campaign: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        device: z.ZodEnum<{
+            phone: "phone";
+            tablet: "tablet";
+            desktop: "desktop";
+        }>;
+    }, z.core.$strip>>;
+    rendered: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+    viewed: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AnalyticsBeacon = z.infer<typeof AnalyticsBeacon>;
 export declare const Api: {
     "/draft/enable": {
         GET: {
@@ -98,6 +119,24 @@ export declare const Api: {
             }, z.core.$strip>]>;
         };
     };
+    "/analytics": {
+        POST: {
+            req: {
+                body: z.ZodUnknown;
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    counted: z.ZodBoolean;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
     "/draft/stat": {
         GET: {
             req: {

package/dist/declarations/src/internal/demo.d.ts

@@ -1,3 +1,4 @@
+import type { JSONValue } from "@valbuild/core/patch";
 /**
  * A Val demo, as the page hands it to the Studio.
  *
@@ -23,6 +24,151 @@ export type ValDemoRuntime = {
      * refuses uploads before sending anything, and says why.
      */
     uploads: boolean;
+    /**
+     * The tour the site wrote, in place of the Studio's own demo tour. See
+     * `ValDemoTourStep`. Absent: the Studio's.
+     */
+    tour?: ValDemoTourStep[];
+    /** The demo script. See `ValDemoOptions.tours`. */
+    tours?: ValDemoTour[];
+    /** "What brings you here?". See `ValDemoOptions.audiences`. */
+    audiences?: ValDemoAudience[];
+};
+/**
+ * What the site starts the demo with: `<ValApp demo={{ tour }}>`.
+ *
+ * `demo` alone (`true`) is the same with nothing given.
+ */
+export type ValDemoOptions = {
+    /**
+     * One tour, behind the demo card's Tour button, opened on a first visit.
+     * `tours` replaces it: given both, `tours` is used.
+     */
+    tour?: ValDemoTourStep[];
+    /**
+     * The demo script: short tours the visitor picks from on the demo card,
+     * each ticked off once done. A tour can be started from a link too:
+     * `/val?tour=<id>`.
+     */
+    tours?: ValDemoTour[];
+    /**
+     * What the demo card asks first, "What brings you here?": each answer is a
+     * list of `tours`, by id, and the card shows the list for the answer. With
+     * two or more, the Studio adds "Show me everything", all of them in order.
+     * Absent: every tour, in the order given.
+     */
+    audiences?: ValDemoAudience[];
+};
+/** One item of the demo script. */
+export type ValDemoTour = {
+    /** Stable: the answer's list names it, and `?tour=` starts it. */
+    id: string;
+    title: string;
+    /** How long it takes, as the card says it: "30 s", "1 min". */
+    duration?: string;
+    /**
+     * Where the tour starts, as a source path: a page of the site (a page
+     * router's module and the page's key). The Studio goes there first, so a
+     * tour about the home page is not started on whatever page the last one
+     * left open.
+     */
+    start?: string;
+    steps: ValDemoTourStep[];
+};
+/**
+ * An answer to "What brings you here?".
+ *
+ * The first tour of its list is the one the card offers first, with a
+ * button of its own: the one to start with.
+ */
+export type ValDemoAudience = {
+    id: string;
+    /** "I write and edit content". */
+    title: string;
+    /** What the list has in it, in a line: "Pages, photos, languages". */
+    description?: string;
+    /** Tours by id, in order. */
+    tours: string[];
+};
+/**
+ * A control of the Studio's a step can point at.
+ *
+ * The `data-val-tour` markers the Studio puts on them. One that is not on
+ * screen (the rail on a phone) leaves the card on its own, so a step's words
+ * must work without the arrow: never "this button here".
+ */
+export type ValDemoTourTarget = "canvas" | "pages" | "media" | "data" | "review" | "preview" | "publish" | "ai" | "locale" | "demo" | "utility" | "new-page";
+/** A panel a step opens, so what it is about is on screen behind the card. */
+export type ValDemoTourPanel = "pages" | "media" | "data" | "settings" | "ai";
+/**
+ * What moves a step on by itself. A step without one has Next.
+ *
+ * Each is something the visitor does, because doing it is the lesson, and
+ * each has a "Do it for me" that does it the way the Studio would:
+ *
+ * - `open`: a field at or below this source path is opened -- by clicking it
+ *   on the page, or anywhere else. Do it for me opens it.
+ * - `edit`: a change is made. Do it for me writes `value` at `path` --
+ *   replacing what is there, or with `add: true` adding it, as a new entry of
+ *   a record or a new item of a list at that index; without them, it is
+ *   offered nowhere and the step waits for the visitor.
+ * - `newPage`: a page is added. Do it for me adds the page this source path
+ *   names (a page router's module and the new page's key, `?p="/journal/x"`)
+ *   the way the New page form does, empty, and opens it.
+ * - `panel`: that panel is opened. Do it for me opens it.
+ * - `locale`: the language shown is changed. Do it for me picks the next one.
+ */
+export type ValDemoTourMoveOn = {
+    open: string;
+} | {
+    edit: true;
+    path?: string;
+    value?: JSONValue;
+    add?: boolean;
+} | {
+    newPage: string;
+} | {
+    panel: ValDemoTourPanel;
+} | {
+    locale: true;
+};
+/**
+ * One stop of the demo's tour, as the site writes it.
+ *
+ * Data rather than components, so the tour can be rewritten -- and tried on
+ * people -- without a Val release: the Studio draws it, the site says what it
+ * says. Written for someone who has never seen Val.
+ */
+export type ValDemoTourStep = {
+    /** Stable, so a test can name a step without matching its words. */
+    id: string;
+    title: string;
+    body: string;
+    /** The control this step is about. */
+    target?: ValDemoTourTarget;
+    /**
+     * A field this step is about, as a source path: ringed wherever the Studio
+     * shows it -- the page's fields, or the module open in the editor. Takes
+     * precedence over `target`, which is what is ringed when the field is not
+     * on screen.
+     */
+    field?: string;
+    /**
+     * A place on the page this step is about, as a source path: the page
+     * outlines it and brings it into view.
+     */
+    page?: string;
+    panel?: ValDemoTourPanel;
+    moveOn?: ValDemoTourMoveOn;
+    /**
+     * Code to show in the card: the line of a `.val.ts` behind what the step is
+     * about, for a visitor who builds sites. Written by the site, so it has to
+     * be kept the same as the file; `file` says which one.
+     */
+    code?: {
+        file: string;
+        text: string;
+    };
 };
 declare global {
     var __VAL_DEMO__: ValDemoRuntime | undefined;

package/internal/dist/valbuild-shared-internal.cjs.dev.js

@@ -1782,6 +1782,48 @@ var onlyOneIntQueryParam = onlyOneStringQueryParam.refine(function (arg) {
  * this. Shared so client and server agree on the limit.
  */
 var JSON_ENTRIES_BATCH_MAX = 100;
+
+/**
+ * Content analytics, wire format version 1: the beacon the browser script
+ * (`@valbuild/react/analytics`) sends to `POST /api/val/analytics`. Its
+ * `AnalyticsBeacon` type is written by hand there, because that code is on
+ * every visitor's page and must not load zod; `analytics/beacon.test.ts` in
+ * `@valbuild/react` checks that what it builds parses here.
+ */
+/*
+ * The limits the browser script keeps to (`MAX_*` in
+ * `@valbuild/react/analytics`'s `beacon.ts`, which cannot import this). The
+ * endpoint takes anyone's POST, so it checks what it is sent rather than
+ * trusting the sender; `beacon.test.ts` builds beacons at the limits and
+ * parses them here.
+ */
+var MAX_ANALYTICS_PATHS_PER_BEACON = 200;
+var AnalyticsPaths = zod.z.record(zod.z.string().max(512), zod.z.array(zod.z.string().max(1024)).max(MAX_ANALYTICS_PATHS_PER_BEACON));
+var countAnalyticsPaths = function countAnalyticsPaths(paths) {
+  return Object.values(paths).reduce(function (n, list) {
+    return n + list.length;
+  }, 0);
+};
+var AnalyticsBeacon = zod.z.object({
+  v: zod.z.literal(1),
+  route: zod.z.string().max(512),
+  cv: zod.z.string().max(128).optional(),
+  view: zod.z.object({
+    ref: zod.z.string().max(253).optional(),
+    utm: zod.z.object({
+      source: zod.z.string().max(100).optional(),
+      medium: zod.z.string().max(100).optional(),
+      campaign: zod.z.string().max(100).optional()
+    }).optional(),
+    device: zod.z["enum"](["phone", "tablet", "desktop"])
+  }).optional(),
+  rendered: AnalyticsPaths,
+  viewed: AnalyticsPaths
+}).refine(function (beacon) {
+  return countAnalyticsPaths(beacon.rendered) + countAnalyticsPaths(beacon.viewed) <= MAX_ANALYTICS_PATHS_PER_BEACON;
+}, {
+  message: "At most ".concat(MAX_ANALYTICS_PATHS_PER_BEACON, " paths a beacon")
+});
 var Api = {
   "/draft/enable": {
     GET: {
@@ -1827,6 +1869,27 @@ var Api = {
       })])
     }
   },
+  "/analytics": {
+    POST: {
+      // Parsed by the handler rather than here, so a beacon of a version this
+      // server does not know is ignored instead of refused.
+      req: {
+        body: zod.z.unknown()
+      },
+      res: zod.z.union([
+      // `counted` is false wherever nothing stores the counts -- every
+      // server but the hosted platform's, for now.
+      zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          counted: zod.z["boolean"]()
+        })
+      }), zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError
+      })])
+    }
+  },
   "/draft/stat": {
     GET: {
       req: {
@@ -4093,6 +4156,58 @@ function isRetryable(error) {
  * modules. See `docs/plans/demo-mode.md`.
  */
 
+/**
+ * What the site starts the demo with: `<ValApp demo={{ tour }}>`.
+ *
+ * `demo` alone (`true`) is the same with nothing given.
+ */
+
+/** One item of the demo script. */
+
+/**
+ * An answer to "What brings you here?".
+ *
+ * The first tour of its list is the one the card offers first, with a
+ * button of its own: the one to start with.
+ */
+
+/**
+ * A control of the Studio's a step can point at.
+ *
+ * The `data-val-tour` markers the Studio puts on them. One that is not on
+ * screen (the rail on a phone) leaves the card on its own, so a step's words
+ * must work without the arrow: never "this button here".
+ */
+
+/** A panel a step opens, so what it is about is on screen behind the card. */
+
+/**
+ * What moves a step on by itself. A step without one has Next.
+ *
+ * Each is something the visitor does, because doing it is the lesson, and
+ * each has a "Do it for me" that does it the way the Studio would:
+ *
+ * - `open`: a field at or below this source path is opened -- by clicking it
+ *   on the page, or anywhere else. Do it for me opens it.
+ * - `edit`: a change is made. Do it for me writes `value` at `path` --
+ *   replacing what is there, or with `add: true` adding it, as a new entry of
+ *   a record or a new item of a list at that index; without them, it is
+ *   offered nowhere and the step waits for the visitor.
+ * - `newPage`: a page is added. Do it for me adds the page this source path
+ *   names (a page router's module and the new page's key, `?p="/journal/x"`)
+ *   the way the New page form does, empty, and opens it.
+ * - `panel`: that panel is opened. Do it for me opens it.
+ * - `locale`: the language shown is changed. Do it for me picks the next one.
+ */
+
+/**
+ * One stop of the demo's tour, as the site writes it.
+ *
+ * Data rather than components, so the tour can be rewritten -- and tried on
+ * people -- without a Val release: the Studio draws it, the site says what it
+ * says. Written for someone who has never seen Val.
+ */
+
 /*
  * A global `var` rather than a `Window` member: this package is compiled
  * without the DOM's types, and a `var` in global scope is also a property of
@@ -8943,6 +9058,7 @@ exports.parseRoutePattern = getSitemapTree.parseRoutePattern;
 exports.withValCanvasParam = getSitemapTree.withValCanvasParam;
 exports.AA_LARGE = AA_LARGE;
 exports.AA_TEXT = AA_TEXT;
+exports.AnalyticsBeacon = AnalyticsBeacon;
 exports.Api = Api;
 exports.BRAND_CONTRAST_PAIRS = BRAND_CONTRAST_PAIRS;
 exports.BinaryFileRef = BinaryFileRef;

package/internal/dist/valbuild-shared-internal.cjs.prod.js

@@ -1782,6 +1782,48 @@ var onlyOneIntQueryParam = onlyOneStringQueryParam.refine(function (arg) {
  * this. Shared so client and server agree on the limit.
  */
 var JSON_ENTRIES_BATCH_MAX = 100;
+
+/**
+ * Content analytics, wire format version 1: the beacon the browser script
+ * (`@valbuild/react/analytics`) sends to `POST /api/val/analytics`. Its
+ * `AnalyticsBeacon` type is written by hand there, because that code is on
+ * every visitor's page and must not load zod; `analytics/beacon.test.ts` in
+ * `@valbuild/react` checks that what it builds parses here.
+ */
+/*
+ * The limits the browser script keeps to (`MAX_*` in
+ * `@valbuild/react/analytics`'s `beacon.ts`, which cannot import this). The
+ * endpoint takes anyone's POST, so it checks what it is sent rather than
+ * trusting the sender; `beacon.test.ts` builds beacons at the limits and
+ * parses them here.
+ */
+var MAX_ANALYTICS_PATHS_PER_BEACON = 200;
+var AnalyticsPaths = zod.z.record(zod.z.string().max(512), zod.z.array(zod.z.string().max(1024)).max(MAX_ANALYTICS_PATHS_PER_BEACON));
+var countAnalyticsPaths = function countAnalyticsPaths(paths) {
+  return Object.values(paths).reduce(function (n, list) {
+    return n + list.length;
+  }, 0);
+};
+var AnalyticsBeacon = zod.z.object({
+  v: zod.z.literal(1),
+  route: zod.z.string().max(512),
+  cv: zod.z.string().max(128).optional(),
+  view: zod.z.object({
+    ref: zod.z.string().max(253).optional(),
+    utm: zod.z.object({
+      source: zod.z.string().max(100).optional(),
+      medium: zod.z.string().max(100).optional(),
+      campaign: zod.z.string().max(100).optional()
+    }).optional(),
+    device: zod.z["enum"](["phone", "tablet", "desktop"])
+  }).optional(),
+  rendered: AnalyticsPaths,
+  viewed: AnalyticsPaths
+}).refine(function (beacon) {
+  return countAnalyticsPaths(beacon.rendered) + countAnalyticsPaths(beacon.viewed) <= MAX_ANALYTICS_PATHS_PER_BEACON;
+}, {
+  message: "At most ".concat(MAX_ANALYTICS_PATHS_PER_BEACON, " paths a beacon")
+});
 var Api = {
   "/draft/enable": {
     GET: {
@@ -1827,6 +1869,27 @@ var Api = {
       })])
     }
   },
+  "/analytics": {
+    POST: {
+      // Parsed by the handler rather than here, so a beacon of a version this
+      // server does not know is ignored instead of refused.
+      req: {
+        body: zod.z.unknown()
+      },
+      res: zod.z.union([
+      // `counted` is false wherever nothing stores the counts -- every
+      // server but the hosted platform's, for now.
+      zod.z.object({
+        status: zod.z.literal(200),
+        json: zod.z.object({
+          counted: zod.z["boolean"]()
+        })
+      }), zod.z.object({
+        status: zod.z.literal(400),
+        json: GenericError
+      })])
+    }
+  },
   "/draft/stat": {
     GET: {
       req: {
@@ -4093,6 +4156,58 @@ function isRetryable(error) {
  * modules. See `docs/plans/demo-mode.md`.
  */
 
+/**
+ * What the site starts the demo with: `<ValApp demo={{ tour }}>`.
+ *
+ * `demo` alone (`true`) is the same with nothing given.
+ */
+
+/** One item of the demo script. */
+
+/**
+ * An answer to "What brings you here?".
+ *
+ * The first tour of its list is the one the card offers first, with a
+ * button of its own: the one to start with.
+ */
+
+/**
+ * A control of the Studio's a step can point at.
+ *
+ * The `data-val-tour` markers the Studio puts on them. One that is not on
+ * screen (the rail on a phone) leaves the card on its own, so a step's words
+ * must work without the arrow: never "this button here".
+ */
+
+/** A panel a step opens, so what it is about is on screen behind the card. */
+
+/**
+ * What moves a step on by itself. A step without one has Next.
+ *
+ * Each is something the visitor does, because doing it is the lesson, and
+ * each has a "Do it for me" that does it the way the Studio would:
+ *
+ * - `open`: a field at or below this source path is opened -- by clicking it
+ *   on the page, or anywhere else. Do it for me opens it.
+ * - `edit`: a change is made. Do it for me writes `value` at `path` --
+ *   replacing what is there, or with `add: true` adding it, as a new entry of
+ *   a record or a new item of a list at that index; without them, it is
+ *   offered nowhere and the step waits for the visitor.
+ * - `newPage`: a page is added. Do it for me adds the page this source path
+ *   names (a page router's module and the new page's key, `?p="/journal/x"`)
+ *   the way the New page form does, empty, and opens it.
+ * - `panel`: that panel is opened. Do it for me opens it.
+ * - `locale`: the language shown is changed. Do it for me picks the next one.
+ */
+
+/**
+ * One stop of the demo's tour, as the site writes it.
+ *
+ * Data rather than components, so the tour can be rewritten -- and tried on
+ * people -- without a Val release: the Studio draws it, the site says what it
+ * says. Written for someone who has never seen Val.
+ */
+
 /*
  * A global `var` rather than a `Window` member: this package is compiled
  * without the DOM's types, and a `var` in global scope is also a property of
@@ -8943,6 +9058,7 @@ exports.parseRoutePattern = getSitemapTree.parseRoutePattern;
 exports.withValCanvasParam = getSitemapTree.withValCanvasParam;
 exports.AA_LARGE = AA_LARGE;
 exports.AA_TEXT = AA_TEXT;
+exports.AnalyticsBeacon = AnalyticsBeacon;
 exports.Api = Api;
 exports.BRAND_CONTRAST_PAIRS = BRAND_CONTRAST_PAIRS;
 exports.BinaryFileRef = BinaryFileRef;

package/internal/dist/valbuild-shared-internal.esm.js

@@ -1775,6 +1775,48 @@ var onlyOneIntQueryParam = onlyOneStringQueryParam.refine(function (arg) {
  * this. Shared so client and server agree on the limit.
  */
 var JSON_ENTRIES_BATCH_MAX = 100;
+
+/**
+ * Content analytics, wire format version 1: the beacon the browser script
+ * (`@valbuild/react/analytics`) sends to `POST /api/val/analytics`. Its
+ * `AnalyticsBeacon` type is written by hand there, because that code is on
+ * every visitor's page and must not load zod; `analytics/beacon.test.ts` in
+ * `@valbuild/react` checks that what it builds parses here.
+ */
+/*
+ * The limits the browser script keeps to (`MAX_*` in
+ * `@valbuild/react/analytics`'s `beacon.ts`, which cannot import this). The
+ * endpoint takes anyone's POST, so it checks what it is sent rather than
+ * trusting the sender; `beacon.test.ts` builds beacons at the limits and
+ * parses them here.
+ */
+var MAX_ANALYTICS_PATHS_PER_BEACON = 200;
+var AnalyticsPaths = z.record(z.string().max(512), z.array(z.string().max(1024)).max(MAX_ANALYTICS_PATHS_PER_BEACON));
+var countAnalyticsPaths = function countAnalyticsPaths(paths) {
+  return Object.values(paths).reduce(function (n, list) {
+    return n + list.length;
+  }, 0);
+};
+var AnalyticsBeacon = z.object({
+  v: z.literal(1),
+  route: z.string().max(512),
+  cv: z.string().max(128).optional(),
+  view: z.object({
+    ref: z.string().max(253).optional(),
+    utm: z.object({
+      source: z.string().max(100).optional(),
+      medium: z.string().max(100).optional(),
+      campaign: z.string().max(100).optional()
+    }).optional(),
+    device: z["enum"](["phone", "tablet", "desktop"])
+  }).optional(),
+  rendered: AnalyticsPaths,
+  viewed: AnalyticsPaths
+}).refine(function (beacon) {
+  return countAnalyticsPaths(beacon.rendered) + countAnalyticsPaths(beacon.viewed) <= MAX_ANALYTICS_PATHS_PER_BEACON;
+}, {
+  message: "At most ".concat(MAX_ANALYTICS_PATHS_PER_BEACON, " paths a beacon")
+});
 var Api = {
   "/draft/enable": {
     GET: {
@@ -1820,6 +1862,27 @@ var Api = {
       })])
     }
   },
+  "/analytics": {
+    POST: {
+      // Parsed by the handler rather than here, so a beacon of a version this
+      // server does not know is ignored instead of refused.
+      req: {
+        body: z.unknown()
+      },
+      res: z.union([
+      // `counted` is false wherever nothing stores the counts -- every
+      // server but the hosted platform's, for now.
+      z.object({
+        status: z.literal(200),
+        json: z.object({
+          counted: z["boolean"]()
+        })
+      }), z.object({
+        status: z.literal(400),
+        json: GenericError
+      })])
+    }
+  },
   "/draft/stat": {
     GET: {
       req: {
@@ -4086,6 +4149,58 @@ function isRetryable(error) {
  * modules. See `docs/plans/demo-mode.md`.
  */
 
+/**
+ * What the site starts the demo with: `<ValApp demo={{ tour }}>`.
+ *
+ * `demo` alone (`true`) is the same with nothing given.
+ */
+
+/** One item of the demo script. */
+
+/**
+ * An answer to "What brings you here?".
+ *
+ * The first tour of its list is the one the card offers first, with a
+ * button of its own: the one to start with.
+ */
+
+/**
+ * A control of the Studio's a step can point at.
+ *
+ * The `data-val-tour` markers the Studio puts on them. One that is not on
+ * screen (the rail on a phone) leaves the card on its own, so a step's words
+ * must work without the arrow: never "this button here".
+ */
+
+/** A panel a step opens, so what it is about is on screen behind the card. */
+
+/**
+ * What moves a step on by itself. A step without one has Next.
+ *
+ * Each is something the visitor does, because doing it is the lesson, and
+ * each has a "Do it for me" that does it the way the Studio would:
+ *
+ * - `open`: a field at or below this source path is opened -- by clicking it
+ *   on the page, or anywhere else. Do it for me opens it.
+ * - `edit`: a change is made. Do it for me writes `value` at `path` --
+ *   replacing what is there, or with `add: true` adding it, as a new entry of
+ *   a record or a new item of a list at that index; without them, it is
+ *   offered nowhere and the step waits for the visitor.
+ * - `newPage`: a page is added. Do it for me adds the page this source path
+ *   names (a page router's module and the new page's key, `?p="/journal/x"`)
+ *   the way the New page form does, empty, and opens it.
+ * - `panel`: that panel is opened. Do it for me opens it.
+ * - `locale`: the language shown is changed. Do it for me picks the next one.
+ */
+
+/**
+ * One stop of the demo's tour, as the site writes it.
+ *
+ * Data rather than components, so the tour can be rewritten -- and tried on
+ * people -- without a Val release: the Studio draws it, the site says what it
+ * says. Written for someone who has never seen Val.
+ */
+
 /*
  * A global `var` rather than a `Window` member: this package is compiled
  * without the DOM's types, and a `var` in global scope is also a property of
@@ -8915,4 +9030,4 @@ function schemaErrorsOf(schema, moduleFilePath, source) {
   return errors;
 }
 
-export { AA_LARGE, AA_TEXT, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchId, PatchJSON, PatchSets, PlanRefusalError, PublishProtocolError, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, STUDIO_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedValViewSchema, SerializedVideoSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_STUDIO_HEADER, ValCommit, ValDeployment, VideoOptions, VideoStreamOption, WASM_ENCODED_MIME_TYPES, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, chainHeadOf, checkCompatibility, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, enumLocaleTag, explainIncompatible, fallbackMimeType, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, forEachRichTextImage, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, getValDemo, indexModule, isInsidePatchSetPath, isLocaleSchema, isMimeTypeAccepted, isRemoteSchema, isRepairedOnSave, isSchemaSourceFixError, isSkippedSource, isStudioFix, joinSharedChanges, keyOfRecordPath, levenshtein, localeAt, localeMeantBy, memoizePerRequest, newestCommitSha, parseArtifacts, parseBuildTarget, parseCancel, parseDeclare, parseDiscard, parseJob, parseNewestCiRun, parsePress, parseProblems, parseProjectSource, parsePromote, parsePublishToken, parseRenew, parseRequestStatus, parseStatus, parseUpdateTarget, parseVerify, partitionValidationErrors, performSearch, relativeLuminance, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextImageSchema, richTextToRemirror, safeParsePatch, schemaErrorsOf, schemaTypesOfPath, selectionClosure, shouldEncodeWithWasm, sideFiles, sideSource, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };
+export { AA_LARGE, AA_TEXT, AnalyticsBeacon, Api, BRAND_CONTRAST_PAIRS, BinaryFileRef, CodeOptions, ColorOptions, DEFAULT_ERROR_MESSAGE, DateOptions, ENCODE_DEFAULTS, ENCODE_MIME_TYPE_OF, FileOptions, HistoricalCommit, HistoricalModule, HistoricalPatchSet, HistoryError, ImageEncodeOption, ImageOptions, JSONValue, JSON_ENTRIES_BATCH_MAX, ModuleComparison, NEVER_ENCODED, ParentRef$1 as ParentRef, Patch, PatchBlock, PatchId, PatchJSON, PatchSets, PlanRefusalError, PublishProtocolError, RAMP_STEPS, RemirrorBr, RemirrorBulletList, RemirrorHeading, RemirrorImage, RemirrorJSON, RemirrorLinkMark, RemirrorListItem, RemirrorOrderedList, RemirrorParagraph, RemirrorText, RemirrorTextMark, RestoreVerdict, RichTextOptions, SCHEMA_SOURCE_FIXES, STUDIO_FIXES, SerializedArraySchema, SerializedBooleanSchema, SerializedCodeSchema, SerializedColorSchema, SerializedDateSchema, SerializedDateTimeSchema, SerializedDiscriminatedUnionSchema, SerializedEnumSchema, SerializedFileSchema, SerializedImageSchema, SerializedKeyOfSchema, SerializedLiteralSchema, SerializedLocaleSchema, SerializedNumberSchema, SerializedObjectSchema, SerializedRecordSchema, SerializedRichTextSchema, SerializedRouteSchema, SerializedSchema, SerializedSettingsSchema, SerializedStringSchema, SerializedValViewSchema, SerializedVideoSchema, SharedValConfig, VAL_ENABLE_COOKIE_NAME, VAL_GREEN_RAMP, VAL_SESSION_COOKIE, VAL_STATE_COOKIE, VAL_STUDIO_HEADER, ValCommit, ValDeployment, VideoOptions, VideoStreamOption, WASM_ENCODED_MIME_TYPES, accentRamp, buildDuplicatePatch, buildEmptyAtPathPatch, buildFileRefValue, buildImageGalleryPatch, buildRemoveImageGalleryEntryPatch, buildSearchIndex, chainHeadOf, checkCompatibility, chooseEncoded, concatModulePath, contrastRatio, createRegExpFromPattern, createSearchIndex, createValClient, declaredLocales, describeContainerAtPath, emptyOf, enumLocaleTag, explainIncompatible, fallbackMimeType, filterBlockingValidationErrors, filterRoutesByPatterns, findSimilar, fitWithin, flattenRichText, forEachRichTextImage, getErrorMessageFromUnknownJson, getFilenameFromRef, getInlineImgInfo, getKeyOfRecordAt, getRefParts, getRoutesOf, getRoutesWithModulePaths, getSourceAt, getValDemo, indexModule, isInsidePatchSetPath, isLocaleSchema, isMimeTypeAccepted, isRemoteSchema, isRepairedOnSave, isSchemaSourceFixError, isSkippedSource, isStudioFix, joinSharedChanges, keyOfRecordPath, levenshtein, localeAt, localeMeantBy, memoizePerRequest, newestCommitSha, parseArtifacts, parseBuildTarget, parseCancel, parseDeclare, parseDiscard, parseJob, parseNewestCiRun, parsePress, parseProblems, parseProjectSource, parsePromote, parsePublishToken, parseRenew, parseRequestStatus, parseStatus, parseUpdateTarget, parseVerify, partitionValidationErrors, performSearch, relativeLuminance, remirrorToRichTextSource, removeModule, resolveEncodeSettings, resolvePairGround, resolveSchemaSourceFixForError, resolveSchemaSourceFixes, resolveSerializedSchemaAtPath, richTextImageSchema, richTextToRemirror, safeParsePatch, schemaErrorsOf, schemaTypesOfPath, selectionClosure, shouldEncodeWithWasm, sideFiles, sideSource, sourcePathOfChild, themeCustomProperties, toolNames, traverseSchemaSource, urlOf, validateRoutePatterns, withExtension };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valbuild/shared",
-  "version": "0.148.2",
+  "version": "0.148.6",
   "private": false,
   "description": "Val shared types and utilities",
   "repository": {