@fias/arche-sdk 2.12.0 → 2.13.0

package/dist/panels.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Panels — the declarative content shape, and a validator for plugins that store
+ * panels as DATA.
+ *
+ * A panel is a bounded block of content (a title, ordered leaf elements, some
+ * buttons) rendered by `@fias/panel-kit`, which the platform serves to plugin
+ * iframes from its own CDN (declare the `sandbox:vendored-libraries` permission
+ * and list `"@fias/panel-kit"` in your manifest `dependencies`). See
+ * `templates/default/CLAUDE.md` § Panels.
+ *
+ * WHAT THIS MODULE IS FOR. Rendering needs no help from the SDK — panel-kit takes
+ * a plain object. What the SDK adds is the part a plugin cannot do for itself:
+ *
+ *   1. **The types**, so a plugin written against the published npm package has
+ *      the same shape the platform validates, without depending on panel-kit's
+ *      private workspace package for type information.
+ *   2. **`validatePanelCatalog`**, so a plugin that keeps its panels as data —
+ *      in `useFiasDataStore`, in a config document, in an admin-edited blob —
+ *      can gate a WRITE the way the platform gates its own server-authored
+ *      catalogs, instead of discovering a malformed panel when a player sees a
+ *      blank one.
+ *
+ * That second point is the whole design: **panels stored as data need no new
+ * platform op.** A plugin already has generic storage; what it lacked was the
+ * shared definition of "valid". Nothing here talks to the platform, nothing is
+ * gated, nothing is billed — it is a pure function over a value you already hold,
+ * which is why it can live in the SDK rather than behind a bridge call.
+ *
+ * MIRROR, NOT A FORK. The canonical schema is `panelThemeSchema` /
+ * `panelElementSchema` in `packages/db-types/src/panel-definition.ts` (Zod,
+ * server-side). This is a hand-written mirror for the same reason panel-kit's
+ * types are: `@fias/db-types` is a server package that would drag zod and a large
+ * unrelated surface into every plugin bundle. `tests/architecture/panel-schema-mirror.test.ts`
+ * runs the canonical corpora against BOTH mirrors, so a grammar cannot drift here
+ * without failing CI.
+ *
+ * A renderer older than a definition SKIPS element kinds it does not know. This
+ * validator is deliberately stricter than that: an unknown kind is an ERROR, so an
+ * authoring mistake fails at write time rather than rendering as silence.
+ */
+/** Element list bounds. Mirrors `PANEL_*` in db-types. */
+export declare const PANEL_MIN_ELEMENTS = 1;
+export declare const PANEL_MAX_ELEMENTS = 24;
+export declare const PANEL_TITLE_MAX_LENGTH = 80;
+export declare const PANEL_TEXT_MAX_LENGTH = 500;
+export declare const PANEL_IMAGE_ALT_MAX_LENGTH = 120;
+export declare const PANEL_IMAGE_KEY_MAX_LENGTH = 500;
+export declare const PANEL_IMAGE_MIN_HEIGHT = 24;
+export declare const PANEL_IMAGE_MAX_HEIGHT = 512;
+export declare const PANEL_BUTTON_LABEL_MAX_LENGTH = 40;
+export declare const PANEL_ACTION_MAX_LENGTH = 2048;
+export declare const PANEL_EMIT_TOKEN_MAX_LENGTH = 64;
+export declare const PANEL_ITEMS_EMPTY_TEXT_MAX_LENGTH = 120;
+export declare const PANEL_ITEMS_SLOT_MAX_LENGTH = 64;
+export declare const PANEL_SHOW_IF_MAX_LENGTH = 64;
+export declare const PANEL_PRIORITY_ABS_MAX = 1000;
+export declare const PANEL_THEME_FONT_MAX_LENGTH = 200;
+export declare const PANEL_THEME_AMOUNT_FORMAT_MAX_LENGTH = 24;
+export declare const PANEL_THEME_Z_MAX = 1000000;
+export declare const PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS = 4;
+/**
+ * Storage roots the platform will presign inside a panel image key. A key outside
+ * them is not merely unusual — it is one the platform will not resolve, so it
+ * would render as a permanently missing image.
+ */
+export declare const PANEL_IMAGE_ROOTS: readonly ["dfe-icons", "dfe-avatars"];
+/** Leaf kinds only — panels do not nest. Order matches the canonical union. */
+export declare const PANEL_ELEMENT_KINDS: readonly ["text", "conditionalText", "image", "assetImage", "items", "slottedItems", "button", "spacer"];
+export type PanelElementKind = (typeof PANEL_ELEMENT_KINDS)[number];
+export type PanelTextStyle = 'title' | 'body' | 'caption';
+export type PanelTextAlign = 'left' | 'center' | 'right';
+export type PanelSize = 'small' | 'medium' | 'large';
+interface PanelTextFields {
+    text: string;
+    style?: PanelTextStyle;
+    align?: PanelTextAlign;
+    /** Draw on the same line as the element that follows. Purely a line-break hint. */
+    joinNext?: boolean;
+}
+export interface PanelTextElement extends PanelTextFields {
+    kind: 'text';
+}
+/** Drawn only when `context.values[showIf]` is truthy. `showIf` is a value NAME, never an expression. */
+export interface PanelConditionalTextElement extends PanelTextFields {
+    kind: 'conditionalText';
+    showIf: string;
+}
+export interface PanelImageElement {
+    kind: 'image';
+    /** Relative platform-storage key under {@link PANEL_IMAGE_ROOTS}; the platform presigns it. */
+    imageKey: string;
+    alt?: string;
+    maxHeight?: number;
+}
+export interface PanelAssetImageElement {
+    kind: 'assetImage';
+    /** `as_<32 hex>` — an arche asset-library id. */
+    assetId: string;
+    alt?: string;
+    maxHeight?: number;
+}
+export interface PanelItemsElement {
+    kind: 'items';
+    showIcons?: boolean;
+    iconSize?: PanelSize;
+    emptyText?: string;
+}
+/** Draws `context.itemsBySlot[slot]` — one panel, several independent lists. */
+export interface PanelSlottedItemsElement {
+    kind: 'slottedItems';
+    slot: string;
+    showIcons?: boolean;
+    iconSize?: PanelSize;
+    emptyText?: string;
+}
+export interface PanelButtonElement {
+    kind: 'button';
+    label: string;
+    /** `close` | `emit:<token>` | `open_arche:arc_<32 hex>` | `open_url:https://…` */
+    action: string;
+    variant?: 'primary' | 'secondary';
+}
+export interface PanelSpacerElement {
+    kind: 'spacer';
+    size?: PanelSize;
+}
+export type PanelElement = PanelTextElement | PanelConditionalTextElement | PanelImageElement | PanelAssetImageElement | PanelItemsElement | PanelSlottedItemsElement | PanelButtonElement | PanelSpacerElement;
+/** An authored hint about presentation; the call site may override any of it. */
+export interface PanelPresentation {
+    size?: PanelSize;
+    dismissible?: boolean;
+    priority?: number;
+}
+export interface PanelDefinition {
+    /** 2–64 chars: lowercase letters, digits and hyphens, not starting with a hyphen. */
+    id: string;
+    title: string;
+    elements: PanelElement[];
+    presentation?: PanelPresentation;
+}
+/** Colours, font, radii, spacing and quantity format for a whole catalog. */
+export interface PanelTheme {
+    bg?: string;
+    fg?: string;
+    border?: string;
+    accent?: string;
+    accentFg?: string;
+    scrim?: string;
+    font?: string;
+    radius?: string;
+    buttonRadius?: string;
+    gap?: string;
+    fontSize?: string;
+    widthSmall?: string;
+    widthMedium?: string;
+    widthLarge?: string;
+    z?: number;
+    /** Must contain `{n}` — `×{n}` renders 25 as `×25`. */
+    amountFormat?: string;
+}
+/** A plugin's own stored panels: the definitions plus one optional theme. */
+export interface PanelCatalog {
+    panels: PanelDefinition[];
+    theme?: PanelTheme;
+}
+/** `ok: false` carries one human-readable issue per problem, each prefixed by its path. */
+export type PanelValidationResult = {
+    ok: true;
+    issues: [];
+} | {
+    ok: false;
+    issues: string[];
+};
+type Issues = string[];
+/**
+ * The closed action namespace. `open_url` is checked by PARSING the URL, not by a
+ * regex, so `javascript:`, `data:`, protocol-relative and whitespace-obfuscated
+ * forms are rejected the same way the platform rejects them.
+ */
+export declare function validatePanelAction(action: unknown, path: string, issues: Issues): void;
+/**
+ * Validate an authored theme.
+ *
+ * The grammars are tight on purpose, and the reason is not style policing: a theme
+ * value becomes a CSS custom property, and a custom property can otherwise carry
+ * `url(…)` — an outbound request from every surface that draws one of your panels
+ * — or a `;` that escapes its declaration. Colours are hex or `rgb()/rgba()`,
+ * lengths are `px`/`rem`/`em`, and a font stack admits no parentheses at all.
+ */
+export declare function validatePanelTheme(value: unknown, path?: string): PanelValidationResult;
+/** Validate one panel definition. */
+export declare function validatePanelDefinition(value: unknown, path?: string): PanelValidationResult;
+/**
+ * Validate a whole catalog — `{ panels, theme? }` — before you STORE it.
+ *
+ * Call this on the write side (a DataStore document, a config blob, an admin form
+ * submit), not on the read side. A renderer skipping an element it cannot draw is
+ * a designed degrade; a panel that was never valid is an authoring bug, and the
+ * difference between the two is which side of the write you find out on.
+ *
+ * ```ts
+ * const result = validatePanelCatalog(draft);
+ * if (!result.ok) return setErrors(result.issues);
+ * await datastore.put('panels', draft);
+ * ```
+ *
+ * Panel ids must be unique within a catalog: they are used for dedupe, telemetry
+ * and render keys, so a duplicate is an authoring error rather than a
+ * last-one-wins.
+ */
+export declare function validatePanelCatalog(value: unknown): PanelValidationResult;
+export {};
+//# sourceMappingURL=panels.d.ts.map

package/dist/panels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panels.d.ts","sourceRoot":"","sources":["../src/panels.ts"],"names":[],"mappings":"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"}

package/dist/panels.js

@@ -0,0 +1,422 @@
+"use strict";
+/**
+ * Panels — the declarative content shape, and a validator for plugins that store
+ * panels as DATA.
+ *
+ * A panel is a bounded block of content (a title, ordered leaf elements, some
+ * buttons) rendered by `@fias/panel-kit`, which the platform serves to plugin
+ * iframes from its own CDN (declare the `sandbox:vendored-libraries` permission
+ * and list `"@fias/panel-kit"` in your manifest `dependencies`). See
+ * `templates/default/CLAUDE.md` § Panels.
+ *
+ * WHAT THIS MODULE IS FOR. Rendering needs no help from the SDK — panel-kit takes
+ * a plain object. What the SDK adds is the part a plugin cannot do for itself:
+ *
+ *   1. **The types**, so a plugin written against the published npm package has
+ *      the same shape the platform validates, without depending on panel-kit's
+ *      private workspace package for type information.
+ *   2. **`validatePanelCatalog`**, so a plugin that keeps its panels as data —
+ *      in `useFiasDataStore`, in a config document, in an admin-edited blob —
+ *      can gate a WRITE the way the platform gates its own server-authored
+ *      catalogs, instead of discovering a malformed panel when a player sees a
+ *      blank one.
+ *
+ * That second point is the whole design: **panels stored as data need no new
+ * platform op.** A plugin already has generic storage; what it lacked was the
+ * shared definition of "valid". Nothing here talks to the platform, nothing is
+ * gated, nothing is billed — it is a pure function over a value you already hold,
+ * which is why it can live in the SDK rather than behind a bridge call.
+ *
+ * MIRROR, NOT A FORK. The canonical schema is `panelThemeSchema` /
+ * `panelElementSchema` in `packages/db-types/src/panel-definition.ts` (Zod,
+ * server-side). This is a hand-written mirror for the same reason panel-kit's
+ * types are: `@fias/db-types` is a server package that would drag zod and a large
+ * unrelated surface into every plugin bundle. `tests/architecture/panel-schema-mirror.test.ts`
+ * runs the canonical corpora against BOTH mirrors, so a grammar cannot drift here
+ * without failing CI.
+ *
+ * A renderer older than a definition SKIPS element kinds it does not know. This
+ * validator is deliberately stricter than that: an unknown kind is an ERROR, so an
+ * authoring mistake fails at write time rather than rendering as silence.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PANEL_ELEMENT_KINDS = exports.PANEL_IMAGE_ROOTS = exports.PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS = exports.PANEL_THEME_Z_MAX = exports.PANEL_THEME_AMOUNT_FORMAT_MAX_LENGTH = exports.PANEL_THEME_FONT_MAX_LENGTH = exports.PANEL_PRIORITY_ABS_MAX = exports.PANEL_SHOW_IF_MAX_LENGTH = exports.PANEL_ITEMS_SLOT_MAX_LENGTH = exports.PANEL_ITEMS_EMPTY_TEXT_MAX_LENGTH = exports.PANEL_EMIT_TOKEN_MAX_LENGTH = exports.PANEL_ACTION_MAX_LENGTH = exports.PANEL_BUTTON_LABEL_MAX_LENGTH = exports.PANEL_IMAGE_MAX_HEIGHT = exports.PANEL_IMAGE_MIN_HEIGHT = exports.PANEL_IMAGE_KEY_MAX_LENGTH = exports.PANEL_IMAGE_ALT_MAX_LENGTH = exports.PANEL_TEXT_MAX_LENGTH = exports.PANEL_TITLE_MAX_LENGTH = exports.PANEL_MAX_ELEMENTS = exports.PANEL_MIN_ELEMENTS = void 0;
+exports.validatePanelAction = validatePanelAction;
+exports.validatePanelTheme = validatePanelTheme;
+exports.validatePanelDefinition = validatePanelDefinition;
+exports.validatePanelCatalog = validatePanelCatalog;
+/** Element list bounds. Mirrors `PANEL_*` in db-types. */
+exports.PANEL_MIN_ELEMENTS = 1;
+exports.PANEL_MAX_ELEMENTS = 24;
+exports.PANEL_TITLE_MAX_LENGTH = 80;
+exports.PANEL_TEXT_MAX_LENGTH = 500;
+exports.PANEL_IMAGE_ALT_MAX_LENGTH = 120;
+exports.PANEL_IMAGE_KEY_MAX_LENGTH = 500;
+exports.PANEL_IMAGE_MIN_HEIGHT = 24;
+exports.PANEL_IMAGE_MAX_HEIGHT = 512;
+exports.PANEL_BUTTON_LABEL_MAX_LENGTH = 40;
+exports.PANEL_ACTION_MAX_LENGTH = 2048;
+exports.PANEL_EMIT_TOKEN_MAX_LENGTH = 64;
+exports.PANEL_ITEMS_EMPTY_TEXT_MAX_LENGTH = 120;
+exports.PANEL_ITEMS_SLOT_MAX_LENGTH = 64;
+exports.PANEL_SHOW_IF_MAX_LENGTH = 64;
+exports.PANEL_PRIORITY_ABS_MAX = 1000;
+exports.PANEL_THEME_FONT_MAX_LENGTH = 200;
+exports.PANEL_THEME_AMOUNT_FORMAT_MAX_LENGTH = 24;
+exports.PANEL_THEME_Z_MAX = 1000000;
+exports.PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS = 4;
+/**
+ * Storage roots the platform will presign inside a panel image key. A key outside
+ * them is not merely unusual — it is one the platform will not resolve, so it
+ * would render as a permanently missing image.
+ */
+exports.PANEL_IMAGE_ROOTS = ['dfe-icons', 'dfe-avatars'];
+/** Leaf kinds only — panels do not nest. Order matches the canonical union. */
+exports.PANEL_ELEMENT_KINDS = [
+    'text',
+    'conditionalText',
+    'image',
+    'assetImage',
+    'items',
+    'slottedItems',
+    'button',
+    'spacer',
+];
+const PANEL_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
+const SLOT_PATTERN = new RegExp(`^[a-z0-9][a-z0-9_-]{0,${exports.PANEL_ITEMS_SLOT_MAX_LENGTH - 1}}$`);
+const EMIT_TOKEN_PATTERN = new RegExp(`^[a-z0-9][a-z0-9_-]{0,${exports.PANEL_EMIT_TOKEN_MAX_LENGTH - 1}}$`);
+const SHOW_IF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ASSET_ID_PATTERN = /^as_[a-f0-9]{32}$/;
+const ARCHE_ID_PATTERN = /^arc_[a-f0-9]{32}$/;
+const IMAGE_KEY_PATTERN = new RegExp(`^(?:${exports.PANEL_IMAGE_ROOTS.join('|')})/[A-Za-z0-9._/-]+\\.(?:png|jpe?g|webp|gif|svg)$`, 'i');
+const THEME_COLOR_PATTERN = /^(?:#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})|rgba?\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(?:,\s*(?:0|1|0?\.\d{1,3})\s*)?\))$/i;
+const THEME_LENGTH_PATTERN = new RegExp(`^\\d{1,${exports.PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS}}(?:\\.\\d{1,3})?(?:px|rem|em)$`);
+const THEME_FONT_PATTERN = /^[A-Za-z0-9 '",._-]+$/;
+const TEXT_STYLES = ['title', 'body', 'caption'];
+const TEXT_ALIGNS = ['left', 'center', 'right'];
+const SIZES = ['small', 'medium', 'large'];
+const BUTTON_VARIANTS = ['primary', 'secondary'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `.strict()`, mirrored: an unrecognized field is a typo that would silently do nothing. */
+function rejectUnknownKeys(value, allowed, path, issues) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            issues.push(`${path}: unknown field "${key}"`);
+    }
+}
+function checkString(value, path, issues, opts) {
+    if (typeof value !== 'string') {
+        issues.push(`${path}: expected a string`);
+        return;
+    }
+    if (value.length < (opts.min ?? 1))
+        issues.push(`${path}: must not be empty`);
+    if (value.length > opts.max)
+        issues.push(`${path}: longer than ${opts.max} characters`);
+    if (opts.pattern && !opts.pattern.test(value)) {
+        issues.push(`${path}: ${opts.hint ?? 'does not match the required format'}`);
+    }
+}
+function checkOptionalEnum(value, path, issues, allowed) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        issues.push(`${path}: must be one of ${allowed.join(' | ')}`);
+    }
+}
+function checkOptionalBoolean(value, path, issues) {
+    if (value !== undefined && typeof value !== 'boolean')
+        issues.push(`${path}: expected a boolean`);
+}
+function checkOptionalIntRange(value, path, issues, min, max) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) {
+        issues.push(`${path}: must be an integer between ${min} and ${max}`);
+    }
+}
+/**
+ * The closed action namespace. `open_url` is checked by PARSING the URL, not by a
+ * regex, so `javascript:`, `data:`, protocol-relative and whitespace-obfuscated
+ * forms are rejected the same way the platform rejects them.
+ */
+function validatePanelAction(action, path, issues) {
+    if (typeof action !== 'string' || action.length === 0) {
+        issues.push(`${path}: expected an action string`);
+        return;
+    }
+    if (action.length > exports.PANEL_ACTION_MAX_LENGTH) {
+        issues.push(`${path}: longer than ${exports.PANEL_ACTION_MAX_LENGTH} characters`);
+        return;
+    }
+    if (action === 'close')
+        return;
+    if (action.startsWith('emit:')) {
+        if (!EMIT_TOKEN_PATTERN.test(action.slice('emit:'.length))) {
+            issues.push(`${path}: emit token must be 1–${exports.PANEL_EMIT_TOKEN_MAX_LENGTH} chars — lowercase letters, digits, hyphens and underscores, not starting with a separator`);
+        }
+        return;
+    }
+    if (action.startsWith('open_arche:')) {
+        if (!ARCHE_ID_PATTERN.test(action.slice('open_arche:'.length))) {
+            issues.push(`${path}: open_arche target must be an arche id (arc_ + 32 hex chars)`);
+        }
+        return;
+    }
+    if (action.startsWith('open_url:')) {
+        if (/\s/.test(action)) {
+            issues.push(`${path}: action must not contain whitespace`);
+            return;
+        }
+        let parsed;
+        try {
+            parsed = new URL(action.slice('open_url:'.length));
+        }
+        catch {
+            issues.push(`${path}: open_url must be a valid absolute URL`);
+            return;
+        }
+        if (parsed.protocol !== 'https:')
+            issues.push(`${path}: open_url scheme must be https`);
+        return;
+    }
+    issues.push(`${path}: must be one of close | emit:<token> | open_arche:arc_<32 hex> | open_url:https://…`);
+}
+function validateTextFields(element, path, issues) {
+    checkString(element.text, `${path}.text`, issues, { max: exports.PANEL_TEXT_MAX_LENGTH });
+    checkOptionalEnum(element.style, `${path}.style`, issues, TEXT_STYLES);
+    checkOptionalEnum(element.align, `${path}.align`, issues, TEXT_ALIGNS);
+    checkOptionalBoolean(element.joinNext, `${path}.joinNext`, issues);
+}
+function validateItemsFields(element, path, issues) {
+    checkOptionalBoolean(element.showIcons, `${path}.showIcons`, issues);
+    checkOptionalEnum(element.iconSize, `${path}.iconSize`, issues, SIZES);
+    if (element.emptyText !== undefined) {
+        checkString(element.emptyText, `${path}.emptyText`, issues, {
+            min: 0,
+            max: exports.PANEL_ITEMS_EMPTY_TEXT_MAX_LENGTH,
+        });
+    }
+}
+function validateImageFields(element, path, issues) {
+    if (element.alt !== undefined) {
+        checkString(element.alt, `${path}.alt`, issues, { min: 0, max: exports.PANEL_IMAGE_ALT_MAX_LENGTH });
+    }
+    checkOptionalIntRange(element.maxHeight, `${path}.maxHeight`, issues, exports.PANEL_IMAGE_MIN_HEIGHT, exports.PANEL_IMAGE_MAX_HEIGHT);
+}
+function validateElement(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push(`${path}: expected an object`);
+        return;
+    }
+    const kind = value.kind;
+    if (typeof kind !== 'string' || !exports.PANEL_ELEMENT_KINDS.includes(kind)) {
+        issues.push(`${path}.kind: unknown element kind ${JSON.stringify(kind)} — expected one of ${exports.PANEL_ELEMENT_KINDS.join(' | ')}`);
+        return;
+    }
+    switch (kind) {
+        case 'text':
+            rejectUnknownKeys(value, ['kind', 'text', 'style', 'align', 'joinNext'], path, issues);
+            validateTextFields(value, path, issues);
+            return;
+        case 'conditionalText':
+            rejectUnknownKeys(value, ['kind', 'text', 'style', 'align', 'joinNext', 'showIf'], path, issues);
+            validateTextFields(value, path, issues);
+            checkString(value.showIf, `${path}.showIf`, issues, {
+                max: exports.PANEL_SHOW_IF_MAX_LENGTH,
+                pattern: SHOW_IF_PATTERN,
+                hint: 'must be a value NAME (letters, digits, underscore; not starting with a digit) — expressions and operators are not supported',
+            });
+            return;
+        case 'image':
+            rejectUnknownKeys(value, ['kind', 'imageKey', 'alt', 'maxHeight'], path, issues);
+            checkString(value.imageKey, `${path}.imageKey`, issues, {
+                max: exports.PANEL_IMAGE_KEY_MAX_LENGTH,
+                pattern: IMAGE_KEY_PATTERN,
+                hint: `must be a relative key under ${exports.PANEL_IMAGE_ROOTS.join(' or ')}/ ending in an image extension (no URL, no leading slash)`,
+            });
+            if (typeof value.imageKey === 'string' && value.imageKey.includes('..')) {
+                issues.push(`${path}.imageKey: must not contain ".."`);
+            }
+            validateImageFields(value, path, issues);
+            return;
+        case 'assetImage':
+            rejectUnknownKeys(value, ['kind', 'assetId', 'alt', 'maxHeight'], path, issues);
+            checkString(value.assetId, `${path}.assetId`, issues, {
+                max: 64,
+                pattern: ASSET_ID_PATTERN,
+                hint: 'must be an arche asset id (as_ + 32 hex chars)',
+            });
+            validateImageFields(value, path, issues);
+            return;
+        case 'items':
+            rejectUnknownKeys(value, ['kind', 'showIcons', 'iconSize', 'emptyText'], path, issues);
+            validateItemsFields(value, path, issues);
+            return;
+        case 'slottedItems':
+            rejectUnknownKeys(value, ['kind', 'slot', 'showIcons', 'iconSize', 'emptyText'], path, issues);
+            checkString(value.slot, `${path}.slot`, issues, {
+                max: exports.PANEL_ITEMS_SLOT_MAX_LENGTH,
+                pattern: SLOT_PATTERN,
+                hint: 'must be lowercase letters, digits, hyphens and underscores, not starting with a separator',
+            });
+            validateItemsFields(value, path, issues);
+            return;
+        case 'button':
+            rejectUnknownKeys(value, ['kind', 'label', 'action', 'variant'], path, issues);
+            checkString(value.label, `${path}.label`, issues, { max: exports.PANEL_BUTTON_LABEL_MAX_LENGTH });
+            validatePanelAction(value.action, `${path}.action`, issues);
+            checkOptionalEnum(value.variant, `${path}.variant`, issues, BUTTON_VARIANTS);
+            return;
+        case 'spacer':
+            rejectUnknownKeys(value, ['kind', 'size'], path, issues);
+            checkOptionalEnum(value.size, `${path}.size`, issues, SIZES);
+            return;
+    }
+}
+const THEME_COLOR_FIELDS = ['bg', 'fg', 'border', 'accent', 'accentFg', 'scrim'];
+const THEME_LENGTH_FIELDS = [
+    'radius',
+    'buttonRadius',
+    'gap',
+    'fontSize',
+    'widthSmall',
+    'widthMedium',
+    'widthLarge',
+];
+/**
+ * Validate an authored theme.
+ *
+ * The grammars are tight on purpose, and the reason is not style policing: a theme
+ * value becomes a CSS custom property, and a custom property can otherwise carry
+ * `url(…)` — an outbound request from every surface that draws one of your panels
+ * — or a `;` that escapes its declaration. Colours are hex or `rgb()/rgba()`,
+ * lengths are `px`/`rem`/`em`, and a font stack admits no parentheses at all.
+ */
+function validatePanelTheme(value, path = 'theme') {
+    const issues = [];
+    if (!isRecord(value))
+        return { ok: false, issues: [`${path}: expected an object`] };
+    rejectUnknownKeys(value, [...THEME_COLOR_FIELDS, ...THEME_LENGTH_FIELDS, 'font', 'z', 'amountFormat'], path, issues);
+    for (const field of THEME_COLOR_FIELDS) {
+        if (value[field] === undefined)
+            continue;
+        checkString(value[field], `${path}.${field}`, issues, {
+            max: 64,
+            pattern: THEME_COLOR_PATTERN,
+            hint: 'must be a hex colour (#rgb, #rgba, #rrggbb, #rrggbbaa) or rgb()/rgba() with numeric components',
+        });
+    }
+    for (const field of THEME_LENGTH_FIELDS) {
+        if (value[field] === undefined)
+            continue;
+        checkString(value[field], `${path}.${field}`, issues, {
+            max: 16,
+            pattern: THEME_LENGTH_PATTERN,
+            hint: `must be a non-negative number (max ${exports.PANEL_THEME_LENGTH_MAX_INTEGER_DIGITS} digits before the point) followed by px, rem or em`,
+        });
+    }
+    if (value.font !== undefined) {
+        checkString(value.font, `${path}.font`, issues, {
+            max: exports.PANEL_THEME_FONT_MAX_LENGTH,
+            pattern: THEME_FONT_PATTERN,
+            hint: 'must be a font-family stack (names, commas, quotes) — no parentheses, so no url() or var()',
+        });
+    }
+    checkOptionalIntRange(value.z, `${path}.z`, issues, 0, exports.PANEL_THEME_Z_MAX);
+    if (value.amountFormat !== undefined) {
+        checkString(value.amountFormat, `${path}.amountFormat`, issues, {
+            max: exports.PANEL_THEME_AMOUNT_FORMAT_MAX_LENGTH,
+        });
+        if (typeof value.amountFormat === 'string' && !value.amountFormat.includes('{n}')) {
+            issues.push(`${path}.amountFormat: must contain the placeholder {n}`);
+        }
+    }
+    return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
+}
+/** Validate one panel definition. */
+function validatePanelDefinition(value, path = 'panel') {
+    const issues = [];
+    if (!isRecord(value))
+        return { ok: false, issues: [`${path}: expected an object`] };
+    rejectUnknownKeys(value, ['id', 'title', 'elements', 'presentation'], path, issues);
+    checkString(value.id, `${path}.id`, issues, {
+        max: 64,
+        pattern: PANEL_ID_PATTERN,
+        hint: 'must be 2–64 chars: lowercase letters, digits and hyphens, not starting with a hyphen',
+    });
+    checkString(value.title, `${path}.title`, issues, { max: exports.PANEL_TITLE_MAX_LENGTH });
+    if (!Array.isArray(value.elements)) {
+        issues.push(`${path}.elements: expected an array`);
+    }
+    else {
+        if (value.elements.length < exports.PANEL_MIN_ELEMENTS) {
+            issues.push(`${path}.elements: needs at least ${exports.PANEL_MIN_ELEMENTS} element`);
+        }
+        if (value.elements.length > exports.PANEL_MAX_ELEMENTS) {
+            issues.push(`${path}.elements: more than ${exports.PANEL_MAX_ELEMENTS} elements`);
+        }
+        value.elements.forEach((element, index) => validateElement(element, `${path}.elements[${index}]`, issues));
+    }
+    if (value.presentation !== undefined) {
+        if (!isRecord(value.presentation)) {
+            issues.push(`${path}.presentation: expected an object`);
+        }
+        else {
+            rejectUnknownKeys(value.presentation, ['size', 'dismissible', 'priority'], `${path}.presentation`, issues);
+            checkOptionalEnum(value.presentation.size, `${path}.presentation.size`, issues, SIZES);
+            checkOptionalBoolean(value.presentation.dismissible, `${path}.presentation.dismissible`, issues);
+            checkOptionalIntRange(value.presentation.priority, `${path}.presentation.priority`, issues, -exports.PANEL_PRIORITY_ABS_MAX, exports.PANEL_PRIORITY_ABS_MAX);
+        }
+    }
+    return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
+}
+/**
+ * Validate a whole catalog — `{ panels, theme? }` — before you STORE it.
+ *
+ * Call this on the write side (a DataStore document, a config blob, an admin form
+ * submit), not on the read side. A renderer skipping an element it cannot draw is
+ * a designed degrade; a panel that was never valid is an authoring bug, and the
+ * difference between the two is which side of the write you find out on.
+ *
+ * ```ts
+ * const result = validatePanelCatalog(draft);
+ * if (!result.ok) return setErrors(result.issues);
+ * await datastore.put('panels', draft);
+ * ```
+ *
+ * Panel ids must be unique within a catalog: they are used for dedupe, telemetry
+ * and render keys, so a duplicate is an authoring error rather than a
+ * last-one-wins.
+ */
+function validatePanelCatalog(value) {
+    const issues = [];
+    if (!isRecord(value))
+        return { ok: false, issues: ['catalog: expected an object'] };
+    rejectUnknownKeys(value, ['panels', 'theme'], 'catalog', issues);
+    if (value.theme !== undefined) {
+        const theme = validatePanelTheme(value.theme, 'catalog.theme');
+        if (!theme.ok)
+            issues.push(...theme.issues);
+    }
+    if (!Array.isArray(value.panels)) {
+        issues.push('catalog.panels: expected an array');
+        return { ok: false, issues };
+    }
+    const seen = new Set();
+    value.panels.forEach((panel, index) => {
+        const path = `catalog.panels[${index}]`;
+        const result = validatePanelDefinition(panel, path);
+        if (!result.ok)
+            issues.push(...result.issues);
+        if (isRecord(panel) && typeof panel.id === 'string') {
+            if (seen.has(panel.id))
+                issues.push(`${path}.id: duplicate panel id "${panel.id}"`);
+            seen.add(panel.id);
+        }
+    });
+    return issues.length === 0 ? { ok: true, issues: [] } : { ok: false, issues };
+}
+//# sourceMappingURL=panels.js.map