Redesign Learn, and give it five real videos in Karti's voice

THE PAGE. The anonymous route rendered outside Shell, so it sat flush against
the viewport edge and read as a form rather than a product — which is the first
thing anyone at Prime Intellect sees when the link is shared. It now brings its
own chrome and leads with a hero; the platform track is a numbered course, the
concept tracks are a poster grid, and admin add/archive moved behind one Manage
toggle so they stop competing with the content. Verified in Chrome at 1440 and
393, light and dark: horizontal overflow is 0 in all three access states.

THE VIDEOS. Five ~30s walkthroughs, narrated in Karti's cloned voice through
Chatterbox and cut against real screen capture of the seeded demo book. The
audio is rendered FIRST and its measured duration drives the capture, because a
shot list that runs short leaves the narrator talking over a frozen frame and
one that runs long gets cut mid-sentence. Levels are loudness-normalised so
clips do not jump between videos.

Cap cannot take a programmatic upload — video.karti.ai needs an interactive
login — so PIG serves these itself. A native <video> on this origin needs no
iframe and therefore no CSP frame-src at all; Karti's own Cap recordings still
render through the existing iframe path, which is why the resolver is now a
discriminated union.

THREE THINGS THE VERIFIERS CAUGHT, all of which shipped green:

  - createMediaRoutes was never mounted. Every layer landed — migration, seed,
    both feeds, the bind mount, the docs — except the one that serves the bytes,
    so /media/learn/* fell through to the SPA fallback and answered HTTP 200
    text/html. The player showed a black box with working controls and no error.
    The tests certified the route factory in isolation, which proves the handler
    and says nothing about whether it is wired in. There is now an assertion
    against the ASSEMBLED app, and it fails loudly on content-type — the failure
    mode is a 200, not a 404.
  - A symlink in the media directory escaped the root. resolve() is lexical and
    stat() follows links, so the containment check this file's own header
    promised did not hold. realpath before the check closes it.
  - Vite proxied only /api, so self-hosted playback broke for anyone running the
    app the documented way — in the same invisible 200-text/html manner.

Also: a duplicate media slug used to throw from the middle of seedDemo() and
take out every later section; it now reports and skips that one entry. And the
player has an onError state, because content-addressed filenames mean a
re-render deliberately leaves the old row pointing at a file that is gone.

The three DEMO platform rows are dropped — five real recordings supersede them,
and placeholders sitting under real ones made the page read as half-finished to
the audience it is meant to convince. The supply and demand concept rows stay:
there are no real recordings for those tracks yet, and an empty track hides the
shape of the page.

Tests 275, typecheck clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

apps/api/src/app.ts

@@ -46,6 +46,7 @@ import {
   type AuthProvider,
 } from './lib/auth-provider';
 import { apiError } from './lib/mutation';
+import { createMediaRoutes } from './lib/media';
 import { CapacityService } from './services/capacity';
 import { createSignupRoute } from './routes/signup';
 import { createRegisterRoute } from './routes/register';
@@ -132,6 +133,18 @@ export function createApp(
     }),
   );
 
+  /*
+   * Learn videos PIG serves itself. Mounted here — before the authenticator,
+   * and before server.ts's SPA fallback — because a <video> re-requests byte
+   * ranges on every seek and carries no bearer token while doing it.
+   *
+   * The FILES are unauthenticated; the LISTING behind /api/learn is not. See
+   * lib/media.ts for that trade and what it costs. Position IS the access
+   * decision here: the /api/* allowlist below can never match /media/learn/*,
+   * so adding an entry there would be dead code.
+   */
+  app.route('/', createMediaRoutes());
+
   // Everything below requires a principal.
   app.use('/api/*', async (c, next) => {
     const path = new URL(c.req.url).pathname;

apps/api/src/lib/media.ts

@@ -0,0 +1,208 @@
+/**
+ * Serving the Learn videos PIG hosts itself.
+ *
+ * ## The trade, stated plainly
+ *
+ * **The files are unauthenticated. The listing is not.** `/api/learn` and
+ * `/api/learn/public` decide who learns that a video exists, what it is called
+ * and which track it belongs to; this route hands the bytes to anyone who can
+ * name the file. That is the same shape every video platform has — a gated
+ * manifest in front of segments on a public CDN — and it is the shape a
+ * `<video>` element actually wants, because a media element re-requests ranges
+ * on every seek and does not carry a bearer token while doing it.
+ *
+ * What it costs: **a URL, once shared, is a permanent public link to that
+ * video**. Someone who has been given the share code can copy the `src` out of
+ * the page and post it, and revoking the Learn access code will not close it.
+ * The only remedies are renaming the file (a new hash) or deleting it. We are
+ * taking that deliberately, because these are product demos meant to be
+ * shareable with the code — the material that must never leak is the concept
+ * tracks, and those are gated by the listing, which is where the boundary
+ * genuinely is.
+ *
+ * The mitigation is the filename. Names are **content-addressed** — a hash in
+ * the middle — so a URL is unguessable and enumerating the directory over HTTP
+ * is not possible: there is no index, and a wrong guess is a flat 404. That
+ * makes the exposure "whoever was given the link" rather than "the internet",
+ * which is exactly what an unlisted video is.
+ *
+ * ## Ranges are not optional
+ *
+ * A `<video>` that cannot be range-requested cannot be scrubbed: the browser
+ * asks for `bytes=…` when the user drags the scrubber, and a server that
+ * answers 200 with the whole file makes seeking either impossible or a
+ * re-download. So `Accept-Ranges: bytes` is advertised and a single range is
+ * honoured with a 206. This is also why the route streams from a file
+ * descriptor rather than reading the file into memory: these are hundreds of
+ * megabytes and several viewers may be seeking at once.
+ *
+ * ## Why the path cannot escape the directory
+ *
+ * The filename is validated by the same allowlist that decides whether a row
+ * may exist at all (`isLearnMediaFilename` in `@pig/core`), so the pattern
+ * that admits a video source and the pattern that admits a file read are one
+ * pattern rather than two that drift. It permits no slash and no `..`. The
+ * resolved path is then checked to be inside the root anyway, because a
+ * defence that rests on a single regular expression rests on nobody ever
+ * editing that regular expression.
+ */
+import { Hono } from 'hono';
+import { createReadStream } from 'node:fs';
+import { realpath, stat } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { Readable } from 'node:stream';
+import { isLearnMediaFilename, learnMediaContentType, LEARN_MEDIA_PATH_PREFIX } from '@pig/core';
+
+/**
+ * Where the files live.
+ *
+ * Read from the environment here rather than through `loadConfig` because the
+ * media root is an operational detail of one route, and a missing value is not
+ * a reason to refuse to boot — an install with no videos should serve 404s and
+ * work in every other respect.
+ *
+ * The default is relative to the working directory, which is the repository
+ * root in development. The container sets it explicitly to `/app/media`, which
+ * is where docker-compose bind-mounts the host directory read-only.
+ */
+export const LEARN_MEDIA_DIR_ENV = 'PIG_MEDIA_DIR';
+const DEFAULT_MEDIA_DIR = './media';
+
+export function learnMediaRoot(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env[LEARN_MEDIA_DIR_ENV]?.trim();
+  return resolve(configured && configured.length > 0 ? configured : DEFAULT_MEDIA_DIR);
+}
+
+/** The mount path, exported so `app.ts` and the resolver cannot disagree. */
+export const LEARN_MEDIA_ROUTE = `${LEARN_MEDIA_PATH_PREFIX}:filename`;
+
+interface ParsedRange {
+  start: number;
+  end: number;
+}
+
+/**
+ * Parse a single byte range against a known size, or say what to do instead.
+ *
+ * `null` means "serve the whole thing with 200" — the correct answer for no
+ * header, a syntactically odd one, or a multi-range request, all of which a
+ * server is permitted to ignore. `'unsatisfiable'` is the one case that must
+ * NOT become a 200: a range starting past the end is a client with a stale
+ * idea of the file, and answering it with the whole file would splice the
+ * beginning of the video into the middle of its buffer.
+ */
+export function parseByteRange(header: string | undefined, size: number): ParsedRange | null | 'unsatisfiable' {
+  if (!header) return null;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!match) return null;
+  const [, rawStart, rawEnd] = match;
+  if (rawStart === '' && rawEnd === '') return null;
+
+  // A suffix range — `bytes=-500`, the last 500 bytes. Browsers use it to read
+  // the MP4 moov atom when it sits at the end of the file, so a player that
+  // cannot start at all is often this branch missing.
+  if (rawStart === '') {
+    const suffix = Number(rawEnd);
+    if (!Number.isSafeInteger(suffix) || suffix <= 0) return 'unsatisfiable';
+    if (size === 0) return 'unsatisfiable';
+    return { start: Math.max(0, size - suffix), end: size - 1 };
+  }
+
+  const start = Number(rawStart);
+  if (!Number.isSafeInteger(start) || start < 0) return 'unsatisfiable';
+  if (start >= size) return 'unsatisfiable';
+  const end = rawEnd === '' ? size - 1 : Math.min(Number(rawEnd), size - 1);
+  if (!Number.isSafeInteger(end) || end < start) return 'unsatisfiable';
+  return { start, end };
+}
+
+export function createMediaRoutes(options: { root?: string } = {}) {
+  const app = new Hono();
+  const root = options.root ? resolve(options.root) : learnMediaRoot();
+
+  // GET and HEAD both, because a player probes with HEAD before it commits to
+  // downloading, and an unrouted HEAD would 404 a file that is plainly there.
+  app.on(['GET', 'HEAD'], LEARN_MEDIA_ROUTE, async (c) => {
+    const filename = c.req.param('filename');
+    if (!filename || !isLearnMediaFilename(filename)) return c.notFound();
+
+    const contentType = learnMediaContentType(filename);
+    if (!contentType) return c.notFound();
+
+    const path = join(root, filename);
+    // Belt and braces over the pattern: if this ever fails, the pattern has
+    // been loosened and the loosening is a traversal.
+    if (path !== resolve(path) || !path.startsWith(root + sep)) return c.notFound();
+
+    let size: number;
+    let modified: Date;
+    try {
+      /*
+       * realpath BEFORE the containment check, not just resolve().
+       *
+       * resolve() is lexical: it collapses `..` in the string but cannot see
+       * through a symlink, and stat() follows one. So a link planted in the
+       * media directory pointing at /etc/passwd passed the check above and was
+       * served in full, while this file's own header claimed containment. The
+       * directory is operator-populated and mounted read-only, so this was
+       * hardening rather than a live hole — but it becomes real the moment the
+       * directory is filled by an rsync or a tarball unpack.
+       */
+      const real = await realpath(path);
+      if (real !== path && !real.startsWith(root + sep)) return c.notFound();
+      const info = await stat(real);
+      if (!info.isFile()) return c.notFound();
+      size = info.size;
+      modified = info.mtime;
+    } catch {
+      // Missing, unreadable, a dangling symlink — all one answer. Telling the
+      // difference tells a prober which names exist, and unguessable names are
+      // the only thing standing between these files and enumeration.
+      return c.notFound();
+    }
+
+    const headers = new Headers({
+      'content-type': contentType,
+      'accept-ranges': 'bytes',
+      // Content-addressed: the bytes behind a name never change, so a year is
+      // safe and `immutable` stops the revalidation round trip on every seek.
+      'cache-control': 'public, max-age=31536000, immutable',
+      'last-modified': modified.toUTCString(),
+      etag: `"${size.toString(16)}-${modified.getTime().toString(16)}"`,
+      // These are downloads to a media element, never documents. Without it a
+      // browser that sniffs its way to text/html on a truncated file would
+      // treat same-origin bytes as a page.
+      'x-content-type-options': 'nosniff',
+    });
+
+    const range = parseByteRange(c.req.header('range'), size);
+    if (range === 'unsatisfiable') {
+      headers.set('content-range', `bytes */${size}`);
+      // Explicit zero rather than an absent header: without it Node falls back
+      // to chunked encoding for a body that does not exist.
+      headers.set('content-length', '0');
+      return new Response(null, { status: 416, headers });
+    }
+
+    const start = range ? range.start : 0;
+    const end = range ? range.end : Math.max(0, size - 1);
+    const length = size === 0 ? 0 : end - start + 1;
+    headers.set('content-length', String(length));
+    if (range) headers.set('content-range', `bytes ${start}-${end}/${size}`);
+
+    // A HEAD answers with the headers and no body — including the 206 status
+    // and Content-Range, so the player learns the file is seekable without
+    // fetching a byte of it.
+    if (c.req.method === 'HEAD') {
+      return new Response(null, { status: range ? 206 : 200, headers });
+    }
+
+    const stream = createReadStream(path, size === 0 ? undefined : { start, end });
+    return new Response(Readable.toWeb(stream) as ReadableStream, {
+      status: range ? 206 : 200,
+      headers,
+    });
+  });
+
+  return app;
+}

apps/api/src/routes/learn.ts

@@ -47,7 +47,7 @@ import {
   LEARN_EMBED_REJECTION_MESSAGES,
   LEARN_TRACKS,
   LEARN_VISIBILITIES,
-  learnEmbedUrl,
+  learnEmbed,
   learnVisibilityPermitted,
   learnWatchUrl,
   resolveLearnEmbed,
@@ -326,9 +326,9 @@ interface LearnRowForView {
  * available, not that it is broken.
  */
 export function learnResourceView(row: LearnRowForView) {
-  const embedUrl = learnEmbedUrl(row.provider, row.externalId);
+  const embed = learnEmbed(row.provider, row.externalId);
   const watchUrl = learnWatchUrl(row.provider, row.externalId);
-  if (!embedUrl || !watchUrl) return null;
+  if (!embed || !watchUrl) return null;
   return {
     id: row.id,
     track: row.track,
@@ -339,7 +339,14 @@ export function learnResourceView(row: LearnRowForView) {
     durationSeconds: row.durationSeconds,
     sortOrder: row.sortOrder,
     publishedAt: row.publishedAt,
-    embedUrl,
+    /**
+     * The discriminated union — `kind: 'iframe' | 'video'` — is what the
+     * client branches on. Sent alongside the flat `embedUrl` rather than
+     * instead of it so a client mid-deploy keeps rendering; the flat field is
+     * the same string and will go once nothing reads it.
+     */
+    embed,
+    embedUrl: embed.src,
     watchUrl,
   };
 }