@velumo/core 0.1.0-beta.0

package/src/manifest-schema.ts

@@ -0,0 +1,823 @@
+/**
+ * JSON Schema (draft 2020-12) derived by hand from the `Manifest` TypeScript
+ * type in `types.ts`. This is the published, machine-readable form of the
+ * manifest contract — the artifact an agent or MCP server validates against.
+ *
+ * It is intentionally a richer, stricter mirror of the type than the
+ * lightweight runtime `validateManifest()`: it requires the `kind`
+ * discriminator on every slide and layout node, enforces every enum, and
+ * forbids unknown fields. The two are kept in sync by a drift test that runs a
+ * canonical manifest through both and asserts they agree.
+ *
+ * No schema library lives in `@velumo/core`: this is a plain, serializable
+ * object. JSON Schema execution (ajv) is confined to the test suite.
+ */
+
+const jsonValue = {
+  $comment: "Any JSON value (string, number, boolean, null, object, array).",
+};
+
+const cameraVector = {
+  type: "object",
+  properties: {
+    x: { type: "number" },
+    y: { type: "number" },
+    z: { type: "number" },
+  },
+  additionalProperties: false,
+};
+
+const layoutMeta = {
+  type: "object",
+  properties: {
+    safeArea: { enum: ["default", "full-bleed", "title-safe"] },
+    depth: { type: "number" },
+    cameraHint: { enum: ["static", "push", "pan", "orbit"] },
+  },
+  additionalProperties: false,
+};
+
+const stringOrNumber = { type: ["string", "number"] };
+
+const layoutChildren = {
+  type: "array",
+  items: { $ref: "#/$defs/layoutNode" },
+};
+
+export const manifestJsonSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://velumo.dev/schemas/manifest.json",
+  title: "Velumo Manifest",
+  type: "object",
+  required: ["deck", "slides"],
+  additionalProperties: false,
+  properties: {
+    deck: { $ref: "#/$defs/deckMetadata" },
+    slides: { type: "array", items: { $ref: "#/$defs/slideEntry" } },
+    assets: { type: "array", items: { $ref: "#/$defs/asset" } },
+    plugins: { type: "array", items: { $ref: "#/$defs/plugin" } },
+    theme: { $ref: "#/$defs/theme" },
+    export: { $ref: "#/$defs/exportOptions" },
+  },
+  $defs: {
+    deckMetadata: {
+      type: "object",
+      required: ["title"],
+      properties: {
+        title: { type: "string", minLength: 1 },
+        description: { type: "string" },
+        author: { type: "string" },
+        watermark: { type: "string" },
+      },
+      additionalProperties: jsonValue,
+    },
+
+    slideEntry: {
+      oneOf: [{ $ref: "#/$defs/slide" }, { $ref: "#/$defs/scene" }],
+    },
+
+    slide: {
+      type: "object",
+      required: ["id", "kind"],
+      additionalProperties: false,
+      properties: {
+        id: { type: "string", minLength: 1 },
+        kind: { const: "slide" },
+        content: jsonValue,
+        layout: { $ref: "#/$defs/layoutNode" },
+        layers: { type: "array", items: { $ref: "#/$defs/layer" } },
+        fragments: { type: "array", items: { $ref: "#/$defs/fragment" } },
+        cues: { type: "array", items: { $ref: "#/$defs/cue" } },
+        notes: { type: "string" },
+        mood: { type: "string" },
+        transition: { type: "string" },
+        chrome: { type: "boolean" },
+        background: { $ref: "#/$defs/background" },
+      },
+    },
+
+    scene: {
+      type: "object",
+      required: ["id", "kind"],
+      additionalProperties: false,
+      properties: {
+        id: { type: "string", minLength: 1 },
+        kind: { const: "scene" },
+        duration: { type: "number" },
+        camera: { $ref: "#/$defs/camera" },
+        cameraPath: {
+          type: "array",
+          minItems: 1,
+          items: { $ref: "#/$defs/cameraStop" },
+        },
+        layout: { $ref: "#/$defs/layoutNode" },
+        layers: { type: "array", items: { $ref: "#/$defs/layer" } },
+        fragments: { type: "array", items: { $ref: "#/$defs/fragment" } },
+        cues: { type: "array", items: { $ref: "#/$defs/cue" } },
+        notes: { type: "string" },
+        mood: { type: "string" },
+        transition: { type: "string" },
+        chrome: { type: "boolean" },
+        background: { $ref: "#/$defs/background" },
+      },
+    },
+
+    camera: {
+      type: "object",
+      properties: {
+        from: cameraVector,
+        to: cameraVector,
+        zoom: { type: "number" },
+      },
+      additionalProperties: true,
+    },
+
+    cameraView: {
+      type: "object",
+      required: ["x", "y"],
+      additionalProperties: false,
+      properties: {
+        x: { type: "number", minimum: 0, maximum: 100 },
+        y: { type: "number", minimum: 0, maximum: 100 },
+        zoom: { type: "number", exclusiveMinimum: 0 },
+      },
+    },
+    cameraTransition: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        duration: { type: "number", minimum: 0 },
+        easing: {
+          enum: ["linear", "ease", "ease-in", "ease-out", "ease-in-out"],
+        },
+      },
+    },
+    cameraStop: {
+      type: "object",
+      required: ["camera"],
+      additionalProperties: false,
+      properties: {
+        camera: { $ref: "#/$defs/cameraView" },
+        transition: { $ref: "#/$defs/cameraTransition" },
+        cues: { type: "array", items: { $ref: "#/$defs/cue" } },
+        hold: { type: "number", minimum: 0 },
+      },
+    },
+
+    layer: {
+      type: "object",
+      required: ["type"],
+      additionalProperties: false,
+      properties: {
+        id: { type: "string" },
+        type: { type: "string", minLength: 1 },
+        content: jsonValue,
+        props: { type: "object", additionalProperties: jsonValue },
+        timing: { type: "object", additionalProperties: jsonValue },
+        visible: { type: "boolean" },
+      },
+    },
+
+    fragment: {
+      type: "object",
+      required: ["id"],
+      additionalProperties: false,
+      properties: {
+        id: { type: "string", minLength: 1 },
+        layerId: { type: "string" },
+        transition: { type: "string" },
+        cues: { type: "array", items: { type: "string" } },
+      },
+    },
+
+    cue: {
+      type: "object",
+      required: ["time", "action"],
+      additionalProperties: false,
+      properties: {
+        time: { type: "number", minimum: 0 },
+        action: { $ref: "#/$defs/cueAction" },
+      },
+    },
+
+    cueAction: {
+      type: "object",
+      required: ["type"],
+      additionalProperties: false,
+      properties: {
+        type: { type: "string", minLength: 1 },
+        target: { type: "string" },
+        payload: jsonValue,
+      },
+    },
+
+    layoutNode: {
+      oneOf: [
+        { $ref: "#/$defs/stackLayout" },
+        { $ref: "#/$defs/gridLayout" },
+        { $ref: "#/$defs/splitLayout" },
+        { $ref: "#/$defs/heroLayout" },
+        { $ref: "#/$defs/frameLayout" },
+        { $ref: "#/$defs/canvasLayout" },
+        { $ref: "#/$defs/animateLayout" },
+        { $ref: "#/$defs/headingElement" },
+        { $ref: "#/$defs/textElement" },
+        { $ref: "#/$defs/mediaElement" },
+        { $ref: "#/$defs/calloutElement" },
+        { $ref: "#/$defs/codeElement" },
+        { $ref: "#/$defs/iconElement" },
+        { $ref: "#/$defs/tableLayout" },
+        { $ref: "#/$defs/connectorElement" },
+        { $ref: "#/$defs/badgeElement" },
+        { $ref: "#/$defs/ruleElement" },
+      ],
+    },
+
+    stackLayout: {
+      type: "object",
+      required: ["kind", "children"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "stack" },
+        children: layoutChildren,
+        direction: { enum: ["vertical", "horizontal"] },
+        align: { enum: ["start", "center", "end", "stretch"] },
+        gap: { type: "string" },
+        justify: { enum: ["start", "center", "between", "end"] },
+        meta: layoutMeta,
+      },
+    },
+
+    gridLayout: {
+      type: "object",
+      required: ["kind", "children"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "grid" },
+        children: layoutChildren,
+        columns: { type: "integer", minimum: 1 },
+        rows: { type: "integer", minimum: 1 },
+        meta: layoutMeta,
+      },
+    },
+
+    splitLayout: {
+      type: "object",
+      required: ["kind", "children"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "split" },
+        children: {
+          type: "array",
+          minItems: 2,
+          items: { $ref: "#/$defs/layoutNode" },
+        },
+        weights: {
+          type: "array",
+          items: { type: "number", exclusiveMinimum: 0 },
+        },
+        meta: layoutMeta,
+      },
+    },
+
+    heroLayout: {
+      type: "object",
+      required: ["kind", "children"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "hero" },
+        children: {
+          type: "array",
+          minItems: 1,
+          items: { $ref: "#/$defs/layoutNode" },
+        },
+        meta: layoutMeta,
+      },
+    },
+
+    frameLayout: {
+      type: "object",
+      required: ["kind", "children"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "frame" },
+        children: layoutChildren,
+        meta: layoutMeta,
+        tone: {
+          enum: [
+            "default",
+            "muted",
+            "accent",
+            "danger",
+            "magenta",
+            "cyan",
+            "purple",
+            "green",
+          ],
+        },
+      },
+    },
+
+    canvasLayout: {
+      type: "object",
+      required: ["kind", "items"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "canvas" },
+        items: { type: "array", items: { $ref: "#/$defs/canvasItem" } },
+        meta: layoutMeta,
+      },
+    },
+
+    canvasItem: {
+      type: "object",
+      required: ["x", "y", "child"],
+      additionalProperties: false,
+      properties: {
+        x: { type: "number", minimum: 0, maximum: 100 },
+        y: { type: "number", minimum: 0, maximum: 100 },
+        width: { type: "number", minimum: 0, maximum: 100 },
+        height: { type: "number", minimum: 0, maximum: 100 },
+        child: { $ref: "#/$defs/layoutNode" },
+      },
+    },
+
+    animateLayout: {
+      type: "object",
+      required: ["kind", "name", "child"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "animate" },
+        name: {
+          enum: [
+            "rise",
+            "fade",
+            "zoom",
+            "draw",
+            "in-left",
+            "in-right",
+            "glow",
+            "blink",
+            "pulse",
+            "sweep",
+          ],
+        },
+        delay: { type: "number", minimum: 0 },
+        duration: { type: "number", exclusiveMinimum: 0 },
+        easing: { type: "string", minLength: 1 },
+        child: { $ref: "#/$defs/layoutNode" },
+      },
+    },
+
+    headingElement: {
+      type: "object",
+      required: ["kind", "text"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "heading" },
+        text: { type: "string", minLength: 1 },
+        size: { enum: ["default", "display", "hero"] },
+        level: { type: "integer", minimum: 1, maximum: 6 },
+        transform: { enum: ["uppercase", "lowercase", "capitalize"] },
+        decoration: { enum: ["underline", "line-through"] },
+        glow: { type: "boolean" },
+        tone: {
+          enum: [
+            "default",
+            "muted",
+            "accent",
+            "danger",
+            "magenta",
+            "cyan",
+            "purple",
+            "green",
+          ],
+        },
+      },
+    },
+
+    textElement: {
+      type: "object",
+      required: ["kind", "text"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "text" },
+        text: { type: "string" },
+        variant: { enum: ["body", "lead", "caption"] },
+        transform: { enum: ["uppercase", "lowercase", "capitalize"] },
+        decoration: { enum: ["underline", "line-through"] },
+        glow: { type: "boolean" },
+        tone: {
+          enum: [
+            "default",
+            "muted",
+            "accent",
+            "danger",
+            "magenta",
+            "cyan",
+            "purple",
+            "green",
+          ],
+        },
+      },
+    },
+
+    mediaElement: {
+      type: "object",
+      required: ["kind", "src", "alt"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "media" },
+        src: { type: "string", minLength: 1 },
+        alt: { type: "string", minLength: 1 },
+        fit: { enum: ["contain", "cover", "fill"] },
+      },
+    },
+
+    calloutElement: {
+      type: "object",
+      required: ["kind", "children"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "callout" },
+        tone: { enum: ["info", "warning", "success", "danger", "quote"] },
+        children: layoutChildren,
+      },
+    },
+
+    codeElement: {
+      type: "object",
+      required: ["kind", "lines"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "code" },
+        lines: {
+          type: "array",
+          items: { type: "array", items: { $ref: "#/$defs/codeToken" } },
+        },
+      },
+    },
+
+    iconElement: {
+      type: "object",
+      required: ["kind", "name"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "icon" },
+        name: { enum: ["check", "cross", "dash", "ring", "dot", "arrow"] },
+        tone: {
+          enum: [
+            "default",
+            "muted",
+            "accent",
+            "danger",
+            "magenta",
+            "cyan",
+            "purple",
+            "green",
+          ],
+        },
+        label: { type: "string" },
+      },
+    },
+
+    badgeElement: {
+      type: "object",
+      required: ["kind", "text"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "badge" },
+        text: { type: "string" },
+        tone: {
+          enum: [
+            "default",
+            "muted",
+            "accent",
+            "danger",
+            "magenta",
+            "cyan",
+            "purple",
+            "green",
+          ],
+        },
+        variant: { enum: ["outline", "soft", "solid"] },
+        dot: {
+          enum: [
+            "default",
+            "muted",
+            "accent",
+            "danger",
+            "magenta",
+            "cyan",
+            "purple",
+            "green",
+          ],
+        },
+        mono: { type: "boolean" },
+      },
+    },
+
+    ruleElement: {
+      type: "object",
+      required: ["kind"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "rule" },
+        length: { type: ["string", "number"] },
+        thickness: { type: "number" },
+        tone: {
+          enum: [
+            "default",
+            "muted",
+            "accent",
+            "danger",
+            "magenta",
+            "cyan",
+            "purple",
+            "green",
+          ],
+        },
+        gradient: {
+          type: "array",
+          minItems: 2,
+          maxItems: 2,
+          items: {
+            enum: [
+              "default",
+              "muted",
+              "accent",
+              "danger",
+              "magenta",
+              "cyan",
+              "purple",
+              "green",
+            ],
+          },
+        },
+        radius: { type: "number" },
+      },
+    },
+
+    tableColumn: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        header: { $ref: "#/$defs/layoutNode" },
+        weight: { type: "number", exclusiveMinimum: 0 },
+        align: { enum: ["start", "center", "end"] },
+        emphasis: { type: "boolean" },
+      },
+    },
+
+    tableLayout: {
+      type: "object",
+      required: ["kind", "columns", "rows"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "table" },
+        columns: {
+          type: "array",
+          minItems: 1,
+          items: { $ref: "#/$defs/tableColumn" },
+        },
+        rows: {
+          type: "array",
+          items: { type: "array", items: { $ref: "#/$defs/layoutNode" } },
+        },
+        meta: layoutMeta,
+      },
+    },
+
+    connectorPoint: {
+      type: "object",
+      required: ["x", "y"],
+      additionalProperties: false,
+      properties: {
+        x: { type: "number", minimum: 0, maximum: 100 },
+        y: { type: "number", minimum: 0, maximum: 100 },
+      },
+    },
+
+    connectorElement: {
+      type: "object",
+      required: ["kind", "from", "to"],
+      additionalProperties: false,
+      properties: {
+        kind: { const: "connector" },
+        from: { $ref: "#/$defs/connectorPoint" },
+        to: { $ref: "#/$defs/connectorPoint" },
+        control: { $ref: "#/$defs/connectorPoint" },
+        arrow: { enum: ["none", "end", "start", "both"] },
+        dashed: { type: "boolean" },
+        tone: {
+          enum: [
+            "default",
+            "muted",
+            "accent",
+            "danger",
+            "magenta",
+            "cyan",
+            "purple",
+            "green",
+          ],
+        },
+      },
+    },
+
+    codeToken: {
+      type: "object",
+      required: ["text"],
+      additionalProperties: false,
+      properties: {
+        text: { type: "string" },
+        kind: {
+          enum: [
+            "keyword",
+            "function",
+            "string",
+            "number",
+            "property",
+            "comment",
+            "punctuation",
+            "plain",
+          ],
+        },
+      },
+    },
+
+    asset: {
+      type: "object",
+      required: ["id", "type", "src"],
+      additionalProperties: false,
+      properties: {
+        id: { type: "string", minLength: 1 },
+        type: { type: "string", minLength: 1 },
+        src: { type: "string", minLength: 1 },
+        metadata: { type: "object", additionalProperties: jsonValue },
+      },
+    },
+
+    plugin: {
+      type: "object",
+      required: ["id"],
+      additionalProperties: false,
+      properties: {
+        id: { type: "string", minLength: 1 },
+        packageName: { type: "string" },
+        options: { type: "object", additionalProperties: jsonValue },
+      },
+    },
+
+    exportOptions: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        formats: { type: "array", items: { type: "string" } },
+        metadata: { type: "object", additionalProperties: jsonValue },
+      },
+    },
+
+    theme: {
+      type: "object",
+      required: ["id"],
+      additionalProperties: false,
+      properties: {
+        id: { type: "string", minLength: 1 },
+        tokens: { $ref: "#/$defs/themeTokens" },
+        css: { type: "string" },
+        fonts: {
+          type: "array",
+          items: { $ref: "#/$defs/themeFontFace" },
+        },
+      },
+    },
+
+    themeFontFace: {
+      type: "object",
+      required: ["family", "source"],
+      additionalProperties: false,
+      properties: {
+        family: { type: "string", minLength: 1 },
+        source: { type: "string", minLength: 1 },
+        format: { type: "string" },
+        weight: stringOrNumber,
+        style: { type: "string" },
+        display: { type: "string" },
+        unicodeRange: { type: "string" },
+        stretch: { type: "string" },
+      },
+    },
+
+    themeTokens: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        colors: { type: "object", additionalProperties: { type: "string" } },
+        typography: {
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/typographyToken" },
+        },
+        spacing: { type: "object", additionalProperties: stringOrNumber },
+        radii: { type: "object", additionalProperties: stringOrNumber },
+        shadows: { type: "object", additionalProperties: { type: "string" } },
+        motion: {
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/motionToken" },
+        },
+        surfaces: { type: "object", additionalProperties: { type: "string" } },
+        text: { type: "object", additionalProperties: { type: "string" } },
+      },
+    },
+
+    typographyToken: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        fontFamily: { type: "string" },
+        fontSize: stringOrNumber,
+        lineHeight: stringOrNumber,
+        fontWeight: stringOrNumber,
+        letterSpacing: stringOrNumber,
+      },
+    },
+
+    motionToken: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        duration: stringOrNumber,
+        easing: { type: "string" },
+        delay: stringOrNumber,
+      },
+    },
+
+    background: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        color: { type: "string", minLength: 1 },
+        layers: { type: "array", items: { $ref: "#/$defs/backgroundLayer" } },
+      },
+    },
+
+    backgroundLayer: {
+      oneOf: [
+        { $ref: "#/$defs/linearGradientLayer" },
+        { $ref: "#/$defs/radialGradientLayer" },
+      ],
+    },
+
+    linearGradientLayer: {
+      type: "object",
+      required: ["type", "stops"],
+      additionalProperties: false,
+      properties: {
+        type: { const: "linear" },
+        stops: {
+          type: "array",
+          minItems: 1,
+          items: { $ref: "#/$defs/gradientStop" },
+        },
+        angle: { type: "number" },
+        blend: { enum: ["normal", "screen", "multiply", "overlay"] },
+        opacity: { type: "number", minimum: 0, maximum: 1 },
+      },
+    },
+
+    radialGradientLayer: {
+      type: "object",
+      required: ["type", "stops"],
+      additionalProperties: false,
+      properties: {
+        type: { const: "radial" },
+        stops: {
+          type: "array",
+          minItems: 1,
+          items: { $ref: "#/$defs/gradientStop" },
+        },
+        shape: { enum: ["circle", "ellipse"] },
+        position: {
+          type: "object",
+          required: ["x", "y"],
+          additionalProperties: false,
+          properties: {
+            x: { type: "number", minimum: 0, maximum: 100 },
+            y: { type: "number", minimum: 0, maximum: 100 },
+          },
+        },
+        blend: { enum: ["normal", "screen", "multiply", "overlay"] },
+        opacity: { type: "number", minimum: 0, maximum: 1 },
+      },
+    },
+
+    gradientStop: {
+      type: "object",
+      required: ["color"],
+      additionalProperties: false,
+      properties: {
+        color: { type: "string", minLength: 1 },
+        at: { type: "number", minimum: 0, maximum: 100 },
+      },
+    },
+  },
+} as const;