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(announce): let the capture decide still or loop, and pack the Awesome 3D Agents announcement

ni3a916d2409ad4c
diff --git a/api/_lib/announce/plan.js b/api/_lib/announce/plan.js
index 621aac509..411b99a7d 100644
--- a/api/_lib/announce/plan.js
+++ b/api/_lib/announce/plan.js
@@ -66,13 +66,18 @@ export function patternsFor(entry) {
const ranked = [];
// A loop has to be a loop of something running, so only a surface with a
// route can carry one. A package's frame is a typeset card, which is a
- // still by construction.
+ // still by construction, and a route the capture already photographed
+ // twice without anything changing carries `moves: false` in the ledger. No
+ // description can answer that question, because a curated list of
+ // animation tools is described entirely in words about motion and does not
+ // move at all; a route nobody has photographed yet is free to try.
const filmable = Boolean(entry.url);
- if (filmable && (entry.signals?.visual ?? 0) >= 25) ranked.push('clip');
+ const moves = filmable && entry.moves !== false;
+ if (moves && (entry.signals?.visual ?? 0) >= 25) ranked.push('clip');
if (/\b\d[\d,.]*\s*(?:%|x\b|ms\b|seconds?|minutes?|hours?|k\b|m\b)|\b\d{2,}\b/.test(text)) ranked.push('number');
if (/instead of|without|no longer|used to|rather than|misconception|assume/i.test(text)) ranked.push('correction');
if (/\bhow to\b|guide|tutorial|step|studio|builder|editor/i.test(text)) ranked.push('walkthrough');
- if (filmable && (entry.signals?.visual ?? 0) > 0 && !ranked.includes('clip')) ranked.push('clip');
+ if (moves && (entry.signals?.visual ?? 0) > 0 && !ranked.includes('clip')) ranked.push('clip');
// Any surface a visitor can act on can be written as a walkthrough, which is
// what keeps a long run of pages from being 40 mechanism posts in a row.
if (filmable && !ranked.includes('walkthrough')) ranked.push('walkthrough');
diff --git a/data/x-content/reviews/awesome.json b/data/x-content/reviews/awesome.json
new file mode 100644
index 000000000..b0cb0071a
--- /dev/null
+++ b/data/x-content/reviews/awesome.json
@@ -0,0 +1,59 @@
+{
+ "id": "awesome",
+ "contentHash": "aa2d1ecaa43622b2fedc10e1eb17f965fcf1346095929e9e0bacb5abe2ed36c0",
+ "reviewedAt": "2026-09-20T07:50:59.086Z",
+ "passed": false,
+ "blockers": [
+ "the AI editor did not run: no model was reachable:"
+ ],
+ "texts": [
+ "Giving an agent a body means stitching a dozen fields together. Awesome 3D Agents is the map: 152 entries across 15 sections, 121 of them free to use. three.ws/awesome",
+ "Each entry says in one sentence what the thing does and why you would reach for it instead of the alternative. The same list is published in the standard awesome list format on GitHub, so it can be forked and added to."
+ ],
+ "lint": [],
+ "verification": {
+ "ok": true,
+ "checks": [
+ {
+ "claim": "152 entries across 15 sections",
+ "kind": "evidence:page",
+ "target": "https://three.ws/awesome",
+ "ok": true,
+ "detail": "live page shows \"152 entries across 15 sections\""
+ },
+ {
+ "claim": "121 of them free to use",
+ "kind": "evidence:page",
+ "target": "https://three.ws/awesome",
+ "ok": true,
+ "detail": "live page shows \"FREE TO USE 121\""
+ },
+ {
+ "kind": "probe:api",
+ "target": "the published list serves 152 entries across 15 sections",
+ "ok": true,
+ "detail": "HTTP 200, expectations met"
+ },
+ {
+ "kind": "probe:api",
+ "target": "every entry ships the sentence that says why it is on the list",
+ "ok": true,
+ "detail": "HTTP 200, expectations met"
+ },
+ {
+ "kind": "probe:browser",
+ "target": "the page renders the counters, the tag filters and the Markdown copy",
+ "ok": true,
+ "detail": "4 steps passed"
+ },
+ {
+ "kind": "link",
+ "target": "https://three.ws/awesome",
+ "ok": true,
+ "detail": "HTTP 200"
+ }
+ ]
+ },
+ "editor": null,
+ "editorError": "no model was reachable:\n No GCP credentials found. Set GCP_SERVICE_ACCOUNT_JSON, run `gcloud auth application-default login`, or run on GCE/Cloud Run."
+}
diff --git a/docs/announcement-factory.md b/docs/announcement-factory.md
index 5bdf4bb62..799325565 100644
--- a/docs/announcement-factory.md
+++ b/docs/announcement-factory.md
@@ -42,6 +42,7 @@ publishing rather than chosen here:
| How many posts a day, at what times, and which tier owns each one | The `cadence.slots` table of [`data/x-content/queue.json`](../data/x-content/queue.json), which is the same table the publisher fills from: T3 at 04:00 UTC, T2 at 12:00, T1 at 20:00. With no table declared, the times are derived from the daily cap, minimum gap and quiet hours instead, and a slot whose jitter window could land inside quiet hours is dropped rather than promised. |
| What order, and which shape | The ledger's scores, then rotation: no more than `maximumSameLaneInARow` of one audience, no more than `maximumSamePatternInARow` of one post shape, from the same queue file. |
| Which tier a surface is | What it is: a flagship (T1) is a `token`-lane surface or one that legitimately names a partner, proof of work (T3) is a package, worker or service, whose frame is a typeset card rather than a route, and everything with a page behind it is a feature (T2). The tier travels into the queue item, because the publisher gives each tier a slot of its own and an item with no tier is treated as a T2 feature. |
+| Which one jumps the queue | [`data/announce-priority.json`](../data/announce-priority.json), the mirror image of the deferrals. A surface listed there enters the sequencer ahead of the backlog and takes the earliest slot its own tier owns, with the reason recorded beside it. The pin buys position only: the cadence, the tier discipline and the lane and shape rotation are unchanged, and the pack still goes through review and approval like any other. |
| Which ones need owner approval first | Any surface in the `crypto` section of [`data/pages.json`](../data/pages.json) renders live third-party market data, so a frame of it falls under the operating rules' coin gate. Those slots carry `mediaGate: "owner-approval"` and the factory skips them unless asked. |
The plan is a pure function of the ledger and the start date, so it is regenerated rather than
@@ -59,6 +60,21 @@ could have had. Clearing a frame puts that surface back in the next plan.
judgement someone made by looking at a captured frame. `data/announce-deferred.json` is where that
judgement lives, with the reason, and it is committed for exactly that reason.
+**Pins.** The same problem in the other direction: the ledger scores a surface on what it can
+measure from a description, a route and a directory, so a surface can be worth posting this week
+and still sit ninety slots down the calendar. `data/announce-priority.json` records that
+judgement, and `CALENDAR.md` prints the pinned surfaces and their reasons in an "Asked for next"
+table. Remove the entry once the surface is packed, since a packed surface leaves the plan anyway.
+
+**What counts as a surface.** The inventory is re-derived from `data/pages.json`, `packages/*`,
+`workers/*` and `services/*` on every run. Most of `data/pages.json` is content: the `learn`
+section alone holds 436 documentation and tutorial pages, and announcing each one would drown the
+features. The five pages in there that carry `showcase: true` are products rather than documents
+(`/awesome`, `/3d`, `/crypto`, `/crypto-api`, `/docs/world`), so `showcase` is the admission rule:
+a content page carrying it is inventory, a content page without it is content. Two of those five
+render live third-party market data, which is why the coin gate matches the `/crypto` path
+namespace and not only the `crypto` section.
+
## Lanes and patterns
`lane` is the audience and comes from where the surface lives: `token` for the crypto section,
@@ -99,11 +115,20 @@ mention it, its docs, and its README. It emits `evidenceCandidates`, each one a
can already run (`page` contains this sentence, `file` contains this line). Two rules make those
candidates trustworthy rather than decorative: a page fact must be a whole sentence of the rendered
page, and a file fact must be a literal substring of the file on disk, because that is what
-[`verify.js`](../api/_lib/x-content/verify.js) matches against. Sentences carrying a banned dash
+[`verify.js`](../api/_lib/x-content/verify.js) matches against. Facts are harvested from the
+page's `main` element rather than the whole body, so a claim never comes out of the header menu
+that sits above every page's own first word. The counters a page leads with are collected
+separately, because a tile (`ENTRIES 152`) and a summary line (`152 entries across 15 sections`)
+are not sentences and the whole-sentence rule would drop exactly the fact the `number` pattern
+exists to lead on. Sentences carrying a banned dash
glyph are dropped rather than rewritten, since the quote has to match character for character.
**2. The media recipe** goes into [`data/announce-media.json`](../data/announce-media.json), and
`npm run announce:media` shoots it from the live route with provenance written beside the pixels.
+A recipe can ask for a five second loop, but the capture has the last word: it takes two frames a
+second apart, and when they are identical it writes the still and records `animated: false` in the
+manifest. Nothing upstream can make that call, because the description of a page about motion
+generation reads exactly like the description of a page that moves.
A surface with no route (115 of the 316 planned announcements are a package, a worker, or a
service) gets a title card instead: [`api/_lib/announce/card.js`](../api/_lib/announce/card.js)
typesets its real name, its real description, the command a developer really runs, and the tools it
@@ -129,7 +154,8 @@ it is written that way, and the longer Telegram register.
**5. The queue item** goes into [`data/x-content/queue.json`](../data/x-content/queue.json), with
`textFrom` pointing at the pack's `.post.txt`, so the bytes that were reviewed are the bytes that
-ship. It lands at `review` when the queue validator finds nothing wrong with it and at `draft` when
+ship. It carries the slot's tier, because the publisher gives each tier a slot of its own, and the
+draft's feature probes, because the review bar refuses an item that cannot prove its feature works. It lands at `review` when the queue validator finds nothing wrong with it and at `draft` when
something is still missing, which is almost always the frame: capture it, re-run the same command,
and it moves up. The status is the validator's verdict, not the factory's opinion.
@@ -140,6 +166,7 @@ and it moves up. The status is the validator's verdict, not the factory's opinio
| Invent a fact | The drafter sees only the brief, and every claim must cite one of its `evidenceCandidates`, copied exactly |
| Invent evidence | `draftFindings` rejects any evidence object that is not one of the candidates |
| State a number with nothing behind it | `claimProblems`: every number, ordinal and absolute must sit inside a declared claim |
+| Ship a post with nothing proving the feature works | Every item declares at least one probe in `probes`, drawn from the routes and endpoints in the brief, and review runs them live |
| Tag an account the feature does not run on | Every `@mention` needs a recorded reason, and the reviewer confirms the account is real and public |
| Write hype, a hashtag, an emoji, a dash, a teaser, or a rhetorical opener | `copyProblems` and `languageProblems` |
| Repeat something @trythreews already posted | Similarity against the scraped archive and the rest of the queue |
@@ -236,5 +263,6 @@ the section above.
| [api/_lib/x-content/llm.js](../api/_lib/x-content/llm.js) | The model chain, shared with the editor |
| `data/announce-plan/` | Generated: the plan, the calendar, briefs, hand-written drafts |
| [data/announce-deferred.json](../data/announce-deferred.json) | Surfaces held back, with the reason |
+| [data/announce-priority.json](../data/announce-priority.json) | Surfaces asked for next, with the reason |
| [docs/announcements/](./announcements/) | The packs themselves |
| [tests/announce-factory.test.js](../tests/announce-factory.test.js) | The rules above, as tests |
diff --git a/docs/announcements/awesome.md b/docs/announcements/awesome.md
new file mode 100644
index 000000000..71a0a70c3
--- /dev/null
+++ b/docs/announcements/awesome.md
@@ -0,0 +1,97 @@
+# Announcement pack: The curated map of the 3D agent pipeline
+
+**Surface:** [`/awesome`](https://three.ws/awesome) · **Stage:** drafted · **Slot:** 2026-09-21 · **Announced externally:** never
+
+Ranked 176 of 330 never-announced surfaces by `npm run announce:rank` (score 46). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/awesome.json`](../../data/announce-plan/briefs/awesome.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.
+
+---
+
+## At a glance
+
+| Field | Value |
+|---|---|
+| Pack id | `awesome` |
+| Publish slot | 2026-09-21. The minute is decided at send time from the production schedule seed, so it is not knowable from this repository |
+| Lane and pattern | community / mechanism |
+| Audience | People who use three.ws and hold $THREE |
+| Primary channel | X, @trythreews, through the reviewed content queue |
+| Secondary channels | Telegram (@three_ws), the surface's own docs page |
+| Proof | https://three.ws/awesome |
+| Tracked links | Telegram `https://three.ws/awesome?utm_source=telegram&utm_medium=community&utm_campaign=announce-awesome&utm_content=announcement`. The X post links the bare URL on purpose: X wraps every link in t.co and the queue's own ledger records the send, so a tagged link buys nothing and reads like marketing. |
+| The single CTA | Open /awesome and use it |
+| Media | `awesome-hero`, still frame |
+| KPI | route sessions and docs reads on the day of the post |
+
+## Why this one, and why now
+
+The ranker scored it on signals measured against our own archive, not on taste:
+
+- **reach (16)**: sitemap priority 0.80, which is what we already decided this surface is worth
+- **visual (25)**: a showcase surface, so its frame can be a motion loop
+- **depth (5)**: documented in the tree, so there is enough to write a mechanism about and link proof for
+
+It shipped on 2026-09-07 and has never been posted about.
+
+The changelog has 2 entries about it, the most recent from 2026-09-20: "Awesome 3D Agents joins the announcement queue, and the machine stops skipping pages like it".
+
+## The claim, and where it is checked
+
+> Giving an agent a body means stitching a dozen fields together. Awesome 3D Agents is the map: 152 entries across 15 sections, 121 of them free to use. three.ws/awesome
+
+Every checkable part of that is declared as a claim in the queue item, and the verifier re-checks each one against the live surface before the post can be approved:
+
+| Claim | Checked against |
+|---|---|
+| 152 entries across 15 sections | live page shows "152 entries across 15 sections" |
+| 121 of them free to use | live page shows "FREE TO USE 121" |
+
+## Media
+
+Captured from the live route by `npm run announce:media`, which drives the real page in a real Chromium and writes provenance (route, commit, time, sha256) beside the pixels in [`public/announce/media-manifest.json`](../../public/announce/media-manifest.json).
+
+| Shot | File | Notes |
+|---|---|---|
+| `awesome-hero` | `/announce/img/awesome-hero.webp` | Still frame of the live route. |
+
+**Alt text, required on the post:**
+
+> The Awesome 3D Agents page on three.ws: a heading reading Everything you need to give an AI agent a body, counters for 152 entries, 15 sections, 121 free to use and 97 tags, a row of tag filters, and a grid of cards for projects such as TRELLIS, Hunyuan3D 2 and TripoSR, each with a one sentence description.
+
+## The post
+
+Pattern: mechanism. **174 weighted characters**, inside the 100 to 179 band that measured a 3.0x lift. Postable file: [`awesome.post.txt`](./awesome.post.txt), which is the byte-for-byte source the queue item points at.
+
+```text
+Giving an agent a body means stitching a dozen fields together. Awesome 3D Agents is the map: 152 entries across 15 sections, 121 of them free to use. three.ws/awesome
+```
+
+### Why it is written that way
+
+The post leads on the problem the list solves, that embodying an agent means assembling a pipeline out of a dozen unrelated fields, and then on the two counters the page itself renders. Those numbers are the strongest checkable thing about the surface: the list is only worth reading because somebody read all 152 entries and said in one sentence why each one is there.
+
+### Thread
+
+2/ (218)
+
+```text
+Each entry says in one sentence what the thing does and why you would reach for it instead of the alternative. The same list is published in the standard awesome list format on GitHub, so it can be forked and added to.
+```
+
+## Telegram (@three_ws)
+
+The same facts in the channel's longer register. The changelog cron posts release notes there automatically; this is the announcement register, sent by hand or queued alongside the post.
+
+```text
+Awesome 3D Agents is a curated list of what it takes to give an AI agent a body: text to 3D, photo and video capture, avatars, rigging, motion generation, texturing, lipsync and voice, web renderers, asset pipelines, and the agent frameworks that drive them. It runs to 152 entries across 15 sections, 121 of them free to use, and each one says in a sentence what it does and why you would reach for it instead of the alternative. Every link is fetched and checked before it ships, and the same list is published in the standard awesome list format on GitHub so it can be forked and contributed to. Search it, filter it by tag, or copy the whole thing as Markdown at https://three.ws/awesome
+```
+
+## Ship it
+
+```bash
+npm run announce:media -- --only awesome-hero # capture the frame from the live route
+npm run x:content -- review awesome # lint, live fact checks, AI editor
+npm run x:content -- run --dry-run --id awesome # exactly what would be sent to X
+```
+
+The queue item is `awesome` in [`data/x-content/queue.json`](../../data/x-content/queue.json), at status `draft`. It becomes eligible to publish when a passing review record exists and the owner sets its status to `approved`; the Cloud Scheduler tick then sends it at its slot. Nothing here posts on its own.
+
diff --git a/docs/announcements/awesome.post.txt b/docs/announcements/awesome.post.txt
new file mode 100644
index 000000000..b3e53be8d
--- /dev/null
+++ b/docs/announcements/awesome.post.txt
@@ -0,0 +1 @@
+Giving an agent a body means stitching a dozen fields together. Awesome 3D Agents is the map: 152 entries across 15 sections, 121 of them free to use. three.ws/awesome
diff --git a/public/announce/img/awesome-hero.webp b/public/announce/img/awesome-hero.webp
new file mode 100644
index 000000000..984ad46e4
Binary files /dev/null and b/public/announce/img/awesome-hero.webp differ
diff --git a/scripts/announce-kit.mjs b/scripts/announce-kit.mjs
index 96a3cde7f..11299dfd2 100644
--- a/scripts/announce-kit.mjs
+++ b/scripts/announce-kit.mjs
@@ -46,7 +46,7 @@ import { briefPath, buildBrief } from '../api/_lib/announce/brief.js';
import { draftFindings, draftPost, itemFor } from '../api/_lib/announce/draft.js';
import { renderPack, renderPostFile } from '../api/_lib/announce/kit.js';
import { MissingLedgerError, ledgerEntryFor, loadLedger, loadOrBuildPlan } from '../api/_lib/announce/ledger.js';
-import { slugFor } from '../api/_lib/announce/plan.js';
+import { patternsFor, slugFor } from '../api/_lib/announce/plan.js';
import { createPageReader } from '../api/_lib/x-content/verify.js';
import { validateItem } from '../api/_lib/x-content/queue.js';
@@ -110,6 +110,7 @@ const wanted = (() => {
console.error(`no planned slot or queue item with id ${id}. See: npm run announce:plan`);
process.exit(1);
}
+ const offered = patternsFor(entry);
return [{
position: 0,
id,
@@ -118,7 +119,11 @@ const wanted = (() => {
section: entry.section,
url: entry.url || null,
lane: queued.lane,
- pattern: queued.pattern,
+ // The shape it was packed in, unless the surface can no longer
+ // carry it: a route the capture photographed twice without
+ // anything changing stops being offered a clip, and re-running the
+ // factory over that pack must not promise a loop again.
+ pattern: offered.includes(queued.pattern) ? queued.pattern : offered[0],
tier: queued.tier,
notBefore: queued.notBefore,
windowMinutes: queued.windowMinutes || plan.slots[0]?.windowMinutes || 90,
@@ -175,7 +180,17 @@ function upsertShot(slot, alt, entry) {
card: { dir: entry.dir || null, title: entry.title || slot.key, description: entry.description || '' },
};
const index = (spec.shots || []).findIndex((row) => row.id === slot.shot);
- if (index >= 0) spec.shots[index] = { ...spec.shots[index], ...shot };
+ // Merge, so a hand-tuned viewport or settle survives a re-run, except for
+ // the motion recipe: a surface whose pattern is no longer a clip must stop
+ // being filmed, and a spread alone would keep filming it forever.
+ if (index >= 0) {
+ const previous = { ...spec.shots[index] };
+ if (!slot.motion) {
+ delete previous.motion;
+ delete previous.settle;
+ }
+ spec.shots[index] = { ...previous, ...shot };
+ }
else spec.shots.push(shot);
if (!dryRun) writeFileSync(MEDIA_SPEC, `${JSON.stringify(spec, null, '\t')}\n`);
@@ -277,15 +292,20 @@ try {
// captured separately). The queue validator decides which, not this
// script's optimism.
const candidate = itemFor(brief, draft, { mediaPath });
- const problems = validateItem(candidate, root);
- const item = { ...candidate, status: problems.length ? 'draft' : 'review' };
const pack = renderPack({ brief, draft, slot, ledgerEntry: entry, rank: rank || null, total: (ledger.totals?.never ?? null), model });
+ // The pack is written before the item is judged, because the item points
+ // at the pack's `.post.txt` and the validator checks that file exists.
+ // Judging first failed every brand-new pack on a file this same run was
+ // about to write, which left the whole batch at `draft` until someone
+ // re-ran it.
if (!dryRun) {
mkdirSync(PACK_DIR, { recursive: true });
writeFileSync(join(PACK_DIR, `${slot.id}.md`), pack);
writeFileSync(join(PACK_DIR, `${slot.id}.post.txt`), renderPostFile(draft));
- upsertItem(item);
}
+ const problems = validateItem(candidate, root);
+ const item = { ...candidate, status: problems.length ? 'draft' : 'review' };
+ if (!dryRun) upsertItem(item);
queuedHeads.set(slot.id, item.posts[0].text);
results.push({
id: slot.id,
diff --git a/scripts/announce-rank.mjs b/scripts/announce-rank.mjs
index db71ff136..da9d06373 100644
--- a/scripts/announce-rank.mjs
+++ b/scripts/announce-rank.mjs
@@ -48,6 +48,8 @@ import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
import { resolve, dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
+import { slugFor } from '../api/_lib/announce/plan.js';
+
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const LEDGER = join(root, 'data/announcements.json');
const COVERAGE = join(root, 'docs/announcement-coverage.md');
@@ -149,6 +151,20 @@ function dirInventory(base, kind, keyPrefix) {
return out;
}
+// Whether a surface actually moves, read back from the only thing that knows:
+// the capture, which shoots two frames a second apart and records `animated`
+// in the media manifest. No description can answer it, because a curated list
+// of animation tools is described entirely in words about motion and sits
+// perfectly still. A surface nobody has photographed yet is left free to try a
+// loop; one that was photographed and held still stops being offered one.
+function motionVerdicts() {
+ const path = join(root, 'public/announce/media-manifest.json');
+ if (!existsSync(path)) return new Map();
+ const manifest = JSON.parse(readFileSync(path, 'utf8'));
+ const shots = Array.isArray(manifest.shots) ? manifest.shots : Object.values(manifest.shots || {});
+ return new Map(shots.filter((shot) => shot && shot.id).map((shot) => [shot.id, shot.animated !== false]));
+}
+
// --- announced status, read out of the coverage audit ------------------------
// Every inventory table in the audit has an "Announced" column, but not at the
@@ -271,6 +287,7 @@ const priorByKey = new Map((previous.entries || []).map((e) => [e.key, e]));
const status = coverageStatus();
const curated = curatedShortlist();
+const verdicts = motionVerdicts();
const inventory = [
...pageInventory(),
...dirInventory('packages', 'package', '@three-ws/'),
@@ -290,6 +307,8 @@ for (const rec of inventory) {
if (prior && prior.media) rec.media = prior.media;
if (prior && prior.pack) rec.pack = prior.pack;
rec.live = prior && prior.live ? prior.live : null;
+ const shot = `${slugFor(rec.key)}-hero`;
+ if (verdicts.has(shot)) rec.moves = verdicts.get(shot);
scoreSurface(rec, curated);
}
diff --git a/scripts/capture-doc-media.mjs b/scripts/capture-doc-media.mjs
index 029d51d1f..f80779712 100644
--- a/scripts/capture-doc-media.mjs
+++ b/scripts/capture-doc-media.mjs
@@ -336,6 +336,25 @@ async function writeStill(buffer, outPath) {
return { bytes: out.length, width: final.width, height: final.height };
}
+/**
+ * Two frames of the same page, compared the way an eye would rather than byte
+ * for byte: downscaled to a thumbnail, greyscaled, and averaged. A compositor
+ * re-renders text antialiasing and gradients slightly differently between two
+ * captures of a page that never changed, so byte equality answers "did the
+ * encoder agree", not "did anything move".
+ */
+async function looksIdentical(left, right) {
+ const thumbnail = (buffer) => sharp(buffer).resize(96, null, { fit: 'inside' }).greyscale().raw().toBuffer();
+ const [a, b] = await Promise.all([thumbnail(left), thumbnail(right)]);
+ if (a.length !== b.length) return false;
+ let total = 0;
+ for (let index = 0; index < a.length; index++) total += Math.abs(a[index] - b[index]);
+ // Mean difference per pixel, on a 0-255 scale. Below 1.5 is resampling
+ // noise; anything actually moving on screen clears it by an order of
+ // magnitude.
+ return total / a.length < 1.5;
+}
+
/**
* Animated capture. Chromium has no video encoder we can trust for a short
* looping clip, so we sample real frames on a fixed cadence and let ffmpeg
@@ -346,6 +365,21 @@ async function writeMotion(page, shot, subject, outPath) {
const fps = Math.min(24, Math.max(4, shot.motion.fps || 12));
const seconds = Math.min(10, Math.max(1, shot.motion.seconds || 3));
const frameCount = Math.round(fps * seconds);
+
+ // Does this route actually move? Nothing upstream can answer that: the
+ // planner reads a description, and the description of a curated list of
+ // animation tools is full of the word motion while the page itself sits
+ // perfectly still. So the capture answers it, by looking. Two frames a
+ // second apart that are byte-identical mean the loop would be sixty copies
+ // of one picture, which costs a reader bandwidth and tells them nothing, so
+ // the still is shipped instead and the manifest records that it is a still.
+ const first = await shoot(page, subject, { timeout: 25000 });
+ await page.waitForTimeout(1000);
+ const second = await shoot(page, subject, { timeout: 25000 });
+ if (await looksIdentical(first, second)) {
+ return { ...(await writeStill(second, outPath)), animated: false, still: 'the route did not change between two frames a second apart' };
+ }
+
const frameDir = mkdtempSync(path.join(tmpdir(), 'docmedia-'));
try {
const interval = 1000 / fps;
@@ -384,6 +418,7 @@ async function writeMotion(page, shot, subject, outPath) {
const out = readFileSync(outPath);
const meta = await sharp(out, { animated: true }).metadata();
return {
+ animated: true,
bytes: out.length,
width: meta.width,
// sharp reports an animated WebP's height as pages*height; the frame
@@ -495,7 +530,9 @@ async function captureShot(browser, shot, commit) {
caption: shot.caption || null,
route: shot.url || `card:${shot.card?.dir || shot.id}`,
viewport: shot.viewport || 'desktop',
- animated: Boolean(shot.motion),
+ // The capture's verdict, not the recipe's intent: a shot asked for
+ // as a loop is recorded as a still when the route held still.
+ animated: Boolean(shot.motion) && written.animated !== false,
authenticated: Boolean(shot.auth),
hidden: shot.hide && shot.hide.length ? shot.hide : undefined,
capturedAt: new Date().toISOString(),
diff --git a/tests/announce-factory.test.js b/tests/announce-factory.test.js
index 3f7756a97..fe84119db 100644
--- a/tests/announce-factory.test.js
+++ b/tests/announce-factory.test.js
@@ -2,7 +2,9 @@ import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import { buildPlan, laneFor, patternsFor, sequence, slotTable, slotTimes, slugFor, tierFor } from '../api/_lib/announce/plan.js';
-import { harvestFacts, quotableLines } from '../api/_lib/announce/brief.js';
+import { cryptoPaths } from '../api/_lib/announce/ledger.js';
+import { languageProblems } from '../api/_lib/x-content/editorial.js';
+import { harvestFacts, harvestStats, quotableLines } from '../api/_lib/announce/brief.js';
import { draftFindings, itemFor, parseDraft } from '../api/_lib/announce/draft.js';
import { cardFacts, cardHtml, commandFrom, namesFrom } from '../api/_lib/announce/card.js';
import { renderPack } from '../api/_lib/announce/kit.js';
@@ -85,6 +87,51 @@ describe('plan', () => {
expect(plan.slots.map((slot) => [slot.tier, slot.slotTier])).toEqual([[1, 3], [1, 1]]);
});
+ it('gives a pinned surface the earliest slot of its tier instead of waiting for its score', () => {
+ const args = {
+ cadence: { ...CADENCE, slots: [{ tier: 2, at: '12:00' }] },
+ quality: QUALITY,
+ start: '2026-10-01',
+ };
+ const entries = [
+ entry('/mocap-studio', { score: 90 }),
+ entry('/capture', { score: 80 }),
+ entry('/awesome', { section: 'learn', score: 40 }),
+ ];
+ const unpinned = buildPlan(entries, args);
+ expect(unpinned.slots.map((slot) => slot.key)).toEqual(['/mocap-studio', '/capture', '/awesome']);
+ expect(unpinned.totals.pinned).toBe(0);
+
+ const pinned = buildPlan(entries, { ...args, pinned: new Map([['/awesome', 'the owner asked for it']]) });
+ expect(pinned.slots.map((slot) => slot.key)).toEqual(['/awesome', '/mocap-studio', '/capture']);
+ expect(pinned.slots[0].notBefore).toBe('2026-10-01T12:00:00Z');
+ expect(pinned.slots[0].pinned).toBe('the owner asked for it');
+ expect(pinned.totals.pinned).toBe(1);
+ // A pin reorders the backlog; it never adds a slot or moves a time.
+ expect(pinned.slots.map((slot) => slot.notBefore)).toEqual(unpinned.slots.map((slot) => slot.notBefore));
+ });
+
+ it('keeps a pinned surface inside the slot its own tier owns', () => {
+ const plan = buildPlan(
+ [
+ entry('@three-ws/alerts-mcp', { kind: 'package', section: 'package', score: 90 }),
+ entry('/mocap-studio', { score: 85 }),
+ entry('/awesome', { section: 'learn', score: 40 }),
+ ],
+ {
+ cadence: { ...CADENCE, slots: [{ tier: 3, at: '04:00' }, { tier: 2, at: '12:00' }] },
+ quality: QUALITY,
+ start: '2026-10-01',
+ pinned: new Map([['/awesome', 'the owner asked for it']]),
+ },
+ );
+ const slot = plan.slots.find((row) => row.key === '/awesome');
+ // Not the 04:00 slot, which belongs to proof of work, even though the
+ // pin puts /awesome first in the queue of things to place.
+ expect([slot.notBefore, slot.tier, slot.slotTier]).toEqual(['2026-10-01T12:00:00Z', 2, 2]);
+ expect(plan.slots[0].key).toBe('@three-ws/alerts-mcp');
+ });
+
it('holds an owner-gated surface out of the calendar instead of dating a slot nobody can fill', () => {
const args = {
cadence: { ...CADENCE, slots: [{ tier: 3, at: '04:00' }, { tier: 2, at: '12:00' }, { tier: 1, at: '20:00' }] },
@@ -132,6 +179,9 @@ describe('plan', () => {
it('only offers a motion pattern to a surface with a route', () => {
expect(patternsFor(entry('/flow', { signals: { visual: 25 } }))).toContain('clip');
expect(patternsFor(entry('@three-ws/flow', { url: null, signals: { visual: 25 } }))).not.toContain('clip');
+ // The capture photographed this one twice and nothing changed, so the
+ // ledger carries moves:false and no pattern may promise a loop of it.
+ expect(patternsFor(entry('/awesome', { signals: { visual: 25 }, moves: false }))).not.toContain('clip');
});
it('never repeats a pattern back to back, and holds the lane run limit', () => {
@@ -190,6 +240,30 @@ describe('brief', () => {
expect(quotableLines(dashed)).toEqual([]);
expect(harvestFacts(dashed)).toEqual([]);
});
+
+ it('harvests the counters a stats page leads with, which are not sentences', () => {
+ const page = [
+ 'Sign in',
+ 'ENTRIES',
+ '152',
+ 'SECTIONS',
+ '15',
+ 'FREE TO USE',
+ '121',
+ '152 entries across 15 sections',
+ 'Each entry says in one sentence what the thing does.',
+ ].join('\n');
+ const stats = harvestStats(page);
+ expect(stats).toContain('ENTRIES 152');
+ expect(stats).toContain('FREE TO USE 121');
+ expect(stats).toContain('152 entries across 15 sections');
+ // Navigation furniture is not a fact about the surface.
+ expect(stats.some((line) => /sign in/i.test(line))).toBe(false);
+ // Every candidate is still a literal substring of the page once
+ // whitespace is collapsed, which is the check verify.js runs.
+ const flat = page.replace(/\s+/g, ' ');
+ for (const line of stats) expect(flat.includes(line)).toBe(true);
+ });
});
const BRIEF = {
@@ -215,6 +289,24 @@ const GOOD = {
telegram: '',
};
+describe('the inventory these rules are applied to', () => {
+ it('gates the crypto namespace wherever a page is filed, not just the crypto section', () => {
+ const gated = cryptoPaths(process.cwd());
+ // Filed under `learn`, renders live third-party market data.
+ expect(gated.has('/crypto-api')).toBe(true);
+ expect(gated.has('/crypto')).toBe(true);
+ // Filed under `learn`, renders a hand-curated list of open-source projects.
+ expect(gated.has('/awesome')).toBe(false);
+ });
+
+ it('bans awesome as an adjective and allows it as the name of a list', () => {
+ const flagged = (text) => languageProblems(text).some((problem) => /awesome/i.test(problem.message));
+ expect(flagged('This release is awesome.')).toBe(true);
+ expect(flagged('Awesome 3D Agents maps the whole pipeline.')).toBe(false);
+ expect(flagged('Published in the standard awesome list format on GitHub.')).toBe(false);
+ });
+});
+
describe('draft', () => {
it('passes a draft that cites the brief and stays in the band', () => {
expect(draftFindings(BRIEF, GOOD)).toEqual([]);