@bycrux/editor 0.12.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "0.12.0",
+  "version": "1.0.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -17,9 +17,11 @@
     "lint": "eslint src"
   },
   "dependencies": {
+    "@bycrux/timeline-core": "^0.1.0",
     "class-variance-authority": "^0.7",
     "clsx": "^2",
     "lucide-react": "^0.400",
+    "mp4box": "^0.5.4",
     "tailwind-merge": "^2"
   },
   "peerDependencies": {

package/src/ControlsInfoModal.tsx

@@ -1,10 +1,46 @@
-import { useEffect } from 'react'
-import { X } from 'lucide-react'
+import { useEffect, type ComponentType } from 'react'
+import {
+  ChevronsLeftRight,
+  Clapperboard,
+  Command,
+  Crop,
+  Keyboard,
+  LayoutPanelTop,
+  Magnet,
+  Maximize2,
+  MousePointer2,
+  MousePointerClick,
+  Move,
+  MoveHorizontal,
+  RotateCw,
+  SeparatorVertical,
+  SlidersHorizontal,
+  Timer,
+  X,
+  type LucideProps,
+} from 'lucide-react'
 
 /** A single control/shortcut row. `keys` renders as <kbd> chips; omit for a pure gesture. */
 export interface ControlEntry {
   keys?: string[]
   label: string
+  /** The row's own glyph, drawn in place of its bullet: a toolbar button's
+   *  actual icon, or a picture of the gesture (four-way arrows for a move,
+   *  facing chevrons for an edge-trim). It carries the meaning ahead of the
+   *  sentence — and for a toolbar row it also ties the words to a button
+   *  that's easy to miss, the crop one especially, since it's a 12px glyph
+   *  that greys out whenever no clip is selected. */
+  icon?: ComponentType<LucideProps>
+  /** Where the gesture applies — "Preview", "Timeline". Rendered as a pill on
+   *  the right, in the same slot the keyboard rows put their key chips.
+   *
+   *  This exists because Preview and Timeline used to be two separate cards,
+   *  and the heading was the only thing saying which surface a gesture was
+   *  for. Merging them into one Mouse card would have thrown that away; the
+   *  pill puts it back per row, where it's easier to read anyway — you no
+   *  longer have to look up to a heading to find out where "corner-drag to
+   *  scale" applies. */
+  where?: string
 }
 
 export interface ControlSection {
@@ -18,11 +54,47 @@ export interface ControlsInfoModalProps {
   onClose: () => void
 }
 
+/** Heading → icon. Lives here rather than on `ControlSection` so the content
+ *  arrays below stay pure data (a heading and some labels) and a host passing
+ *  its own sections doesn't have to know about lucide. Unknown headings fall
+ *  back to the neutral slider glyph rather than rendering a hole. */
+const SECTION_ICONS: Record<string, ComponentType<LucideProps>> = {
+  Mouse: MousePointer2,
+  Canvas: MousePointer2,
+  Toolbar: SlidersHorizontal,
+  Keyboard: Keyboard,
+  // Not used by the two content arrays below any more (Preview and Timeline
+  // merged into Mouse), but kept for a host passing sections of its own.
+  Preview: Clapperboard,
+  Timeline: LayoutPanelTop,
+}
+
 /**
  * Read-only "how to drive this editor" modal. Content is passed in per editor
  * (video vs carousel) so this component stays a dumb, themed renderer. Matches
- * the backdrop/Esc/close conventions of the other editor modals (TranscriptModal
+ * the backdrop/Esc/close conventions of the other editor modals (RenderModal
  * et al.) and uses the shared `--editor-*` theme tokens.
+ *
+ * The layout is deliberately not a flat list: each section is its own card with
+ * an icon and a heading, and each row is a hoverable line with the gesture or
+ * shortcut right-aligned. A dense unbroken list of ~20 rows is technically the
+ * same information, but nobody scans it — which is what made the old ⓘ feel
+ * like fine print rather than help.
+ *
+ * Sizing: the panel is wide (max-w-4xl) and the cards flow into TWO columns from
+ * `sm` up. At one narrow column the video reference ran past the viewport and
+ * the Keyboard section — the half people actually come here for — sat below the
+ * fold. Two columns put the whole thing on screen at once, which is also why the
+ * body text is a full 14px rather than the 12px used elsewhere in the chrome:
+ * this is a document you read, not a toolbar you glance at.
+ *
+ * Sections are cut by INPUT, not by surface: Mouse, Toolbar, Keyboard. "Where
+ * does this apply" then lives on the row that needs it (`ControlEntry.where`)
+ * instead of forcing a whole card per surface.
+ *
+ * Accent use is intentionally cheap to theme: everything tinted reads
+ * `var(--editor-accent)` directly (section and toolbar icons, row dots, the
+ * header wash), so a host theme re-skins the modal without touching this file.
  */
 export default function ControlsInfoModal({ title, sections, onClose }: ControlsInfoModalProps) {
   useEffect(() => {
@@ -42,7 +114,7 @@ export default function ControlsInfoModal({ title, sections, onClose }: Controls
       onClick={onClose}
     >
       <div
-        className="relative mx-4 flex max-h-[80vh] w-full max-w-md flex-col overflow-hidden rounded-lg border shadow-2xl"
+        className="relative mx-4 flex max-h-[86vh] w-full max-w-4xl flex-col overflow-hidden rounded-xl border shadow-2xl"
         style={{
           background: 'var(--editor-surface)',
           borderColor: 'var(--editor-border)',
@@ -51,86 +123,204 @@ export default function ControlsInfoModal({ title, sections, onClose }: Controls
         onClick={(e) => e.stopPropagation()}
       >
         <div
-          className="flex shrink-0 items-center justify-between border-b px-4 py-3"
+          className="relative shrink-0 overflow-hidden border-b px-6 py-5"
           style={{ borderColor: 'var(--editor-border)' }}
         >
-          <h2 className="text-sm font-semibold">{title}</h2>
-          <button
-            type="button"
-            onClick={onClose}
-            aria-label="Close"
-            className="cursor-pointer opacity-60 transition-opacity hover:opacity-100"
-          >
-            <X size={16} />
-          </button>
+          {/* Accent wash. A gradient that fades the accent var straight to
+              `transparent` needs no color-mix support, so it renders the same
+              everywhere; the opacity keeps it a tint rather than a colour. */}
+          <div
+            aria-hidden
+            className="pointer-events-none absolute inset-0 opacity-[0.13]"
+            style={{
+              background:
+                'linear-gradient(105deg, var(--editor-accent), transparent 62%)',
+            }}
+          />
+          <div className="relative flex items-start justify-between gap-4">
+            <div className="flex items-center gap-3">
+              <span
+                className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border bg-[var(--editor-text)]/[0.06]"
+                style={{ borderColor: 'var(--editor-border)' }}
+              >
+                <Command size={17} style={{ color: 'var(--editor-accent)' }} />
+              </span>
+              <div>
+                <h2 className="text-lg font-semibold leading-tight tracking-tight">{title}</h2>
+                <p className="mt-0.5 text-[13px] opacity-55">
+                  Everything this editor responds to.
+                </p>
+              </div>
+            </div>
+            <button
+              type="button"
+              onClick={onClose}
+              aria-label="Close"
+              className="-mr-1 -mt-1 shrink-0 cursor-pointer rounded-md p-1.5 opacity-55 transition-all hover:bg-[var(--editor-text)]/10 hover:opacity-100"
+            >
+              <X size={18} />
+            </button>
+          </div>
         </div>
 
-        <div className="space-y-4 overflow-y-auto px-4 py-3">
-          {sections.map((section) => (
-            <div key={section.heading}>
-              <p className="mb-1.5 text-[11px] font-semibold uppercase tracking-wide opacity-50">
-                {section.heading}
-              </p>
-              <ul className="space-y-1.5">
-                {section.entries.map((entry, i) => (
-                  <li key={i} className="flex items-start justify-between gap-3 text-xs">
-                    <span className="opacity-80">{entry.label}</span>
-                    {entry.keys && entry.keys.length > 0 && (
-                      <span className="flex shrink-0 items-center gap-1">
-                        {entry.keys.map((k, j) => (
-                          <kbd
-                            key={j}
-                            className="rounded border px-1.5 py-0.5 font-mono text-[10px] leading-none"
-                            style={{ borderColor: 'var(--editor-border)', background: 'var(--editor-bg)' }}
+        <div className="overflow-y-auto px-6 py-5">
+          {/* CSS columns rather than a grid: the sections are wildly uneven (a
+              few gestures vs eight shortcuts) and columns balance the total
+              height instead of pairing them row-by-row and leaving a tall
+              gap. */}
+          <div className="gap-5 sm:columns-2">
+            {sections.map((section) => {
+              const Icon = SECTION_ICONS[section.heading] ?? SlidersHorizontal
+              return (
+                <section
+                  key={section.heading}
+                  className="mb-5 break-inside-avoid rounded-lg border last:mb-0"
+                  style={{ borderColor: 'var(--editor-border)', background: 'var(--editor-bg)' }}
+                >
+                  <div
+                    className="flex items-center gap-2.5 border-b px-3.5 py-3"
+                    style={{ borderColor: 'var(--editor-border)' }}
+                  >
+                    <span
+                      className="flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-[var(--editor-text)]/[0.06]"
+                    >
+                      <Icon size={14} style={{ color: 'var(--editor-accent)' }} />
+                    </span>
+                    <h3 className="text-xs font-semibold uppercase tracking-[0.14em] opacity-70">
+                      {section.heading}
+                    </h3>
+                  </div>
+                  <ul className="p-2">
+                    {section.entries.map((entry, i) => (
+                      <li
+                        key={i}
+                        className="flex items-center justify-between gap-3 rounded-md px-2 py-2 text-sm transition-colors hover:bg-[var(--editor-text)]/[0.06]"
+                      >
+                        <span className="flex items-start gap-2.5 opacity-90">
+                          {/* A toolbar row shows that button's real glyph;
+                              everything else gets a dot. Both occupy the same
+                              width, so the labels stay on one left edge to scan
+                              down, and the chip-less gesture rows don't read as
+                              orphaned text beside the shortcut rows. */}
+                          {entry.icon ? (
+                            <entry.icon
+                              size={14}
+                              aria-hidden
+                              className="mt-[1px] shrink-0"
+                              style={{ color: 'var(--editor-accent)' }}
+                            />
+                          ) : (
+                            <span
+                              aria-hidden
+                              className="mt-[7px] h-1 w-1 shrink-0 rounded-full opacity-50"
+                              style={{ background: 'var(--editor-accent)' }}
+                            />
+                          )}
+                          {entry.label}
+                        </span>
+                        {entry.where && (
+                          /* Deliberately NOT a <kbd>: a surface name is not
+                             something you press. Pill, not keycap. */
+                          <span
+                            className="shrink-0 rounded-full border px-1.5 py-[3px] text-[10px] uppercase opacity-55"
+                            style={{
+                              borderColor: 'var(--editor-border)',
+                              background: 'var(--editor-surface)',
+                            }}
                           >
-                            {k}
-                          </kbd>
-                        ))}
-                      </span>
-                    )}
-                  </li>
-                ))}
-              </ul>
-            </div>
-          ))}
+                            {entry.where}
+                          </span>
+                        )}
+                        {entry.keys && entry.keys.length > 0 && (
+                          <span className="flex shrink-0 items-center gap-1">
+                            {entry.keys.map((k, j) => (
+                              <kbd
+                                key={j}
+                                className="rounded-md border border-b-2 px-2 py-1 font-mono text-[11px] leading-none shadow-sm"
+                                style={{
+                                  borderColor: 'var(--editor-border)',
+                                  background: 'var(--editor-surface)',
+                                }}
+                              >
+                                {k}
+                              </kbd>
+                            ))}
+                          </span>
+                        )}
+                      </li>
+                    ))}
+                  </ul>
+                </section>
+              )
+            })}
+          </div>
+        </div>
+
+        <div
+          className="flex shrink-0 items-center justify-end gap-2 border-t px-6 py-3 text-[13px]"
+          style={{ borderColor: 'var(--editor-border)' }}
+        >
+          <kbd
+            className="rounded-md border border-b-2 px-2 py-1 font-mono text-[11px] leading-none shadow-sm"
+            style={{ borderColor: 'var(--editor-border)', background: 'var(--editor-bg)' }}
+          >
+            Esc
+          </kbd>
+          <span className="opacity-55">to close</span>
         </div>
       </div>
     </div>
   )
 }
 
-/** Controls reference for the video/timeline editor. Sourced from VideoEditor's
- *  key handler (S / ⌘Z), the track-controls toolbar, and PreviewPlayer's
- *  on-canvas transform (drag / corner-drag / scroll / rotate). */
+/** Controls reference for the video/timeline editor. Sourced from the shared
+ *  keymap (`video/keymap.ts`, mounted by VideoEditor's ReviewSurface and
+ *  Timeline), the track-controls toolbar, and PreviewPlayer's on-canvas
+ *  transform (drag / corner-drag / scroll / rotate). */
 export const VIDEO_CONTROLS: ControlSection[] = [
   {
-    heading: 'Preview',
-    entries: [
-      { label: 'Drag to move the selected clip or overlay' },
-      { label: 'Corner-drag or scroll to scale it' },
-      { label: 'Drag the rotate handle to turn an overlay' },
-    ],
-  },
-  {
-    heading: 'Timeline',
+    // One card for every mouse gesture, Preview and Timeline alike. They were
+    // two cards, which read as two subjects when they are one — "what the
+    // mouse does" — and split seven short rows across a column break. The
+    // per-row `where` pill carries the surface the heading used to.
+    heading: 'Mouse',
     entries: [
-      { label: 'Drag a clip to reposition it' },
-      { label: "Drag a clip's edge to trim it" },
-      { label: 'Select a clip, then click ⓘ to inspect it' },
+      { icon: Move, where: 'Preview', label: 'Drag to move the selected clip or overlay' },
+      { icon: Maximize2, where: 'Preview', label: 'Corner-drag or scroll to scale it' },
+      { icon: RotateCw, where: 'Preview', label: 'Drag the rotate handle to turn an overlay' },
+      { icon: MoveHorizontal, where: 'Timeline', label: 'Drag a clip to reposition it' },
+      { icon: ChevronsLeftRight, where: 'Timeline', label: "Drag a clip's edge to trim it" },
+      { icon: MousePointerClick, where: 'Timeline', label: 'Double-click a clip to inspect it' },
+      { icon: Timer, where: 'Timeline', label: 'Click the time readout to go to a timecode' },
     ],
   },
   {
+    // Icons here are the very buttons in the track-controls bar, in the order
+    // they sit there. Keep the two in step: a row whose glyph no longer matches
+    // its button is worse than no glyph at all.
     heading: 'Toolbar',
     entries: [
-      { label: 'Ripple: edits close the gap instead of leaving it' },
-      { label: 'Crop source: non-destructively crop the selected clip' },
+      { icon: SeparatorVertical, label: 'Preview axis: hover the timeline to preview that frame' },
+      { icon: Magnet, label: 'Ripple: edits close the gap instead of leaving it' },
+      { icon: Crop, label: 'Crop source: non-destructively crop the selected clip (greyed out until you select one)' },
     ],
   },
   {
     heading: 'Keyboard',
     entries: [
       { keys: ['S'], label: 'Split at the playhead' },
+      { keys: ['⌘/Ctrl', 'A'], label: 'Toggle the preview axis' },
+      { keys: ['⇧', 'Delete'], label: 'Ripple-delete the selection' },
       { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+      { keys: ['⌘/Ctrl', '⇧', 'Z'], label: 'Redo' },
+      { keys: ['⌘/Ctrl', 'C'], label: 'Copy the selection' },
+      { keys: ['⌘/Ctrl', 'V'], label: 'Paste at the playhead' },
+      { keys: ['⌘/Ctrl', 'D'], label: 'Duplicate the selection in place' },
+      { keys: ['⌘/Ctrl', '⌥/Alt', 'V'], label: 'Paste attributes onto the selection' },
+      { keys: ['⌘/Ctrl', 'K'], label: 'Command palette' },
+      { keys: ['J', 'K', 'L'], label: 'Shuttle backward / stop / forward' },
+      { keys: ['←', '→'], label: 'Step one frame (⇧ for ten frames)' },
+      { keys: ['F'], label: 'Toggle fullscreen preview' },
     ],
   },
 ]
@@ -141,9 +331,9 @@ export const CAROUSEL_CONTROLS: ControlSection[] = [
   {
     heading: 'Canvas',
     entries: [
-      { label: 'Drag an element to reposition it' },
-      { label: 'Resize or rotate it via the handles' },
-      { label: 'Double-click text to edit it' },
+      { icon: Move, label: 'Drag an element to reposition it' },
+      { icon: Maximize2, label: 'Resize or rotate it via the handles' },
+      { icon: MousePointerClick, label: 'Double-click text to edit it' },
     ],
   },
   {

package/src/__tests__/ControlsInfoModal.test.tsx

@@ -59,4 +59,47 @@ describe('ControlsInfoModal', () => {
     expect(VIDEO_CONTROLS.length).toBeGreaterThan(0)
     expect(CAROUSEL_CONTROLS.length).toBeGreaterThan(0)
   })
+
+  it('renders an entry\'s `where` as a pill, not as a key chip', () => {
+    render(
+      <ControlsInfoModal
+        title="Editor controls"
+        sections={[{ heading: 'Mouse', entries: [{ where: 'Timeline', label: 'Drag a clip' }] }]}
+        onClose={vi.fn()}
+      />,
+    )
+    // A surface name is not something you press, so it must not be a <kbd> —
+    // that element is the modal's promise that a row names a keystroke.
+    expect(screen.getByText('Timeline').tagName).not.toBe('KBD')
+  })
+
+  it('keeps every mouse gesture in ONE section, tagged by surface', () => {
+    // Preview and Timeline were two cards; merging them into "Mouse" moved the
+    // surface onto each row. Re-splitting is fine, but silently dropping the
+    // `where` tags would lose which surface a gesture applies to entirely.
+    const mouse = VIDEO_CONTROLS.filter((s) => s.entries.some((e) => e.where))
+    expect(mouse).toHaveLength(1)
+    expect(mouse[0].heading).toBe('Mouse')
+    expect(mouse[0].entries.every((e) => e.where && e.icon)).toBe(true)
+    expect(new Set(mouse[0].entries.map((e) => e.where))).toEqual(new Set(['Preview', 'Timeline']))
+  })
+
+  it('gives every toolbar row the glyph of its button', () => {
+    const toolbar = VIDEO_CONTROLS.find((s) => s.heading === 'Toolbar')!
+    expect(toolbar.entries.every((e) => e.icon)).toBe(true)
+  })
+
+  it('lists the clipboard and fullscreen shortcuts under Keyboard', () => {
+    const keyboard = VIDEO_CONTROLS.find((s) => s.heading === 'Keyboard')!
+    const labels = keyboard.entries.map((e) => e.label)
+    expect(labels).toEqual(
+      expect.arrayContaining([
+        'Copy the selection',
+        'Paste at the playhead',
+        'Duplicate the selection in place',
+        'Paste attributes onto the selection',
+        'Toggle fullscreen preview',
+      ]),
+    )
+  })
 })

package/src/__tests__/adapter.test.ts

@@ -7,7 +7,7 @@ import type {
   MediaScope,
 } from '../types'
 import type { Project, ImageElement } from '../types'
-import { defaultMontajTheme, applyTheme } from '../theme'
+import { defaultMontajTheme, lightMontajTheme, applyTheme, isLightTheme } from '../theme'
 
 // ── (a) A fake adapter literal must satisfy the EditorAdapter interface ──────
 // This test is purely structural: it type-checks at build time. The runtime
@@ -197,4 +197,62 @@ describe('applyTheme', () => {
       defaultMontajTheme.spacing[2],
     )
   })
+
+  it('writes editor CSS vars onto a div for lightMontajTheme', () => {
+    const el = document.createElement('div')
+    applyTheme(el, lightMontajTheme)
+
+    expect(el.style.getPropertyValue('--editor-bg')).toBe(
+      lightMontajTheme.colors.background,
+    )
+    expect(el.style.getPropertyValue('--editor-surface')).toBe(
+      lightMontajTheme.colors.surface,
+    )
+    expect(el.style.getPropertyValue('--editor-accent')).toBe(
+      lightMontajTheme.colors.accent,
+    )
+    expect(el.style.getPropertyValue('--editor-accent-foreground')).toBe(
+      lightMontajTheme.colors.accentForeground,
+    )
+    expect(el.style.getPropertyValue('--editor-text')).toBe(
+      lightMontajTheme.colors.text,
+    )
+    expect(el.style.getPropertyValue('--editor-border')).toBe(
+      lightMontajTheme.colors.border,
+    )
+    expect(el.style.getPropertyValue('--editor-selection')).toBe(
+      lightMontajTheme.colors.selection,
+    )
+    expect(el.style.getPropertyValue('--editor-font-sans')).toBe(
+      lightMontajTheme.fonts.sans,
+    )
+
+    expect(lightMontajTheme.colors.background).not.toBe(defaultMontajTheme.colors.background)
+    expect(lightMontajTheme.colors.text).not.toBe(defaultMontajTheme.colors.text)
+  })
+})
+
+// ── (d) isLightTheme classifies a theme by its background's luminance ───────
+describe('isLightTheme', () => {
+  it('returns true for lightMontajTheme', () => {
+    expect(isLightTheme(lightMontajTheme)).toBe(true)
+  })
+
+  it('returns false for defaultMontajTheme', () => {
+    expect(isLightTheme(defaultMontajTheme)).toBe(false)
+  })
+
+  it('falls back to false for an unparseable background color', () => {
+    expect(
+      isLightTheme({
+        ...defaultMontajTheme,
+        colors: { ...defaultMontajTheme.colors, background: 'not-a-color' },
+      }),
+    ).toBe(false)
+  })
+
+  it('parses 3-digit hex backgrounds', () => {
+    expect(isLightTheme({ ...defaultMontajTheme, colors: { ...defaultMontajTheme.colors, background: '#fff' } })).toBe(true)
+    expect(isLightTheme({ ...defaultMontajTheme, colors: { ...defaultMontajTheme.colors, background: '#000' } })).toBe(false)
+  })
 })

package/src/__tests__/schema-assignability.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest'
+import { EASING_NAMES } from '@bycrux/timeline-core'
+import type {
+  Keyframe as CoreKeyframe,
+  KeyframeTrack as CoreKeyframeTrack,
+  EasingName as CoreEasingName,
+  KeyframeProp as CoreKeyframeProp,
+} from '@bycrux/timeline-core'
+import type {
+  Keyframe as EditorKeyframe,
+  KeyframeTrack as EditorKeyframeTrack,
+  EasingName as EditorEasingName,
+  KeyframeProp as EditorKeyframeProp,
+} from '../schema'
+
+// schema.ts re-declares Keyframe/KeyframeTrack/EasingName/KeyframeProp
+// instead of importing them — schema.ts is deliberately import-free (see its
+// module header). The duplication is intentional but must stay structurally
+// identical to the canonical definitions in @bycrux/timeline-core
+// (src/curves.js, declared in its index.d.ts), which is where geometryAt/
+// sampleTrack actually interpret these shapes for BOTH the preview and the
+// render. This file is a compile-time tripwire: if either side's shape
+// drifts, one of the assignments below fails to type-check — and thus fails
+// `tsc`/the vitest build — long before it becomes a silent runtime bug.
+//
+// Mirrors montaj_assets/ui/src/lib/types/__tests__/schema-assignability.test.ts,
+// extended to prove MUTUAL assignability (both directions) since neither side
+// here is a superset of the other — they're meant to be the same shape twice.
+function mutuallyAssignable<A, B>(_forward: (a: A) => B, _backward: (b: B) => A) {}
+
+describe('editor schema Keyframe types <-> @bycrux/timeline-core Keyframe types', () => {
+  it('EasingName is mutually assignable', () => {
+    mutuallyAssignable<CoreEasingName, EditorEasingName>((a) => a, (b) => b)
+  })
+
+  it('KeyframeProp is mutually assignable', () => {
+    mutuallyAssignable<CoreKeyframeProp, EditorKeyframeProp>((a) => a, (b) => b)
+  })
+
+  it('Keyframe is mutually assignable', () => {
+    mutuallyAssignable<CoreKeyframe, EditorKeyframe>((a) => a, (b) => b)
+
+    const sample: EditorKeyframe = { t: 0, value: 1, easing: 'ease-in-out' }
+    const asCore: CoreKeyframe = sample
+    const asEditor: EditorKeyframe = asCore
+    expect(asEditor.t).toBe(0)
+  })
+
+  it('KeyframeTrack is mutually assignable', () => {
+    mutuallyAssignable<CoreKeyframeTrack, EditorKeyframeTrack>((a) => a, (b) => b)
+
+    const sample: EditorKeyframeTrack = { prop: 'scale', points: [{ t: 0, value: 1 }] }
+    const asCore: CoreKeyframeTrack = sample
+    const asEditor: EditorKeyframeTrack = asCore
+    expect(asEditor.prop).toBe('scale')
+  })
+})
+
+// The assignability checks above are type-level ONLY, so they fire under
+// `tsc --noEmit` but NOT under `vitest run` — vitest's transform strips types
+// without checking them, and the editor's `npm test` is `vitest run` with no
+// typecheck step. That leaves the likeliest real drift unguarded in the command
+// people actually run: someone adds an easing preset to timeline-core's
+// curves.js and forgets schema.ts's `EasingName` union.
+//
+// This block closes that at runtime. EASING_NAMES is a real exported VALUE, so
+// comparing it against the union's members catches the drift under vitest, and
+// the exhaustiveness map makes the reverse direction (a member added to the
+// union but not to the list below) a compile error.
+describe('EasingName stays in sync with timeline-core at RUNTIME', () => {
+  // Adding a member to EditorEasingName without adding it here fails to compile:
+  // the Record must cover every member of the union exactly.
+  const EXHAUSTIVE: Record<EditorEasingName, true> = {
+    linear: true,
+    ease: true,
+    'ease-in': true,
+    'ease-out': true,
+    'ease-in-out': true,
+    hold: true,
+  }
+  const DECLARED = Object.keys(EXHAUSTIVE) as EditorEasingName[]
+
+  it('schema.ts declares exactly the easings timeline-core implements', () => {
+    expect([...DECLARED].sort()).toEqual([...EASING_NAMES].sort())
+  })
+
+  it('every name timeline-core exports is assignable to the editor union', () => {
+    for (const name of EASING_NAMES) {
+      const asEditor: EditorEasingName = name
+      expect(DECLARED).toContain(asEditor)
+    }
+  })
+})

package/src/__tests__/schema.test.ts

@@ -1,10 +1,12 @@
 import { describe, it, expect } from 'vitest'
 import type {
+  CaptionSegment,
   EditorProject,
   ImageElement,
   OverlayElement,
   Slide,
 } from '../schema'
+import { laneOf } from '../video/captionLanes'
 
 // Compile-time assignability helper: if the argument doesn't satisfy T,
 // this fails to type-check (and thus fails `tsc`/build, which vitest runs through).
@@ -101,4 +103,17 @@ describe('editor schema', () => {
     expectAssignable<Slide>(slide)
     expect(slide.elements).toHaveLength(2)
   })
+
+  it('round-trips CaptionSegment.lane both present and absent', () => {
+    const withLane: CaptionSegment = { text: 'hi', start: 0, end: 1, lane: 2 }
+    const withoutLane: CaptionSegment = { text: 'hi', start: 0, end: 1 }
+    expectAssignable<CaptionSegment>(withLane)
+    expectAssignable<CaptionSegment>(withoutLane)
+    expect(withLane.lane).toBe(2)
+    expect(withoutLane.lane).toBeUndefined()
+    // Absent lane reads as lane 0 through the module every consumer goes
+    // through — not just `undefined` left for each caller to default itself.
+    expect(laneOf(withoutLane)).toBe(0)
+    expect(laneOf(withLane)).toBe(2)
+  })
 })