@texuli/deck 0.0.0-stage → 0.4.0

package/dist/model/backgrounds/schema.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Deck backgrounds (model v2 §3.5), ported from Protoyard: 13 presets and a
+ * spec union (`solid`, `gradient`, `pattern`, `image`/`image-full`,
+ * `video`/`video-full`). Colors come only from the caller's palette, from a
+ * validated `#rrggbb`, or from numbers computed in `resolve.ts`, so no author
+ * string ever reaches CSS. iframe backgrounds are not part of the model.
+ *
+ * Media sources are checked for syntax here (`MEDIA_SRC_PATTERN`, plus the
+ * image/video kind rule below); the stage applies the URL policy at the
+ * host's trust tier when it paints.
+ */
+import { type Infer } from '../../schema/index.js';
+/** The background diagnostic codes this module raises. */
+export declare const BACKGROUND_CODES: Readonly<{
+    readonly unknownBackground: "unknown-background";
+    readonly solidConflict: "solid-conflict";
+    readonly mediaKind: "media-kind";
+    readonly invalidPaletteColor: "invalid-palette-color";
+}>;
+/**
+ * The palette a background reads: semantic role → color. Role names mirror
+ * `SEMANTIC_ROLES` in `@texuli/tokens` (the stage passes the active theme's
+ * resolved roles, converted to hex). `inverse` is not a Texuli role; it
+ * defaults to `foreground`. Values are `#rgb`/`#rrggbb` or `rgb()`/`rgba()`
+ * (composited over `background`); an unreadable value is replaced and
+ * reported (`invalid-palette-color`), never guessed at.
+ */
+export declare const DECK_PALETTE_ROLES: readonly ["background", "foreground", "surface", "primary", "accent", "muted", "border", "info", "success", "warning", "destructive"];
+export type DeckPaletteRole = (typeof DECK_PALETTE_ROLES)[number];
+export type DeckBackgroundPalette = {
+    readonly [R in DeckPaletteRole]: string;
+} & {
+    /** Defaults to `foreground`. */
+    readonly inverse?: string;
+};
+/** Palette roles a `solid` background may name (`background` is the theme page color). */
+export declare const DECK_SOLID_TOKENS: readonly ["background", "surface", "primary", "accent", "muted", "inverse"];
+export type DeckSolidToken = (typeof DECK_SOLID_TOKENS)[number];
+/** Gradient stops, as palette roles (Protoyard's five). */
+export declare const DECK_GRADIENTS: Readonly<{
+    readonly brand: readonly ["primary", "info"];
+    readonly dusk: readonly ["foreground", "primary"];
+    readonly dawn: readonly ["warning", "destructive"];
+    readonly forest: readonly ["success", "info"];
+    readonly mist: readonly ["muted", "accent", "surface"];
+}>;
+export type DeckGradient = keyof typeof DECK_GRADIENTS;
+export declare const DECK_GRADIENT_IDS: readonly ["brand", "dusk", "dawn", "forest", "mist"];
+export declare const DECK_PATTERNS: readonly ["dots", "grid"];
+export type DeckPattern = (typeof DECK_PATTERNS)[number];
+export declare const DECK_MEDIA_TONES: readonly ["dark", "light"];
+export declare const DECK_MEDIA_FITS: readonly ["cover", "contain"];
+export declare const DECK_MEDIA_POSITIONS: readonly ["center", "top", "bottom", "left", "right"];
+/** The default gradient angle, in degrees. */
+export declare const DECK_GRADIENT_ANGLE = 135;
+/** `#rrggbb` (any case) for `solid {color}`; normalized to lowercase when resolved. */
+export declare const HEX_COLOR_PATTERN = "^#[0-9a-fA-F]{6}$";
+/** A background spec (the object form), told apart by `kind`. */
+export declare const deckBackgroundSpec: import("../../index.js").UnionSchema<readonly [import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+    readonly kind: import("../../index.js").LiteralSchema<"solid">;
+    readonly token: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"accent" | "background" | "surface" | "primary" | "muted" | "inverse">, false>;
+    readonly color: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+}>>, import("../../index.js").ObjectSchema<{
+    readonly kind: import("../../index.js").LiteralSchema<"gradient">;
+    readonly gradient: import("../../index.js").EnumSchema<"brand" | "dusk" | "dawn" | "forest" | "mist">;
+    readonly angle: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+}>, import("../../index.js").ObjectSchema<{
+    readonly kind: import("../../index.js").LiteralSchema<"pattern">;
+    readonly pattern: import("../../index.js").EnumSchema<"dots" | "grid">;
+}>, import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+    readonly tone: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light">, false>;
+    readonly overlay: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+    readonly position: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"center" | "top" | "bottom" | "left" | "right">, false>;
+    readonly kind: import("../../index.js").EnumSchema<"image" | "image-full">;
+    readonly src: import("../../index.js").StringSchema;
+    readonly alt: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+    readonly fit: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"cover" | "contain">, false>;
+}>>, import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+    readonly tone: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light">, false>;
+    readonly overlay: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+    readonly position: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"center" | "top" | "bottom" | "left" | "right">, false>;
+    readonly kind: import("../../index.js").EnumSchema<"video" | "video-full">;
+    readonly src: import("../../index.js").StringSchema;
+    readonly poster: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+}>>]>;
+export type DeckBackgroundSpec = Infer<typeof deckBackgroundSpec>;
+export type DeckBackgroundKind = DeckBackgroundSpec['kind'];
+/** The 13 presets, each a spec. */
+export declare const DECK_BACKGROUND_PRESETS: Readonly<{
+    readonly 'solid-color': Readonly<{
+        kind: "solid";
+        token: "background";
+    }>;
+    readonly 'solid-surface': Readonly<{
+        kind: "solid";
+        token: "surface";
+    }>;
+    readonly 'solid-primary': Readonly<{
+        kind: "solid";
+        token: "primary";
+    }>;
+    readonly 'solid-accent': Readonly<{
+        kind: "solid";
+        token: "accent";
+    }>;
+    readonly 'solid-muted': Readonly<{
+        kind: "solid";
+        token: "muted";
+    }>;
+    readonly 'solid-inverse': Readonly<{
+        kind: "solid";
+        token: "inverse";
+    }>;
+    readonly 'gradient-brand': Readonly<{
+        kind: "gradient";
+        gradient: "brand";
+    }>;
+    readonly 'gradient-dusk': Readonly<{
+        kind: "gradient";
+        gradient: "dusk";
+    }>;
+    readonly 'gradient-dawn': Readonly<{
+        kind: "gradient";
+        gradient: "dawn";
+    }>;
+    readonly 'gradient-forest': Readonly<{
+        kind: "gradient";
+        gradient: "forest";
+    }>;
+    readonly 'gradient-mist': Readonly<{
+        kind: "gradient";
+        gradient: "mist";
+    }>;
+    readonly 'pattern-dots': Readonly<{
+        kind: "pattern";
+        pattern: "dots";
+    }>;
+    readonly 'pattern-grid': Readonly<{
+        kind: "pattern";
+        pattern: "grid";
+    }>;
+}>;
+export type DeckBackgroundPresetId = keyof typeof DECK_BACKGROUND_PRESETS;
+export declare const DECK_BACKGROUND_PRESET_IDS: readonly ["solid-color", "solid-surface", "solid-primary", "solid-accent", "solid-muted", "solid-inverse", "gradient-brand", "gradient-dusk", "gradient-dawn", "gradient-forest", "gradient-mist", "pattern-dots", "pattern-grid"];
+export declare const DEFAULT_DECK_BACKGROUND: DeckBackgroundPresetId;
+/** A preset id; an unknown id is the error `unknown-background` (v2; Protoyard only warned). */
+export declare const deckBackgroundPreset: import("../../index.js").EnumSchema<"solid-color" | "solid-surface" | "solid-primary" | "solid-accent" | "solid-muted" | "solid-inverse" | "gradient-brand" | "gradient-dusk" | "gradient-dawn" | "gradient-forest" | "gradient-mist" | "pattern-dots" | "pattern-grid">;
+/** `style.background` and `slides[].background`: a preset id or a spec. */
+export declare const deckBackground: import("../../index.js").UnionSchema<readonly [import("../../index.js").EnumSchema<"solid-color" | "solid-surface" | "solid-primary" | "solid-accent" | "solid-muted" | "solid-inverse" | "gradient-brand" | "gradient-dusk" | "gradient-dawn" | "gradient-forest" | "gradient-mist" | "pattern-dots" | "pattern-grid">, import("../../index.js").UnionSchema<readonly [import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+    readonly kind: import("../../index.js").LiteralSchema<"solid">;
+    readonly token: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"accent" | "background" | "surface" | "primary" | "muted" | "inverse">, false>;
+    readonly color: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+}>>, import("../../index.js").ObjectSchema<{
+    readonly kind: import("../../index.js").LiteralSchema<"gradient">;
+    readonly gradient: import("../../index.js").EnumSchema<"brand" | "dusk" | "dawn" | "forest" | "mist">;
+    readonly angle: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+}>, import("../../index.js").ObjectSchema<{
+    readonly kind: import("../../index.js").LiteralSchema<"pattern">;
+    readonly pattern: import("../../index.js").EnumSchema<"dots" | "grid">;
+}>, import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+    readonly tone: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light">, false>;
+    readonly overlay: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+    readonly position: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"center" | "top" | "bottom" | "left" | "right">, false>;
+    readonly kind: import("../../index.js").EnumSchema<"image" | "image-full">;
+    readonly src: import("../../index.js").StringSchema;
+    readonly alt: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+    readonly fit: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"cover" | "contain">, false>;
+}>>, import("../../index.js").RefineSchema<import("../../index.js").ObjectSchema<{
+    readonly tone: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"dark" | "light">, false>;
+    readonly overlay: import("../../index.js").OptionalSchema<import("../../index.js").NumberSchema, false>;
+    readonly position: import("../../index.js").OptionalSchema<import("../../index.js").EnumSchema<"center" | "top" | "bottom" | "left" | "right">, false>;
+    readonly kind: import("../../index.js").EnumSchema<"video" | "video-full">;
+    readonly src: import("../../index.js").StringSchema;
+    readonly poster: import("../../index.js").OptionalSchema<import("../../index.js").StringSchema, false>;
+}>>]>]>;
+export type DeckBackground = Infer<typeof deckBackground>;
+/** True for one of the 13 preset ids (own keys only; `__proto__` and friends are not presets). */
+export declare function isDeckBackgroundPreset(value: unknown): value is DeckBackgroundPresetId;

package/dist/model/backgrounds/schema.js

@@ -0,0 +1,203 @@
+/**
+ * Deck backgrounds (model v2 §3.5), ported from Protoyard: 13 presets and a
+ * spec union (`solid`, `gradient`, `pattern`, `image`/`image-full`,
+ * `video`/`video-full`). Colors come only from the caller's palette, from a
+ * validated `#rrggbb`, or from numbers computed in `resolve.ts`, so no author
+ * string ever reaches CSS. iframe backgrounds are not part of the model.
+ *
+ * Media sources are checked for syntax here (`MEDIA_SRC_PATTERN`, plus the
+ * image/video kind rule below); the stage applies the URL policy at the
+ * host's trust tier when it paints.
+ */
+import { t } from "../../schema/index.js";
+import { line, MEDIA_SRC_PATTERN, mediaSrc } from "../shared.js";
+/** The background diagnostic codes this module raises. */
+export const BACKGROUND_CODES = Object.freeze({
+    unknownBackground: 'unknown-background',
+    solidConflict: 'solid-conflict',
+    mediaKind: 'media-kind',
+    invalidPaletteColor: 'invalid-palette-color',
+});
+/**
+ * The palette a background reads: semantic role → color. Role names mirror
+ * `SEMANTIC_ROLES` in `@texuli/tokens` (the stage passes the active theme's
+ * resolved roles, converted to hex). `inverse` is not a Texuli role; it
+ * defaults to `foreground`. Values are `#rgb`/`#rrggbb` or `rgb()`/`rgba()`
+ * (composited over `background`); an unreadable value is replaced and
+ * reported (`invalid-palette-color`), never guessed at.
+ */
+export const DECK_PALETTE_ROLES = [
+    'background',
+    'foreground',
+    'surface',
+    'primary',
+    'accent',
+    'muted',
+    'border',
+    'info',
+    'success',
+    'warning',
+    'destructive',
+];
+/** Palette roles a `solid` background may name (`background` is the theme page color). */
+export const DECK_SOLID_TOKENS = [
+    'background',
+    'surface',
+    'primary',
+    'accent',
+    'muted',
+    'inverse',
+];
+/** Gradient stops, as palette roles (Protoyard's five). */
+export const DECK_GRADIENTS = Object.freeze({
+    brand: ['primary', 'info'],
+    dusk: ['foreground', 'primary'],
+    dawn: ['warning', 'destructive'],
+    forest: ['success', 'info'],
+    mist: ['muted', 'accent', 'surface'],
+});
+export const DECK_GRADIENT_IDS = ['brand', 'dusk', 'dawn', 'forest', 'mist'];
+export const DECK_PATTERNS = ['dots', 'grid'];
+export const DECK_MEDIA_TONES = ['dark', 'light'];
+export const DECK_MEDIA_FITS = ['cover', 'contain'];
+export const DECK_MEDIA_POSITIONS = ['center', 'top', 'bottom', 'left', 'right'];
+/** The default gradient angle, in degrees. */
+export const DECK_GRADIENT_ANGLE = 135;
+/** `#rrggbb` (any case) for `solid {color}`; normalized to lowercase when resolved. */
+export const HEX_COLOR_PATTERN = '^#[0-9a-fA-F]{6}$';
+/** True when a media source is the right kind (`data:` type, avatars are images). */
+function mediaFits(src, kind) {
+    if (src.startsWith('avatar:'))
+        return kind === 'image';
+    if (src.startsWith('data:'))
+        return src.startsWith(`data:${kind}/`);
+    return true;
+}
+const solidSpec = t.refine(t.object({
+    kind: t.literal('solid'),
+    token: t.optional(t.enum(DECK_SOLID_TOKENS)),
+    color: t.optional(t.string({ pattern: HEX_COLOR_PATTERN, max: 7 })),
+}), {
+    code: BACKGROUND_CODES.solidConflict,
+    description: '`token` and `color` are mutually exclusive; neither means `background`.',
+    check(value, context) {
+        if (value.token !== undefined && value.color !== undefined) {
+            context.issue({
+                message: 'A solid background takes a palette `token` or a hex `color`, not both.',
+                path: ['color'],
+                fix: 'Remove `token` or `color`.',
+            });
+        }
+    },
+});
+const gradientSpec = t.object({
+    kind: t.literal('gradient'),
+    gradient: t.enum(DECK_GRADIENT_IDS),
+    angle: t.optional(t.int({ min: 0, max: 359 })),
+});
+const patternSpec = t.object({
+    kind: t.literal('pattern'),
+    pattern: t.enum(DECK_PATTERNS),
+});
+const mediaShape = {
+    tone: t.optional(t.enum(DECK_MEDIA_TONES)),
+    overlay: t.optional(t.number({ min: 0, max: 0.9 })),
+    position: t.optional(t.enum(DECK_MEDIA_POSITIONS)),
+};
+/** A poster is always an image: `MEDIA_SRC_PATTERN`, at most 2,000,000 code points. */
+const posterSrc = t.string({ min: 1, max: 2_000_000, pattern: MEDIA_SRC_PATTERN });
+const imageSpec = t.refine(t.object({
+    kind: t.enum(['image', 'image-full']),
+    src: mediaSrc,
+    alt: t.optional(line(200)),
+    fit: t.optional(t.enum(DECK_MEDIA_FITS)),
+    ...mediaShape,
+}), {
+    code: BACKGROUND_CODES.mediaKind,
+    description: 'An image `src` is not a `data:video/…` URI.',
+    check(value, context) {
+        if (!mediaFits(value.src, 'image')) {
+            context.issue({
+                message: 'An image background needs an image source.',
+                path: ['src'],
+                fix: 'Use an image path, a `data:image/…` URI or an avatar, or `kind: "video"`.',
+            });
+        }
+    },
+});
+const videoSpec = t.refine(t.object({
+    kind: t.enum(['video', 'video-full']),
+    src: mediaSrc,
+    poster: t.optional(posterSrc),
+    ...mediaShape,
+}), {
+    code: BACKGROUND_CODES.mediaKind,
+    description: 'A video `src` is not an image `data:` URI or an avatar; a `poster` is an image.',
+    check(value, context) {
+        if (!mediaFits(value.src, 'video')) {
+            context.issue({
+                message: 'A video background needs a video source.',
+                path: ['src'],
+                fix: 'Use a video path or a `data:video/…` URI, or `kind: "image"`.',
+            });
+        }
+        if (value.poster !== undefined && !mediaFits(value.poster, 'image')) {
+            context.issue({
+                message: 'A video poster must be an image.',
+                path: ['poster'],
+                fix: 'Use an image path, a `data:image/…` URI or an avatar.',
+            });
+        }
+    },
+});
+/** A background spec (the object form), told apart by `kind`. */
+export const deckBackgroundSpec = t.union([solidSpec, gradientSpec, patternSpec, imageSpec, videoSpec], {
+    discriminator: 'kind',
+    code: BACKGROUND_CODES.unknownBackground,
+    description: 'A background spec: solid, gradient, pattern, image(-full) or video(-full).',
+});
+/** The 13 presets, each a spec. */
+export const DECK_BACKGROUND_PRESETS = Object.freeze({
+    'solid-color': Object.freeze({ kind: 'solid', token: 'background' }),
+    'solid-surface': Object.freeze({ kind: 'solid', token: 'surface' }),
+    'solid-primary': Object.freeze({ kind: 'solid', token: 'primary' }),
+    'solid-accent': Object.freeze({ kind: 'solid', token: 'accent' }),
+    'solid-muted': Object.freeze({ kind: 'solid', token: 'muted' }),
+    'solid-inverse': Object.freeze({ kind: 'solid', token: 'inverse' }),
+    'gradient-brand': Object.freeze({ kind: 'gradient', gradient: 'brand' }),
+    'gradient-dusk': Object.freeze({ kind: 'gradient', gradient: 'dusk' }),
+    'gradient-dawn': Object.freeze({ kind: 'gradient', gradient: 'dawn' }),
+    'gradient-forest': Object.freeze({ kind: 'gradient', gradient: 'forest' }),
+    'gradient-mist': Object.freeze({ kind: 'gradient', gradient: 'mist' }),
+    'pattern-dots': Object.freeze({ kind: 'pattern', pattern: 'dots' }),
+    'pattern-grid': Object.freeze({ kind: 'pattern', pattern: 'grid' }),
+});
+export const DECK_BACKGROUND_PRESET_IDS = [
+    'solid-color',
+    'solid-surface',
+    'solid-primary',
+    'solid-accent',
+    'solid-muted',
+    'solid-inverse',
+    'gradient-brand',
+    'gradient-dusk',
+    'gradient-dawn',
+    'gradient-forest',
+    'gradient-mist',
+    'pattern-dots',
+    'pattern-grid',
+];
+export const DEFAULT_DECK_BACKGROUND = 'solid-color';
+/** A preset id; an unknown id is the error `unknown-background` (v2; Protoyard only warned). */
+export const deckBackgroundPreset = t.enum(DECK_BACKGROUND_PRESET_IDS, {
+    code: BACKGROUND_CODES.unknownBackground,
+    description: 'A background preset id.',
+});
+/** `style.background` and `slides[].background`: a preset id or a spec. */
+export const deckBackground = t.union([deckBackgroundPreset, deckBackgroundSpec], {
+    description: 'A background preset id, or a background spec object.',
+});
+/** True for one of the 13 preset ids (own keys only; `__proto__` and friends are not presets). */
+export function isDeckBackgroundPreset(value) {
+    return typeof value === 'string' && Object.hasOwn(DECK_BACKGROUND_PRESETS, value);
+}

package/dist/model/codes.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Every diagnostic code deck model v2 reports (model-v2 §3.9), with its usual
+ * severity and a one-line meaning. JSON validation, the cross-field passes,
+ * the untrusted loader, migration and the host hooks all use these codes, so
+ * authors, agents and docs read one table. Codes are stable kebab-case.
+ */
+import type { DeckDiagnostic, DiagnosticSeverity } from '../schema/index.js';
+export interface DeckCodeInfo {
+    /** The severity the engine reports this code with. */
+    readonly severity: DiagnosticSeverity;
+    /** Where it comes from. */
+    readonly group: 'structure' | 'cross-field' | 'policy' | 'version' | 'loader' | 'host' | 'style';
+    readonly meaning: string;
+}
+/** The documented code table. `too-many` and `too-deep` are shared by the kit and the loader. */
+export declare const DECK_CODES: Readonly<{
+    readonly 'invalid-type': DeckCodeInfo;
+    readonly required: DeckCodeInfo;
+    readonly 'unknown-key': DeckCodeInfo;
+    readonly 'too-short': DeckCodeInfo;
+    readonly 'too-long': DeckCodeInfo;
+    readonly 'too-few': DeckCodeInfo;
+    readonly 'too-many': DeckCodeInfo;
+    readonly 'out-of-range': DeckCodeInfo;
+    readonly 'not-integer': DeckCodeInfo;
+    readonly 'not-finite': DeckCodeInfo;
+    readonly pattern: DeckCodeInfo;
+    readonly reserved: DeckCodeInfo;
+    readonly enum: DeckCodeInfo;
+    readonly 'unknown-kind': DeckCodeInfo;
+    readonly 'unsafe-text': DeckCodeInfo;
+    readonly 'unsafe-key': DeckCodeInfo;
+    readonly 'too-deep': DeckCodeInfo;
+    readonly cycle: DeckCodeInfo;
+    readonly 'too-large': DeckCodeInfo;
+    readonly 'invalid-input': DeckCodeInfo;
+    readonly 'unknown-layout': DeckCodeInfo;
+    readonly 'layout-props': DeckCodeInfo;
+    readonly 'invalid-block': DeckCodeInfo;
+    readonly 'unknown-background': DeckCodeInfo;
+    readonly 'solid-conflict': DeckCodeInfo;
+    readonly 'media-kind': DeckCodeInfo;
+    readonly 'invalid-palette-color': DeckCodeInfo;
+    readonly 'unknown-theme-kind': DeckCodeInfo;
+    readonly 'embedded-theme': DeckCodeInfo;
+    readonly 'unknown-theme': DeckCodeInfo;
+    readonly 'unknown-font-pair': DeckCodeInfo;
+    readonly 'unknown-code-theme': DeckCodeInfo;
+    readonly 'duplicate-id': DeckCodeInfo;
+    readonly 'duplicate-block-id': DeckCodeInfo;
+    readonly 'unknown-slide': DeckCodeInfo;
+    readonly 'section-overlap': DeckCodeInfo;
+    readonly 'stack-not-contiguous': DeckCodeInfo;
+    readonly 'start-hidden': DeckCodeInfo;
+    readonly 'all-hidden': DeckCodeInfo;
+    readonly 'fragment-conflict': DeckCodeInfo;
+    readonly 'too-many-steps': DeckCodeInfo;
+    readonly 'step-unrevealed': DeckCodeInfo;
+    readonly 'step-missing': DeckCodeInfo;
+    readonly 'unknown-component': DeckCodeInfo;
+    readonly 'component-props': DeckCodeInfo;
+    readonly 'block-props': DeckCodeInfo;
+    readonly 'unsupported-version': DeckCodeInfo;
+    readonly migrated: DeckCodeInfo;
+    readonly 'invalid-json': DeckCodeInfo;
+    readonly 'hidden-characters': DeckCodeInfo;
+    readonly 'invalid-deck': DeckCodeInfo;
+}>;
+export type DeckCode = keyof typeof DECK_CODES;
+/** The deck diagnostic, narrowed to the documented codes. */
+export type DeckIssue = DeckDiagnostic<DeckCode>;
+/** True when `value` is a documented code (own keys only). */
+export declare function isDeckCode(value: unknown): value is DeckCode;

package/dist/model/codes.js

@@ -0,0 +1,67 @@
+function code(severity, group, meaning) {
+    return Object.freeze({ severity, group, meaning });
+}
+/** The documented code table. `too-many` and `too-deep` are shared by the kit and the loader. */
+export const DECK_CODES = Object.freeze({
+    // Structure (the schema kit and the layout catalog)
+    'invalid-type': code('error', 'structure', 'The value has the wrong JSON type.'),
+    required: code('error', 'structure', 'A required key is missing.'),
+    'unknown-key': code('error', 'structure', 'The object has a key the model does not define.'),
+    'too-short': code('error', 'structure', 'The text is shorter than its minimum (code points).'),
+    'too-long': code('error', 'structure', 'The text is longer than its maximum (code points).'),
+    'too-few': code('error', 'structure', 'The list has fewer items than its minimum.'),
+    'too-many': code('error', 'structure', 'The list, record or deck has more items than its maximum.'),
+    'out-of-range': code('error', 'structure', 'The number is outside its allowed range.'),
+    'not-integer': code('error', 'structure', 'The number must be a whole number.'),
+    'not-finite': code('error', 'structure', 'NaN and Infinity are not data.'),
+    pattern: code('error', 'structure', 'The text does not match the required syntax.'),
+    reserved: code('error', 'structure', 'The value is reserved in this position.'),
+    enum: code('error', 'structure', 'The value is not one of the listed values.'),
+    'unknown-kind': code('error', 'structure', 'A union `kind` names no known variant.'),
+    'unsafe-text': code('error', 'structure', 'The text holds control, line-break or bidi-override characters.'),
+    'unsafe-key': code('error', 'structure', '`__proto__`, `constructor` and `prototype` are refused.'),
+    'too-deep': code('error', 'structure', 'The value nests deeper than allowed.'),
+    cycle: code('error', 'structure', 'The value contains itself.'),
+    'too-large': code('error', 'loader', 'The input is larger than the byte or node budget.'),
+    'invalid-input': code('error', 'loader', 'The input is not plain JSON data (accessors, class instances, functions…).'),
+    'unknown-layout': code('error', 'structure', 'The slide `layout` is not a catalog id or slide kind.'),
+    'layout-props': code('error', 'structure', 'A layout props rule failed (e.g. comparison row width).'),
+    'invalid-block': code('error', 'structure', 'A free-slide item is not a block shape (`type`, `id`, step fields).'),
+    // Style, theme and backgrounds
+    'unknown-background': code('error', 'style', 'The background preset or spec kind is unknown.'),
+    'solid-conflict': code('error', 'style', 'A solid background sets both `token` and `color`.'),
+    'media-kind': code('error', 'style', 'An image background has a video source, or the reverse.'),
+    'invalid-palette-color': code('warning', 'style', 'A palette color could not be read; replaced.'),
+    'unknown-theme-kind': code('error', 'style', 'A theme reference `kind` is not catalog, embedded or seed.'),
+    'embedded-theme': code('error', 'style', 'An embedded theme is not an object.'),
+    'unknown-theme': code('warning', 'style', 'The catalog theme id is unknown to the host; default used.'),
+    'unknown-font-pair': code('warning', 'style', 'The font pairing is unknown to the host; theme font used.'),
+    'unknown-code-theme': code('warning', 'style', 'The code theme is unknown to the host; default used.'),
+    // Cross-field (parseDeck)
+    'duplicate-id': code('error', 'cross-field', 'A slide or section id is used twice.'),
+    'duplicate-block-id': code('error', 'cross-field', 'A block id is used twice in the deck.'),
+    'unknown-slide': code('error', 'cross-field', 'A section or `navigation.start` names no slide.'),
+    'section-overlap': code('error', 'cross-field', 'A slide is listed in more than one section.'),
+    'stack-not-contiguous': code('error', 'cross-field', 'A vertical-stack section lists slides that are not adjacent in `slides`.'),
+    'start-hidden': code('error', 'cross-field', '`navigation.start` names a hidden slide.'),
+    'all-hidden': code('error', 'cross-field', 'Every slide is hidden; nothing would present.'),
+    'fragment-conflict': code('error', 'cross-field', 'A step marker sets both `fragment` and `reveal`.'),
+    'too-many-steps': code('error', 'cross-field', 'A slide has more than 32 distinct steps.'),
+    'step-unrevealed': code('warning', 'cross-field', 'A step marker sits where the layout reveals nothing.'),
+    'step-missing': code('warning', 'cross-field', 'A props marker sets `fragment` or `reveal` but no `step`; it is ignored.'),
+    // Host phase (parse options)
+    'unknown-component': code('error', 'host', 'The component id is not in the host registry.'),
+    'component-props': code('error', 'host', 'The host registry refused the component props.'),
+    'block-props': code('error', 'host', 'The host block validator refused a block.'),
+    // Version and migration
+    'unsupported-version': code('error', 'version', '`formatVersion` is not 2.'),
+    migrated: code('warning', 'version', 'The input was converted to model v2; review the note.'),
+    // Untrusted loader
+    'invalid-json': code('error', 'loader', 'The text is not valid JSON (line and column given).'),
+    'hidden-characters': code('warning', 'loader', 'Invisible or reordering characters were removed from a string.'),
+    'invalid-deck': code('error', 'loader', 'The input is not a recognized deck shape.'),
+});
+/** True when `value` is a documented code (own keys only). */
+export function isDeckCode(value) {
+    return typeof value === 'string' && Object.hasOwn(DECK_CODES, value);
+}