@velumo/core 0.1.0-beta.0

package/src/types.ts

@@ -0,0 +1,560 @@
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonValue =
+  | JsonPrimitive
+  | { readonly [key: string]: JsonValue }
+  | readonly JsonValue[];
+
+export type SlideKind = "slide" | "scene";
+
+export interface DeckMetadata {
+  readonly title: string;
+  readonly description?: string;
+  readonly author?: string;
+  readonly watermark?: string;
+  readonly [key: string]: JsonValue | undefined;
+}
+
+export interface CameraVector {
+  readonly x?: number;
+  readonly y?: number;
+  readonly z?: number;
+}
+
+export interface Camera {
+  readonly from?: CameraVector;
+  readonly to?: CameraVector;
+  readonly zoom?: number;
+  readonly [key: string]: JsonValue | CameraVector | undefined;
+}
+
+export type CameraEasing =
+  | "linear"
+  | "ease"
+  | "ease-in"
+  | "ease-out"
+  | "ease-in-out";
+
+export interface CameraView {
+  readonly x: number;
+  readonly y: number;
+  readonly zoom?: number;
+}
+
+export interface CameraTransition {
+  readonly duration?: number;
+  readonly easing?: CameraEasing;
+}
+
+export interface CameraStop {
+  readonly camera: CameraView;
+  readonly transition?: CameraTransition;
+  readonly cues?: readonly Cue[];
+  readonly hold?: number;
+}
+
+export interface Layer {
+  readonly id?: string;
+  readonly type: string;
+  readonly content?: JsonValue;
+  readonly props?: Record<string, JsonValue>;
+  readonly timing?: Record<string, JsonValue>;
+  readonly visible?: boolean;
+}
+
+export interface LayoutMeta {
+  readonly safeArea?: "default" | "full-bleed" | "title-safe";
+  readonly depth?: number;
+  readonly cameraHint?: "static" | "push" | "pan" | "orbit";
+}
+
+export interface HeadingElement {
+  readonly kind: "heading";
+  readonly text: string;
+  readonly size?: "default" | "display" | "hero";
+  readonly level?: 1 | 2 | 3 | 4 | 5 | 6;
+  readonly transform?: "uppercase" | "lowercase" | "capitalize";
+  readonly decoration?: "underline" | "line-through";
+  readonly glow?: boolean;
+  readonly tone?:
+    | "default"
+    | "muted"
+    | "accent"
+    | "danger"
+    | "magenta"
+    | "cyan"
+    | "purple"
+    | "green";
+}
+
+export interface TextElement {
+  readonly kind: "text";
+  readonly text: string;
+  readonly variant?: "body" | "lead" | "caption";
+  readonly transform?: "uppercase" | "lowercase" | "capitalize";
+  readonly decoration?: "underline" | "line-through";
+  readonly glow?: boolean;
+  readonly tone?:
+    | "default"
+    | "muted"
+    | "accent"
+    | "danger"
+    | "magenta"
+    | "cyan"
+    | "purple"
+    | "green";
+}
+
+export interface MediaElement {
+  readonly kind: "media";
+  readonly src: string;
+  readonly alt: string;
+  readonly fit?: "contain" | "cover" | "fill";
+}
+
+export interface CalloutElement {
+  readonly kind: "callout";
+  readonly tone?: "info" | "warning" | "success" | "danger" | "quote";
+  readonly children: readonly LayoutNode[];
+}
+
+export interface StackLayout {
+  readonly kind: "stack";
+  readonly children: readonly LayoutNode[];
+  readonly direction?: "vertical" | "horizontal";
+  readonly align?: "start" | "center" | "end" | "stretch";
+  readonly gap?: string;
+  readonly justify?: "start" | "center" | "between" | "end";
+  readonly meta?: LayoutMeta;
+}
+
+export interface GridLayout {
+  readonly kind: "grid";
+  readonly children: readonly LayoutNode[];
+  readonly columns?: number;
+  readonly rows?: number;
+  readonly meta?: LayoutMeta;
+}
+
+export interface SplitLayout {
+  readonly kind: "split";
+  readonly children: readonly LayoutNode[];
+  readonly weights?: readonly number[];
+  readonly meta?: LayoutMeta;
+}
+
+export interface HeroLayout {
+  readonly kind: "hero";
+  readonly children: readonly LayoutNode[];
+  readonly meta?: LayoutMeta;
+}
+
+export interface FrameLayout {
+  readonly kind: "frame";
+  readonly children: readonly LayoutNode[];
+  readonly meta?: LayoutMeta;
+  readonly tone?:
+    | "default"
+    | "muted"
+    | "accent"
+    | "danger"
+    | "magenta"
+    | "cyan"
+    | "purple"
+    | "green";
+}
+
+export interface CanvasItem {
+  readonly x: number;
+  readonly y: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly child: LayoutNode;
+}
+
+export interface CanvasLayout {
+  readonly kind: "canvas";
+  readonly items: readonly CanvasItem[];
+  readonly meta?: LayoutMeta;
+}
+
+export interface TableColumn {
+  readonly header?: LayoutNode;
+  readonly weight?: number;
+  readonly align?: "start" | "center" | "end";
+  readonly emphasis?: boolean;
+}
+
+export interface TableLayout {
+  readonly kind: "table";
+  readonly columns: readonly TableColumn[];
+  readonly rows: readonly (readonly LayoutNode[])[];
+  readonly meta?: LayoutMeta;
+}
+
+export type AnimationName =
+  | "rise"
+  | "fade"
+  | "zoom"
+  | "draw"
+  | "in-left"
+  | "in-right"
+  | "glow"
+  | "blink"
+  | "pulse"
+  | "sweep";
+
+export interface AnimateLayout {
+  readonly kind: "animate";
+  readonly name: AnimationName;
+  readonly delay?: number;
+  readonly duration?: number;
+  readonly easing?: string;
+  readonly child: LayoutNode;
+}
+
+export type CodeTokenKind =
+  | "keyword"
+  | "function"
+  | "string"
+  | "number"
+  | "property"
+  | "comment"
+  | "punctuation"
+  | "plain";
+
+export interface CodeToken {
+  readonly text: string;
+  readonly kind?: CodeTokenKind;
+}
+
+export interface CodeElement {
+  readonly kind: "code";
+  readonly lines: readonly (readonly CodeToken[])[];
+}
+
+export type IconName = "check" | "cross" | "dash" | "ring" | "dot" | "arrow";
+
+export interface IconElement {
+  readonly kind: "icon";
+  readonly name: IconName;
+  readonly tone?:
+    | "default"
+    | "muted"
+    | "accent"
+    | "danger"
+    | "magenta"
+    | "cyan"
+    | "purple"
+    | "green";
+  readonly label?: string;
+}
+
+export interface ConnectorPoint {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface ConnectorElement {
+  readonly kind: "connector";
+  readonly from: ConnectorPoint;
+  readonly to: ConnectorPoint;
+  readonly control?: ConnectorPoint;
+  readonly arrow?: "none" | "end" | "start" | "both";
+  readonly dashed?: boolean;
+  readonly tone?:
+    | "default"
+    | "muted"
+    | "accent"
+    | "danger"
+    | "magenta"
+    | "cyan"
+    | "purple"
+    | "green";
+}
+
+export interface BadgeElement {
+  readonly kind: "badge";
+  readonly text: string;
+  readonly tone?:
+    | "default"
+    | "muted"
+    | "accent"
+    | "danger"
+    | "magenta"
+    | "cyan"
+    | "purple"
+    | "green";
+  readonly variant?: "outline" | "soft" | "solid";
+  readonly dot?: BadgeElement["tone"];
+  readonly mono?: boolean;
+}
+
+export interface RuleElement {
+  readonly kind: "rule";
+  readonly length?: string | number;
+  readonly thickness?: number;
+  readonly tone?: BadgeElement["tone"];
+  readonly gradient?: readonly [BadgeElement["tone"], BadgeElement["tone"]];
+  readonly radius?: number;
+}
+
+export type ContentElement =
+  | HeadingElement
+  | TextElement
+  | MediaElement
+  | CalloutElement
+  | CodeElement
+  | IconElement
+  | ConnectorElement
+  | BadgeElement
+  | RuleElement;
+
+export type LayoutNode =
+  | StackLayout
+  | GridLayout
+  | SplitLayout
+  | HeroLayout
+  | FrameLayout
+  | CanvasLayout
+  | AnimateLayout
+  | TableLayout
+  | ContentElement;
+
+export interface Fragment {
+  readonly id: string;
+  readonly layerId?: string;
+  readonly transition?: string;
+  readonly cues?: readonly string[];
+}
+
+export interface CueAction {
+  readonly type: string;
+  readonly target?: string;
+  readonly payload?: JsonValue;
+}
+
+export interface Cue {
+  readonly time: number;
+  readonly action: CueAction;
+}
+
+export type BlendMode = "normal" | "screen" | "multiply" | "overlay";
+
+export interface GradientStop {
+  readonly color: string;
+  readonly at?: number;
+}
+
+export interface LinearGradientLayer {
+  readonly type: "linear";
+  readonly stops: readonly GradientStop[];
+  readonly angle?: number;
+  readonly blend?: BlendMode;
+  readonly opacity?: number;
+}
+
+export interface RadialGradientLayer {
+  readonly type: "radial";
+  readonly stops: readonly GradientStop[];
+  readonly shape?: "circle" | "ellipse";
+  readonly position?: { readonly x: number; readonly y: number };
+  readonly blend?: BlendMode;
+  readonly opacity?: number;
+}
+
+export type BackgroundLayer = LinearGradientLayer | RadialGradientLayer;
+
+export interface Background {
+  readonly color?: string;
+  readonly layers?: readonly BackgroundLayer[];
+}
+
+export interface Slide {
+  readonly id: string;
+  readonly kind: "slide";
+  readonly background?: Background;
+  readonly content?: JsonValue;
+  readonly layout?: LayoutNode;
+  readonly layers?: readonly Layer[];
+  readonly fragments?: readonly Fragment[];
+  readonly cues?: readonly Cue[];
+  readonly notes?: string;
+  readonly mood?: string;
+  readonly transition?: string;
+  readonly chrome?: boolean;
+}
+
+export interface Scene {
+  readonly id: string;
+  readonly kind: "scene";
+  readonly background?: Background;
+  readonly duration?: number;
+  readonly camera?: Camera;
+  readonly cameraPath?: readonly CameraStop[];
+  readonly layout?: LayoutNode;
+  readonly layers?: readonly Layer[];
+  readonly fragments?: readonly Fragment[];
+  readonly cues?: readonly Cue[];
+  readonly notes?: string;
+  readonly mood?: string;
+  readonly transition?: string;
+  readonly chrome?: boolean;
+}
+
+export type SlideEntry = Slide | Scene;
+
+export interface Asset {
+  readonly id: string;
+  readonly type: string;
+  readonly src: string;
+  readonly metadata?: Record<string, JsonValue>;
+}
+
+export interface Plugin {
+  readonly id: string;
+  readonly packageName?: string;
+  readonly options?: Record<string, JsonValue>;
+}
+
+export type TokenReference = string;
+
+export interface TypographyToken {
+  readonly fontFamily?: string;
+  readonly fontSize?: string | number;
+  readonly lineHeight?: string | number;
+  readonly fontWeight?: string | number;
+  readonly letterSpacing?: string | number;
+}
+
+export interface MotionToken {
+  readonly duration?: string | number;
+  readonly easing?: string;
+  readonly delay?: string | number;
+}
+
+export interface ThemeTokens {
+  readonly colors?: Record<string, string>;
+  readonly typography?: Record<string, TypographyToken>;
+  readonly spacing?: Record<string, string | number>;
+  readonly radii?: Record<string, string | number>;
+  readonly shadows?: Record<string, string>;
+  readonly motion?: Record<string, MotionToken>;
+  readonly surfaces?: Record<string, TokenReference>;
+  readonly text?: Record<string, TokenReference>;
+}
+
+export interface ThemeFontFace {
+  readonly family: string;
+  readonly source: string;
+  readonly format?: string;
+  readonly weight?: string | number;
+  readonly style?: string;
+  readonly display?: string;
+  readonly unicodeRange?: string;
+  readonly stretch?: string;
+}
+
+export interface Theme {
+  readonly id: string;
+  readonly tokens?: ThemeTokens;
+  readonly css?: string;
+  readonly fonts?: readonly ThemeFontFace[];
+}
+
+export interface ExportOptions {
+  readonly formats?: readonly string[];
+  readonly metadata?: Record<string, JsonValue>;
+}
+
+export interface RuntimeOptions {
+  readonly [key: string]: JsonValue | undefined;
+}
+
+export interface Deck {
+  readonly title: string;
+  readonly description?: string;
+  readonly theme?: string | Theme;
+  readonly slides: readonly SlideEntry[];
+  readonly assets?: readonly Asset[];
+  readonly plugins?: readonly Plugin[];
+  readonly runtime?: RuntimeOptions;
+  readonly export?: ExportOptions;
+}
+
+export interface Manifest {
+  readonly deck: DeckMetadata;
+  readonly slides: readonly SlideEntry[];
+  readonly assets?: readonly Asset[];
+  readonly plugins?: readonly Plugin[];
+  readonly theme?: Theme;
+  readonly export?: ExportOptions;
+}
+
+export type ValidationIssueCode =
+  | "required"
+  | "wrong_type"
+  | "unknown_field"
+  | "unknown_kind"
+  | "invalid_enum"
+  | "invalid_value"
+  | "constraint"
+  | "not_serializable"
+  | "renderer_specific";
+
+/**
+ * A single, machine-readable validation problem.
+ *
+ * `message` is the human-readable string (identical to the legacy flat
+ * `errors` entries). `code`, `expected`, `received`, and `suggestion` are the
+ * AI-first additions: a stable code an agent can branch on, the expected shape
+ * or allowed values, what was actually found, and a concrete fix hint.
+ */
+export interface ValidationIssue {
+  readonly path: string;
+  readonly code: ValidationIssueCode;
+  readonly message: string;
+  readonly expected?: string;
+  readonly received?: string;
+  readonly suggestion?: string;
+}
+
+export interface ManifestValidationResult {
+  readonly valid: boolean;
+  readonly errors: readonly string[];
+  readonly issues: readonly ValidationIssue[];
+}
+
+/**
+ * A single authorable field on a layout or content node, as advertised to an
+ * agent through {@link VelumoCapabilities}.
+ *
+ * `type` is a friendly type hint derived from the schema: a JSON type
+ * (`string`, `number`, `integer`, `boolean`, `object`, `array`), a union like
+ * `string|number`, `enum` (with allowed values in `enum`), or `node[]` for a
+ * field that holds child layout nodes.
+ */
+export interface CapabilityField {
+  readonly name: string;
+  readonly required: boolean;
+  readonly type: string;
+  readonly enum?: readonly string[];
+}
+
+export interface NodeCapability {
+  readonly kind: string;
+  readonly fields: readonly CapabilityField[];
+}
+
+/**
+ * A discoverable, machine-readable description of what an author can express:
+ * the available slide kinds, layout/content node kinds with their fields and
+ * allowed values, and the theme token families. Projected from
+ * `manifestJsonSchema`, so it can never drift from the validated contract.
+ */
+export interface VelumoCapabilities {
+  readonly schemaId: string;
+  readonly slideKinds: readonly string[];
+  readonly nodes: readonly NodeCapability[];
+  readonly themeTokenFamilies: readonly string[];
+}

package/src/validation-issue.ts

@@ -0,0 +1,43 @@
+import type { ValidationIssue, ValidationIssueCode } from "./types.js";
+
+/**
+ * Describe the runtime type of a value for the `received` field of an issue.
+ * Distinguishes the JSON-relevant cases (null, array) from `typeof`.
+ */
+export function describeType(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  return typeof value;
+}
+
+interface IssueExtras {
+  readonly expected?: string;
+  readonly received?: string;
+  readonly suggestion?: string;
+}
+
+/**
+ * Build a {@link ValidationIssue}, omitting any optional field that is
+ * undefined so issues stay clean to compare and serialize.
+ */
+export function issue(
+  path: string,
+  code: ValidationIssueCode,
+  message: string,
+  extras: IssueExtras = {},
+): ValidationIssue {
+  return {
+    path,
+    code,
+    message,
+    ...(extras.expected !== undefined ? { expected: extras.expected } : {}),
+    ...(extras.received !== undefined ? { received: extras.received } : {}),
+    ...(extras.suggestion !== undefined
+      ? { suggestion: extras.suggestion }
+      : {}),
+  };
+}