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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// The announcement calendar: which unannounced surface goes out, in what order,
// on which day, in which lane and shape.
//
// scripts/announce-rank.mjs answers "what is worth announcing" and writes the
// ledger. This module answers the next question, which nobody had automated:
// given 300-plus never-announced surfaces and an account that can carry three
// posts a day without reading as a bot, what is the actual schedule?
//
// Everything here is pure so the schedule is reproducible: the same ledger and
// the same start date always produce the same calendar, which is what makes a
// plan reviewable rather than a fresh guess on every run.
//
// Three constraints shape it, and all three come from files that already exist
// rather than from taste:
//
// cadence data/x-content/queue.json: the slot table when it declares one
// (each slot is a time and the tier that owns it), otherwise the
// daily cap, minimum gap and quiet hours it is derived from.
// Slot times are read or derived, never hardcoded.
// rotation the same queue's quality block: no more than N of the same
// lane in a row, no more than M of the same pattern. The
// scheduler in api/_lib/x-content/schedule.js enforces this at
// publish time by *skipping* an item, so a calendar that ignores
// it would stall itself.
// pins data/announce-priority.json: surfaces somebody asked for
// next. They enter the sequencer first and take the earliest
// slot their own tier owns; the pin buys position, never a
// different cadence, lane rule or shape rule.
// the coin gate a frame captured from a surface under the `crypto` section of
// data/pages.json bakes live third-party tickers into a
// committed file, which the operating rules gate on owner
// approval. Those surfaces are planned like any other and carry
// `mediaGate`, so a batch can be run without them.
const MINUTE = 60_000;
// The queue's tiers, best first. Mirrors api/_lib/x-content/schedule.js.
export const TIERS = [1, 2, 3];
// Audience lane. Rotation only cares that neighbours differ, but the lane also
// decides who the pack is written for, so it is derived from where the surface
// lives rather than assigned round-robin.
export const LANES = ['community', 'developer', 'token', 'labs'];
// Post shape. Each surface gets a ranked list; the sequencer takes the first
// one that does not repeat its neighbour, which is how a 300-item run avoids
// converging on a single format.
export const PATTERNS = ['mechanism', 'clip', 'number', 'correction', 'walkthrough'];
const DEVELOPER_SECTIONS = new Set(['build', 'agent-tools', 'machine', 'package', 'worker', 'service']);
const TOKEN_RE = /\$THREE|\btoken\b|\bcoin\b|\bx402\b|\bwallet\b|\bUSDC\b|on-chain|onchain|\bmint\b|\btrading\b|\blaunchpad\b/i;
export function laneFor(entry) {
if (entry.section === 'crypto') return 'token';
if (entry.section === 'labs') return 'labs';
if (DEVELOPER_SECTIONS.has(entry.section)) return 'developer';
if (TOKEN_RE.test(`${entry.title} ${entry.description}`) && entry.signals?.token) return 'token';
return 'community';
}
// A surface that renders motion can carry a loop; one with a measured number in
// its own description can lead on the number. Everything can lead on mechanism,
// so it is always last and always available.
export function patternsFor(entry) {
const text = `${entry.title} ${entry.description}`;
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, 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);
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 (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');
ranked.push('mechanism');
return [...new Set(ranked)];
}
// `/labor-market` -> `labor-market`, `@three-ws/walk-sdk` -> `walk-sdk`,
// `workers/rigger` -> `worker-rigger`. Stable, because it becomes the queue id,
// the pack filename, and the media shot id.
export function slugFor(key) {
const raw = String(key || '');
if (raw.startsWith('@')) return raw.split('/').pop().replace(/[^a-z0-9-]+/gi, '-').toLowerCase();
if (raw.includes('/') && !raw.startsWith('/')) {
const [base, name] = raw.split('/');
return `${base.replace(/s$/, '')}-${name}`.replace(/[^a-z0-9-]+/gi, '-').toLowerCase();
}
return raw.replace(/^\//, '').replace(/[^a-z0-9-]+/gi, '-').toLowerCase() || 'home';
}
function minutesOf(value) {
const [hour, minute] = String(value).split(':').map(Number);
return hour * 60 + (minute || 0);
}
const inQuiet = (minutes, quiet) => {
if (!Array.isArray(quiet) || quiet.length !== 2) return false;
const [start, end] = quiet.map(minutesOf);
const at = ((minutes % 1440) + 1440) % 1440;
return start <= end ? at >= start && at < end : at >= start || at < end;
};
// The posting times of a day, derived from the cadence rather than chosen. A
// slot whose jitter window could land inside quiet hours is dropped, so the
// calendar never promises a slot the scheduler would refuse.
export function slotTimes(cadence = {}) {
const quiet = cadence.quietHoursUtc || null;
const cap = Math.max(1, Number(cadence.dailyCap ?? 3));
const gap = Math.max(60, Number(cadence.minimumMinutesApart ?? 240));
const window = Math.max(0, Number(cadence.windowMinutes ?? 90));
const first = quiet ? minutesOf(quiet[1]) + 60 : 13 * 60;
const spacing = Math.max(gap, 300);
const times = [];
for (let index = 0; index < cap; index++) {
const at = first + index * spacing;
if (at >= 1440) break;
if (inQuiet(at, quiet) || inQuiet(at + window, quiet)) continue;
times.push(`${String(Math.floor(at / 60)).padStart(2, '0')}:${String(at % 60).padStart(2, '0')}`);
}
return times.length ? times : ['13:00'];
}
// The same day as the publisher sees it: a list of slots, each with the tier
// that owns it. api/_lib/x-content/schedule.js reads `cadence.slots` and fills
// each one from its own tier first, so a calendar that ignored the table would
// promise times the publisher never uses and tiers it never fills.
export function slotTable(cadence = {}) {
const declared = Array.isArray(cadence.slots) ? cadence.slots : [];
const table = declared
.filter((slot) => slot && typeof slot.at === 'string' && TIERS.includes(Number(slot.tier)))
.map((slot) => ({ at: slot.at, tier: Number(slot.tier) }))
.sort((left, right) => minutesOf(left.at) - minutesOf(right.at));
if (table.length) return table;
// No table: fall back to the derived times, every one of them a feature
// slot, which is the tier the publisher itself defaults an item to.
return slotTimes(cadence).map((at) => ({ at, tier: 2 }));
}
// Which tier a surface belongs in, using the queue's own definitions: 1 is a
// flagship (a $THREE utility or a partner we can truthfully tag), 3 is proof of
// work (a package, worker or service, whose frame is a typeset card rather than
// a route), and 2 is a shipped feature with a page behind it.
export function tierFor(entry, lane = laneFor(entry)) {
if (!entry.url) return 3;
if (lane === 'token' || entry.partner) return 1;
return 2;
}
// The order a slot is filled from: its own tier, then the lower tiers, then the
// higher ones. It mirrors tierOrder() in the publisher, so the calendar degrades
// the same way the live scheduler does when one tier runs out of stock.
const tierOrderFor = (slotTier) => [...TIERS.filter((tier) => tier >= slotTier), ...TIERS.filter((tier) => tier < slotTier).reverse()];
function runLength(list, field, value) {
let run = 0;
for (let index = list.length - 1; index >= 0; index--) {
if (list[index][field] !== value) break;
run++;
}
return run;
}
// Greedy sequencer. Highest score first, but a candidate that would repeat the
// previous lane or pattern too many times yields to the next one that fits,
// and a candidate whose preferred pattern is blocked falls through its own
// ranked list before it gives up its slot.
export function sequence(entries, { maximumSameLaneInARow = 2, maximumSamePatternInARow = 1 } = {}, { tierAt = null } = {}) {
const pool = entries.map((entry) => ({
entry,
lane: laneFor(entry),
patterns: patternsFor(entry),
tier: tierFor(entry),
}));
const placed = [];
while (pool.length) {
let chosen = -1;
let pattern = null;
// Which of the remaining surfaces this position may take. With a slot
// table, a position belongs to a tier: the candidates are that tier's,
// and only when it is out of stock does the next tier get the slot,
// which is how the publisher fills down too. Rotation then chooses
// inside that group, so tier discipline never costs variety.
const wantedTier = tierAt ? tierAt(placed.length) : null;
const group = wantedTier
? (tierOrderFor(wantedTier).map((tier) => pool.filter((candidate) => candidate.tier === tier)).find((list) => list.length) || pool)
: pool;
const eligible = new Set(group);
for (let index = 0; index < pool.length; index++) {
const candidate = pool[index];
if (!eligible.has(candidate)) continue;
if (runLength(placed, 'lane', candidate.lane) >= maximumSameLaneInARow) continue;
pattern = candidate.patterns.find((option) => runLength(placed, 'pattern', option) < maximumSamePatternInARow) || null;
if (pattern) {
chosen = index;
break;
}
}
// Every remaining candidate repeats the neighbour. That happens whenever
// the inventory is lopsided (167 of the 316 unannounced surfaces are
// developer-lane packages, so a long developer run is unavoidable), and
// the scheduler's own starvation rule releases such an item a day past
// its slot. Shape still matters more than lane here, so the fallback
// takes the best candidate that can at least change the post's shape.
if (chosen < 0) {
const lastPattern = placed[placed.length - 1]?.pattern;
chosen = pool.findIndex((candidate) => eligible.has(candidate) && candidate.patterns.some((option) => option !== lastPattern));
if (chosen < 0) chosen = pool.findIndex((candidate) => eligible.has(candidate));
if (chosen < 0) chosen = 0;
pattern = pool[chosen].patterns.find((option) => option !== lastPattern) || pool[chosen].patterns[0];
}
const [candidate] = pool.splice(chosen, 1);
placed.push({ entry: candidate.entry, lane: candidate.lane, pattern, tier: candidate.tier });
}
return placed;
}
export function buildPlan(entries, { cadence = {}, quality = {}, start, cryptoPaths = new Set(), perDay = null, holdGated = false, pinned = new Map() } = {}) {
const table = slotTable(cadence).slice(0, perDay || Infinity);
const times = table.map((slot) => slot.at);
const day0 = Date.parse(`${start}T00:00:00Z`);
if (!Number.isFinite(day0)) throw new Error(`start must be a YYYY-MM-DD date, got ${start}`);
// A gated surface is one nobody can pack without the owner clearing its
// frame, so dating it into a near slot promises a post the factory cannot
// produce and pushes every surface it could have produced weeks out.
// `holdGated` lifts them out of the calendar and reports them instead.
const gatedOf = (entry) => Boolean(entry.url && cryptoPaths.has(entry.url));
const held = holdGated ? entries.filter(gatedOf) : [];
const plannable = holdGated ? entries.filter((entry) => !gatedOf(entry)) : entries;
// A pinned surface is one somebody judged worth posting ahead of its score,
// so it enters the sequencer first and takes the earliest slot its own tier
// owns. Everything else keeps the ledger's order behind it. The pin buys
// position only: tier, lane rotation and shape rotation all still apply,
// because those are what keep the account readable.
const pinRank = (entry) => {
const index = [...pinned.keys()].indexOf(entry.key);
return index < 0 ? Infinity : index;
};
const pinnable = [...plannable].sort((left, right) => pinRank(left) - pinRank(right));
// Each position is sequenced against the tier of the slot it will land in,
// so a flagship takes the flagship slot instead of whichever minute came
// next in the list, while lane and shape still rotate inside that tier.
const ordered = sequence(pinnable, quality, { tierAt: (position) => table[position % table.length].tier });
const slots = ordered.map((row, index) => {
const day = Math.floor(index / table.length);
const { at: time, tier: slotTier } = table[index % table.length];
const notBefore = new Date(day0 + day * 1440 * MINUTE + minutesOf(time) * MINUTE).toISOString().replace('.000Z', 'Z');
const slug = slugFor(row.entry.key);
const gated = gatedOf(row.entry);
return {
position: index + 1,
id: slug,
key: row.entry.key,
kind: row.entry.kind,
section: row.entry.section,
url: row.entry.url || null,
lane: row.lane,
pattern: row.pattern,
tier: row.tier,
slotTier,
notBefore,
windowMinutes: Number(cadence.windowMinutes ?? 90),
batch: Math.floor(day / 7) + 1,
score: row.entry.score,
partner: row.entry.partner || null,
shot: `${slug}-hero`,
motion: row.pattern === 'clip',
mediaGate: gated ? 'owner-approval' : null,
pinned: pinned.get(row.entry.key) || null,
pack: `docs/announcements/${slug}.md`,
};
});
return {
generatedAt: new Date().toISOString(),
start,
times,
holdGated: Boolean(holdGated),
held: held.map((entry) => ({
key: entry.key,
id: slugFor(entry.key),
url: entry.url || null,
lane: laneFor(entry),
tier: tierFor(entry),
score: entry.score,
why: 'the frame is captured from a surface rendering live third-party market data, which needs owner approval before it can be committed',
})).sort((left, right) => right.score - left.score),
perDay: times.length,
days: Math.ceil(slots.length / times.length),
totals: {
slots: slots.length,
pinned: slots.filter((slot) => slot.pinned).length,
gated: slots.filter((slot) => slot.mediaGate).length + held.length,
held: held.length,
byTier: Object.fromEntries(TIERS.map((tier) => [tier, slots.filter((slot) => slot.tier === tier).length])),
byLane: Object.fromEntries(LANES.map((lane) => [lane, slots.filter((slot) => slot.lane === lane).length])),
byPattern: Object.fromEntries(PATTERNS.map((pattern) => [pattern, slots.filter((slot) => slot.pattern === pattern).length])),
},
slots,
};
}