Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(x-content): film every post as a passing end-to-end run of its feature

nirholas084ea4864d2d
diff --git a/api/_lib/x-content/editor.js b/api/_lib/x-content/editor.js
index 1c36c3db7..714ebece4 100644
--- a/api/_lib/x-content/editor.js
+++ b/api/_lib/x-content/editor.js
@@ -20,6 +20,8 @@ import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { mediaType } from './media.js';
import { EDITOR_MODEL, callModelChain } from './llm.js';
+import { STANDARD_MAX_LENGTH } from './quality.js';
+import { loadProof, reelFrames } from './reel.js';
export { EDITOR_MODEL };
const MAX_SOURCE_CHARS = 24_000;
@@ -35,7 +37,7 @@ Judge the post on:
- specificity: it states a mechanism or a checkable fact, not an adjective. The first line carries the strongest true statement.
- voice: matches the house voice contract exactly (no hashtags, no emoji, no hype openers, no dashes, no rhetorical questions, no teaser threads).
- professionalism: grammar, punctuation, capitalization of names, and tone a partner's comms team would be comfortable being tagged in. Nothing that reads as investment advice or a price promise about $THREE. Tags are only for accounts the feature genuinely runs on.
-- visual: the image is sharp, shows the real product, supports the claim, and would not be cropped badly in the timeline; alt text describes what is in the image for someone who cannot see it.
+- visual: the image is sharp, shows the real product, supports the claim, and would not be cropped badly in the timeline; alt text describes what is in the image for someone who cannot see it. When the attachment is a reel you cannot watch it, so you are given still frames from it, the captions it shows in order, and the record of the run it filmed (what the run read off the screen, what the server answered, and how long any wait was cut). Judge whether those frames show the feature doing what the post says, whether each caption is true of the frame it sits under, and whether anything a frame shows contradicts the copy.
Score each 1 to 5, where 5 means you would ship it unchanged at a top-tier company and 3 means a competent draft that needs work.
@@ -43,7 +45,7 @@ Rules for your output:
- Quote the exact words each issue is about.
- severity "blocking" means it must not be published as is; "major" should be fixed; "minor" is polish.
- Every fix is concrete: the replacement text, or exactly what to recapture.
-- The rewrite must obey every rule above, stay within 280 weighted characters per post (URLs count as 23), keep the same link, and contain only facts that appear word for word in a passing verification result or in the live page text quoted by a passing check. Do not import facts from the announcement pack that no check verified. If nothing needs to change, return the original text.
+- The rewrite must obey every rule above, stay within {MAX} weighted characters per post (URLs count as 23), keep the same link, and contain only facts that appear word for word in a passing verification result or in the live page text quoted by a passing check. Do not import facts from the announcement pack that no check verified. If nothing needs to change, return the original text.
- verdict is "publish" only when there are no blocking issues and every score is at least 4; "revise" when fixable; "reject" when the post should not exist (wrong premise, unverifiable core claim, or reputational risk).
Respond with a single JSON object and nothing else:
@@ -67,8 +69,21 @@ function topPosts(root, count = 6) {
.map((row) => ({ text: String(row.text || '').replace(/\s+/g, ' ').trim(), likes: row.likes, reposts: row.retweets, views: row.views }));
}
-// Images go to the model at a readable size. Video is described by its probe,
-// since the editor cannot watch it.
+// What a reel is, in words: the editor judges the frames against this.
+function reelRecord(item, row, proof) {
+ const captions = (item.scenario?.steps || []).map((step) => step.caption).filter(Boolean);
+ return [
+ `${row.role}: a ${row.probe?.durationSec ?? '?'} second reel, ${row.probe?.width}x${row.probe?.height}, filmed from the live product by running the item's scenario end to end.`,
+ `Filmed ${proof?.ranAt || 'at an unknown time'} against ${proof?.target?.commit ? `production commit ${proof.target.commit}` : 'production'}; ${Math.round((proof?.video?.motion || 0) * 100)}% of its frames change.`,
+ `Captions, in order: ${JSON.stringify(captions)}.`,
+ `The run read off the screen: ${JSON.stringify(proof?.facts || {})}. It waited for and saw: ${JSON.stringify(proof?.saw || [])}. The server answered: ${JSON.stringify(proof?.responses || [])}.`,
+ `Waits cut from the film, each labelled in the reel: ${JSON.stringify(proof?.cuts || [])}.`,
+ ].join('\n');
+}
+
+// Images go to the model at a readable size. A reel goes as still frames and
+// the record of its run; any other video is described by its probe, since the
+// editor cannot watch it.
async function imageParts(item, root) {
const { default: sharp } = await import('sharp');
const parts = [];
@@ -79,6 +94,15 @@ async function imageParts(item, root) {
for (const row of media) {
const type = mediaType(row.path);
if (!type || !existsSync(resolve(root, row.path))) continue;
+ if (type.kind === 'video' && row.reel) {
+ parts.push({ type: 'text', text: reelRecord(item, row, loadProof(root, item.id)) });
+ for (const frame of reelFrames({ root, path: row.path })) {
+ const buffer = await sharp(frame.buffer).resize({ width: 1280, withoutEnlargement: true }).jpeg({ quality: 85 }).toBuffer();
+ parts.push({ type: 'text', text: `Reel frame at ${frame.atSec} s` });
+ parts.push({ type: 'image', data: buffer.toString('base64'), mime: 'image/jpeg' });
+ }
+ continue;
+ }
if (type.kind === 'video') {
parts.push({ type: 'text', text: `${row.role}: video ${row.path}, probe ${JSON.stringify(row.probe || {})}. Captions burned in: ${row.captions ? 'yes' : 'unknown'}.` });
continue;
@@ -90,7 +114,10 @@ async function imageParts(item, root) {
return parts;
}
-export async function buildReviewRequest(item, { root, verification, lint }) {
+// `calibration` is the account's best posts as the X API measured them
+// (outcomes.js). Without it the editor falls back to the archive report, which
+// was scraped before X had loaded the like counts of the largest posts.
+export async function buildReviewRequest(item, { root, verification, lint, maximum = STANDARD_MAX_LENGTH, calibration = null }) {
const voice = readIfExists(root, 'docs/announce-voice.md', MAX_SOURCE_CHARS);
const source = readIfExists(root, item.source?.path, MAX_SOURCE_CHARS);
const article = item.kind === 'article' ? readIfExists(root, item.article?.body, MAX_ARTICLE_CHARS) : null;
@@ -111,12 +138,12 @@ export async function buildReviewRequest(item, { root, verification, lint }) {
article ? `## Article body (Markdown)\n${article}` : null,
source ? `## Announcement pack this post came from\n${source}` : null,
voice ? `## House voice contract\n${voice}` : null,
- `## The account's best-performing posts, for calibration\n${JSON.stringify(topPosts(root), null, 2)}`,
+ `## The account's best-performing posts, for calibration\n${JSON.stringify(calibration?.length ? calibration : topPosts(root), null, 2)}`,
'Review the post now. Respond with the JSON object only.',
]
.filter(Boolean)
.join('\n\n');
- return { system: SYSTEM, parts: [{ type: 'text', text }, ...(await imageParts(item, root))] };
+ return { system: SYSTEM.replace('{MAX}', String(maximum)), parts: [{ type: 'text', text }, ...(await imageParts(item, root))] };
}
export function parseReview(raw) {
diff --git a/api/_lib/x-content/quality.js b/api/_lib/x-content/quality.js
index 9ebf6af15..43a102450 100644
--- a/api/_lib/x-content/quality.js
+++ b/api/_lib/x-content/quality.js
@@ -83,13 +83,26 @@ export const BANNED_PHRASES = [
/\bstay tuned\b/i,
];
+// X cuts a post off at 280 weighted characters for a standard account and lets
+// a Premium account write up to 25,000. @trythreews is Premium, and its head
+// posts over 280 measured about twice the likes of the ones under it (140
+// against 76, head posts since August 2026), so the wall is a queue setting
+// (`quality.maximumLength`) and not a constant. Anything below 280 is ignored:
+// a queue cannot make the limit stricter than X does.
+export const STANDARD_MAX_LENGTH = 280;
+export const PREMIUM_MAX_LENGTH = 25_000;
+export function maxLengthOf(quality) {
+ const wanted = Number(quality?.maximumLength);
+ return Number.isFinite(wanted) && wanted > STANDARD_MAX_LENGTH ? Math.min(Math.floor(wanted), PREMIUM_MAX_LENGTH) : STANDARD_MAX_LENGTH;
+}
+
// Acronyms and tickers that are legitimately written in capitals.
const ALLCAPS_TERMS = new Set(['THREE', 'HTTP', 'HTTPS', 'JSON', 'GLTF', 'HTML', 'WEBP', 'NVIDIA', 'OAUTH', 'MCP', 'GPU', 'GPUS']);
// `minimum` applies to the head of a post; replies may be short. `requireUrl`
// is false for parts whose item carries its link somewhere else (a reply, or a
// quoted Article).
-export function copyProblems(text, { minimum = 100, maximum = 280, requireUrl = true } = {}) {
+export function copyProblems(text, { minimum = 100, maximum = STANDARD_MAX_LENGTH, requireUrl = true } = {}) {
const problems = [];
const copy = String(text || '').trim();
const weight = weightedLength(copy);
diff --git a/api/_lib/x-content/queue.js b/api/_lib/x-content/queue.js
index 87a8a36b7..5fe396db8 100644
--- a/api/_lib/x-content/queue.js
+++ b/api/_lib/x-content/queue.js
@@ -7,11 +7,12 @@
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
-import { copyProblems, copySimilarity, hasUrl, weightedLength } from './quality.js';
+import { copyProblems, copySimilarity, hasUrl, maxLengthOf, weightedLength } from './quality.js';
import { attachmentProblems, mediaProblems, mediaType } from './media.js';
import { MARKDOWN_ENTITY_BUDGET, markdownToContentState } from './articles.js';
import { claimProblems, languageProblems } from './editorial.js';
import { approvalProblems } from './review.js';
+import { proofProblems, scenarioProblems } from './reel.js';
export const QUEUE_PATH = 'data/x-content/queue.json';
export const STATUSES = ['draft', 'review', 'approved', 'paused', 'posted'];
@@ -62,7 +63,7 @@ function textFromProblems(post, root) {
return readFileSync(path, 'utf8').trim() === String(post.text || '').trim() ? [] : [`text differs from ${post.textFrom}; copy the reviewed pack text into the queue`];
}
-function postProblems(item, root, { headMinimum, headNeedsUrl }) {
+function postProblems(item, root, { headMinimum, headNeedsUrl, maximum }) {
const problems = [];
const posts = item.posts || [];
const itemLinks = posts.some((post) => hasUrl(post.text));
@@ -71,7 +72,7 @@ function postProblems(item, root, { headMinimum, headNeedsUrl }) {
posts.forEach((post, index) => {
const label = index === 0 ? 'head' : `reply ${index}`;
problems.push(...textFromProblems(post, root).map((problem) => `${label}: ${problem}`));
- for (const problem of copyProblems(post.text, { minimum: index === 0 ? headMinimum : 1, requireUrl: false })) {
+ for (const problem of copyProblems(post.text, { minimum: index === 0 ? headMinimum : 1, maximum, requireUrl: false })) {
problems.push(`${label}: ${problem}`);
}
for (const problem of attachmentProblems(post.media)) problems.push(`${label}: ${problem}`);
@@ -117,8 +118,19 @@ function articleProblems(item, root) {
return problems;
}
-export function validateItem(item, root) {
+// The queue's own quality settings, for a caller that holds one item and not
+// the queue it came from.
+function qualityAt(root) {
+ try {
+ return loadQueue(root).quality || {};
+ } catch {
+ return {};
+ }
+}
+
+export function validateItem(item, root, { quality = qualityAt(root) } = {}) {
const problems = [];
+ const maximum = maxLengthOf(quality);
if (!/^[a-z0-9][a-z0-9-]{1,80}$/.test(String(item.id || ''))) problems.push('id must be a lowercase slug');
if (!STATUSES.includes(item.status)) problems.push(`status must be one of ${STATUSES.join(', ')}`);
if (!KINDS.includes(item.kind)) problems.push(`kind must be one of ${KINDS.join(', ')}`);
@@ -134,7 +146,8 @@ export function validateItem(item, root) {
}
if (item.priority !== undefined && !(Number(item.priority) >= -50 && Number(item.priority) <= 50)) problems.push('priority is an owner boost from -50 to 50');
for (const probe of item.probes || []) {
- if (!['api', 'browser', 'command'].includes(probe.type)) problems.push(`probe type ${probe.type} must be api, browser, or command`);
+ if (!['api', 'browser', 'command', 'scenario'].includes(probe.type)) problems.push(`probe type ${probe.type} must be api, browser, command, or scenario`);
+ if (probe.type === 'scenario' && !item.scenario) problems.push('a scenario probe needs the item to carry a `scenario`');
if (probe.type === 'api' && !/^https:\/\//.test(String(probe.url || ''))) problems.push('api probes need an https url');
if (probe.type === 'command' && !Array.isArray(probe.argv)) problems.push('command probes need an argv array');
}
@@ -145,14 +158,14 @@ export function validateItem(item, root) {
if (!item.textOnly && !item.posts[0].media?.length) {
problems.push('head post has no media; attach an image, GIF, or video, or set "textOnly": true on purpose');
}
- problems.push(...postProblems(item, root, { headMinimum: 100, headNeedsUrl: true }));
+ problems.push(...postProblems(item, root, { headMinimum: 100, headNeedsUrl: true, maximum }));
}
}
if (item.kind === 'article') {
problems.push(...articleProblems(item, root));
// Follow-up posts quote the published Article, so the Article itself is
// the link and the head may be short.
- if (item.posts?.length) problems.push(...postProblems(item, root, { headMinimum: 40, headNeedsUrl: false }));
+ if (item.posts?.length) problems.push(...postProblems(item, root, { headMinimum: 40, headNeedsUrl: false, maximum }));
}
// Editorial standards that can be judged offline block at every stage.
@@ -162,6 +175,15 @@ export function validateItem(item, root) {
}
for (const finding of claimProblems(item)) if (finding.severity === 'blocking') problems.push(`${finding.rule}: ${finding.message}`);
+ // A scenario is the item's claim that the feature works. It has to be
+ // runnable as written, it has to be the item's probe, and the reel on the
+ // head post has to be the one a passing run of it filmed.
+ if (item.scenario !== undefined) {
+ problems.push(...scenarioProblems(item.scenario).map((problem) => `scenario: ${problem}`));
+ if (!(item.probes || []).some((probe) => probe.type === 'scenario')) problems.push('scenario: declare { "type": "scenario" } in probes so every review runs it again');
+ if (['review', 'approved'].includes(item.status)) problems.push(...proofProblems(item, root).map((problem) => `proof: ${problem}`));
+ }
+
// Approval is only real while a passing review covers these exact bytes.
if (item.status === 'approved') problems.push(...approvalProblems(item, root).map((problem) => `review: ${problem}`));
return problems;
@@ -176,7 +198,7 @@ export function validateQueue(queue, root, { state = null } = {}) {
const notes = [];
const ids = new Set();
for (const item of queue.items || []) {
- const list = validateItem(item, root);
+ const list = validateItem(item, root, { quality: queue.quality || {} });
if (ids.has(item.id)) list.push('id is duplicated');
ids.add(item.id);
problems[item.id] = list;
diff --git a/api/_lib/x-content/reel.js b/api/_lib/x-content/reel.js
new file mode 100644
index 000000000..4464d1d90
--- /dev/null
+++ b/api/_lib/x-content/reel.js
@@ -0,0 +1,836 @@
+// Proof reels: a post's video is a filmed, passing end-to-end run of the
+// feature it announces.
+//
+// A fact check proves a page says something. It cannot prove the feature does
+// it, and every post the owner has pulled was pulled for that gap: the copy
+// matched the page, and the product did not live up to the copy. A scenario
+// closes it. One list of steps is, at once:
+//
+// the probe every step must pass against the live product, or there is no
+// reel and therefore no post
+// the video the run is filmed, so the media cannot show anything the
+// product did not do
+// the captions each step may carry the sentence that explains it
+// the evidence what the run read off the screen (`read`), what it waited
+// for (`expect`), and what the server answered (`awaits`) are
+// the facts a claim may cite
+//
+// Filming in real time does not work here. A headless browser renders WebGL in
+// software at one to three frames a second, and a recorder pads that to 25 by
+// repeating frames, which is what made the first Portal clip read as a slide
+// show. So the page's clock is taken over instead: it is advanced one frame at
+// a time and a screenshot is taken after each advance. Every frame of the reel
+// is a real, distinct frame at exactly 1/fps of page time, and the render speed
+// of the machine only decides how long the job takes.
+//
+// Waiting is not filmed. While a step waits on the network the clock runs in
+// real time, and the reel shows a badge saying how long was cut, so a reel
+// never implies a result was instant when it was not.
+//
+// Nothing is drawn over the product. Captions, the cut badge, and the stamp
+// that says which production commit was filmed and when all live in a bar
+// under the page, so no caption can hide a control and no viewer has to wonder
+// what was behind it. Only the pointer is drawn on the page, because a viewer
+// has to see what was clicked.
+//
+// A browser and ffmpeg are needed, so reels are made where posts are reviewed
+// and never in production. Production checks the record (proofProblems).
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { chromeStylesheet } from './site-chrome.js';
+import { parseFfmpegProbe } from './media.js';
+
+export const PROOF_DIR = 'data/x-content/proofs';
+export const proofPath = (id) => `${PROOF_DIR}/${id}.json`;
+export const reelPath = (id) => `public/x-media/${id}/reel.mp4`;
+
+// Logical frame, device scale, and the height of the bar under the page. A
+// small logical viewport is deliberate: the page lays out for a small screen,
+// so its text and controls come out large in the final frame and stay readable
+// in a phone timeline. The page is filmed at width by (height - bar); the
+// output is width * scale by height * scale, always even.
+export const FORMATS = {
+ landscape: { width: 1024, height: 576, bar: 80, scale: 1.25 },
+ square: { width: 720, height: 720, bar: 104, scale: 1.5 },
+ portrait: { width: 540, height: 675, bar: 108, scale: 2 },
+};
+export const DEFAULT_FPS = 30;
+export const PROOF_MAX_AGE_DAYS = 14;
+// Under this share of changing frames a reel is a still with a progress bar.
+export const MIN_MOTION = 0.15;
+
+const LIMITS = {
+ settleMs: [0, 60_000],
+ holdMs: [100, 15_000],
+ waitMs: [0, 180_000],
+ withinMs: [1000, 300_000],
+ filmedWaitFrames: 20 * DEFAULT_FPS,
+};
+const CUT_BADGE_AFTER_SEC = 2;
+const CUT_BADGE_FRAMES = 45;
+const MOVE_FRAMES = 12;
+const LOCATE_FRAMES = 60;
+const RIPPLE_FRAMES = 9;
+const TYPE_FRAMES_PER_CHAR = 2;
+
+// `caption` is last on purpose: any step may carry a caption as well as its
+// action, and a step is only a caption step when it does nothing else.
+export const STEP_KINDS = ['goto', 'hold', 'click', 'hover', 'type', 'press', 'expect', 'read', 'drag', 'scroll', 'wait', 'caption'];
+
+// The steps that can cause a request, and so may carry `awaits`.
+const ACTIONS = ['click', 'press', 'type'];
+
+export const stepKind = (step) => STEP_KINDS.find((kind) => step && Object.hasOwn(step, kind)) || null;
+
+const between = (value, [low, high]) => Number.isFinite(Number(value)) && Number(value) >= low && Number(value) <= high;
+const targetOf = (value) => (typeof value === 'string' ? value : value?.selector || value?.text || '');
+
+// Problems with a scenario as written, before a browser is ever started.
+export function scenarioProblems(scenario) {
+ if (!scenario || typeof scenario !== 'object') return ['scenario must be an object with a steps list'];
+ const problems = [];
+ if (scenario.format !== undefined && !FORMATS[scenario.format]) problems.push(`format must be one of ${Object.keys(FORMATS).join(', ')}`);
+ if (scenario.fps !== undefined && !between(scenario.fps, [12, 60])) problems.push('fps must be between 12 and 60');
+ const steps = scenario.steps;
+ if (!Array.isArray(steps) || !steps.length) return [...problems, 'scenario has no steps'];
+ if (stepKind(steps[0]) !== 'goto') problems.push('the first step must be a goto, so the reel starts on a real page');
+ if (!steps.some((step) => ['expect', 'read'].includes(stepKind(step)) || step?.awaits)) {
+ problems.push('a scenario must expect, read, or await something, or it proves nothing about the feature');
+ }
+ const names = new Set();
+ steps.forEach((step, index) => {
+ const kind = stepKind(step);
+ const at = `step ${index + 1}`;
+ if (!kind) return problems.push(`${at}: needs one of ${STEP_KINDS.join(', ')}`);
+ if (step.caption !== undefined && typeof step.caption !== 'string') problems.push(`${at}: caption must be text`);
+ if (String(step.caption || '').length > 90) problems.push(`${at}: caption is ${step.caption.length} characters; a viewer reads about 90 in the time a step takes`);
+ if (step.awaits !== undefined) {
+ if (!ACTIONS.includes(kind)) problems.push(`${at}: awaits belongs on the action that causes the request (${ACTIONS.join(', ')})`);
+ if (typeof step.awaits !== 'string' || !step.awaits.startsWith('/')) problems.push(`${at}: awaits needs the path of the request the action causes, such as "/api/galaxy"`);
+ }
+ switch (kind) {
+ case 'goto':
+ if (!/^https:\/\//.test(String(step.goto))) problems.push(`${at}: goto needs an https url`);
+ if (step.settle !== undefined && !between(step.settle, LIMITS.settleMs)) problems.push(`${at}: settle is 0 to ${LIMITS.settleMs[1]} ms`);
+ break;
+ case 'hold':
+ if (!between(step.hold, LIMITS.holdMs)) problems.push(`${at}: hold is ${LIMITS.holdMs[0]} to ${LIMITS.holdMs[1]} ms of film`);
+ break;
+ case 'wait':
+ if (!between(step.wait, LIMITS.waitMs)) problems.push(`${at}: wait is up to ${LIMITS.waitMs[1]} ms`);
+ break;
+ case 'click':
+ case 'hover':
+ if (!targetOf(step[kind])) problems.push(`${at}: ${kind} needs the visible text of the control, or { "selector": "..." }`);
+ break;
+ case 'type':
+ if (typeof step.type !== 'string' || !step.type) problems.push(`${at}: type needs the text to type`);
+ if (!step.into) problems.push(`${at}: type needs "into": the placeholder, label, or selector of the field`);
+ break;
+ case 'press':
+ if (typeof step.press !== 'string' || !step.press) problems.push(`${at}: press needs a key name such as Enter`);
+ break;
+ case 'expect':
+ if (typeof step.expect !== 'string' || !step.expect.trim()) problems.push(`${at}: expect needs the text that only appears once the feature worked`);
+ if (step.within !== undefined && !between(step.within, LIMITS.withinMs)) problems.push(`${at}: within is ${LIMITS.withinMs[0]} to ${LIMITS.withinMs[1]} ms`);
+ break;
+ case 'read':
+ if (!/^[a-z][a-zA-Z0-9]{0,39}$/.test(String(step.read))) problems.push(`${at}: read needs a fact name such as "entries"`);
+ else if (names.has(step.read)) problems.push(`${at}: fact "${step.read}" is read twice`);
+ else names.add(step.read);
+ try {
+ new RegExp(step.match, 'i');
+ if (!step.match) problems.push(`${at}: read needs "match": a pattern whose first group is the fact`);
+ } catch (err) {
+ problems.push(`${at}: match is not a valid pattern (${err.message})`);
+ }
+ break;
+ case 'drag': {
+ const points = step.drag;
+ const valid = Array.isArray(points) && points.length === 2 && points.every((point) => Array.isArray(point) && point.length === 2 && point.every((n) => between(n, [0, 1])));
+ if (!valid) problems.push(`${at}: drag needs [[x, y], [x, y]] as fractions of the viewport, 0 to 1`);
+ break;
+ }
+ case 'scroll':
+ if (typeof step.scroll !== 'number' && !targetOf(step.scroll)) problems.push(`${at}: scroll needs a pixel distance or the text to scroll to`);
+ break;
+ default:
+ break;
+ }
+ });
+ return problems;
+}
+
+export const scenarioHash = (scenario) => createHash('sha256').update(JSON.stringify(scenario || null)).digest('hex');
+
+export function loadProof(root, id) {
+ const path = resolve(root, proofPath(id));
+ return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+}
+
+const sha256File = (path) => createHash('sha256').update(readFileSync(path)).digest('hex');
+
+// Why the proof on record does not cover this item as it is now, or [] when it
+// does. Runs everywhere, production included: it reads files, never a browser.
+export function proofProblems(item, root, now = Date.now()) {
+ if (!item.scenario) return [];
+ const proof = loadProof(root, item.id);
+ if (!proof) return [`no proof on record; run \`npm run x:content -- prove ${item.id}\``];
+ const problems = [];
+ if (!proof.passed) {
+ const failed = (proof.steps || []).find((step) => !step.ok);
+ problems.push(`the last run failed${failed ? ` at step ${failed.index} (${failed.kind} ${failed.target}): ${failed.detail}` : ''}`);
+ return problems;
+ }
+ if (proof.scenarioHash !== scenarioHash(item.scenario)) problems.push('the scenario changed after it was filmed; prove it again');
+ const age = (now - Date.parse(proof.ranAt)) / 86_400_000;
+ if (age > PROOF_MAX_AGE_DAYS) problems.push(`the reel was filmed ${Math.floor(age)} days ago; the product moves, so film it again`);
+ const reel = (item.posts || []).flatMap((post) => post.media || []).find((media) => media.path === proof.video?.path);
+ if (!reel) problems.push(`the head post does not carry the reel ${proof.video?.path || ''}`);
+ else {
+ const file = resolve(root, reel.path);
+ if (existsSync(file) && sha256File(file) !== proof.video.sha256) problems.push(`${reel.path} is not the file the proof filmed`);
+ }
+ if (proof.video && proof.video.motion < MIN_MOTION) {
+ problems.push(`only ${Math.round(proof.video.motion * 100)}% of the reel's frames change; film an action, or post a still instead`);
+ }
+ return problems;
+}
+
+// A claim may cite the run: a fact it read off the screen, or a text it waited
+// for. `equals` and `contains` compare against the fact as it was read.
+export function factCheck(evidence, proof) {
+ if (!proof) return { ok: false, detail: 'no proof on record' };
+ if (!proof.passed) return { ok: false, detail: 'the last run of the scenario failed' };
+ if (evidence.responded !== undefined) {
+ const hit = (proof.responses || []).find((row) => row.path.includes(String(evidence.responded)));
+ return { ok: Boolean(hit), detail: hit ? `${hit.method} ${hit.path} answered ${hit.status} in ${hit.seconds} s` : `no step of the run awaited "${evidence.responded}"` };
+ }
+ if (evidence.saw !== undefined) {
+ const wanted = String(evidence.saw).toLowerCase();
+ const seen = (proof.saw || []).some((text) => String(text).toLowerCase().includes(wanted));
+ return { ok: seen, detail: seen ? `the run waited for and saw "${evidence.saw}"` : `no step of the run expected "${evidence.saw}"` };
+ }
+ const value = proof.facts?.[evidence.fact];
+ if (value === undefined) return { ok: false, detail: `the run read no fact named "${evidence.fact}"` };
+ if (evidence.equals !== undefined) {
+ const ok = String(value) === String(evidence.equals);
+ return { ok, detail: `the run read ${evidence.fact} = "${value}"${ok ? '' : `; the claim needs "${evidence.equals}"`}` };
+ }
+ if (evidence.contains !== undefined) {
+ const ok = String(value).toLowerCase().includes(String(evidence.contains).toLowerCase());
+ return { ok, detail: `the run read ${evidence.fact} = "${value}"${ok ? '' : `; the claim needs it to contain "${evidence.contains}"`}` };
+ }
+ return { ok: true, detail: `the run read ${evidence.fact} = "${value}"` };
+}
+
+export function formatCut(seconds) {
+ const total = Math.round(seconds);
+ if (total < 60) return `${total} s`;
+ const minutes = Math.floor(total / 60);
+ const rest = total % 60;
+ return rest ? `${minutes} min ${rest} s` : `${minutes} min`;
+}
+
+// ── In the page ─────────────────────────────────────────────────────────────
+// The pointer lives in a closed shadow root hung off <html>, not <body>: the
+// page's own text queries never see it and a framework that replaces the body
+// does not remove it.
+function installPointer({ stylesheet }) {
+ // Embedded frames get no pointer and no stylesheet of ours.
+ if (window.__reel || window.top !== window) return;
+ const host = document.createElement('div');
+ host.setAttribute('data-reel-overlay', '');
+ host.style.cssText = 'position:fixed;inset:0;z-index:2147483647;pointer-events:none';
+ const shadow = host.attachShadow({ mode: 'closed' });
+ shadow.innerHTML = `
+ <style>
+ .cursor { position: absolute; left: 0; top: 0; width: 26px; height: 26px; margin: -13px 0 0 -13px; border-radius: 50%;
+ background: rgba(255, 255, 255, .55); border: 2px solid rgba(8, 9, 12, .85); box-shadow: 0 2px 10px rgba(0, 0, 0, .5); display: none; }
+ .ripple { position: absolute; left: 0; top: 0; width: 26px; height: 26px; margin: -13px 0 0 -13px; border-radius: 50%;
+ border: 3px solid rgba(255, 255, 255, .9); display: none; }
+ </style>
+ <div class="ripple"></div><div class="cursor"></div>`;
+ const part = (name) => shadow.querySelector(`.${name}`);
+ const chrome = document.createElement('style');
+ chrome.setAttribute('data-reel-chrome', '');
+ chrome.textContent = stylesheet;
+ // An init script can run before <html> exists, so the first observer waits
+ // for the root element and the second keeps the overlay attached to it.
+ let watching = null;
+ const mount = () => {
+ const rootNode = document.documentElement;
+ if (!rootNode) return;
+ if (!host.isConnected) rootNode.appendChild(host);
+ if (!chrome.isConnected) rootNode.appendChild(chrome);
+ if (watching !== rootNode) {
+ watching = rootNode;
+ new MutationObserver(mount).observe(rootNode, { childList: true });
+ }
+ };
+ mount();
+ new MutationObserver(mount).observe(document, { childList: true });
+ window.__reel = {
+ cursor(x, y) {
+ const node = part('cursor');
+ node.style.display = 'block';
+ node.style.transform = `translate(${x}px, ${y}px)`;
+ },
+ rest() {
+ part('cursor').style.display = 'none';
+ },
+ // The ring is sized from the page clock, so it grows one step per filmed
+ // frame instead of at whatever rate the compositor is running.
+ ripple(x, y, ms) {
+ const node = part('ripple');
+ const start = performance.now();
+ node.style.display = 'block';
+ const tick = () => {
+ const t = Math.min(1, (performance.now() - start) / ms);
+ node.style.transform = `translate(${x}px, ${y}px) scale(${1 + t * 2.2})`;
+ node.style.opacity = String(1 - t);
+ if (t < 1) requestAnimationFrame(tick);
+ else node.style.display = 'none';
+ };
+ tick();
+ },
+ };
+}
+
+// ── The bar ─────────────────────────────────────────────────────────────────
+// A page of its own, in the same browser, rendered at the same device scale and
+// stacked under every frame. It is only photographed again when what it says
+// changes.
+const FONT_FILE = fileURLToPath(new URL('../../../public/fonts/inter-latin.woff2', import.meta.url));
+
+function barDocument() {
+ const font = existsSync(FONT_FILE) ? `@font-face { font-family: Inter; font-weight: 100 900; src: url(data:font/woff2;base64,${readFileSync(FONT_FILE).toString('base64')}) format('woff2'); }` : '';
+ return `<!doctype html><meta charset="utf-8"><style>
+ ${font}
+ * { box-sizing: border-box; margin: 0; }
+ html, body { height: 100%; background: #07080b; color: #fff; font-family: Inter, ui-sans-serif, system-ui, sans-serif; overflow: hidden; }
+ body { display: grid; grid-template-columns: 1fr auto; align-items: center; gap: 0 4vw; padding: 0 4vw; border-top: 1px solid rgba(255, 255, 255, .1); }
+ #caption { font-size: min(34vh, 4.1vw); font-weight: 600; line-height: 1.22; letter-spacing: -.01em; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+ aside { display: grid; justify-items: end; gap: .5vh; text-align: right; white-space: nowrap; }
+ #badge { font-size: min(19vh, 2.2vw); font-weight: 600; color: #ffd479; min-height: 1.2em; }
+ #stamp { font-size: min(16vh, 1.85vw); font-weight: 500; color: rgba(255, 255, 255, .62); font-variant-numeric: tabular-nums; }
+ </style><div id="caption"></div><aside><div id="badge"></div><div id="stamp"></div></aside>`;
+}
+
+class Bar {
+ constructor(page) {
+ this.page = page;
+ this.state = { caption: '', badge: '', stamp: '' };
+ this.shot = null;
+ }
+
+ static async open(context, format, stamp) {
+ const page = await context.newPage();
+ await page.setViewportSize({ width: format.width, height: format.bar });
+ await page.setContent(barDocument(), { waitUntil: 'load' });
+ await page.evaluate(() => document.fonts.ready);
+ const bar = new Bar(page);
+ await bar.set({ stamp });
+ return bar;
+ }
+
+ async set(change) {
+ const next = { ...this.state, ...change };
+ if (JSON.stringify(next) === JSON.stringify(this.state) && this.shot) return;
+ this.state = next;
+ await this.page.evaluate((state) => {
+ for (const [id, text] of Object.entries(state)) document.getElementById(id).textContent = text;
+ }, next);
+ this.shot = await this.page.screenshot({ type: 'png', scale: 'device' });
+ }
+}
+
+const visibleText = () => (document.querySelector('main')?.innerText || document.body?.innerText || '').replace(/[ \t ]+/g, ' ');
+
+// ── The take ────────────────────────────────────────────────────────────────
+class Take {
+ constructor(page, { fps, film, framesDir, bar, size, compose }) {
+ this.page = page;
+ this.bar = bar;
+ this.size = size;
+ this.compose = compose;
+ this.fps = fps;
+ this.film = film;
+ this.framesDir = framesDir;
+ this.frameMs = 1000 / fps;
+ this.count = 0;
+ this.changes = 0;
+ this.lastHash = null;
+ this.paused = false;
+ this.badgeFrames = 0;
+ this.cursor = null;
+ this.cuts = [];
+ }
+
+ async pause() {
+ if (this.paused) return;
+ const pageNow = await this.page.evaluate(() => Date.now());
+ await this.page.clock.pauseAt(pageNow + 50);
+ this.paused = true;
+ }
+
+ async resume() {
+ if (!this.paused) return;
+ await this.page.clock.resume();
+ this.paused = false;
+ }
+
+ async frame() {
+ await this.pause();
+ await this.page.clock.runFor(this.frameMs);
+ if (this.badgeFrames > 0 && --this.badgeFrames === 0) await this.bar.set({ badge: '' });
+ if (!this.film) return;
+ const shot = await this.page.screenshot({ type: 'png', scale: 'device', timeout: 60_000 });
+ // Motion is measured on the product alone, so a caption changing never
+ // counts as the feature doing something.
+ const hash = createHash('sha1').update(shot).digest('hex');
+ if (this.lastHash && hash !== this.lastHash) this.changes++;
+ this.lastHash = hash;
+ const frame = await this.compose(shot, this.bar.shot, this.size);
+ writeFileSync(join(this.framesDir, `f${String(++this.count).padStart(6, '0')}.jpg`), frame);
+ }
+
+ async frames(count) {
+ for (let index = 0; index < count; index++) await this.frame();
+ }
+
+ pointer(method, ...args) {
+ return this.page.evaluate(([name, values]) => window.__reel?.[name]?.(...values), [method, args]);
+ }
+
+ // Anything that waits on the world runs on the real clock and is not filmed.
+ // A cut long enough to notice is labelled on the frames that follow it.
+ async unfilmed(index, work) {
+ const started = Date.now();
+ await this.resume();
+ try {
+ return await work();
+ } finally {
+ const seconds = (Date.now() - started) / 1000;
+ await this.pause();
+ if (seconds >= CUT_BADGE_AFTER_SEC && this.count > 0) {
+ this.cuts.push({ afterStep: index, seconds: Math.round(seconds * 10) / 10 });
+ await this.bar.set({ badge: `cut ${formatCut(seconds)}` });
+ this.badgeFrames = CUT_BADGE_FRAMES;
+ }
+ }
+ }
+
+ async moveTo(x, y) {
+ const viewport = this.page.viewportSize();
+ const from = this.cursor || { x: viewport.width * 0.5, y: viewport.height * 0.62 };
+ for (let step = 1; step <= MOVE_FRAMES; step++) {
+ const t = step / MOVE_FRAMES;
+ const eased = t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2;
+ const at = { x: from.x + (x - from.x) * eased, y: from.y + (y - from.y) * eased };
+ await this.page.mouse.move(at.x, at.y);
+ await this.pointer('cursor', at.x, at.y);
+ await this.frame();
+ }
+ this.cursor = { x, y };
+ }
+}
+
+// Exact names are tried before partial ones. A partial match is how "Search"
+// once resolved to a "Clear search" button that sat earlier in the page, and
+// the reel filmed the query being wiped instead of run.
+function candidatesFor(page, text, field) {
+ const named = (exact) =>
+ field
+ ? [page.getByPlaceholder(text, { exact }), page.getByLabel(text, { exact }), page.getByRole('textbox', { name: text, exact }), page.getByRole('searchbox', { name: text, exact }), page.getByRole('combobox', { name: text, exact })]
+ : [page.getByRole('button', { name: text, exact }), page.getByRole('link', { name: text, exact }), page.getByRole('tab', { name: text, exact }), page.getByRole('menuitem', { name: text, exact }), page.getByText(text, { exact })];
+ return [...named(true), ...named(false)];
+}
+
+async function locateNow(page, target, field) {
+ if (typeof target === 'object' && target?.selector) {
+ const chosen = page.locator(target.selector).filter({ visible: true });
+ return (await chosen.count().catch(() => 0)) > 0 ? chosen.first() : null;
+ }
+ for (const candidate of candidatesFor(page, targetOf(target), field)) {
+ const visible = candidate.filter({ visible: true });
+ if ((await visible.count().catch(() => 0)) > 0) return visible.first();
+ }
+ return null;
+}
+
+// A control that is about to appear is waited for on the page's clock, which
+// is filmed: the viewer sees the same second pass that the run did.
+async function locate(take, target, { field = false } = {}) {
+ for (let waited = 0; waited <= LOCATE_FRAMES; waited++) {
+ const found = await locateNow(take.page, target, field);
+ if (found) return found;
+ await take.frame();
+ }
+ throw new Error(`nothing visible matches "${targetOf(target)}"`);
+}
+
+async function centreOf(locator) {
+ await locator.scrollIntoViewIfNeeded({ timeout: 10_000 });
+ const box = await locator.boundingBox();
+ if (!box) throw new Error('the control has no box on screen');
+ return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+}
+
+async function waitForText(page, text, timeout) {
+ await page.getByText(text, { exact: false }).filter({ visible: true }).first().waitFor({ state: 'visible', timeout });
+}
+
+// The request an action must cause. The listener is armed before the action
+// and awaited after it, off the film, on the real clock.
+function armResponse(take, step) {
+ if (!step.awaits) return null;
+ const started = Date.now();
+ const pending = take.page
+ .waitForResponse((response) => new URL(response.url()).pathname.startsWith(step.awaits), { timeout: step.within ?? 60_000 })
+ .then((response) => ({ method: response.request().method(), path: new URL(response.url()).pathname, status: response.status(), seconds: Math.round((Date.now() - started) / 100) / 10 }));
+ // The action may throw first; this promise must not become an unhandled
+ // rejection while nothing is awaiting it yet.
+ pending.catch(() => {});
+ return pending;
+}
+
+async function settleResponse(take, step, index, run, pending) {
+ if (!pending) return '';
+ const hit = await take.unfilmed(index, () => pending).catch(() => {
+ throw new Error(`no request to ${step.awaits} answered within ${(step.within ?? 60_000) / 1000} s`);
+ });
+ if (hit.status >= 400) throw new Error(`${hit.method} ${hit.path} answered HTTP ${hit.status}`);
+ run.responses.push(hit);
+ return `; ${hit.method} ${hit.path} answered ${hit.status} in ${hit.seconds} s`;
+}
+
+const STEPS = {
+ async goto(take, step, index) {
+ await take.unfilmed(index, async () => {
+ const response = await take.page.goto(step.goto, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+ if (response && response.status() >= 400) throw new Error(`HTTP ${response.status()}`);
+ await take.page.waitForLoadState('networkidle', { timeout: 15_000 }).catch(() => {});
+ await take.page.waitForTimeout(step.settle ?? 6000);
+ });
+ take.cursor = null;
+ return `loaded ${step.goto}`;
+ },
+ async hold(take, step) {
+ await take.frames(Math.round((step.hold / 1000) * take.fps));
+ return `${step.hold} ms`;
+ },
+ async caption() {
+ return 'caption set';
+ },
+ async wait(take, step, index) {
+ await take.unfilmed(index, () => take.page.waitForTimeout(step.wait));
+ return `${step.wait} ms, not filmed`;
+ },
+ async click(take, step, index, run) {
+ const at = await centreOf(await locate(take, step.click));
+ await take.moveTo(at.x, at.y);
+ const pending = armResponse(take, step);
+ await take.pointer('ripple', at.x, at.y, RIPPLE_FRAMES * take.frameMs);
+ await take.page.mouse.click(at.x, at.y);
+ await take.frames(RIPPLE_FRAMES);
+ // The pointer has said what was clicked. Left in place it covers the
+ // control's own label for the rest of the reel.
+ await take.pointer('rest');
+ return `clicked${await settleResponse(take, step, index, run, pending)}`;
+ },
+ async hover(take, step) {
+ const at = await centreOf(await locate(take, step.hover));
+ await take.moveTo(at.x, at.y);
+ await take.frames(6);
+ return 'hovered';
+ },
+ async type(take, step, index, run) {
+ const field = await locate(take, step.into, { field: true });
+ const at = await centreOf(field);
+ await take.moveTo(at.x, at.y);
+ await take.page.mouse.click(at.x, at.y);
+ await take.frames(4);
+ const pending = armResponse(take, step);
+ for (const char of step.type) {
+ await take.page.keyboard.type(char);
+ await take.frames(TYPE_FRAMES_PER_CHAR);
+ }
+ return `typed ${step.type.length} characters${await settleResponse(take, step, index, run, pending)}`;
+ },
+ async press(take, step, index, run) {
+ const pending = armResponse(take, step);
+ await take.page.keyboard.press(step.press);
+ await take.frames(6);
+ return `pressed ${step.press}${await settleResponse(take, step, index, run, pending)}`;
+ },
+ async expect(take, step, index) {
+ const within = step.within ?? 45_000;
+ if (step.film) {
+ const deadline = Date.now() + within;
+ const target = take.page.getByText(step.expect, { exact: false }).filter({ visible: true });
+ for (let filmed = 0; filmed < LIMITS.filmedWaitFrames; filmed++) {
+ if ((await target.count()) > 0) return `appeared after ${filmed} filmed frames`;
+ if (Date.now() > deadline) break;
+ await take.frame();
+ }
+ throw new Error(`"${step.expect}" did not appear within ${within} ms`);
+ }
+ const started = Date.now();
+ await take.unfilmed(index, () => waitForText(take.page, step.expect, within));
+ return `appeared after ${((Date.now() - started) / 1000).toFixed(1)} s`;
+ },
+ async read(take, step, _index, run) {
+ const scope = step.selector ? await take.page.locator(step.selector).first().innerText({ timeout: 10_000 }) : await take.page.evaluate(visibleText);
+ const match = new RegExp(step.match, 'i').exec(scope);
+ if (!match) throw new Error(`the page shows nothing matching /${step.match}/`);
+ run.facts[step.read] = String(match[1] ?? match[0]).trim();
+ return `${step.read} = "${run.facts[step.read]}"`;
+ },
+ async drag(take, step) {
+ const viewport = take.page.viewportSize();
+ const [[x1, y1], [x2, y2]] = step.drag.map(([x, y]) => [x * viewport.width, y * viewport.height]);
+ await take.moveTo(x1, y1);
+ await take.page.mouse.down();
+ const count = Math.max(6, Math.round(((step.ms ?? 1500) / 1000) * take.fps));
+ for (let index = 1; index <= count; index++) {
+ const t = index / count;
+ const at = { x: x1 + (x2 - x1) * t, y: y1 + (y2 - y1) * t };
+ await take.page.mouse.move(at.x, at.y);
+ await take.pointer('cursor', at.x, at.y);
+ await take.frame();
+ }
+ await take.page.mouse.up();
+ take.cursor = { x: x2, y: y2 };
+ return `dragged over ${count} frames`;
+ },
+ async scroll(take, step) {
+ const count = Math.max(6, Math.round(((step.ms ?? 1000) / 1000) * take.fps));
+ let distance = step.scroll;
+ if (typeof distance !== 'number') {
+ const box = await (await locate(take, step.scroll)).boundingBox();
+ if (!box) throw new Error('the scroll target has no box on screen');
+ distance = box.y - take.page.viewportSize().height * 0.3;
+ }
+ for (let index = 0; index < count; index++) {
+ await take.page.mouse.wheel(0, distance / count);
+ await take.frame();
+ }
+ return `scrolled ${Math.round(distance)} px`;
+ },
+};
+
+// One frame of the reel: the page on top, the bar under it.
+async function composer() {
+ const { default: sharp } = await import('sharp');
+ return (shot, bar, size) =>
+ sharp({ create: { width: size.width, height: size.height, channels: 3, background: '#07080b' } })
+ .composite([
+ { input: shot, top: 0, left: 0 },
+ { input: bar, top: size.page, left: 0 },
+ ])
+ .jpeg({ quality: 92, chromaSubsampling: '4:4:4' })
+ .toBuffer();
+}
+
+// WebGL is rendered in software, because the machines that make reels have no
+// GPU. The last two flags are what make filming practical: without them the
+// page itself is composited through the same software Vulkan device as the
+// scene, and one frame of a plain list page measured 3.5 to 15 seconds. With
+// the page composited on the CPU the same frame takes about 250 ms, and WebGL
+// still runs on SwiftShader exactly as before.
+const BROWSER_ARGS = ['--use-gl=angle', '--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist', '--disable-gpu-compositing', '--disable-gpu-rasterization'];
+
+// Runs the scenario against the live product. With `film` false no frame is
+// captured, which is the fast path a review uses to confirm the feature still
+// works and still shows the facts the reel shows.
+export async function runScenario(scenario, { film = true, stamp = '', framesDir = null, failureShot = null } = {}) {
+ const { chromium } = await import('playwright');
+ const format = FORMATS[scenario.format || 'landscape'];
+ const fps = scenario.fps || DEFAULT_FPS;
+ const size = { width: Math.round(format.width * format.scale), height: Math.round(format.height * format.scale), page: Math.round((format.height - format.bar) * format.scale) };
+ const browser = await chromium.launch({ args: BROWSER_ARGS });
+ const run = { passed: true, steps: [], facts: {}, saw: [], responses: [], cuts: [], frames: 0, changes: 0, fps, width: size.width, height: size.height };
+ try {
+ const context = await browser.newContext({ viewport: { width: format.width, height: format.height - format.bar }, deviceScaleFactor: format.scale, reducedMotion: 'no-preference' });
+ const bar = await Bar.open(context, format, stamp);
+ const page = await context.newPage();
+ await page.clock.install();
+ await page.addInitScript(installPointer, { stylesheet: chromeStylesheet(scenario.hide) });
+ const take = new Take(page, { fps, film, framesDir, bar, size, compose: film ? await composer() : null });
+
+ for (const [offset, step] of scenario.steps.entries()) {
+ const index = offset + 1;
+ const kind = stepKind(step);
+ const started = Date.now();
+ const framesBefore = take.count;
+ const row = { index, kind, target: targetOf(step[kind]) || String(step[kind]) };
+ try {
+ if (step.caption !== undefined) await bar.set({ caption: step.caption });
+ row.detail = await STEPS[kind](take, step, index, run);
+ if (kind === 'expect') run.saw.push(step.expect);
+ row.ok = true;
+ } catch (err) {
+ row.ok = false;
+ row.detail = String(err.message || err).split('\n')[0];
+ run.passed = false;
+ if (failureShot) await page.screenshot({ path: failureShot, timeout: 30_000 }).catch(() => {});
+ }
+ row.ms = Date.now() - started;
+ row.frames = take.count - framesBefore;
+ run.steps.push(row);
+ if (!row.ok) break;
+ }
+ run.frames = take.count;
+ run.changes = take.changes;
+ run.cuts = take.cuts;
+ } finally {
+ await browser.close();
+ }
+ return run;
+}
+
+export function ffmpegPath(root) {
+ const bundled = resolve(root, 'node_modules/ffmpeg-static/ffmpeg');
+ return existsSync(bundled) ? bundled : 'ffmpeg';
+}
+
+// Frames in, an X-ready clip out: H.264 high, yuv420p, constant frame rate,
+// moov atom first so it plays before it has finished downloading.
+export function encodeReel({ root, framesDir, out, fps }) {
+ mkdirSync(dirname(out), { recursive: true });
+ const ffmpeg = ffmpegPath(root);
+ const encode = spawnSync(
+ ffmpeg,
+ ['-y', '-hide_banner', '-loglevel', 'error', '-framerate', String(fps), '-i', join(framesDir, 'f%06d.jpg'), '-vf', 'scale=trunc(iw/2)*2:trunc(ih/2)*2', '-c:v', 'libx264', '-profile:v', 'high', '-preset', 'slow', '-crf', '19', '-pix_fmt', 'yuv420p', '-r', String(fps), '-movflags', '+faststart', '-an', out],
+ { encoding: 'utf8' },
+ );
+ if (encode.status !== 0) throw new Error(`ffmpeg failed: ${String(encode.stderr || encode.error?.message || '').trim().split('\n').slice(-2).join(' | ')}`);
+ const probe = parseFfmpegProbe(spawnSync(ffmpeg, ['-hide_banner', '-i', out], { encoding: 'utf8' }).stderr || '');
+ if (!probe) throw new Error(`could not read the encoded reel ${out}`);
+ return probe;
+}
+
+// Still frames out of a finished reel, for the editor, which cannot watch video.
+export function reelFrames({ root, path, count = 4 }) {
+ const ffmpeg = ffmpegPath(root);
+ const file = resolve(root, path);
+ const probe = parseFfmpegProbe(spawnSync(ffmpeg, ['-hide_banner', '-i', file], { encoding: 'utf8' }).stderr || '');
+ if (!probe) return [];
+ const dir = mkdtempSync(join(tmpdir(), 'reel-frames-'));
+ try {
+ const frames = [];
+ for (let index = 0; index < count; index++) {
+ const at = probe.durationSec * ((index + 0.6) / count);
+ const out = join(dir, `k${index}.jpg`);
+ const cut = spawnSync(ffmpeg, ['-y', '-hide_banner', '-loglevel', 'error', '-ss', at.toFixed(2), '-i', file, '-frames:v', '1', '-q:v', '3', out], { encoding: 'utf8' });
+ if (cut.status === 0 && existsSync(out)) frames.push({ atSec: Math.round(at * 10) / 10, buffer: readFileSync(out) });
+ }
+ return frames;
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+}
+
+async function productionVersion(scenario) {
+ try {
+ const origin = new URL(scenario.steps[0].goto).origin;
+ const response = await fetch(`${origin}/api/version`, { signal: AbortSignal.timeout(10_000) });
+ if (!response.ok) return null;
+ const body = await response.json();
+ return { commit: body.commitShort || String(body.commit || '').slice(0, 9) || null, revision: body.runtime?.revision || null };
+ } catch {
+ return null;
+ }
+}
+
+// Films the item's scenario and writes the proof. Returns { proof, media },
+// where media is the attachment for the head post, or null when the run failed.
+export async function proveItem(item, { root, film = true, now = Date.now(), failureShot = null }) {
+ const problems = scenarioProblems(item.scenario);
+ if (problems.length) throw new Error(`scenario is not runnable: ${problems.join('; ')}`);
+ const version = await productionVersion(item.scenario);
+ const day = new Date(now).toISOString().slice(0, 10);
+ const host = new URL(item.scenario.steps[0].goto).host;
+ const stamp = item.scenario.stamp === false ? '' : `live on ${host}${version?.commit ? ` @ ${version.commit}` : ''}, ${day}`;
+ const framesDir = film ? mkdtempSync(join(tmpdir(), `reel-${item.id}-`)) : null;
+ try {
+ const run = await runScenario(item.scenario, { film, stamp, framesDir, failureShot });
+ const proof = {
+ id: item.id,
+ scenarioHash: scenarioHash(item.scenario),
+ ranAt: new Date(now).toISOString(),
+ target: version,
+ passed: run.passed,
+ steps: run.steps,
+ facts: run.facts,
+ saw: run.saw,
+ responses: run.responses,
+ cuts: run.cuts,
+ video: null,
+ };
+ let media = null;
+ if (run.passed && film) {
+ if (run.frames < run.fps) throw new Error(`the scenario filmed ${run.frames} frame(s); add hold steps so there is something to watch`);
+ const path = reelPath(item.id);
+ const probe = encodeReel({ root, framesDir, out: resolve(root, path), fps: run.fps });
+ const motion = run.frames > 1 ? Math.round((run.changes / (run.frames - 1)) * 1000) / 1000 : 0;
+ proof.video = { path, sha256: sha256File(resolve(root, path)), frames: run.frames, motion, ...probe };
+ media = { path, probe, reel: true };
+ }
+ if (film || !run.passed) {
+ const target = resolve(root, proofPath(item.id));
+ mkdirSync(dirname(target), { recursive: true });
+ writeFileSync(target, `${JSON.stringify(proof, null, '\t')}\n`);
+ }
+ return { proof, media };
+ } finally {
+ if (framesDir) rmSync(framesDir, { recursive: true, force: true });
+ }
+}
+
+// What a person would look for before writing a scenario: the controls, the
+// fields, the headings, and the lines of the page that carry a number.
+export async function scoutPage(url, { format = 'landscape', settle = 7000, shot = null, hide = [] } = {}) {
+ const { chromium } = await import('playwright');
+ const size = FORMATS[format];
+ const browser = await chromium.launch({ args: BROWSER_ARGS });
+ try {
+ const page = await browser.newPage({ viewport: { width: size.width, height: size.height }, deviceScaleFactor: size.scale });
+ await page.addInitScript(installPointer, { stylesheet: chromeStylesheet(hide) });
+ const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+ await page.waitForLoadState('networkidle', { timeout: 15_000 }).catch(() => {});
+ await page.waitForTimeout(settle);
+ if (shot) await page.screenshot({ path: shot });
+ const outline = await page.evaluate(() => {
+ const seen = (node) => {
+ const box = node.getBoundingClientRect();
+ const style = getComputedStyle(node);
+ return box.width > 0 && box.height > 0 && style.visibility !== 'hidden' && style.display !== 'none';
+ };
+ const clean = (text) => String(text || '').replace(/\s+/g, ' ').trim();
+ const unique = (list) => [...new Set(list.filter(Boolean))];
+ const inMain = (node) => !node.closest('nav, header, footer, [data-reel-overlay]');
+ const pick = (selector, read, limit) => unique([...document.querySelectorAll(selector)].filter((node) => seen(node) && inMain(node)).map(read)).slice(0, limit);
+ const text = (document.querySelector('main')?.innerText || document.body.innerText || '').split('\n').map(clean).filter(Boolean);
+ return {
+ title: document.title,
+ headings: pick('h1, h2, h3', (node) => clean(node.innerText).slice(0, 120), 20),
+ buttons: pick('button, [role="button"], [role="tab"], summary', (node) => clean(node.innerText || node.getAttribute('aria-label')).slice(0, 60), 40),
+ links: pick('main a[href], [role="main"] a[href]', (node) => `${clean(node.innerText).slice(0, 50)} -> ${node.getAttribute('href')}`, 25),
+ fields: pick('input, textarea, select', (node) => clean(`${node.tagName.toLowerCase()}[${node.type || ''}] placeholder="${node.placeholder || ''}" label="${node.getAttribute('aria-label') || ''}" name="${node.name || ''}"`), 20),
+ canvases: [...document.querySelectorAll('canvas')].filter(seen).map((node) => `${Math.round(node.getBoundingClientRect().width)}x${Math.round(node.getBoundingClientRect().height)}`),
+ numbers: unique(text.filter((line) => /\d/.test(line) && line.length < 140)).slice(0, 40),
+ text: text.slice(0, 60),
+ };
+ });
+ return { url, status: response?.status() ?? 0, format, ...outline };
+ } finally {
+ await browser.close();
+ }
+}
diff --git a/api/_lib/x-content/review.js b/api/_lib/x-content/review.js
index 7e3b7e184..8e3c0ddfe 100644
--- a/api/_lib/x-content/review.js
+++ b/api/_lib/x-content/review.js
@@ -13,9 +13,10 @@ import { createHash } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { claimProblems, languageProblems, mediaQualityProblems } from './editorial.js';
-import { copyProblems } from './quality.js';
+import { copyProblems, maxLengthOf } from './quality.js';
import { buildReviewRequest, reviewWithEditor } from './editor.js';
import { itemTexts, verifyItem } from './verify.js';
+import { bestPosts, outcomesStore } from './outcomes.js';
export const REVIEW_MAX_AGE_DAYS = 14;
export const reviewPath = (id) => `data/x-content/reviews/${id}.json`;
@@ -36,6 +37,9 @@ export function contentHash(item, root) {
claims: item.claims || [],
mentions: item.mentions || {},
probes: item.probes || [],
+ // Absent on an item with no scenario, so the hash of every item reviewed
+ // before scenarios existed is unchanged.
+ scenario: item.scenario,
};
return createHash('sha256').update(JSON.stringify(subject)).digest('hex');
}
@@ -46,12 +50,12 @@ export function loadReview(root, id) {
}
// Offline lint for every post in an item, as structured findings.
-export function lintItem(item) {
+export function lintItem(item, { maximum } = {}) {
const findings = [];
(item.posts || []).forEach((post, index) => {
const where = index === 0 ? 'head' : `reply ${index}`;
for (const problem of languageProblems(post.text)) findings.push({ where, ...problem });
- for (const message of copyProblems(post.text, { minimum: 1, requireUrl: false })) findings.push({ where, rule: 'voice', severity: 'blocking', message });
+ for (const message of copyProblems(post.text, { minimum: 1, maximum, requireUrl: false })) findings.push({ where, rule: 'voice', severity: 'blocking', message });
});
if (item.kind === 'article' && item.article?.title) {
for (const problem of languageProblems(item.article.title)) findings.push({ where: 'article title', ...problem });
@@ -72,8 +76,19 @@ export function approvalProblems(item, root, now = Date.now()) {
return problems;
}
-export async function reviewItem(item, { root, glossary = [], env = process.env, skipEditor = false }) {
- const lint = lintItem(item);
+// A review runs fine without the measured posts; it is only calibrated worse.
+async function calibrationPosts(env) {
+ if (!env.DATABASE_URL) return null;
+ try {
+ return bestPosts((await outcomesStore().load()).posts);
+ } catch {
+ return null;
+ }
+}
+
+export async function reviewItem(item, { root, glossary = [], quality = {}, env = process.env, skipEditor = false }) {
+ const maximum = maxLengthOf(quality);
+ const lint = lintItem(item, { maximum });
for (const [index, post] of (item.posts || []).entries()) {
for (const problem of await mediaQualityProblems(post, root)) lint.push({ where: index === 0 ? 'head' : `reply ${index}`, ...problem });
}
@@ -91,7 +106,7 @@ export async function reviewItem(item, { root, glossary = [], env = process.env,
let editor = null;
if (!skipEditor) {
try {
- editor = await reviewWithEditor(await buildReviewRequest(item, { root, verification, lint }), env);
+ editor = await reviewWithEditor(await buildReviewRequest(item, { root, verification, lint, maximum, calibration: await calibrationPosts(env) }), env);
} catch (err) {
editorError = err.message;
}
@@ -114,7 +129,7 @@ export async function reviewItem(item, { root, glossary = [], env = process.env,
if (editor?.rewrite?.posts?.length) {
const draft = { ...item, posts: editor.rewrite.posts.map((text) => ({ text })) };
editor.rewriteFindings = [
- ...lintItem(draft).filter((row) => row.severity === 'blocking').map((row) => `${row.where}: ${row.message}`),
+ ...lintItem(draft, { maximum }).filter((row) => row.severity === 'blocking').map((row) => `${row.where}: ${row.message}`),
];
}
diff --git a/api/_lib/x-content/site-chrome.js b/api/_lib/x-content/site-chrome.js
new file mode 100644
index 000000000..4d425f6c7
--- /dev/null
+++ b/api/_lib/x-content/site-chrome.js
@@ -0,0 +1,29 @@
+// Floating site chrome that follows a visitor across every route and parks
+// itself over a corner of the viewport: the corner stack, the discovery card,
+// the language switcher, the walk companion, the cookie banner. Each is one of
+// our own features, which is exactly why none of them may sit in a frame that
+// announces a different one. Framing them out is a crop, not an edit of the
+// product surface.
+//
+// One list, shared by every capture path, so a new piece of chrome is hidden
+// everywhere the day it is added here.
+
+export const SITE_CHROME = [
+ '#tws-corner-stack',
+ '.tws-corner-item',
+ '.tws-disc-card',
+ '.tws-atlas-hint',
+ '.twx-i18n-fab',
+ 'lang-switcher',
+ '.walk-companion',
+ '.walk-trail-layer',
+ '.walk-c2w-fx',
+ '#cookie-banner',
+ '.cookie-banner',
+ '[data-consent-banner]',
+];
+
+// A stylesheet installed before any page script runs holds regardless of when a
+// node appears. Removing nodes once after load is not enough: the discovery
+// card is injected on a timer and reappeared during the settle.
+export const chromeStylesheet = (extra = []) => `${[...SITE_CHROME, ...extra].join(',')}{display:none !important}`;
diff --git a/api/_lib/x-content/verify.js b/api/_lib/x-content/verify.js
index c221dd8cc..cb8318f3e 100644
--- a/api/_lib/x-content/verify.js
+++ b/api/_lib/x-content/verify.js
@@ -9,6 +9,8 @@
// module a repo module's export has the stated length or value
// github-issue an issue has the stated state and label
// github-issues a repository has at least N issues matching state and label
+// proof the item's filmed scenario read the fact off the screen,
+// waited for the text, or got the answer from the server
//
// It also resolves every link in the copy, confirms every @mention is a real,
// public account, and spellchecks the prose. The CLI runs it before the editor
@@ -20,6 +22,7 @@ import { resolve } from 'node:path';
import { pathToFileURL } from 'node:url';
import { mentionsIn } from './editorial.js';
import { urlRe, urlsIn } from './quality.js';
+import { factCheck, loadProof, runScenario } from './reel.js';
const UA = 'three.ws editorial verifier (+https://three.ws)';
const normalize = (text) => String(text || '').replace(/\s+/g, ' ').trim().toLowerCase();
@@ -133,8 +136,8 @@ async function github(path) {
const hasLabel = (issue, label) => !label || issue.labels.some((row) => row.name.toLowerCase() === label.toLowerCase());
-async function evidenceCheck(evidence, { root, pages }) {
- const target = evidence.url || evidence.path || (evidence.repo ? `${evidence.repo}${evidence.number ? `#${evidence.number}` : ''}` : '');
+async function evidenceCheck(evidence, { root, pages, item }) {
+ const target = evidence.url || evidence.path || evidence.fact || evidence.saw || evidence.responded || (evidence.repo ? `${evidence.repo}${evidence.number ? `#${evidence.number}` : ''}` : '');
const base = { kind: `evidence:${evidence.type}`, target };
switch (evidence.type) {
case 'page': {
@@ -167,6 +170,8 @@ async function evidenceCheck(evidence, { root, pages }) {
const labelOk = hasLabel(issue, evidence.label);
return { ...base, ok: stateOk && labelOk, detail: `#${evidence.number} is ${issue.state}${evidence.label ? `, ${labelOk ? 'has' : 'lacks'} label "${evidence.label}"` : ''}` };
}
+ case 'proof':
+ return { ...base, ...factCheck(evidence, loadProof(root, item.id)) };
case 'github-issues': {
const params = new URLSearchParams({ state: evidence.state || 'open', per_page: '100' });
if (evidence.label) params.set('labels', evidence.label);
@@ -231,8 +236,10 @@ async function spellingChecks(item, texts, glossary) {
// browser drive the live page in a real browser: goto, click, expect text.
// command run a repo test that exercises the exact behavior the post claims
// (e.g. `node --test packages/three-token-mcp/test/burn-policy.test.mjs`).
-// Browser and command probes need a browser and a checkout, so they run at
-// review time only; the production pre-flight runs the api probes.
+// scenario run the item's filmed scenario again, without filming, and hold
+// what it reads today against what the reel shows (reel.js).
+// Browser, command and scenario probes need a browser and a checkout, so they
+// run at review time only; the production pre-flight runs the api probes.
const jsonPath = (value, path) => String(path).split('.').reduce((node, key) => (node == null ? node : node[key]), value);
@@ -290,17 +297,35 @@ async function commandProbe(probe, root) {
return { ok: false, detail: `exit ${run.status ?? run.signal}: ${tail}` };
}
+// The feature still works, and the reel still tells the truth about it: every
+// fact the run reads today has to be the fact the reel was filmed showing. A
+// count that has moved since is a stale reel, and the fix is to film it again.
+async function scenarioProbe(item, root) {
+ const proof = loadProof(root, item.id);
+ const run = await runScenario(item.scenario, { film: false });
+ if (!run.passed) {
+ const failed = run.steps.find((step) => !step.ok);
+ return { ok: false, detail: `step ${failed.index} (${failed.kind} ${failed.target}): ${failed.detail}` };
+ }
+ const drifted = Object.entries(proof?.facts || {}).filter(([name, value]) => run.facts[name] !== value);
+ if (drifted.length) {
+ return { ok: false, detail: `${drifted.map(([name, value]) => `${name} is now "${run.facts[name]}", the reel shows "${value}"`).join('; ')}; prove it again` };
+ }
+ return { ok: true, detail: `${run.steps.length} steps passed against the live product${Object.keys(run.facts).length ? `, facts unchanged (${Object.entries(run.facts).map(([name, value]) => `${name} ${value}`).join(', ')})` : ''}` };
+}
+
// `where` is 'review' (every probe) or 'publish' (api probes only).
export async function probeChecks(item, { root, where = 'review' }) {
const checks = [];
for (const probe of item.probes || []) {
if (where === 'publish' && probe.type !== 'api') continue;
- const label = probe.name || probe.url || (probe.argv || []).join(' ');
+ const label = probe.name || probe.url || (probe.argv || []).join(' ') || (probe.type === 'scenario' ? 'the filmed scenario' : '');
try {
let result;
if (probe.type === 'api') result = await apiProbe(probe);
else if (probe.type === 'browser') result = await browserProbe(probe);
else if (probe.type === 'command') result = await commandProbe(probe, root);
+ else if (probe.type === 'scenario') result = await scenarioProbe(item, root);
else result = { ok: false, detail: `unknown probe type ${probe.type}` };
checks.push({ kind: `probe:${probe.type}`, target: label, ...result });
} catch (err) {
@@ -318,7 +343,7 @@ export async function verifyItem(item, { root, glossary = [], env = process.env
for (const claim of item.claims || []) {
for (const evidence of claim.evidence || []) {
try {
- checks.push({ claim: claim.says, ...(await evidenceCheck(evidence, { root, pages })) });
+ checks.push({ claim: claim.says, ...(await evidenceCheck(evidence, { root, pages, item })) });
} catch (err) {
checks.push({ claim: claim.says, kind: `evidence:${evidence.type}`, target: evidence.url || evidence.path || evidence.repo, ok: false, detail: err.message });
}
diff --git a/scripts/x-content.mjs b/scripts/x-content.mjs
index e4d3acb89..719b3413b 100644
--- a/scripts/x-content.mjs
+++ b/scripts/x-content.mjs
@@ -8,6 +8,9 @@
// npm run x:content -- run --id slug publish one item now (owner-approved posts only)
// npm run x:content -- import <blog-slug|url> --as post|article --id slug [--lane l] [--pattern p]
// npm run x:content -- prepare-video <input> --out public/x-media/<id>/clip.mp4 [--captions file.srt] [--speed 3] [--item slug]
+// npm run x:content -- scout <url> [--format square] what a page offers a scenario: controls, fields, numbers
+// npm run x:content -- prove <slug> [--no-film] run the item's scenario against the live product and film it
+// npm run x:content -- prove --status draft film every item in a status that carries a scenario
// npm run x:content -- review <slug> [--no-editor] the editorial bar: lint, live fact checks, AI editor
// npm run x:content -- review --status review review every item awaiting review
// npm run x:content -- approve <slug> owner gate: release a reviewed item
@@ -31,6 +34,8 @@ import { dbStore, memoryStore } from '../api/_lib/x-content/state.js';
import { MAX_SPEED, VIDEO_LIMITS, mediaType, parseFfmpegProbe, videoFilterChain } from '../api/_lib/x-content/media.js';
import { weightedLength } from '../api/_lib/x-content/quality.js';
import { approvalProblems, loadReview, reviewItem } from '../api/_lib/x-content/review.js';
+import { FORMATS, proofPath, proveItem, scoutPage } from '../api/_lib/x-content/reel.js';
+import { learnLifts, outcomesStore } from '../api/_lib/x-content/outcomes.js';
const root = resolve(fileURLToPath(new URL('..', import.meta.url)));
const DAY = 24 * 60 * 60_000;
@@ -46,7 +51,7 @@ loadEnvFile(resolve(root, '.env.local'));
loadEnvFile(resolve(root, '.env'));
const args = process.argv.slice(2);
-const VALUE_FLAGS = new Set(['--id', '--as', '--lane', '--pattern', '--out', '--captions', '--item', '--now', '--status', '--speed']);
+const VALUE_FLAGS = new Set(['--id', '--as', '--lane', '--pattern', '--out', '--captions', '--item', '--now', '--status', '--speed', '--format', '--shot']);
const positional = args.filter((arg, index) => !arg.startsWith('--') && !VALUE_FLAGS.has(args[index - 1]));
const has = (flag) => args.includes(`--${flag}`);
const option = (name, fallback = null) => {
@@ -91,7 +96,9 @@ async function plan() {
const cadence = { ...DEFAULT_CADENCE, ...queue.cadence };
const seed = process.env.X_CONTENT_SCHEDULE_SEED || null;
const published = new Map((state.published || []).map((row) => [row.id, row]));
- const lifts = loadLifts(root);
+ // Rank the way a tick does: with what the account's own posts measured.
+ const learned = process.env.DATABASE_URL ? learnLifts((await outcomesStore().load().catch(() => ({ posts: [] }))).posts, { now }) : null;
+ const lifts = learned ? Object.assign(loadLifts(root) || new Map(), { learned }) : loadLifts(root);
const reviews = new Map(queue.items.map((item) => [item.id, loadReview(root, item.id)]));
const holds = activeHolds(state, queue.items, root, now);
console.log(`ledger: ${s.label}${seed ? '' : ' (slot minutes are placeholders here: X_CONTENT_SCHEDULE_SEED only exists in production)'}\n`);
@@ -377,6 +384,62 @@ function prepareVideo() {
console.log(`\nAttached to ${itemId} as the head post's only media.`);
}
+// --- proof reels -----------------------------------------------------------
+
+async function scout() {
+ const url = positional[1];
+ if (!/^https:\/\//.test(String(url))) fail('Usage: scout <https url> [--format landscape|square|portrait] [--shot file.png]');
+ const format = option('format', 'landscape');
+ if (!FORMATS[format]) fail(`--format must be one of ${Object.keys(FORMATS).join(', ')}`);
+ const page = await scoutPage(url, { format, shot: option('shot') });
+ console.log(`${page.url} HTTP ${page.status} "${page.title}" (${format}, ${FORMATS[format].width}x${FORMATS[format].height - FORMATS[format].bar} logical)`);
+ const section = (title, rows) => rows.length && console.log(`\n${title}\n${rows.map((row) => ` ${row}`).join('\n')}`);
+ section('Headings', page.headings);
+ section('Controls (click by this text)', page.buttons);
+ section('Fields (type "into" the placeholder or label)', page.fields);
+ section('Links', page.links);
+ section('Canvases', page.canvases);
+ section('Lines that carry a number (candidates for read)', page.numbers);
+ section('First lines of the page', page.text.slice(0, 25));
+}
+
+function printProof(id, proof) {
+ console.log(`\n=== ${id}: ${proof.passed ? 'PROVED' : 'FAILED'} ===`);
+ for (const step of proof.steps) console.log(` ${step.ok ? 'pass' : 'FAIL'} ${String(step.index).padStart(2)} ${step.kind.padEnd(7)} ${String(step.target).slice(0, 44).padEnd(44)} ${String(step.frames).padStart(4)} frames ${step.detail}`);
+ if (Object.keys(proof.facts).length) console.log(` read: ${Object.entries(proof.facts).map(([name, value]) => `${name} = "${value}"`).join(', ')}`);
+ for (const hit of proof.responses) console.log(` answered: ${hit.method} ${hit.path} ${hit.status} in ${hit.seconds} s`);
+ for (const cut of proof.cuts) console.log(` cut: ${cut.seconds} s after step ${cut.afterStep}, labelled in the reel`);
+ if (proof.video) console.log(` reel: ${proof.video.path} ${proof.video.durationSec} s, ${proof.video.width}x${proof.video.height}, ${proof.video.frames} frames, ${Math.round(proof.video.motion * 100)}% changing`);
+}
+
+async function prove() {
+ const queue = loadQueue(root);
+ const status = option('status');
+ const id = positional[1];
+ const items = queue.items.filter((item) => item.scenario && (id ? item.id === id : status ? item.status === status : false));
+ if (!items.length) fail(id ? `${id} is not in the queue, or carries no scenario` : 'Usage: prove <slug> | prove --status draft [--no-film]');
+ const film = !has('no-film');
+ let failed = 0;
+ for (const item of items) {
+ const failureShot = resolve(root, `node_modules/.cache/x-content/${item.id}-failure.png`);
+ mkdirSync(dirname(failureShot), { recursive: true });
+ const { proof, media } = await proveItem(item, { root, film, failureShot });
+ printProof(item.id, proof);
+ if (!proof.passed) {
+ failed++;
+ console.log(` the page as it was when the step failed: ${relative(root, failureShot)}`);
+ continue;
+ }
+ if (!media) continue;
+ // The reel replaces whatever led the post. Anything else the head carried
+ // goes with it, because X allows a video no company on its post.
+ item.posts[0].media = [media];
+ console.log(` recorded in ${proofPath(item.id)}`);
+ }
+ if (film) writeFileSync(resolve(root, QUEUE_PATH), `${JSON.stringify(queue, null, '\t')}\n`);
+ if (failed) process.exit(1);
+}
+
// --- review ----------------------------------------------------------------
// Credentials the review needs, taken from the Cloud Run service when they are
@@ -435,7 +498,7 @@ async function review() {
hydrateReviewEnv();
let failed = 0;
for (const item of items) {
- const record = await reviewItem(item, { root, glossary: queue.quality?.glossary || [], skipEditor: has('no-editor') });
+ const record = await reviewItem(item, { root, glossary: queue.quality?.glossary || [], quality: queue.quality || {}, skipEditor: has('no-editor') });
printReview(record);
if (!record.passed) failed++;
}
@@ -468,6 +531,6 @@ async function approve() {
if (blocked) process.exit(1);
}
-const commands = { check, plan, run, review, approve, import: importSource, 'prepare-video': prepareVideo };
+const commands = { check, plan, run, review, approve, scout, prove, import: importSource, 'prepare-video': prepareVideo };
if (!commands[command]) fail(`Unknown command ${command}. Commands: ${Object.keys(commands).join(', ')}`);
await commands[command]();
diff --git a/tests/x-content-reel.test.js b/tests/x-content-reel.test.js
new file mode 100644
index 000000000..4986edce3
--- /dev/null
+++ b/tests/x-content-reel.test.js
@@ -0,0 +1,321 @@
+import { describe, it, expect } from 'vitest';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { FORMATS, MIN_MOTION, PROOF_MAX_AGE_DAYS, factCheck, formatCut, proofPath, proofProblems, reelPath, scenarioHash, scenarioProblems, stepKind } from '../api/_lib/x-content/reel.js';
+import { SITE_CHROME, chromeStylesheet } from '../api/_lib/x-content/site-chrome.js';
+import { PREMIUM_MAX_LENGTH, STANDARD_MAX_LENGTH, maxLengthOf } from '../api/_lib/x-content/quality.js';
+import { validateItem } from '../api/_lib/x-content/queue.js';
+import { contentHash } from '../api/_lib/x-content/review.js';
+import { buildReviewRequest } from '../api/_lib/x-content/editor.js';
+import { bestPosts } from '../api/_lib/x-content/outcomes.js';
+
+const DAY = 86_400_000;
+const NOW = Date.parse('2026-09-29T12:00:00Z');
+const REEL_BYTES = Buffer.from('a filmed reel');
+const sha256 = (buffer) => createHash('sha256').update(buffer).digest('hex');
+
+const SCENARIO = {
+ format: 'square',
+ steps: [
+ { goto: 'https://three.ws/galaxy', settle: 6000, caption: 'Every published agent, placed by what it does' },
+ { hold: 2000 },
+ { read: 'agents', match: '([\\d,]+)\\s*agents' },
+ { type: 'trading bots', into: 'Search by meaning', caption: 'Describe what you want in plain words' },
+ { click: 'Search', awaits: '/api/galaxy' },
+ { expect: 'Closest to', caption: 'The map flies to the closest matches' },
+ { hold: 3000 },
+ ],
+};
+
+const PROBE = { durationSec: 9.1, width: 1080, height: 1080, fps: 30, videoCodec: 'h264', pixFmt: 'yuv420p' };
+
+function item(overrides = {}) {
+ return {
+ id: 'galaxy-search',
+ status: 'review',
+ kind: 'post',
+ tier: 2,
+ lane: 'labs',
+ pattern: 'walkthrough',
+ notBefore: '2026-09-29T00:00:00Z',
+ scenario: SCENARIO,
+ probes: [{ type: 'scenario' }],
+ posts: [
+ { text: 'Agent Galaxy places every published agent by what it does. Type what you want in plain words and the map flies to the closest matches.', media: [{ path: reelPath('galaxy-search'), probe: PROBE, reel: true }] },
+ { text: 'Try it on the live map: three.ws/galaxy' },
+ ],
+ claims: [{ says: 'every published agent', evidence: [{ type: 'proof', fact: 'agents' }] }],
+ mentions: {},
+ ...overrides,
+ };
+}
+
+function proof(overrides = {}) {
+ return {
+ id: 'galaxy-search',
+ scenarioHash: scenarioHash(SCENARIO),
+ ranAt: new Date(NOW - DAY).toISOString(),
+ target: { commit: 'f2081d946', revision: 'three-ws-api-00459-pxd' },
+ passed: true,
+ steps: [{ index: 1, kind: 'goto', target: 'https://three.ws/galaxy', ok: true, detail: 'loaded' }],
+ facts: { agents: '600' },
+ saw: ['Closest to'],
+ responses: [{ method: 'POST', path: '/api/galaxy', status: 200, seconds: 6.1 }],
+ cuts: [{ afterStep: 5, seconds: 6.1 }],
+ video: { path: reelPath('galaxy-search'), sha256: sha256(REEL_BYTES), frames: 273, motion: 0.98, ...PROBE },
+ ...overrides,
+ };
+}
+
+// A checkout with the reel on disk, a queue that allows long posts, and the
+// proof given (or none).
+function sandbox(record = proof(), { maximumLength = 1000 } = {}) {
+ const dir = mkdtempSync(join(tmpdir(), 'x-reel-'));
+ mkdirSync(join(dir, 'public/x-media/galaxy-search'), { recursive: true });
+ mkdirSync(join(dir, 'data/x-content/proofs'), { recursive: true });
+ writeFileSync(join(dir, reelPath('galaxy-search')), REEL_BYTES);
+ writeFileSync(join(dir, 'data/x-content/queue.json'), JSON.stringify({ quality: { maximumLength }, items: [] }));
+ if (record) writeFileSync(join(dir, proofPath('galaxy-search')), JSON.stringify(record));
+ return dir;
+}
+
+describe('scenario', () => {
+ it('accepts a runnable scenario', () => {
+ expect(scenarioProblems(SCENARIO)).toEqual([]);
+ });
+
+ it('reads a step that carries a caption as its action, not as a caption', () => {
+ expect(stepKind({ scroll: 500, caption: 'Every entry says why' })).toBe('scroll');
+ expect(stepKind({ caption: 'Only words' })).toBe('caption');
+ expect(stepKind({ nothing: true })).toBe(null);
+ });
+
+ it('refuses a scenario that proves nothing', () => {
+ const problems = scenarioProblems({ steps: [{ goto: 'https://three.ws/galaxy' }, { hold: 2000 }] }).join('\n');
+ expect(problems).toMatch(/proves nothing/);
+ });
+
+ it('counts an awaited response as proof', () => {
+ expect(scenarioProblems({ steps: [{ goto: 'https://three.ws/galaxy' }, { click: 'Search', awaits: '/api/galaxy' }, { hold: 2000 }] })).toEqual([]);
+ });
+
+ it('names every malformed step', () => {
+ const problems = scenarioProblems({
+ format: 'cinema',
+ fps: 240,
+ steps: [
+ { click: 'Search' },
+ { goto: 'http://three.ws/galaxy' },
+ { hold: 60_000 },
+ { type: 'hello' },
+ { read: 'Agents Count', match: '(' },
+ { read: 'agents', match: '(\\d+)' },
+ { read: 'agents', match: '(\\d+)' },
+ { drag: [[0.2, 0.5], [1.4, 0.5]] },
+ { hold: 500, awaits: '/api/galaxy' },
+ { click: 'Go', awaits: 'api/galaxy' },
+ { caption: 'x'.repeat(91) },
+ { mystery: true },
+ ],
+ }).join('\n');
+ expect(problems).toMatch(/format must be one of/);
+ expect(problems).toMatch(/fps must be between/);
+ expect(problems).toMatch(/first step must be a goto/);
+ expect(problems).toMatch(/step 2: goto needs an https url/);
+ expect(problems).toMatch(/step 3: hold is/);
+ expect(problems).toMatch(/step 4: type needs "into"/);
+ expect(problems).toMatch(/step 5: read needs a fact name/);
+ expect(problems).toMatch(/step 7: fact "agents" is read twice/);
+ expect(problems).toMatch(/step 8: drag needs/);
+ expect(problems).toMatch(/step 9: awaits belongs on the action/);
+ expect(problems).toMatch(/step 10: awaits needs the path/);
+ expect(problems).toMatch(/step 11: caption is 91 characters/);
+ expect(problems).toMatch(/step 12: needs one of/);
+ });
+
+ it('films every format at even dimensions with room for the bar', () => {
+ for (const format of Object.values(FORMATS)) {
+ expect((format.width * format.scale) % 2).toBe(0);
+ expect((format.height * format.scale) % 2).toBe(0);
+ expect(format.bar).toBeLessThan(format.height / 4);
+ }
+ });
+
+ it('says how long was cut the way a viewer would', () => {
+ expect(formatCut(3.2)).toBe('3 s');
+ expect(formatCut(106)).toBe('1 min 46 s');
+ expect(formatCut(120)).toBe('2 min');
+ });
+});
+
+describe('proof', () => {
+ it('covers an item whose reel a passing run filmed', () => {
+ expect(proofProblems(item(), sandbox(), NOW)).toEqual([]);
+ });
+
+ it('asks for nothing of an item with no scenario', () => {
+ expect(proofProblems(item({ scenario: undefined }), sandbox(null), NOW)).toEqual([]);
+ });
+
+ it('reports a missing proof', () => {
+ expect(proofProblems(item(), sandbox(null), NOW).join('\n')).toMatch(/no proof on record/);
+ });
+
+ it('reports the step a failed run stopped at', () => {
+ const failed = proof({ passed: false, video: null, steps: [{ index: 5, kind: 'click', target: 'Search', ok: false, detail: 'POST /api/galaxy answered HTTP 503' }] });
+ expect(proofProblems(item(), sandbox(failed), NOW)).toEqual(['the last run failed at step 5 (click Search): POST /api/galaxy answered HTTP 503']);
+ });
+
+ it('is void once the scenario changes', () => {
+ const changed = item({ scenario: { ...SCENARIO, steps: [...SCENARIO.steps, { hold: 1000 }] } });
+ expect(proofProblems(changed, sandbox(), NOW).join('\n')).toMatch(/scenario changed after it was filmed/);
+ });
+
+ it('expires, because the product moves', () => {
+ const old = proof({ ranAt: new Date(NOW - (PROOF_MAX_AGE_DAYS + 2) * DAY).toISOString() });
+ expect(proofProblems(item(), sandbox(old), NOW).join('\n')).toMatch(/filmed 16 days ago/);
+ });
+
+ it('requires the head post to carry the reel that was filmed', () => {
+ const swapped = item({ posts: [{ text: item().posts[0].text, media: [{ path: 'public/x-media/galaxy-search/other.mp4', probe: PROBE }] }] });
+ expect(proofProblems(swapped, sandbox(), NOW).join('\n')).toMatch(/does not carry the reel/);
+ });
+
+ it('notices a reel that was replaced after the run', () => {
+ const dir = sandbox();
+ writeFileSync(join(dir, reelPath('galaxy-search')), Buffer.from('a different file'));
+ expect(proofProblems(item(), dir, NOW).join('\n')).toMatch(/is not the file the proof filmed/);
+ });
+
+ it('refuses a reel in which almost nothing moves', () => {
+ const still = proof({ video: { ...proof().video, motion: MIN_MOTION - 0.05 } });
+ expect(proofProblems(item(), sandbox(still), NOW).join('\n')).toMatch(/only 10% of the reel's frames change/);
+ });
+});
+
+describe('proof as evidence', () => {
+ it('checks a fact the run read', () => {
+ expect(factCheck({ type: 'proof', fact: 'agents', equals: '600' }, proof()).ok).toBe(true);
+ expect(factCheck({ type: 'proof', fact: 'agents', equals: '601' }, proof())).toEqual({ ok: false, detail: 'the run read agents = "600"; the claim needs "601"' });
+ expect(factCheck({ type: 'proof', fact: 'agents', contains: '60' }, proof()).ok).toBe(true);
+ expect(factCheck({ type: 'proof', fact: 'agents' }, proof()).ok).toBe(true);
+ expect(factCheck({ type: 'proof', fact: 'stars' }, proof()).detail).toMatch(/read no fact named "stars"/);
+ });
+
+ it('checks a text the run waited for', () => {
+ expect(factCheck({ type: 'proof', saw: 'closest to' }, proof()).ok).toBe(true);
+ expect(factCheck({ type: 'proof', saw: 'No matches' }, proof()).ok).toBe(false);
+ });
+
+ it('checks what the server answered', () => {
+ expect(factCheck({ type: 'proof', responded: '/api/galaxy' }, proof())).toEqual({ ok: true, detail: 'POST /api/galaxy answered 200 in 6.1 s' });
+ expect(factCheck({ type: 'proof', responded: '/api/search' }, proof()).ok).toBe(false);
+ });
+
+ it('cites nothing from a failed or missing run', () => {
+ expect(factCheck({ type: 'proof', fact: 'agents' }, proof({ passed: false })).ok).toBe(false);
+ expect(factCheck({ type: 'proof', fact: 'agents' }, null).ok).toBe(false);
+ });
+});
+
+describe('queue validation of a filmed item', () => {
+ it('passes an item whose proof covers it', () => {
+ expect(validateItem(item(), sandbox())).toEqual([]);
+ });
+
+ it('requires the scenario to be the item probe', () => {
+ expect(validateItem(item({ probes: [{ type: 'api', url: 'https://three.ws/api/galaxy' }] }), sandbox()).join('\n')).toMatch(/declare \{ "type": "scenario" \} in probes/);
+ });
+
+ it('refuses a scenario probe on an item with no scenario', () => {
+ const bare = item({ scenario: undefined, posts: [{ text: item().posts[0].text, media: [{ path: reelPath('galaxy-search'), probe: PROBE }] }, item().posts[1]], claims: [] });
+ expect(validateItem(bare, sandbox()).join('\n')).toMatch(/a scenario probe needs the item to carry a `scenario`/);
+ });
+
+ it('holds a draft to the scenario but not yet to the proof', () => {
+ expect(validateItem(item({ status: 'draft' }), sandbox(null))).toEqual([]);
+ expect(validateItem(item({ status: 'review' }), sandbox(null)).join('\n')).toMatch(/proof: no proof on record/);
+ });
+
+ it('binds the review to the scenario without disturbing older hashes', () => {
+ const dir = sandbox();
+ const plain = item({ scenario: undefined });
+ const { scenario, ...withoutField } = item();
+ expect(scenario).toBe(SCENARIO);
+ expect(contentHash(plain, dir)).toBe(contentHash(withoutField, dir));
+ expect(contentHash(item(), dir)).not.toBe(contentHash(plain, dir));
+ expect(contentHash(item({ scenario: { ...SCENARIO, format: 'landscape' } }), dir)).not.toBe(contentHash(item(), dir));
+ });
+});
+
+describe('post length', () => {
+ const long = `${'The map places every published agent by what it does, and a plain sentence is enough to find one. '.repeat(4)}three.ws/galaxy`;
+
+ it('takes the wall from the queue, never below the one X enforces', () => {
+ expect(maxLengthOf({})).toBe(STANDARD_MAX_LENGTH);
+ expect(maxLengthOf({ maximumLength: 100 })).toBe(STANDARD_MAX_LENGTH);
+ expect(maxLengthOf({ maximumLength: 1000 })).toBe(1000);
+ expect(maxLengthOf({ maximumLength: 90_000 })).toBe(PREMIUM_MAX_LENGTH);
+ expect(maxLengthOf({ maximumLength: 'long' })).toBe(STANDARD_MAX_LENGTH);
+ });
+
+ it('holds a long head to the standard wall unless the queue lifts it', () => {
+ const post = item({ posts: [{ text: long, media: item().posts[0].media }] });
+ expect(validateItem(post, sandbox(proof(), { maximumLength: 280 })).join('\n')).toMatch(/maximum is 280/);
+ expect(validateItem(post, sandbox(proof(), { maximumLength: 1000 }))).toEqual([]);
+ });
+
+ it('reads the wall from the queue at root when a caller holds only the item', () => {
+ const post = item({ posts: [{ text: long, media: item().posts[0].media }] });
+ expect(validateItem(post, sandbox(proof(), { maximumLength: 1000 }), { quality: { maximumLength: 300 } }).join('\n')).toMatch(/maximum is 300/);
+ });
+});
+
+describe('the editor and a reel', () => {
+ it('is given the record of the run and the length it may write to', async () => {
+ const request = await buildReviewRequest(item(), { root: sandbox(), verification: { checks: [] }, lint: [], maximum: 1000 });
+ expect(request.system).toMatch(/stay within 1000 weighted characters/);
+ const text = request.parts.filter((part) => part.type === 'text').map((part) => part.text).join('\n');
+ expect(text).toMatch(/a 9.1 second reel, 1080x1080, filmed from the live product/);
+ expect(text).toMatch(/production commit f2081d946/);
+ expect(text).toMatch(/"agents":"600"/);
+ expect(text).toMatch(/"path":"\/api\/galaxy"/);
+ expect(text).toMatch(/Describe what you want in plain words/);
+ });
+
+ it('is calibrated against the measured posts when they are given', async () => {
+ const calibration = [{ text: 'Your three.ws avatar speaks sign language now', likes: 222, reposts: 61, bookmarks: 5, views: 15609, media: 'video', posted: '2026-08-01' }];
+ const request = await buildReviewRequest(item(), { root: sandbox(), verification: { checks: [] }, lint: [], calibration });
+ expect(request.parts[0].text).toMatch(/speaks sign language now/);
+ expect(request.system).toMatch(/stay within 280 weighted characters/);
+ });
+});
+
+describe('measured posts for calibration', () => {
+ const row = (overrides) => ({ id: '1', at: new Date(NOW - 10 * DAY).toISOString(), impressions: 1000, likes: 10, reposts: 1, replies: 0, bookmarks: 0, media: 'photo', text: 'a post', ...overrides });
+
+ it('ranks matured posts by outcome and leaves out the rest', () => {
+ const posts = bestPosts(
+ [
+ row({ id: 'a', likes: 40, text: 'forty likes' }),
+ row({ id: 'b', likes: 220, bookmarks: 5, text: 'the sign language\npost' }),
+ row({ id: 'c', likes: 900, at: new Date(NOW - 3_600_000).toISOString(), text: 'an hour old' }),
+ row({ id: 'd', likes: 500, text: '' }),
+ ],
+ { now: NOW, count: 2 },
+ );
+ expect(posts.map((post) => post.text)).toEqual(['the sign language post', 'forty likes']);
+ expect(posts[0]).toMatchObject({ likes: 220, bookmarks: 5, views: 1000, media: 'photo' });
+ });
+});
+
+describe('site chrome', () => {
+ it('hides every floating layer, and whatever a scenario adds', () => {
+ const sheet = chromeStylesheet(['.promo-banner']);
+ for (const selector of [...SITE_CHROME, '.promo-banner']) expect(sheet).toContain(selector);
+ expect(sheet).toMatch(/\{display:none !important\}$/);
+ });
+});