auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/canvas-fit.ts

@@ -0,0 +1,116 @@
+/**
+ * A film's canvas changing shape: the canvas takes the new shape with its short side kept (a
+ * 1920×1080 film made 3:4 is 1080×1440), and each picture is fitted to it on its own. A picture's place is read as
+ * two shares: its size as a share of the size that fits it whole in the canvas (1: it meets the canvas's edges
+ * one way), and its center as a share of the canvas from the canvas's center. Both are kept, so a full-frame video
+ * stays full-frame in any shape, a portrait photo on another clip fits by its own height, a title halfway up stays
+ * halfway up, and shapes picked one after another never shrink anything.
+ *
+ * A video or still without a box is the canvas whatever its shape (its picture fitted inside by CSS): it is left
+ * without one. A page is written its box. A page that sets no size of its own is laid out at the canvas's: it is
+ * given the old canvas as its `size`, so it is scaled as a video is rather than laid out again in the new shape.
+ */
+import { pictureRect } from '../../../../src/film-doc.mjs';
+import { customFilmFrame, frameRatioOf, type FilmFrameId } from './film-frame.ts';
+import { filmSrcKind, type FilmBox, type FilmSrcKind } from './film.ts';
+
+type Size = { w: number; h: number };
+
+/** Even sizes: H.264 samples chroma in 2×2 blocks and refuses odd dimensions. At most 8192 a side. */
+const even = (n: number) => Math.max(2, Math.min(8192, Math.round(n / 2) * 2));
+
+/** A canvas's sides, in px, and how far from square it may be (as a ratio typed for an export: 1:4 to 4:1). */
+export const CANVAS_SIDE = { min: 16, max: 8192 } as const;
+const CANVAS_STRETCH = 4;
+
+/**
+ * A canvas `side` (its width or height) of `n` px, the other side kept: whole even px within CANVAS_SIDE, and no more
+ * than 4 times the other side or less than a quarter of it.
+ */
+export function canvasSide(n: number, other: number): number {
+  const lo = Math.max(CANVAS_SIDE.min, other / CANVAS_STRETCH);
+  const hi = Math.min(CANVAS_SIDE.max, other * CANVAS_STRETCH);
+  return Math.min(Math.floor(hi / 2) * 2, Math.max(Math.ceil(lo / 2) * 2, Math.round(n / 2) * 2));
+}
+
+/** The canvas in another shape, its short side kept (a typed size is taken as it is elsewhere). */
+export function canvasFor(stage: Size, frame: FilmFrameId): Size {
+  const ratio = frame === 'native' ? null : frameRatioOf(frame);
+  if (ratio == null) return { w: even(stage.w), h: even(stage.h) };
+  const short = Math.min(stage.w, stage.h);
+  return ratio >= 1 ? { w: even(short * ratio), h: even(short) } : { w: even(short), h: even(short / ratio) };
+}
+
+/**
+ * A picture clip as the fit needs it: its kind, its picture's own size (unknown: the old canvas), its box if any, and
+ * for a page, whether it sets no size of its own (`reflows`) and the `size` its clip gives it.
+ */
+export interface CanvasClip { id: string; kind: FilmSrcKind | null; own?: Size | null; box?: FilmBox | null; reflows?: boolean; size?: Size | null }
+
+/** A clip on the new canvas: its box, and for a page laid out at the old canvas, that size. */
+export interface CanvasFit { id: string; box: FilmBox; size?: Size }
+
+/** The size of a picture shaped `ratio` (width / height) that fits whole in `canvas`, meeting its edges one way. */
+const fitted = (ratio: number, canvas: Size): Size => (
+  canvas.w / canvas.h > ratio ? { w: canvas.h * ratio, h: canvas.h } : { w: canvas.w, h: canvas.w / ratio }
+);
+
+/**
+ * Each picture clip's box on the new canvas `to` (the old one is `from`), each clip fitted on its own: the same
+ * share of its fitted size, its center the same share of the canvas from the canvas's center. Sounds, and videos and
+ * stills without a box (they are the canvas), are left out.
+ */
+export function fitToCanvas(clips: readonly CanvasClip[], from: Size, to: Size): CanvasFit[] {
+  const out: CanvasFit[] = [];
+  for (const clip of clips) {
+    if (!clip.kind || clip.kind === 'sound') continue;
+    if (clip.kind !== 'page' && !clip.box) continue;
+    const own = clip.own && clip.own.w > 0 && clip.own.h > 0 ? clip.own : from;
+    const at = pictureRect(clip.kind, own, from, clip.box ?? undefined);
+    if (!(at.w > 0 && at.h > 0)) continue;
+    /* the box's shape; its picture's own when they differ only by rounding (a box written in whole px), so shapes
+       picked one after another do not drift */
+    const ownRatio = own.w / own.h;
+    const ratio = Math.abs(at.w / at.h / ownRatio - 1) < 0.01 ? ownRatio : at.w / at.h;
+    const share = at.w / fitted(ratio, from).w;
+    const fit = fitted(ratio, to);
+    const w = fit.w * share, h = fit.h * share;
+    const cx = to.w / 2 + ((at.x + at.w / 2 - from.w / 2) / from.w) * to.w;
+    const cy = to.h / 2 + ((at.y + at.h / 2 - from.h / 2) / from.h) * to.h;
+    /* whole px; an edge within 2 px of the canvas's meets it, so rounding never leaves a hairline of black */
+    const near = (v: number, edge: number) => (Math.abs(v - edge) <= 2 ? edge : Math.round(v));
+    const left = near(cx - w / 2, 0), top = near(cy - h / 2, 0);
+    const box: FilmBox = { x: left, y: top, w: near(cx + w / 2, to.w) - left, h: near(cy + h / 2, to.h) - top };
+    if (at.r) box.r = at.r;
+    out.push(clip.kind === 'page' && clip.reflows && !clip.size ? { id: clip.id, box, size: { w: from.w, h: from.h } } : { id: clip.id, box });
+  }
+  return out;
+}
+
+/** Whether the stage has this ratio: its width within 2 px of it (a size made from a ratio is rounded to even px). */
+export const shaped = (stage: Size, ratio: number) => Math.abs(stage.w - stage.h * ratio) <= 2;
+
+/**
+ * The film's first picture's own size, which "Original" fits the canvas to: the earliest clip on the film with a
+ * picture whose size the preview knows (`spans`). A page that sets no size of its own is passed over: it is laid out at
+ * the canvas's size, so it has no shape of its own, and a film of such pages would always read as "Original".
+ */
+export function firstPictureSize(
+  clips: readonly { id: string; src: string; at?: number | null; sound?: unknown }[],
+  spans: readonly { id: string; w?: number; h?: number; reflows?: true }[],
+): Size | null {
+  const sized = new Map(spans.filter((span) => span.w && span.h && !span.reflows).map((span) => [span.id, { w: span.w!, h: span.h! }]));
+  const first = clips
+    .filter((clip) => !clip.sound && filmSrcKind(clip.src) !== 'sound' && sized.has(clip.id))
+    .sort((a, b) => (a.at ?? 0) - (b.at ?? 0))[0];
+  return first ? sized.get(first.id) ?? null : null;
+}
+
+/**
+ * The canvas's "Original" shape: the first picture's own (`original`), when there is one and it is between 1:4 and
+ * 4:1; and whether the stage has it now.
+ */
+export function originalShape(stage: Size, original: Size | null): { frame: FilmFrameId | null; current: boolean } {
+  const frame = original ? customFilmFrame(original.w, original.h) : null;
+  return { frame, current: Boolean(frame && original && shaped(stage, original.w / original.h)) };
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/chat-marks.ts

@@ -0,0 +1,114 @@
+/**
+ * What the app's chat points at in Studio (lib/host.ts StudioCommand `highlight` and `draft-refs`): the thing a pill
+ * hovered there stands for, lit while it is hovered, and the things the message being written references, numbered
+ * as the agent will read them ([1], [2], …). Pure, so `node --test` runs it (chat-marks.test.ts).
+ */
+import type { StageBox, StudioRef } from './host';
+import type { FilmRange } from './studio-refs';
+
+/** A clip as the timeline has it: its film.html id and its place (`film.html#<track>.<clip>`). */
+export interface ClipKey { clipId?: string | null; loc?: string | null }
+
+/** A box on the picture at its moment of the film (ms). */
+export interface BoxAt { timeMs: number; box: StageBox }
+
+/** A box is on the picture shown when it was pointed at within this much of the playhead (about a frame). */
+export const BOX_AT_MS = 20;
+
+/** The same clip: by film.html id when both have one (a clip keeps its id when tracks move), else by place. */
+export function sameClip(a: ClipKey, b: ClipKey): boolean {
+  if (a.clipId && b.clipId) return a.clipId === b.clipId;
+  return Boolean(a.loc && a.loc === b.loc);
+}
+
+/**
+ * What a hovered pill lights: a clip's block (a layer's too: the clip it is in), a box on the picture (a layer where
+ * it was measured, a region), a span on the ruler (a range, a subtitle line, a moment as a span of none), a track's
+ * head, a file of the media pane.
+ */
+export interface ChatPoint {
+  clip: ClipKey | null;
+  box: BoxAt | null;
+  span: FilmRange | null;
+  track: number | null;
+  file: string | null;
+}
+
+const ms = (s: number) => Math.round(s * 1000);
+const NOTHING: ChatPoint = { clip: null, box: null, span: null, track: null, file: null };
+
+export function chatPointOf(ref: StudioRef | null | undefined): ChatPoint | null {
+  if (!ref) return null;
+  switch (ref.kind) {
+    case 'clip': return ref.id || ref.loc ? { ...NOTHING, clip: { clipId: ref.id, loc: ref.loc } } : null;
+    case 'layer': return {
+      ...NOTHING,
+      clip: ref.clipId ? { clipId: ref.clipId } : null,
+      box: ref.box && typeof ref.time === 'number' ? { timeMs: ms(ref.time), box: ref.box } : null,
+    };
+    case 'region': return { ...NOTHING, box: { timeMs: ms(ref.time), box: ref.box } };
+    case 'time': return { ...NOTHING, span: { startMs: ms(ref.time), endMs: ms(ref.time) } };
+    case 'range':
+    case 'subtitle': return { ...NOTHING, span: { startMs: ms(Math.min(ref.start, ref.end)), endMs: ms(Math.max(ref.start, ref.end)) } };
+    case 'track': return { ...NOTHING, track: ref.track };
+    case 'file': return { ...NOTHING, file: ref.path };
+  }
+  return null;
+}
+
+/** The box, when the picture shows the moment it was pointed at; null otherwise. */
+export function boxNow(at: BoxAt | null | undefined, nowMs: number): StageBox | null {
+  return at && Math.abs(at.timeMs - nowMs) <= BOX_AT_MS ? at.box : null;
+}
+
+/**
+ * The message being written, as marks: its clips' blocks and its layers' and regions' boxes, each with its number
+ * (its place among the references, from 1). Other kinds take their number and show nowhere.
+ */
+export interface DraftMarks {
+  clips: ReadonlyArray<{ n: number; clip: ClipKey }>;
+  boxes: ReadonlyArray<{ n: number } & BoxAt>;
+}
+
+export const NO_DRAFT: DraftMarks = { clips: [], boxes: [] };
+
+export function draftMarksOf(refs: readonly StudioRef[]): DraftMarks {
+  if (!refs.length) return NO_DRAFT;
+  const clips: Array<{ n: number; clip: ClipKey }> = [];
+  const boxes: Array<{ n: number } & BoxAt> = [];
+  refs.forEach((ref, i) => {
+    const n = i + 1;
+    if (ref.kind === 'clip' && (ref.id || ref.loc)) clips.push({ n, clip: { clipId: ref.id, loc: ref.loc } });
+    else if (ref.kind === 'layer' && ref.box && typeof ref.time === 'number') boxes.push({ n, timeMs: ms(ref.time), box: ref.box });
+    else if (ref.kind === 'region') boxes.push({ n, timeMs: ms(ref.time), box: ref.box });
+  });
+  return { clips, boxes };
+}
+
+/** A block's numbers in the message being written (none: it is not referenced). */
+export function draftNumbersOf(marks: DraftMarks, clip: ClipKey): number[] {
+  return marks.clips.filter((m) => sameClip(m.clip, clip)).map((m) => m.n);
+}
+
+/** The boxes of the message being written that are on the picture shown now. */
+export function draftBoxesAt(marks: DraftMarks, nowMs: number): Array<{ n: number; box: StageBox }> {
+  return marks.boxes.filter((m) => boxNow(m, nowMs)).map(({ n, box }) => ({ n, box }));
+}
+
+/** What the picture draws for the chat: the hovered pill's clip (by place) or box, and the numbered boxes. */
+export interface PictureMarks {
+  clipLoc: string | null;
+  box: StageBox | null;
+  numbered: ReadonlyArray<{ n: number; box: StageBox }>;
+}
+
+const sameBox = (a: StageBox | null | undefined, b: StageBox | null | undefined) =>
+  a === b || Boolean(a && b && a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h);
+
+/** By content: the picture is memoized, and these are made anew as the playhead moves. */
+export function samePictureMarks(a: PictureMarks | null | undefined, b: PictureMarks | null | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b) return !(a?.clipLoc || a?.box || a?.numbered.length || b?.clipLoc || b?.box || b?.numbered.length);
+  return a.clipLoc === b.clipLoc && sameBox(a.box, b.box)
+    && a.numbered.length === b.numbered.length && a.numbered.every((m, i) => m.n === b.numbered[i]!.n && sameBox(m.box, b.numbered[i]!.box));
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/clip-attrs.ts

@@ -0,0 +1,102 @@
+/**
+ * A clip's attributes copied onto other clips (copy / paste attributes, ⌘⇧C / ⌘⇧V): the groups its paste dialog
+ * offers, all ticked unless unticked —
+ *   · `place`: where the picture sits and how big it is, turned (`box`);
+ *   · `blend`: how it shows through (`opacity`, `mix-blend-mode` in its style; the rest of its style stays);
+ *   · `volume`: how loud its sound is;
+ *   · `fade`: its fade in and fade out, shortened to fit a shorter clip.
+ * A picture's groups go onto pictures, the sound's onto clips with sound; what a clip cannot take is left out.
+ *
+ * Pure: the editor reads the copy from film.html and writes the edits it gives back (lib/film-clip-edits).
+ */
+import { declared, withDeclarations } from './clip-look.ts';
+import { fadeMsOf } from './clip-fade.ts';
+import { filmSrcKind } from './film.ts';
+import type { ClipEdit } from './film-clip-edits';
+
+export type AttrGroup = 'place' | 'blend' | 'volume' | 'fade';
+
+type Box = { x: number; y: number; w?: number; h?: number; r?: number };
+/** What a clip's attributes are read from: its row in film.html (lib/film's FilmClip, api's Clip). */
+export interface AttrClip {
+  id: string;
+  src: string;
+  sound?: boolean;
+  box?: Box;
+  style?: string;
+  volume?: number;
+  overrides?: readonly unknown[];
+}
+export const ATTR_GROUPS: readonly AttrGroup[] = ['place', 'blend', 'volume', 'fade'];
+
+export interface CopiedAttrs {
+  /** The clip copied from, for saying so. */
+  from: string;
+  picture: boolean;
+  sound: boolean;
+  place: Box | null;
+  blend: { opacity: string | null; mode: string | null };
+  volume: number;
+  /** Seconds. */
+  fade: [number, number];
+}
+
+/** What a clip shows and what it plays: a picture (a page, a video, a still), a sound (a video, a sound). */
+function sides(clip: Pick<AttrClip, 'src' | 'sound'>): { picture: boolean; sound: boolean } {
+  const kind = clip.sound ? 'sound' : filmSrcKind(clip.src);
+  return { picture: kind !== 'sound', sound: kind === 'video' || kind === 'sound' };
+}
+
+/** The attributes of a clip, as film.html has them. */
+export function attrsOf(clip: AttrClip): CopiedAttrs {
+  const style = clip.style ?? '';
+  const [fadeIn, fadeOut] = fadeMsOf(clip);
+  return {
+    from: clip.id,
+    ...sides(clip),
+    place: clip.box ? { ...clip.box } : null,
+    blend: { opacity: declared(style, 'opacity') ?? null, mode: declared(style, 'mix-blend-mode') ?? null },
+    volume: clip.volume ?? 1,
+    fade: [fadeIn / 1000, fadeOut / 1000],
+  };
+}
+
+/** The groups a copy has anything for: a picture's for a picture, the sound's for a sound. */
+export function groupsOf(attrs: CopiedAttrs): AttrGroup[] {
+  return ATTR_GROUPS.filter((g) => (g === 'place' || g === 'blend' ? attrs.picture : g === 'volume' ? attrs.sound : true));
+}
+
+export interface AttrTarget {
+  loc: string;
+  clip: AttrClip;
+  /** Its length on the film, seconds: a fade longer than the clip is shortened. */
+  lengthS: number;
+}
+
+/** The fade a clip `lengthS` long can take: the copy's, both ends shortened alike when together they are longer. */
+function fitted([fadeIn, fadeOut]: [number, number], lengthS: number): [number, number] {
+  const total = fadeIn + fadeOut;
+  if (total <= lengthS || total <= 0) return [fadeIn, fadeOut];
+  const k = lengthS / total;
+  return [Math.floor(fadeIn * k * 1000) / 1000, Math.floor(fadeOut * k * 1000) / 1000];
+}
+
+/** The edits that put the ticked groups of a copy onto these clips (not onto the clip copied from). */
+export function pasteAttrs(attrs: CopiedAttrs, groups: ReadonlySet<AttrGroup>, targets: readonly AttrTarget[]): ClipEdit[] {
+  const out: ClipEdit[] = [];
+  for (const { loc, clip, lengthS } of targets) {
+    if (clip.id === attrs.from) continue;
+    const can = sides(clip);
+    if (can.picture && attrs.picture && groups.has('place')) out.push({ loc, prop: 'box', value: attrs.place ? { ...attrs.place } : null });
+    if (can.picture && attrs.picture && groups.has('blend')) {
+      const style = withDeclarations(clip.style ?? '', { opacity: attrs.blend.opacity, 'mix-blend-mode': attrs.blend.mode });
+      if (style !== (clip.style ?? '')) out.push({ loc, prop: 'style', value: style || null });
+    }
+    if (can.sound && attrs.sound && groups.has('volume')) out.push({ loc, prop: 'volume', value: attrs.volume });
+    if (groups.has('fade')) {
+      const [fadeIn, fadeOut] = fitted(attrs.fade, lengthS);
+      out.push({ loc, prop: 'fade', value: fadeIn > 0 || fadeOut > 0 ? [fadeIn, fadeOut] : null });
+    }
+  }
+  return out;
+}

package/skill/assets/upstream/packages/openfilm/studio/ui/src/lib/clip-fade.ts

@@ -0,0 +1,70 @@
+/**
+ * A clip's fades on the timeline: the handles at its top corners, dragged inward, and the ramp drawn over it.
+ *
+ * A fade is kept in film.html as the clip's own entry of its `overrides` (`{ "fade": [in, out] }`, seconds; see
+ * SPEC §1): the timeline writes it with the `fade` prop (studio/server/ops.mjs), one edit for the clip and the clips
+ * linked to it, so a picture and the sound taken off it fade together.
+ *
+ * Pure: the timeline draws a drag's fade from here while the hand is still on the handle, and writes it on release.
+ */
+import type { Op } from '../api.ts';
+import { clipFade } from '../../../../src/film-doc.mjs';
+
+/** In and out, in ms. */
+export type FadeMs = readonly [number, number];
+export type FadeEdge = 'in' | 'out';
+
+/** A clip's fades in ms (`[0, 0]` without any), from its film.html row. */
+export function fadeMsOf(clip: { overrides?: readonly unknown[] } | null | undefined): FadeMs {
+  const fade = clipFade(clip);
+  return fade ? [Math.round(fade[0] * 1000), Math.round(fade[1] * 1000)] : [0, 0];
+}
+
+/**
+ * The fade a handle dragged to `pointerMs` sets on a clip over `[startMs, endMs)`: from its start (in) or back from
+ * its end (out), on the frame grid (`frameMs` a frame), never past where the other fade begins, never below 0.
+ */
+export function fadeFromPointer(edge: FadeEdge, pointerMs: number, clip: { startMs: number; endMs: number }, other: number, frameMs: number): number {
+  const room = Math.max(0, clip.endMs - clip.startMs - other);
+  const raw = edge === 'in' ? pointerMs - clip.startMs : clip.endMs - pointerMs;
+  const snapped = frameMs > 0 ? Math.round(raw / frameMs) * frameMs : raw;
+  /* a whole frame less when the frame nearest does not fit, so it stays on the grid */
+  const fit = snapped > room && frameMs > 0 ? Math.floor(room / frameMs) * frameMs : snapped;
+  /* to the microsecond: frames of 33.33… ms gather float noise */
+  return Math.round(Math.max(0, Math.min(room, fit)) * 1000) / 1000;
+}
+
+/** Where a fade's handle sits in a clip `widthPx` wide: px from its left edge. */
+export function fadeHandleX(edge: FadeEdge, fadeMs: number, widthPx: number, pxPerMs: number): number {
+  const px = Math.min(widthPx, fadeMs * pxPerMs);
+  return edge === 'in' ? px : widthPx - px;
+}
+
+/** A clip as a fade edit sees it. */
+export interface FadeClip { id: string; startMs: number; endMs: number; fade: FadeMs; locked?: boolean }
+
+/**
+ * One fade set on a clip and on the clips going with it (`with`: those linked to it, unless ⌥), each that has the same
+ * edge within `tolMs` of the clip's: a picture and its sound end together, so they fade together. Fitted to each one's
+ * length; none on a locked track. The edits film.html takes, by clip id.
+ */
+export function fadeEdits(edge: FadeEdge, ms: number, clip: FadeClip, others: readonly FadeClip[] = [], tolMs = 1): { clip: string; prop: 'fade'; value: [number, number] }[] {
+  const at = (c: FadeClip) => (edge === 'in' ? c.startMs : c.endMs);
+  const all = [clip, ...others.filter((c) => c.id !== clip.id && Math.abs(at(c) - at(clip)) <= tolMs)];
+  return all.filter((c) => !c.locked).flatMap((c) => {
+    const len = c.endMs - c.startMs;
+    const other = edge === 'in' ? c.fade[1] : c.fade[0];
+    const own = Math.max(0, Math.min(ms, len - other));
+    const next: [number, number] = edge === 'in' ? [own, c.fade[1]] : [c.fade[0], own];
+    if (Math.round(next[0]) === Math.round(c.fade[0]) && Math.round(next[1]) === Math.round(c.fade[1])) return [];
+    return [{ clip: c.id, prop: 'fade' as const, value: [secs(next[0]), secs(next[1])] }];
+  });
+}
+
+/** The edit of fades as an operation (one write, one undo step); null when nothing changes. */
+export function fadeOp(edits: ReturnType<typeof fadeEdits>): Op | null {
+  return edits.length ? { op: 'props', edits } : null;
+}
+
+/** ms → seconds to the millisecond, as film.html keeps them. */
+export const secs = (ms: number): number => Math.round(ms) / 1000;