@homie-rocks/studio 0.26.1 → 0.28.0

package/lib/media.mjs

@@ -14,6 +14,7 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, normalize, relative, resolve, sep } from 'node:path';
+import { isoDate } from './site.mjs';
 
 export const SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
 export const KINDS = {
@@ -177,12 +178,18 @@ export function resolveMedia(root, kind, { r2 = false, deploy = false } = {}) {
     }
     const main = kind === 'music' ? 'audio' : 'video';
     if (!files.some((f) => f.role === main)) { skipped.push({ kind, item: item.slug, why: `no playable "${main}" file reachable (see the file lines above)` }); continue; }
+    if (kind === 'videos' && !isoDate(item.date) && !isoDate(item.made?.at)) notes.push({ kind, item: item.slug, file: 'date', why: 'no "date" (or made.at): its page names no upload date, so search engines will not show it as a video; add "date": "2026-09-30"' });
     entries.push({
       slug: item.slug, kind: KINDS[kind].includes(item.kind) ? item.kind : KINDS[kind][0], title: String(item.title).slice(0, 120), blurb: String(item.blurb ?? '').slice(0, 600),
       duration: Number.isFinite(item.duration) ? item.duration : null, bpm: Number.isFinite(item.bpm) ? item.bpm : null, key: item.key ?? null,
       lyrics: typeof item.lyrics === 'string' ? item.lyrics.slice(0, 8000) : null, credits: typeof item.credits === 'string' ? item.credits.slice(0, 600) : null,
       rights: item.rights && typeof item.rights === 'object' ? item.rights : null, for: item.for && typeof item.for === 'object' ? item.for : null,
       honesty: typeof item.honesty === 'string' ? item.honesty.slice(0, 600) : null, made: item.made?.at ? { at: item.made.at, provider: item.made.provider ?? null } : null,
+      // When it came out (0.27.0): `date` (a day, or a day and a time), else when it was made (`made.at`). A video's
+      // VideoObject needs it as its uploadDate; a song's MusicRecording says it as datePublished.
+      date: isoDate(item.date) ?? isoDate(item.made?.at) ?? null,
+      // A music manifest's `album` (or an entry's own): the songs' MusicAlbum.
+      ...(kind === 'music' && typeof (item.album ?? manifest.album) === 'string' && (item.album ?? manifest.album).trim() ? { album: String(item.album ?? manifest.album).trim().slice(0, 120) } : {}),
       files,
     });
   }

package/lib/redact.mjs

@@ -0,0 +1,99 @@
+/**
+ * SECRETS OUT OF TOOL OUTPUT. The Homie mod runs every tool result through `redact` before Claude reads it or the
+ * transcript keeps it. It only matches text: it never opens a key file, the keychain or the environment.
+ *
+ * What it hides: the studio's own one-time and owner keys (office and stats keys `hsk_`, progress write keys `hbk_`,
+ * agent passes `hap_…`, whose public id part stays), Cloudflare API tokens and global keys, provider keys (fal,
+ * ElevenLabs, Anthropic, OpenAI, GitHub, npm, Stripe keys and webhook secrets, AWS, Google), bearer tokens, private key blocks, and the value
+ * of any `NAME=value` whose name says key, token or secret.
+ *
+ * A link that carries one (the owner's one-time sign-in link, a confirm link, a player-owner link) is a link for the
+ * person, not for Claude: it is taken out whole and handed back in `links`, so the mod can show it to the person in
+ * its pane, and Claude reads that it is there.
+ */
+
+const HIDE = (kind) => `[${kind} hidden by Homie]`;
+
+/** Each rule: what it is, the pattern, and how to write what replaces a match (the default hides the whole match). */
+export const RULES = [
+  { kind: 'private key', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g },
+  { kind: 'office key', re: /\bhsk_[a-f0-9]{48}\b/g },
+  { kind: 'progress key', re: /\bhbk_[a-f0-9]{48}\b/g },
+  // An agent pass: its id (hap_ and ten hex digits) is public and stays; the secret after it goes.
+  { kind: 'agent pass', re: /\b(hap_[a-f0-9]{10})_[A-Za-z0-9_-]{40}(?![A-Za-z0-9_-])/g, to: (m, id) => `${id}_${HIDE('agent pass')}` },
+  { kind: 'Anthropic key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}/g },
+  { kind: 'OpenAI key', re: /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{32,}/g },
+  { kind: 'ElevenLabs key', re: /\bsk_[a-f0-9]{48}\b/g },
+  { kind: 'Stripe key', re: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g },
+  // A webhook signing secret has no live/test part: whsec_ and the secret itself.
+  { kind: 'Stripe webhook secret', re: /\bwhsec_[A-Za-z0-9+/=_-]{16,}/g },
+  { kind: 'fal key', re: /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:[0-9a-f]{32}\b/g },
+  { kind: 'GitHub token', re: /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{40,})\b/g },
+  { kind: 'npm token', re: /\bnpm_[A-Za-z0-9]{36}\b/g },
+  { kind: 'AWS key', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+  { kind: 'Google key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { kind: 'Cloudflare key', re: /(X-Auth-Key["']?\s*[:=]\s*["']?)([a-f0-9]{37})\b/gi, to: (m, head) => `${head}${HIDE('Cloudflare key')}` },
+  { kind: 'token', re: /(\b[Bb]earer\s+)([A-Za-z0-9_\-.~+/]{24,}=*)/g, to: (m, head) => `${head}${HIDE('token')}` },
+  // NAME=value (or NAME: value) where the name says what it is: CLOUDFLARE_API_TOKEN, FAL_KEY, ELEVENLABS_API_KEY ...
+  // Only a value that looks like a key (16+ characters of letters AND digits, no dots or brackets), so source code
+  // that names a key (`const FAL_KEY = process.env.FAL_KEY`) is never changed under Claude's eyes.
+  {
+    kind: 'secret',
+    re: /\b([A-Z][A-Z0-9_]*(?:API_KEY|API_TOKEN|_TOKEN|_SECRET|SECRET_KEY|_KEY|PASSWORD)\b["']?\s*[=:]\s*["']?)([A-Za-z0-9_\-+/=:]{16,})(?![A-Za-z0-9_.(])/g,
+    to: (m, head, value) => (/[A-Za-z]/.test(value) && /[0-9]/.test(value) ? `${head}${HIDE('secret')}` : m),
+  },
+];
+
+const URL_RE = /https?:\/\/[^\s"'<>`)\]]+/g;
+const LINK_SECRET = /\b(?:hsk|hbk)_[a-f0-9]{48}\b|\bhap_[a-f0-9]{10}_[A-Za-z0-9_-]{40}/;
+export const LINK_NOTE = '[one-time owner link: the Homie mod showed it to the person in its Studio pane; Claude never sees it]';
+
+/** Redact one string: { text, hits: [kinds], links: [urls] }. Unchanged text keeps its identity. */
+export function redactText(text) {
+  if (typeof text !== 'string' || text.length < 8) return { text, hits: [], links: [] };
+  const hits = [];
+  const links = [];
+  let out = text.replace(URL_RE, (url) => {
+    if (!LINK_SECRET.test(url)) return url;
+    links.push(url.replace(/[.,;:]+$/, ''));
+    hits.push('owner link');
+    return LINK_NOTE + url.slice(url.replace(/[.,;:]+$/, '').length);
+  });
+  for (const rule of RULES) {
+    rule.re.lastIndex = 0;
+    out = out.replace(rule.re, (...m) => {
+      const replaced = rule.to ? rule.to(...m) : HIDE(rule.kind);
+      if (replaced !== m[0]) hits.push(rule.kind);
+      return replaced;
+    });
+  }
+  return hits.length ? { text: out, hits, links } : { text, hits, links };
+}
+
+/**
+ * Redact every string inside a value (a tool's result record, an MCP result, a string), at most 12 levels deep.
+ * Returns { value, hits, links }; `value` is the same object when nothing was hidden.
+ */
+export function redact(value) {
+  const hits = [];
+  const links = [];
+  const walk = (v, depth) => {
+    if (typeof v === 'string') {
+      const r = redactText(v);
+      if (r.hits.length) { hits.push(...r.hits); links.push(...r.links); }
+      return r.text;
+    }
+    if (depth > 12 || v === null || typeof v !== 'object') return v;
+    if (Array.isArray(v)) {
+      let changed = false;
+      const next = v.map((x) => { const y = walk(x, depth + 1); if (y !== x) changed = true; return y; });
+      return changed ? next : v;
+    }
+    let changed = false;
+    const next = {};
+    for (const [k, x] of Object.entries(v)) { const y = walk(x, depth + 1); if (y !== x) changed = true; next[k] = y; }
+    return changed ? next : v;
+  };
+  const out = walk(value, 0);
+  return { value: out, hits: [...new Set(hits)], links: [...new Set(links)] };
+}

package/lib/scaffold.mjs

@@ -210,6 +210,9 @@ studio's pinned copy, never a registry lookup of the bare name.
 - **Cards and the directory** show each game's landing still (\`hero/wide.jpg\`), else its cover. A song without
   a cover of its own shows the music manifest's \`cover\`, else its game's still.
 - **Live rooms** are listed on homie.rocks too; studio.json \`"rooms": { "share": false }\` keeps them off it.
+- **Search engines and AI agents** read every page's schema.org data (a full VideoGame on each landing) and
+  \`/robots.txt\`, \`/sitemap.xml\`, \`/llms.txt\`, made from what is public. Give a game game.json \`"genre"\`, put
+  pictures of play in \`games/<id>/screenshots/\`, give each video a \`"date"\`, and never invent ratings.
 - Every page ends with "Made with Homie", linking to homie.rocks/studio/. Restyle it in \`site/theme.css\`; keep it.
 
 ## Making games
@@ -424,6 +427,18 @@ chat's card follows the work from then on) and, for a studio still being set up,
   the budget until the person says Proceed, and takes keys out of command output. When it refuses a call, say what
   you meant to do and why; do not retry it unless the person asks.
 
+## Telling Homie
+
+The people who make Homie read every note, and someone who is stuck rarely writes to a forum. So when the person is
+stuck, confused or frustrated, after an error you could not fix, or at the end of their first studio setup or first
+publish, you may OFFER, once in a session, to send them a short note about it: the Homie MCP's \`homie_feedback\`
+(in Claude Code also \`/feedback\`, and Tell Homie in the Studio pane). Draft it in plain words from what happened
+(what they tried, what they expected, what they saw); a draft sends nothing. Show it exactly as it would go, and send
+it only after they say yes (in Claude Code, Claude Code itself asks them with the exact note). Never nag: a no is
+final for the session, and help never depends on it. Never put a key, a log, a file, code or anyone's name in a
+note; a reply address only if they typed it. When they ask to tell Homie something, draft it with
+\`offered: false\`.
+
 ## Beta
 
 Homie for studios is in beta. When something breaks, or a game you want to port does
@@ -533,8 +548,8 @@ anything here wins. The whole list is in \`node_modules/@homie-rocks/studio/site
 | \`theme.json\` | The look: \`bg\`, \`fg\`, \`accent\`, \`glow\` colours, \`display\` and \`text\` fonts (\`fonts\` loads a file from \`public/\`), \`radius\`, \`mark\` (a logo). Or \`palette\`: neon, dock, gold, acid, ember, orchid, tide, candy. |
 | \`theme.css\` | Extra CSS on every page (restyle anything, the "Made with Homie" footer included). |
 | \`partials/<name>.html\` | A piece of every page: \`head\`, \`header\`, \`footer\`, \`home\` (a band on Home), \`game\` (a band on every game's landing), \`game-<id>\` (on one game's), \`post\`. |
-| \`pages/<path>/index.html\` | A whole page at \`/<path>/\`, instead of the generated one (\`pages/<id>/index.html\` replaces a game's landing) or beside them (\`pages/about/index.html\`). It may borrow \`<!-- homie:style -->\`, \`<!-- homie:header -->\`, \`<!-- homie:footer -->\`, \`<!-- homie:script -->\`. |
-| \`public/\` | Files served as they are, at the same path (\`public/fonts/x.woff2\` is \`/fonts/x.woff2\`). |
+| \`pages/<path>/index.html\` | A whole page at \`/<path>/\`, instead of the generated one (\`pages/<id>/index.html\` replaces a game's landing) or beside them (\`pages/about/index.html\`). It may borrow \`<!-- homie:style -->\`, \`<!-- homie:header -->\`, \`<!-- homie:footer -->\`, \`<!-- homie:script -->\`, and \`<!-- homie:schema -->\` in its \`<head>\` (the page's structured data for search engines). |
+| \`public/\` | Files served as they are, at the same path (\`public/fonts/x.woff2\` is \`/fonts/x.woff2\`). A \`robots.txt\`, \`sitemap.xml\` or \`llms.txt\` here replaces the one the site makes. |
 
 \`src/worker.mjs\` and \`migrations/\` are the Worker (its config is \`wrangler.jsonc\`, at the studio's root); \`dist/\` is the build (not committed).
 `;

package/lib/schema-check.mjs

@@ -0,0 +1,227 @@
+/**
+ * THE STRUCTURED-DATA CHECK (0.27.0): every `<script type="application/ld+json">` block of a page, read the way a
+ * search engine reads it, and held to two bars.
+ *
+ *   errors   the block is not valid JSON, has no schema.org @context, names a type or a property schema.org does
+ *            not have (schema-vocab.json, written from schema.org's own release file by scripts/schema-vocab.mjs),
+ *            puts a property on a type it is not for, or gives a value of the wrong kind (a date that is not ISO
+ *            8601, a duration that is not PT…, a type the property does not take, an enumeration member that is not
+ *            one of its enumeration's).
+ *   google   what Google Search Central documents as required for the result each type can get: VideoGame (as a
+ *            Software App: name and offers.price, co-typed with another app type), VideoObject (name, thumbnailUrl,
+ *            uploadDate), BreadcrumbList (each ListItem's position and name, and its item except the last's),
+ *            ItemList (each ListItem's position and url), and the fields Homie holds itself to where Google requires
+ *            none (BlogPosting and every other Article: headline, datePublished, author.name; Organization: name, url;
+ *            MusicRecording: name, url, byArtist).
+ *   notes    what is true and not a fault: a Software App is shown as a rich result only with ratings or reviews,
+ *            which Homie never invents.
+ *
+ *   import { checkHtml, checkJsonLd } from '@homie-rocks/studio/lib/schema-check.mjs'  (or a relative path)
+ *   checkHtml(html) -> { blocks, errors, google, notes }
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+let vocabulary = null;
+/** schema.org's vocabulary, as scripts/schema-vocab.mjs wrote it beside this file. */
+export function vocab() {
+  vocabulary ??= JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'schema-vocab.json'), 'utf8'));
+  return vocabulary;
+}
+
+const DATATYPES = new Set(['Text', 'URL', 'Number', 'Integer', 'Float', 'Boolean', 'Date', 'DateTime', 'Time', 'CssSelectorType', 'XPathType', 'PronounceableText', 'Duration', 'DataType']);
+const ISO_DATE = /^\d{4}(?:-\d{2}(?:-\d{2})?)?$/;
+const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$/;
+const ISO_DURATION = /^P(?!$)(?:\d+Y)?(?:\d+M)?(?:\d+W)?(?:\d+D)?(?:T(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/;
+const ABS_URL = /^https?:\/\/[^\s<>"]+$/i;
+const SCHEMA = /^https?:\/\/schema\.org\/?$/;
+
+/** The JSON-LD blocks of a page: [{ text, value }] (value undefined when the block is not JSON). */
+export function jsonLdBlocks(html) {
+  const out = [];
+  const re = /<script\b[^>]*\btype\s*=\s*["']?application\/ld\+json["']?[^>]*>([\s\S]*?)<\/script>/gi;
+  for (let m = re.exec(String(html ?? '')); m; m = re.exec(String(html ?? ''))) {
+    let value;
+    try { value = JSON.parse(m[1]); } catch { value = undefined; }
+    out.push({ text: m[1], value });
+  }
+  return out;
+}
+
+const typesOf = (node) => (Array.isArray(node['@type']) ? node['@type'] : node['@type'] ? [node['@type']] : []).map((t) => String(t).replace(/^https?:\/\/schema\.org\//, '').replace(/^schema:/, ''));
+
+/** A type and every type above it. */
+function lineage(type, v = vocab()) {
+  const seen = new Set();
+  const walk = (t) => { if (seen.has(t)) return; seen.add(t); for (const p of v.types[t] ?? []) walk(p); };
+  walk(type);
+  return seen;
+}
+const isA = (type, want, v) => lineage(type, v).has(want);
+
+function checkValue(prop, value, ranges, at, errors, v) {
+  if (value === null || value === undefined) { errors.push(`${at}: ${prop} is empty`); return; }
+  const allowsText = ranges.some((r) => r === 'Text' || r === 'PronounceableText' || r === 'CssSelectorType' || r === 'XPathType');
+  const numeric = ranges.some((r) => r === 'Number' || r === 'Integer' || r === 'Float');
+  const onlyData = ranges.every((r) => DATATYPES.has(r));
+  const want = ranges.join(' or ');
+  if (typeof value === 'object') {
+    const types = typesOf(value);
+    if (!types.length) {
+      if (!value['@id']) errors.push(`${at}: ${prop} is an object with no @type`);
+      return;
+    }
+    if (onlyData) { errors.push(`${at}: ${prop} takes ${want}, not a ${types.join('/')}`); return; }
+    if (!types.some((t) => ranges.some((r) => r === 'Thing' || isA(t, r, v)))) errors.push(`${at}: ${prop} takes ${want}, not a ${types.join('/')}`);
+    return;
+  }
+  if (typeof value === 'boolean') {
+    if (!ranges.includes('Boolean')) errors.push(`${at}: ${prop} takes ${want}, not true or false`);
+    return;
+  }
+  if (typeof value === 'number') {
+    if (!numeric && !ranges.includes('QuantitativeValue')) errors.push(`${at}: ${prop} takes ${want}, not a number`);
+    else if (ranges.includes('Integer') && !ranges.includes('Number') && !Number.isInteger(value)) errors.push(`${at}: ${prop} is a whole number`);
+    return;
+  }
+  const s = String(value);
+  // An enumeration's member, by its schema.org address.
+  const enums = ranges.filter((r) => v.types[r] && isA(r, 'Enumeration', v));
+  const member = /^https?:\/\/schema\.org\/([A-Za-z0-9]+)$/.exec(s)?.[1];
+  if (enums.length && member && v.members[member]) {
+    if (!v.members[member].some((e) => enums.some((r) => isA(e, r, v)))) errors.push(`${at}: ${prop} "${s}" is not one of ${enums.join(' or ')}`);
+    return;
+  }
+  if (ranges.includes('DateTime') || ranges.includes('Date')) {
+    if (ISO_DATE.test(s) || ISO_DATETIME.test(s)) return;
+    if (!allowsText) { errors.push(`${at}: ${prop} "${s.slice(0, 40)}" is not an ISO 8601 date`); return; }
+  }
+  if (ranges.includes('Duration')) {
+    if (ISO_DURATION.test(s)) return;
+    if (!allowsText) { errors.push(`${at}: ${prop} "${s.slice(0, 40)}" is not an ISO 8601 duration (PT1M5S)`); return; }
+  }
+  if (numeric && /^-?\d+(?:\.\d+)?$/.test(s)) return;
+  if (allowsText) return;
+  // A URL, or a thing given by its address.
+  if (ABS_URL.test(s)) return;
+  if (enums.length) { errors.push(`${at}: ${prop} "${s.slice(0, 60)}" is not a member of ${enums.join(' or ')} (https://schema.org/<Member>)`); return; }
+  errors.push(`${at}: ${prop} takes ${want}, not "${s.slice(0, 60)}"`);
+}
+
+/** Every node, depth first, with where it is: [{ node, at, depth, via }]. */
+function nodesOf(value, at = '$', depth = 0, via = null, out = []) {
+  if (Array.isArray(value)) { value.forEach((x, i) => nodesOf(x, `${at}[${i}]`, depth, via, out)); return out; }
+  if (!value || typeof value !== 'object') return out;
+  out.push({ node: value, at, depth, via });
+  for (const [k, x] of Object.entries(value)) {
+    if (k === '@context') continue;
+    if (k === '@graph') { nodesOf(x, `${at}.@graph`, depth, null, out); continue; }
+    if (x && typeof x === 'object') nodesOf(x, `${at}.${k}`, depth + 1, k, out);
+  }
+  return out;
+}
+
+/** One block's value: { errors, google, notes }. */
+export function checkJsonLd(value) {
+  const v = vocab();
+  const errors = [];
+  const google = [];
+  const notes = [];
+  const tops = Array.isArray(value) ? value : [value];
+  for (const top of tops) {
+    if (!top || typeof top !== 'object') { errors.push('$: a block is a JSON object (or a list of them)'); continue; }
+    if (!SCHEMA.test(String(top['@context'] ?? ''))) errors.push(`$: @context is "https://schema.org" (it is ${JSON.stringify(top['@context'] ?? null)})`);
+  }
+  for (const { node, at, depth, via } of tops.flatMap((t) => nodesOf(t))) {
+    const types = typesOf(node);
+    if (node['@id'] !== undefined && !(typeof node['@id'] === 'string' && (ABS_URL.test(node['@id']) || node['@id'].startsWith('#')))) errors.push(`${at}: @id is an absolute URL`);
+    const keys = Object.keys(node).filter((k) => !k.startsWith('@'));
+    if (!types.length) {
+      if (keys.length && !node['@graph'] && !node['@id']) errors.push(`${at}: an object with properties has a @type`);
+      if (!keys.length) continue;
+    }
+    for (const t of types) if (!v.types[t]) errors.push(`${at}: "${t}" is not a schema.org type`);
+    const known = types.filter((t) => v.types[t]);
+    const lines = new Set(known.flatMap((t) => [...lineage(t, v)]));
+    for (const k of keys) {
+      const p = v.props[k];
+      if (!p) { errors.push(`${at}: "${k}" is not a schema.org property`); continue; }
+      const [domains, ranges, superseded] = p;
+      if (known.length && !domains.some((d) => lines.has(d))) errors.push(`${at}: "${k}" is not a property of ${known.join('/')} (it is for ${domains.join(', ')})`);
+      if (superseded) errors.push(`${at}: "${k}" is superseded by "${superseded}"`);
+      for (const x of Array.isArray(node[k]) ? node[k] : [node[k]]) checkValue(k, x, ranges, at, errors, v);
+    }
+    // Google's bar: what the result each type can get requires. Top-level nodes, and every video.
+    const top = depth === 0;
+    const has = (k) => node[k] !== undefined && node[k] !== null && node[k] !== '' && !(Array.isArray(node[k]) && !node[k].length);
+    if (top && known.some((t) => isA(t, 'SoftwareApplication', v))) {
+      if (!has('name')) google.push(`${at}: a ${known.join('/')} has a name`);
+      const offers = Array.isArray(node.offers) ? node.offers : node.offers ? [node.offers] : [];
+      if (!offers.length || offers.some((o) => o.price === undefined)) google.push(`${at}: a ${known.join('/')} has offers.price (0 when it is free)`);
+      if (known.includes('VideoGame') && known.length < 2) google.push(`${at}: Google shows no Software App result for a bare VideoGame; co-type it (["VideoGame", "WebApplication"])`);
+      if (!has('aggregateRating') && !has('review')) notes.push(`${at}: a Software App is shown as a rich result only with aggregateRating or review; none is given (Homie never invents one)`);
+    }
+    if (known.some((t) => isA(t, 'VideoObject', v)) && (top || via === 'trailer' || via === 'video')) {
+      for (const k of ['name', 'thumbnailUrl', 'uploadDate']) if (!has(k)) google.push(`${at}: a VideoObject has ${k}`);
+      if (has('uploadDate') && /T\d/.test(node.uploadDate) && !/(?:Z|[+-]\d{2}:?\d{2})$/.test(node.uploadDate)) google.push(`${at}: uploadDate has a time zone`);
+    }
+    if (top && known.some((t) => isA(t, 'BreadcrumbList', v))) {
+      const items = node.itemListElement ?? [];
+      if (!items.length) google.push(`${at}: a BreadcrumbList has itemListElement`);
+      items.forEach((li, i) => {
+        if (li?.position !== i + 1) google.push(`${at}.itemListElement[${i}]: position is ${i + 1}`);
+        if (!li?.name) google.push(`${at}.itemListElement[${i}]: a breadcrumb has a name`);
+        if (i < items.length - 1 && !li?.item) google.push(`${at}.itemListElement[${i}]: a breadcrumb before the last has an item`);
+      });
+    }
+    if (top && known.some((t) => isA(t, 'ItemList', v) && !isA(t, 'BreadcrumbList', v))) {
+      (node.itemListElement ?? []).forEach((li, i) => {
+        if (li?.position !== i + 1) google.push(`${at}.itemListElement[${i}]: position is ${i + 1}`);
+        if (!li?.url && !li?.item) google.push(`${at}.itemListElement[${i}]: a list item has a url`);
+      });
+    }
+    if (top && known.some((t) => isA(t, 'Article', v))) {
+      if (!has('headline')) google.push(`${at}: an article has a headline`);
+      if (has('headline') && String(node.headline).length > 110) google.push(`${at}: a headline is at most 110 characters`);
+      if (!has('datePublished')) google.push(`${at}: an article has datePublished`);
+      const authors = Array.isArray(node.author) ? node.author : node.author ? [node.author] : [];
+      if (!authors.length || authors.some((a) => !a?.name)) google.push(`${at}: an article's author has a name`);
+    }
+    if (top && known.some((t) => t === 'Organization' || isA(t, 'Organization', v)) && !known.some((t) => isA(t, 'CreativeWork', v))) {
+      if (!has('name')) google.push(`${at}: an Organization has a name`);
+      if (!has('url')) google.push(`${at}: an Organization has a url`);
+    }
+    if (top && known.some((t) => isA(t, 'MusicRecording', v))) {
+      for (const k of ['name', 'url', 'byArtist']) if (!has(k)) google.push(`${at}: a MusicRecording has ${k}`);
+    }
+  }
+  return { errors, google, notes };
+}
+
+/** Every JSON-LD block of a page, checked. */
+export function checkHtml(html) {
+  const blocks = jsonLdBlocks(html);
+  const errors = [];
+  const google = [];
+  const notes = [];
+  blocks.forEach((b, i) => {
+    if (b.value === undefined) { errors.push(`block ${i + 1}: not valid JSON`); return; }
+    const r = checkJsonLd(b.value);
+    errors.push(...r.errors.map((e) => `block ${i + 1} ${e}`));
+    google.push(...r.google.map((e) => `block ${i + 1} ${e}`));
+    notes.push(...r.notes.map((e) => `block ${i + 1} ${e}`));
+  });
+  return { blocks: blocks.map((b) => b.value), errors, google, notes };
+}
+
+/** The types a page's blocks declare, top-level graph nodes only, in order: ["Organization", "WebSite"]. */
+export function typesOnPage(html) {
+  const out = [];
+  for (const b of jsonLdBlocks(html)) {
+    const v = b.value;
+    const tops = Array.isArray(v) ? v : v?.['@graph'] ?? (v ? [v] : []);
+    for (const n of tops) out.push(...typesOf(n));
+  }
+  return out;
+}