@algorisys/tinyfly 0.125.0 → 0.127.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -42,9 +42,9 @@ function shineStops(progress, baseColor, options = {}) {
42
42
  return stops;
43
43
  }
44
44
  function pathLength(points) {
45
- let length = 0;
46
- for (let i = 1; i < points.length; i++) length += Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
47
- return length;
45
+ let length2 = 0;
46
+ for (let i = 1; i < points.length; i++) length2 += Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
47
+ return length2;
48
48
  }
49
49
  function partialPath(points, progress) {
50
50
  const t = Math.min(1, Math.max(0, progress));
@@ -55,14 +55,14 @@ function partialPath(points, progress) {
55
55
  for (let i = 1; i < points.length; i++) {
56
56
  const a = points[i - 1];
57
57
  const b = points[i];
58
- const length = Math.hypot(b.x - a.x, b.y - a.y);
59
- if (length >= remaining) {
60
- const f = length === 0 ? 0 : remaining / length;
58
+ const length2 = Math.hypot(b.x - a.x, b.y - a.y);
59
+ if (length2 >= remaining) {
60
+ const f = length2 === 0 ? 0 : remaining / length2;
61
61
  result.push({ x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f });
62
62
  return result;
63
63
  }
64
64
  result.push(b);
65
- remaining -= length;
65
+ remaining -= length2;
66
66
  }
67
67
  return result;
68
68
  }
@@ -168,13 +168,13 @@ function sketchPen(ctx, style, time) {
168
168
  let along = 0;
169
169
  for (let i = 1; i < ends.length; i++) {
170
170
  const cubic = bowedCubic(ends[i - 1], ends[i], roughness, bows[i - 1]);
171
- const length = lengths[i - 1];
172
- if (along + length <= drawn) {
171
+ const length2 = lengths[i - 1];
172
+ if (along + length2 <= drawn) {
173
173
  ctx.bezierCurveTo(cubic[1].x, cubic[1].y, cubic[2].x, cubic[2].y, cubic[3].x, cubic[3].y);
174
- along += length;
174
+ along += length2;
175
175
  continue;
176
176
  }
177
- const part = splitCubic(cubic, length === 0 ? 1 : (drawn - along) / length);
177
+ const part = splitCubic(cubic, length2 === 0 ? 1 : (drawn - along) / length2);
178
178
  ctx.bezierCurveTo(part[1].x, part[1].y, part[2].x, part[2].y, part[3].x, part[3].y);
179
179
  break;
180
180
  }
@@ -238,10 +238,10 @@ function sketchPen(ctx, style, time) {
238
238
  function bowedCubic(a, b, roughness, offsets) {
239
239
  const dx = b.x - a.x;
240
240
  const dy = b.y - a.y;
241
- const length = Math.hypot(dx, dy) || 1;
242
- const bow = roughness * Math.min(1.5, Math.max(0.3, length / 80));
243
- const nx = -dy / length;
244
- const ny = dx / length;
241
+ const length2 = Math.hypot(dx, dy) || 1;
242
+ const bow = roughness * Math.min(1.5, Math.max(0.3, length2 / 80));
243
+ const nx = -dy / length2;
244
+ const ny = dx / length2;
245
245
  return [
246
246
  a,
247
247
  { x: a.x + dx / 3 + nx * offsets[0] * bow, y: a.y + dy / 3 + ny * offsets[0] * bow },
@@ -741,11 +741,11 @@ class CanvasAdapter {
741
741
  const angleRad = (gradient.angle - 90) * (Math.PI / 180);
742
742
  const centerX = bounds.x + bounds.width / 2;
743
743
  const centerY = bounds.y + bounds.height / 2;
744
- const length = Math.max(bounds.width, bounds.height);
745
- const x1 = centerX - Math.cos(angleRad) * length / 2;
746
- const y1 = centerY - Math.sin(angleRad) * length / 2;
747
- const x2 = centerX + Math.cos(angleRad) * length / 2;
748
- const y2 = centerY + Math.sin(angleRad) * length / 2;
744
+ const length2 = Math.max(bounds.width, bounds.height);
745
+ const x1 = centerX - Math.cos(angleRad) * length2 / 2;
746
+ const y1 = centerY - Math.sin(angleRad) * length2 / 2;
747
+ const x2 = centerX + Math.cos(angleRad) * length2 / 2;
748
+ const y2 = centerY + Math.sin(angleRad) * length2 / 2;
749
749
  const canvasGradient = ctx.createLinearGradient(x1, y1, x2, y2);
750
750
  for (const stop of gradient.stops) {
751
751
  canvasGradient.addColorStop(stop.offset, stop.color);
@@ -931,12 +931,12 @@ class CanvasAdapter {
931
931
  { x: target.x, y: target.y },
932
932
  { x: target.x2, y: target.y2 }
933
933
  ];
934
- const length = Math.hypot(target.x2 - target.x, target.y2 - target.y);
934
+ const length2 = Math.hypot(target.x2 - target.x, target.y2 - target.y);
935
935
  return this.renderOutlined(
936
936
  ctx,
937
937
  target,
938
938
  void 0,
939
- (progress, pen) => drawOutline(ctx, [{ kind: "line", points, length }], progress, pen)
939
+ (progress, pen) => drawOutline(ctx, [{ kind: "line", points, length: length2 }], progress, pen)
940
940
  );
941
941
  }
942
942
  ctx.beginPath();
@@ -1139,17 +1139,17 @@ function brightPass(data, threshold) {
1139
1139
  function boxPass(source, width, height, radius, horizontal) {
1140
1140
  const out = new Float32Array(source.length);
1141
1141
  const lines = horizontal ? height : width;
1142
- const length = horizontal ? width : height;
1142
+ const length2 = horizontal ? width : height;
1143
1143
  const at = (line, i) => (horizontal ? line * width + i : i * width + line) * 3;
1144
1144
  const span = radius * 2 + 1;
1145
1145
  for (let line = 0; line < lines; line++) {
1146
1146
  for (let c = 0; c < 3; c++) {
1147
1147
  let sum = 0;
1148
- for (let i = -radius; i <= radius; i++) sum += source[at(line, Math.min(length - 1, Math.max(0, i))) + c];
1149
- for (let i = 0; i < length; i++) {
1148
+ for (let i = -radius; i <= radius; i++) sum += source[at(line, Math.min(length2 - 1, Math.max(0, i))) + c];
1149
+ for (let i = 0; i < length2; i++) {
1150
1150
  out[at(line, i) + c] = sum / span;
1151
1151
  const leaving = source[at(line, Math.max(0, i - radius)) + c];
1152
- const entering = source[at(line, Math.min(length - 1, i + radius + 1)) + c];
1152
+ const entering = source[at(line, Math.min(length2 - 1, i + radius + 1)) + c];
1153
1153
  sum += entering - leaving;
1154
1154
  }
1155
1155
  }
@@ -1677,32 +1677,32 @@ function encodeWav(samples, sampleRate) {
1677
1677
  return bytes;
1678
1678
  }
1679
1679
  function loopSamples(samples, options) {
1680
- const length = Math.max(1, Math.round(options.length));
1681
- const crossfade = Math.min(length, Math.max(0, Math.round(options.crossfade ?? length * 0.02)));
1682
- if (samples.length === 0) return new Float32Array(length);
1683
- const needed = length + crossfade;
1680
+ const length2 = Math.max(1, Math.round(options.length));
1681
+ const crossfade = Math.min(length2, Math.max(0, Math.round(options.crossfade ?? length2 * 0.02)));
1682
+ if (samples.length === 0) return new Float32Array(length2);
1683
+ const needed = length2 + crossfade;
1684
1684
  let source = samples;
1685
1685
  if (source.length < needed) {
1686
1686
  const tiled = new Float32Array(needed);
1687
1687
  for (let i = 0; i < needed; i++) tiled[i] = samples[i % samples.length];
1688
1688
  source = tiled;
1689
1689
  }
1690
- const out = new Float32Array(length);
1691
- for (let i = 0; i < length; i++) out[i] = source[i];
1690
+ const out = new Float32Array(length2);
1691
+ for (let i = 0; i < length2; i++) out[i] = source[i];
1692
1692
  for (let i = 0; i < crossfade; i++) {
1693
1693
  const t = (i + 1) / (crossfade + 1);
1694
1694
  const head = Math.sin(t * Math.PI / 2);
1695
1695
  const tail = Math.cos(t * Math.PI / 2);
1696
- out[i] = source[i] * head + source[length + i] * tail;
1696
+ out[i] = source[i] * head + source[length2 + i] * tail;
1697
1697
  }
1698
- const fadeIn = Math.min(length, Math.max(0, Math.round(options.fadeIn ?? 0)));
1698
+ const fadeIn = Math.min(length2, Math.max(0, Math.round(options.fadeIn ?? 0)));
1699
1699
  for (let i = 0; i < fadeIn; i++) out[i] *= i / fadeIn;
1700
- const fadeOut = Math.min(length, Math.max(0, Math.round(options.fadeOut ?? 0)));
1701
- for (let i = 0; i < fadeOut; i++) out[length - 1 - i] *= i / fadeOut;
1700
+ const fadeOut = Math.min(length2, Math.max(0, Math.round(options.fadeOut ?? 0)));
1701
+ for (let i = 0; i < fadeOut; i++) out[length2 - 1 - i] *= i / fadeOut;
1702
1702
  return out;
1703
1703
  }
1704
- function layOut(layer, sampleRate, length) {
1705
- const out = new Float32Array(length);
1704
+ function layOut(layer, sampleRate, length2) {
1705
+ const out = new Float32Array(length2);
1706
1706
  const gain = layer.gain ?? 1;
1707
1707
  const source = layer.samples;
1708
1708
  if (source.length === 0) return out;
@@ -1711,10 +1711,10 @@ function layOut(layer, sampleRate, length) {
1711
1711
  const fadeOut = Math.round((layer.fadeOut ?? 0) * sampleRate / 1e3);
1712
1712
  for (const startMs of starts) {
1713
1713
  const start = Math.round(startMs * sampleRate / 1e3);
1714
- const span = layer.loop && !layer.at ? length - start : Math.min(source.length, length - start);
1714
+ const span = layer.loop && !layer.at ? length2 - start : Math.min(source.length, length2 - start);
1715
1715
  for (let i = 0; i < span; i++) {
1716
1716
  const index = start + i;
1717
- if (index < 0 || index >= length) continue;
1717
+ if (index < 0 || index >= length2) continue;
1718
1718
  let v = source[layer.loop && !layer.at ? i % source.length : i] * gain;
1719
1719
  if (fadeIn > 0 && i < fadeIn) v *= i / fadeIn;
1720
1720
  if (fadeOut > 0 && span - 1 - i < fadeOut) v *= (span - 1 - i) / fadeOut;
@@ -1751,13 +1751,13 @@ function duckGain(other, sampleRate, amount, attack, release, threshold) {
1751
1751
  }
1752
1752
  function mixAudio(layers, options) {
1753
1753
  const { sampleRate } = options;
1754
- const length = Math.max(0, Math.round(options.duration * sampleRate / 1e3));
1755
- const laid = layers.map((layer) => layOut(layer, sampleRate, length));
1754
+ const length2 = Math.max(0, Math.round(options.duration * sampleRate / 1e3));
1755
+ const laid = layers.map((layer) => layOut(layer, sampleRate, length2));
1756
1756
  const byId = /* @__PURE__ */ new Map();
1757
1757
  layers.forEach((layer, i) => {
1758
1758
  if (layer.id) byId.set(layer.id, i);
1759
1759
  });
1760
- const out = new Float32Array(length);
1760
+ const out = new Float32Array(length2);
1761
1761
  const hop = Math.max(1, Math.round(sampleRate / 100));
1762
1762
  layers.forEach((layer, i) => {
1763
1763
  let track = laid[i];
@@ -1766,13 +1766,13 @@ function mixAudio(layers, options) {
1766
1766
  if (under === void 0) throw new Error(`mixAudio: no layer "${layer.duck.under}" to duck under`);
1767
1767
  const amount = Math.min(1, Math.max(0, layer.duck.amount ?? 0.7));
1768
1768
  const gain = duckGain(laid[under], sampleRate, amount, layer.duck.attack ?? 80, layer.duck.release ?? 400, layer.duck.threshold ?? 0.01);
1769
- track = new Float32Array(length);
1770
- for (let s = 0; s < length; s++) track[s] = laid[i][s] * gain[Math.min(gain.length - 1, Math.floor(s / hop))];
1769
+ track = new Float32Array(length2);
1770
+ for (let s = 0; s < length2; s++) track[s] = laid[i][s] * gain[Math.min(gain.length - 1, Math.floor(s / hop))];
1771
1771
  }
1772
- for (let s = 0; s < length; s++) out[s] += track[s];
1772
+ for (let s = 0; s < length2; s++) out[s] += track[s];
1773
1773
  });
1774
1774
  const master = options.master ?? 1;
1775
- for (let s = 0; s < length; s++) {
1775
+ for (let s = 0; s < length2; s++) {
1776
1776
  const v = out[s] * master;
1777
1777
  out[s] = Math.abs(v) <= 0.8 ? v : Math.sign(v) * (0.8 + 0.2 * Math.tanh((Math.abs(v) - 0.8) / 0.2));
1778
1778
  }
@@ -1814,8 +1814,13 @@ async function renderMix(layers, options) {
1814
1814
  const baseDir = options.baseDir ?? process.cwd();
1815
1815
  const sampleRate = options.sampleRate ?? 48e3;
1816
1816
  const decoded = [];
1817
- for (const { file, ...layer } of layers) {
1818
- decoded.push({ ...layer, samples: await decodeAudio(resolve(baseDir, file), { sampleRate, ffmpeg: options.ffmpeg ?? "ffmpeg" }) });
1817
+ for (const layer of layers) {
1818
+ if ("samples" in layer) {
1819
+ decoded.push(layer);
1820
+ continue;
1821
+ }
1822
+ const { file, ...rest } = layer;
1823
+ decoded.push({ ...rest, samples: await decodeAudio(resolve(baseDir, file), { sampleRate, ffmpeg: options.ffmpeg ?? "ffmpeg" }) });
1819
1824
  }
1820
1825
  const output = resolve(baseDir, options.output);
1821
1826
  await mkdir(dirname(output), { recursive: true });
@@ -1842,6 +1847,117 @@ function decodeAudio(file, options = {}) {
1842
1847
  });
1843
1848
  });
1844
1849
  }
1850
+ const length = (sampleRate, ms) => Math.max(1, Math.round(sampleRate * ms / 1e3));
1851
+ function lowPass(input, cutoff) {
1852
+ const out = new Float32Array(input.length);
1853
+ let acc = 0;
1854
+ for (let i = 0; i < input.length; i++) {
1855
+ acc += cutoff(i) * (input[i] - acc);
1856
+ out[i] = acc;
1857
+ }
1858
+ return out;
1859
+ }
1860
+ function normalise(samples, peak) {
1861
+ let max = 0;
1862
+ for (const v of samples) max = Math.max(max, Math.abs(v));
1863
+ if (max > 0) for (let i = 0; i < samples.length; i++) samples[i] *= peak / max;
1864
+ return samples;
1865
+ }
1866
+ function soundWhoosh(sampleRate, options = {}) {
1867
+ const n = length(sampleRate, options.duration ?? 700);
1868
+ const random = createRandom(options.seed ?? 1);
1869
+ const noise = new Float32Array(n);
1870
+ for (let i = 0; i < n; i++) noise[i] = random.next() * 2 - 1;
1871
+ const rise = options.rise ?? true;
1872
+ const swept = lowPass(noise, (i) => {
1873
+ const u = i / n;
1874
+ return 0.02 + 0.25 * (rise ? u : 1 - u) ** 1.5;
1875
+ });
1876
+ const rumble = lowPass(swept, () => 0.01);
1877
+ for (let i = 0; i < n; i++) swept[i] = (swept[i] - rumble[i]) * Math.sin(Math.PI * i / n) ** 2;
1878
+ return normalise(swept, 0.8);
1879
+ }
1880
+ function soundPop(sampleRate, options = {}) {
1881
+ const n = length(sampleRate, options.duration ?? 120);
1882
+ const f0 = options.frequency ?? 660;
1883
+ const out = new Float32Array(n);
1884
+ let phase = 0;
1885
+ for (let i = 0; i < n; i++) {
1886
+ const t = i / sampleRate;
1887
+ phase += 2 * Math.PI * f0 * (1 + 0.6 * Math.exp(-t * 40)) / sampleRate;
1888
+ out[i] = 0.8 * Math.sin(phase) * Math.exp(-t * 28);
1889
+ }
1890
+ return out;
1891
+ }
1892
+ function soundThud(sampleRate, options = {}) {
1893
+ const n = length(sampleRate, options.duration ?? 350);
1894
+ const random = createRandom(options.seed ?? 3);
1895
+ const out = new Float32Array(n);
1896
+ let phase = 0;
1897
+ for (let i = 0; i < n; i++) {
1898
+ const t = i / sampleRate;
1899
+ phase += 2 * Math.PI * (55 + 90 * Math.exp(-t * 18)) / sampleRate;
1900
+ const click = (random.next() * 2 - 1) * Math.exp(-t * 160) * 0.3;
1901
+ out[i] = Math.sin(phase) * Math.exp(-t * 11) + click;
1902
+ }
1903
+ return normalise(out, 0.9);
1904
+ }
1905
+ function soundShimmer(sampleRate, options = {}) {
1906
+ const ms = options.duration ?? 900;
1907
+ const n = length(sampleRate, ms);
1908
+ const random = createRandom(options.seed ?? 2);
1909
+ const out = new Float32Array(n);
1910
+ for (let k = 0; k < 7; k++) {
1911
+ const f = 1200 * 2 ** (Math.floor(random.next() * 12) / 12);
1912
+ const start = Math.round(k * n / 10);
1913
+ for (let i = start; i < n; i++) {
1914
+ const t = (i - start) / sampleRate;
1915
+ out[i] += Math.sin(2 * Math.PI * f * t) * Math.exp(-t * 9);
1916
+ }
1917
+ }
1918
+ const release = length(sampleRate, Math.min(200, ms));
1919
+ for (let i = 0; i < n; i++) out[i] *= 0.25 * Math.min(1, (n - i) / release);
1920
+ return out;
1921
+ }
1922
+ function soundTick(sampleRate) {
1923
+ const n = length(sampleRate, 30);
1924
+ const out = new Float32Array(n);
1925
+ for (let i = 0; i < n; i++) {
1926
+ const t = i / sampleRate;
1927
+ out[i] = 0.5 * Math.sin(2 * Math.PI * 2400 * t) * Math.exp(-t * 300);
1928
+ }
1929
+ return out;
1930
+ }
1931
+ function soundClick(sampleRate, options = {}) {
1932
+ const n = length(sampleRate, 120);
1933
+ const random = createRandom(options.seed ?? 6);
1934
+ const out = new Float32Array(n);
1935
+ for (const [t0, f] of [[0, 3200], [0.035, 2100]]) {
1936
+ for (let i = Math.round(t0 * sampleRate); i < n; i++) {
1937
+ const t = i / sampleRate - t0;
1938
+ out[i] += Math.sin(2 * Math.PI * f * t) * Math.exp(-t * 120);
1939
+ }
1940
+ }
1941
+ for (let i = 0; i < n; i++) out[i] = 0.7 * (out[i] + (random.next() * 2 - 1) * Math.exp(-(i / sampleRate) * 200) * 0.25);
1942
+ return out;
1943
+ }
1944
+ function soundPad(sampleRate, options) {
1945
+ const n = length(sampleRate, options.duration);
1946
+ const random = createRandom(options.seed ?? 4);
1947
+ const out = new Float32Array(n);
1948
+ const voices = [];
1949
+ for (const f of [110, 164.8, 196, 261.6]) for (const d of [-0.4, 0.4]) voices.push({ f: f + d, phase: random.next() * 2 * Math.PI });
1950
+ const fadeIn = length(sampleRate, 2e3);
1951
+ const fadeOut = length(sampleRate, 2500);
1952
+ for (let i = 0; i < n; i++) {
1953
+ const t = i / sampleRate;
1954
+ let v = 0;
1955
+ for (const voice of voices) v += Math.sin(2 * Math.PI * voice.f * t + voice.phase + 0.3 * Math.sin(2 * Math.PI * 0.07 * t));
1956
+ const breath = 0.6 + 0.4 * Math.sin(2 * Math.PI * t / 9);
1957
+ out[i] = v * breath / 8 * Math.min(1, i / fadeIn) * Math.min(1, (n - i) / fadeOut);
1958
+ }
1959
+ return out;
1960
+ }
1845
1961
  export {
1846
1962
  CLOSED_DB,
1847
1963
  DEFAULT_FPS,
@@ -1866,6 +1982,13 @@ export {
1866
1982
  renderStills,
1867
1983
  renderVideo,
1868
1984
  sceneCaptions,
1985
+ soundClick,
1986
+ soundPad,
1987
+ soundPop,
1988
+ soundShimmer,
1989
+ soundThud,
1990
+ soundTick,
1991
+ soundWhoosh,
1869
1992
  toSRT,
1870
1993
  toWebVTT,
1871
1994
  voiceNarration
@@ -107,6 +107,15 @@ export interface Capabilities {
107
107
  /** `meetHands(kind, a, b)` */
108
108
  handMeetings: string[];
109
109
  };
110
+ /** The cosmic explainer kit: skies and depth, flat-shaded shapes, zooming through scale, short captions (canvas drawing functions) */
111
+ cosmic: {
112
+ depth: Record<string, string>;
113
+ shapes: Record<string, string>;
114
+ zoom: Record<string, string>;
115
+ captions: Record<string, string>;
116
+ skies: readonly string[];
117
+ sounds: string;
118
+ };
110
119
  /** The noir / detective kit: atmosphere, detective overlays and the case board (canvas drawing functions) */
111
120
  noir: {
112
121
  atmosphere: Record<string, string>;
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Burned-in short captions and label chips, the way science Shorts show
3
+ * text: a caption of one to three words at a time, in step with the voice,
4
+ * small and boxless near the lower third; and rounded chips that label
5
+ * things ("~1%", "nucleus"). Text and fonts are the caller's; words split at
6
+ * spaces, so Devanagari and other scripts that use spaces work as they are.
7
+ */
8
+ /** A spoken line: its text and when it is spoken, ms. */
9
+ export interface CaptionLine {
10
+ text: string;
11
+ start: number;
12
+ end: number;
13
+ }
14
+ /** The line cut into chunks of `wordsPerChunk` words. */
15
+ export declare function captionChunks(text: string, wordsPerChunk?: number): string[];
16
+ /**
17
+ * The chunk showing at `time` (or null outside the line). Each chunk's share
18
+ * of the line is its share of the characters (plus a little per chunk), an
19
+ * estimate of when the voice reaches it that is close enough for one to
20
+ * three words at a time.
21
+ */
22
+ export declare function captionChunkAt(line: CaptionLine, time: number, wordsPerChunk?: number, hold?: number): string | null;
23
+ export interface ShortCaptionOptions {
24
+ /** The spoken lines (narration cues) */
25
+ lines: ReadonlyArray<CaptionLine>;
26
+ /** Centre x and baseline y, px (for vertical video about 72% of the height; 16:9 about 86%) */
27
+ x: number;
28
+ y: number;
29
+ /** Font size, px (default 48) */
30
+ size?: number;
31
+ /** Font family (default 'sans-serif'); the weight is bold */
32
+ font?: string;
33
+ color?: string;
34
+ /** Drop shadow colour (default a near-black); null for none */
35
+ shadow?: string | null;
36
+ wordsPerChunk?: number;
37
+ /** Show lower case (default true, the reference look) */
38
+ lowercase?: boolean;
39
+ }
40
+ /** Draw the caption chunk for `time`; returns the text drawn, or null. */
41
+ export declare function drawShortCaption(ctx: CanvasRenderingContext2D, time: number, options: ShortCaptionOptions): string | null;
42
+ export interface LabelChipOptions {
43
+ text: string;
44
+ /** Centre of the chip, px */
45
+ x: number;
46
+ y: number;
47
+ /** Font size, px (default 34) */
48
+ size?: number;
49
+ font?: string;
50
+ /** Chip fill (default yellow) and text colour (default near-black) */
51
+ fill?: string;
52
+ color?: string;
53
+ /** When it pops on, ms (default: already on) */
54
+ at?: number;
55
+ /** Pop duration, ms (default 300) */
56
+ pop?: number;
57
+ }
58
+ /** A rounded label chip that pops on at `at`; returns its width (0 before it appears). */
59
+ export declare function drawLabelChip(ctx: CanvasRenderingContext2D, time: number, options: LabelChipOptions): number;
60
+ /** A small corner note (e.g. "*not to scale"), right-aligned at (x, y). */
61
+ export declare function drawCornerNote(ctx: CanvasRenderingContext2D, options: {
62
+ text: string;
63
+ x: number;
64
+ y: number;
65
+ size?: number;
66
+ font?: string;
67
+ color?: string;
68
+ }): void;
@@ -0,0 +1,35 @@
1
+ /**
2
+ * The cosmic explainer kit as data, for the capabilities catalog: every
3
+ * function with its call shape and what it draws.
4
+ */
5
+ export declare const COSMIC_KIT: {
6
+ readonly depth: {
7
+ readonly 'drawSkyGradient(ctx, { width, height, sky?, top?, bottom? })': "a flat saturated gradient sky filling the frame (one per scene)";
8
+ readonly 'drawDust(ctx, time, { width, height, count?, color?, opacity?, size?, drift?, offset?, seed? })': "twinkling specks in three parallax depths, wrapping round the frame (offset = camera shift)";
9
+ readonly 'drawBokeh(ctx, time, { width, height, count?, color?, opacity?, minRadius?, maxRadius?, drift?, offset?, seed? })': "big soft out-of-focus discs drifting across the frame";
10
+ readonly 'dustTwinkle(time, i, seed?)': "the twinkle 0..1 drawDust uses for speck i";
11
+ };
12
+ readonly shapes: {
13
+ readonly 'drawShadedBall(ctx, { x, y, radius, color, light?, shadow?, highlight?, opacity? })': "a flat sphere: base fill, a darker crescent away from the light, a small highlight; no outline";
14
+ readonly 'drawIsoCube(ctx, { x, y, size, color, opacity?, sheen? })': "an isometric cube: lit top, mid left, dark right face (isoCubeFaces gives the polygons)";
15
+ readonly 'drawHaze(ctx, time, { x, y, radius, color?, dots?, dot?, opacity?, squash?, spin?, seed? })': "a probability cloud of flickering dots, densest on a ring (an electron shell)";
16
+ readonly 'cosmicShade(color, amount, alpha?)': "a colour toward black (amount < 0) or white (> 0), for flat shading";
17
+ };
18
+ readonly zoom: {
19
+ readonly 'zoomAt(time, [{ time, value }])': "a zoom factor eased in log space between keys (a steady dive from 1x to 1000x)";
20
+ readonly 'depthAt(time, [{ time, value }])': "a depth eased between keys (0 = the first level)";
21
+ readonly 'drawZoomLevels(ctx, time, { width, height, depth, levels: [(ctx, time) => void], factor?, center?, portalRadius?, rim?, rimWidth? })': "zoom through scale: each level factor times smaller, opening as a growing portal in the middle of the last; levels behind a covering portal are skipped";
22
+ readonly 'zoomLevelLayout({ width, height, depth, levelCount, factor?, portalRadius? })': "which levels draw at a depth, their scale and portal radius";
23
+ readonly 'drawPortalRim(ctx, x, y, radius, color?, width?)': "a glowing ring";
24
+ readonly 'levelPresence(depth, level, settle?)': "0..1: how much a level fills the screen (to fade its label)";
25
+ };
26
+ readonly captions: {
27
+ readonly 'drawShortCaption(ctx, time, { lines: [{ text, start, end }], x, y, size?, font?, color?, shadow?, wordsPerChunk?, lowercase? })': "burned-in short captions: one to three words at a time in step with the voice (by character share)";
28
+ readonly 'captionChunkAt({ text, start, end }, time, wordsPerChunk?)': "the chunk showing at a time, or null";
29
+ readonly 'captionChunks(text, wordsPerChunk?)': "a line cut into chunks (split at spaces; works for Devanagari)";
30
+ readonly 'drawLabelChip(ctx, time, { text, x, y, size?, font?, fill?, color?, at?, pop? })': "a rounded label chip that pops on; returns its width";
31
+ readonly 'drawCornerNote(ctx, { text, x, y, size?, font?, color? })': "a small right-aligned note, e.g. \"*not to scale\"";
32
+ };
33
+ readonly skies: string[];
34
+ readonly sounds: "from tinyfly/headless: soundWhoosh, soundPop, soundThud, soundShimmer, soundTick, soundClick, soundPad (Float32Array samples for mixAudio / renderMix layers)";
35
+ };
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Small pure helpers shared by the cosmic explainer kit: colour parsing and
3
+ * shading (lighter / darker variants for flat-shaded shapes) and easing for
4
+ * camera zooms. Nothing here keeps state.
5
+ */
6
+ import { clamp01, smooth } from '../noir/noir-utils';
7
+ export { clamp01, smooth };
8
+ /** An `[r, g, b]` triple, 0..255. */
9
+ export type RgbTriple = [number, number, number];
10
+ /**
11
+ * Parse `#rgb`, `#rrggbb`, `rgb()` or `rgba()` into an `[r, g, b]` triple.
12
+ * Anything else throws: the kit shades colours, so it has to know them.
13
+ */
14
+ export declare function parseRgb(color: string): RgbTriple;
15
+ /** `rgba(r,g,b,a)` from a triple. */
16
+ export declare function rgba([r, g, b]: RgbTriple, alpha?: number): string;
17
+ /**
18
+ * A colour shaded toward black (`amount` < 0) or white (`amount` > 0),
19
+ * |amount| up to 1. The flat-shading look: one base colour, a darker side,
20
+ * a lighter highlight.
21
+ */
22
+ export declare function shade(color: string, amount: number, alpha?: number): string;
23
+ /** Ease in-out on 0..1 (smoothstep). */
24
+ export declare const easeInOut: (k: number) => number;
25
+ /** Deterministic 0..1 hash of an integer pair: the same particle lands in the same place every frame. */
26
+ export declare function hash01(i: number, salt: number): number;
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The cosmic explainer kit: gradient skies, parallax dust and bokeh, flat-
3
+ * shaded shapes (sphere, isometric cube, probability haze), zooming through
4
+ * scale with portals, burned-in short captions and label chips. Pair it with
5
+ * the noir kit's drawGlow and drawVignette, and the sound generators in
6
+ * tinyfly/headless. See docs/cosmic-explainer.md.
7
+ */
8
+ export * from './sky';
9
+ export * from './shapes';
10
+ export * from './zoom';
11
+ export * from './captions';
12
+ export { shade as cosmicShade, parseRgb } from './cosmic-utils';
13
+ export { COSMIC_KIT } from './cosmic-kit';
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Flat-shaded shapes for science explainers: a sphere with a shadow
3
+ * crescent and a highlight, an isometric cube, and a probability haze (an
4
+ * electron cloud of flickering dots). No outlines: the look is fills only.
5
+ */
6
+ export interface BallOptions {
7
+ x: number;
8
+ y: number;
9
+ radius: number;
10
+ color: string;
11
+ /** Where the light comes from, -1..1 each way (default { x: -0.35, y: -0.45 }: top left) */
12
+ light?: {
13
+ x: number;
14
+ y: number;
15
+ };
16
+ /** Strength of the shadow crescent, 0..1 (default 0.28) */
17
+ shadow?: number;
18
+ /** Draw the small highlight (default true) */
19
+ highlight?: boolean;
20
+ opacity?: number;
21
+ }
22
+ /** A flat sphere: the base fill, a darker crescent away from the light, a small highlight. */
23
+ export declare function drawShadedBall(ctx: CanvasRenderingContext2D, options: BallOptions): void;
24
+ export interface CubeOptions {
25
+ /** Centre of the cube */
26
+ x: number;
27
+ y: number;
28
+ /** Edge length, px */
29
+ size: number;
30
+ color: string;
31
+ opacity?: number;
32
+ /** A sparkle on the top face, 0..1 (default 0) */
33
+ sheen?: number;
34
+ }
35
+ /** The three visible faces of a cube in isometric view, as polygons (top, left, right). */
36
+ export declare function isoCubeFaces(options: Pick<CubeOptions, 'x' | 'y' | 'size'>): {
37
+ top: [number, number][];
38
+ left: [number, number][];
39
+ right: [number, number][];
40
+ };
41
+ /** An isometric cube: lit top, a mid left face, a dark right face. */
42
+ export declare function drawIsoCube(ctx: CanvasRenderingContext2D, options: CubeOptions): void;
43
+ export interface HazeOptions {
44
+ x: number;
45
+ y: number;
46
+ /** Radius of the densest ring, px */
47
+ radius: number;
48
+ color?: string;
49
+ /** How many dots (default 420) */
50
+ dots?: number;
51
+ /** Dot radius, px (default 2.6) */
52
+ dot?: number;
53
+ opacity?: number;
54
+ /** Vertical squash for a cloud seen at an angle (default 1) */
55
+ squash?: number;
56
+ /** Slow rotation, radians per second (default 0.15) */
57
+ spin?: number;
58
+ seed?: number;
59
+ }
60
+ /** A probability cloud: flickering dots, densest on a ring (an electron shell); fixed per seed. */
61
+ export declare function drawHaze(ctx: CanvasRenderingContext2D, time: number, options: HazeOptions): void;
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Backgrounds and depth for science-explainer scenes: a flat saturated
3
+ * gradient sky per scene, twinkling dust in parallax layers, and big soft
4
+ * out-of-focus discs (bokeh). Every function is a pure function of its
5
+ * options and the time (ms), so frames draw the same in any order.
6
+ */
7
+ /** Ready skies: a top and a bottom colour each. One per scene keeps cuts readable even without a hard cut. */
8
+ export declare const COSMIC_SKIES: {
9
+ readonly space: readonly ["#0b1026", "#1e1650"];
10
+ readonly micro: readonly ["#1a0b3d", "#3b1170"];
11
+ readonly magenta: readonly ["#e040a0", "#7c2bd9"];
12
+ readonly cyan: readonly ["#22d3ee", "#2563eb"];
13
+ readonly lime: readonly ["#f7f59a", "#b9f27c"];
14
+ readonly sunset: readonly ["#fb7185", "#f59e0b"];
15
+ readonly ocean: readonly ["#0ea5e9", "#0b2e6b"];
16
+ };
17
+ export type CosmicSky = keyof typeof COSMIC_SKIES;
18
+ export interface SkyOptions {
19
+ width: number;
20
+ height: number;
21
+ /** A ready sky (see COSMIC_SKIES), or give `top` and `bottom` */
22
+ sky?: CosmicSky;
23
+ top?: string;
24
+ bottom?: string;
25
+ }
26
+ /** A vertical gradient filling the frame. */
27
+ export declare function drawSkyGradient(ctx: CanvasRenderingContext2D, options: SkyOptions): void;
28
+ export interface DustOptions {
29
+ width: number;
30
+ height: number;
31
+ /** How many specks (default 70) */
32
+ count?: number;
33
+ /** Speck colour (default white) */
34
+ color?: string;
35
+ /** Peak opacity of the nearest layer (default 0.7) */
36
+ opacity?: number;
37
+ /** Speck radius of the nearest layer, px (default 3) */
38
+ size?: number;
39
+ /** Drift, px per second for the nearest layer (default { x: 0, y: -14 }: rising) */
40
+ drift?: {
41
+ x: number;
42
+ y: number;
43
+ };
44
+ /** Camera offset, px: far layers move less (parallax) */
45
+ offset?: {
46
+ x: number;
47
+ y: number;
48
+ };
49
+ /** Seed for where the specks sit (default 1) */
50
+ seed?: number;
51
+ }
52
+ /** Twinkling specks in three parallax depths, wrapping round the frame. */
53
+ export declare function drawDust(ctx: CanvasRenderingContext2D, time: number, options: DustOptions): void;
54
+ export interface BokehOptions {
55
+ width: number;
56
+ height: number;
57
+ /** How many discs (default 7) */
58
+ count?: number;
59
+ /** Disc colour (default white) */
60
+ color?: string;
61
+ /** Disc opacity (default 0.1) */
62
+ opacity?: number;
63
+ /** Radius range, px (default 60..190) */
64
+ minRadius?: number;
65
+ maxRadius?: number;
66
+ /** Sideways drift, px per second (default 8) */
67
+ drift?: number;
68
+ /** Camera offset, px: bokeh is near the lens, so it moves 1.6 times as far */
69
+ offset?: {
70
+ x: number;
71
+ y: number;
72
+ };
73
+ seed?: number;
74
+ }
75
+ /** Big soft out-of-focus discs drifting across the frame (foreground depth). */
76
+ export declare function drawBokeh(ctx: CanvasRenderingContext2D, time: number, options: BokehOptions): void;
77
+ /** Twinkle brightness 0..1 of speck `i` at `time` (the same curve drawDust uses), for syncing a glint to it. */
78
+ export declare function dustTwinkle(time: number, i: number, seed?: number): number;