@bendyline/squisq 1.4.1 → 1.5.1

package/src/schemas/Media.ts

@@ -0,0 +1,169 @@
+/**
+ * Media-clip timing model.
+ *
+ * An additive layer on top of the legacy sequential `Doc.audio.segments[]`
+ * narration track. A {@link MediaClip} is a piece of audio or video whose
+ * timing is expressed *relative to its parent block* (or the whole document),
+ * with an optional `startAt` offset and an optional `spillover` past the
+ * block's end. {@link resolveMediaSchedule} flattens these into absolute,
+ * doc-timeline `ScheduledClip`s that playback and export consume.
+ *
+ * Authoring: a body-level `{[audio …]}` / `{[video …]}` annotation inside a
+ * block becomes a `block.media` clip; the same annotation in the preamble
+ * (before the first heading) with `anchor=document` becomes a
+ * `doc.documentMedia` clip that spans the whole timeline.
+ */
+
+import type { Block, Doc } from './Doc.js';
+
+/**
+ * A timed piece of media attached to a block (or the document).
+ */
+export interface MediaClip {
+  /** Stable id (for React keys and timeline selection). */
+  id: string;
+  /** Source path (mp3/mp4/…), relative to the article media dir. */
+  src: string;
+  kind: 'audio' | 'video';
+  /**
+   * Seconds from the parent block's start when this clip begins. For an
+   * `anchor='document'` clip, seconds from the document start. Default 0.
+   */
+  startAt: number;
+  /** Source in-point within the file (seconds). Default 0. */
+  clipStart?: number;
+  /** Source out-point within the file (seconds). Default: file/block end. */
+  clipEnd?: number;
+  /**
+   * When false (default) the clip stops at its block's end. When true it
+   * keeps playing past the block boundary until the clip itself finishes.
+   * Ignored for `anchor='document'` clips (they already span the timeline).
+   */
+  spillover?: boolean;
+  /**
+   * `'block'` (default) — timed relative to the parent block. `'document'` —
+   * timed relative to the document start and able to span every block.
+   */
+  anchor: 'block' | 'document';
+  /**
+   * 1-based source line of the authoring annotation, when derived from
+   * markdown. Enables round-tripping edits (e.g. the timeline editor rewriting
+   * `startAt`) back to the exact line. Absent for programmatically built clips.
+   */
+  sourceLine?: number;
+}
+
+/**
+ * A {@link MediaClip} resolved to absolute document-timeline coordinates.
+ * Produced by {@link resolveMediaSchedule}; consumed by the playback
+ * scheduler and the MP4 export.
+ */
+export interface ScheduledClip {
+  id: string;
+  src: string;
+  kind: 'audio' | 'video';
+  /** Absolute doc-timeline second the clip starts. */
+  absoluteStart: number;
+  /** Absolute doc-timeline second the clip ends (exclusive). */
+  absoluteEnd: number;
+  /** Source in-point to seek to at `absoluteStart`. */
+  sourceIn: number;
+  anchor: 'block' | 'document';
+  /** Owning block id for block-anchored clips (for video re-homing/export). */
+  blockId?: string;
+  /** 1-based source line of the authoring annotation, when known. */
+  sourceLine?: number;
+}
+
+/** Depth-first flatten of the block tree (local copy to avoid a doc-layer dep). */
+function flatten(blocks: Block[], out: Block[] = []): Block[] {
+  for (const b of blocks) {
+    out.push(b);
+    if (b.children && b.children.length > 0) flatten(b.children, out);
+  }
+  return out;
+}
+
+/** Played length of a clip when known from its in/out points, else null. */
+function clipLength(clip: MediaClip): number | null {
+  if (clip.clipEnd == null) return null;
+  return Math.max(0, clip.clipEnd - (clip.clipStart ?? 0));
+}
+
+/**
+ * Base playback span ignoring media — the larger of the audio-segment sum
+ * and the last block's end. Document clips that don't pin a length run to
+ * this point.
+ */
+function baseTimelineEnd(doc: Doc): number {
+  const blockEnd = flatten(doc.blocks).reduce(
+    (max, b) => Math.max(max, b.startTime + b.duration),
+    0,
+  );
+  return Math.max(doc.duration ?? 0, blockEnd);
+}
+
+/**
+ * Flatten every block clip and document clip into absolute-timed
+ * `ScheduledClip`s. Pure — depends only on `doc`.
+ */
+export function resolveMediaSchedule(doc: Doc): ScheduledClip[] {
+  const out: ScheduledClip[] = [];
+  const docEnd = baseTimelineEnd(doc);
+
+  for (const block of flatten(doc.blocks)) {
+    const blockEnd = block.startTime + block.duration;
+    for (const clip of block.media ?? []) {
+      const start = block.startTime + clip.startAt;
+      const len = clipLength(clip);
+      let end: number;
+      if (clip.spillover) {
+        // Continue past the block; fall back to the block end when the
+        // played length is unknown (no clipEnd authored).
+        end = len != null ? start + len : blockEnd;
+      } else {
+        end = len != null ? Math.min(start + len, blockEnd) : blockEnd;
+      }
+      out.push({
+        id: clip.id,
+        src: clip.src,
+        kind: clip.kind,
+        absoluteStart: start,
+        absoluteEnd: Math.max(start, end),
+        sourceIn: clip.clipStart ?? 0,
+        anchor: 'block',
+        blockId: block.id,
+        ...(clip.sourceLine != null ? { sourceLine: clip.sourceLine } : {}),
+      });
+    }
+  }
+
+  for (const clip of doc.documentMedia ?? []) {
+    const start = clip.startAt;
+    const len = clipLength(clip);
+    const end = len != null ? start + len : docEnd;
+    out.push({
+      id: clip.id,
+      src: clip.src,
+      kind: clip.kind,
+      absoluteStart: start,
+      absoluteEnd: Math.max(start, end),
+      sourceIn: clip.clipStart ?? 0,
+      anchor: 'document',
+      ...(clip.sourceLine != null ? { sourceLine: clip.sourceLine } : {}),
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Total playback duration including any media that spills past the last
+ * block (or audio segment). Export uses this for the frame count and the
+ * player for its effective timeline length.
+ */
+export function getDocPlaybackDuration(doc: Doc): number {
+  const base = baseTimelineEnd(doc);
+  const mediaEnd = resolveMediaSchedule(doc).reduce((max, c) => Math.max(max, c.absoluteEnd), 0);
+  return Math.max(base, mediaEnd);
+}

package/src/schemas/Theme.ts

@@ -21,7 +21,7 @@
  */
 
 import type { LayoutHints } from './LayoutStrategy.js';
-import type { AnimationType, TransitionType } from './Doc.js';
+import type { AnimationType, ImageTreatment, TransitionType } from './Doc.js';
 import type { PersistentLayerConfig } from './BlockTemplates.js';
 
 // ============================================
@@ -32,6 +32,14 @@ import type { PersistentLayerConfig } from './BlockTemplates.js';
 export const THEME_SCHEMA_VERSION = '1' as const;
 export type ThemeSchemaVersion = typeof THEME_SCHEMA_VERSION;
 
+/**
+ * Frontmatter key under which a document inlines its custom Theme
+ * definitions. The theme analog of `FRONTMATTER_CUSTOM_TEMPLATES_KEY`
+ * (custom block templates). See `doc/customThemesFrontmatter.ts` for the
+ * codec and `doc/resolveDocTheme.ts` for doc-scoped resolution.
+ */
+export const FRONTMATTER_CUSTOM_THEMES_KEY = 'squisq-custom-themes';
+
 // ============================================
 // Color Palette
 // ============================================
@@ -146,6 +154,13 @@ export interface ThemeStyle {
   animationSpeed?: number;
   /** Default horizontal padding for text (percentage string, e.g. "5%") */
   blockPadding?: string;
+  /**
+   * Photographic grade applied to template imagery (full-bleed photos,
+   * feature halves, accent strips) so photos look native to the theme.
+   * Duotone tints default to the theme primary. Blocks opt out per
+   * template via `imageTreatment: 'none'`.
+   */
+  imageTreatment?: ImageTreatment;
 }
 
 // ============================================
@@ -195,6 +210,13 @@ export interface Theme {
   name: string;
   /** Short description for theme pickers */
   description?: string;
+  /**
+   * Id of the theme this custom theme was derived from, if any. Recorded
+   * by `compileTheme({ base })` so a customizer can re-open the theme and
+   * re-inherit the base's render style / color schemes / typography.
+   * Absent on built-ins.
+   */
+  basedOn?: string;
   /** Optional authoring seeds (customizer fills these; built-ins typically omit) */
   seedColors?: ThemeSeedColors;
   /** Color palette */

package/src/schemas/Transitions.ts

@@ -0,0 +1,224 @@
+/**
+ * Shared transition vocabulary for block-to-block slide changes.
+ *
+ * The canonical names are based on PowerPoint / PresentationML transition
+ * names where possible, with a few legacy renderer aliases kept so older
+ * Squisq documents continue to work.
+ */
+
+export const DEFAULT_TRANSITION_DURATION_SECONDS = 0.7;
+
+export const TRANSITION_TYPES = [
+  // Existing / common transitions
+  'cut',
+  'fade',
+  'dissolve',
+  'push',
+  'wipe',
+  'split',
+  'reveal',
+  'randomBars',
+  'shape',
+  'uncover',
+  'cover',
+  'zoom',
+  'pan',
+
+  // PowerPoint subtle / exciting transitions
+  'flash',
+  'fallOver',
+  'drape',
+  'curtains',
+  'wind',
+  'prestige',
+  'fracture',
+  'crush',
+  'peelOff',
+  'pageCurl',
+  'airplane',
+  'origami',
+  'checkerboard',
+  'blinds',
+  'clock',
+  'ripple',
+  'honeycomb',
+  'glitter',
+  'vortex',
+  'shred',
+  'switch',
+  'flip',
+  'gallery',
+  'cube',
+  'doors',
+  'box',
+  'ferrisWheel',
+  'conveyor',
+  'rotate',
+  'window',
+  'orbit',
+  'flyThrough',
+  'morph',
+
+  // PresentationML/Open XML precise names and legacy aliases
+  'checker',
+  'circle',
+  'comb',
+  'diamond',
+  'newsflash',
+  'plus',
+  'pull',
+  'random',
+  'randomBar',
+  'strips',
+  'wedge',
+  'wheel',
+  'prism',
+  'warp',
+  'ferris',
+  'flythrough',
+  'wheelReverse',
+  'pageCurlDouble',
+  'pageCurlSingle',
+  'slideLeft',
+  'slideRight',
+  'slideUp',
+  'slideDown',
+] as const;
+
+export type TransitionType = (typeof TRANSITION_TYPES)[number];
+
+export const TRANSITION_DIRECTIONS = [
+  'left',
+  'right',
+  'up',
+  'down',
+  'in',
+  'out',
+  'horizontal',
+  'vertical',
+] as const;
+
+export type TransitionDirection = (typeof TRANSITION_DIRECTIONS)[number];
+
+/**
+ * Transition between blocks.
+ *
+ * A block's transition is the lead-in from the previous block. The same
+ * transition drives the entering block and the previous block's exit.
+ */
+export interface Transition {
+  /** Transition type */
+  type: TransitionType;
+  /** Duration in seconds. Defaults to DEFAULT_TRANSITION_DURATION_SECONDS. */
+  duration?: number;
+  /** Optional direction/variant for directional transitions. */
+  direction?: TransitionDirection;
+}
+
+const TRANSITION_TYPE_SET = new Set<string>(TRANSITION_TYPES);
+
+const TRANSITION_TYPE_ALIASES: Record<string, TransitionType> = {
+  none: 'cut',
+  randombars: 'randomBars',
+  randombar: 'randomBar',
+  // Self-referential spellings (`checkerboard`, `shape`, `uncover`) are
+  // intentionally absent: an exact valid type returns early from
+  // `normalizeTransitionType`, and any case variant resolves through
+  // `NORMALIZED_TRANSITION_TYPES`. Only the *plural* aliases need an entry.
+  checkerboards: 'checkerboard',
+  shapes: 'shape',
+  ferris: 'ferrisWheel',
+  ferriswheel: 'ferrisWheel',
+  flythrough: 'flyThrough',
+  flythru: 'flyThrough',
+  pagecurl: 'pageCurl',
+  pagecurldouble: 'pageCurlDouble',
+  pagecurlsingle: 'pageCurlSingle',
+  wheelreverse: 'wheelReverse',
+  slideleft: 'slideLeft',
+  slideright: 'slideRight',
+  slideup: 'slideUp',
+  slidedown: 'slideDown',
+};
+
+const NORMALIZED_TRANSITION_TYPES = new Map<string, TransitionType>(
+  TRANSITION_TYPES.map((type) => [normalizeToken(type), type]),
+);
+
+export function isTransitionType(value: string): value is TransitionType {
+  return TRANSITION_TYPE_SET.has(value);
+}
+
+export function normalizeTransitionType(value: string): TransitionType | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (isTransitionType(trimmed)) return trimmed;
+  const normalized = normalizeToken(trimmed);
+  return TRANSITION_TYPE_ALIASES[normalized] ?? NORMALIZED_TRANSITION_TYPES.get(normalized) ?? null;
+}
+
+export function normalizeTransitionDirection(value: string): TransitionDirection | null {
+  const normalized = normalizeToken(value);
+  switch (normalized) {
+    case 'left':
+    case 'l':
+      return 'left';
+    case 'right':
+    case 'r':
+      return 'right';
+    case 'up':
+    case 'u':
+      return 'up';
+    case 'down':
+    case 'd':
+      return 'down';
+    case 'in':
+      return 'in';
+    case 'out':
+      return 'out';
+    case 'horizontal':
+    case 'horz':
+    case 'h':
+      return 'horizontal';
+    case 'vertical':
+    case 'vert':
+    case 'v':
+      return 'vertical';
+    default:
+      return null;
+  }
+}
+
+export function resolveTransitionDuration(
+  transition: Transition | undefined,
+  fallback: number = DEFAULT_TRANSITION_DURATION_SECONDS,
+): number {
+  const duration = transition?.duration;
+  return duration != null && Number.isFinite(duration) && duration > 0 ? duration : fallback;
+}
+
+/**
+ * Resolve the effective transition for a block: the authored value wins
+ * (markdown frontmatter and transform styles both write `block.transition`
+ * upstream), then the theme's `renderStyle.defaultTransition`, then
+ * `undefined` (the player's built-in default).
+ *
+ * Block 0 never gets a theme default — an entrance transition on the first
+ * block would dim the opening frames of every exported video.
+ *
+ * The theme parameter is structural (not `Theme`) to avoid a schema import
+ * cycle; pass any resolved theme.
+ */
+export function resolveBlockTransition(
+  block: { transition?: Transition },
+  theme: { renderStyle: { defaultTransition?: Transition } },
+  blockIndex: number,
+): Transition | undefined {
+  if (block.transition) return block.transition;
+  if (blockIndex === 0) return undefined;
+  return theme.renderStyle.defaultTransition;
+}
+
+function normalizeToken(value: string): string {
+  return value.toLowerCase().replace(/[\s_-]+/g, '');
+}

package/src/schemas/colorUtils.ts

@@ -143,6 +143,39 @@ export function relativeLuminance(hex: string): number {
   return 0.2126 * r + 0.7152 * g + 0.0722 * b;
 }
 
+/**
+ * Hue of a hex color in HSL degrees (0..360). Returns 0 for pure grays
+ * and on parse failure. Used by the duotone image treatment to aim its
+ * `hue-rotate()` at the theme's tint color.
+ */
+export function hexHueDegrees(hex: string): number {
+  const rgb = parseHex(hex);
+  if (!rgb) return 0;
+  const [r, g, b] = rgb;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  if (max === min) return 0;
+  const d = max - min;
+  let h: number;
+  if (max === r) h = ((g - b) / d) % 6;
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return Math.round((h * 60 + 360) % 360);
+}
+
+/**
+ * Convert a hex color + alpha (0..1) to an `rgba()` string.
+ * Falls back to the input on parse failure (e.g. a value that is
+ * already an rgba()/gradient string).
+ */
+export function withAlpha(hex: string, alpha: number): string {
+  const rgb = parseHex(hex);
+  if (!rgb) return hex;
+  const a = Math.max(0, Math.min(1, alpha));
+  const ch = (v: number) => Math.round(v * 255);
+  return `rgba(${ch(rgb[0])}, ${ch(rgb[1])}, ${ch(rgb[2])}, ${a})`;
+}
+
 /**
  * WCAG contrast ratio between two hex colors. Returns 1..21.
  */

package/src/schemas/fontStacks.ts

@@ -87,7 +87,10 @@ export const AVAILABLE_FONT_STACKS: FontStack[] = [
   {
     id: 'oswald',
     label: 'Oswald',
-    family: '"Oswald", Impact, "Arial Black", sans-serif',
+    // Condensed grotesques make a far better stand-in for Oswald than
+    // Impact/Arial Black, whose extreme weight distorts every layout
+    // tuned for the real face.
+    family: '"Oswald", "Arial Narrow", "Helvetica Neue Condensed", "Roboto Condensed", sans-serif',
     kind: 'display',
     googleFontFamily: 'Oswald',
   },
@@ -185,7 +188,7 @@ const FALLBACK_BY_KIND: Record<FontFamilyKind, string> = {
   sans: 'system-ui, sans-serif',
   serif: 'Georgia, serif',
   mono: 'Consolas, monospace',
-  display: 'Impact, Arial, sans-serif',
+  display: '"Arial Narrow", "Helvetica Neue", Arial, sans-serif',
 };
 
 /**

package/src/schemas/index.ts

@@ -1,6 +1,9 @@
 export * from './Types.js';
 export * from './Doc.js';
+export * from './Transitions.js';
+export * from './Media.js';
 export * from './BlockTemplates.js';
+export * from './CustomTemplates.js';
 export * from './Theme.js';
 export * from './themeLibrary.js';
 export * from './themeValidator.js';

package/src/schemas/themeCompile.ts

@@ -140,17 +140,28 @@ export type ContrastPreset = 'subtle' | 'balanced' | 'high';
 export interface CompileOptions {
   /** Contrast level for OKLCh derivation (default 'balanced'). */
   contrast?: ContrastPreset;
+  /**
+   * Base theme to inherit from. When provided, the partial is deep-merged
+   * over this theme instead of the neutral `STARTER_THEME`, so the compiled
+   * theme inherits the base's render style, color schemes, typography, and
+   * persistent layers — and only the fields the user changed are overridden.
+   * The base's id is recorded on the result as `basedOn`.
+   */
+  base?: Theme;
 }
 
 /**
  * Compile a partial Theme into a complete one. Fills missing fields from
- * `STARTER_THEME`, derives missing color slots from `seedColors` (when
- * present), and validates the result.
+ * the base (`opts.base` when given, else `STARTER_THEME`), derives missing
+ * color slots from `seedColors` (when present), and validates the result.
  */
 export function compileTheme(partial: DeepPartial<Theme>, opts: CompileOptions = {}): Theme {
-  // Step 1: deep-merge over the starter
-  const merged = createTheme(STARTER_THEME, partial);
+  // Step 1: deep-merge over the base (a chosen theme, or the neutral starter)
+  const base = opts.base ?? STARTER_THEME;
+  const merged = createTheme(base, partial);
   merged.schemaVersion = THEME_SCHEMA_VERSION;
+  // Record which theme this was derived from so a customizer can re-inherit.
+  if (opts.base && !merged.basedOn) merged.basedOn = opts.base.id;
 
   // Step 1b: typography fonts are discriminated unions ({stackId} | {custom}),
   // so deep-merge would leave stale keys from the starter when the partial
@@ -168,6 +179,14 @@ export function compileTheme(partial: DeepPartial<Theme>, opts: CompileOptions =
     }
   }
 
+  // Step 1c: colorSchemes is a map the user edits wholesale (add / remove
+  // accents). Deep-merge can't delete keys, so replace it outright when the
+  // partial provides it — mirroring the font replacement above. This lets a
+  // removed accent actually disappear rather than lingering from the base.
+  if (partial.colorSchemes !== undefined) {
+    merged.colorSchemes = partial.colorSchemes as Record<string, ThemeColorScheme>;
+  }
+
   // Step 2: derive missing color slots from seeds, if present
   if (merged.seedColors) {
     const partialColors = (partial.colors ?? {}) as Partial<ThemeColorPalette>;
@@ -187,7 +206,7 @@ export function parseTheme(json: string): Theme {
   let parsed: unknown;
   try {
     parsed = JSON.parse(json);
-  } catch (err) {
+  } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new Error(`Invalid theme JSON: ${msg}`);
   }

package/src/schemas/themeValidator.ts

@@ -13,6 +13,7 @@
 import type { Theme, ThemeColorPalette } from './Theme.js';
 import { THEME_SCHEMA_VERSION } from './Theme.js';
 import { isHex } from './colorUtils.js';
+import { isTransitionType } from './Transitions.js';
 
 export interface ValidationError {
   path: string;
@@ -28,16 +29,6 @@ export interface ValidationResult {
 
 const VALID_FALLBACK = new Set(['serif', 'sans-serif', 'monospace', 'system-ui']);
 const VALID_TITLE_WEIGHT = new Set(['normal', 'bold']);
-const VALID_TRANSITION_TYPES = new Set([
-  'cut',
-  'fade',
-  'dissolve',
-  'slideLeft',
-  'slideRight',
-  'slideUp',
-  'slideDown',
-  'zoom',
-]);
 const VALID_GRADIENT_PRESETS = new Set([
   'dark-vignette',
   'radial-dark',
@@ -179,6 +170,24 @@ class V {
     if (v.blockPadding !== undefined && !this.isString(v.blockPadding)) {
       this.err(`${path}.blockPadding`, 'expected string (percentage e.g. "5%")');
     }
+    if (v.imageTreatment !== undefined) {
+      this.imageTreatment(`${path}.imageTreatment`, v.imageTreatment);
+    }
+  }
+
+  imageTreatment(path: string, v: unknown): void {
+    if (!this.isObject(v)) {
+      this.err(path, 'expected object');
+      return;
+    }
+    const kinds = ['none', 'mono', 'duotone', 'warm', 'cool'];
+    if (!this.isString(v.type) || !kinds.includes(v.type)) {
+      this.err(`${path}.type`, `expected one of ${kinds.join('|')}`);
+    }
+    if (v.strength !== undefined && !this.isNumber(v.strength)) {
+      this.err(`${path}.strength`, 'expected number (0..1)');
+    }
+    if (v.color !== undefined) this.hex(`${path}.color`, v.color);
   }
 
   renderStyle(path: string, v: unknown): void {
@@ -202,7 +211,7 @@ class V {
       if (!this.isObject(t)) {
         this.err(`${path}.defaultTransition`, 'expected object');
       } else {
-        if (!this.isString(t.type) || !VALID_TRANSITION_TYPES.has(t.type)) {
+        if (!this.isString(t.type) || !isTransitionType(t.type)) {
           this.err(`${path}.defaultTransition.type`, 'expected valid transition type');
         }
         if (t.duration !== undefined && !this.isNumber(t.duration)) {
@@ -286,6 +295,32 @@ class V {
           'raw CSS gradient strings are not allowed in Theme JSON; use a `preset`',
         );
       }
+      if (v.template === 'patternBackground') {
+        const patterns = ['dots', 'grid', 'diagonal', 'noise'];
+        if (!this.isString(cfg.pattern) || !patterns.includes(cfg.pattern)) {
+          this.err(`${path}.config.pattern`, `expected one of ${patterns.join('|')}`);
+        }
+        for (const k of ['opacity', 'scale']) {
+          if (cfg[k] !== undefined && !this.isNumber(cfg[k])) {
+            this.err(`${path}.config.${k}`, 'expected number');
+          }
+        }
+        if (cfg.color !== undefined) this.hex(`${path}.config.color`, cfg.color);
+      }
+      if (v.template === 'vignette') {
+        if (cfg.strength !== undefined && !this.isNumber(cfg.strength)) {
+          this.err(`${path}.config.strength`, 'expected number (0..1)');
+        }
+        if (cfg.color !== undefined) this.hex(`${path}.config.color`, cfg.color);
+      }
+      if (v.template === 'ambientGradient') {
+        if (cfg.duration !== undefined && !this.isNumber(cfg.duration)) {
+          this.err(`${path}.config.duration`, 'expected number (seconds)');
+        }
+        for (const k of ['from', 'to']) {
+          if (cfg[k] !== undefined) this.hex(`${path}.config.${k}`, cfg[k]);
+        }
+      }
     }
     // Raw Layer form is permissive — no schema check here
   }
@@ -328,6 +363,9 @@ export function validateTheme(input: unknown): ValidationResult {
   if (input.description !== undefined && !v.isString(input.description)) {
     v.err('description', 'expected string');
   }
+  if (input.basedOn !== undefined && !v.isString(input.basedOn)) {
+    v.err('basedOn', 'expected string');
+  }
 
   if (input.seedColors !== undefined) v.seedColors('seedColors', input.seedColors);