@acms-subir/core 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @acms-subir/core
 
+## 0.3.1
+
+### Patch Changes
+
+- 2555746: Add owner-configured Twitch and YouTube live-video connections with guided setup, encrypted credentials, Google read-only OAuth, connection tests and scheduled discovery. Shared homepage sections, widgets and links-page cards show fresh live status with optional click-to-load players, manual overrides and neutral fallback links. Include token renewal, quota backoff, stale-status expiry, safe backup/restore behavior and setup documentation. Live cards come in poster, split and compact-row styles with same-site thumbnails, optional viewer counts, an upcoming countdown and a slim offline row; optional site-wide signals (live bar, header marker, floating card) and a themeable `--live-*` token set.
+- e93111f: Add signed outgoing webhooks for post/page publication, updates, unpublishing and deletion; design publication; media creation, alt-text updates and deletion; and content backup restoration. Content notifications cover admin, agents, bulk operations and scheduled posts, while pending drafts remain private. Persist new deliveries atomically with their database writes and lease deliveries to prevent simultaneous request/cron sends.
+
+  Move API & webhooks to the site-wide Team section, available without the calendar, and add `/api/webhooks/docs` with event contracts and receiver guidance. Migration 33 installs the transactional notification triggers. Existing explicit subscriptions remain unchanged; wildcard subscriptions include the new events.
+
 ## 0.3.0
 
 ### Minor Changes

package/docs/live-video.md

@@ -0,0 +1,91 @@
+# Live video connections
+
+ACMS can discover a site's current YouTube or Twitch broadcast and display it on its homepage and links page. Each site owner registers their own developer application and supplies its credentials. ACMS makes API requests from the deployed site's server; there is no shared ACMS developer app, hosted proxy or shared quota. The streaming platform continues to broadcast and host the video.
+
+Open **Integrations → Live video** (`/admin/live`) as an owner. Connect a provider, run a successful test, turn the connection on, and save the display mode as **Automatic**. A healthy connection can be offline: starting a broadcast happens on the streaming platform, not in ACMS.
+
+## Before connecting
+
+- Set the site's canonical URL in Settings. Use that exact origin to sign in and authorize YouTube, including whether it uses `www`. Production callbacks require HTTPS; localhost HTTP is allowed for development.
+- Supply a strong `SESSION_SECRET` (at least 32 random characters), or a separate `LIVE_ENCRYPTION_KEY` of that length, using the host's secret configuration. Live credentials use AES-256-GCM and a separate encryption context. An explicit live key takes precedence. Losing/changing the effective encryption key requires re-entering credentials and reauthorizing.
+- Ensure the independent scheduler runs every minute. Workers deployments use the existing scheduled handler/cron trigger; self-hosted Docker uses the existing supervised scheduler. Custom Node deployments must invoke the existing authenticated `/api/email/run` runner, which now also runs live checks. It is a shared operational runner despite its historical name. See [production deployment](../../../docs/production-deployment.md). Visitor traffic does not drive live-provider polling.
+- The UI reports the live scheduler heartbeat, each connection's last successful check, next due check and any provider error. Public visitors only receive a sanitized snapshot.
+
+## Twitch
+
+1. Open the [Twitch application console](https://dev.twitch.tv/console/apps) and register a **Confidential** application. Follow Twitch's account/2FA requirements.
+2. If registration requests an OAuth redirect URI, use the copyable address shown by ACMS (`https://your-site.example/admin/live`). This app-only lookup does not use a Twitch OAuth callback or broadcaster sign-in.
+3. Copy the Client ID and generate/copy the Client Secret. Enter them with the channel username or HTTPS channel URL in ACMS.
+4. Save, test, and turn the connection on. The test resolves the channel's stable ID.
+
+ACMS obtains an app token with the client-credentials flow and checks Get Streams for that broadcaster. App tokens are [validated](https://dev.twitch.tv/docs/authentication/validate-tokens/) when acquired and hourly during use. Expired or revoked app tokens are reacquired; these tokens do not use refresh tokens. ACMS requests no stream key or broadcast-management permissions. See [app registration](https://dev.twitch.tv/docs/authentication/register-app/), [token flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#client-credentials-grant-flow), and [Get Streams](https://dev.twitch.tv/docs/api/reference/#get-streams).
+
+## YouTube
+
+1. Create/select a Google Cloud project and enable **YouTube Data API v3**.
+2. Configure OAuth consent for the appropriate audience. During external-app testing, add the Google account that owns the intended channel as a test user.
+3. Create an OAuth **Web application** client. Copy the exact callback shown in ACMS into Google's authorized redirect URIs: `https://your-site.example/api/live/oauth/youtube/callback`.
+4. Save the Client ID and Client Secret in ACMS, then choose **Authorize YouTube**. Approve YouTube read-only access using the correct Google/Brand channel identity.
+5. Confirm the available channel, test, and turn the connection on. Selecting another channel requires a new test. A typed channel ID cannot override the authorized identity.
+
+The authorization-code flow uses session-bound, one-use state and PKCE. Access/refresh tokens stay encrypted on the server. ACMS lists active broadcasts, filters to the selected channel and public `live` broadcasts, and checks public video visibility/embedding permission. Private, unlisted and test broadcasts are excluded. Multiple current broadcasts use the latest actual start time with a stable ID tie-break. See [liveBroadcasts.list](https://developers.google.com/youtube/v3/live/docs/liveBroadcasts/list) and [server OAuth](https://developers.google.com/identity/protocols/oauth2/web-server).
+
+External OAuth apps left in **Testing** receive refresh tokens for YouTube scopes that expire after seven days. The UI's Testing/Production choice is owner-reported; ACMS cannot verify the app's publishing status. Follow Google's applicable publishing and verification requirements before relying on a long-running connection. A revoked or expired grant requires reauthorization. See [Google token expiration](https://developers.google.com/identity/protocols/oauth2#expiration).
+
+### Quota and timing
+
+The normal target is a check each minute and visible changes within roughly one to two minutes, subject to provider latency, scheduler operation and quota. One single-page active-broadcast list per minute is about 1,440 units/day before extra calls. Live-video visibility checks, connection tests, pagination and optional upcoming lookups add usage. Check the owner's actual project limits and other apps sharing that project.
+
+Current Google documentation assigns `liveBroadcasts.list` a cost of one unit, with a default shared 10,000-unit daily allocation for non-search/non-upload endpoints. Public `search.list` has a separate default 100-call daily allowance. ACMS therefore implements owner-authorized OAuth, not minute-by-minute public search. API-key-only discovery is not included in this release. See [Google's current quota table](https://developers.google.com/youtube/v3/determine_quota_cost).
+
+Rate-limit/quota errors back off. The UI reports estimated workload and provider errors, not an invented remaining quota. Optional YouTube upcoming lookup is cached for up to 15 minutes while active detection continues normally. A scheduled start time never becomes a live badge on its own.
+
+## Place the live card
+
+- **Design → Pages:** add a **Live video** section; choose `card` or `player`, preview and publish using the existing design flow.
+- **Links:** add a **Live video** block and save. This is a compact card referencing the same site-wide status.
+- **Older widget pages:** add a **Live video** widget and choose its display mode. Rich-text-only/custom coded homepages must opt into a Design section or explicitly render the component.
+- **Custom themes:** import `LiveCard.astro` from `@acms-subir/core/components/LiveCard.astro`, or use the built-in `live` section. ACMS never injects a new placement automatically into a custom template. If a custom route renders the component, set `Astro.response.headers.set('Cache-Control', 'no-store')` in that route's frontmatter; the built-in page routes handle this for you.
+
+### How it looks
+
+**What your site shows → How it looks** (shown unless live video is Off) controls presentation:
+
+- **Card style** for sections set to `card`: **Poster** (thumbnail with a live tag, title below; default), **Split** (thumbnail beside the title; stacks in columns narrower than 700px) or **Compact row**. Sections set to `player` always use the split layout, with the poster as the play button. The Links block is its own compact layout and moves to the top of the Links page while you're live.
+- **Thumbnail** (on by default): served from `/api/live/thumb`, which fetches the current broadcast's still from YouTube (`i.ytimg.com`) or Twitch (`static-cdn.jtvnw.net`) on the server and caches it for a minute. Visitors never contact the platform until they press play. The upstream URL is derived only from the current snapshot's validated id; the query string is a cache version.
+- **Viewer count** (off by default): Twitch reports it in the existing streams call; YouTube adds `liveStreamingDetails` to the existing `videos.list` check at the same one-unit cost. It is only sent to visitors when this is on.
+- **Site-wide signals** (all off by default), shown on every page only while a broadcast is live: a **live bar** that temporarily replaces the announcement bar, a **"Live" marker** in the header, and a **floating card** in the corner (hidden on pages that already show a live card). The bar and card can be dismissed for the rest of that broadcast in the visitor's session. They are filled in by the browser from `/api/live/status`, so pages keep their normal caching.
+
+Offline, a card shows a single "Not live right now · Watch our channel" row when an offline link is set, and hides otherwise. Upcoming broadcasts show their start time on the poster ("Sat 7:00 PM · in 2 h").
+
+### Theming
+
+The markup is a stable class API: `.pc-live` with `data-layout` (`poster`, `split`, `row`, `links`) and `data-status` (`live`, `upcoming`, `offline`); parts `.pc-live-poster`, `.pc-live-tag`, `.pc-live-viewers`, `.pc-live-kicker`, `.pc-live-title-text`, `.pc-live-meta`, `.pc-live-btn`, `.pc-live-off`; site-wide `.pc-live-bar`, `.site-live`, `.pc-live-dock`. While a broadcast is live or upcoming, `<html data-live="live|upcoming">` is set, so a theme can style anything (for example `html[data-live='live'] .brand`).
+
+Override these on `:root` in `theme.css`: `--live-color` (defaults to the theme token `live`, a tuned red), `--live-ink`, `--live-radius`, `--live-tag-radius` (keep it a rectangle), `--live-poster-ratio` and `--live-pulse`. The marker blink is disabled under `prefers-reduced-motion`.
+
+All placements share the same status. Changing credentials or live mode takes effect independently of staged layout changes. Adding/reordering a placement still follows its existing save/publish workflow. Existing sites start with live display off.
+
+Player mode loads the official platform iframe only after a visitor clicks. Autoplay is off. The external watch link stays available when playback is blocked. Twitch requires HTTPS, the embedding hostname in `parent`, and at least 400×300 pixels; narrow slots use a watch link. YouTube embeds preserve an origin referrer. The compact links card never embeds a player. Cross-domain embedding of an entire ACMS site may require additional Twitch parent domains and is not configured automatically. See [Twitch embeds](https://dev.twitch.tv/docs/embed/video-and-clips/) and [YouTube players](https://developers.google.com/youtube/iframe_api_reference).
+
+## Manual, off, fallback and outages
+
+**Manual** accepts an HTTPS watch URL and a bounded expiry of up to 12 hours (UI default: four hours). It overrides automatic detection until it expires; automatic detection then resumes. **End manual link now** resumes automatic immediately. **Off** hides every placement; turn off individual provider connections too if you want to stop their background checks.
+
+An optional neutral “Watch our channel” URL appears when no fresh live/upcoming broadcast is available. Provider priority chooses the first currently live enabled source; a live source always takes precedence over an upcoming one. No replay is automatically labelled live, and replay libraries are not part of this release.
+
+A successful live observation expires after two minutes. Failures never extend that expiry. A confirmed offline result clears the badge, revoked access clears live state and disables that connection, and expired state hides the badge. Visible browser tabs refresh the sanitized status every 30 seconds and on focus; an expiry timer removes stale badges even if requests fail. Without JavaScript, status refreshes on the next page load. Pages containing live cards and the public status endpoint are not cached.
+
+## Storage, permissions and recovery
+
+Migration 34 adds a `settings.live` display configuration, a separate `live_connections` vault, one-use `live_oauth_states`, and a live scheduler heartbeat. Credentials never enter generic Settings, theme props, public API responses, React hydration or ordinary content exports. Owner-only APIs use existing authenticated sessions plus same-origin writes. Public `/api/live/status` only returns the selected public snapshot and server time.
+
+Each background check claims a durable lease. Settings revisions and lease tokens prevent a delayed check from overwriting a newer edit/disconnection; concurrent runners cannot refresh the same connection simultaneously. Requests have timeouts, response-size limits and redacted errors. Provider requests use fixed official endpoints; pasted URLs are never fetched by the server.
+
+Saving a connection disables it until tested again. Blank secrets preserve the saved secret only for the same client ID; changing the client ID or supplying a new secret clears incompatible authorization. Disconnect removes local credentials and state immediately and attempts provider revocation. Other applications using the same owner developer project may share quota or authorization consequences.
+
+Content backups include inert display preferences but no connection secrets or tokens. Restore forces live mode off and disables any destination connections until retested; it neither imports credentials nor resumes a copied live badge. On a new host, enter app credentials, update Google's callback, authorize and test again.
+
+Facebook HTTPS watch links work in manual mode. A Facebook automatic Page connector, Twitch EventSub and the slower YouTube API-key mode remain separate follow-up releases. They are not represented as working connectors in the UI.
+
+Validation uses simulated provider HTTP responses for token renewal, filtering, expiry, quotas and OAuth attacks, plus SQLite/D1 concurrency and real local HTTP rendering tests. A real owner-owned Twitch/Google app is still needed to validate its external consent and account permissions end to end.

package/integration.mjs

@@ -54,6 +54,13 @@ const ROUTES = [
   ['/admin/posts', 'admin/posts/index.astro'],
   ['/admin/posts/[id]', 'admin/posts/[id].astro'],
   ['/admin/settings', 'admin/settings.astro'],
+  ['/admin/integrations', 'admin/integrations.astro'],
+  ['/admin/live', 'admin/live.astro'],
+  ['/api/live/settings', 'api/live/settings.ts'],
+  ['/api/live/status', 'api/live/status.ts'],
+  ['/api/live/thumb', 'api/live/thumb.ts'],
+  ['/api/live/oauth/youtube/callback', 'api/live/oauth/youtube/callback.ts'],
+  ['/api/webhooks/docs', 'api/webhooks/docs.ts'],
   ['/admin/email', 'admin/email.astro'],
   ['/account/[action]', 'account/[action].astro'],
   ['/api/email/settings', 'api/email/settings.ts'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "publishConfig": {
     "access": "public"
   },

package/src/actions/index.ts

@@ -7,7 +7,7 @@ import type { ActionAPIContext } from 'astro:actions';
 import { getRepo } from '../lib/repo';
 import { getMediaStore } from '../lib/media/store';
 import { validateSession, SESSION_COOKIE } from '../lib/auth';
-import { parseConfig, slugify, widgetTypes, type WidgetType } from '../lib/schema';
+import { LinkKind, parseConfig, slugify, widgetTypes, type WidgetType } from '../lib/schema';
 import { env } from '../lib/env';
 import { CONTENT, collectionUrl } from '../lib/content';
 import { invalidateRedirectCache } from '../middleware';
@@ -393,7 +393,8 @@ export const server = {
   links: {
     create: defineAction({
       input: z.object({
-        kind: z.enum(['link', 'email', 'phone', 'heading', 'text', 'spacer', 'vcard', 'html']).default('link'),
+        // every block kind the schema knows, incl. 'live' (kept in one place)
+        kind: z.enum(LinkKind.options).default('link'),
         label: z.string().default(''),
         url: z.string().default(''),
         icon: z.string().default(''),

package/src/components/LinksManager.tsx

@@ -61,6 +61,7 @@ const SITES = [
 ];
 
 const TILE_ICONS: Record<string, string> = {
+  live: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"><path d="M3 5h12v14H3zM15 10l6-4v12l-6-4"/></svg>',
   site: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"><path d="M12 3l4 2.3v4.4L12 12 8 9.7V5.3L12 3zM6 13l4 2.3v4.4L6 22l-4-2.3v-4.4L6 13zM18 13l4 2.3v4.4L18 22l-4-2.3v-4.4L18 13z"/></svg>',
   link: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"><path d="M10 14a5 5 0 007.07 0l2.83-2.83a5 5 0 00-7.07-7.07L11 5.93M14 10a5 5 0 00-7.07 0L4.1 12.83a5 5 0 007.07 7.07L13 18.07"/></svg>',
   email: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7"><rect x="3" y="5" width="18" height="14" rx="2"/><path d="M3 7l9 6 9-6"/></svg>',
@@ -87,6 +88,7 @@ const TILE_GROUPS: { label: string; tiles: Tile[] }[] = [
   {
     label: 'Content & layout',
     tiles: [
+      { key: 'live', kind: 'live', name: 'Live video', desc: 'Your shared live broadcast' },
       { key: 'heading', kind: 'heading', name: 'Heading', desc: 'Group your links' },
       { key: 'text', kind: 'text', name: 'Text', desc: 'Non-clickable copy' },
       { key: 'spacer', kind: 'spacer', name: 'Spacer', desc: 'Blank vertical space' },
@@ -96,6 +98,7 @@ const TILE_GROUPS: { label: string; tiles: Tile[] }[] = [
 ];
 
 const NEW_ITEM: Record<Kind, Partial<Link>> = {
+  live: { kind: 'live', label: 'Live video', url: '' },
   link: { kind: 'link', label: 'New link', url: '', icon: '' },
   email: { kind: 'email', label: 'E-mail me', url: '', icon: '✉️' },
   phone: { kind: 'phone', label: 'Call me', url: '', icon: '📞' },
@@ -448,6 +451,7 @@ export default function LinksManager({ links: initial, settings, unsplashEnabled
 // ---- rows -----------------------------------------------------------------
 
 const KIND_BADGE: Partial<Record<Kind, string>> = {
+  live: '●',
   heading: 'H', text: 'T', spacer: '↕', html: 'HTML', email: '@', phone: 'TEL', vcard: 'VCF',
 };
 
@@ -493,7 +497,7 @@ function ItemRow({
           <span className="lm-badge">{KIND_BADGE[k]}</span>
         )}
 
-        {k === 'spacer' ? (
+        {k === 'live' ? <span style={{ flex: 1 }}>Live video · <a href="/admin/live">Manage broadcast</a></span> : k === 'spacer' ? (
           <>
             <span className="bare strong" style={{ padding: '5px 8px' }}>Spacer</span>
             <select

package/src/components/LiveCard.astro

@@ -0,0 +1,174 @@
+---
+import { getRepo } from '../lib/repo';
+import { liveState, publicSnapshot } from '../lib/live/service';
+import { liveView } from '../lib/live/view';
+import '../styles/live.css';
+
+// One component for every live placement. Layout:
+//   compact (links page) → 'links'; display 'player' → 'split' with an
+//   in-page player; otherwise the owner's card style (poster/split/row).
+// Theme hooks: .pc-live-* classes, --live-* tokens, [data-layout], [data-status].
+interface Props { compact?: boolean; display?: string }
+const { compact = false, display = 'card' } = Astro.props;
+const { config, snapshot: raw } = await liveState(await getRepo(Astro.locals));
+const snapshot = publicSnapshot(raw, config);
+const now = Date.now();
+const v = liveView(snapshot, now);
+const player = !compact && display === 'player';
+const layout = compact ? 'links' : player ? 'split' : config.display.style;
+---
+<section
+  class="pc-live"
+  data-live-card
+  data-layout={layout}
+  data-player={player ? '' : undefined}
+  data-pin={compact ? '' : undefined}
+  data-status={v?.status ?? 'offline'}
+  data-snapshot={JSON.stringify(snapshot)}
+  data-server-now={now}
+  hidden={!v}
+  aria-label="Live video"
+>
+  <div class="pc-live-off">
+    <i class="pc-live-off-dot" aria-hidden="true"></i>
+    <span>Not live right now</span>
+    <a data-live-watch href={v?.watchUrl || '#'} target="_blank" rel="noopener noreferrer">{v?.watchLabel}</a>
+  </div>
+  <div class="pc-live-body">
+    <div class="pc-live-media">
+      <a class="pc-live-poster" data-live-poster href={v?.watchUrl || '#'} target="_blank" rel="noopener noreferrer" aria-label={v ? `${v.watchLabel.replace(' ↗', '')}: ${v.title}` : undefined}>
+        <span class="pc-live-ph" aria-hidden="true">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="2" /><path d="M16.2 7.8a6 6 0 0 1 0 8.4M7.8 16.2a6 6 0 0 1 0-8.4M19 5a10 10 0 0 1 0 14M5 19A10 10 0 0 1 5 5" /></svg>
+        </span>
+        <img data-live-thumb src={v?.thumbUrl || undefined} alt="" loading="lazy" decoding="async" hidden={!v?.thumbUrl} />
+        <span class="pc-live-tag" data-live-tag>{v?.tag}</span>
+        <span class="pc-live-viewers" data-live-viewers hidden={!v?.viewers}>{v?.viewers}</span>
+        <span class="pc-live-play" data-live-playicon aria-hidden="true" hidden></span>
+      </a>
+      <div class="pc-live-player" data-live-player hidden></div>
+    </div>
+    <div class="pc-live-info">
+      <span class="pc-live-kicker" data-live-kicker>{v?.kicker}</span>
+      <h2 class="pc-live-title"><span class="pc-live-title-text" data-live-title>{v?.title}</span></h2>
+      <p class="pc-live-meta" data-live-meta hidden={!v?.meta}>{v?.meta}</p>
+      <div class="pc-live-actions">
+        <button type="button" class="pc-live-btn" data-live-load hidden>Play here</button>
+        <a class="pc-live-btn" data-live-watch href={v?.watchUrl || '#'} target="_blank" rel="noopener noreferrer">{v?.watchLabel}</a>
+      </div>
+      <small class="pc-live-privacy" data-live-privacy hidden></small>
+    </div>
+  </div>
+</section>
+<script>
+  import { subscribeLive, currentLive, serverNow } from '../lib/live/client';
+  import { liveView, PROVIDER_NAMES } from '../lib/live/view';
+  import type { PublicLiveSnapshot } from '../lib/live/types';
+
+  const q = <T extends HTMLElement>(root: Element, sel: string) => root.querySelector<T>(sel)!;
+  const qa = <T extends HTMLElement>(root: Element, sel: string) => Array.from(root.querySelectorAll<T>(sel));
+
+  function setupLiveCards() {
+    const cards = Array.from(document.querySelectorAll<HTMLElement>('[data-live-card]')).filter((c) => !c.dataset.initialized);
+    for (const card of cards) {
+      card.dataset.initialized = 'true';
+      let shownKey = '';
+      // the links page lifts its live block to the top while live; a marker
+      // remembers where the owner placed it
+      const home = card.hasAttribute('data-pin') ? document.createComment('live-block') : null;
+      if (home) card.before(home);
+
+      const media = q(card, '.pc-live-media');
+      const poster = q<HTMLAnchorElement>(card, '[data-live-poster]');
+      const player = q(card, '[data-live-player]');
+      const load = q(card, '[data-live-load]');
+      const img = q<HTMLImageElement>(card, '[data-live-thumb]');
+      img.addEventListener('load', () => { img.hidden = false; });
+      img.addEventListener('error', () => { img.hidden = true; });
+
+      const eligible = (s: PublicLiveSnapshot | null) =>
+        card.hasAttribute('data-player') && !!s?.embedId && s.status === 'live' &&
+        (s.provider === 'youtube' || (s.provider === 'twitch' && media.clientWidth >= 400));
+
+      function reset() {
+        player.replaceChildren();
+        player.hidden = true;
+        poster.hidden = false;
+      }
+
+      function play() {
+        const s = currentLive();
+        if (!s || !eligible(s)) return false;
+        let src = '';
+        if (s.provider === 'youtube' && /^[\w-]{11}$/.test(s.embedId)) src = `https://www.youtube-nocookie.com/embed/${s.embedId}?autoplay=0`;
+        if (s.provider === 'twitch' && /^[a-z0-9_]{1,25}$/.test(s.embedId)) {
+          const u = new URL('https://player.twitch.tv/');
+          u.searchParams.set('channel', s.embedId);
+          u.searchParams.set('parent', location.hostname);
+          u.searchParams.set('autoplay', 'false');
+          src = u.href;
+        }
+        if (!src) return false;
+        const iframe = document.createElement('iframe');
+        iframe.src = src;
+        iframe.title = s.title || 'Live video';
+        iframe.allowFullscreen = true;
+        iframe.allow = 'fullscreen; picture-in-picture; encrypted-media';
+        iframe.referrerPolicy = 'strict-origin-when-cross-origin';
+        player.replaceChildren(iframe);
+        player.hidden = false;
+        poster.hidden = true;
+        load.hidden = true;
+        return true;
+      }
+      poster.addEventListener('click', (e) => { if (play()) e.preventDefault(); });
+      load.addEventListener('click', () => { play(); });
+
+      function pin(live: boolean) {
+        if (!home) return;
+        const slot = document.querySelector('[data-live-slot]');
+        if (live && slot) slot.after(card);
+        else if (!live && home.isConnected) home.after(card);
+      }
+
+      function render(s: PublicLiveSnapshot | null, now: number) {
+        const v = liveView(s, now);
+        card.hidden = !v;
+        const key = s ? `${s.provider}:${s.id}:${s.status}:${s.embedId}` : '';
+        if (key !== shownKey || !eligible(s)) { if (!player.hidden) reset(); }
+        shownKey = key;
+        pin(v?.status === 'live');
+        if (!v) return;
+        card.dataset.status = v.status;
+        q(card, '[data-live-tag]').textContent = v.tag;
+        q(card, '[data-live-kicker]').textContent = v.kicker;
+        q(card, '[data-live-title]').textContent = v.title;
+        const meta = q(card, '[data-live-meta]');
+        meta.textContent = v.meta;
+        meta.hidden = !v.meta;
+        const viewers = q(card, '[data-live-viewers]');
+        viewers.textContent = v.viewers;
+        viewers.hidden = !v.viewers;
+        for (const a of [poster, ...qa<HTMLAnchorElement>(card, '[data-live-watch]')]) a.href = v.watchUrl;
+        for (const a of qa(card, '[data-live-watch]')) a.textContent = v.watchLabel;
+        if (!v.thumbUrl) { img.hidden = true; img.removeAttribute('src'); }
+        else if (img.getAttribute('src') !== v.thumbUrl) img.src = v.thumbUrl;
+        const canPlay = eligible(s);
+        const name = PROVIDER_NAMES[v.provider] || 'the platform';
+        poster.setAttribute('aria-label', canPlay ? `Play ${v.title} here` : `${v.watchLabel.replace(' ↗', '')}: ${v.title}`);
+        q(card, '[data-live-playicon]').hidden = !canPlay;
+        load.hidden = !canPlay || !player.hidden;
+        const privacy = q(card, '[data-live-privacy]');
+        privacy.hidden = !canPlay;
+        privacy.textContent = `Playing loads video from ${name}.`;
+        card.dataset.playable = canPlay ? 'true' : 'false';
+      }
+
+      let initial: PublicLiveSnapshot | null = null;
+      try { initial = JSON.parse(card.dataset.snapshot || 'null'); } catch { /* no initial state */ }
+      subscribeLive(card, render, { snapshot: initial, serverNow: Number(card.dataset.serverNow) || Date.now() });
+      new ResizeObserver(() => render(currentLive(), serverNow())).observe(media);
+    }
+  }
+  setupLiveCards();
+  document.addEventListener('astro:page-load', setupLiveCards);
+</script>