demos: oEmbed/embed metadata gaps blocking rich-player resolution on third-party platforms #285

Context

Goal: get the demo embed (demos/embed.html) to resolve as a rich interactive player — not a plain link card — when its URL is handed to oEmbed/OpenGraph consumers.

Investigation via iframely.com/debug confirmed the embed does resolve to a live, working player (video + captions + word-synced transcript playing inside the debugger iframe). So the core embed is sound and has no cross-origin problems. A few metadata gaps on our side stop it short of working everywhere, and they're all fixable here.

What's already working (verified 2026-08-30)

• demos/oembed.json is live — HTTP 200, content-type: application/json, "type": "rich", valid html iframe payload.
• OpenGraph tags in demos/embed.html are read correctly (updated og:description propagates to consumer cards).
• iframely resolves the og:video tags into a rich, interactive, playable embed.
• The player works inside a plain <iframe> — no cross-origin issues.

Actionable defects (all on our side)

1. demos/preview.png returns 404

$ curl -sI https://hyperaudio.github.io/hyperaudio-lite/demos/preview.png
HTTP/2 404

Both og:image and the oEmbed thumbnail_url point at this missing file, so every card-fallback and thumbnail shows a broken image. Fix: add demos/preview.png (640×480 to match the declared thumbnail_width/height).

2. No oEmbed discovery <link> in embed.html

The head has the OpenGraph og:video:* tags but no oEmbed discovery link, so a consumer that relies on oEmbed autodiscovery (rather than OG parsing) can't find oembed.json. iframely only succeeded via the OG video path. Fix: add to demos/embed.html:

<link rel="alternate" type="application/json+oembed"
      href="https://hyperaudio.github.io/hyperaudio-lite/demos/oembed.json?url=https%3A%2F%2Fhyperaudio.github.io%2Fhyperaudio-lite%2Fdemos%2Fembed.html"
      title="Hyperaudio Lite — interactive transcript">

3. oembed.json is static and ignores ?url=

$ curl -s '.../oembed.json'                    # 539 bytes
$ curl -s '.../oembed.json?url=...embed.html'  # identical 539 bytes

Spec-permissible for a single fixed resource, but some consumers validate that the response corresponds to the requested url, and a few reject endpoints that don't behave dynamically. Fix (optional / only if a consumer complains): a tiny Cloudflare Worker that echoes/validates the url parameter. Low priority.

Broader context — this is not the Leaflet path

The motivating use case (embedding on Leaflet) will not be solved by any metadata change here: Leaflet doesn't render arbitrary HTML/iframe embeds at all, so the oEmbed route is a non-starter for it specifically. Per the Discourse discussion, the intended Leaflet integration is a native "hypertranscript block":

• Transcript stored as structured JSON (as a blob — word-level timings for a 30–60 min talk exceed AT Proto's per-record size limit).
• The block renders that JSON to HAL-compatible HTML at display time — i.e. Hyperaudio Lite is the render target.
• Aligned to a standard.site schema so any standard.site-aware renderer (not just Leaflet) can consume the same canonical JSON.

So the fixes in this issue benefit oEmbed/OpenGraph consumers that do support rich embeds (and give us a clean proving-ground + fallback), while the Leaflet/standard.site block is tracked separately.

Acceptance criteria

• demos/preview.png exists and returns 200 (640×480).
• demos/embed.html includes an application/json+oembed discovery link.
• iframely debugger's Iframely tab (not just the OpenGraph tab) returns a rich player.
• Card fallback shows the real thumbnail, not a broken image.