Videos Module

The /videos page is the public-facing Matters AI video gallery. It pulls every video from the WordPress video CPT, renders a hero + featured slot + filterable grid + deep-link modal player, and emits VideoObject + ItemList JSON-LD for SEO.

This module follows the CPT-backed module pattern — read that page first for the shared blueprint. This page documents the video-specific details.

The category vocabulary — one array, six consumers#

PRODUCT_VIDEO_CATEGORIES in lib/data/product-videos.ts is the single source of truth for video categories. Array order is display order.

export const PRODUCT_VIDEO_CATEGORIES = [
  { value: "dispatch", label: "Dispatch" },
  { value: "endpoint", label: "Endpoint" },
  { value: "platform", label: "Platform" },
  { value: "integrations-use-cases", label: "Integrations & Use Cases" },
  { value: "events", label: "Events" },
  { value: "company", label: "Company" },
] as const satisfies readonly { readonly value: string; readonly label: string }[];

export type ProductVideoCategory = (typeof PRODUCT_VIDEO_CATEGORIES)[number]["value"];

Everything downstream derives from it: the union type, PRODUCT_VIDEO_CATEGORY_LABELS, isProductVideoCategory(), normalizeProductVideoCategory(), the workspace editor's <Select>, the gallery's filter pills, and the Zod enum that guards the write API. Adding a category is a one-line edit to this array — no other file changes.

Retired categories#

integrations and use-cases were merged into integrations-use-cases while each held too few videos to earn its own filter chip. Historical CPT rows still carry the old values, so normalizeProductVideoCategory() maps them onto the merged bucket on read rather than dumping them to the default. To split them apart again: add both entries back to the array and delete the matching entries from LEGACY_CATEGORY_ALIASES.

The ProductVideo shape#

Every video the gallery renders conforms to this shape — both the static fallback registry and the live CPT data are mapped to it before consumption:

// lib/data/product-videos.ts
export interface ProductVideo {
  slug: string;                  // Deep-link key: /videos?v=<slug>
  title: string;
  description: string;           // Card description (1–2 sentences)
  longDescription?: string;      // Featured-slot description
  playbackId: string;            // Mux playback ID — required
  assetId: string;               // Mux asset ID — used for analytics
  youtubeId?: string;            // Optional — shows "Watch on YouTube" link in modal
  duration?: string;             // e.g. "2:14"
  thumbnailUrl?: string;         // Optional poster override — replaces the Mux frame
  category: ProductVideoCategory;
  tags: string[];
  featured?: boolean;            // Hero slot (only one wins)
  relatedLinks?: { title; href; kind?: "Blog" | "Datasheet" | "Webinar" | "Docs" | "Page" }[];
}

The CPT's content.raw stores this JSON minus slug and title (those map to WP's native post.slug and post.title).

The workspace list#

Each row shows a 64×36 poster between the drag handle and the title. The URL is resolved server-side in the list route via productVideoPosterUrl(), so the precedence rule — custom thumbnailUrl wins, else the Mux frame at 0:05, else a placeholder icon — lives in one place and matches what the gallery renders.

This is why listCptItems takes { includeContent: true }: the poster lives in the content blob, which is the largest field on a row, so it is opt-in and the other four CPT lists do not pay for it.

Validation — two schemas, opposite failure modes#

The generic cptUpsertSchema types content as unknown, because every CPT stores a different payload. Videos pin theirs in lib/data/product-video-content.ts, which exports two schemas on purpose:

The asymmetry is deliberate. A bad write should fail loudly at the boundary; a bad row already in the database must never take down the whole gallery.

Data flow#

Workspace edit form  ──┐
                       │  PUT /api/workspace/videos/<id>
                       │  ├─ videoUpdateSchema
                       │  └─ productVideoContentWriteSchema  (strict — 422 on bad input)
                       ▼
              WP video CPT (private)
                       │
                       │  GET /wp-json/wp/v2/video?status=publish
                       │  └─ productVideoContentReadSchema   (lenient — skips bad rows)
                       ▼
       lib/data/videos-server.ts → getProductVideos()
                       │
       (if CPT empty / errors → falls back to PRODUCT_VIDEOS static array)
                       ▼
        app/videos/page.tsx (server)
                       │  passes videos + featured as props
                       ▼
     app/videos/client-page.tsx (client)
                       │
   ┌───────────────────┼───────────────────┐
   ▼                   ▼                   ▼
 FeaturedVideo     CategoryFilter       VideoCard grid
                                        + ?v=<slug> deep-link
                                        → VideoModal

Key files#

WordPress side#

The video CPT is registered in WP admin via the Simple CPT plugin. Settings:

Workspace admin#

Public website#

Bulk editing#

Select rows in the workspace list and a toolbar appears above the table.

Everything routes through POST /api/workspace/videos/bulk, whose body is a Zod discriminated union on action (schema.ts). Trashing is gated on org:content:delete or org:content:edit, matching the single-item route; everything else needs org:content:edit.

What is generic and what is not#

Status and delete are WordPress-native, so they live in cpt.service and any CPT module gets them by calling the primitive. Category and tags are video content fields — industries and use cases store entirely different shapes — so those are defined in the videos route. The shared seam is bulkPatchCptContent(cfg, ids, patch): the service does the read-modify-write and knows nothing about any module's schema, while the module supplies a closure that does.

The selection UI is shared the same way — useRowSelection and BulkActionBar are module-agnostic; only the buttons inside the bar are video-specific.

Two limits worth knowing: CPT_BULK_MAX_ITEMS caps one request at 50 (each item costs one or two sequential WordPress round-trips inside a serverless time budget), and drag-to-reorder is disabled while any row is selected, since the two gestures fight over the same pointer.

Bulk import#

scripts/seed-videos.ts loads a JSON array of ProductVideo objects straight into the CPT.

npx tsx scripts/seed-videos.ts --dry-run              # validate + report, write nothing
npx tsx scripts/seed-videos.ts                        # import the static fallback catalog
npx tsx scripts/seed-videos.ts path/to/videos.json    # import your own JSON
npx tsx scripts/seed-videos.ts videos.json --status=draft

• Input is a bare array, or the { "videos": [...] } envelope that /api/videos/list emits — so you can pipe the live list back in after editing it. With no path, it imports PRODUCT_VIDEOS.
• Idempotent. Records are matched by slug and updated in place, never duplicated.
• Order comes from array position, written as the [ORDER:nnn] excerpt marker. Re-import a reordered file to re-order the gallery.
• Validated up front. Every row must pass productVideoContentWriteSchema — the same contract the API enforces — and the script validates the whole file before writing anything, so you never get a half-imported gallery.
• Status defaults to publish, because the reader only picks up publish in production. Use --status=draft to stage.

It talks to the WordPress REST API directly rather than calling createCptItem, because that service calls revalidateTag(), which throws outside a Next.js request context. The consequence: "videos" is not in the /api/revalidate allowlist, so the public gallery picks up a script import on its 1-hour ISR window — or immediately if you open and save any video in the workspace afterwards.

Static fallback strategy#

getProductVideos() returns a source of "wordpress" | "fallback":

Every failure path resolves to "fallback", so /videos never shows an empty gallery during migration or downtime. Once you publish CPT entries, those override the static fallback automatically.

The navbar carousel progressively enhances the same way: it renders PRODUCT_VIDEOS on first paint, then swaps in the live list once /api/videos/list resolves (Navbar.tsx). It is a client component, so it cannot await the CPT before painting — the static seed is what prevents an empty carousel on load.

Deep-link modal pattern#

The gallery is a single page (/videos); individual videos open in a modal via a query param:

/videos              → gallery only
/videos?v=funding-journey  → opens that video's modal on load

Implemented in client-page.tsx:

useEffect(() => {
  const slug = searchParams.get(QUERY_KEY);
  if (!slug) {
    setActiveVideo(null);
    return;
  }
  const match = videos.find((v) => v.slug === slug);
  if (match) setActiveVideo(match);
}, [searchParams, videos]);

Sharing a ?v=... URL gets the recipient straight into the right modal — used by the navbar "Resources" carousel and as the workspace's "View Live" action.

SEO#

The server page injects:

1. ItemList — the full gallery, lets Google show "video carousel" rich results.
2. VideoObject per video — name, description, Mux thumbnail, m3u8 content URL, embed URL pointing to /videos?v=<slug>.

If you change the uploadDate field (currently hardcoded "2025-01-01"), make it dynamic from the WP post's modified field.

The Google sitemap entry lives at app/(sitemaps)/sitemap-videos.xml/route.ts — note that one scans blog posts for embedded YouTube/Mux/Vimeo videos, not the video CPT. The CPT sitemap entry doesn't exist yet — add it if you want individual gallery deep-links indexed.

Navbar consumption#

The Resources carousel in components/nav/Navbar.tsx already fetches live data. It seeds navVideos from the static PRODUCT_VIDEOS array (via SOCIAL_VIDEOS_MATTERS) so the carousel paints immediately, then a useEffect (~line 247) fetches /api/videos/list with { cache: "no-store" } and swaps in the live CPT data once it resolves. Any failure (non-ok response, empty list, or thrown error) silently keeps the static seed, so the carousel always works. React Query is not used — it's a plain fetch inside a useEffect with a cancelled guard.

Adding a new video#

1. Open workspace.matters.ai/videos → New Video.
2. Fill the form (Mux playback ID is required).
3. Set status to Published and save.
4. The public site picks it up within ~1 hour — the getProductVideos() fetch is tagged ["videos"] with revalidate: 60 * 60. (Note: the workspace videos API routes do not currently call revalidateTag("videos"), so a published change surfaces when the 1-hour TTL elapses rather than instantly.)

Gotchas#

• playbackId is required. Server-side mapper drops any CPT entry without one (see videos-server.ts:97-98).
• Only one featured should be true. The picker uses the first match; backstop warning in the workspace UI is a TODO.
• The static fallback is intentional. Don't remove product-videos.ts until every video is migrated to the CPT and verified. It's our safety net.

Related#

• CPT-Backed Module Pattern — the shared blueprint
• Snippet Generators — the videoplayer snippet block is how Mux videos get embedded inside blog posts (different surface from this gallery)
• SEO & Analytics — VideoObject JSON-LD spec