@phis/ui 0.2.1 → 0.3.0

package/helpers/cms-preset-page-tree.js

@@ -0,0 +1,83 @@
+import { createPhiPresetCmsPageId } from "../types/cms-instance-id";
+import { buildPhiRuntimeModulePackageRoutePrefix } from "./runtime-module-route-path";
+function humanizePageKey(value) {
+    const label = value.replace(/[-_]+/g, " ").trim();
+    return label ? label.replace(/\b\w/g, (letter) => letter.toUpperCase()) : value;
+}
+/**
+ * Puts one Module route into a Page tree, under the folders its path names.
+ *
+ * Shared by the Builder's catalog of every installed route and by the list of the Pages an Area answers
+ * on today, which a link picker offers (`gateway/page-references-route.ts`).
+ */
+export function insertPhiPresetPageTarget(roots, target) {
+    const sourcePreset = {
+        ownerModuleId: target.ownerModuleId,
+        presetKey: target.presetKey,
+        sourcePresetVersion: target.presetVersion,
+    };
+    const pageId = createPhiPresetCmsPageId({
+        ownerModuleId: target.ownerModuleId,
+        presetKey: target.presetKey,
+    });
+    /*
+     * The package namespace is an addressing device, not structure a person authored.
+     *
+     * Every Page of a Module outside Public answers under `/<scope>/<package>`, so leaving those segments
+     * in would bury every Page two folders deep under the same two words and say nothing about how the
+     * Pages relate. The tree shows what the Module arranged below its namespace; the address keeps it.
+     */
+    const namespace = target.area === "public"
+        ? ""
+        : buildPhiRuntimeModulePackageRoutePrefix(target.ownerModuleId);
+    const treePath = namespace && target.path.startsWith(`${namespace}/`)
+        ? target.path.slice(namespace.length)
+        : target.path;
+    const segments = treePath.split("/").filter(Boolean);
+    if (segments.length === 0) {
+        roots.push({
+            key: pageId,
+            title: target.title,
+            storagePath: target.path,
+            catalogPath: treePath,
+            sourcePreset,
+            ...(target.defaultPageFlags ? { defaultPageFlags: target.defaultPageFlags } : {}),
+            ...(target.landingPage ? { landingPage: true } : {}),
+        });
+        return;
+    }
+    let siblings = roots;
+    for (const segment of segments.slice(0, -1)) {
+        let group = siblings.find((node) => node.key === segment);
+        if (!group) {
+            group = { key: segment, title: humanizePageKey(segment), children: [] };
+            siblings.push(group);
+        }
+        group.children ??= [];
+        siblings = group.children;
+    }
+    siblings.push({
+        key: pageId,
+        title: target.title,
+        storagePath: target.path,
+        catalogPath: treePath,
+        sourcePreset,
+        ...(target.defaultPageFlags ? { defaultPageFlags: target.defaultPageFlags } : {}),
+        ...(target.landingPage ? { landingPage: true } : {}),
+    });
+}
+/**
+ * The Module Pages one Area answers on today, as catalog nodes.
+ *
+ * The routes that answer, not every one that was declared: this is what a link may point at, so a Page
+ * of a Module the Area has switched off is not offered, and of two routes claiming one address only the
+ * one the table lets answer is. A route with a parameter is left out -- `/news/:id` is a family of Pages,
+ * and a link names one -- which reading the exact paths does by itself.
+ */
+export function buildPhiAreaActivePresetPages(routeTable) {
+    const roots = [];
+    for (const descriptor of routeTable.exactByPath.values()) {
+        insertPhiPresetPageTarget(roots, descriptor);
+    }
+    return roots;
+}

package/helpers/cms-region-keys.d.ts

@@ -33,6 +33,5 @@ export declare function resolvePhiCmsRegionOwnership(regionKey: string | null |
  * know is not a placement anybody chose -- refusing it would hide Widgets over a typo.
  */
 export declare function phiCmsRegionAcceptsWidget(regionKey: string | null | undefined, required: PhiCmsRegionOwnership | null | undefined): boolean;
-export declare const PHI_CMS_REGION_KEY_BY_TYPE: Record<number, PhiCmsRegionKey>;
 export declare function resolvePhiCmsRegionType(regionKey: string | null | undefined): 10 | 40 | 50 | 11 | 12 | 20 | 21 | 25 | 30 | 39 | 41;
 export declare function resolvePhiCmsRegionKey(regionType: number | null | undefined): "content" | "header_top" | "header_main" | "header_bottom" | "sider_left" | "sider_right" | "hero" | "footer_top" | "footer_main" | "footer_bottom" | "drawer_right" | undefined;

package/helpers/cms-region-keys.js

@@ -56,7 +56,7 @@ export function phiCmsRegionAcceptsWidget(regionKey, required) {
     const ownership = resolvePhiCmsRegionOwnership(regionKey);
     return ownership === undefined || ownership === required;
 }
-export const PHI_CMS_REGION_KEY_BY_TYPE = Object.fromEntries(Object.entries(PHI_CMS_REGION_TYPE_BY_KEY).map(([key, type]) => [type, key]));
+const PHI_CMS_REGION_KEY_BY_TYPE = Object.fromEntries(Object.entries(PHI_CMS_REGION_TYPE_BY_KEY).map(([key, type]) => [type, key]));
 export function resolvePhiCmsRegionType(regionKey) {
     return regionKey && regionKey in PHI_CMS_REGION_TYPE_BY_KEY
         ? PHI_CMS_REGION_TYPE_BY_KEY[regionKey]

package/helpers/cms-routing.d.ts

@@ -1,5 +1,4 @@
 export declare const PHI_CMS_SPECIAL_ROOTS: ("app" | "admin" | "builder" | "editor" | "accounting")[];
-export type PhiCmsSpecialRoot = (typeof PHI_CMS_SPECIAL_ROOTS)[number];
 export declare function isKnownSpecialCmsRoot(root: string): boolean;
 export declare function isPhiReservedCmsRoot(root: string): boolean;
 export declare function normalizePhiCmsRouteSegment(segment: string): string;

package/helpers/cms-scope-search-params.d.ts

@@ -11,4 +11,8 @@ export declare function normalizePhiBuilderAreaSearchParam(value: unknown): PhiB
 export declare function normalizePhiBuilderPageSearchParam(value: unknown): string | null;
 export declare function serializePhiBuilderRuntimeModuleIdsSearchParam(moduleIds: readonly PhiRuntimeModuleId[]): string;
 export declare function normalizePhiBuilderRuntimeModuleIdsSearchParam(value: unknown): PhiRuntimeModuleId[] | null;
-export declare function normalizePhiBuilderRevisionsKindSearchParam(value: unknown): "area" | "page" | "navigation" | "theme" | null;
+/** What a revision can be the revision of -- the one list the review route and the Revisions page read. */
+export declare const PHI_CMS_REVIEW_KINDS: readonly ["area", "page", "navigation", "theme"];
+export type PhiCmsReviewKind = (typeof PHI_CMS_REVIEW_KINDS)[number];
+export declare function isPhiCmsReviewKind(value: unknown): value is PhiCmsReviewKind;
+export declare function normalizePhiBuilderRevisionsKindSearchParam(value: unknown): PhiCmsReviewKind | null;

package/helpers/cms-scope-search-params.js

@@ -27,6 +27,11 @@ export function normalizePhiBuilderRuntimeModuleIdsSearchParam(value) {
         return null;
     }
 }
+/** What a revision can be the revision of -- the one list the review route and the Revisions page read. */
+export const PHI_CMS_REVIEW_KINDS = ["area", "page", "navigation", "theme"];
+export function isPhiCmsReviewKind(value) {
+    return PHI_CMS_REVIEW_KINDS.includes(value);
+}
 export function normalizePhiBuilderRevisionsKindSearchParam(value) {
-    return value === "area" || value === "page" || value === "navigation" || value === "theme" ? value : null;
+    return isPhiCmsReviewKind(value) ? value : null;
 }

package/helpers/cms-tree-controller-settings.d.ts

@@ -0,0 +1,11 @@
+import type { PhiCmsTreeControllerSettings } from "../types/cms";
+/**
+ * Two trees' Controller settings put together, as their nodes are when a Shell or an Area Overlay is
+ * composed.
+ *
+ * A Controller configured by both is configured once, with the routes of both: each tree names the
+ * receivers it holds -- the Shell its header Widgets, an Overlay contribution its dialogs -- and the
+ * composed tree holds them all. Anything else both set, and a route both name, is refused like a
+ * duplicate node id: which one counted would be left to the order they were composed in.
+ */
+export declare function concatPhiCmsTreeControllerSettings(base: PhiCmsTreeControllerSettings | null | undefined, addition: PhiCmsTreeControllerSettings | null | undefined, label: string): PhiCmsTreeControllerSettings;

package/helpers/cms-tree-controller-settings.js

@@ -0,0 +1,37 @@
+import { joinPhiSignalRouteSets } from "./signal-route-set-join";
+/**
+ * Two trees' Controller settings put together, as their nodes are when a Shell or an Area Overlay is
+ * composed.
+ *
+ * A Controller configured by both is configured once, with the routes of both: each tree names the
+ * receivers it holds -- the Shell its header Widgets, an Overlay contribution its dialogs -- and the
+ * composed tree holds them all. Anything else both set, and a route both name, is refused like a
+ * duplicate node id: which one counted would be left to the order they were composed in.
+ */
+export function concatPhiCmsTreeControllerSettings(base, addition, label) {
+    const settings = [...(base ?? [])];
+    for (const setting of addition ?? []) {
+        const key = `${setting.type}:${setting.instanceKey}`;
+        const index = settings.findIndex((entry) => `${entry.type}:${entry.instanceKey}` === key);
+        if (index < 0) {
+            settings.push(setting);
+            continue;
+        }
+        const existing = settings[index];
+        const existingConfig = existing.config ?? {};
+        const addedConfig = setting.config ?? {};
+        const shared = Object.keys(addedConfig).filter((name) => name !== "signalRoutes" && name in existingConfig);
+        if (existing.mountScope !== setting.mountScope || shared.length > 0) {
+            throw new Error(`${label} configures Controller "${key}" twice.`);
+        }
+        const signalRoutes = joinPhiSignalRouteSets(existingConfig.signalRoutes, addedConfig.signalRoutes, {
+            duplicate: "refuse",
+            label: `${label}, Controller "${key}",`,
+        });
+        settings[index] = {
+            ...existing,
+            config: { ...existingConfig, ...addedConfig, ...(signalRoutes ? { signalRoutes } : {}) },
+        };
+    }
+    return settings;
+}

package/helpers/content-entry-record-binding.d.ts

@@ -0,0 +1,21 @@
+import type { PhiContentEntryKind } from "../constants/content-entry-kinds";
+import { type PhiRuntimeDataProviderBinding } from "../types/runtime-data-provider";
+/**
+ * A binding to one entry through the content entry record Provider (`types/record-provider.ts`): what a
+ * detail route's tree writes into the Widgets it places, the route's slug in the parameters.
+ */
+export declare function createPhiContentEntryRecordBinding(kind: PhiContentEntryKind, slug: string): PhiRuntimeDataProviderBinding;
+/**
+ * The record an entry Widget is bound to. A stored binding is kept whichever record Provider it names;
+ * a Widget that names none starts on the content entry Provider, with News and no address until somebody
+ * picks them in the Inspector.
+ */
+export declare function readPhiContentEntryRecordBinding(value: unknown): PhiRuntimeDataProviderBinding;
+/**
+ * What a binding says about its entry, for the Builder's placeholder: the kind and address it names, or
+ * nothing where it is bound to another Provider's record or names no address yet.
+ */
+export declare function describePhiContentEntryRecordBinding(binding: PhiRuntimeDataProviderBinding | null | undefined): {
+    kind: string | null;
+    slug: string;
+};

package/helpers/content-entry-record-binding.js

@@ -0,0 +1,31 @@
+import { PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS } from "../constants/core-data-provider-keys";
+import { readPhiRuntimeDataProviderBinding, } from "../types/runtime-data-provider";
+/**
+ * A binding to one entry through the content entry record Provider (`types/record-provider.ts`): what a
+ * detail route's tree writes into the Widgets it places, the route's slug in the parameters.
+ */
+export function createPhiContentEntryRecordBinding(kind, slug) {
+    return { providerKey: PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.contentEntry, params: { kind, slug } };
+}
+/**
+ * The record an entry Widget is bound to. A stored binding is kept whichever record Provider it names;
+ * a Widget that names none starts on the content entry Provider, with News and no address until somebody
+ * picks them in the Inspector.
+ */
+export function readPhiContentEntryRecordBinding(value) {
+    return readPhiRuntimeDataProviderBinding(value) ?? createPhiContentEntryRecordBinding("news", "");
+}
+/**
+ * What a binding says about its entry, for the Builder's placeholder: the kind and address it names, or
+ * nothing where it is bound to another Provider's record or names no address yet.
+ */
+export function describePhiContentEntryRecordBinding(binding) {
+    if (binding?.providerKey !== PHI_CORE_RUNTIME_DATA_PROVIDER_KEYS.contentEntry) {
+        return { kind: null, slug: "" };
+    }
+    const { kind, slug } = binding.params ?? {};
+    return {
+        kind: typeof kind === "string" ? kind : null,
+        slug: typeof slug === "string" ? slug.trim() : "",
+    };
+}

package/helpers/css-linear-gradient.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A CSS `linear-gradient(...)` read into a direction and stops, or why it cannot be one.
+ *
+ * One reader for every place that edits a gradient: the Background stores what it returns, and the
+ * colour picker offers to edit only what it can read -- the picker had a second parser that accepted
+ * corners and two-position stops the Background then refused.
+ */
+export type PhiCssLinearGradientDirection = "to right" | "to left" | "to bottom" | "to top" | `${number}deg`;
+export type PhiCssLinearGradientStop = {
+    color: string;
+    percent: number;
+};
+export type PhiCssLinearGradient = {
+    direction: PhiCssLinearGradientDirection;
+    stops: PhiCssLinearGradientStop[];
+};
+/**
+ * `null` means the string is no gradient at all and may still be a colour or an image; a gradient that
+ * cannot be held is a problem, never a colour.
+ */
+export type PhiCssLinearGradientReading = {
+    gradient: PhiCssLinearGradient;
+    problem?: undefined;
+} | {
+    gradient?: undefined;
+    problem: string;
+};
+export declare function readPhiCssLinearGradient(css: string): PhiCssLinearGradientReading | null;

package/helpers/css-linear-gradient.js

@@ -0,0 +1,122 @@
+function splitPhiCssGradientArguments(input) {
+    const stops = [];
+    let current = "";
+    let depth = 0;
+    for (const char of input) {
+        if (char === "(")
+            depth += 1;
+        if (char === ")")
+            depth = Math.max(0, depth - 1);
+        if (char === "," && depth === 0) {
+            stops.push(current.trim());
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim())
+        stops.push(current.trim());
+    return stops;
+}
+const PHI_CSS_NUMBER = "[-+]?(?:\\d+(?:\\.\\d+)?|\\.\\d+)";
+const PHI_CSS_ANGLE = new RegExp(`^(${PHI_CSS_NUMBER})(deg|grad|rad|turn)$`, "i");
+const PHI_CSS_GRADIENT_STOP = new RegExp(`^(.+?)(?:\\s+(${PHI_CSS_NUMBER})%)?$`);
+const PHI_CSS_DEGREES_PER_UNIT = { deg: 1, grad: 0.9, rad: 180 / Math.PI, turn: 360 };
+/**
+ * The first argument, when it is a direction.
+ *
+ * Only an angle or `to <side>` is one. Everything else is the first colour stop -- `red 0%` included,
+ * which read as a direction used to swallow the first stop and fall back to `to right`. A direction the
+ * Base cannot hold (a corner, an unreadable angle) is a problem rather than a stop.
+ */
+function readPhiCssGradientDirection(part) {
+    const side = part.match(/^to\s+(.+)$/i);
+    if (side) {
+        const target = side[1].trim().toLowerCase();
+        return target === "right" || target === "left" || target === "bottom" || target === "top"
+            ? { direction: `to ${target}` }
+            : { problem: `Gradient direction "${part}" is not supported; use an angle or one side.` };
+    }
+    const angle = part.match(PHI_CSS_ANGLE);
+    if (!angle) {
+        return null;
+    }
+    const unit = angle[2].toLowerCase();
+    const degrees = Number(angle[1]) * PHI_CSS_DEGREES_PER_UNIT[unit];
+    return Number.isFinite(degrees)
+        ? { direction: `${Math.round(degrees * 1000) / 1000}deg` }
+        : { problem: `Gradient angle "${part}" is not a number.` };
+}
+function readPhiCssGradientStop(part) {
+    const match = part.match(PHI_CSS_GRADIENT_STOP);
+    const color = match?.[1]?.trim();
+    if (!match || !color) {
+        return null;
+    }
+    // A colour is one token outside its parentheses; anything left over is a second position or a length.
+    let bare = color;
+    while (/\([^()]*\)/.test(bare))
+        bare = bare.replace(/\([^()]*\)/g, "");
+    if (/\s/.test(bare)) {
+        return null;
+    }
+    const percent = match[2] == null ? null : Number(match[2]);
+    return percent == null || Number.isFinite(percent) ? { color, percent } : null;
+}
+/**
+ * Positions for stops that name none, the way CSS places them: the first at 0, the last at 100, and
+ * any run in between evenly spaced between its neighbours.
+ */
+function placePhiCssGradientStops(stops) {
+    const percents = stops.map((stop) => stop.percent);
+    percents[0] ??= 0;
+    percents[percents.length - 1] ??= 100;
+    let previous = 0;
+    while (previous < percents.length - 1) {
+        let next = previous + 1;
+        while (percents[next] == null)
+            next += 1;
+        const start = percents[previous];
+        const end = percents[next];
+        for (let index = previous + 1; index < next; index += 1) {
+            percents[index] = start + ((end - start) * (index - previous)) / (next - previous);
+        }
+        previous = next;
+    }
+    return stops.map((stop, index) => ({ color: stop.color, percent: percents[index] }));
+}
+export function readPhiCssLinearGradient(css) {
+    const background = css.trim();
+    const kind = background.match(/^([a-z-]*gradient)\(/i)?.[1]?.toLowerCase();
+    if (!kind) {
+        return null;
+    }
+    if (kind !== "linear-gradient") {
+        return { problem: `A Background gradient is linear; "${kind}" is not supported.` };
+    }
+    if (!background.endsWith(")")) {
+        return { problem: "The gradient is not closed." };
+    }
+    const parts = splitPhiCssGradientArguments(background.slice("linear-gradient(".length, -1));
+    const direction = parts.length > 0 ? readPhiCssGradientDirection(parts[0]) : null;
+    if (direction && "problem" in direction) {
+        return { problem: direction.problem };
+    }
+    const stopParts = direction ? parts.slice(1) : parts;
+    if (stopParts.length < 2) {
+        return { problem: "A gradient needs at least two colour stops." };
+    }
+    const stops = stopParts.map(readPhiCssGradientStop);
+    const unreadable = stops.findIndex((stop) => stop === null);
+    if (unreadable >= 0) {
+        return { problem: `Gradient stop "${stopParts[unreadable]}" is not a colour with a percentage.` };
+    }
+    return {
+        gradient: {
+            // What CSS draws when a gradient names no direction.
+            direction: direction?.direction ?? "to bottom",
+            stops: placePhiCssGradientStops(stops),
+        },
+    };
+}

package/helpers/flags.d.ts

@@ -1 +1,11 @@
 export declare function hasPhiFlag(flags: number | null | undefined, flag: number): boolean;
+/**
+ * The flag set a stored config carries, read off its `flags` field.
+ *
+ * A config states its yes-or-no answers as bits (`PhiCmsFlags`), and a config that states none has none.
+ * Anything else in the field is a broken record and is refused rather than read as unset -- read as
+ * unset, a Sider would quietly lose its full height and the record would look as if it had never said so.
+ */
+/** Whether a stored config's `flags` carry the bit; the config may be absent, its field unset. */
+export declare function hasPhiConfigFlag(config: Record<string, unknown> | null | undefined, flag: number): boolean;
+export declare function readPhiFlags(value: unknown): number;

package/helpers/flags.js

@@ -1,3 +1,23 @@
 export function hasPhiFlag(flags, flag) {
     return ((flags ?? 0) & flag) === flag;
 }
+/**
+ * The flag set a stored config carries, read off its `flags` field.
+ *
+ * A config states its yes-or-no answers as bits (`PhiCmsFlags`), and a config that states none has none.
+ * Anything else in the field is a broken record and is refused rather than read as unset -- read as
+ * unset, a Sider would quietly lose its full height and the record would look as if it had never said so.
+ */
+/** Whether a stored config's `flags` carry the bit; the config may be absent, its field unset. */
+export function hasPhiConfigFlag(config, flag) {
+    return hasPhiFlag(readPhiFlags(config?.flags), flag);
+}
+export function readPhiFlags(value) {
+    if (value === undefined || value === null) {
+        return 0;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error(`A config's "flags" must be a non-negative integer, got ${JSON.stringify(value)}.`);
+    }
+    return value;
+}

package/helpers/form-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A Form id or a submit handler key as the registry files it: trimmed, lower-case.
+ *
+ * Three files normalised a Form id for themselves and a fourth its handler key, each `trim().toLowerCase()`;
+ * a registry that compares keys has to spell the comparison once, or a key written one way is filed
+ * under another.
+ */
+export declare function normalizePhiFormKey(value: string): string;

package/helpers/form-id.js

@@ -0,0 +1,10 @@
+/**
+ * A Form id or a submit handler key as the registry files it: trimmed, lower-case.
+ *
+ * Three files normalised a Form id for themselves and a fourth its handler key, each `trim().toLowerCase()`;
+ * a registry that compares keys has to spell the comparison once, or a key written one way is filed
+ * under another.
+ */
+export function normalizePhiFormKey(value) {
+    return value.trim().toLowerCase();
+}

package/helpers/format-date-time.d.ts

@@ -1,2 +1,7 @@
 export declare function formatPhiDate(value: string | null | undefined, locale: string): string;
 export declare function formatPhiDateTime(value: string | null | undefined, locale: string): string;
+/**
+ * How long ago or how far ahead, in the locale the caller names: "3 days ago", "in 2 hours". The
+ * largest unit the distance fills, so a moment reads in the words a person would use for it.
+ */
+export declare function formatPhiRelativeTime(value: string | null | undefined, locale: string, now?: number): string;

package/helpers/format-date-time.js

@@ -32,3 +32,34 @@ export function formatPhiDateTime(value, locale) {
         ? readFormatter(dateTimeFormatters, locale, { dateStyle: "medium", timeStyle: "short" }).format(date)
         : value || "—";
 }
+const relativeFormatters = new Map();
+const RELATIVE_UNITS = [
+    ["year", 365 * 24 * 60 * 60 * 1000],
+    ["month", 30 * 24 * 60 * 60 * 1000],
+    ["week", 7 * 24 * 60 * 60 * 1000],
+    ["day", 24 * 60 * 60 * 1000],
+    ["hour", 60 * 60 * 1000],
+    ["minute", 60 * 1000],
+];
+/**
+ * How long ago or how far ahead, in the locale the caller names: "3 days ago", "in 2 hours". The
+ * largest unit the distance fills, so a moment reads in the words a person would use for it.
+ */
+export function formatPhiRelativeTime(value, locale, now = Date.now()) {
+    const date = readPhiDate(value);
+    if (!date) {
+        return value || "—";
+    }
+    let formatter = relativeFormatters.get(locale);
+    if (!formatter) {
+        formatter = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+        relativeFormatters.set(locale, formatter);
+    }
+    const distance = date.getTime() - now;
+    for (const [unit, size] of RELATIVE_UNITS) {
+        if (Math.abs(distance) >= size) {
+            return formatter.format(Math.round(distance / size), unit);
+        }
+    }
+    return formatter.format(0, "minute");
+}

package/helpers/internal-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * An address on this Site, and only one.
+ *
+ * The rule is phis-server's `normalizeAuthNextPath`, kept the same on both sides: one leading slash,
+ * no second slash or backslash after it, no control characters, and parsed against a fixed origin it
+ * must not leave. The backslash is the one that matters -- a browser reads `/\evil.com` as `//evil.com`,
+ * so a reader that refused only `//` sent a visitor who finished signing in onto somebody else's host.
+ *
+ * Returns the trimmed path with its query and fragment, or `null`. Where a caller wants only the
+ * pathname it resolves the accepted value itself; the check is what this shares.
+ */
+export declare function readPhiInternalPath(value: unknown): string | null;

package/helpers/internal-path.js

@@ -0,0 +1,28 @@
+/**
+ * An address on this Site, and only one.
+ *
+ * The rule is phis-server's `normalizeAuthNextPath`, kept the same on both sides: one leading slash,
+ * no second slash or backslash after it, no control characters, and parsed against a fixed origin it
+ * must not leave. The backslash is the one that matters -- a browser reads `/\evil.com` as `//evil.com`,
+ * so a reader that refused only `//` sent a visitor who finished signing in onto somebody else's host.
+ *
+ * Returns the trimmed path with its query and fragment, or `null`. Where a caller wants only the
+ * pathname it resolves the accepted value itself; the check is what this shares.
+ */
+export function readPhiInternalPath(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim();
+    if (!normalized.startsWith("/") ||
+        normalized.startsWith("//") ||
+        normalized.includes("\\") ||
+        /[\u0000-\u001f\u007f]/u.test(normalized)) {
+        return null;
+    }
+    try {
+        return new URL(normalized, "https://phi.invalid").origin === "https://phi.invalid" ? normalized : null;
+    }
+    catch {
+        return null;
+    }
+}

package/helpers/is-record.js

@@ -1,6 +1,7 @@
 // About thirty files each carried a private copy of this predicate, and "plain object record" had two
 // possible answers for arrays. One export means the answer is chosen once: arrays are not records, so a
-// JSON array never passes as a keyed config object.
+// JSON array never passes as a keyed config object. Seventy more copies had grown back by 2026-10-05;
+// `scripts/validate-record-predicate.mjs` now fails the build for every spelling of the question but this.
 export function isPhiRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }

package/helpers/layout-authoring-markers.d.ts

@@ -23,8 +23,6 @@ export type PhiLayoutAuthoringSignal = {
 export declare function isPhiLayoutAuthoringRender(signal: PhiLayoutAuthoringSignal): boolean;
 /** The layout band's marker, and nothing at all outside authoring. */
 export declare function phiLayoutDebugLayerMarker(authoring: boolean): "layout" | undefined;
-/** The slot band's class, joinable with a layout's own slot class. */
-export declare function phiLayoutScaffoldSlotMarker(authoring: boolean): "phi-layout-scaffold-slot" | undefined;
 /** Whether a slot holds something, which only the scaffold asks. */
 export declare function phiLayoutSlotContentMarker(authoring: boolean, hasContent: boolean): "false" | "true" | undefined;
 /** Joins a layout's own slot class with the marker, dropping what is absent. */

package/helpers/layout-authoring-markers.js

@@ -23,7 +23,7 @@ export function phiLayoutDebugLayerMarker(authoring) {
     return authoring ? "layout" : undefined;
 }
 /** The slot band's class, joinable with a layout's own slot class. */
-export function phiLayoutScaffoldSlotMarker(authoring) {
+function phiLayoutScaffoldSlotMarker(authoring) {
     return authoring ? "phi-layout-scaffold-slot" : undefined;
 }
 /** Whether a slot holds something, which only the scaffold asks. */

package/helpers/layout-style.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from "react";
-import { type PhiLayoutEffectId, type PhiShadow } from "../types/layout-style";
+import { type PhiGlassLayoutEffectId, type PhiShadow } from "../types/layout-style";
 /**
  * What each glass strength is made of.
  *
@@ -17,20 +17,6 @@ export declare const PHI_GLASS_LAYOUT_EFFECT_DEFINITIONS: {
         readonly strengthPercent: 60;
     };
 };
-export declare const PHI_LAYOUT_EFFECT_DEFINITIONS: {
-    readonly glass: {
-        readonly backdropFilter: "blur(24px) saturate(1.2)";
-    };
-    readonly haze: {
-        readonly backdropFilter: "blur(10px) saturate(1.1)";
-    };
-    readonly blur: {
-        readonly filter: "blur(6px)";
-    };
-    readonly dim: {
-        readonly filter: "brightness(0.85)";
-    };
-};
 export declare const PHI_SHADOW_DEFINITIONS: {
     readonly none: "none";
     readonly soft: "var(--ant-box-shadow-tertiary)";
@@ -38,7 +24,7 @@ export declare const PHI_SHADOW_DEFINITIONS: {
 };
 export declare function resolvePhiShadow(value: PhiShadow | null | undefined): CSSProperties["boxShadow"] | undefined;
 export declare function resolvePhiLayoutEffectStyle({ effect, background, }: {
-    effect?: PhiLayoutEffectId | null;
+    effect?: PhiGlassLayoutEffectId | null;
     background?: CSSProperties["background"];
 }): CSSProperties | undefined;
 export declare function composePhiLayoutEffectStyle(baseStyle: CSSProperties, effectStyle: CSSProperties | null | undefined): CSSProperties;