@velumo/core 0.1.0-beta.0

package/src/builders.ts

@@ -0,0 +1,626 @@
+import type {
+  AnimateLayout,
+  AnimationName,
+  CalloutElement,
+  CameraStop,
+  CameraView,
+  CanvasItem,
+  CanvasLayout,
+  CodeElement,
+  CodeToken,
+  CodeTokenKind,
+  ConnectorElement,
+  ConnectorPoint,
+  Cue,
+  CueAction,
+  ExportOptions,
+  FrameLayout,
+  Fragment,
+  GridLayout,
+  HeadingElement,
+  HeroLayout,
+  BadgeElement,
+  IconElement,
+  RuleElement,
+  IconName,
+  JsonValue,
+  Layer,
+  LayoutMeta,
+  LayoutNode,
+  Manifest,
+  MediaElement,
+  Plugin,
+  Scene,
+  Slide,
+  SlideEntry,
+  SplitLayout,
+  StackLayout,
+  TableColumn,
+  TableLayout,
+  TextElement,
+  Theme,
+} from "./types.js";
+
+export interface DeckInput {
+  readonly title: string;
+  readonly description?: string;
+  readonly author?: string;
+  readonly watermark?: string;
+  readonly slides: readonly SlideEntry[];
+  readonly assets?: Manifest["assets"];
+  readonly plugins?: readonly Plugin[];
+  readonly theme?: Theme;
+  readonly export?: ExportOptions;
+}
+
+export type SlideOptions = Omit<Slide, "id" | "kind">;
+export type SceneOptions = Omit<Scene, "id" | "kind">;
+export type LayerOptions = Omit<Layer, "type">;
+export type FragmentOptions = Omit<Fragment, "id">;
+export type StackOptions = Omit<StackLayout, "kind" | "children">;
+export type GridOptions = Omit<GridLayout, "kind" | "children">;
+export type SplitOptions = Omit<SplitLayout, "kind" | "children">;
+export type HeroOptions = Omit<HeroLayout, "kind" | "children">;
+export type FrameOptions = Omit<FrameLayout, "kind" | "children">;
+export type CanvasOptions = Omit<CanvasLayout, "kind" | "items">;
+export type CameraStopOptions = Omit<CameraStop, "camera">;
+
+export interface AtOptions {
+  readonly width?: number;
+  readonly height?: number;
+}
+
+export interface AnimateOptions {
+  readonly delay?: number;
+  readonly duration?: number;
+  readonly easing?: string;
+}
+export type HeadingOptions = Omit<HeadingElement, "kind" | "text">;
+export type TextOptions = Omit<TextElement, "kind" | "text">;
+export type MediaOptions = Omit<MediaElement, "kind" | "src" | "alt"> & {
+  readonly alt?: string;
+};
+export type CalloutOptions = Omit<CalloutElement, "kind" | "children">;
+export type LayoutChildInput = LayoutNode | readonly LayoutNode[];
+export type LayoutSlideOptions = Omit<SlideOptions, "layout">;
+export type LayoutSceneOptions = Omit<SceneOptions, "layout">;
+
+export interface TitleLayoutOptions {
+  readonly subtitle?: string;
+  readonly kicker?: string;
+  readonly level?: HeadingElement["level"];
+}
+
+export interface SectionLayoutOptions {
+  readonly level?: HeadingElement["level"];
+}
+
+export interface TwoColumnOptions {
+  readonly weights?: readonly [number, number];
+}
+
+export interface MediaHeroOptions {
+  readonly alt?: string;
+  readonly title?: string;
+  readonly body?: string;
+  readonly fit?: MediaElement["fit"];
+}
+
+export interface QuoteOptions {
+  readonly attribution?: string;
+}
+
+export interface VelumoConfig {
+  readonly entry?: string;
+  readonly root?: string;
+  readonly outDir?: string;
+  readonly theme?: string;
+  readonly [key: string]: JsonValue | undefined;
+}
+
+function assertUniqueSlideEntryIds(slides: readonly SlideEntry[]): void {
+  const seen = new Set<string>();
+
+  for (const entry of slides) {
+    if (seen.has(entry.id)) {
+      throw new Error(`duplicate slide/scene id: ${entry.id}`);
+    }
+
+    seen.add(entry.id);
+  }
+}
+
+export function deck(input: DeckInput): Manifest {
+  assertUniqueSlideEntryIds(input.slides);
+
+  return {
+    deck: {
+      title: input.title,
+      ...(input.description === undefined
+        ? {}
+        : { description: input.description }),
+      ...(input.author === undefined ? {} : { author: input.author }),
+      ...(input.watermark === undefined ? {} : { watermark: input.watermark }),
+    },
+    slides: input.slides,
+    ...(input.assets === undefined ? {} : { assets: input.assets }),
+    ...(input.plugins === undefined ? {} : { plugins: input.plugins }),
+    ...(input.theme === undefined ? {} : { theme: input.theme }),
+    ...(input.export === undefined ? {} : { export: input.export }),
+  };
+}
+
+export function slide(id: string, options: SlideOptions = {}): Slide {
+  return {
+    id,
+    kind: "slide",
+    ...options,
+  };
+}
+
+export function scene(id: string, options: SceneOptions = {}): Scene {
+  return {
+    id,
+    kind: "scene",
+    ...options,
+  };
+}
+
+export function layer(type: string, options: LayerOptions = {}): Layer {
+  return {
+    ...options,
+    type,
+  };
+}
+
+export function markdown(content: string, options: LayerOptions = {}): Layer {
+  return layer("markdown", {
+    ...options,
+    content,
+  });
+}
+
+function normalizeLayoutChildren(
+  input: LayoutChildInput | undefined,
+): LayoutNode[] {
+  if (input === undefined) {
+    return [];
+  }
+
+  if (Array.isArray(input)) {
+    return [...input];
+  }
+
+  return [input as LayoutNode];
+}
+
+function normalizeColumnLayout(input: LayoutChildInput): LayoutNode {
+  const children = normalizeLayoutChildren(input);
+
+  if (Array.isArray(input)) {
+    return stack(children);
+  }
+
+  return children[0];
+}
+
+function headingOptions(
+  level: HeadingElement["level"] | undefined,
+): HeadingOptions {
+  return level === undefined ? {} : { level };
+}
+
+export function stack(
+  children: readonly LayoutNode[] = [],
+  options: StackOptions = {},
+): StackLayout {
+  return {
+    kind: "stack",
+    children,
+    ...options,
+  };
+}
+
+export function grid(
+  children: readonly LayoutNode[] = [],
+  options: GridOptions = {},
+): GridLayout {
+  return {
+    kind: "grid",
+    children,
+    ...options,
+  };
+}
+
+export function split(
+  children: readonly LayoutNode[],
+  options: SplitOptions = {},
+): SplitLayout {
+  return {
+    kind: "split",
+    children,
+    ...options,
+  };
+}
+
+export function hero(
+  children: readonly LayoutNode[],
+  options: HeroOptions = {},
+): HeroLayout {
+  return {
+    kind: "hero",
+    children,
+    ...options,
+  };
+}
+
+export function frame(
+  children: readonly LayoutNode[] = [],
+  options: FrameOptions = {},
+): FrameLayout {
+  return {
+    kind: "frame",
+    children,
+    ...options,
+  };
+}
+
+export function canvas(
+  items: readonly CanvasItem[] = [],
+  options: CanvasOptions = {},
+): CanvasLayout {
+  return {
+    kind: "canvas",
+    items,
+    ...options,
+  };
+}
+
+export function col(
+  header?: LayoutNode,
+  options: {
+    readonly weight?: number;
+    readonly align?: TableColumn["align"];
+    readonly emphasis?: boolean;
+  } = {},
+): TableColumn {
+  return {
+    ...(header === undefined ? {} : { header }),
+    ...(options.weight === undefined ? {} : { weight: options.weight }),
+    ...(options.align === undefined ? {} : { align: options.align }),
+    ...(options.emphasis === undefined ? {} : { emphasis: options.emphasis }),
+  };
+}
+
+export function table(
+  columns: readonly TableColumn[],
+  rows: readonly (readonly LayoutNode[])[],
+  options: { readonly meta?: LayoutMeta } = {},
+): TableLayout {
+  return {
+    kind: "table",
+    columns,
+    rows,
+    ...(options.meta === undefined ? {} : { meta: options.meta }),
+  };
+}
+
+export function at(
+  x: number,
+  y: number,
+  child: LayoutNode,
+  options: AtOptions = {},
+): CanvasItem {
+  return {
+    x,
+    y,
+    ...(options.width === undefined ? {} : { width: options.width }),
+    ...(options.height === undefined ? {} : { height: options.height }),
+    child,
+  };
+}
+
+export function cameraView(x: number, y: number, zoom?: number): CameraView {
+  return zoom === undefined ? { x, y } : { x, y, zoom };
+}
+
+export function cameraStop(
+  camera: CameraView,
+  options: CameraStopOptions = {},
+): CameraStop {
+  return {
+    camera,
+    ...(options.transition === undefined
+      ? {}
+      : { transition: options.transition }),
+    ...(options.cues === undefined ? {} : { cues: options.cues }),
+    ...(options.hold === undefined ? {} : { hold: options.hold }),
+  };
+}
+
+export function animate(
+  name: AnimationName,
+  child: LayoutNode,
+  options: AnimateOptions = {},
+): AnimateLayout {
+  return {
+    kind: "animate",
+    name,
+    ...(options.delay === undefined ? {} : { delay: options.delay }),
+    ...(options.duration === undefined ? {} : { duration: options.duration }),
+    ...(options.easing === undefined ? {} : { easing: options.easing }),
+    child,
+  };
+}
+
+export function heading(
+  text: string,
+  options: HeadingOptions = {},
+): HeadingElement {
+  return {
+    kind: "heading",
+    text,
+    ...options,
+  };
+}
+
+export function text(text: string, options: TextOptions = {}): TextElement {
+  return {
+    kind: "text",
+    text,
+    ...options,
+  };
+}
+
+/**
+ * Derive a sensible, non-empty `alt` from a media `src` so a minimal
+ * `media(src)` call still produces a valid (non-empty alt) manifest. This is a
+ * fallback, not a substitute for authored alt text: explicit `alt` should
+ * always be preferred and overrides this default.
+ */
+function deriveMediaAlt(src: string): string {
+  if (typeof src !== "string") {
+    return "image";
+  }
+  const base = src.split(/[/\\]/).pop() ?? "";
+  const withoutExtension = base.replace(/\.[^.]+$/, "");
+  const words = withoutExtension.replace(/[-_]+/g, " ").trim();
+  return words.length > 0 ? words : "image";
+}
+
+export function media(src: string, options: MediaOptions = {}): MediaElement {
+  const { alt, ...rest } = options;
+  return {
+    kind: "media",
+    src,
+    alt: alt ?? deriveMediaAlt(src),
+    ...rest,
+  };
+}
+
+export function callout(
+  children: readonly LayoutNode[] = [],
+  options: CalloutOptions = {},
+): CalloutElement {
+  return {
+    kind: "callout",
+    children,
+    ...options,
+  };
+}
+
+export function token(text: string, kind?: CodeTokenKind): CodeToken {
+  return kind === undefined ? { text } : { text, kind };
+}
+
+export function code(lines: readonly (readonly CodeToken[])[]): CodeElement {
+  return { kind: "code", lines };
+}
+
+export function icon(
+  name: IconName,
+  options: {
+    readonly tone?: IconElement["tone"];
+    readonly label?: string;
+  } = {},
+): IconElement {
+  return {
+    kind: "icon",
+    name,
+    ...(options.tone === undefined ? {} : { tone: options.tone }),
+    ...(options.label === undefined ? {} : { label: options.label }),
+  };
+}
+
+export function badge(
+  text: string,
+  options: {
+    readonly tone?: BadgeElement["tone"];
+    readonly variant?: BadgeElement["variant"];
+    readonly dot?: BadgeElement["tone"];
+    readonly mono?: boolean;
+  } = {},
+): BadgeElement {
+  return {
+    kind: "badge",
+    text,
+    ...(options.tone === undefined ? {} : { tone: options.tone }),
+    ...(options.variant === undefined ? {} : { variant: options.variant }),
+    ...(options.dot === undefined ? {} : { dot: options.dot }),
+    ...(options.mono === undefined ? {} : { mono: options.mono }),
+  };
+}
+
+export function rule(
+  options: {
+    readonly length?: string | number;
+    readonly thickness?: number;
+    readonly tone?: RuleElement["tone"];
+    readonly gradient?: RuleElement["gradient"];
+    readonly radius?: number;
+  } = {},
+): RuleElement {
+  return {
+    kind: "rule",
+    ...(options.length === undefined ? {} : { length: options.length }),
+    ...(options.thickness === undefined
+      ? {}
+      : { thickness: options.thickness }),
+    ...(options.tone === undefined ? {} : { tone: options.tone }),
+    ...(options.gradient === undefined ? {} : { gradient: options.gradient }),
+    ...(options.radius === undefined ? {} : { radius: options.radius }),
+  };
+}
+
+export function point(x: number, y: number): ConnectorPoint {
+  return { x, y };
+}
+
+export function connector(
+  from: ConnectorPoint,
+  to: ConnectorPoint,
+  options: {
+    readonly control?: ConnectorPoint;
+    readonly arrow?: ConnectorElement["arrow"];
+    readonly dashed?: boolean;
+    readonly tone?: ConnectorElement["tone"];
+  } = {},
+): ConnectorElement {
+  return {
+    kind: "connector",
+    from,
+    to,
+    ...(options.control === undefined ? {} : { control: options.control }),
+    ...(options.arrow === undefined ? {} : { arrow: options.arrow }),
+    ...(options.dashed === undefined ? {} : { dashed: options.dashed }),
+    ...(options.tone === undefined ? {} : { tone: options.tone }),
+  };
+}
+
+export function layoutSlide(
+  id: string,
+  layout: LayoutNode,
+  options: LayoutSlideOptions = {},
+): Slide {
+  return slide(id, {
+    ...options,
+    layout,
+  });
+}
+
+export function layoutScene(
+  id: string,
+  layout: LayoutNode,
+  options: LayoutSceneOptions = {},
+): Scene {
+  return scene(id, {
+    ...options,
+    layout,
+  });
+}
+
+export function titleLayout(
+  title: string,
+  options: TitleLayoutOptions = {},
+): HeroLayout {
+  const children: LayoutNode[] = [];
+
+  if (options.kicker !== undefined) {
+    children.push(text(options.kicker, { variant: "caption" }));
+  }
+
+  children.push(heading(title, headingOptions(options.level)));
+
+  if (options.subtitle !== undefined) {
+    children.push(text(options.subtitle, { variant: "lead" }));
+  }
+
+  return hero(children);
+}
+
+export function sectionLayout(
+  title: string,
+  children?: LayoutChildInput,
+  options: SectionLayoutOptions = {},
+): StackLayout {
+  return stack([
+    heading(title, headingOptions(options.level)),
+    ...normalizeLayoutChildren(children),
+  ]);
+}
+
+export function twoColumn(
+  left: LayoutChildInput,
+  right: LayoutChildInput,
+  options: TwoColumnOptions = {},
+): SplitLayout {
+  return split(
+    [normalizeColumnLayout(left), normalizeColumnLayout(right)],
+    options,
+  );
+}
+
+export function mediaHero(
+  src: string,
+  options: MediaHeroOptions = {},
+): HeroLayout {
+  const children: LayoutNode[] = [];
+
+  if (options.title !== undefined) {
+    children.push(heading(options.title));
+  }
+
+  if (options.body !== undefined) {
+    children.push(text(options.body, { variant: "lead" }));
+  }
+
+  children.push(
+    media(src, {
+      ...(options.alt === undefined ? {} : { alt: options.alt }),
+      ...(options.fit === undefined ? {} : { fit: options.fit }),
+    }),
+  );
+
+  return hero(children);
+}
+
+export function quote(
+  value: string,
+  options: QuoteOptions = {},
+): CalloutElement {
+  const children: LayoutNode[] = [text(value)];
+
+  if (options.attribution !== undefined) {
+    children.push(text(options.attribution, { variant: "caption" }));
+  }
+
+  return callout(children, { tone: "quote" });
+}
+
+export function fragment(id: string, options: FragmentOptions = {}): Fragment {
+  return {
+    id,
+    ...options,
+  };
+}
+
+export function cue(time: number, action: CueAction): Cue {
+  return {
+    time,
+    action,
+  };
+}
+
+export function defineTheme<TTheme extends Theme>(theme: TTheme): TTheme {
+  return theme;
+}
+
+export function definePlugin<TPlugin extends Plugin>(plugin: TPlugin): TPlugin {
+  return plugin;
+}
+
+export function defineConfig<TConfig extends VelumoConfig>(
+  config: TConfig,
+): TConfig {
+  return config;
+}

package/src/capabilities.ts

@@ -0,0 +1,99 @@
+import type {
+  CapabilityField,
+  VelumoCapabilities,
+  NodeCapability,
+} from "./types.js";
+import { manifestJsonSchema } from "./manifest-schema.js";
+
+/**
+ * Minimal structural view of the parts of `manifestJsonSchema` this projection
+ * reads. The schema is authored as a literal `as const`; this loose shape lets
+ * us walk it without fighting the inferred literal types.
+ */
+interface PropSchema {
+  readonly const?: string;
+  readonly type?: string | readonly string[];
+  readonly enum?: readonly string[];
+  readonly items?: { readonly $ref?: string };
+  readonly $ref?: string;
+}
+
+interface DefSchema {
+  readonly oneOf?: readonly { readonly $ref: string }[];
+  readonly required?: readonly string[];
+  readonly properties?: Record<string, PropSchema>;
+}
+
+const schema = manifestJsonSchema as unknown as {
+  readonly $id: string;
+  readonly $defs: Record<string, DefSchema>;
+};
+
+const LAYOUT_NODE_REF = "#/$defs/layoutNode";
+
+function resolveRef(ref: string): DefSchema {
+  return schema.$defs[ref.replace("#/$defs/", "")];
+}
+
+function deriveType(prop: PropSchema): string {
+  if (Array.isArray(prop.enum)) {
+    return "enum";
+  }
+  if (prop.type === "array") {
+    return prop.items?.$ref === LAYOUT_NODE_REF ? "node[]" : "array";
+  }
+  if (Array.isArray(prop.type)) {
+    return prop.type.join("|");
+  }
+  if (typeof prop.type === "string") {
+    return prop.type;
+  }
+  return "object";
+}
+
+function describeNode(def: DefSchema): NodeCapability {
+  const required = new Set(def.required ?? []);
+  const properties = def.properties ?? {};
+
+  const fields: CapabilityField[] = Object.entries(properties)
+    .filter(([name]) => name !== "kind")
+    .map(([name, prop]) => {
+      const field: CapabilityField = {
+        name,
+        required: required.has(name),
+        type: deriveType(prop),
+      };
+      return Array.isArray(prop.enum)
+        ? { ...field, enum: [...prop.enum] }
+        : field;
+    });
+
+  return {
+    kind: def.properties?.kind?.const ?? "unknown",
+    fields,
+  };
+}
+
+function discriminatorKinds(def: DefSchema): readonly string[] {
+  return (def.oneOf ?? []).map(
+    (ref) => resolveRef(ref.$ref).properties?.kind?.const ?? "unknown",
+  );
+}
+
+/**
+ * Project the manifest JSON Schema into an agent-friendly capability catalog.
+ * Pure and deterministic: returns a fresh, JSON-serializable object every call.
+ */
+export function describeCapabilities(): VelumoCapabilities {
+  const layoutNode = schema.$defs.layoutNode;
+  const nodes = (layoutNode.oneOf ?? []).map((ref) =>
+    describeNode(resolveRef(ref.$ref)),
+  );
+
+  return {
+    schemaId: schema.$id,
+    slideKinds: discriminatorKinds(schema.$defs.slideEntry),
+    nodes,
+    themeTokenFamilies: Object.keys(schema.$defs.themeTokens.properties ?? {}),
+  };
+}