@homie-rocks/studio 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -17,9 +17,43 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.27.0] - 2026-10-03
+
+**Plugin 0.28.0** · [#42](https://github.com/homie-rocks/homie/pull/42)
+
+Search engines and AI agents read a studio's site correctly: schema.org data on every page, a full VideoGame on every landing, and a sitemap, robots.txt and llms.txt made from what is public.
+
+### Added
+
+- Structured data (schema.org JSON-LD) on every generated page, from the studio's own files and nothing else:
+  - Home: the studio as an `Organization` (its name, address, logo, share picture and tagline) and its `WebSite`.
+  - Each game's landing: a `VideoGame` (co-typed `WebApplication`, as Google asks) with its description and pitch, pictures and screenshots, genre, players (fewest and most), play modes, platforms, the studio as author and publisher, the source's licence (linked to its SPDX page when it names one), what it is based on (a remix's original page, a port's original), its trailer as a `VideoObject`, when it came out and last changed, a Play action and a free-to-play offer.
+  - Music: `MusicRecording` (the studio as the artist, its length, its audio file, its cover, its key and date) and a `MusicAlbum` when the music manifest names one. Videos: `VideoObject` (poster, upload date, length, the file itself). Posts: `BlogPosting` and the studio's `Blog`. Games and Rooms: an `ItemList` of the public games. Every page but Home: a `BreadcrumbList`.
+- Never a rating or a review, and no price for anything the shop does not sell. While your shop really sells, each item sold in a game is an add-on of that game's free offer, in real money. The Rooms page's data names the games, never who is playing this minute.
+- `/robots.txt`, `/sitemap.xml`, `/llms.txt` and `/llms-full.txt`, made from your public catalogue:
+  - robots.txt lets crawlers read every public page, keeps them off your office, the APIs, accounts and each game's play, TV, watch and socket doors, and names the sitemap. A Preview asks not to be crawled.
+  - The sitemap lists Home, Games and each landing, Music, Videos, Rooms, Posts and your own pages, with dates only where a real date says when each changed.
+  - llms.txt tells an AI agent what your studio is: each game with its pitch, players, Play, Watch and big-screen links; which games are open to remix, with the licence, the source and the words to say to Claude Code or Codex with Homie; songs, videos, posts with their feeds, your own pages, and homie.rocks's llms.txt. llms-full.txt adds each game's whole description, how to play and credits, and every post's text.
+  - A private or invite-only game is in none of them, and a game is offered for remixing only when its source is shared, your Remixable switch is on and its licence allows it.
+- game.json takes `"genre"` (a word, or up to three), `"released"` (the day it came out) and `"schema"` (schema.org properties of your own on the game). studio.json takes `"site": { "schema": { … } }` for the studio, such as `"sameAs"` links to its other pages. Homie's own properties always win, and ratings, reviews and offers are refused (the build says so).
+- Screenshots: pictures in `games/<id>/screenshots/` (or game.json `landing.screenshots`), at most eight, get a band on the landing and go into its VideoGame. A game's genre shows with its room facts.
+- A video's or song's `"date"` in its manifest; without one, when it was made (`made.at`). Search engines show no video without an upload date, so the build says when a video has neither.
+- `<!-- homie:schema -->` in the `<head>` of a page of your own (`site/pages`) puts there the structured data the generated page would carry.
+- `lib/schema-check.mjs` checks every JSON-LD block of a page against schema.org's own vocabulary (types, properties, which type each property is for, value kinds, enumerations) and against what Google documents as required for VideoGame, VideoObject, BreadcrumbList, ItemList, BlogPosting, Organization and MusicRecording.
+
+### Changed
+
+- A landing's VideoGame was a short block with a price of 0 and no co-type; it is now the full record above, inside one `@graph` with the page's breadcrumbs.
+- A private or invite-only game's landing, which only its owner and invitees see, answers `x-robots-tag: noindex`.
+
+### Upgrade notes
+
+- Nothing to do: `homie-studio upgrade` and a deploy bring all of it. Give each game a `"genre"`, put a few pictures of real play in `games/<id>/screenshots/`, give each video a `"date"` if it has no `made.at`, and add your studio's other pages to `studio.json` `"site": { "schema": { "sameAs": [...] } }`.
+- A `robots.txt`, `sitemap.xml`, `llms.txt` or `llms-full.txt` you already keep in `site/public/` still wins over the made one. A landing or Home page of your own in `site/pages/` is left exactly as it is; add `<!-- homie:schema -->` to its `<head>` to give it the structured data.
+
 ## [0.26.1] - 2026-10-03
 
-**Plugin 0.27.1** · [#41](https://github.com/homie-rocks/homie/pull/41)
+**Plugin 0.27.1** · [#41](https://github.com/homie-rocks/homie/pull/41) · [release-2026-10-03-studio-0.26.1](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-03-studio-0.26.1)
 
 In Codex, Homie now holds what the Claude Code mod holds: protected files, deploys, Cloudflare changes, spending past the budget and model downloads wait for your own "proceed", and secrets come out of what Codex reads.
 

package/README.md

@@ -107,6 +107,14 @@ in that palette, light or dark as its paper is (0.26.0). Every HTML answer is `n
 site. A game made with Homie's arcade controls that knocks for a Homie box (`/__homie/call`) is told
 `not-a-homie`, at the site's root as under the game.
 
+Search engines and AI agents read a studio correctly (0.27.0): every generated page carries schema.org JSON-LD
+(`worker/schema.mjs`: the studio's `Organization` and `WebSite` on Home, a full `VideoGame` on each landing with its
+players, platforms, licence, remix original, trailer, dates and a free-to-play offer whose add-ons are what the shop
+really sells, `MusicRecording`, `VideoObject`, `BlogPosting`, `ItemList` and `BreadcrumbList`; never a rating), and the
+site makes `/robots.txt`, `/sitemap.xml`, `/llms.txt` and `/llms-full.txt` from its public catalogue
+(`worker/discover.mjs`). `lib/schema-check.mjs` checks every block against schema.org's own vocabulary and what Google
+documents as required. game.json `"schema"` and studio.json `site.schema` add the owner's own properties.
+
 Anyone can **watch** a live room from any player's view at `/<game>/watch?room=<room>` (a Watch button sits beside
 Join on every room): the game itself, drawn by the watcher's own browser as a watcher that never takes a seat,
 with a strip of the players to switch between (a tap, keys 1-9, Auto, the whole room). A game draws the followed

package/lib/build.mjs

@@ -40,7 +40,9 @@ import { join, relative } from 'node:path';
 import { buildCodexPages } from './codex.mjs';
 import { servedAssets } from './asset-manifest.mjs';
 import { buildMedia } from './media.mjs';
-import { buildSiteFiles, landingOf, readPosts, readTheme } from './site.mjs';
+import { buildSiteFiles, isoDate, landingOf, readPosts, readTheme } from './site.mjs';
+import { checkJsonLd } from './schema-check.mjs';
+import { SCHEMA_REFUSED } from '../worker/schema.mjs';
 import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
 import { SEAT_MAX } from '../worker/seats.mjs';
 import { STUDIO_VERSION } from './version.mjs';
@@ -152,6 +154,57 @@ function readJson(path) {
   try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
 }
 
+/**
+ * When a game came and last changed (its landing's datePublished and dateModified, and the sitemap's lastmod):
+ * game.json `"released"` (a day) when the owner says so, else the commit that added its game.json; and the last
+ * commit that touched its folder. Nothing from a shallow clone (its first commit would claim every file was made that
+ * day) or a folder git does not track.
+ */
+export function gameDates(root, g, log = () => {}) {
+  const git = (args) => { try { const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 5000 }); return r.status === 0 ? r.stdout.trim() : null; } catch { return null; } };
+  const released = isoDate(g.released);
+  if (g.released !== undefined && !released) log(`warning: games/${g.id}/game.json "released" is a day (2026-09-30); left out`);
+  const shallow = git(['rev-parse', '--is-shallow-repository']);
+  if (shallow !== 'false') return released ? { published: released } : null;
+  const rel = relative(root, g.dir).split('\\').join('/');
+  const added = git(['log', '--diff-filter=A', '--format=%cI', '--', `${rel}/game.json`])?.split('\n').filter(Boolean).pop() ?? null;
+  const last = git(['log', '-1', '--format=%cI', '--', rel]) || null;
+  const iso = (v) => (v && Number.isFinite(Date.parse(v)) ? new Date(Date.parse(v)).toISOString() : null);
+  const out = { published: released ?? iso(added), modified: iso(last) };
+  if (out.published && out.modified && Date.parse(out.modified) < Date.parse(out.published)) out.modified = out.published;
+  return out.published || out.modified ? Object.fromEntries(Object.entries(out).filter(([, v]) => v)) : null;
+}
+
+/**
+ * The owner's own structured data (game.json "schema", studio.json "site": { "schema" }): a plain object of schema.org
+ * properties put on the game's VideoGame (the studio's Organization), under Homie's own. Ratings, reviews and offers
+ * are refused (Homie shows no ratings on the page; prices are shop.json's), and so is anything that is not JSON-LD a
+ * page can carry; a property schema.org does not have, or does not put on that type, is warned about.
+ */
+export function schemaExtras(value, { where, types, log = () => {} }) {
+  if (value === undefined) return null;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) { log(`warning: ${where} "schema" is an object of schema.org properties; left out`); return null; }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (SCHEMA_REFUSED.includes(k)) { log(`warning: ${where} schema.${k} is left out: Homie publishes no ${k === 'offers' ? 'prices but the shop\'s (shop.json)' : 'ratings or reviews the page does not show'}`); continue; }
+    if (!/^[a-z][A-Za-z0-9]{0,63}$/.test(k)) { log(`warning: ${where} schema "${k.slice(0, 40)}" is not a property name (Homie sets @type and @id); left out`); continue; }
+    out[k] = v;
+  }
+  const json = JSON.stringify(out);
+  if (json.length > 8192) { log(`warning: ${where} "schema" is over 8 KB; left out`); return null; }
+  const { errors } = checkJsonLd({ '@context': 'https://schema.org', '@type': types, ...out });
+  for (const e of errors) log(`warning: ${where} schema: ${e.replace(/^\$: /, '')}`);
+  return Object.keys(out).length ? out : null;
+}
+
+/** game.json "genre": a word or up to three ("Arcade", ["Racing", "Party"]); its landing and VideoGame say it. */
+export function genreOf(g, log = () => {}) {
+  if (g.genre === undefined) return null;
+  const list = (Array.isArray(g.genre) ? g.genre : [g.genre]).filter((x) => typeof x === 'string' && x.trim()).map((x) => x.trim().slice(0, 40)).slice(0, 3);
+  if (!list.length) log(`warning: games/${g.id}/game.json "genre" is a word or a list of up to three; left out`);
+  return list.length ? list : null;
+}
+
 /**
  * A game's netplay manifest: game.json's `netplay` block, over a `netplay.json` beside game.json or in the game's
  * built output (a ported Vite game ships public/netplay.json), over nothing.
@@ -357,6 +410,11 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
     // The game's own palette (style.json, its art direction): the play page's buttons wear its paper and ink, so the
     // page's pills and the game's own HUD are one UI.
     const ui = uiOf(g);
+    // Search engines and agents (0.27.0, worker/schema.mjs): its genre, when it came and last changed, and the owner's
+    // own schema.org properties.
+    const genre = genreOf(g, log);
+    const dates = gameDates(root, g, log);
+    const extras = schemaExtras(g.schema, { where: `games/${g.id}/game.json`, types: ['VideoGame', 'WebApplication'], log });
     return {
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
       ...(ui ? { ui } : {}),
@@ -384,6 +442,9 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
       // Its source licence (worker/license.mjs), and, for a remix, what it is a remix of (shown on its landing).
       license: licenseOf(g.license),
       ...(remixRow(g.remixOf) ? { remixOf: remixRow(g.remixOf) } : {}),
+      ...(genre ? { genre } : {}),
+      ...(dates ? { dates } : {}),
+      ...(extras ? { schema: extras } : {}),
       landing: landingOf(g, join(dist, 'games', g.id), { videos: media.videos, songs: media.songs, log }),
     };
   });
@@ -394,11 +455,14 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   mkdirSync(join(dist, '_site'), { recursive: true });
   writeFileSync(join(dist, '_site', 'posts.json'), `${JSON.stringify({ v: 1, posts })}\n`);
   const s = studio.site && typeof studio.site === 'object' ? studio.site : {};
+  const studioExtras = schemaExtras(s.schema, { where: 'studio.json site', types: 'Organization', log });
   const catalogue = {
     studio: {
       name: studio.name, slug: studio.slug, version: STUDIO_VERSION,
       ...(typeof studio.tagline === 'string' && studio.tagline.trim() ? { tagline: studio.tagline.trim().slice(0, 140) } : {}),
       theme,
+      // studio.json "site": { "schema": { … } }: the owner's own schema.org properties on the studio (sameAs, …).
+      ...(studioExtras ? { schema: studioExtras } : {}),
       site: {
         ...(rows.some((g) => g.id === s.featured) ? { featured: s.featured } : {}),
         ...(Array.isArray(s.frameAncestors) ? { frameAncestors: s.frameAncestors.filter((o) => /^https:\/\/[a-z0-9.-]+(?::\d+)?$/i.test(String(o))).slice(0, 8) } : {}),

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/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
@@ -533,8 +536,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;
+}