@phis/ui 0.3.0 → 0.4.0

package/plugins/runtime-modules/revisions/presets.d.ts

@@ -1,2 +1,53 @@
-import type { PhiCmsRoutePresetDescriptor } from "../../../types/cms-module-descriptors";
-export declare const PHI_REVISIONS_RUNTIME_MODULE_ROUTES: PhiCmsRoutePresetDescriptor[];
+export declare const PHI_REVISIONS_RUNTIME_MODULE_ROUTES: {
+    tour: {
+        readonly id: "@phis/ui/modules/revisions/revisions";
+        readonly version: 1;
+        readonly steps: readonly [{
+            readonly key: "history";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:filters`;
+            readonly title: "Whose history";
+            readonly description: "Every save is kept as a revision. Kind chooses what the list shows: an Area's Shell, a Page, a Navigation or the Theme. Scope chooses which Page or which Navigation.";
+            readonly placement: "bottom";
+            readonly ifMissing: "skip";
+        }, {
+            readonly key: "list";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:header`;
+            readonly title: "One row per revision";
+            readonly description: "Newest first, with when it was saved, by whom and what changed. The tags say which revision is live and which is the draft being worked on; those two cannot be deleted.";
+            readonly placement: "bottom";
+        }, {
+            readonly key: "answer";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:row-actions`;
+            readonly title: "Looking back and going back";
+            readonly description: "Review opens the revision as it was, in a new tab. Restore makes a new draft from it: nothing live changes until that draft is published. Delete removes a revision for good; selected rows can be deleted together.";
+            readonly placement: "left";
+            readonly ifMissing: "skip";
+        }, {
+            readonly key: "reset";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:toolbar`;
+            readonly title: "Back to the preset";
+            readonly description: "A Page a Module brings can go back to that Module's version. Every revision the Site stored for it goes with it, so this is offered only while a Page's history is shown.";
+            readonly placement: "bottom";
+            readonly ifMissing: "skip";
+        }, {
+            readonly key: "delete-area";
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: "Deleting an Area";
+            readonly description: "Clears everything the Site stored for an Area's Shell and Module selection, live included, and leaves no revision to restore. The Area keeps its Pages, its Navigation and its Theme. It asks for the Area's key before it does anything.";
+            readonly placement: "bottom";
+        }];
+    };
+    ownerModuleId: import("../contracts").PhiRuntimeModuleId;
+    presetKey: string;
+    presetVersion: number;
+    area: import("@phis/contracts/cms").PhiCmsAreaKey;
+    path: string;
+    landingPage?: true;
+    title: string;
+    defaultPageFlags?: number;
+    loadTree: (context: import("../../../types").PhiCmsDescriptorBuildContext & {
+        activeModuleIds: ReadonlySet<import("../contracts").PhiRuntimeModuleId>;
+        params: Readonly<Record<string, string>>;
+    }) => import("../../../types").PhiResolvedCmsPageTree | Promise<import("../../../types").PhiResolvedCmsPageTree>;
+    navigation?: readonly import("../../../types").PhiCmsNavigationInjectionDescriptor[];
+}[];

package/plugins/runtime-modules/revisions/presets.js

@@ -1,16 +1,20 @@
 import { buildPhiSidebarRoutePresetDescriptor } from "../sidebar-route";
 import { PHI_REVISIONS_RUNTIME_MODULE_ID } from "./ids";
+import { PHI_REVISIONS_TOUR } from "./tour";
 export const PHI_REVISIONS_RUNTIME_MODULE_ROUTES = [
-    buildPhiSidebarRoutePresetDescriptor({
-        area: "builder",
-        anchor: "main",
-        ownerModuleId: PHI_REVISIONS_RUNTIME_MODULE_ID,
-        presetKey: "builder-revisions-page",
-        title: "Revisions",
-        path: "/revisions",
-        itemKey: "@phis/ui/modules/revisions/nav/builder/revisions",
-        icon: "antd:history",
-        loadTree: ({ page, runtime }) => import("./trees/phi-default-builder-revisions-page-tree")
-            .then((module) => module.buildPhiDefaultBuilderRevisionsPageTree({ page, runtime })),
-    }),
+    {
+        ...buildPhiSidebarRoutePresetDescriptor({
+            area: "builder",
+            anchor: "main",
+            ownerModuleId: PHI_REVISIONS_RUNTIME_MODULE_ID,
+            presetKey: "builder-revisions-page",
+            title: "Revisions",
+            path: "/revisions",
+            itemKey: "@phis/ui/modules/revisions/nav/builder/revisions",
+            icon: "antd:history",
+            loadTree: ({ page, runtime }) => import("./trees/phi-default-builder-revisions-page-tree")
+                .then((module) => module.buildPhiDefaultBuilderRevisionsPageTree({ page, runtime })),
+        }),
+        tour: PHI_REVISIONS_TOUR,
+    },
 ];

package/plugins/runtime-modules/revisions/tour.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The Revisions Tour. What the Page does not say is that every save is kept, that going back never
+ * touches what is live -- a restored revision is a new draft -- and that the one act here that cannot be
+ * taken back stands apart from the rest.
+ */
+export declare const PHI_REVISIONS_TOUR: {
+    readonly id: "@phis/ui/modules/revisions/revisions";
+    readonly version: 1;
+    readonly steps: readonly [{
+        readonly key: "history";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:filters`;
+        readonly title: "Whose history";
+        readonly description: "Every save is kept as a revision. Kind chooses what the list shows: an Area's Shell, a Page, a Navigation or the Theme. Scope chooses which Page or which Navigation.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "list";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:header`;
+        readonly title: "One row per revision";
+        readonly description: "Newest first, with when it was saved, by whom and what changed. The tags say which revision is live and which is the draft being worked on; those two cannot be deleted.";
+        readonly placement: "bottom";
+    }, {
+        readonly key: "answer";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:row-actions`;
+        readonly title: "Looking back and going back";
+        readonly description: "Review opens the revision as it was, in a new tab. Restore makes a new draft from it: nothing live changes until that draft is published. Delete removes a revision for good; selected rows can be deleted together.";
+        readonly placement: "left";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "reset";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}:toolbar`;
+        readonly title: "Back to the preset";
+        readonly description: "A Page a Module brings can go back to that Module's version. Every revision the Site stored for it goes with it, so this is offered only while a Page's history is shown.";
+        readonly placement: "bottom";
+        readonly ifMissing: "skip";
+    }, {
+        readonly key: "delete-area";
+        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+        readonly title: "Deleting an Area";
+        readonly description: "Clears everything the Site stored for an Area's Shell and Module selection, live included, and leaves no revision to restore. The Area keeps its Pages, its Navigation and its Theme. It asks for the Area's key before it does anything.";
+        readonly placement: "bottom";
+    }];
+};

package/plugins/runtime-modules/revisions/tour.js

@@ -0,0 +1,51 @@
+import { PHI_REVISIONS_RUNTIME_MODULE_ID } from "./ids";
+import { PHI_REVISIONS_PAGE_WIDGET_IDS, PHI_REVISIONS_TABLE_WIDGET_ID } from "./page-ids";
+/**
+ * The Revisions Tour. What the Page does not say is that every save is kept, that going back never
+ * touches what is live -- a restored revision is a new draft -- and that the one act here that cannot be
+ * taken back stands apart from the rest.
+ */
+export const PHI_REVISIONS_TOUR = {
+    id: `${PHI_REVISIONS_RUNTIME_MODULE_ID}/revisions`,
+    version: 1,
+    steps: [
+        {
+            key: "history",
+            target: `cms:${PHI_REVISIONS_TABLE_WIDGET_ID}:filters`,
+            title: "Whose history",
+            description: "Every save is kept as a revision. Kind chooses what the list shows: an Area's Shell, a Page, a Navigation or the Theme. Scope chooses which Page or which Navigation.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "list",
+            target: `cms:${PHI_REVISIONS_TABLE_WIDGET_ID}:header`,
+            title: "One row per revision",
+            description: "Newest first, with when it was saved, by whom and what changed. The tags say which revision is live and which is the draft being worked on; those two cannot be deleted.",
+            placement: "bottom",
+        },
+        {
+            key: "answer",
+            target: `cms:${PHI_REVISIONS_TABLE_WIDGET_ID}:row-actions`,
+            title: "Looking back and going back",
+            description: "Review opens the revision as it was, in a new tab. Restore makes a new draft from it: nothing live changes until that draft is published. Delete removes a revision for good; selected rows can be deleted together.",
+            placement: "left",
+            ifMissing: "skip",
+        },
+        {
+            key: "reset",
+            target: `cms:${PHI_REVISIONS_TABLE_WIDGET_ID}:toolbar`,
+            title: "Back to the preset",
+            description: "A Page a Module brings can go back to that Module's version. Every revision the Site stored for it goes with it, so this is offered only while a Page's history is shown.",
+            placement: "bottom",
+            ifMissing: "skip",
+        },
+        {
+            key: "delete-area",
+            target: `cms:${PHI_REVISIONS_PAGE_WIDGET_IDS.widgetRevisionsAreaShellDelete}`,
+            title: "Deleting an Area",
+            description: "Clears everything the Site stored for an Area's Shell and Module selection, live included, and leaves no revision to restore. The Area keeps its Pages, its Navigation and its Theme. It asks for the Area's key before it does anything.",
+            placement: "bottom",
+        },
+    ],
+};

package/plugins/runtime-modules/theme/presets.d.ts

@@ -5,15 +5,47 @@ export declare const PHI_THEME_RUNTIME_MODULE_ROUTES: {
         readonly steps: readonly [{
             readonly key: "theme-choice";
             readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
-            readonly title: "Which theme you are working on";
-            readonly description: "The Site's published theme, its draft, or a theme a Module brings. A Module's theme changes nothing until it is picked here.";
+            readonly title: "What your draft starts from";
+            readonly description: "The Site's published theme, its draft, or a theme a Module brings. Picking one makes it the base of your theme draft; the Module's theme itself stays as it is.";
             readonly placement: "bottom";
         }, {
             readonly key: "theme-parts";
             readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
-            readonly title: "Colour and style";
-            readonly description: "Switch between the palette and the shapes and type of the theme.";
+            readonly title: "Four parts of the theme";
+            readonly description: "Colour, style, background and brand: each opens its own controls on the left, with the preview beside them.";
             readonly placement: "bottom";
+        }, {
+            readonly key: string;
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: string;
+            readonly description: string;
+            readonly placement: "right";
+            readonly prepare: readonly [import("../../../types").PhiTourStepSignal];
+            readonly release: readonly [import("../../../types").PhiTourStepSignal];
+        }, {
+            readonly key: string;
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: string;
+            readonly description: string;
+            readonly placement: "right";
+            readonly prepare: readonly [import("../../../types").PhiTourStepSignal];
+            readonly release: readonly [import("../../../types").PhiTourStepSignal];
+        }, {
+            readonly key: string;
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: string;
+            readonly description: string;
+            readonly placement: "right";
+            readonly prepare: readonly [import("../../../types").PhiTourStepSignal];
+            readonly release: readonly [import("../../../types").PhiTourStepSignal];
+        }, {
+            readonly key: string;
+            readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+            readonly title: string;
+            readonly description: string;
+            readonly placement: "right";
+            readonly prepare: readonly [import("../../../types").PhiTourStepSignal];
+            readonly release: readonly [import("../../../types").PhiTourStepSignal];
         }, {
             readonly key: "preview-mode";
             readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;

package/plugins/runtime-modules/theme/tour.d.ts

@@ -1,34 +1,68 @@
+import type { PhiCmsInstanceId } from "../../../types/cms-instance-id";
+import type { PhiTourStepSignal } from "../../../types/tours";
 /**
  * The Theme workspace's Tour (TODOS.md, "A Tour for the Theme workspace").
  *
- * What the workspace does not say out loud is its first step: a Module's Theme is offered and never
- * taken, so installing a package that ships a look changes nothing until somebody picks it here. The
- * rest is the order a person meets the workspace in.
+ * What the workspace does not say out loud is its first step: the selector picks what a draft starts
+ * from. A Module's Theme is a base to start from, never edited through it, and installing a package
+ * that ships a look changes nothing for the Site. The rest is the order a person meets the workspace in.
  */
 export declare const PHI_THEME_WORKSPACE_TOUR: {
     readonly id: "@phis/ui/modules/theme/workspace";
     readonly version: 1;
     readonly steps: readonly [{
         readonly key: "theme-choice";
-        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
-        readonly title: "Which theme you are working on";
-        readonly description: "The Site's published theme, its draft, or a theme a Module brings. A Module's theme changes nothing until it is picked here.";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "What your draft starts from";
+        readonly description: "The Site's published theme, its draft, or a theme a Module brings. Picking one makes it the base of your theme draft; the Module's theme itself stays as it is.";
         readonly placement: "bottom";
     }, {
         readonly key: "theme-parts";
-        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
-        readonly title: "Colour and style";
-        readonly description: "Switch between the palette and the shapes and type of the theme.";
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: "Four parts of the theme";
+        readonly description: "Colour, style, background and brand: each opens its own controls on the left, with the preview beside them.";
         readonly placement: "bottom";
+    }, {
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "right";
+        readonly prepare: readonly [PhiTourStepSignal];
+        readonly release: readonly [PhiTourStepSignal];
+    }, {
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "right";
+        readonly prepare: readonly [PhiTourStepSignal];
+        readonly release: readonly [PhiTourStepSignal];
+    }, {
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "right";
+        readonly prepare: readonly [PhiTourStepSignal];
+        readonly release: readonly [PhiTourStepSignal];
+    }, {
+        readonly key: string;
+        readonly target: `cms:${PhiCmsInstanceId}`;
+        readonly title: string;
+        readonly description: string;
+        readonly placement: "right";
+        readonly prepare: readonly [PhiTourStepSignal];
+        readonly release: readonly [PhiTourStepSignal];
     }, {
         readonly key: "preview-mode";
-        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+        readonly target: `cms:${PhiCmsInstanceId}`;
         readonly title: "Light and dark";
         readonly description: "See the theme in either mode. This switches the preview, not the Site.";
         readonly placement: "bottom";
     }, {
         readonly key: "draft-status";
-        readonly target: `cms:${import("@phis/contracts/cms").PhiCmsInstanceId}`;
+        readonly target: `cms:${PhiCmsInstanceId}`;
         readonly title: "Where your changes stand";
         readonly description: "What you change here is a draft. The Site keeps its published theme until the draft is published.";
         readonly placement: "bottom";

package/plugins/runtime-modules/theme/tour.js

@@ -1,11 +1,38 @@
+import { PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS } from "../../../constants/cms-layout-types";
 import { PHI_THEME_RUNTIME_MODULE_ID } from "./ids";
-import { PHI_THEME_PAGE_WIDGET_IDS } from "./page-ids";
+import { PHI_THEME_PAGE_LAYOUT_IDS, PHI_THEME_PAGE_WIDGET_IDS } from "./page-ids";
+/** Turns the workspace's Stack to one of its four panels, as the Segmented above it does. */
+function showPanel(slot) {
+    return {
+        receiver: `cms:${PHI_THEME_PAGE_LAYOUT_IDS.layoutBrandStack}`,
+        channel: "activeSlotKey",
+        action: "change",
+        valueType: "string",
+        value: PHI_CMS_SEQUENTIAL_LAYOUT_SLOTS[slot].key,
+    };
+}
+/**
+ * One panel of the workspace, pointed at by its controls. The step turns the Stack to the panel and back
+ * to Color when it is left, the panel the workspace opens with; from one panel step to the next both
+ * arrive together, so the Stack simply moves on.
+ */
+function panelStep(key, slot, controls, title, description) {
+    return {
+        key,
+        target: `cms:${controls}`,
+        title,
+        description,
+        placement: "right",
+        prepare: [showPanel(slot)],
+        release: [showPanel(0)],
+    };
+}
 /**
  * The Theme workspace's Tour (TODOS.md, "A Tour for the Theme workspace").
  *
- * What the workspace does not say out loud is its first step: a Module's Theme is offered and never
- * taken, so installing a package that ships a look changes nothing until somebody picks it here. The
- * rest is the order a person meets the workspace in.
+ * What the workspace does not say out loud is its first step: the selector picks what a draft starts
+ * from. A Module's Theme is a base to start from, never edited through it, and installing a package
+ * that ships a look changes nothing for the Site. The rest is the order a person meets the workspace in.
  */
 export const PHI_THEME_WORKSPACE_TOUR = {
     id: `${PHI_THEME_RUNTIME_MODULE_ID}/workspace`,
@@ -14,17 +41,21 @@ export const PHI_THEME_WORKSPACE_TOUR = {
         {
             key: "theme-choice",
             target: `cms:${PHI_THEME_PAGE_WIDGET_IDS.widgetBrandContextSelect}`,
-            title: "Which theme you are working on",
-            description: "The Site's published theme, its draft, or a theme a Module brings. A Module's theme changes nothing until it is picked here.",
+            title: "What your draft starts from",
+            description: "The Site's published theme, its draft, or a theme a Module brings. Picking one makes it the base of your theme draft; the Module's theme itself stays as it is.",
             placement: "bottom",
         },
         {
             key: "theme-parts",
             target: `cms:${PHI_THEME_PAGE_WIDGET_IDS.widgetThemeStackSegmented}`,
-            title: "Colour and style",
-            description: "Switch between the palette and the shapes and type of the theme.",
+            title: "Four parts of the theme",
+            description: "Colour, style, background and brand: each opens its own controls on the left, with the preview beside them.",
             placement: "bottom",
         },
+        panelStep("color", 0, PHI_THEME_PAGE_WIDGET_IDS.widgetBrandThemeControls, "Colour from a few seeds", "A palette is picked whole, or each colour is set on its own. Every colour is a seed: Primary, Info, Success, Warning, Error, Link, the text and the background each grow into the shades for hover, borders and backgrounds, and Custom grows into ten steps of its own."),
+        panelStep("style", 1, PHI_THEME_PAGE_WIDGET_IDS.widgetBrandStyleControls, "Buttons and corners", "A shape sets the corners at once -- square, subtle, rounded or pill -- for buttons and fields alike. Below it the details: the buttons' shadows, the corner radius in three sizes, how tall controls are, and the fonts and their size."),
+        panelStep("background", 2, PHI_THEME_PAGE_WIDGET_IDS.widgetBrandBackgroundControls, "Behind everything", "The root background is one layer behind the whole Site: a colour, a gradient or an image, still or in parallax, with an overlay of colour, pattern or noise on top. The chrome overlay is a second ground the header, the sider and the footer share, and the chrome shadow sets how they cast onto the Page. Each is set for light and dark."),
+        panelStep("brand", 3, PHI_THEME_PAGE_WIDGET_IDS.widgetBrandIdentityControls, "The Site's own marks", "The logo, one per mode, and where a click on it leads; the wordmark, the Site's name in type; and the two short lines the Brand shows beside them."),
         {
             key: "preview-mode",
             target: `cms:${PHI_THEME_PAGE_WIDGET_IDS.widgetBrandPreviewModeSwitch}`,

package/plugins/runtime-modules/tour/controller/address.js

@@ -1,3 +1,3 @@
-import { PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY } from "../../../../types/tours";
-// The Controller's address is the foundation's (`types/tours.ts`): the Tour button, which is Core's, asks it.
+import { PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY } from "../../../../types/tour-controller";
+// The Controller's address is the foundation's (`types/tour-controller.ts`): the Tour button, which is Core's, asks it.
 export const PHI_TOUR_CONTROLLER_TYPE = `${PHI_TOUR_CONTROLLER_PLUGIN_KEY}/${PHI_TOUR_CONTROLLER_KEY}`;

package/plugins/runtime-modules/tour/controller/client.js

@@ -3,16 +3,19 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
 import { PhiTourControl } from "../../../../components/controls/phi-tour-control";
+import { holdPhiTourViewport, releasePhiTourViewport } from "../../../../components/controls/phi-tour-viewport";
 import { createPhiRuntimeControllerClient } from "../../../../components/runtime/runtime-controller-client-factory";
 import { usePhiSignalDispatcher, usePhiSignalListener } from "../../../../components/runtime/runtime-signal-bus";
 import { usePhiSignalRuntimePartition } from "../../../../components/runtime/runtime-signal-partition";
-import { readPhiVisualAnchor, waitForPhiVisualAnchor } from "../../../../components/runtime/runtime-visual-anchors";
+import { readPhiVisualAnchor, waitForPhiVisualAnchor, waitForPhiVisualAnchorToSettle, } from "../../../../components/runtime/runtime-visual-anchors";
 import { fetchPhiUserState, writePhiUserState } from "../../../../components/runtime/user-state-client";
 import { PHI_TOUR_PROGRESS_USER_STATE_KEY } from "../ids";
 import { PHI_TOUR_RUNTIME_CONTROLLER_DEFINITION } from "./definition";
 import { readPhiTourProgress, recordPhiTourProgress, shouldOfferPhiTour, } from "./progress";
 /** How long a step waits for its target before its `ifMissing` decides. */
 const TARGET_WAIT_MS = 4000;
+/** How long a found target may keep moving before it is pointed at where it stands. */
+const TARGET_SETTLE_MS = 1000;
 const PROGRESS_DESCRIPTOR = {
     key: PHI_TOUR_PROGRESS_USER_STATE_KEY,
     shape: "value",
@@ -115,6 +118,31 @@ function PhiTourControllerView({ address, config }) {
      * never pointed at anything but its own address in this partition.
      */
     const step = run ? run.tour.steps[run.index] ?? null : null;
+    const send = useCallback((signals) => {
+        for (const signal of signals ?? []) {
+            dispatchSignal({
+                scope: "area",
+                channel: signal.channel,
+                action: signal.action,
+                value: signal.value ?? null,
+                valueType: signal.valueType,
+                ...(signal.valueSchema ? { valueSchema: signal.valueSchema } : {}),
+                sender: address,
+                receiver: signal.receiver,
+            });
+        }
+    }, [address, dispatchSignal]);
+    /*
+     * The step asked for gets its `prepare` before its target is waited for, and its `release` the moment it
+     * is no longer the one asked for -- the next step, a step passed over, the Tour closed or finished, the
+     * Page left. One effect per step, so every prepare is answered by exactly one release.
+     */
+    useEffect(() => {
+        if (!step)
+            return undefined;
+        send(step.prepare);
+        return () => send(step.release);
+    }, [send, step]);
     // A step centered on purpose has nothing to wait for.
     const presented = run && step?.target == null ? run.index : run?.presented ?? null;
     useEffect(() => {
@@ -122,10 +150,16 @@ function PhiTourControllerView({ address, config }) {
             return undefined;
         const abort = new AbortController();
         void waitForPhiVisualAnchor(partition, step.target, { timeoutMs: TARGET_WAIT_MS, signal: abort.signal })
-            .then((element) => {
+            .then(async (element) => {
             if (abort.signal.aborted)
                 return;
             if (element) {
+                // Pointed at once it stands still: a target a `prepare` just opened is often still moving in.
+                await waitForPhiVisualAnchorToSettle(element, { timeoutMs: TARGET_SETTLE_MS, signal: abort.signal });
+                if (abort.signal.aborted)
+                    return;
+                // Scrolled to below the sticky bands, once the step is presented (`phi-tour-viewport.ts`).
+                holdPhiTourViewport(element);
                 setRun({ ...run, presented: run.index });
                 return;
             }
@@ -136,6 +170,13 @@ function PhiTourControllerView({ address, config }) {
         });
         return () => abort.abort();
     }, [partition, run, step]);
+    // The window's scroll padding is the Tour's only while a Tour runs.
+    const running = run != null;
+    useEffect(() => {
+        if (!running)
+            return undefined;
+        return releasePhiTourViewport;
+    }, [running]);
     const steps = useMemo(() => (run?.tour.steps ?? []).map((definition) => ({
         key: definition.key,
         title: definition.title,

package/plugins/runtime-modules/tour/controller/definition.js

@@ -1,5 +1,6 @@
 import { PHI_SIGNAL_VALUE_SCHEMAS } from "../../../../types/signals";
-import { PHI_PAGE_TOUR_CONFIG_KEY, PHI_PAGE_TOUR_CONTROLLER_FLAG, PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY, readPhiResolvedPageTour, } from "../../../../types/tours";
+import { PHI_TOUR_CONTROLLER_KEY, PHI_TOUR_CONTROLLER_PLUGIN_KEY } from "../../../../types/tour-controller";
+import { PHI_PAGE_TOUR_CONFIG_KEY, PHI_PAGE_TOUR_CONTROLLER_FLAG, readPhiResolvedPageTour, } from "../../../../types/tours";
 /**
  * Runs the Tour of whichever Page is shown (design/TOURS.md).
  *

package/server-helpers/cms-request.js

@@ -320,6 +320,7 @@ export async function resolvePhiCmsRequest({ siteKey, locale, area, path, cookie
         pageTour: routeTour
             ? {
                 definition: routeTour,
+                ownerModuleId: routeBinding.descriptor.ownerModuleId,
                 sourceLocale: catalog.sourceLocaleByModuleId.get(routeBinding.descriptor.ownerModuleId),
             }
             : null,

package/server-helpers/page-tour.d.ts

@@ -1,11 +1,18 @@
 import "server-only";
+import type { PhiRuntimeModuleId } from "../types/cms-module-descriptors";
 import type { PhiResolvedPageTour, PhiTourDefinition } from "../types/tours";
 /**
- * A Page's Tour in the viewer's language: every step's words translated from the owning Module's
- * language, and the step buttons from Core's label set. Addresses and keys are not words and pass through.
+ * A Page's Tour in the viewer's language: every step's words translated, and the step buttons from Core's
+ * label set. Addresses, keys and step signals are not words and pass through.
+ *
+ * Where the words are kept depends on who wrote them. A built-in Tour's text is this package's, the same
+ * on every Site, so it is translated once in the global set. A third-party Module's Tour is translated per
+ * Site from the language that Module writes in, where the Site's own corrections apply. Either way the
+ * Tour's id is the context, so a translator sees which Tour a sentence belongs to.
  */
-export declare function resolvePhiPageTour({ definition, sourceLocale, locale, }: {
+export declare function resolvePhiPageTour({ definition, ownerModuleId, sourceLocale, locale, }: {
     definition: PhiTourDefinition;
+    ownerModuleId: PhiRuntimeModuleId;
     sourceLocale?: string;
     locale: string;
 }): Promise<PhiResolvedPageTour>;

package/server-helpers/page-tour.js

@@ -1,26 +1,39 @@
 import "server-only";
 import { getPhiTourWidgetLabels } from "../components/widgets/label-sets/tour";
+import { PHI_SHARED_PACKAGE_NAME } from "../constants/package";
 import { readPhiServerApiCredentials } from "../helpers/phis-server-credentials";
-import { trForLocale } from "./translate";
+import { trBulkForLocale, trGlobalBulkForLocale } from "./translate";
+/** A Tour this package ships, whose words are the same on every Site. */
+function isPhiBuiltInTour(ownerModuleId) {
+    return ownerModuleId.startsWith(`${PHI_SHARED_PACKAGE_NAME}/`);
+}
 /**
- * A Page's Tour in the viewer's language: every step's words translated from the owning Module's
- * language, and the step buttons from Core's label set. Addresses and keys are not words and pass through.
+ * A Page's Tour in the viewer's language: every step's words translated, and the step buttons from Core's
+ * label set. Addresses, keys and step signals are not words and pass through.
+ *
+ * Where the words are kept depends on who wrote them. A built-in Tour's text is this package's, the same
+ * on every Site, so it is translated once in the global set. A third-party Module's Tour is translated per
+ * Site from the language that Module writes in, where the Site's own corrections apply. Either way the
+ * Tour's id is the context, so a translator sees which Tour a sentence belongs to.
  */
-export async function resolvePhiPageTour({ definition, sourceLocale, locale, }) {
-    const translate = (text) => trForLocale(locale, text, 0, 0, "text", sourceLocale);
+export async function resolvePhiPageTour({ definition, ownerModuleId, sourceLocale, locale, }) {
+    const texts = definition.steps.flatMap((step) => [step.title, step.description ?? ""]);
+    const translate = isPhiBuiltInTour(ownerModuleId)
+        ? trGlobalBulkForLocale(locale, texts, definition.id)
+        : trBulkForLocale(locale, texts, definition.id, "text", sourceLocale);
     const credentials = readPhiServerApiCredentials();
-    const [labels, steps] = await Promise.all([
+    const [labels, translated] = await Promise.all([
         getPhiTourWidgetLabels({ apiBaseUrl: credentials.apiBaseUrl, internalToken: credentials.internalToken, locale }),
-        Promise.all(definition.steps.map(async (step) => ({
-            ...step,
-            title: await translate(step.title),
-            ...(step.description ? { description: await translate(step.description) } : {}),
-        }))),
+        translate,
     ]);
     return {
         id: definition.id,
         version: definition.version,
-        steps,
+        steps: definition.steps.map((step, index) => ({
+            ...step,
+            title: translated[index * 2] ?? step.title,
+            ...(step.description ? { description: translated[index * 2 + 1] ?? step.description } : {}),
+        })),
         labels: { next: labels.next, previous: labels.previous, finish: labels.finish },
     };
 }

package/types/cms-config.d.ts

@@ -6,6 +6,7 @@ import { type PhiCssLength } from "./length";
 import type { PhiResponsiveValue } from "./responsive";
 import type { PhiRenderableBlockBase, PhiRenderableBlockAnchor, PhiRenderableBlockResponsiveSize } from "./renderable-block";
 import type { PhiBaseLayoutSlotStates } from "../components/layouts/phi-layout-contract";
+import { type PhiSpacingScaleKey } from "../components/widgets/config/spacing-options";
 export type PhiCmsPluginConfigBase = Record<string, unknown>;
 export type PhiCmsRenderableBlockConfigBase = PhiCmsPluginConfigBase & PhiRenderableBlockBase;
 export type PhiCmsLayerBase = PhiCmsRenderableBlockConfigBase & {
@@ -120,7 +121,8 @@ export type PhiCmsCarouselLayoutConfig = PhiCmsLayerBase & {
     transition?: PhiSequenceTransition;
     transitionDurationMs?: number;
     transitionEasing?: PhiMotionEasing;
-    slotGap?: string;
+    /** A step of the spacing scale between the slots of a window. */
+    slotGap?: PhiSpacingScaleKey;
     /** Which of its own controls the Carousel draws. Pager Widgets work regardless of this. */
     controls?: "none" | "arrows" | "dots" | "both";
     loop?: boolean;

package/types/cms-config.js

@@ -9,6 +9,7 @@ import { applyPhiLayoutDefaults } from "../helpers/cms-layout-defaults";
 import { resolvePhiLayoutDefaults } from "../helpers/cms-layout-defaults";
 import { normalizeRenderableBlockAnchor } from "../helpers/renderable-block-anchor";
 import { isPhiRecord } from "../helpers/is-record";
+import { PHI_SPACING_SCALE_KEYS } from "../components/widgets/config/spacing-options";
 import { PHI_GRID_COLUMN_COUNTS, isPhiGridColumnCount } from "../constants/grid-columns";
 function readInitialSlotStates(value) {
     if (Array.isArray(value)) {
@@ -334,6 +335,7 @@ export function parsePhiCmsCarouselLayoutConfig(config) {
     const loop = readCarouselFlag(config.loop, "loop");
     const autoplayMs = readCarouselCount(config.autoplayMs, "autoplayMs", 0);
     const lookahead = readCarouselCount(config.lookahead, "lookahead", 0);
+    const slotGap = readCarouselMember(config.slotGap, PHI_SPACING_SCALE_KEYS, "slotGap");
     return applyPhiLayoutDefaults({
         ...readRenderableBlockConfig(config),
         labelEnd: readPhiLayoutLabelEnd(config.labelEnd),
@@ -342,15 +344,13 @@ export function parsePhiCmsCarouselLayoutConfig(config) {
         ...(visibleSlots === undefined ? {} : { visibleSlots }),
         ...(windowAnchor === undefined ? {} : { windowAnchor }),
         ...(transition === undefined ? {} : { transition }),
-        // Absent means "whatever the theme does", which is why nothing is written here rather than a
-        // number this parser invented.
         ...(config.transitionDurationMs === undefined || config.transitionDurationMs === null ? {} : {
             transitionDurationMs: clampPhiSequenceTransitionMs(config.transitionDurationMs),
         }),
         ...(config.transitionEasing === undefined ? {} : {
             transitionEasing: readPhiMotionEasing(config.transitionEasing, undefined),
         }),
-        slotGap: readString(config.slotGap),
+        ...(slotGap === undefined ? {} : { slotGap }),
         ...(controls === undefined ? {} : { controls }),
         ...(loop === undefined ? {} : { loop }),
         // Zero is how "does not move on its own" is written, so it is the one number below the floor