@praeko/studio-core 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](https://semver.org/).
+
+## [0.2.0] - unreleased
+
+Breaking: the whole public API is English. There are no deprecated aliases; move to the new names. Published types are generated by `tsc`, and their relative specifiers end in `.js`.
+
+- Types and data: `Palavra` -> `Word`, `Tema` -> `Theme`, `TEMA_PADRAO` -> `DEFAULT_THEME`, `EpData` -> `EpisodeData` (`voz` -> `voice`, `palavras` -> `words`, `cenas` -> `scenes`, `fechamento` -> `outro`, `fundoLinhas` -> `backgroundLines`, `legendaPx` -> `captionPx`, `golpes` -> `hits`), `EpCena` -> `EpisodeScene` (`rotulo` -> `label`, `sons` -> `sounds`), `Som` -> `Sound` (`f` -> `sound`), `Golpe` -> `Hit` (`tipo` -> `type`, `tudo` -> `all`), `Grupo` -> `Group`, `LongoData` -> `LongData`, `CenaLongo` -> `LongScene`, `FechoLongo` -> `LongEndcard`.
+- Functions and components: `Episodio` -> `Episode`, `Longo` -> `Long`, `Rotulo` -> `Label`, `Fundo` -> `Background`, `agrupar` -> `groupWords`, `TemaProvider` -> `ThemeProvider` (prop `tema` -> `theme`), `useTema` -> `useTheme`, `temaDaMarca` -> `themeFromBrand`, `surge` -> `appear`, `mkAt` -> `makeAt`, `mkAtG` -> `makeAtGlobal`, `janela` -> `fadeWindow`.
+- Theme fields: `fundo` -> `background`, `fundoCapa` -> `coverBackground`, `destaque` -> `accent`, `texto` -> `text`, `suave` -> `muted`, `erro` -> `error`, `caixa` -> `box`, `caixaLongo` -> `longBox`, `codigo` -> `code`, `fonte` -> `font`. New `mascotPath` (default `mascots/{name}.png`). `themeFromBrand` reads the English `brand.json` shape (`colors`, `fonts.title`, `fonts.mono`).
+- Error messages are English (`phrase not found: ...`).
+
+## [0.1.0] - 2026-11-07
+
+First published version, extracted from the project where it was born. Publishes compiled `dist/` (ESM + `.d.ts`); `react` and `remotion` are peers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcone Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES.md

@@ -0,0 +1,36 @@
+# Praeko Studio licenses
+
+Verified on 2026-11-07. This file is not legal advice; each vendor's own text prevails.
+
+## Praeko Studio's code
+The packages `@praeko/studio`, `@praeko/studio-core` and `@praeko/studio-kit` are **MIT** (see `LICENSE`, Copyright (c) 2026 Marcone Santos), like `@praeko/sdk` and `@praeko/cli`. The sound effects (`pop`, `ding`, `thump`, `whoosh`) and the `avatar.png` of the project template were created for Studio (sounds synthesized by `scripts/generate-sfx.mjs`, with no third-party samples) and follow the same MIT license. The package ships no fonts, music, stock images or third-party art.
+
+## Notice you need to see (Remotion is NOT MIT)
+> **Remotion.** Remotion is *source-available*, not open source. It is **free** for individuals, non-profits, evaluation and companies with **up to 3 employees** (commercial use included). Companies with **4 or more people** need the **Company License** (remotion.pro/license). You install and run Remotion, so the license is **yours**, not Praeko's. Remotion also sells plans for those who **automate renders by program or agent** (Creators, Automators); their FAQ does not expressly say whether a local agent running `remotion render` counts: **ask Remotion** before using at scale. Praeko Studio does not copy or modify Remotion code: it uses it as a dependency (peer) that you install.
+
+This notice appears in the `README`, at install time (`praeko studio init`), in `praeko studio doctor` and in `praeko studio licenses` (`--accept` records that you read it in `~/.config/praeko/studio/licenses.json`).
+
+**Engines.** Remotion is the default engine for videos **and** covers. With `--engine hyperframes` (or `"engine": "hyperframes"` in `brand.json`) the video **and** the cover are rendered by HyperFrames and nothing from Remotion is used, so a project that only uses HyperFrames does not need a Remotion license. Scenes or covers written as TSX (`component:`) only exist in Remotion.
+
+**We do not promise "free forever":** Remotion's conditions may change (their own page warns that the license changes in Remotion 5.0). Review the license when you upgrade.
+
+## Third-party dependencies
+| Component | Where | License | Source |
+|---|---|---|---|
+| `remotion`, `@remotion/cli` (4.0.539) | installed in the user's **project** (peer of core/kit) | Remotion License (see above), not MIT | remotion.pro/license; github.com/remotion-dev/remotion (LICENSE.md) |
+| `react`, `react-dom` (19.2.3) | user's project (peer) | MIT | each package's package.json |
+| `@praeko/studio-core`, `-kit` | user's project | MIT | LICENSE |
+| `yaml` (2.9.1) | embedded in the `@praeko/studio` bundle | ISC | package.json |
+| `@elevenlabs/elevenlabs-js` (2.x) | dependency of `@praeko/studio` | MIT | package.json |
+| `hyperframes` (0.9.13, optional engine) | downloaded by `npx` the first time you use `--engine hyperframes` | Apache-2.0 | github.com/heygen-com/hyperframes |
+| `typescript`, `esbuild`, `@types/*` | development/build only | Apache-2.0 / MIT | package.json |
+| ffmpeg / ffprobe | you install | LGPL or GPL, depending on the build | ffmpeg.org/legal.html |
+| Chrome Headless Shell / Chromium | Remotion downloads it on the first render | Chromium/Google licenses | remotion.dev/docs/miscellaneous/chrome-headless-shell |
+
+## Services and models (you sign up)
+- **ElevenLabs**: its terms and your plan (voice cloning only with rights over the voice). The key is yours; Studio never prints it.
+- **Local VoiceStudio** (optional): the OmniVoice model is **CC-BY-NC (non-commercial use)**. It is not the default in any Studio configuration and **must not be used in monetized content**. Check the license of any local model you use.
+- **YouTube, Instagram, TikTok**: each network's terms and synthetic-content rules (see `praeko studio docs publish`).
+
+## Fonts and media
+No font is distributed. The project template uses system fonts (`Arial Black`, `Menlo`) that `doctor` checks; swap them in `brand.json` for open fonts (OFL) if you want the video to look the same on every system. Music, images and clips you add are your responsibility (rights and licenses).

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @praeko/studio-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Praeko Studio engine (Remotion parts): voice-driven episodes with timed words, word-by-word captions, editing hits, outro and brand theme. A library for projects created with [`@praeko/studio`](https://www.npmjs.com/package/@praeko/studio) (`praeko studio init` installs and configures it).
+
+> **Licenses.** This package is MIT and uses **Remotion** as a peer dependency that **you** install. Remotion is **not MIT**: free for individuals, non-profits and companies of up to 3 employees; companies of 4 or more people need the Company License ([remotion.pro/license](https://www.remotion.pro/license)). Details in [LICENSES.md](./LICENSES.md).
+
+## Install
+```sh
+# npm
+npm install @praeko/studio-core remotion react
+# yarn
+yarn add @praeko/studio-core remotion react
+# pnpm
+pnpm add @praeko/studio-core remotion react
+# bun
+bun add @praeko/studio-core remotion react
+```
+Peers: `remotion` ^4.0.539 (all `@remotion/*` packages on the same version) and `react` ^19. Node 22 or newer. Usage: `praeko studio docs episode-yaml`.

package/dist/engine.d.ts

@@ -0,0 +1,56 @@
+import type { Word } from "./word.js";
+/**
+ * PRAEKO STUDIO ENGINE.
+ * An episode is just data (EpisodeData): voice, timed words, scenes (card + label + sounds) and outro.
+ * The rest (background, captions, progress bar, outro, effects) is shared and uses the brand theme.
+ */
+export type Sound = {
+    at: number;
+    sound: "pop" | "ding" | "thump" | "whoosh";
+    v?: number;
+};
+export type Hit = {
+    at: number;
+    type: "shake" | "zoom" | "flash" | "all";
+};
+export type EpisodeScene = {
+    a: number;
+    b: number;
+    C: React.FC<{
+        dur: number;
+    }>;
+    label?: string;
+    /** sounds relative to the start of the scene (s) */
+    sounds?: Sound[];
+};
+export type EpisodeData = {
+    id: string;
+    durS: number;
+    voice: string;
+    words: Word[];
+    scenes: EpisodeScene[];
+    outro: {
+        a: number;
+        cta: string;
+    };
+    /** blurred "terminal" lines in the background */
+    backgroundLines?: string[];
+    /** caption size (default 90) */
+    captionPx?: number;
+    /** editing hits: quick shake, flash and zoom at instants (s) of the narration */
+    hits?: Hit[];
+};
+export declare const Label: React.FC<{
+    text: string;
+}>;
+/** Clean background: dark, a pulsing amber glow and dots drifting up slowly. */
+export declare const Background: React.FC;
+export type Group = {
+    words: Word[];
+    a: number;
+    b: number;
+};
+export declare const groupWords: (ps: Word[]) => Group[];
+export declare const Episode: React.FC<{
+    d: EpisodeData;
+}>;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./engine.js";
+export * from "./word.js";
+export * from "./theme.js";
+export * from "./theme-context.js";
+export * from "./util.js";
+export * from "./long.js";

package/dist/index.js

@@ -0,0 +1,465 @@
+// src/engine.tsx
+import { AbsoluteFill, Audio, Img, Sequence, interpolate as interpolate2, spring, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+// src/theme.ts
+var BASE = {
+  background: "#14110f",
+  coverBackground: "#0e0c14",
+  accent: "#f4b942",
+  text: "#f3ece0",
+  muted: "#a89c8a",
+  ok: "#7ee787",
+  error: "#ff6b5e",
+  info: "#7fd7ff",
+  extra: "#a98bff",
+  box: "#2a2118",
+  code: "#1b1610",
+  font: "'Arial Black', 'Helvetica Neue', system-ui, sans-serif",
+  mono: "Menlo, 'Courier New', monospace",
+  handle: "@yourchannel",
+  avatar: "cover/avatar.png",
+  mascotPath: "mascots/{name}.png"
+};
+var DEFAULT_THEME = BASE;
+var themeFromBrand = (m) => ({
+  ...DEFAULT_THEME,
+  ...m.colors ?? {},
+  ...m.fonts?.title ? { font: m.fonts.title } : {},
+  ...m.fonts?.mono ? { mono: m.fonts.mono } : {},
+  ...m.handle ? { handle: m.handle } : {},
+  ...m.avatar ? { avatar: m.avatar } : {},
+  ...m.mascotPath ? { mascotPath: m.mascotPath } : {}
+});
+var rgba = (hex, a) => {
+  const n = parseInt(hex.slice(1), 16);
+  return `rgba(${n >> 16 & 255},${n >> 8 & 255},${n & 255},${a})`;
+};
+
+// src/theme-context.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var Ctx = createContext(DEFAULT_THEME);
+var ThemeProvider = ({ theme, children }) => /* @__PURE__ */ jsx(Ctx.Provider, { value: theme, children });
+var useTheme = () => useContext(Ctx);
+
+// src/util.ts
+import { Easing, interpolate } from "remotion";
+var FPS = 30;
+var clamp = { extrapolateLeft: "clamp", extrapolateRight: "clamp" };
+var EO = Easing.bezier(0.16, 1, 0.3, 1);
+var appear = (t, q, d = 0.35) => interpolate(t, [q, q + d], [0, 1], { ...clamp, easing: EO });
+var ramp = (t, a, b) => interpolate(t, [a, b], [0, 1], { ...clamp, easing: Easing.out(Easing.cubic) });
+var pop = (t, q) => interpolate(t, [q, q + 0.18, q + 0.4], [0.6, 1.14, 1], { ...clamp, easing: Easing.out(Easing.cubic) });
+var fmt = (n) => String(Math.round(n)).replace(/\B(?=(\d{3})+(?!\d))/g, ".");
+var norm = (s) => s.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]/g, "");
+var makeAt = (P, S) => {
+  const W = P.map((p) => norm(p.t));
+  return (i) => (phrase, nth = 0) => {
+    const f2 = phrase.split(/\s+/).map(norm).filter(Boolean);
+    let c = 0;
+    for (let k = 0; k <= W.length - f2.length; k++) {
+      if (f2.every((w, j) => W[k + j] === w)) {
+        if (c === nth) return P[k].a - S[i];
+        c++;
+      }
+    }
+    throw new Error("phrase not found: " + phrase);
+  };
+};
+
+// src/engine.tsx
+import { Fragment, jsx as jsx2, jsxs } from "react/jsx-runtime";
+var f = (s) => Math.round(s * FPS);
+var DUR_SOM = { pop: 0.16, ding: 0.9, thump: 0.4, whoosh: 0.55 };
+var VOL_SOM = { pop: 0.22, ding: 0.26, thump: 0.33, whoosh: 0.28 };
+var Label = ({ text }) => {
+  const { accent: LAMP, background: BG, text: INK, font: FONT, ok: OK, box: BOX } = useTheme();
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const pop2 = spring({ frame: frame - 3, fps, config: { damping: 11, stiffness: 200 } });
+  return /* @__PURE__ */ jsx2(
+    "div",
+    {
+      style: {
+        position: "absolute",
+        top: 70,
+        left: 0,
+        right: 0,
+        display: "flex",
+        justifyContent: "center",
+        transform: `scale(${0.6 + 0.4 * pop2}) rotate(${(1 - pop2) * -4}deg)`,
+        opacity: Math.min(1, pop2 * 1.5)
+      },
+      children: /* @__PURE__ */ jsx2(
+        "div",
+        {
+          style: {
+            background: LAMP,
+            color: BG,
+            fontFamily: FONT,
+            fontSize: 62,
+            fontWeight: 900,
+            letterSpacing: 1,
+            padding: "14px 36px",
+            borderRadius: 22,
+            boxShadow: "0 10px 30px rgba(0,0,0,.55)",
+            whiteSpace: "nowrap"
+          },
+          children: text
+        }
+      )
+    }
+  );
+};
+var Background = () => {
+  const { accent: LAMP, background: BG, text: INK, font: FONT, ok: OK, box: BOX } = useTheme();
+  const frame = useCurrentFrame();
+  const pulse = 0.16 + 0.05 * Math.sin(frame / 22);
+  return /* @__PURE__ */ jsx2(
+    AbsoluteFill,
+    {
+      style: {
+        background: `radial-gradient(ellipse at 50% 20%, ${rgba(LAMP, pulse)} 0%, ${rgba(LAMP, 0)} 55%), radial-gradient(ellipse at 50% 100%, rgba(80,60,120,.22) 0%, rgba(0,0,0,0) 60%), ${BG}`
+      },
+      children: Array.from({ length: 26 }).map((_, i) => {
+        const x = i * 137 % 1080;
+        const vel = 0.35 + i % 5 * 0.18;
+        const y = (i * 251 % 1920 - frame * vel + 1920 * 4) % 1920;
+        const r = 3 + i % 4 * 2;
+        return /* @__PURE__ */ jsx2(
+          "div",
+          {
+            style: {
+              position: "absolute",
+              left: x,
+              top: y,
+              width: r,
+              height: r,
+              borderRadius: r,
+              background: LAMP,
+              opacity: 0.1 + i % 4 * 0.05
+            }
+          },
+          i
+        );
+      })
+    }
+  );
+};
+var groupWords = (ps) => {
+  const g = [];
+  let cur = [];
+  const close = () => {
+    if (cur.length) g.push({ words: cur, a: cur[0].a, b: cur[cur.length - 1].b });
+    cur = [];
+  };
+  ps.forEach((p, i) => {
+    cur.push(p);
+    const gap = i < ps.length - 1 ? ps[i + 1].a - p.b : 1;
+    const letters = cur.reduce((n, x) => n + x.t.length, 0);
+    const next = ps[i + 1]?.t.length ?? 0;
+    if (/[.,?!:]$/.test(p.t) || cur.length >= 3 || letters + next > 15 || gap > 0.3) close();
+  });
+  close();
+  return g;
+};
+var TerminalBackground = ({ lines }) => {
+  const { accent: LAMP, ok: OK } = useTheme();
+  const frame = useCurrentFrame();
+  const n = Math.max(1, lines.length);
+  const step = 64, cycle = 34 * step + 0;
+  return /* @__PURE__ */ jsxs(AbsoluteFill, { style: { overflow: "hidden" }, children: [
+    /* @__PURE__ */ jsx2(Background, {}),
+    /* @__PURE__ */ jsx2("div", { style: { position: "absolute", inset: 0, opacity: 0.09, filter: "blur(1.2px)" }, children: Array.from({ length: 34 }).map((_, i) => {
+      const y = ((i * step - frame * 0.8) % cycle + cycle) % cycle - 160;
+      const col = (i + Math.floor(i / n)) % 2;
+      return /* @__PURE__ */ jsx2(
+        "div",
+        {
+          style: {
+            position: "absolute",
+            left: 30 + col * 420,
+            top: y,
+            fontFamily: "Menlo, 'Courier New', monospace",
+            fontSize: 28,
+            color: i % 4 === 0 ? LAMP : OK,
+            whiteSpace: "nowrap"
+          },
+          children: lines[i % n]
+        },
+        i
+      );
+    }) })
+  ] });
+};
+var CaptionEp = ({ words, bottom, px = 90 }) => {
+  const { accent: LAMP, background: BG, text: INK, font: FONT, ok: OK, box: BOX } = useTheme();
+  const frame = useCurrentFrame();
+  const t = frame / FPS;
+  const groups = groupWords(words);
+  const idx = groups.findIndex((g2, i) => {
+    const next = groups[i + 1]?.a ?? g2.b + 0.4;
+    return t >= g2.a - 0.05 && t < Math.max(g2.b + 0.15, Math.min(next, g2.b + 0.5));
+  });
+  if (idx < 0) return null;
+  const g = groups[idx];
+  const inside = frame - f(g.a);
+  const enter = interpolate2(inside, [-2, 4], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+  return /* @__PURE__ */ jsx2(
+    "div",
+    {
+      style: {
+        position: "absolute",
+        left: px < 90 ? 70 : 40,
+        right: px < 90 ? 70 : 40,
+        bottom,
+        display: "flex",
+        justifyContent: "center",
+        gap: px < 90 ? 64 : 44,
+        flexWrap: "wrap",
+        opacity: enter,
+        transform: `translateY(${(1 - enter) * 24}px)`
+      },
+      children: g.words.map((p, i) => {
+        const active = t >= p.a && t < p.b + 0.05;
+        const spoken = t >= p.a;
+        return /* @__PURE__ */ jsx2(
+          "span",
+          {
+            style: {
+              fontFamily: FONT,
+              fontWeight: 900,
+              fontSize: px,
+              lineHeight: 1.05,
+              textTransform: "uppercase",
+              color: active ? LAMP : spoken ? INK : rgba(INK, 0.55),
+              transform: `scale(${active ? 1.12 : 1})`,
+              textShadow: "0 6px 0 #000, 0 0 24px rgba(0,0,0,.85), 4px 0 0 #000, -4px 0 0 #000"
+            },
+            children: p.t
+          },
+          i
+        );
+      })
+    }
+  );
+};
+var OutroEp = ({ cta }) => {
+  const theme = useTheme();
+  const { accent: LAMP, background: BG, text: INK, font: FONT, ok: OK, box: BOX } = useTheme();
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const logo = spring({ frame, fps, config: { damping: 10, stiffness: 150 } });
+  const handleSpring = spring({ frame: frame - 8, fps, config: { damping: 200 } });
+  const pill = spring({ frame: frame - 20, fps, config: { damping: 12, stiffness: 160 } });
+  return /* @__PURE__ */ jsxs(
+    AbsoluteFill,
+    {
+      style: {
+        background: `radial-gradient(circle at 50% 40%, ${BOX} 0%, ${BG} 72%)`,
+        justifyContent: "center",
+        alignItems: "center",
+        fontFamily: FONT,
+        textAlign: "center"
+      },
+      children: [
+        /* @__PURE__ */ jsx2(
+          "div",
+          {
+            style: {
+              width: 420,
+              height: 420,
+              borderRadius: 210,
+              overflow: "hidden",
+              border: `12px solid ${LAMP}`,
+              boxShadow: `0 0 80px ${rgba(LAMP, 0.45)}`,
+              transform: `scale(${0.6 + 0.4 * logo})`,
+              opacity: Math.min(1, logo * 1.5)
+            },
+            children: /* @__PURE__ */ jsx2(Img, { src: staticFile(theme.avatar), style: { width: 420, height: 420, imageRendering: "pixelated" } })
+          }
+        ),
+        /* @__PURE__ */ jsx2(
+          "div",
+          {
+            style: {
+              marginTop: 46,
+              fontSize: 92,
+              fontWeight: 900,
+              color: LAMP,
+              opacity: Math.max(0, handleSpring),
+              transform: `translateY(${(1 - Math.max(0, handleSpring)) * 30}px)`
+            },
+            children: theme.handle
+          }
+        ),
+        /* @__PURE__ */ jsx2(
+          "div",
+          {
+            style: {
+              marginTop: 50,
+              background: LAMP,
+              color: BG,
+              fontSize: cta.length > 18 ? 54 : 64,
+              fontWeight: 900,
+              padding: "20px 44px",
+              borderRadius: 28,
+              opacity: Math.max(0, pill),
+              transform: `scale(${0.6 + 0.4 * Math.max(0, pill)})`
+            },
+            children: cta
+          }
+        )
+      ]
+    }
+  );
+};
+var ProgressBar = ({ durS }) => {
+  const { accent: LAMP, background: BG, text: INK, font: FONT, ok: OK, box: BOX } = useTheme();
+  const frame = useCurrentFrame();
+  const w = Math.min(100, frame / f(durS) * 100);
+  return /* @__PURE__ */ jsx2("div", { style: { position: "absolute", top: 0, left: 0, right: 0, height: 10, background: "rgba(0,0,0,.4)" }, children: /* @__PURE__ */ jsx2("div", { style: { width: `${w}%`, height: "100%", background: LAMP } }) });
+};
+var Hits = ({ hits, children }) => {
+  const t = useCurrentFrame() / FPS;
+  let sx = 0, sy = 0, zoom = 1, flash = 0;
+  for (const g of hits) {
+    const dt = t - g.at;
+    if (dt < 0 || dt > 0.45) continue;
+    const k = (1 - dt / 0.45) ** 2;
+    if (g.type === "shake" || g.type === "all") {
+      sx += Math.sin(dt * 95) * 16 * k;
+      sy += Math.cos(dt * 120) * 9 * k;
+    }
+    if (g.type === "zoom" || g.type === "all") zoom = Math.max(zoom, 1 + 0.055 * k);
+    if (g.type === "flash" || g.type === "all") flash = Math.max(flash, 0.33 * k);
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx2(AbsoluteFill, { style: { transform: `translate(${sx}px, ${sy}px) scale(${zoom})` }, children }),
+    flash > 0.01 ? /* @__PURE__ */ jsx2(AbsoluteFill, { style: { background: `rgba(255,244,214,${flash})`, pointerEvents: "none" } }) : null
+  ] });
+};
+var Episode = ({ d }) => {
+  const { background: BG } = useTheme();
+  return /* @__PURE__ */ jsxs(AbsoluteFill, { style: { backgroundColor: BG }, children: [
+    /* @__PURE__ */ jsx2(Audio, { src: staticFile(d.voice) }),
+    /* @__PURE__ */ jsxs(Hits, { hits: d.hits ?? [], children: [
+      /* @__PURE__ */ jsx2(TerminalBackground, { lines: d.backgroundLines ?? ["\u2713 ok"] }),
+      /* @__PURE__ */ jsx2(Sequence, { from: 0, durationInFrames: f(DUR_SOM.whoosh) + 2, children: /* @__PURE__ */ jsx2(Audio, { src: staticFile("sfx/whoosh.wav"), volume: VOL_SOM.whoosh }) }),
+      d.scenes.flatMap((c, i) => {
+        const sounds = [{ at: 0, sound: "pop" }, ...c.sounds ?? []];
+        return sounds.map((s, k) => /* @__PURE__ */ jsx2(Sequence, { from: f(c.a + s.at), durationInFrames: f(DUR_SOM[s.sound]) + 2, children: /* @__PURE__ */ jsx2(Audio, { src: staticFile(`sfx/${s.sound}.wav`), volume: s.v ?? VOL_SOM[s.sound] }) }, `s${i}-${k}`));
+      }),
+      d.scenes.map((c, i) => /* @__PURE__ */ jsx2(Sequence, { from: f(c.a), durationInFrames: f(c.b - c.a), premountFor: 10, children: /* @__PURE__ */ jsx2(c.C, { dur: c.b - c.a }) }, "c" + i)),
+      d.scenes.map(
+        (c, i) => c.label ? /* @__PURE__ */ jsx2(Sequence, { from: f(c.a), durationInFrames: f(c.b - c.a), children: /* @__PURE__ */ jsx2(Label, { text: c.label }) }, "r" + i) : null
+      )
+    ] }),
+    /* @__PURE__ */ jsx2(Sequence, { from: f(d.outro.a), durationInFrames: f(d.durS - d.outro.a), children: /* @__PURE__ */ jsx2(OutroEp, { cta: d.outro.cta }) }),
+    /* @__PURE__ */ jsx2(Sequence, { from: 0, durationInFrames: f(d.durS), children: /* @__PURE__ */ jsx2(CaptionEp, { words: d.words, bottom: 190, px: d.captionPx }) }),
+    /* @__PURE__ */ jsx2(Sequence, { from: f(d.outro.a), durationInFrames: 2, children: /* @__PURE__ */ jsx2(Audio, { src: staticFile("sfx/ding.wav"), volume: 0.22 }) }),
+    /* @__PURE__ */ jsx2(ProgressBar, { durS: d.durS })
+  ] });
+};
+
+// src/long.tsx
+import { AbsoluteFill as AbsoluteFill2, Audio as Audio2, Img as Img2, interpolate as interpolate3, spring as spring2, staticFile as staticFile2, useCurrentFrame as useCurrentFrame2, useVideoConfig as useVideoConfig2 } from "remotion";
+import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
+var clamp2 = { extrapolateLeft: "clamp", extrapolateRight: "clamp" };
+var fadeWindow = (t, a, b, d = 0.4) => interpolate3(t, [a, a + d, b - d, b], [0, 1, 1, 0], clamp2);
+var makeAtGlobal = (P) => {
+  const W = P.map((p) => norm(p.t));
+  return (phrase, nth = 0, from = 0) => {
+    const f2 = phrase.split(/\s+/).map(norm).filter(Boolean);
+    let c = 0;
+    for (let i = 0; i <= W.length - f2.length; i++) {
+      if (P[i].a < from) continue;
+      if (f2.every((w, k) => W[i + k] === w)) {
+        if (c === nth) return P[i].a;
+        c++;
+      }
+    }
+    throw new Error("phrase not found: " + phrase);
+  };
+};
+var SceneFrame = ({ t, a, b, n, title, children }) => {
+  const T = useTheme();
+  if (t < a - 0.1 || t > b + 0.1) return null;
+  return /* @__PURE__ */ jsxs2(AbsoluteFill2, { style: { opacity: fadeWindow(t, a, b) }, children: [
+    /* @__PURE__ */ jsxs2("div", { style: { position: "absolute", left: 100, top: 46, display: "flex", alignItems: "center", gap: 18, fontFamily: T.font, fontSize: 30, letterSpacing: 4, color: T.accent, whiteSpace: "nowrap" }, children: [
+      /* @__PURE__ */ jsx3("span", { style: { background: T.accent, color: T.background, borderRadius: 12, padding: "4px 16px" }, children: n }),
+      title
+    ] }),
+    children
+  ] });
+};
+var splitGroups = (P) => {
+  const g = [];
+  let cur = [];
+  P.forEach((p) => {
+    cur.push(p);
+    if (/[.!?:]$/.test(p.t) || cur.length >= 8 || /[,;]$/.test(p.t) && cur.length >= 5) {
+      g.push(cur);
+      cur = [];
+    }
+  });
+  if (cur.length) g.push(cur);
+  return g;
+};
+var Captions = ({ t, G }) => {
+  const T = useTheme();
+  let group = null;
+  for (const g of G) if (t >= g[0].a - 0.05 && t <= g[g.length - 1].b + 0.4) group = g;
+  if (!group) return null;
+  return /* @__PURE__ */ jsx3("div", { style: { position: "absolute", left: 160, right: 160, bottom: 56, textAlign: "center", fontFamily: T.font, fontSize: 46, lineHeight: 1.2, textShadow: "0 3px 12px rgba(0,0,0,.9)" }, children: group.map((p, i) => /* @__PURE__ */ jsxs2("span", { style: { color: t >= p.a && t < p.b + 0.05 ? T.accent : T.text }, children: [
+    p.t,
+    i < group.length - 1 ? " " : ""
+  ] }, i)) });
+};
+var EndcardScreen = ({ f: f2, t }) => {
+  const T = useTheme();
+  const { fps } = useVideoConfig2();
+  const k = (delay) => spring2({ frame: (t - f2.a - delay) * fps, fps, config: { damping: 14, stiffness: 140 } });
+  const op = interpolate3(t, [f2.a, f2.a + 0.5], [0, 1], clamp2);
+  return /* @__PURE__ */ jsxs2(AbsoluteFill2, { style: { opacity: op, background: `radial-gradient(circle at 50% 40%, ${T.box} 0%, ${T.background} 75%)`, alignItems: "center", justifyContent: "center", fontFamily: T.font, textAlign: "center", paddingBottom: 90 }, children: [
+    /* @__PURE__ */ jsx3("div", { style: { width: 230, height: 230, borderRadius: 44, overflow: "hidden", border: `8px solid ${f2.image ? "#3a3566" : T.accent}`, background: f2.image ? "#1c1a33" : void 0, boxShadow: `0 0 70px ${rgba(T.accent, 0.3)}`, transform: `scale(${0.6 + 0.4 * k(0)})`, opacity: Math.min(1, k(0) * 1.5) }, children: /* @__PURE__ */ jsx3(Img2, { src: staticFile2(f2.image ?? T.avatar), style: { width: 230, height: 230, imageRendering: "pixelated", objectFit: "contain" } }) }),
+    f2.text ? /* @__PURE__ */ jsx3("div", { style: { marginTop: 44, fontSize: 104, fontWeight: 900, color: T.accent, opacity: Math.max(0, k(0.15)), transform: `translateY(${(1 - Math.max(0, k(0.15))) * 24}px)` }, children: f2.text }) : null,
+    /* @__PURE__ */ jsx3("div", { style: { marginTop: 28, fontSize: 54, fontWeight: 900, color: T.text, opacity: Math.max(0, k(0.3)) }, children: T.handle }),
+    f2.link ? /* @__PURE__ */ jsx3("div", { style: { marginTop: 18, fontSize: 38, fontFamily: T.mono, color: T.muted, opacity: Math.max(0, k(0.45)) }, children: f2.link }) : null
+  ] });
+};
+var Long = ({ d }) => {
+  const T = useTheme();
+  const t = useCurrentFrame2() / FPS;
+  const G = splitGroups(d.words);
+  return /* @__PURE__ */ jsxs2(AbsoluteFill2, { style: { background: T.background, color: T.text, fontFamily: T.font }, children: [
+    /* @__PURE__ */ jsx3(AbsoluteFill2, { style: { background: `radial-gradient(1200px 700px at 70% 20%, ${rgba(T.accent, 0.07)}, transparent 70%)` } }),
+    /* @__PURE__ */ jsx3(Audio2, { src: staticFile2(d.voice) }),
+    d.scenes.map((c) => /* @__PURE__ */ jsx3(SceneFrame, { t, a: c.a, b: c.b, n: c.n, title: c.title, children: /* @__PURE__ */ jsx3(c.C, { t }) }, c.n)),
+    d.endcard && t >= d.endcard.a ? /* @__PURE__ */ jsx3(EndcardScreen, { f: d.endcard, t }) : null,
+    /* @__PURE__ */ jsx3(Captions, { t, G }),
+    /* @__PURE__ */ jsx3("div", { style: { position: "absolute", left: 0, top: 0, height: 8, width: `${t / d.durS * 100}%`, background: T.accent } })
+  ] });
+};
+export {
+  Background,
+  DEFAULT_THEME,
+  Episode,
+  FPS,
+  Label,
+  Long,
+  ThemeProvider,
+  appear,
+  clamp,
+  fadeWindow,
+  fmt,
+  groupWords,
+  makeAt,
+  makeAtGlobal,
+  norm,
+  pop,
+  ramp,
+  rgba,
+  themeFromBrand,
+  useTheme
+};

package/dist/long.d.ts

@@ -0,0 +1,39 @@
+import type { Word } from "./word.js";
+/**
+ * LONG ENGINE (16:9, several minutes). A long video is a list of scenes in GLOBAL time: each scene receives `t` (s since the start of the video)
+ * and ties itself to the voice with `makeAtGlobal(WORDS)(phrase, nth, from)`. The engine handles the background, the voice, the scene header (number + title),
+ * grouped captions and the progress bar. Scenes are project TSX, built with the parts of `@praeko/studio-kit`.
+ */
+export type LongScene = {
+    n: string;
+    title: string;
+    a: number;
+    b: number;
+    C: React.FC<{
+        t: number;
+    }>;
+};
+/** Optional end card: avatar, text (e.g. the signature), brand handle and link. Starts at `a` (s) and stays until the end. */
+export type LongEndcard = {
+    a: number;
+    text?: string;
+    link?: string;
+    image?: string;
+};
+export type LongData = {
+    id: string;
+    durS: number;
+    voice: string;
+    words: Word[];
+    scenes: LongScene[];
+    width?: number;
+    height?: number;
+    endcard?: LongEndcard;
+};
+/** Fades in and out over `d` s at the ends of the window [a, b]. */
+export declare const fadeWindow: (t: number, a: number, b: number, d?: number) => number;
+/** Global anchor: `at("phrase", nth, from)` = instant (s) at which the phrase starts; `from` ignores occurrences before `from` s. Fails loudly if not found. */
+export declare const makeAtGlobal: (P: Word[]) => (phrase: string, nth?: number, from?: number) => number;
+export declare const Long: React.FC<{
+    d: LongData;
+}>;

package/dist/theme-context.d.ts

@@ -0,0 +1,6 @@
+import type { Theme } from "./theme.js";
+export declare const ThemeProvider: React.FC<{
+    theme: Theme;
+    children: React.ReactNode;
+}>;
+export declare const useTheme: () => Theme;

package/dist/theme.d.ts

@@ -0,0 +1,37 @@
+/** Brand tokens. Everything that is a color, font, name or avatar comes from here; the engine and the kit know no brand. */
+export type Theme = {
+    background: string;
+    coverBackground: string;
+    accent: string;
+    text: string;
+    muted: string;
+    ok: string;
+    error: string;
+    info: string;
+    extra: string;
+    box: string;
+    longBox?: string;
+    code: string;
+    font: string;
+    mono: string;
+    handle: string;
+    avatar: string;
+    /** Mascot image path template under public/; `{name}` is replaced. Default `mascots/{name}.png`. */
+    mascotPath?: string;
+};
+export declare const DEFAULT_THEME: Theme;
+type BrandLike = {
+    colors?: Partial<Theme>;
+    fonts?: {
+        title?: string;
+        mono?: string;
+    };
+    handle?: string;
+    avatar?: string;
+    mascotPath?: string;
+};
+/** Reads a project's `brand.json` (missing fields use the default theme). */
+export declare const themeFromBrand: (m: BrandLike) => Theme;
+/** "#f4b942" + 0.16 -> "rgba(244,185,66,0.16)". */
+export declare const rgba: (hex: string, a: number) => string;
+export {};

package/dist/util.d.ts

@@ -0,0 +1,18 @@
+import type { Word } from "./word.js";
+export declare const FPS = 30;
+export declare const clamp: {
+    readonly extrapolateLeft: "clamp";
+    readonly extrapolateRight: "clamp";
+};
+/** 0 -> 1 from instant `q` (s), with a soft ease-out. */
+export declare const appear: (t: number, q: number, d?: number) => number;
+export declare const ramp: (t: number, a: number, b: number) => number;
+export declare const pop: (t: number, q: number) => number;
+/** Number with "." as thousands separator (pt-BR style): 13500 -> "13.500". */
+export declare const fmt: (n: number) => string;
+export declare const norm: (s: string) => string;
+/**
+ * Phrase anchors: `makeAt(words, starts)(i)(phrase, n)` returns the LOCAL instant (s since the start of scene i) at which the phrase
+ * starts in the voice. Fails loudly if the phrase does not exist (the aligner sometimes writes numbers as digits).
+ */
+export declare const makeAt: (P: Word[], S: number[]) => (i: number) => (phrase: string, nth?: number) => number;

package/dist/word.d.ts

@@ -0,0 +1,6 @@
+/** A spoken word with its timing: `t` text, `a` start (s), `b` end (s). */
+export type Word = {
+    t: string;
+    a: number;
+    b: number;
+};

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@praeko/studio-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "The Praeko Studio engine: voice-driven episodes with timed words, word-by-word captions, editing hits, outro and brand theme (Remotion parts). A library for projects created with `praeko studio init`.",
+  "license": "MIT",
+  "keywords": [
+    "praeko",
+    "video",
+    "shorts",
+    "remotion",
+    "captions",
+    "engine"
+  ],
+  "homepage": "https://praeko.app/docs",
+  "bugs": {
+    "url": "https://praeko.app/docs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Praeko/praeko-js.git",
+    "directory": "studio/packages/core"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "LICENSES.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../../scripts/build-studio.mjs core",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test test/*.test.ts"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "remotion": "^4.0.539"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.7",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "remotion": "4.0.539"
+  }
+}