@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/skills/vfrey-product/scenes/NOTICE

@@ -0,0 +1,5 @@
+The files in this folder (craft.md, motion.md, blocks.md) are original to vfrey in structure and wording, but their craft guidance is adapted from the skills and references of Framey, a modified version of HyperFrames by HeyGen (https://github.com/heygen-com/hyperframes), licensed under Apache-2.0.
+
+Adapted and changed: the motion-craft defaults (ease by role, springs, overlap and stagger, holds, titles that land still, transitions with a cause, common faults), the caption placement and grouping advice, and the contrast and compression notes were rewritten for vfrey's 1080x1920 frame, its local GSAP, fonts and supplied helpers (vfrey.timeline, vfrey.at, vfrey.onWord, vfrey.onLine, vfrey.block), and its offline, deterministic renderer. Material about HyperFrames' own CLI, studio, registry, cloud and media tools was left out. The numbers were adjusted for vertical short video and the label that vfrey adds.
+
+Copyright for the original work remains with HeyGen and the HyperFrames contributors. See src/scene/blocks/LICENSE (the Apache License, Version 2.0) and src/scene/blocks/NOTICE in the vfrey package. This is not affiliated with or endorsed by HeyGen.

package/skills/vfrey-product/scenes/blocks.md

@@ -0,0 +1,57 @@
+# Scene blocks
+
+Blocks are ready-made pieces (lower thirds, charts, code panels, chat cards, overlays, backgrounds, transitions) you copy into your own scene and restyle. They are ingredients, not templates: the scene around them is still yours. HTML scenes only; a Remotion scene (`index.tsx`) gets a `Fix:` line, so write the piece in React instead.
+
+## Find one
+
+```
+npx vfrey scene blocks                       # name, category, size, duration, fit
+npx vfrey scene blocks --category chart      # one category
+npx vfrey scene blocks --json
+```
+
+Categories: `lower-third`, `chart`, `diagram`, `chat`, `code`, `overlay`, `background`, `title`, `transition`. Choose by what the picture needs at that beat, and do not reach for a block when drawing the thing yourself says it better. At most one or two blocks in a short.
+
+## Add and place it
+
+```
+npx vfrey scene add lt-clean-bar scenes/my-idea
+```
+
+This copies `blocks/<name>/<name>.html` into the scene folder and prints a snippet. Paste its `<div>` inside `#root`, after your own content so it paints on top (or before, for a background). Adding twice is a no-op; an edited copy is not overwritten without `--force`. Each block can be mounted **once** per scene (its composition id is its name).
+
+The snippet's inline `style` already places it by the block's fit:
+
+| Fit | Meaning |
+| --- | --- |
+| `native` | at most 1080 wide, centered as drawn |
+| `crop` | the 1920x1080 canvas at full size, only its left 1080 px show: for pieces anchored left or at the bottom (lower thirds). Change `top` to move it; keep it clear of the caption zone and the label (see `craft.md`) |
+| `scale` | the canvas is scaled to the frame width, a band across the middle; change `top` to move it |
+| `cover` | scaled to the frame height and cropped at the sides: backgrounds and full-frame overlays |
+
+Move or resize the mount freely; a block is ordinary HTML.
+
+## Time it
+
+A block is a sub-composition with its own GSAP timeline, seeked from `data-start`. Without a call it starts at 0. Set when it starts, after `const tl = vfrey.timeline()`:
+
+```js
+vfrey.onLine(1, (tl, t) => vfrey.block("#block-lt-clean-bar", t));       // when line 1 is spoken
+vfrey.at(3.5, (tl, t) => vfrey.block("#block-data-chart", t, 4));        // at 3.5 s, for 4 s
+vfrey.onWord(5, (tl, t) => vfrey.block("#block-snow", t));         // at a word
+```
+
+`duration` is optional; each block plays for its own length otherwise. Do not start it after the film ends (voice length plus 0.3 s). If you need it again later, copy the folder under a different name or build a second instance yourself.
+
+## Restyle it
+
+Open `blocks/<name>/<name>.html`. Colors, fonts, sizes and text are plain CSS and markup:
+
+- Replace the placeholder text ("Your Brand", "Track title", "@yourhandle") with words from the script. Never leave placeholder text or a real person's or company's name on screen.
+- Swap its colors and fonts for your scene's variables (the local fonts are Titan One, JetBrains Mono, Google Sans Flex). A block that keeps its default look next to your palette is the most visible sign of a pasted-in piece.
+- Change its timings with the `gsap` calls inside, but keep it self-contained: its own timeline, no network, no randomness, no clock.
+- Do not add a CDN script, remote font or remote image; the render has no network.
+
+## Checks
+
+Render a still at the moment it shows (`--frame` a little after the cue) and look: is it where you want it, readable at phone size, clear of the captions and the label, not covering the focal element? Then a frame before the cue: it must not be visible yet.

package/skills/vfrey-product/scenes/craft.md

@@ -0,0 +1,118 @@
+# Scene craft
+
+Read this before you design a scene. It is about the picture, not the commands (those are in `../SKILL.md`). Every number is for the 1080x1920 frame. These are defaults: the idea in front of you can break one on purpose, but know which.
+
+## 1. Plan before you write HTML
+
+1. Read the script aloud in your head and mark the **picture moments**: the hook, each claim, the turn, the last line. A short is 15 to 45 seconds; something on screen should change at every beat (`vfrey.timing.beats`), and nothing should sit unchanged for more than about 3 s.
+2. Pick **one idea for the picture** that is not a text slide: a comparison drawn as two objects, a counter, a diagram that builds, a stick figure acting it out. Words are already in the voice and the captions; the picture must add something the words do not.
+3. Write down the look as numbers before coding: ground color, ink color, one accent, one display font, one body font, a corner radius. Put them in CSS variables on `#root` and use only those.
+4. Sketch the layout as three bands (below), then build it in that order: ground, big shapes, text, then motion.
+
+## 2. The frame: bands and safe areas
+
+```
+y 0     ┌────────────────────────┐
+        │ top margin   (0-160)   │  keep clear: phone status bars, platform UI
+ 160    ├────────────────────────┤
+        │ hero zone   (160-1250) │  the picture and the headline
+ 1250   ├────────────────────────┤
+        │ caption zone (1250-1700)│ captions live here by default
+ 1700   ├────────────────────────┤
+        │ label zone (1700-1920) │  the AI-GENERATED label is at x 686-1008, y 1806-1864
+y 1920  └────────────────────────┘
+```
+
+- Side margin 60 px minimum for anything that must be read; 80 px for text. Nothing important within 40 px of an edge.
+- vfrey burns the `AI-GENERATED` label on top at the bottom right (about 322x58, right margin 72, bottom margin 56). Keep your own content out of x 650 to 1080, y 1780 to 1920. Never try to cover it.
+- Captions are yours to place (`vfrey.captions("#captions", ...)`). The default box sits at `bottom: 220px`, about 250 px tall, which clears the label. If you move them up to make room for a bigger picture, keep the box at least 160 px above the label zone and never over the hero's focal point. Do not run a second block of text through the caption zone while captions are showing.
+- Phones crop and overlay the lower right of a short (buttons, titles). Put the single most important thing in the upper two thirds, centered.
+- Use full-width absolutely positioned containers with `text-align: center`. Avoid `left: 50%` plus `translateX(-50%)`: it clips at the frame edge once the element grows.
+- Do not hard-code a pixel height for text you fill from the script; size by `max-width` and let it wrap, then check a frame.
+
+## 3. Type
+
+| Role | Size | Notes |
+| --- | --- | --- |
+| Hero word or number | 220 to 420 px | one per beat, fills 60 to 90 % of the width |
+| Headline | 90 to 130 px | at most 2 lines, 3 to 7 words |
+| Support line / label | 48 to 64 px | never below 44 px: it is unreadable on a phone |
+| Captions | 64 to 88 px | set through `vfrey.captions` options |
+| Small chrome (units, tags) | 36 to 44 px | decoration only, never the message |
+
+- Use the supplied fonts: Titan One (loud display, one weight), Google Sans Flex (clean body, many weights), JetBrains Mono (numbers, code, labels). Pair one display with one body; do not add a third. No Google Fonts link, the network is blocked.
+- Line height 1.0 to 1.1 for display, 1.25 for body. Tight tracking (-0.01em) for big type, wide (0.08em) for small uppercase tags.
+- Contrast ratio at least 4.5:1 against the ground right behind the text. White text on a mid-tone gets a dark scrim or a solid chip, not a drop shadow.
+- Keep the same type scale for the whole film. Vary size by role, not at random.
+- Highlight one word per line in the accent color. Two accents on one line fight.
+
+## 4. Color
+
+- A ground, an ink, one accent, and at most one support color. Choose them from the subject (its era, materials, the place it lives), not from a default palette. Pure white grounds with blue accents and dark purple gradients with neon are where unprompted scenes land; use them only when the idea is that.
+- Full-screen linear gradients on dark grounds band after video compression. Use a solid fill, a radial gradient, or a solid with a local glow.
+- An accent at 5 % opacity vanishes in compression: 15 to 25 % for atmosphere, full strength for the focal element.
+- Change the ground color between acts of the story (hook, explanation, payoff) with a quick flood, so the film has chapters.
+
+## 5. Motion principles
+
+The timeline is `vfrey.timeline()`, one paused GSAP timeline. Cue with `vfrey.onLine(i, (tl, t) => ...)`, `vfrey.onWord(i, ...)` or `vfrey.at(sec, ...)`; every tween takes its position `t` so it lands on the spoken moment. Frames are a function of timeline time, so never use `Date.now`, `requestAnimationFrame`, CSS animations or `Math.random()` (use a seeded generator written inline if you need scatter).
+
+- **Ease by role.** Arrivals: long tail (`power4.out`, `expo.out`). Camera moves and color floods: `power2.inOut`. Exits and zooms-through: `power3.in`. Linear only for rotation, progress and constant speed. The same `power2.out` at 0.5 s on everything is what makes a scene look generated.
+- **Durations.** A fast move 0.3 to 0.6 s. Landing is slower than leaving; an exit is 40 to 50 % shorter than its entrance. Under 0.2 s reads as a glitch unless it is a deliberate whip.
+- **Overlap.** Start the next element when the previous is 30 to 50 % done. Fully sequential looks robotic; everything at once looks cheap. Stagger: letters one frame apart, words 60 to 120 ms, list items 40 to 80 ms.
+- **Springs.** `back.out(1.4)` or `elastic.out(1, 0.5)` for position and size only. Opacity and color never bounce. Bounce on UI reads as a toy; keep it for characters and objects.
+- **Titles land dead still.** Once a title has arrived it stops. Move the next element, or the world behind it, instead. Do not let a headline creep with a slow scale, breathe, float or pulse; those are fillers.
+- **Vary the entrance.** Not every element fades and slides up. Mix: per-word blur-in (`filter: blur(6px)` to 0, 0.13 s, 0.07 s apart), a mask or `clip-path` reveal, a wipe from a shape, a drop with a squash, a count-up, a line that draws itself (animate `strokeDashoffset`).
+- **Motion that earns its place:** an object doing the thing the line says (the pieces assembling, the bar growing to its value, the figure walking), a slow push on a background (3 to 5 degrees or 2 to 4 % scale over several seconds), a diagram building step by step.
+- **Hold to read.** A line of text the viewer must read holds about 0.5 s plus 0.3 s per word. The last line holds at least 1.5 s before the film ends (the film is voice length plus 0.3 s, so end your final tween before then).
+- **Transitions have a cause**: a shape grows to become the next ground, the old content blurs out as the new blurs in on the same stage, a color floods across, the figure pushes the old panel off. Pick two or three kinds for a short, not a different one per beat. Do not crossfade between unrelated scenes.
+- **Move with transforms.** Tween `x`, `y`, `scale`, `rotation`, `opacity`, `clipPath`, `filter`. Do not animate `left`, `top`, `width` or `height`; they relayout and jitter.
+- **Never fight the timeline.** One tween per property per element at a time; use `fromTo` rather than `from` when an element is shown twice; a `tl.set(el, { opacity: 0 }, end)` hard-kills a hidden element so no stale frame stays; do not tween `visibility` with `.to` (use `set`).
+
+## 6. Pacing to the voice
+
+- `vfrey.timing.lines[i]` and `words[j]` carry `start` and `end` in seconds. Anchor each *picture change* to the start of its line (`onLine`) or to the key word (`onWord`), so the picture lands as the claim is spoken, not before and not after. Slight lead (0.05 to 0.15 s before the word) feels in sync.
+- Number or object a line names should appear with the word that names it. A statistic appearing a beat after the voice says it looks like a mistake.
+- Hook (line 0): something moving within the first 0.3 s, the hero element on screen by 1 s. No logo sting, no empty frame.
+- Beats of one second or less: one element. Beats of three to six seconds: a small sequence, with motion inside the beat so it never sits still.
+- Contrast speeds: a fast montage of three to five quick changes, then a held frame, then the payoff. Hold 0.3 to 0.7 s before the payoff.
+- Layout changes on a bar-sized unit (a new line of the script), small accents on word beats.
+
+## 7. Structure that survives a render
+
+- One `#root` at 1080x1920, `data-composition-id="main"`, children absolutely positioned. Put every initial state in CSS (hidden things `opacity: 0`) so the first frame is right before the timeline runs.
+- Build every animation synchronously, in the same script that calls `vfrey.timeline()`. No `await`, no `setTimeout`, no `fetch`: the timeline must be complete when the page loads.
+- Draw art as inline SVG or SVG files in the scene folder (`<img src="octopus.svg">`) and the supplied `vfrey/assets/` stick figures and glyphs. Nothing from the network; no remote image, font or script.
+- Prefix ids by area (`#hero-title`, `#cmp-left`) so selectors do not collide with a block's ids.
+- When a scene is long, build it as functions per beat (`function beat3(t) { ... }`) called from `vfrey.onLine`, so each beat reads on its own.
+
+## 8. Mistakes that make a scene look generated
+
+- A text slide: the headline in the middle with a fade, then the next headline with the same fade.
+- The same entrance on every element; everything fades and slides up 40 px.
+- Captions over the picture's focal point, or a second text block in the caption zone.
+- Content near the label (bottom right) or hugging an edge.
+- Text under 44 px, or low contrast against a busy picture.
+- Looping decoration (pulsing dots, floating shapes) used in place of meaning.
+- Elements that never leave: the picture fills up with old content. Exit what is done, in one motion.
+- A palette of five accent colors, or a default blue on white because no choice was made.
+- Copying an example. Read one for the mechanics, then design for this idea.
+- Reusing the previous video's scene with new text.
+
+## 9. Check your own work
+
+Render a still at the hook (`--frame 1`), a middle beat (`--frame` at a line start from `timing.lines`), and the last second, and look at each (`../SKILL.md` has the command). For each ask: is the focal element obvious in one glance? Is anything under the label or crossing the caption zone? Is any text under 44 px? Does the picture change at the beat? Fix, rerender, look again. Do not stop at one frame.
+
+## 10. Change just this
+
+When the person says "make the title red" or "the chart appears too late", do not rewrite the scene. Find the exact element, rule and tween, change those, and look again:
+
+```
+npx vfrey scene inspect my-scene --at 2.5 --text "the title words"      # or --selector '#title'; add --json for everything
+```
+
+It loads the scene in the same headless Chrome as `render --frame` (network blocked), seeks the timeline to `--at`, and prints for each match: the selector path, the opening tag at `file:line:col`, its box in the 1080x1920 frame, computed color, background, font, opacity and transform, the CSS declarations behind them (`*` marks the one that wins; a value inherited from an ancestor says so) and the GSAP tweens that move it, each with start, duration, end, ease, properties, the line that wrote it and the `vfrey.at`, `onLine`, `onWord`, `block` or `transition` cue that ran it. Pick `--at` where the problem shows.
+
+Then edit only what it names: "red" is that one declaration (or the winning one, if two rules fight, or the tween if GSAP sets `color`); "too late" is the tween's position argument or the `onLine`/`at` time of its cue; "too slow" is its duration. Do not touch other rules, tweens or elements. Then check with `render --frame` at the same `--at` (and `scene inspect` again if you moved timing). HTML scenes only: for a Remotion scene it prints a `Fix:` line; use `--frame` and edit `index.tsx`.
+
+More: `motion.md` (recipes for GSAP moves, transitions, count-ups, draw-on lines), `blocks.md` (ready-made pieces such as lower thirds, charts, code and overlays to restyle).

package/skills/vfrey-product/scenes/motion.md

@@ -0,0 +1,88 @@
+# Motion recipes
+
+Copy the idea, not the numbers; change the ease, distance and timing for the idea at hand. All of this runs inside the single `const tl = vfrey.timeline()` and is cued with `vfrey.onLine`, `vfrey.onWord` or `vfrey.at`. Elements start hidden in CSS.
+
+## Arrivals (choose a different one per beat)
+
+```js
+// Per-word blur-in (split the headline into spans yourself, no random)
+const words = [...document.querySelectorAll("#head span")];
+vfrey.onLine(0, (tl, t) =>
+  tl.fromTo(words, { opacity: 0, filter: "blur(6px)" },
+    { opacity: 1, filter: "blur(0px)", duration: 0.16, ease: "power2.out", stagger: 0.08 }, t));
+
+// Mask wipe from the left
+vfrey.onLine(1, (tl, t) =>
+  tl.fromTo("#bar", { clipPath: "inset(0 100% 0 0)" }, { clipPath: "inset(0 0% 0 0)", duration: 0.5, ease: "power3.inOut" }, t));
+
+// Drop with a squash (position and size may bounce)
+vfrey.onLine(2, (tl, t) => {
+  tl.fromTo("#ball", { y: -300, scaleY: 1 }, { y: 0, duration: 0.45, ease: "power3.in" }, t)
+    .to("#ball", { scaleY: 0.78, transformOrigin: "50% 100%", duration: 0.08 }, t + 0.45)
+    .to("#ball", { scaleY: 1, duration: 0.3, ease: "elastic.out(1, 0.5)" }, t + 0.53);
+});
+
+// Line that draws itself (SVG path)
+const path = document.querySelector("#arrow path");
+const len = path.getTotalLength();
+gsap.set(path, { strokeDasharray: len, strokeDashoffset: len });
+vfrey.onLine(3, (tl, t) => tl.to(path, { strokeDashoffset: 0, duration: 0.7, ease: "power2.inOut" }, t));
+```
+
+## Numbers and bars
+
+```js
+// Count-up: tween a plain object, write text in onUpdate (deterministic: no clock)
+const n = { v: 0 };
+vfrey.onWord(4, (tl, t) =>
+  tl.to(n, { v: 87, duration: 0.9, ease: "power3.out",
+    onUpdate: () => (document.getElementById("num").textContent = Math.round(n.v)) }, t));
+
+// Bar to a value: scale a full-size bar, do not animate height
+tl.fromTo("#fill", { scaleY: 0 }, { scaleY: 0.64, transformOrigin: "50% 100%", duration: 0.7, ease: "power4.out" }, t);
+```
+
+Only show a number that is in the script or that you are certain of. A chart is a picture of what the voice says, not new claims.
+
+## Camera moves on a wrapper
+
+Put the whole scene (or a stage) in `#world` and move that. A punch-in: `tl.to("#world", { scale: 1.12, x: -40, y: -60, duration: 0.5, ease: "power2.inOut" }, t)`. A hard cut inside a scene is a punch-in plus a content swap on the same frame, with matching direction on both sides. Transform-origin is set once, in CSS.
+
+## Transitions
+
+| Idea | How |
+| --- | --- |
+| Object becomes the world | a circle or card scales past the frame (0.6 s, `power2.inOut`); its fill is the next ground; the new content fades in while it still grows |
+| Color flood | the hero stays; the ground changes color in about 0.4 s (`power2.inOut`) |
+| Whip | a 0.15 to 0.3 s horizontal slide with a `blur(12px)` that sharpens on landing |
+| Blur swap on one stage | out: opacity to 0 with `blur(8px)` in 0.15 s; in: blur to 0 in 0.15 s; the ground never changes |
+| Iris | `clipPath: "circle(0% at 50% 60%)"` to `"circle(150% at 50% 60%)"` onto the next stage |
+| Dip | darken the old frame by about 40 % for 3 frames (0.1 s) before a hard cut |
+
+Mirror eases across a seam: `power3.in` going out, `power3.out` coming in.
+
+### Shader transitions between shots (HTML scenes only)
+
+GPU transitions (glitch, zoom blur, warp, iris, light leak and more) between full-frame shots; `npx vfrey scene transitions` lists them. Stack the shots as sibling `<div>`s in `#root` (each fills the frame), load `<script src="vfrey/transitions.js"></script>` before `vfrey/vfrey.js`, then cue each seam. Calls chain (shot A to B, then B to C), may not overlap, and are driven by the scene's timeline, so frames are the same on every render:
+
+```js
+vfrey.transition("#shot-a", "#shot-b", { type: "cross-warp-morph", at: 3.2, duration: 0.7 });
+vfrey.transition("#shot-b", "#shot-c", { type: "glitch", at: 7.5, duration: 0.5 });
+```
+
+Place `at` with `vfrey.line(i).start` to cut on a spoken line. Animate each shot's contents as usual on `tl` (both shots keep playing through the seam). Use a type per seam with a cause, about 0.4 to 0.8 s, never every beat; `crossfade` is the quiet one. A `--frame` of a scene with transitions renders the clip up to that frame, so it takes about as long as a short render. Remotion scenes cannot use them (`✗` with a Fix); use `interpolate()` there.
+
+## Exits
+
+One smooth motion, 40 to 50 % shorter than the entrance: blur-and-fade 0.13 to 0.25 s, or move with the scene's own transition. Finish with a hard kill so no stale frame lingers: `tl.set("#panel", { opacity: 0 }, end)`.
+
+## Common faults
+
+| Symptom | Usual cause |
+| --- | --- |
+| Blank first frame, then pop | initial state not in CSS; tween built after the page loaded |
+| Jitter or drift between renders | layout measured in `onUpdate`; two tweens on the same property; `left/top` animated |
+| Text clipped at the edge after it scales | `overflow: hidden` on a parent, or `translateX(-50%)` centering |
+| Everything lands at once | every cue uses the same `t`; stagger or use different lines |
+| A block shows too early | `vfrey.block` never called for it (it plays from `data-start` 0) |
+| Nothing visible in the still at 2.5 s | the element's entrance is later than that; render a frame after its cue |

package/src/analytics/dashboard.ts

@@ -0,0 +1,109 @@
+export interface DashboardRow {
+  accountId: string;
+  platform: string;
+  externalId: string;
+  views: number | null;
+  watchTimeSec: number | null;
+  retention: number | null;
+  estimatedRevenue: number | null;
+  revenueStatus: string;
+  capturedAt?: string | null;
+  rank: number;
+}
+
+export interface HealthRow {
+  accountId: string;
+  platform: string;
+  tokenState: string;
+  lastError: string | null;
+  postsLast7d: number;
+  targetPostsLast7d: number;
+  cadence: "on_track" | "behind" | "ahead";
+  strikes: "not_exposed_by_official_api";
+}
+
+export function rankMetrics(
+  rows: Array<Omit<DashboardRow, "rank">>,
+): DashboardRow[] {
+  const sorted = [...rows].sort((a, b) => {
+    const av = a.views ?? -1;
+    const bv = b.views ?? -1;
+    if (bv !== av) return bv - av;
+    return (b.watchTimeSec ?? -1) - (a.watchTimeSec ?? -1);
+  });
+  return sorted.map((row, index) => ({ ...row, rank: index + 1 }));
+}
+
+export function cadenceHealth(postsLast7d: number, target: number): HealthRow["cadence"] {
+  if (postsLast7d + 0.5 < target * 0.6) return "behind";
+  if (postsLast7d > target * 1.4) return "ahead";
+  return "on_track";
+}
+
+export function renderDashboard(input: { rows: DashboardRow[]; health: HealthRow[]; generatedAt: string }): string {
+  const body = input.rows
+    .map(
+      (row) => `<tr>
+        <td>${row.rank}</td>
+        <td>${esc(row.accountId)}</td>
+        <td>${esc(row.platform)}</td>
+        <td>${esc(row.externalId)}</td>
+        <td>${cell(row.views)}</td>
+        <td>${cell(row.watchTimeSec)}</td>
+        <td>${row.retention === null ? "—" : `${cell(row.retention)}%`}</td>
+        <td>${row.revenueStatus === "present" ? cell(row.estimatedRevenue) : `— (${esc(row.revenueStatus)}: not available from the official API)`}</td>
+        <td>${row.capturedAt ? esc(row.capturedAt) : "—"}</td>
+      </tr>`,
+    )
+    .join("\n");
+  const health = input.health
+    .map(
+      (row) => `<tr>
+        <td>${esc(row.accountId)}</td>
+        <td>${esc(row.platform)}</td>
+        <td>${esc(row.tokenState)}</td>
+        <td>${esc(row.cadence)}</td>
+        <td>${row.postsLast7d}/${row.targetPostsLast7d}</td>
+        <td>${esc(row.strikes)}</td>
+        <td>${esc(row.lastError ?? "")}</td>
+      </tr>`,
+    )
+    .join("\n");
+  return `<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<title>Pipeline analytics</title>
+<style>
+  body { font: 15px/1.4 "Iowan Old Style", Palatino, serif; background: #f6f3ec; color: #1b1914; margin: 32px; }
+  h1 { font-weight: 500; letter-spacing: -0.03em; }
+  table { border-collapse: collapse; width: 100%; background: white; margin: 12px 0 28px; }
+  th, td { border-bottom: 1px solid #e4ddd0; text-align: left; padding: 8px 10px; font-variant-numeric: tabular-nums; }
+  th { font: 12px/1.2 ui-sans-serif, sans-serif; letter-spacing: 0.06em; text-transform: uppercase; color: #665e52; }
+  p { color: #665e52; }
+</style>
+<h1>Account ranking</h1>
+<p>Generated ${esc(input.generatedAt)}. Watch time, retention, and revenue stay blank when the official API does not return them. A forbidden revenue scope is not shown as zero. Strike status is not exposed by these APIs.</p>
+<table>
+  <thead><tr><th>Rank</th><th>Account</th><th>Platform</th><th>Post</th><th>Views</th><th>Watch sec</th><th>Retention</th><th>Revenue</th><th>As of</th></tr></thead>
+  <tbody>${body || `<tr><td colspan="9">No snapshots yet.</td></tr>`}</tbody>
+</table>
+<h1>Account health</h1>
+<table>
+  <thead><tr><th>Account</th><th>Platform</th><th>Token</th><th>Cadence</th><th>Posts 7d</th><th>Strikes</th><th>Last error</th></tr></thead>
+  <tbody>${health || `<tr><td colspan="7">No health rows yet.</td></tr>`}</tbody>
+</table>
+</html>`;
+}
+
+function cell(value: number | null): string {
+  if (value === null || Number.isNaN(value)) return "—";
+  return esc(String(value));
+}
+
+export function esc(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/src/analytics/index.ts

@@ -0,0 +1,260 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { interpretRevenue } from "@vfrey/contracts";
+import type { Account, AppConfig } from "@vfrey/contracts";
+import { requestJson } from "@vfrey/contracts";
+import type { Store } from "../queue/store.js";
+import { cadenceHealth, rankMetrics, renderDashboard, type HealthRow } from "./dashboard.js";
+
+export async function captureAnalytics(input: {
+  config: AppConfig;
+  account: Account;
+  posts: Array<{ platform: string; externalId: string }>;
+  tokenFor: (platform: string) => Promise<string>;
+  store: Store;
+  fetchImpl: typeof fetch;
+  now: Date;
+}): Promise<void> {
+  for (const post of input.posts) {
+    if (!post.externalId || post.externalId === "dry-run") continue;
+    const reading = await readPost(input, post.platform, post.externalId);
+    input.store.insertMetric({
+      accountId: input.account.id,
+      platform: post.platform,
+      externalId: post.externalId,
+      capturedAt: input.now.toISOString(),
+      views: reading.views,
+      watchTimeSec: reading.watchTimeSec,
+      retention: reading.retention,
+      estimatedRevenue: reading.estimatedRevenue,
+      revenueStatus: reading.revenueStatus,
+      raw: reading.raw,
+    });
+  }
+}
+
+interface Reading {
+  views: number | null;
+  watchTimeSec: number | null;
+  retention: number | null;
+  estimatedRevenue: number | null;
+  revenueStatus: string;
+  raw: unknown;
+}
+
+async function readPost(
+  input: { config: AppConfig; tokenFor: (platform: string) => Promise<string>; fetchImpl: typeof fetch },
+  platform: string,
+  externalId: string,
+): Promise<Reading> {
+  if (platform === "youtube") return readYouTube(input, externalId);
+  if (platform === "tiktok") return readTikTok(input, externalId);
+  if (platform === "instagram") return readInstagram(input, externalId);
+  if (platform === "facebook") return readFacebook(input, externalId);
+  return empty("unavailable");
+}
+
+async function readYouTube(
+  input: { tokenFor: (platform: string) => Promise<string>; fetchImpl: typeof fetch },
+  videoId: string,
+): Promise<Reading> {
+  const token = await input.tokenFor("youtube");
+  const stats = await requestJson(
+    input.fetchImpl,
+    `https://www.googleapis.com/youtube/v3/videos?part=statistics&id=${encodeURIComponent(videoId)}`,
+    { headers: { authorization: `Bearer ${token}` } },
+  );
+  const viewsRaw = (stats.json as { items?: Array<{ statistics?: { viewCount?: string } }> }).items?.[0]?.statistics?.viewCount;
+  const views = viewsRaw === undefined ? null : Number(viewsRaw);
+  const end = new Date().toISOString().slice(0, 10);
+  const startDate = new Date(Date.now() - 28 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+  const report = await requestJson(
+    input.fetchImpl,
+    "https://youtubeanalytics.googleapis.com/v2/reports?" +
+      new URLSearchParams({
+        ids: "channel==MINE",
+        startDate,
+        endDate: end,
+        metrics: "estimatedMinutesWatched,averageViewPercentage",
+        filters: `video==${videoId}`,
+      }).toString(),
+    { headers: { authorization: `Bearer ${token}` } },
+  );
+  let watchTimeSec: number | null = null;
+  let retention: number | null = null;
+  if (report.status < 400) {
+    const row = (report.json as { rows?: number[][] }).rows?.[0];
+    if (row) {
+      watchTimeSec = typeof row[0] === "number" ? row[0] * 60 : null;
+      retention = typeof row[1] === "number" ? row[1] : null;
+    }
+  }
+  const money = await requestJson(
+    input.fetchImpl,
+    "https://youtubeanalytics.googleapis.com/v2/reports?" +
+      new URLSearchParams({
+        ids: "channel==MINE",
+        startDate,
+        endDate: end,
+        metrics: "estimatedRevenue",
+        filters: `video==${videoId}`,
+      }).toString(),
+    { headers: { authorization: `Bearer ${token}` } },
+  );
+  const revenueValue =
+    money.status < 400 ? ((money.json as { rows?: number[][] }).rows?.[0]?.[0] ?? null) : null;
+  const revenue = interpretRevenue({
+    value: typeof revenueValue === "number" ? revenueValue : null,
+    httpStatus: money.status,
+  });
+  return {
+    views: Number.isFinite(views) ? views : null,
+    watchTimeSec,
+    retention,
+    estimatedRevenue: revenue.estimatedRevenue,
+    revenueStatus: revenue.revenueStatus,
+    raw: { stats: stats.status, analytics: report.status, revenue: money.status },
+  };
+}
+
+async function readTikTok(
+  input: { tokenFor: (platform: string) => Promise<string>; fetchImpl: typeof fetch },
+  externalId: string,
+): Promise<Reading> {
+  const token = await input.tokenFor("tiktok");
+  const result = await requestJson(
+    input.fetchImpl,
+    "https://open.tiktokapis.com/v2/video/query/?fields=id,view_count,like_count,comment_count,share_count",
+    {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ filters: { video_ids: [externalId] } }),
+    },
+  );
+  const video = (result.json as { data?: { videos?: Array<{ view_count?: number }> } }).data?.videos?.[0];
+  return {
+    views: typeof video?.view_count === "number" ? video.view_count : null,
+    watchTimeSec: null,
+    retention: null,
+    estimatedRevenue: null,
+    revenueStatus: "unavailable",
+    raw: { status: result.status, note: "Display API does not return watch time or revenue" },
+  };
+}
+
+async function readInstagram(
+  input: { config: AppConfig; tokenFor: (platform: string) => Promise<string>; fetchImpl: typeof fetch },
+  mediaId: string,
+): Promise<Reading> {
+  const token = await input.tokenFor("instagram");
+  const version = input.config.meta.graphVersion;
+  const result = await requestJson(
+    input.fetchImpl,
+    `https://graph.facebook.com/${version}/${mediaId}/insights?metric=views`,
+    { headers: { authorization: `Bearer ${token}` } },
+  );
+  const value = (result.json as { data?: Array<{ values?: Array<{ value?: number }> }> }).data?.[0]?.values?.[0]?.value;
+  return {
+    views: typeof value === "number" ? value : null,
+    watchTimeSec: null,
+    retention: null,
+    estimatedRevenue: null,
+    revenueStatus: "unavailable",
+    raw: { status: result.status, note: "Organic Instagram insights do not include estimated revenue" },
+  };
+}
+
+async function readFacebook(
+  input: { config: AppConfig; tokenFor: (platform: string) => Promise<string>; fetchImpl: typeof fetch },
+  videoId: string,
+): Promise<Reading> {
+  const token = await input.tokenFor("facebook");
+  const version = input.config.meta.graphVersion;
+  const result = await requestJson(
+    input.fetchImpl,
+    `https://graph.facebook.com/${version}/${videoId}/video_insights?metric=total_video_views,total_video_view_total_time`,
+    { headers: { authorization: `Bearer ${token}` } },
+  );
+  const data = (result.json as { data?: Array<{ name?: string; values?: Array<{ value?: number }> }> }).data ?? [];
+  const views = data.find((item) => item.name === "total_video_views")?.values?.[0]?.value;
+  const watch = data.find((item) => item.name === "total_video_view_total_time")?.values?.[0]?.value;
+  return {
+    views: typeof views === "number" ? views : null,
+    watchTimeSec: typeof watch === "number" ? watch / 1000 : null,
+    retention: null,
+    estimatedRevenue: null,
+    revenueStatus: "unavailable",
+    raw: { status: result.status },
+  };
+}
+
+function empty(revenueStatus: string): Reading {
+  return {
+    views: null,
+    watchTimeSec: null,
+    retention: null,
+    estimatedRevenue: null,
+    revenueStatus,
+    raw: {},
+  };
+}
+
+export async function writeDashboard(input: {
+  store: Store;
+  accounts: Account[];
+  dataDir: string;
+  now: Date;
+}): Promise<string> {
+  const metrics = input.store.latestMetrics().map((row) => ({
+    accountId: String(row.account_id),
+    platform: String(row.platform),
+    externalId: String(row.external_id),
+    views: row.views === null || row.views === undefined ? null : Number(row.views),
+    watchTimeSec: row.watch_time_sec === null || row.watch_time_sec === undefined ? null : Number(row.watch_time_sec),
+    retention: row.retention === null || row.retention === undefined ? null : Number(row.retention),
+    estimatedRevenue:
+      row.estimated_revenue === null || row.estimated_revenue === undefined ? null : Number(row.estimated_revenue),
+    revenueStatus: String(row.revenue_status),
+    capturedAt: row.captured_at ? String(row.captured_at) : null,
+  }));
+  const ranked = rankMetrics(metrics);
+  const healthDb = new Map(
+    input.store.healthRows().map((row) => [`${row.account_id}:${row.platform}`, row]),
+  );
+  const health: HealthRow[] = [];
+  for (const account of input.accounts) {
+    const times = input.store.publicationTimes(account.id, 100);
+    const weekAgo = input.now.getTime() - 7 * 24 * 60 * 60 * 1000;
+    const postsLast7d = times.filter((time) => time.getTime() >= weekAgo).length;
+    const overlay = input.store.deskOverlay(account.id);
+    const maxPosts = overlay ? overlay.maxPostsPerDay : account.cadence.maxPostsPerDay;
+    const target = maxPosts * 7;
+    for (const platform of Object.keys(account.platforms)) {
+      const row = healthDb.get(`${account.id}:${platform}`);
+      health.push({
+        accountId: account.id,
+        platform,
+        tokenState: row ? String(row.token_state) : "unknown",
+        lastError: row?.last_error ? String(row.last_error) : null,
+        postsLast7d,
+        targetPostsLast7d: target,
+        cadence: cadenceHealth(postsLast7d, target),
+        strikes: "not_exposed_by_official_api",
+      });
+      const label = cadenceHealth(postsLast7d, target);
+      if (label === "behind" || label === "ahead") {
+        input.store.warnOnce({
+          accountId: account.id,
+          jobId: null,
+          code: `cadence_${label}`,
+          message: `${account.id} is ${label}.`,
+        });
+      }
+    }
+  }
+  const html = renderDashboard({ rows: ranked, health, generatedAt: input.now.toISOString() });
+  const file = path.join(input.dataDir, "dashboard.html");
+  await mkdir(input.dataDir, { recursive: true });
+  await writeFile(file, html);
+  return file;
+}