@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/scheme-sx.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Scheme-scoped node sx (AGL-588).
+ *
+ * Home: this module lived in `@aglyn/aglyn-node-renderer` (which re-exports
+ * it unchanged) until the instance override layer (AGL-1306) needed
+ * {@link mergeSchemeValue} from `composeReusableComponentNodes` — and this
+ * library cannot import the renderer, which imports it back.
+ *
+ * Sites resolve light/dark by SWAPPING a single-mode MUI theme: the
+ * tenant's `HostThemeProvider` picks the scheme from the shared cookie +
+ * `prefers-color-scheme` mode state and rebuilds the theme via
+ * `hostThemeToThemeOptions(theme, scheme)`; the besigner canvas does the
+ * same through `useAglynSiteTheme({ scheme: canvasScheme })`. There is no
+ * CSS-variables/attribute selector and no pure media-query dark mode to
+ * target — a `@media (prefers-color-scheme: dark)` slice would ignore the
+ * cookie override and would never show on the canvas. Scheme overrides
+ * are therefore resolved in JS against the ACTIVE theme's
+ * `palette.mode`, exactly like MUI's own non-CSS-vars
+ * `theme.applyStyles('dark', …)`.
+ *
+ * Persisted shape — the scheme dimension wraps the breakpoint dimension
+ * (scheme OUTER, breakpoints INNER): a node's sx may carry a single
+ * reserved {@link SX_SCHEME_DARK_KEY} slice whose entries are ordinary
+ * style properties, each optionally in MUI's responsive-object form:
+ *
+ * ```ts
+ * {
+ *   color: { xs: '#111', md: '#222' },        // base = light scheme
+ *   '@scheme dark': { color: '#eee' },        // dark override
+ * }
+ * ```
+ *
+ * Light (the default scheme) IS the base — there is no light slice.
+ * Renderers that predate this feature emit the slice as an unknown
+ * `@scheme dark { … }` at-rule, which browsers drop: dark overrides
+ * simply fall back to the base styles, never breaking light rendering.
+ */
+/** Reserved node-sx key holding dark-scheme style overrides. */
+export declare const SX_SCHEME_DARK_KEY = "@scheme dark";
+export type SxScheme = 'light' | 'dark';
+/**
+ * Whether a value is an sx responsive object — a non-empty record whose
+ * every key is a breakpoint name. Exported for the sibling merge utils
+ * (`mergeNodeSx`), which must route responsive values through
+ * {@link mergeSchemeValue} and everything else through leaf replacement.
+ */
+export declare const isResponsiveSxObject: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Merges a dark-scheme override over a base property value with real
+ * CSS-cascade semantics: at every breakpoint the override wins where it
+ * resolves (mobile-first within its own responsive object) and the base
+ * shows through where it does not. Plain (non-responsive) overrides
+ * therefore replace the property at every width; a `{ md: … }` override
+ * keeps the base's xs–sm values. The merged result is compacted —
+ * duplicate consecutive slices collapse and a single `xs` slice becomes
+ * a plain value.
+ */
+export declare function mergeSchemeValue(base: unknown, override: unknown): unknown;
+/**
+ * Resolves {@link SX_SCHEME_DARK_KEY} slices in an sx value against the
+ * active scheme: in dark, each slice entry merges over the base property
+ * ({@link mergeSchemeValue}); in light, slices drop. Arrays resolve
+ * per entry, theme callbacks are wrapped, and nested objects (pseudo
+ * selectors, custom CSS) resolve recursively. The input is never
+ * mutated.
+ */
+export declare function resolveSchemeSx<T>(sx: T, scheme: SxScheme): T;
+export default resolveSchemeSx;

package/src/lib/app-utils/scheme-sx.js

@@ -0,0 +1,148 @@
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { _ as _to_property_key } from "@swc/helpers/_/_to_property_key";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Scheme-scoped node sx (AGL-588).
+ *
+ * Home: this module lived in `@aglyn/aglyn-node-renderer` (which re-exports
+ * it unchanged) until the instance override layer (AGL-1306) needed
+ * {@link mergeSchemeValue} from `composeReusableComponentNodes` — and this
+ * library cannot import the renderer, which imports it back.
+ *
+ * Sites resolve light/dark by SWAPPING a single-mode MUI theme: the
+ * tenant's `HostThemeProvider` picks the scheme from the shared cookie +
+ * `prefers-color-scheme` mode state and rebuilds the theme via
+ * `hostThemeToThemeOptions(theme, scheme)`; the besigner canvas does the
+ * same through `useAglynSiteTheme({ scheme: canvasScheme })`. There is no
+ * CSS-variables/attribute selector and no pure media-query dark mode to
+ * target — a `@media (prefers-color-scheme: dark)` slice would ignore the
+ * cookie override and would never show on the canvas. Scheme overrides
+ * are therefore resolved in JS against the ACTIVE theme's
+ * `palette.mode`, exactly like MUI's own non-CSS-vars
+ * `theme.applyStyles('dark', …)`.
+ *
+ * Persisted shape — the scheme dimension wraps the breakpoint dimension
+ * (scheme OUTER, breakpoints INNER): a node's sx may carry a single
+ * reserved {@link SX_SCHEME_DARK_KEY} slice whose entries are ordinary
+ * style properties, each optionally in MUI's responsive-object form:
+ *
+ * ```ts
+ * {
+ *   color: { xs: '#111', md: '#222' },        // base = light scheme
+ *   '@scheme dark': { color: '#eee' },        // dark override
+ * }
+ * ```
+ *
+ * Light (the default scheme) IS the base — there is no light slice.
+ * Renderers that predate this feature emit the slice as an unknown
+ * `@scheme dark { … }` at-rule, which browsers drop: dark overrides
+ * simply fall back to the base styles, never breaking light rendering.
+ */ /** Reserved node-sx key holding dark-scheme style overrides. */ export const SX_SCHEME_DARK_KEY = '@scheme dark';
+/** MUI breakpoint keys, smallest to largest (`xs` doubles as the base). */ const SCHEME_SX_BREAKPOINTS = [
+    'xs',
+    'sm',
+    'md',
+    'lg',
+    'xl'
+];
+const isPlainObject = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Whether a value is an sx responsive object — a non-empty record whose
+ * every key is a breakpoint name. Exported for the sibling merge utils
+ * (`mergeNodeSx`), which must route responsive values through
+ * {@link mergeSchemeValue} and everything else through leaf replacement.
+ */ export const isResponsiveSxObject = (value)=>isPlainObject(value) && Object.keys(value).length > 0 && Object.keys(value).every((key)=>SCHEME_SX_BREAKPOINTS.includes(key));
+/**
+ * The value a (possibly responsive) sx property resolves to at the given
+ * breakpoint index, following MUI's mobile-first cascade. Plain values
+ * apply at every width.
+ */ function resolveResponsive(value, index) {
+    if (!isResponsiveSxObject(value)) return value;
+    for(let i = index; i >= 0; i -= 1){
+        const slice = value[SCHEME_SX_BREAKPOINTS[i]];
+        if (slice !== undefined) return slice;
+    }
+    return undefined;
+}
+/**
+ * Merges a dark-scheme override over a base property value with real
+ * CSS-cascade semantics: at every breakpoint the override wins where it
+ * resolves (mobile-first within its own responsive object) and the base
+ * shows through where it does not. Plain (non-responsive) overrides
+ * therefore replace the property at every width; a `{ md: … }` override
+ * keeps the base's xs–sm values. The merged result is compacted —
+ * duplicate consecutive slices collapse and a single `xs` slice becomes
+ * a plain value.
+ */ export function mergeSchemeValue(base, override) {
+    if (override === undefined) return base;
+    if (base === undefined) return override;
+    if (!isResponsiveSxObject(base) && !isResponsiveSxObject(override)) {
+        return override;
+    }
+    const merged = {};
+    let previous;
+    let hasPrevious = false;
+    SCHEME_SX_BREAKPOINTS.forEach((breakpoint, index)=>{
+        const fromOverride = resolveResponsive(override, index);
+        const resolved = fromOverride !== undefined ? fromOverride : resolveResponsive(base, index);
+        if (resolved === undefined) return;
+        if (!hasPrevious || resolved !== previous) {
+            merged[breakpoint] = resolved;
+            hasPrevious = true;
+            previous = resolved;
+        }
+    });
+    const keys = Object.keys(merged);
+    if (keys.length === 0) return undefined;
+    if (keys.length === 1 && keys[0] === 'xs') return merged['xs'];
+    return merged;
+}
+/**
+ * Resolves {@link SX_SCHEME_DARK_KEY} slices in an sx value against the
+ * active scheme: in dark, each slice entry merges over the base property
+ * ({@link mergeSchemeValue}); in light, slices drop. Arrays resolve
+ * per entry, theme callbacks are wrapped, and nested objects (pseudo
+ * selectors, custom CSS) resolve recursively. The input is never
+ * mutated.
+ */ export function resolveSchemeSx(sx, scheme) {
+    if (Array.isArray(sx)) {
+        return sx.map((entry)=>resolveSchemeSx(entry, scheme));
+    }
+    if (typeof sx === 'function') {
+        const callback = sx;
+        return (...args)=>resolveSchemeSx(callback(...args), scheme);
+    }
+    if (!isPlainObject(sx)) return sx;
+    const { [SX_SCHEME_DARK_KEY]: darkSlice } = sx, rest = _object_without_properties_loose(sx, [
+        _to_property_key(SX_SCHEME_DARK_KEY)
+    ]);
+    const out = {};
+    for (const [key, value] of Object.entries(rest)){
+        out[key] = isPlainObject(value) || Array.isArray(value) ? resolveSchemeSx(value, scheme) : value;
+    }
+    if (scheme === 'dark' && isPlainObject(darkSlice)) {
+        for (const [key, value] of Object.entries(darkSlice)){
+            const merged = mergeSchemeValue(out[key], value);
+            if (merged === undefined) delete out[key];
+            else out[key] = merged;
+        }
+    }
+    return out;
+}
+export default resolveSchemeSx;
+
+//# sourceMappingURL=scheme-sx.js.map

package/src/lib/app-utils/scheme-sx.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/scheme-sx.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Scheme-scoped node sx (AGL-588).\n *\n * Home: this module lived in `@aglyn/aglyn-node-renderer` (which re-exports\n * it unchanged) until the instance override layer (AGL-1306) needed\n * {@link mergeSchemeValue} from `composeReusableComponentNodes` — and this\n * library cannot import the renderer, which imports it back.\n *\n * Sites resolve light/dark by SWAPPING a single-mode MUI theme: the\n * tenant's `HostThemeProvider` picks the scheme from the shared cookie +\n * `prefers-color-scheme` mode state and rebuilds the theme via\n * `hostThemeToThemeOptions(theme, scheme)`; the besigner canvas does the\n * same through `useAglynSiteTheme({ scheme: canvasScheme })`. There is no\n * CSS-variables/attribute selector and no pure media-query dark mode to\n * target — a `@media (prefers-color-scheme: dark)` slice would ignore the\n * cookie override and would never show on the canvas. Scheme overrides\n * are therefore resolved in JS against the ACTIVE theme's\n * `palette.mode`, exactly like MUI's own non-CSS-vars\n * `theme.applyStyles('dark', …)`.\n *\n * Persisted shape — the scheme dimension wraps the breakpoint dimension\n * (scheme OUTER, breakpoints INNER): a node's sx may carry a single\n * reserved {@link SX_SCHEME_DARK_KEY} slice whose entries are ordinary\n * style properties, each optionally in MUI's responsive-object form:\n *\n * ```ts\n * {\n *   color: { xs: '#111', md: '#222' },        // base = light scheme\n *   '@scheme dark': { color: '#eee' },        // dark override\n * }\n * ```\n *\n * Light (the default scheme) IS the base — there is no light slice.\n * Renderers that predate this feature emit the slice as an unknown\n * `@scheme dark { … }` at-rule, which browsers drop: dark overrides\n * simply fall back to the base styles, never breaking light rendering.\n */\n\n/** Reserved node-sx key holding dark-scheme style overrides. */\nexport const SX_SCHEME_DARK_KEY = '@scheme dark'\n\nexport type SxScheme = 'light' | 'dark'\n\n/** MUI breakpoint keys, smallest to largest (`xs` doubles as the base). */\nconst SCHEME_SX_BREAKPOINTS = ['xs', 'sm', 'md', 'lg', 'xl'] as const\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * Whether a value is an sx responsive object — a non-empty record whose\n * every key is a breakpoint name. Exported for the sibling merge utils\n * (`mergeNodeSx`), which must route responsive values through\n * {@link mergeSchemeValue} and everything else through leaf replacement.\n */\nexport const isResponsiveSxObject = (\n  value: unknown,\n): value is Record<string, unknown> =>\n  isPlainObject(value) &&\n  Object.keys(value).length > 0 &&\n  Object.keys(value).every((key) =>\n    (SCHEME_SX_BREAKPOINTS as readonly string[]).includes(key),\n  )\n\n/**\n * The value a (possibly responsive) sx property resolves to at the given\n * breakpoint index, following MUI's mobile-first cascade. Plain values\n * apply at every width.\n */\nfunction resolveResponsive(value: unknown, index: number): unknown {\n  if (!isResponsiveSxObject(value)) return value\n  for (let i = index; i >= 0; i -= 1) {\n    const slice = value[SCHEME_SX_BREAKPOINTS[i]]\n    if (slice !== undefined) return slice\n  }\n  return undefined\n}\n\n/**\n * Merges a dark-scheme override over a base property value with real\n * CSS-cascade semantics: at every breakpoint the override wins where it\n * resolves (mobile-first within its own responsive object) and the base\n * shows through where it does not. Plain (non-responsive) overrides\n * therefore replace the property at every width; a `{ md: … }` override\n * keeps the base's xs–sm values. The merged result is compacted —\n * duplicate consecutive slices collapse and a single `xs` slice becomes\n * a plain value.\n */\nexport function mergeSchemeValue(base: unknown, override: unknown): unknown {\n  if (override === undefined) return base\n  if (base === undefined) return override\n  if (!isResponsiveSxObject(base) && !isResponsiveSxObject(override)) {\n    return override\n  }\n  const merged: Record<string, unknown> = {}\n  let previous: unknown\n  let hasPrevious = false\n  SCHEME_SX_BREAKPOINTS.forEach((breakpoint, index) => {\n    const fromOverride = resolveResponsive(override, index)\n    const resolved =\n      fromOverride !== undefined ? fromOverride : resolveResponsive(base, index)\n    if (resolved === undefined) return\n    if (!hasPrevious || resolved !== previous) {\n      merged[breakpoint] = resolved\n      hasPrevious = true\n      previous = resolved\n    }\n  })\n  const keys = Object.keys(merged)\n  if (keys.length === 0) return undefined\n  if (keys.length === 1 && keys[0] === 'xs') return merged['xs']\n  return merged\n}\n\n/**\n * Resolves {@link SX_SCHEME_DARK_KEY} slices in an sx value against the\n * active scheme: in dark, each slice entry merges over the base property\n * ({@link mergeSchemeValue}); in light, slices drop. Arrays resolve\n * per entry, theme callbacks are wrapped, and nested objects (pseudo\n * selectors, custom CSS) resolve recursively. The input is never\n * mutated.\n */\nexport function resolveSchemeSx<T>(sx: T, scheme: SxScheme): T {\n  if (Array.isArray(sx)) {\n    return sx.map((entry) => resolveSchemeSx(entry, scheme)) as T\n  }\n  if (typeof sx === 'function') {\n    const callback = sx as (...args: unknown[]) => unknown\n    return ((...args: unknown[]) =>\n      resolveSchemeSx(callback(...args), scheme)) as T\n  }\n  if (!isPlainObject(sx)) return sx\n\n  const { [SX_SCHEME_DARK_KEY]: darkSlice, ...rest } = sx as Record<\n    string,\n    unknown\n  >\n  const out: Record<string, unknown> = {}\n  for (const [key, value] of Object.entries(rest)) {\n    out[key] =\n      isPlainObject(value) || Array.isArray(value)\n        ? resolveSchemeSx(value, scheme)\n        : value\n  }\n  if (scheme === 'dark' && isPlainObject(darkSlice)) {\n    for (const [key, value] of Object.entries(darkSlice)) {\n      const merged = mergeSchemeValue(out[key], value)\n      if (merged === undefined) delete out[key]\n      else out[key] = merged\n    }\n  }\n  return out as T\n}\n\nexport default resolveSchemeSx\n"],"names":["SX_SCHEME_DARK_KEY","SCHEME_SX_BREAKPOINTS","isPlainObject","value","Array","isArray","isResponsiveSxObject","Object","keys","length","every","key","includes","resolveResponsive","index","i","slice","undefined","mergeSchemeValue","base","override","merged","previous","hasPrevious","forEach","breakpoint","fromOverride","resolved","resolveSchemeSx","sx","scheme","map","entry","callback","args","darkSlice","rest","out","entries"],"mappings":"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"}

package/src/lib/app-utils/scope-tokens.d.ts

@@ -0,0 +1,249 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Scoped sharing (AGL-1037): org-owned resources — datasets, media assets,
+ * media folders — carry a `visibleTo` array naming who may see them, so an
+ * agency can keep an internal dataset off its client sites without forking
+ * storage into a second host-scoped collection (see AGL-237, which moved
+ * these the other way).
+ *
+ * The shape is dictated by what both enforcement layers can evaluate:
+ * Firestore rules have no `.map()`, so the caller's read set is denormalized
+ * onto their member doc (AGL-1038) and matched with `list.hasAny(list)`;
+ * clients match the same field with `array-contains-any`. A flat array of
+ * strings is the only shape both primitives accept — the friendlier
+ * `{ kind, hostIds }` form is a presentation concern and lives in
+ * `describeScope` below, never on the doc.
+ */
+import type { ScopeToken } from '../foundation';
+export type { ScopeToken };
+/** Everyone in the owning org, and every host it owns. */
+export declare const ORG_SCOPE_TOKEN: "org";
+/**
+ * `array-contains-any` and `hasAny` both cap at 30 values. That caps a
+ * selected-sites scope at 30 hosts, and a collaborator's read query at 29
+ * hosts plus `'org'`. Wider than that is the `['org']` case.
+ */
+export declare const MAX_SCOPE_HOSTS = 30;
+/** `host:{hostId}` — the token naming a single site. */
+export declare function hostScopeToken(hostId: string): ScopeToken;
+export declare function isScopeToken(value: unknown): value is ScopeToken;
+/** Reads a token back apart; null when it isn't one. */
+export declare function parseScopeToken(token: string): {
+    kind: 'org';
+} | {
+    kind: 'host';
+    hostId: string;
+} | null;
+/** Every host id named by a scope, in order; `['org']` names none. */
+export declare function hostIdsFromScope(visibleTo: readonly string[] | undefined): string[];
+/**
+ * The read set for one site: what a server read path or a scoped client
+ * query passes to `array-contains-any`. `'org'` is included because an
+ * org-wide resource is visible to every host in the org.
+ */
+export declare function scopeTokensForHost(hostId: string): ScopeToken[];
+/**
+ * Whether a host may see a resource.
+ *
+ * ## A missing `visibleTo` is visible to NOBODY
+ *
+ * It once read as org-wide, so that documents predating the scope backfill
+ * stayed visible until it reached them. That default is the shape of failure
+ * this codebase keeps paying for: **a read that cannot see a value answered
+ * the same as a value that is absent.** "This document was never scoped" and
+ * "this document is shared with every site" are different facts, and one
+ * unscoped document under an agency account was one client's data on every
+ * other client's site — silently, because the permissive answer is the one
+ * nothing complains about.
+ *
+ * Both enforcement layers below this function already fail CLOSED on the
+ * missing field: `array-contains-any` matches nothing on a document that
+ * lacks the array, and the rules' `hasAny` is false for the same reason. So
+ * the permissive default was never a policy either of them agreed with — it
+ * was one TypeScript helper disagreeing with the database, which is what made
+ * AGL-1466 invisible for three weeks.
+ *
+ * The migration is `tools/scripts/backfill-consent-host.mjs`, which stamps
+ * `['org']` on the documents that should carry it. Until a document is
+ * stamped it is hidden, and hiding is the recoverable direction.
+ *
+ * An **empty array** answers the same and always did.
+ */
+export declare function visibleToHost(visibleTo: readonly string[] | undefined | null, hostId: string): boolean;
+/**
+ * Whether a caller holding `scopeTokens` (AGL-1038) may see a resource.
+ * The TypeScript twin of the rules' `visibleTo.hasAny(scopeTokens)`, for
+ * the Admin-SDK paths that never evaluate rules at all.
+ *
+ * A missing `visibleTo` is visible to nobody, for the reason
+ * {@link visibleToHost} gives — and here the twinning is the argument on its
+ * own: `hasAny` over a missing field is false in the rules, so a helper that
+ * answered `true` was not a twin of anything.
+ */
+export declare function visibleToTokens(visibleTo: readonly string[] | undefined | null, scopeTokens: readonly string[] | undefined | null): boolean;
+/**
+ * The scope a document ACTUALLY carries — `null` when it carries none
+ * (AGL-1466/AGL-1480).
+ *
+ * Every helper above this line answers "may this be seen", and answers it
+ * the way both enforcement layers do: a missing `visibleTo` is seen by
+ * nobody.
+ *
+ * An **editor** asks a different question — "what did somebody choose" —
+ * and it still needs its own answer, because "nobody chose" and "somebody
+ * chose nobody" are the same to an editor and different on the document.
+ * Four call sites across two files each wrote their own
+ *
+ * ```ts
+ * Array.isArray(doc.visibleTo) ? doc.visibleTo : [ORG_SCOPE_TOKEN]
+ * ```
+ *
+ * and every one of them rendered "All sites" over a document no site could
+ * see. That inversion is why AGL-1466 went three weeks unnoticed with the
+ * folder tree missing from every host, and AGL-1480 is the third and fourth
+ * copies of it turning up at the surface people use most.
+ *
+ * So: one function, the same lesson `newMediaFolderDoc` drew on the write
+ * side. A caller that wants a display default may still `?? []` or
+ * `?? [ORG_SCOPE_TOKEN]` — but it has to say so, in one visible place,
+ * instead of a ternary that reads like a null check.
+ *
+ * An empty array answers `null` too. On the document the two differ, and
+ * `newResourceScopeFields` refuses to WRITE one; to an editor they are the
+ * same fact — nobody chose this — and both must offer the choice rather
+ * than pre-fill an answer.
+ *
+ * Not normalized, deliberately. `normalizeVisibleTo` collapses for STORAGE;
+ * doing it here would make an untouched editor differ from the document it
+ * was seeded from, and the save gates compare exactly those two to decide
+ * whether to write at all.
+ */
+export declare function storedScope(visibleTo: readonly string[] | undefined | null): string[] | null;
+/**
+ * Cleans a scope for storage: drops junk, dedupes, and collapses to
+ * `['org']` when org-wide is present, since that already implies every
+ * host. Returns null when the result is unusable — empty, or over
+ * `MAX_SCOPE_HOSTS` — so the caller decides rather than this silently
+ * dropping hosts (losing access) or widening to org (leaking).
+ */
+export declare function normalizeVisibleTo(input: readonly string[] | undefined | null): ScopeToken[] | null;
+/**
+ * The scope a save writes, or why the selection cannot be written.
+ *
+ * {@link normalizeVisibleTo} answers null for a selection it cannot store, and
+ * a save has no safe substitute for that null: the org token shares the
+ * resource with every site, and dropping tokens takes access from sites
+ * somebody picked. So a caller refuses the save and shows `problem`.
+ */
+export declare function scopeToStore(input: readonly string[] | undefined | null): {
+    scope: ScopeToken[];
+    problem: null;
+} | {
+    scope: null;
+    problem: string;
+};
+/** A scope covering exactly the given hosts; null when unusable. */
+export declare function scopeForHosts(hostIds: readonly string[]): ScopeToken[] | null;
+/**
+ * Whether a scope is the org-wide one.
+ *
+ * An absent scope is NOT org-wide — see {@link visibleToHost}. That is the
+ * whole correction: this predicate is what `describeScope` renders and what
+ * `scopeCovers` and `narrowsScope` reason from, and while it answered `true`
+ * for a document nothing could see, the console said "All sites" over it.
+ */
+export declare function isOrgWideScope(visibleTo: readonly string[] | undefined | null): boolean;
+/**
+ * Whether moving from `before` to `after` takes visibility away from any
+ * host — the direction that can break a published page, and the one the
+ * console confirms before saving (AGL-1044/AGL-1045).
+ */
+export declare function narrowsScope(before: readonly string[] | undefined | null, after: readonly string[] | undefined | null): boolean;
+/**
+ * The sentence the console shows. `hostNames` maps host id → display name;
+ * ids missing from it fall back to the count wording, since a name we
+ * can't resolve is worse than no name.
+ */
+export declare function describeScope(visibleTo: readonly string[] | undefined | null, hostNames?: Readonly<Record<string, string>>): string;
+/**
+ * The scope a newly created resource starts with (AGL-1048).
+ *
+ * Honours the org's `defaultResourceScope`, but only when a site is
+ * actually in context: created from the org Media or Data page there is no
+ * host to scope to, and inventing one would hide the resource from the
+ * page that just created it.
+ */
+export declare function defaultScopeForNewResource(options: {
+    defaultResourceScope?: 'org' | 'host';
+    hostId?: string | null;
+}): ScopeToken[];
+/**
+ * The scope fields a document being CREATED in a scoped collection carries
+ * (AGL-1478), as a spreadable object.
+ *
+ * The argument is REQUIRED and has no default, which is the whole point.
+ * AGL-1466 was two call sites that each built a `mediaFolders` document
+ * inline and each forgot `visibleTo`; `newMediaFolderDoc` fixed that one
+ * collection by making the input mandatory, and this is the same guarantee
+ * for the collections that have no document constructor of their own —
+ * `datasets`, `media`, `contacts`, `contactSegments`. A creator that has
+ * not decided cannot compile.
+ *
+ * Three inputs, three meanings:
+ *
+ * - **tokens** — stamp them.
+ * - **`null`** — this collection is NOT scoped (a `hosts/{hostId}`
+ *   subcollection is private by construction), so store nothing. Saying it
+ *   out loud is what distinguishes "not applicable" from "forgotten".
+ * - **`[]`** — throws. Unlike a missing field, a stored empty array is a
+ *   written "visible to nobody": the backfill leaves it alone by design and
+ *   no read path treats it as legacy, so it is permanent where absent is
+ *   repairable. Getting here means a caller computed a scope and came back
+ *   with nothing, which is worth a stack trace.
+ */
+export declare function newResourceScopeFields(visibleTo: readonly ScopeToken[] | null): {
+    visibleTo?: ScopeToken[];
+};
+/**
+ * Whether `target` is visible everywhere `source` is — the condition a
+ * cross-dataset REFERENCE has to satisfy (AGL-1044).
+ *
+ * A reference field on dataset A pointing at dataset B is only resolvable
+ * on the sites that can see BOTH. If A is shared with a site that cannot
+ * see B, a page there resolves the reference to nothing: the row renders
+ * with a blank where the linked value should be, and nothing says why. So
+ * B's scope must COVER A's.
+ *
+ * Org-wide covers everything. A missing scope is seen by nobody and
+ * therefore covers nothing, matching the rest of this module.
+ */
+export declare function scopeCovers(target: readonly string[] | undefined | null, source: readonly string[] | undefined | null): boolean;
+/**
+ * Rewrites an org media CDN path so it names the site using the asset
+ * (AGL-1043/1045).
+ *
+ * `/api/media/cdn/org:{orgId}/{mediaId}` serves ORG-WIDE assets only. A
+ * restricted asset has to be requested through the form that names the
+ * site — `org:{orgId}:{hostId}` — because the CDN is unauthenticated and
+ * the URL is the only thing it can decide from.
+ *
+ * Returns the path untouched when there is nothing to do: an org-wide
+ * asset, a host-library asset, no host context, or a path that is not an
+ * org CDN URL. That keeps it safe to apply blindly at every pick site.
+ */
+export declare function hostQualifiedCdnPath(cdnPath: string | undefined | null, visibleTo: readonly string[] | undefined | null, hostId: string | undefined | null): string | undefined;