@phis/ui 0.1.0 → 0.2.1

package/components/runtime/core-runtime-application-adapter.js

@@ -1,17 +1,47 @@
 "use client";
-import { useEffect } from "react";
-import { App } from "antd";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { requestPhiLogout } from "../../helpers/logout";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useRouter } from "next/navigation";
+import dynamic from "next/dynamic";
 import { readPhiCoreRuntimeMessageSignalValue, readPhiCoreRuntimeNavigateSignalValue, readPhiCoreRuntimeNotificationSignalValue, } from "../../types/core-runtime-controller";
 import { usePhiSignalListener } from "./runtime-signal-bus";
 import { usePhiSignalRuntimePartition } from "./runtime-signal-partition";
 import { registerPhiSignalInstance } from "./runtime-signal-registry";
 import { createPhiCoreRuntimeControllerAddress } from "./core-runtime-controller-address";
+/*
+ * Fetched the first time this Site has something to say, and not before.
+ *
+ * `ssr: false` because there is nothing to render on the server: a queue that is empty during the
+ * server render is empty in the HTML too, and the host exists only to play what arrives afterwards.
+ */
+const PhiLazyApplicationFeedbackHost = dynamic(() => import("./application-feedback-host").then((module) => module.PhiApplicationFeedbackHost), { ssr: false });
 const PHI_CORE_RUNTIME_APPLICATION_SIGNAL_FILTER = {
     scopes: ["site"],
     receiver: createPhiCoreRuntimeControllerAddress(),
 };
-export function PhiCoreRuntimeApplicationAdapter() {
-    const { message, notification } = App.useApp();
+/*
+ * No `siteKey` any more. It was passed in so a logout could name the Site, and that header never left
+ * the browser: the proxy strips every `x-phis-` header and sets the Site's own.
+ */
+export function PhiCoreRuntimeApplicationAdapter({ labels, }) {
+    const router = useRouter();
+    /*
+     * Armed once and never disarmed: the host owns the toast that is on screen, so unmounting it when
+     * the queue runs dry would take the announcement down with it. What empties is the queue.
+     */
+    const [armed, setArmed] = useState(false);
+    const [requests, setRequests] = useState([]);
+    const nextRequestKey = useRef(0);
+    const enqueue = useCallback((request) => {
+        const key = (nextRequestKey.current += 1);
+        setArmed(true);
+        setRequests((current) => [...current, { ...request, key }]);
+    }, []);
+    const handlePlayed = useCallback((keys) => {
+        const played = new Set(keys);
+        setRequests((current) => current.filter((request) => !played.has(request.key)));
+    }, []);
     const partition = usePhiSignalRuntimePartition();
     const address = createPhiCoreRuntimeControllerAddress();
     /*
@@ -23,6 +53,36 @@ export function PhiCoreRuntimeApplicationAdapter() {
      * was listening without ever having said that it answers here. Listening is not the same as existing.
      */
     useEffect(() => registerPhiSignalInstance(partition, { address, scope: "site" }), [address, partition]);
+    /* A second click while the first request is still out asks for nothing new. */
+    const signingOut = useRef(false);
+    const signOut = useCallback(async () => {
+        if (signingOut.current) {
+            return;
+        }
+        signingOut.current = true;
+        /*
+         * A failure is said, on the same surface every other announcement uses: the person asked to be
+         * signed out and still is signed in, and a menu that simply closed would let them believe
+         * otherwise.
+         */
+        try {
+            await requestPhiLogout({ failedMessage: labels.signOutFailed });
+        }
+        catch {
+            signingOut.current = false;
+            enqueue({ kind: "notification", value: { level: "error", title: labels.signOutFailed } });
+            return;
+        }
+        /*
+         * The same Page, as a fresh document. It is asked for again rather than replaced with one chosen
+         * here: whoever is now nobody may not be allowed where they stood, and the Area answers that --
+         * with its own redirect, its own sign-in Page -- which is a decision that belongs to it and not
+         * to this adapter. And a document rather than `router.refresh()`, because the RSC cache and the
+         * client stores on this page were built for a session that is gone; keeping them is the one
+         * thing a sign-out must not do.
+         */
+        window.location.reload();
+    }, [enqueue, labels.signOutFailed]);
     usePhiSignalListener((signal) => {
         const navigateValue = readPhiCoreRuntimeNavigateSignalValue(signal);
         if (navigateValue) {
@@ -34,34 +94,45 @@ export function PhiCoreRuntimeApplicationAdapter() {
             }
             return;
         }
+        /*
+         * Out, and then back to where anybody may be.
+         *
+         * The door is the Site's own `/api/auth/logout`, mounted by every Site regardless of which Modules
+         * it installs, so this works in an Area no Auth Module ever enters. A failed call leaves the
+         * session alone and the page where it is, and says so: signing out half way and forwarding
+         * anyway would tell somebody they are out while they are not.
+         */
+        if (signal.channel === "session" && signal.action === "clear") {
+            void signOut();
+            return;
+        }
+        /*
+         * The same Page, asked for again.
+         *
+         * `router.refresh()` rather than `location.reload()`: it re-renders the route's Server components
+         * with the cookies the browser now holds, which is the whole point, and leaves the visitor where
+         * they were -- the panel they had open stays open, which a document reload would close.
+         */
+        if (signal.channel === "reload" && signal.action === "activate") {
+            router.refresh();
+            return;
+        }
+        /*
+         * Queued rather than shown. What draws a toast is Ant Design's `App`, and it is fetched the first
+         * time a Site actually has something to say -- so the announcement waits for its host instead of
+         * every page waiting for the announcement.
+         */
         const notificationValue = readPhiCoreRuntimeNotificationSignalValue(signal);
         if (notificationValue) {
-            notification[notificationValue.level]({
-                title: notificationValue.title,
-                ...(notificationValue.description ? { description: notificationValue.description } : {}),
-                ...(notificationValue.durationSeconds != null
-                    ? { duration: notificationValue.durationSeconds }
-                    : {}),
-                ...(notificationValue.placement ? { placement: notificationValue.placement } : {}),
-                ...(notificationValue.showTimeoutProgress != null
-                    ? { showProgress: notificationValue.showTimeoutProgress }
-                    : {}),
-                role: notificationValue.level === "error" || notificationValue.level === "warning"
-                    ? "alert"
-                    : "status",
-            });
+            enqueue({ kind: "notification", value: notificationValue });
             return;
         }
         const messageValue = readPhiCoreRuntimeMessageSignalValue(signal);
         if (messageValue) {
-            message.open({
-                type: messageValue.level,
-                content: messageValue.content,
-                ...(messageValue.durationSeconds != null
-                    ? { duration: messageValue.durationSeconds }
-                    : {}),
-            });
+            enqueue({ kind: "message", value: messageValue });
         }
     }, PHI_CORE_RUNTIME_APPLICATION_SIGNAL_FILTER, address);
-    return null;
+    return armed
+        ? _jsx(PhiLazyApplicationFeedbackHost, { requests: requests, onPlayed: handlePlayed })
+        : null;
 }

package/components/runtime/core-runtime-controller-definition.d.ts

@@ -18,6 +18,11 @@ export declare const PHI_CORE_RUNTIME_CONTROLLER_DEFINITION: {
             action: "change";
             valueType: "string";
             valueSchema?: undefined;
+        } | {
+            id: string;
+            action: "change";
+            valueType: "boolean";
+            valueSchema?: undefined;
         } | {
             id: string;
             action: "clear";
@@ -65,6 +70,12 @@ export declare const PHI_CORE_RUNTIME_CONTROLLER_DEFINITION: {
             action: "activate";
             valueType: "json";
             valueSchema: `${string}/signals/${string}`;
+        } | {
+            id: string;
+            channel: string;
+            action: "activate";
+            valueType: "none";
+            valueSchema?: undefined;
         })[];
     };
     defaultConfig: {};

package/components/runtime/core-runtime-controller-definition.js

@@ -17,6 +17,13 @@ export const PHI_CORE_RUNTIME_CONTROLLER_DEFINITION = {
                 valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.pageMeta,
             },
             { id: "pageTitle", action: "change", valueType: "string" },
+            /*
+             * The mode the Site is shown in, whenever it changes: after the page wakes up in the mode the
+             * browser prefers, when that preference changes, and when something switches it. `true` is dark,
+             * the way the `themeMode` input reads it. A Control that offers the switch listens for it, so it
+             * shows the mode on screen rather than the one the server rendered it in.
+             */
+            { id: "themeMode", action: "change", valueType: "boolean" },
             { id: "pageDescription", action: "change", valueType: "string" },
             { id: "pageDescriptionClear", action: "clear", valueType: "none" },
             { id: "openGraphImage", action: "change", valueType: "image" },
@@ -63,6 +70,32 @@ export const PHI_CORE_RUNTIME_CONTROLLER_DEFINITION = {
                 valueType: "json",
                 valueSchema: PHI_SIGNAL_VALUE_SCHEMAS.runtimeNavigation,
             },
+            /*
+             * Ask the Server for this Page again, because what it renders has changed underneath it.
+             *
+             * The case is a Form that wrote something only the Server applies -- the language the account
+             * reads in, the mode it is shown in -- where the answer is not another Page but the same one,
+             * rendered again now that the account says something else. So it carries no value: there is
+             * nothing to say beyond "again", and the request that follows brings the new cookie with it.
+             *
+             * Staff Areas are routed by their own segment and carry no locale in the address, so the same
+             * address really is the right one. Public is localized in its path; a Page there that changes
+             * the language is a forward on `path`, not this.
+             */
+            { id: "reload", channel: "reload", action: "activate", valueType: "none" },
+            /*
+             * End the session this browser holds.
+             *
+             * Site scope, because that is what a session is: the cookie belongs to the account on this Site
+             * and not to the Area somebody happened to be in, and signing out of the Admin signs the same
+             * person out of App. Modelling it per Area would be six copies of one act that must never differ.
+             *
+             * It reaches the Site's own auth door, which every Site mounts whether or not an Auth Module is
+             * installed -- so an Area that Auth never enters can still offer a way out. That makes this the
+             * one input here that writes: everything else applies what was already decided, and the note in
+             * SIGNALS.md says which is which.
+             */
+            { id: "signOut", channel: "session", action: "clear", valueType: "none" },
             {
                 id: "notification",
                 channel: "notification",

package/components/runtime/core-runtime-controller-plugin.d.ts

@@ -19,6 +19,11 @@ export declare const PHI_CORE_RUNTIME_CONTROLLER_PLUGIN: {
             action: "change";
             valueType: "string";
             valueSchema?: undefined;
+        } | {
+            id: string;
+            action: "change";
+            valueType: "boolean";
+            valueSchema?: undefined;
         } | {
             id: string;
             action: "clear";
@@ -66,6 +71,12 @@ export declare const PHI_CORE_RUNTIME_CONTROLLER_PLUGIN: {
             action: "activate";
             valueType: "json";
             valueSchema: `${string}/signals/${string}`;
+        } | {
+            id: string;
+            channel: string;
+            action: "activate";
+            valueType: "none";
+            valueSchema?: undefined;
         })[];
     };
     defaultConfig: {};

package/components/runtime/phi-password-change-required-modal.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from "react";
+/**
+ * The password change an administrator asked for, in front of the Page and with no way past it.
+ *
+ * Nothing closes it: no button, no Escape, no click beside it. The server refuses the session everything
+ * else until the password is set, so a Page behind it has nothing to offer. The way on is the Form
+ * inside, or -- where no Module supplies one -- signing out and following the reset link, which is the
+ * one action offered then. Signing out goes through the Core Runtime Controller, which every Site mounts
+ * whatever Modules it installs.
+ */
+export declare function PhiPasswordChangeRequiredModal({ title, text, signOutLabel, children, }: {
+    title: string;
+    text: string;
+    signOutLabel: string | null;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/components/runtime/phi-password-change-required-modal.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PhiDialogControl } from "../controls/phi-dialog-control";
+import { PhiTypographyControl } from "../controls/phi-typography-control";
+import { createPhiCoreRuntimeControllerAddress } from "./core-runtime-controller-address";
+import { usePhiSignalEmitter } from "./runtime-signal-identity";
+/**
+ * The password change an administrator asked for, in front of the Page and with no way past it.
+ *
+ * Nothing closes it: no button, no Escape, no click beside it. The server refuses the session everything
+ * else until the password is set, so a Page behind it has nothing to offer. The way on is the Form
+ * inside, or -- where no Module supplies one -- signing out and following the reset link, which is the
+ * one action offered then. Signing out goes through the Core Runtime Controller, which every Site mounts
+ * whatever Modules it installs.
+ */
+export function PhiPasswordChangeRequiredModal({ title, text, signOutLabel, children, }) {
+    const emitSignal = usePhiSignalEmitter(null);
+    return (_jsxs(PhiDialogControl, { open: true, title: title, closable: false, keyboard: false, mask: { appearance: "normal", allowOutsideInteraction: false, closable: false }, centered: true, controlSize: "small", actions: signOutLabel
+            ? [{
+                    key: "sign-out",
+                    label: signOutLabel,
+                    type: "primary",
+                    onClick: () => emitSignal({
+                        scope: "site",
+                        channel: "session",
+                        action: "clear",
+                        value: null,
+                        valueType: "none",
+                        valueSchema: null,
+                        receiver: createPhiCoreRuntimeControllerAddress(),
+                    }),
+                }]
+            : [], children: [_jsx(PhiTypographyControl, { presentation: "paragraph", children: text }), children] }));
+}

package/components/runtime/phi-password-change-required.d.ts

@@ -0,0 +1,14 @@
+import type { PhiResolvedRuntimeRenderRegistry } from "../../plugins/runtime-modules/contracts";
+import type { PhiBlockRuntime } from "../../types";
+/**
+ * What a Page shows in front of itself while an administrator's password change is outstanding.
+ *
+ * The Form is whichever an active Module registers for `account-password-change` -- the Auth Module's
+ * own, or the one a replacement brings -- and not a Form id Core would have to know. Where no Module
+ * supplies one, the reset link that went out with the administrator's request is the way on, and
+ * signing out is offered rather than a link to somewhere that has no Form either.
+ */
+export declare function PhiPasswordChangeRequired({ runtime, registry, }: {
+    runtime: PhiBlockRuntime;
+    registry: PhiResolvedRuntimeRenderRegistry;
+}): Promise<import("react").JSX.Element>;

package/components/runtime/phi-password-change-required.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { findPhiFormDefinitionByPurpose, PHI_FORM_PURPOSES } from "../forms/form-registry";
+import { getPhiPasswordChangeRequiredLabels } from "../widgets/label-sets/profile";
+import { readPhiServerApiCredentials } from "../../helpers/phis-server-credentials";
+import { PhiFormWidget } from "../forms/phi-form-widget";
+import { parsePhiFormWidgetConfig } from "../forms/form-widget-config";
+import { createPhiCoreRuntimeControllerAddress } from "./core-runtime-controller-address";
+import { PhiPasswordChangeRequiredModal } from "./phi-password-change-required-modal";
+/*
+ * The Form's success asks for the Page again: the account no longer carries the flag then, and the Page
+ * renders without this in front of it.
+ */
+const RELOAD_ON_SUCCESS = {
+    emits: [{
+            routeKey: "password-change-required-reload",
+            capabilityId: "submitSuccess",
+            scope: "site",
+            channel: "reload",
+            action: "activate",
+            valueType: "none",
+            receiver: createPhiCoreRuntimeControllerAddress(),
+        }],
+};
+/**
+ * What a Page shows in front of itself while an administrator's password change is outstanding.
+ *
+ * The Form is whichever an active Module registers for `account-password-change` -- the Auth Module's
+ * own, or the one a replacement brings -- and not a Form id Core would have to know. Where no Module
+ * supplies one, the reset link that went out with the administrator's request is the way on, and
+ * signing out is offered rather than a link to somewhere that has no Form either.
+ */
+export async function PhiPasswordChangeRequired({ runtime, registry, }) {
+    const credentials = readPhiServerApiCredentials();
+    const labels = await getPhiPasswordChangeRequiredLabels({
+        apiBaseUrl: credentials.apiBaseUrl,
+        internalToken: credentials.internalToken,
+        locale: runtime.locale.current,
+    });
+    const form = findPhiFormDefinitionByPurpose(registry.formDefinitionsById.values(), PHI_FORM_PURPOSES.accountPasswordChange);
+    return (_jsx(PhiPasswordChangeRequiredModal, { title: labels.title, text: form ? labels.text : labels.emailOnlyText, signOutLabel: form ? null : labels.signOut, children: form ? (_jsx(PhiFormWidget, { runtime: runtime, registry: registry, formId: form.formId, formInstanceKey: "password-change-required", config: parsePhiFormWidgetConfig({ formId: form.formId, signalRoutes: RELOAD_ON_SUCCESS }) })) : null }));
+}

package/components/runtime/phi-state-machine-binding.d.ts

@@ -0,0 +1,40 @@
+import type { PhiRuntimeConditionSourceValues } from "../../types/runtime-condition";
+import type { PhiStateMachineCheckpoint, PhiStateMachineDefinition, PhiStateMachineReference, PhiStateMachineSnapshot } from "../../types/state-machine";
+export type PhiStateMachineSendResult = {
+    /** Whether the machine moved. Under `server` authority this is always false: Core decides. */
+    readonly taken: boolean;
+    /** The position for the host to keep, or null when this machine keeps none. */
+    readonly checkpoint: PhiStateMachineCheckpoint | null;
+    readonly snapshot: PhiStateMachineSnapshot;
+};
+export type UsePhiStateMachineBindingOptions = {
+    readonly definition: PhiStateMachineDefinition;
+    readonly reference: PhiStateMachineReference;
+    /**
+     * A position the host read back, from the query string or the account-bound store.
+     *
+     * Used only for the state the machine starts in, and discarded without complaint when its version no
+     * longer matches -- that is what the version is for.
+     */
+    readonly restored?: PhiStateMachineCheckpoint | null;
+};
+export type PhiStateMachineBinding = {
+    readonly snapshot: PhiStateMachineSnapshot;
+    /**
+     * Raise an event. Returns what the host should do about it.
+     *
+     * `sources` are the condition sources the guards read, and they are passed per call rather than held,
+     * because a guard evaluated against sources from the last render is the quiet mistake this whole
+     * mechanism exists to avoid. A machine without guards can leave them out.
+     */
+    readonly send: (event: string, sources?: PhiRuntimeConditionSourceValues) => PhiStateMachineSendResult;
+    /**
+     * Hand the machine what the authoritative reader answered. `server` authority only.
+     *
+     * This is the only way a projection's state changes. There is no local transition function to call
+     * instead, which is the structural part of `authority`: a third party cannot rebuild a security state
+     * machine in the browser because this package gives them nowhere to write one.
+     */
+    readonly project: (state: string, data?: Readonly<Record<string, unknown>>) => void;
+};
+export declare function usePhiStateMachineBinding({ definition, reference, restored, }: UsePhiStateMachineBindingOptions): PhiStateMachineBinding;

package/components/runtime/phi-state-machine-binding.js

@@ -0,0 +1,119 @@
+"use client";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { isPhiStateMachineState, readPhiStateMachineCheckpoint, readPhiStateMachineSnapshot, resolvePhiStateMachineTransition, restorePhiStateMachineState, } from "../../helpers/state-machine-binding";
+import { reportPhiStateMachineDivergence, reportPhiStateMachineMisuse, reportPhiStateMachineRefusal, } from "../../helpers/state-machine-diagnostics";
+export function usePhiStateMachineBinding({ definition, reference, restored, }) {
+    const initial = restorePhiStateMachineState(definition, restored) ?? definition.initial;
+    const [rendered, setRendered] = useState({ state: initial });
+    const positionRef = useRef(rendered);
+    /*
+     * Whether an answer is owed, which is what separates progress from divergence.
+     *
+     * A projection changing state is the ordinary case -- that is what a projection does -- so a report
+     * on every change would be noise, and noise is how the one that matters gets missed. What is
+     * surprising is a re-read that disagrees with what was on screen while nothing was asked: another tab
+     * finished the flow, a Session expired underneath, or the host projected a state without raising the
+     * event that would have asked for it. Sending sets this; projecting clears it.
+     *
+     * It starts owed for a projection, and that is not a convenience. A projection's first state always
+     * arrives unasked -- the host mounts, reads, and hands over whatever Core said -- so treating that as
+     * a contradiction would put a line in the console on every single sign-in, which is how the one line
+     * that means something stops being read. The machine has shown nothing yet; there is nothing for an
+     * answer to contradict.
+     */
+    const awaitingAnswer = useRef(definition.authority === "server");
+    /*
+     * Rendered from the state and never from the ref.
+     *
+     * The two hold the same position for different readers, and reading the ref here would be a real bug
+     * rather than a lint rule being strict: this memo is keyed on `rendered`, so a projection that brought
+     * new data for the state the machine was already in would have left the old data on screen. The state
+     * is the one that makes React re-run this.
+     */
+    const snapshot = useMemo(() => readPhiStateMachineSnapshot(definition, reference, rendered.state, rendered.data), [definition, reference, rendered]);
+    const send = useCallback((event, sources = {}) => {
+        const { state: from, data } = positionRef.current;
+        /*
+         * Under server authority an event is a request and never a transition.
+         *
+         * Nothing here moves: the next state arrives through `project`. A binding that guessed the outcome
+         * and corrected itself afterwards would be showing a state no server ever said. What the send does
+         * is record that an answer is owed, so the projection that follows is progress and not a
+         * contradiction -- and put the transition table to use, since an event from a state that does not
+         * answer to it is a fault worth reporting.
+         */
+        if (definition.authority === "server") {
+            const resolution = resolvePhiStateMachineTransition(definition, from, event, sources);
+            if (!resolution.taken) {
+                reportPhiStateMachineRefusal(reference, resolution.refusal, from, event);
+                return {
+                    taken: false,
+                    checkpoint: null,
+                    snapshot: readPhiStateMachineSnapshot(definition, reference, from, data),
+                };
+            }
+            awaitingAnswer.current = true;
+            return {
+                taken: false,
+                checkpoint: null,
+                snapshot: readPhiStateMachineSnapshot(definition, reference, from, data),
+            };
+        }
+        const resolution = resolvePhiStateMachineTransition(definition, from, event, sources);
+        if (!resolution.taken) {
+            reportPhiStateMachineRefusal(reference, resolution.refusal, from, event);
+            return {
+                taken: false,
+                checkpoint: null,
+                snapshot: readPhiStateMachineSnapshot(definition, reference, from, data),
+            };
+        }
+        const to = resolution.transition.to;
+        /*
+         * A transition onto the state the machine is already in reports nothing and keeps nothing.
+         *
+         * What is suppressed is the render and the checkpoint: a position that did not move is not worth a
+         * round trip, and a change signal for a state nobody left is the kind of no-op that ends in a loop.
+         */
+        if (to === from) {
+            return {
+                taken: true,
+                checkpoint: null,
+                snapshot: readPhiStateMachineSnapshot(definition, reference, from, data),
+            };
+        }
+        /*
+         * A new state arrives without the old one's data, which is why this replaces rather than merges.
+         * The data is the state's, not the machine's -- carrying it forward would let a Widget read a
+         * factor's method key while the machine is back at the beginning.
+         */
+        const next = { state: to };
+        positionRef.current = next;
+        setRendered(next);
+        return {
+            taken: true,
+            checkpoint: readPhiStateMachineCheckpoint(definition, to),
+            snapshot: readPhiStateMachineSnapshot(definition, reference, to),
+        };
+    }, [definition, reference]);
+    const project = useCallback((state, data) => {
+        if (definition.authority !== "server") {
+            reportPhiStateMachineMisuse(reference, `a state was pushed into a "client" authority machine, which owns its own. Send an event instead.`);
+            return;
+        }
+        if (!isPhiStateMachineState(definition, state)) {
+            reportPhiStateMachineRefusal(reference, "unknown-state", state, "<projected>");
+            return;
+        }
+        if (process.env.NODE_ENV !== "production" &&
+            !awaitingAnswer.current &&
+            positionRef.current.state !== state) {
+            reportPhiStateMachineDivergence(reference, positionRef.current.state, state);
+        }
+        awaitingAnswer.current = false;
+        const next = { state, ...(data ? { data } : {}) };
+        positionRef.current = next;
+        setRendered(next);
+    }, [definition, reference]);
+    return { snapshot, send, project };
+}

package/components/runtime/phi-video-consent-store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What this tab already answered for that provider.
+ *
+ * The default is always "no", which is what makes the first Client render agree with the Server's: the
+ * Server cannot see session storage, so a placeholder is what both draw. `seed` then turns it into a
+ * player, from an effect, the way the Form runtime restores an unsent draft.
+ */
+export declare function usePhiVideoVisitConsent(providerKey: string): boolean;
+/** Reads the answer this tab gave earlier. Called from an effect, never during a render. */
+export declare function seedPhiVideoVisitConsent(providerKey: string): void;
+/** Yes, for this tab, until it is closed or the answer is taken back. */
+export declare function grantPhiVideoVisitConsent(providerKey: string): void;
+/**
+ * Taking it back, which this step owes: withdrawal has to be possible at any time, and as easily as the
+ * consent was given. It ends the unlock for the tab and every placeholder returns to asking.
+ */
+export declare function revokePhiVideoVisitConsent(providerKey: string): void;

package/components/runtime/phi-video-consent-store.js

@@ -0,0 +1,54 @@
+"use client";
+import { createPhiPluginStateStore } from "../state/plugin-state-store";
+const PHI_VIDEO_VISIT_CONSENT_STORAGE_PREFIX = "phi.video.visit-consent:";
+const videoVisitConsentStore = createPhiPluginStateStore("@phis/ui/video-visit-consent", () => ({ unlocked: false }));
+function storageKey(providerKey) {
+    return `${PHI_VIDEO_VISIT_CONSENT_STORAGE_PREFIX}${providerKey}`;
+}
+/**
+ * What this tab already answered for that provider.
+ *
+ * The default is always "no", which is what makes the first Client render agree with the Server's: the
+ * Server cannot see session storage, so a placeholder is what both draw. `seed` then turns it into a
+ * player, from an effect, the way the Form runtime restores an unsent draft.
+ */
+export function usePhiVideoVisitConsent(providerKey) {
+    return videoVisitConsentStore.useStoreSelector(providerKey, (state) => state.unlocked);
+}
+/** Reads the answer this tab gave earlier. Called from an effect, never during a render. */
+export function seedPhiVideoVisitConsent(providerKey) {
+    let stored = null;
+    try {
+        stored = window.sessionStorage.getItem(storageKey(providerKey));
+    }
+    catch {
+        // An answer nobody can store is an answer nobody has to restore.
+        return;
+    }
+    if (stored === "1" && !videoVisitConsentStore.getSnapshot(providerKey).unlocked) {
+        videoVisitConsentStore.replace(providerKey, { unlocked: true });
+    }
+}
+/** Yes, for this tab, until it is closed or the answer is taken back. */
+export function grantPhiVideoVisitConsent(providerKey) {
+    videoVisitConsentStore.replace(providerKey, { unlocked: true });
+    try {
+        window.sessionStorage.setItem(storageKey(providerKey), "1");
+    }
+    catch {
+        // The unlock then lasts this page rather than this visit, which is the lesser of the two promises.
+    }
+}
+/**
+ * Taking it back, which this step owes: withdrawal has to be possible at any time, and as easily as the
+ * consent was given. It ends the unlock for the tab and every placeholder returns to asking.
+ */
+export function revokePhiVideoVisitConsent(providerKey) {
+    videoVisitConsentStore.replace(providerKey, { unlocked: false });
+    try {
+        window.sessionStorage.removeItem(storageKey(providerKey));
+    }
+    catch {
+        // Nothing stored, nothing to remove.
+    }
+}

package/components/runtime/renderable-block-runtime.d.ts

@@ -1,6 +1,5 @@
 import { type PhiSignal, type PhiSignalAction, type PhiSignalAddress, type PhiSignalRuntimeContext, type PhiSignalScope, type PhiSignalValue, type PhiSignalValueType } from "../../types/signals";
 import type { PhiRenderableBlock, PhiRenderableBlockCapabilities, PhiRenderableBlockRuntime, PhiRenderableBlockSize, PhiRenderableBlockVisibility } from "../../types/renderable-block";
-import type { PhiBlockRuntime } from "../../types/widget-runtime";
 import type { PhiCmsInstanceId } from "../../types/cms-instance-id";
 import { usePhiSignalDispatcher } from "./runtime-signal-bus";
 type PhiRenderableBlockSignalChannel = "visibility" | "enabled" | "background" | "border" | "selected" | "hovered" | "dragging" | "focused" | "active" | "layout" | "size" | "minSize" | "maxSize" | "shadow" | "zIndex" | "opacity" | "effects" | "text" | "content" | "html" | "markdown" | "markdownToc" | "descriptionConfig" | "icon" | "imageConfig" | "color" | "textColor" | "style" | "fontFamily" | "fontSize" | "textStyle" | "drag" | "drop" | "flush";
@@ -39,12 +38,5 @@ export type PhiRenderableBlockRuntimeController = {
     hide: () => void;
     toggle: () => void;
 };
-export type PhiRenderableWidgetRuntimeInput<TConfig extends Record<string, unknown> = Record<string, unknown>> = {
-    blockId: PhiCmsInstanceId | null | undefined;
-    receiver?: PhiRenderableBlockReceiver | null | undefined;
-    runtime: Pick<PhiBlockRuntime, "site" | "locale" | "area">;
-    config?: TConfig | null;
-};
 export declare function usePhiRenderableBlockRuntime(input?: Partial<PhiRenderableBlockRuntimeState>): PhiRenderableBlockRuntimeController;
-export declare function usePhiRenderableWidgetRuntime<TConfig extends Record<string, unknown> = Record<string, unknown>>(input: PhiRenderableWidgetRuntimeInput<TConfig>): PhiRenderableBlockRuntimeController;
 export {};