@bycrux/editor 1.1.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "lint": "eslint src"
   },
   "dependencies": {
-    "@bycrux/timeline-core": "^0.2.0",
+    "@bycrux/timeline-core": "^0.2.1",
     "class-variance-authority": "^0.7",
     "clsx": "^2",
     "lucide-react": "^0.400",

package/src/ControlsInfoModal.tsx

@@ -309,6 +309,7 @@ export const VIDEO_CONTROLS: ControlSection[] = [
     heading: 'Keyboard',
     entries: [
       { keys: ['S'], label: 'Split at the playhead' },
+      { keys: ['M'], label: 'Drop a marker at the playhead (or the preview axis)' },
       { keys: ['⌘/Ctrl', 'A'], label: 'Toggle the preview axis' },
       { keys: ['⇧', 'Delete'], label: 'Ripple-delete the selection' },
       { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },

package/src/engine/__tests__/scheduler.test.ts

@@ -483,7 +483,27 @@ describe('transportEndFor', () => {
     expect(transportEndFor(p)).toBe(8)
   })
 
-  it('uses max(overlayEnd, captionEnd) for a canvas project — audio EXCLUDED', () => {
+  it('counts track 0 in a canvas project — an overlay-only single track is not a zero-length transport', () => {
+    // The shape an animations-workflow project actually has: ONE track, holding
+    // nothing but overlays, and no captions. Reading the ceiling off
+    // `tracks.slice(1)` made this 0, so play/space started the transport and
+    // stopped it in the same tick — the picture never moved.
+    const p = project([overlay('o1', 0, 5), overlay('o2', 5, 12)])
+    expect(p.tracks).toHaveLength(1)
+    expect(transportEndFor(p)).toBe(12)
+  })
+
+  it('counts track 0 images in a canvas project, even past the overlay tracks', () => {
+    // Same defect, other content kind: a background image outlasting every
+    // overlay used to be invisible to the ceiling.
+    const p = project(
+      [{ id: 'img', type: 'image', src: '/a.png', start: 0, end: 9 }],
+      [overlay('o', 0, 4)],
+    )
+    expect(transportEndFor(p)).toBe(9)
+  })
+
+  it('uses max(visualEnd, captionEnd) for a canvas project — audio EXCLUDED', () => {
     // The legacy canvas rAF's ceiling is `canvasMaxEndRef`, which really does
     // leave audio out. Faithful, not unified.
     const p = project([{ id: 'img', type: 'image', src: '/a.png', start: 0, end: 3 }], [
@@ -494,6 +514,41 @@ describe('transportEndFor', () => {
     })
     expect(transportEndFor(p)).toBe(6)
   })
+
+  it('falls back to the audio end when NOTHING visual sets a ceiling', () => {
+    // Audio-only timeline: the shape an animations-workflow project has while
+    // the music is wired but no overlay exists yet. The ceiling was 0, so the
+    // transport started and stopped on the same tick and play did nothing at
+    // all — with no feedback saying why.
+    const p = project([], [], {
+      audio: { tracks: [{ id: 'm', src: '/m.wav', start: 0, end: 15 }] },
+    })
+    expect(transportEndFor(p)).toBe(15)
+  })
+
+  it('resolves an audio-only track carrying no explicit end to its natural length', () => {
+    const p = project([], [], {
+      // `AudioTrack` types `start`/`end` as required, but project.json files on
+      // disk routinely omit them — `resolveAudioWindow` exists precisely to cope
+      // at runtime. That gap between the type and the real shape is what this
+      // test pins, so the under-specified track is the point, not a shortcut.
+      // @ts-expect-error — deliberately the under-specified on-disk shape
+      audio: { tracks: [{ id: 'm', src: '/m.wav', sourceDuration: 15 }] },
+    })
+    expect(transportEndFor(p)).toBe(15)
+  })
+
+  it('skips muted tracks in the audio-only fallback', () => {
+    const p = project([], [], {
+      audio: {
+        tracks: [
+          { id: 'a', src: '/a.wav', start: 0, end: 30, muted: true },
+          { id: 'b', src: '/b.wav', start: 0, end: 15 },
+        ],
+      },
+    })
+    expect(transportEndFor(p)).toBe(15)
+  })
 })
 
 describe('engineSrcFor — proxy-only playback is structural', () => {

package/src/engine/scheduler.ts

@@ -83,7 +83,7 @@ import type { ItemCrossfade, Scene, SourceWindow } from '@bycrux/timeline-core'
 import type { EditorProject as Project, VisualItem, VisualTrack } from '../schema'
 import type { ClipTimebase, MasterClock } from './audio-clock'
 import type { FrameServer } from './frame-server'
-import { effectiveItemAudio, enabledTrackItems, enabledTracks, withEnabledItemTracks } from '../video/timeline/timeline-model'
+import { audioEnd, effectiveItemAudio, enabledTrackItems, enabledTracks, withEnabledItemTracks } from '../video/timeline/timeline-model'
 
 // ── Tuning constants ────────────────────────────────────────────────────────
 
@@ -517,9 +517,9 @@ function withTrackAudio(track: VisualTrack | undefined, item: VisualItem): Visua
  * Two formulas, because the legacy hook has two and they legitimately differ:
  *
  *   - **Canvas projects** (no track-0 video) run the `isCanvasProject` rAF,
- *     whose ceiling is `canvasMaxEndRef` = `max(overlayEnd, captionEnd)`. Note
+ *     whose ceiling is `canvasMaxEndRef` = `max(visualEnd, captionEnd)`. Note
  *     what is NOT in it: audio. A canvas project whose music outlasts its
- *     overlays stops at the overlays today.
+ *     visuals stops at the visuals today.
  *   - **Video projects** use `projectEnd` = `max(videoEnd, overlayEnd,
  *     audioEnd)` — captions excluded, audio included — which timeline-core
  *     already ports verbatim (including its two documented faithfulness warts:
@@ -527,18 +527,36 @@ function withTrackAudio(track: VisualTrack | undefined, item: VisualItem): Visua
  *
  * Unifying them would be a behavior change in one mode or the other, so both
  * are kept and the divergence is named here rather than smoothed over.
+ *
+ * `visualEnd` spans EVERY enabled track, track 0 included — it is deliberately
+ * not the video path's `overlayEnd` (`tracks.slice(1)`). In canvas mode track 0
+ * is a content track like any other: it carries the background images, and an
+ * agent-authored project can put its overlays there too (an animations-workflow
+ * project is frequently ONE track holding nothing but overlays). Skipping it
+ * made the ceiling collapse to 0 for exactly those projects, so play/space
+ * started the transport and stopped it in the same tick. `OverlayItemsLayer`
+ * has always drawn track 0 in canvas mode (`isCanvasProject ? enabledTrackItems
+ * : overlayTracks`); this is the transport agreeing with what is on screen.
  */
 export function transportEndFor(project: Project): number {
   const clips = track0VideoItems(project)
   if (clips.length > 0) return timelineProjectEnd(withEnabledItemTracks(project))
-  const overlayEnd = enabledTrackItems(project).slice(1)
+  const visualEnd = enabledTrackItems(project)
     .flat()
     .reduce((m, i) => Math.max(m, i?.end ?? 0), 0)
   const captionEnd = (project.captions?.segments ?? []).reduce(
     (m: number, s) => Math.max(m, s.end ?? 0),
     0,
   )
-  return Math.max(overlayEnd, captionEnd)
+  const ceiling = Math.max(visualEnd, captionEnd)
+  if (ceiling > 0) return ceiling
+  // Nothing visual sets a ceiling: an audio-only timeline. Returning 0 here
+  // started the transport and stopped it in the same tick, so play did nothing
+  // at all. Audio is otherwise deliberately kept out of the ceiling (the
+  // canvas/video divergence over the audio tail, above) — this is the last
+  // resort that only fires when there is no visual content to measure.
+  // Mirrored in `canvasMaxEndRef` (video/preview/useVideoPlayback.ts).
+  return audioEnd(project)
 }
 
 /**

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
   CarouselElement,
   Slide,
   EditorProject,
+  Marker,
 } from './schema'
 
 // ── Contracts (adapter, theme, render, media, component props) ────────────────
@@ -103,6 +104,9 @@ export {
 // "land where you dropped it, without stomping existing footage".
 export { placeDroppedClip, resolveDropTrackIndex } from './video/timeline/placement'
 export type { DroppedClipPlacement, PlacedClipResult } from './video/timeline/placement'
+// Marker model — pure mutations over `project.markers` (see markers.ts's file
+// header for the "same reference when unchanged" contract they all share).
+export { addMarker, moveMarker, renameMarker, removeMarkers, nextMarkerLabel } from './video/timeline/markers'
 
 // ── Image tone (HDR image color mapping) ─────────────────────────────────────
 // The picker component is exported so hosts using `onProvideImageTone` can
@@ -165,6 +169,38 @@ export {
   FontSizePicker,
 } from './text/FontPicker'
 export type { FontOption } from './text/FontPicker'
+// Two independent Google Fonts base-URL setters, one per loader — see each
+// file's own header for why there are two. `setFontsBaseUrl` (from
+// `lib/google-fonts.ts`) covers the broader surface: captions, overlays and
+// the timeline/overlay preview. `setPickerFontsBaseUrl` (renamed at this
+// export boundary only — the source file still calls it `setFontsBaseUrl`,
+// same as the other loader) covers just the font-family picker's own
+// preview list. A host must call BOTH to eliminate Google Fonts egress
+// entirely; calling only one still leaves the other loader fetching from
+// fonts.googleapis.com.
+//
+// Both take the same two arguments: `(url, families)`. `families` is the list
+// of families the stylesheet at `url` declares — the host reads its own
+// `families.json` (or equivalent) ONCE at app init and passes the result to
+// both setters. It is deliberately not fetched inside the loaders: they are
+// synchronous and called from effects, and a pending fetch would leave them
+// unable to decide the partition at the moment they have to act on it.
+//
+// **Passing a url with no families means NOTHING is treated as vendored** —
+// the vendored stylesheet is not linked and every family is fetched from
+// Google. That is the safe direction: glyphs stay correct and preview and
+// render still agree, at the cost of the egress the base exists to remove.
+// Assuming the stylesheet covers everything would instead preview unvendored
+// families as a system fallback while the renderer — reading its own manifest
+// off local disk — got them right, and nothing on screen would say so.
+//
+// `vendoredFamiliesDigest()` returns a short fingerprint of the family list in
+// force. The renderers log the same digest for the manifest they read; two
+// different strings mean the two sides are partitioning against different
+// vendored sets, and captions will differ between editing and export.
+export { setFontsBaseUrl, vendoredFamiliesDigest } from './lib/google-fonts'
+export { setFontsBaseUrl as setPickerFontsBaseUrl } from './text/FontPicker'
+export { fontFamilyKey, familiesDigest, partitionFontSpecs, vendoredKeySet } from './lib/font-families'
 export { InlineTextEditor } from './text/InlineTextEditor'
 export type { InlineTextEditorProps } from './text/InlineTextEditor'
 export {

package/src/lib/__tests__/font-faces.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { ensureGoogleFontsLoaded, setFontsBaseUrl } from '../google-fonts'
+import { requiredFaces, specFacesAvailable, vendoredFaceIndex } from '../font-families'
+
+// THE FACE-LEVEL PARTITION (L1).
+//
+// The vendored set is family + STYLE + WEIGHT, not family. `fonts.css` carries
+// only the faces the vendoring pass actually received — every face is
+// `font-style: normal`, and the weights are only the ones it asked for. A
+// family-level partition therefore gets two shapes silently wrong:
+//
+//   Playfair+Display:ital@1  — family vendored, no italic face exists, so the
+//                              browser synthesises an oblique from the upright.
+//   Inter:wght@300           — family vendored, no 300 face exists, so the
+//                              browser synthesises a light weight from the 400.
+//
+// Neither produces a failed request or a console error, and both change what
+// the user sees. `skills/write-overlay/SKILL.md` uses the first as its own
+// documented example.
+//
+// Every assertion here has a twin on the render side
+// (`montaj_assets/render/test/fonts-fallthrough.test.mjs`). The two sides MUST
+// partition identically — a caption laid out in one face while editing and
+// another at export is the Syne bug that case study documents.
+
+const N = (weight: number) => ({ style: 'normal', weight })
+const I = (weight: number) => ({ style: 'italic', weight })
+
+describe('requiredFaces: a spec resolves to the faces it asks Google for', () => {
+  for (const [spec, want] of [
+    // No axis list — Google serves the family default, which is normal 400.
+    ['Anton', [N(400)]],
+    ['Playfair Display', [N(400)]],
+    ['Inter:wght@400;700', [N(400), N(700)]],
+    ['Inter:wght@300', [N(300)]],
+    ['Playfair+Display:ital@1', [I(400)]],
+    ['Playfair+Display:ital@0', [N(400)]],
+    // The axes are named in one list and their values in another, positionally.
+    ['Playfair+Display:ital,wght@1,700', [I(700)]],
+    ['Playfair+Display:ital,wght@0,400;1,700', [N(400), I(700)]],
+    ['Baloo+2:wght@400;500;600;700;800', [N(400), N(500), N(600), N(700), N(800)]],
+  ] as [string, ReturnType<typeof N>[]][]) {
+    it(`${spec} → ${JSON.stringify(want)}`, () => {
+      expect(requiredFaces(spec)).toEqual(want)
+    })
+  }
+
+  // `null` means "I cannot parse this confidently" and the caller must fall
+  // through. Fetching a font we happen to have costs one request; silently
+  // dropping one we lack costs the author a wrong face in a finished export.
+  for (const spec of [
+    'Inter:',                  // a colon with no axis list
+    'Inter:wght',              // an axis with no '@'
+    'Inter:wght@',             // an '@' with no value
+    'Inter:wght@400;',         // a trailing ';' leaves an empty tuple
+    'Inter:wght@100..900',     // a variable RANGE is not a face
+    'Inter:ital@0..1',
+    'Inter:opsz@14',           // an axis we do not model
+    'Inter:slnt@-10',
+    'Inter:GRAD@150',
+    'Inter:wght,opsz@400,14',  // one modelled axis, one not
+    'Inter:wght,wght@400,700', // a duplicated axis
+    'Inter:ital,wght@1',       // arity mismatch: two axes, one value
+    'Inter:wght@400@700',      // two '@'
+    'Inter:ital@2',            // ital is 0 or 1, nothing else
+    'Inter:wght@0',            // out of range
+    'Inter:wght@abc',
+    'Inter:@400',              // an empty axis name
+  ]) {
+    it(`${spec} → null, so the caller falls through`, () => {
+      expect(requiredFaces(spec)).toBeNull()
+    })
+  }
+})
+
+describe('vendoredFaceIndex: `faces` and `requested` together say what is available', () => {
+  it('merges both maps — a weight in either one counts as available', () => {
+    // Bebas Neue publishes no 700, so we asked for it and got only the 400.
+    // Falling through would fetch a stylesheet that omits it identically.
+    const index = vendoredFaceIndex(
+      { 'Bebas Neue': { normal: [400] } },
+      { 'Bebas Neue': { normal: [400, 700] } },
+    )!
+    expect(specFacesAvailable('Bebas+Neue:wght@400;700', index)).toBe(true)
+    expect(specFacesAvailable('Bebas+Neue:wght@500', index)).toBe(false)
+  })
+
+  it('distinguishes NO face information from face information covering nothing', () => {
+    // Nothing supplied at all: the partition has nothing to refine against and
+    // must stay at family level, which the loader signals with `undefined`.
+    expect(vendoredFaceIndex(undefined, undefined)).toBeUndefined()
+    // An empty map IS information: it says nothing is available.
+    const empty = vendoredFaceIndex({}, undefined)
+    expect(empty).toBeInstanceOf(Map)
+    expect(specFacesAvailable('Inter', empty!)).toBe(false)
+  })
+
+  it('normalises family keys the way the family list does', () => {
+    const index = vendoredFaceIndex({ 'Open+Sans': { normal: [400] } })!
+    expect(specFacesAvailable('Open+Sans', index)).toBe(true)
+    expect(specFacesAvailable('OPEN SANS', index)).toBe(true)
+  })
+
+  it('skips malformed entries rather than throwing inside a font load', () => {
+    const index = vendoredFaceIndex({
+      Inter: { normal: [400, 'x' as unknown as number, null as unknown as number] },
+      Bad: null as unknown as { normal: number[] },
+      Worse: { normal: 'nope' as unknown as number[] },
+    })!
+    expect(specFacesAvailable('Inter', index)).toBe(true)
+    expect(specFacesAvailable('Bad', index)).toBe(false)
+    expect(specFacesAvailable('Worse', index)).toBe(false)
+  })
+
+  it('a family with no index entry is not covered', () => {
+    const index = vendoredFaceIndex({ Inter: { normal: [400] } })!
+    expect(specFacesAvailable('Anton', index)).toBe(false)
+  })
+
+  it('a spec it cannot parse is not covered, however complete the index', () => {
+    const index = vendoredFaceIndex({ Inter: { normal: [100, 200, 300, 400, 700, 900] } })!
+    expect(specFacesAvailable('Inter:wght@100..900', index)).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Through the loader
+// ---------------------------------------------------------------------------
+
+function injectedHrefs(): string[] {
+  return Array.from(document.head.querySelectorAll('link[rel="stylesheet"]')).map(
+    (l) => (l as HTMLLinkElement).href,
+  )
+}
+
+// The injected-URL Set is module state that outlives a single test, so every
+// base and every unvendored family below must be unique or a later test is
+// served a suppressed <link> and passes for the wrong reason.
+const B = (name: string) => `https://example.com/faces/${name}`
+
+const REAL = {
+  faces: {
+    'Playfair Display': { normal: [400, 700] },
+    Inter: { normal: [400, 700] },
+    'Bebas Neue': { normal: [400] },
+  },
+  requested: {
+    'Playfair Display': { normal: [400, 700] },
+    Inter: { normal: [400, 700] },
+    'Bebas Neue': { normal: [400, 700] },
+  },
+}
+const FAMILIES = ['Playfair Display', 'Inter', 'Bebas Neue']
+
+beforeEach(() => {
+  document.head.querySelectorAll('link[rel="stylesheet"]').forEach((l) => l.remove())
+  vi.spyOn(console, 'info').mockImplementation(() => {})
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+})
+afterEach(() => {
+  setFontsBaseUrl(undefined)
+  vi.restoreAllMocks()
+})
+
+describe('ensureGoogleFontsLoaded: the face refinement', () => {
+  for (const [spec, vendored, why] of [
+    ['Playfair+Display:ital@1', false, 'no italic face is vendored'],
+    ['Playfair+Display:ital,wght@1,700', false, 'italic 700 is not on disk either'],
+    ['Playfair+Display:ital@0', true, 'ital@0 is normal 400, which IS on disk'],
+    ['Inter:wght@300', false, '300 was never vendored'],
+    ['Inter:wght@400;700', true, 'both weights are on disk'],
+    ['Bebas+Neue:wght@400;700', true, 'Google publishes no 700, so asking again cannot help'],
+    ['Bebas+Neue:wght@500', false, '500 was neither vendored nor asked for'],
+  ] as [string, boolean, string][]) {
+    it(`${spec} is ${vendored ? 'served locally' : 'fetched from Google'} — ${why}`, () => {
+      const base = B(spec.replace(/\W/g, ''))
+      setFontsBaseUrl(base, FAMILIES, REAL)
+      ensureGoogleFontsLoaded([spec])
+      const hrefs = injectedHrefs()
+      if (vendored) {
+        expect(hrefs).toEqual([`${base}/fonts.css`])
+      } else {
+        expect(hrefs).toEqual([`https://fonts.googleapis.com/css2?family=${spec}&display=swap`])
+      }
+    })
+  }
+
+  it('a partially vendored spec falls through WHOLE, exactly as the author wrote it', () => {
+    // Splitting would mean synthesising a new spec string, and a spec is the
+    // author's — ours to honour or pass on untouched, never to rewrite.
+    const base = B('partial')
+    setFontsBaseUrl(base, FAMILIES, REAL)
+    ensureGoogleFontsLoaded(['Inter:wght@400;300'])
+    expect(injectedHrefs()).toEqual([
+      'https://fonts.googleapis.com/css2?family=Inter:wght@400;300&display=swap',
+    ])
+  })
+
+  it('a MIX puts each spec on exactly one side, by face and not by family', () => {
+    const base = B('mix')
+    setFontsBaseUrl(base, FAMILIES, REAL)
+    // Same family on both sides: the 700 is vendored, the italic is not.
+    //
+    // The italic spec here is spelled `ital,wght@1,400` rather than `ital@1`
+    // — the same FACE, a different URL. `__injectedFontUrls` dedupes on the
+    // full URL and is module state outliving a single test, so reusing the
+    // spelling an earlier case already injected would suppress this <link>
+    // and the assertion would fail for a reason that has nothing to do with
+    // the partition.
+    ensureGoogleFontsLoaded(['Playfair+Display:wght@700', 'Playfair+Display:ital,wght@1,400'])
+    const hrefs = injectedHrefs()
+    expect(hrefs).toEqual([
+      `${base}/fonts.css`,
+      'https://fonts.googleapis.com/css2?family=Playfair+Display:ital,wght@1,400&display=swap',
+    ])
+  })
+
+  it('omitting face data leaves the partition at family level', () => {
+    // A manifest vendored before the refinement existed carries no face
+    // information. That is a real shape, and it must degrade to the previous
+    // behaviour rather than treating every face as missing.
+    const base = B('nofaces')
+    setFontsBaseUrl(base, FAMILIES)
+    ensureGoogleFontsLoaded(['Playfair+Display:ital@1'])
+    expect(injectedHrefs()).toEqual([`${base}/fonts.css`])
+  })
+
+  it('faces cannot promote a family the list does not declare', () => {
+    const base = B('narrowing')
+    setFontsBaseUrl(base, ['Inter'], { faces: { Inter: { normal: [400] }, Zilch: { normal: [400] } } })
+    ensureGoogleFontsLoaded(['Zilch'])
+    expect(injectedHrefs()).toEqual(['https://fonts.googleapis.com/css2?family=Zilch&display=swap'])
+  })
+
+  it('names the fallen-through spec in the warning, and not the vendored one', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const base = B('logged')
+    setFontsBaseUrl(base, FAMILIES, REAL)
+    ensureGoogleFontsLoaded(['Inter:wght@400', 'Quire:ital@1'])
+    expect(warn).toHaveBeenCalledOnce()
+    expect(warn.mock.calls[0][0]).toContain('Quire:ital@1')
+    expect(warn.mock.calls[0][0]).not.toContain('Inter')
+  })
+})