@xexr/blog-platform 1.1.5 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.2.0
+
+### Minor Changes
+
+- e336ad5: Add optional article videos. `PublishedArticle.video` carries a YouTube video that replaces the featured image at the top of the article as a click-to-play preview (the featured image is the poster, and the privacy-enhanced `youtube-nocookie.com` player loads only after the reader presses play). The BlogPosting structured data gains a `VideoObject`, the publish endpoint validates the video, and the video is stored in `meta_json`, so no host migration is needed. Hosts that cache article data should bump their cache key, since the stored article shape changed.
+
+## 1.1.7
+
+### Patch Changes
+
+- Correct article subjects and author expertise, add topic and series archive structured data, and omit paginated URLs from sitemaps.
+- 5e14632: Raise the `next` peer dependency range to `^15.5.28 || ^16.4.1`, excluding Next.js releases affected by the October 2026 Next.js security advisories (GHSA-2464-fhr4-w9xw, GHSA-p3m5-59mp-jv5r, GHSA-673q-mjm6-r5xr).
+
 ## 1.1.1
 
 ### Patch Changes

package/README.md

@@ -775,6 +775,27 @@ The blog platform displays author information based on Bloggy's author settings:
    "Oct 4, 2025 • 4 min read • From Indie Web Growth"
 ```
 
+### Article Videos
+
+An article can carry an optional YouTube video (`article.video`, available from 1.2.0):
+
+```json
+"video": {
+  "provider": "youtube",
+  "id": "4kXvcIqw0RQ",
+  "title": "The Eisenhower matrix",
+  "uploadDate": "2026-10-01",
+  "duration": "PT4M13S"
+}
+```
+
+- The video takes the featured image's place at the top of the article, using the featured image as its poster.
+- It is click-to-play: nothing is requested from YouTube until the reader presses play, then the `youtube-nocookie.com` player loads with autoplay. Without JavaScript the poster links to the YouTube watch page.
+- The BlogPosting JSON-LD gains a `VideoObject` (`description` falls back to the article excerpt).
+- `verticalId` is reserved for a future vertical cut and is not rendered yet.
+- The publish endpoint rejects a malformed video (`PUB001`). Older packages silently ignore the field, so Bloggy checks `/api/blog/version` first and refuses to send a video to a platform older than 1.2.0.
+- Mention YouTube embeds in your privacy policy: pressing play sends the reader's IP address and device details to Google.
+
 ### SEO Best Practices
 
 When publishing articles, the blog platform automatically handles:

package/dist/app/api/blog/publish/route.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+
+import { validatePublishPayload } from "./route";
+
+function payload(articleOverrides: Record<string, unknown> = {}) {
+  return {
+    idempotencyKey: "key-1",
+    article: {
+      id: "article-1",
+      slug: "eisenhower-matrix",
+      title: "The Eisenhower matrix",
+      content: "Body",
+      publishedAt: "2026-11-06T10:00:00.000Z",
+      site: { id: "site-1", name: "dypt", domain: "dypt.app" },
+      meta: { keywords: [] },
+      ...articleOverrides,
+    },
+  };
+}
+
+describe("validatePublishPayload video", () => {
+  it("accepts articles without a video", () => {
+    expect(validatePublishPayload(payload())).toEqual([]);
+  });
+
+  it("accepts a valid YouTube video", () => {
+    expect(
+      validatePublishPayload(
+        payload({
+          video: {
+            provider: "youtube",
+            id: "4kXvcIqw0RQ",
+            title: "The Eisenhower matrix",
+            uploadDate: "2026-10-01",
+          },
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  it("rejects a malformed video instead of storing it", () => {
+    expect(
+      validatePublishPayload(
+        payload({
+          video: {
+            provider: "youtube",
+            id: "javascript:alert(1)",
+            title: "Bad",
+            uploadDate: "2026-10-01",
+          },
+        }),
+      ),
+    ).toEqual(["Article video id must be an 11-character YouTube id"]);
+  });
+});

package/dist/app/api/blog/publish/route.ts

@@ -8,6 +8,7 @@ import {
 } from "@/lib/auth";
 import { enforceRateLimit, getRateLimitHeaders } from "@/lib/ratelimit";
 import { createCorsResponse, handleCorsOptions } from "@/lib/cors";
+import { validatePublishedArticleVideo } from "@/lib/video";
 import type {
   PublishPayload,
   PublishResult,
@@ -119,7 +120,7 @@ export async function POST(
           success: false,
           error: {
             code: "PUB001",
-            message: "Missing required fields",
+            message: "Invalid or missing fields",
             details: { errors: validationErrors },
           },
           idempotencyKey: payload.idempotencyKey ?? "",
@@ -286,7 +287,7 @@ export async function OPTIONS(request: NextRequest): Promise<NextResponse> {
 /**
  * Validate the publish payload structure
  */
-function validatePublishPayload(payload: unknown): string[] {
+export function validatePublishPayload(payload: unknown): string[] {
   const errors: string[] = [];
 
   if (!payload || typeof payload !== "object") {
@@ -341,6 +342,10 @@ function validatePublishPayload(payload: unknown): string[] {
         errors.push("Article meta.keywords must be an array");
       }
     }
+
+    if (article.video !== undefined && article.video !== null) {
+      errors.push(...validatePublishedArticleVideo(article.video));
+    }
   }
 
   return errors;

package/dist/app/blog/[slug]/page.tsx

@@ -16,6 +16,8 @@ import { Card, CardContent } from "../../../components/ui/card";
 import ArticleTopActions from "../../../components/ArticleTopActions";
 import { ExpandableArticleImage } from "../../../components/ExpandableArticleImage";
 import { ArticleReadingProgress } from "../../../components/ArticleReadingProgress";
+import { ArticleVideo } from "../../../components/ArticleVideo";
+import { isYouTubeVideoId } from "../../../lib/video";
 import { Separator } from "../../../components/ui/separator";
 import {
   generateCompleteArticleStructuredData,
@@ -166,6 +168,19 @@ export default function ArticlePage({
     article.featuredImageCreditText ??
     article.featuredImageCreditUrl,
   );
+  const featuredImageCaption = hasFeaturedImageMeta ? (
+    <figcaption className="text-muted-foreground mt-3 space-y-1 px-2 text-center text-sm leading-relaxed sm:px-0">
+      {article.featuredImageCaption && <p>{article.featuredImageCaption}</p>}
+      {(article.featuredImageCreditText ?? article.featuredImageCreditUrl) && (
+        <p className="text-xs">
+          <FeaturedImageCredit
+            creditText={article.featuredImageCreditText}
+            creditUrl={article.featuredImageCreditUrl}
+          />
+        </p>
+      )}
+    </figcaption>
+  ) : null;
   const resolvedRelatedArticles =
     relatedArticles.length > 0
       ? relatedArticles.slice(0, 3)
@@ -340,37 +355,35 @@ export default function ArticlePage({
         </div>
       </header>
 
-      {/* Featured Image */}
-      {imageUrl && (
-        <figure className="article-featured-image mx-auto my-8 w-full max-w-4xl sm:my-12 lg:my-16">
-          <Image
-            src={imageUrl}
-            alt={
-              article.featuredImageAlt ?? `Featured image for ${article.title}`
+      {/* Video (replaces the featured image, which becomes its poster) */}
+      {article.video && isYouTubeVideoId(article.video.id) ? (
+        <figure className="article-featured-video mx-auto my-8 w-full max-w-4xl sm:my-12 lg:my-16">
+          <ArticleVideo
+            video={article.video}
+            posterSrc={imageUrl}
+            posterAlt={
+              article.featuredImageAlt ?? `Video poster for ${article.title}`
             }
-            className="h-auto w-full rounded-3xl border border-[var(--blog-accent-border)] shadow-[0_24px_80px_rgb(168_85_247_/_0.14)]"
-            width={1200}
-            height={800}
-            priority
           />
-
-          {hasFeaturedImageMeta && (
-            <figcaption className="text-muted-foreground mt-3 space-y-1 px-2 text-center text-sm leading-relaxed sm:px-0">
-              {article.featuredImageCaption && (
-                <p>{article.featuredImageCaption}</p>
-              )}
-              {(article.featuredImageCreditText ??
-                article.featuredImageCreditUrl) && (
-                <p className="text-xs">
-                  <FeaturedImageCredit
-                    creditText={article.featuredImageCreditText}
-                    creditUrl={article.featuredImageCreditUrl}
-                  />
-                </p>
-              )}
-            </figcaption>
-          )}
+          {imageUrl && featuredImageCaption}
         </figure>
+      ) : (
+        imageUrl && (
+          <figure className="article-featured-image mx-auto my-8 w-full max-w-4xl sm:my-12 lg:my-16">
+            <Image
+              src={imageUrl}
+              alt={
+                article.featuredImageAlt ??
+                `Featured image for ${article.title}`
+              }
+              className="h-auto w-full rounded-3xl border border-[var(--blog-accent-border)] shadow-[0_24px_80px_rgb(168_85_247_/_0.14)]"
+              width={1200}
+              height={800}
+              priority
+            />
+            {featuredImageCaption}
+          </figure>
+        )
       )}
 
       {/* Article Content */}

package/dist/components/ArchiveStructuredData.tsx

@@ -0,0 +1,61 @@
+import React from "react";
+import type { PublishedArticle } from "../types/contracts";
+import {
+  generateBreadcrumbStructuredData,
+  structuredDataToJsonLd,
+} from "../lib/structured-data";
+import { buildBlogPath } from "../lib/urls";
+
+export function ArchiveStructuredData({
+  articles,
+  title,
+  kind,
+  slug,
+  basePath,
+}: {
+  articles: PublishedArticle[];
+  title: string;
+  kind: "topics" | "series";
+  slug: string;
+  basePath: string;
+}) {
+  const site = articles[0]?.site;
+  if (!site) return null;
+  const domain = site.domain;
+  const archivePath = buildBlogPath(basePath, `${kind}/${slug}`);
+  const collection = {
+    "@context": "https://schema.org" as const,
+    "@type": "CollectionPage",
+    name: title,
+    url: `https://${domain}${archivePath}`,
+    mainEntity: {
+      "@type": "ItemList",
+      itemListElement: articles.map((article, index) => ({
+        "@type": "ListItem",
+        position: index + 1,
+        name: article.title,
+        url: `https://${domain}${buildBlogPath(basePath, article.slug)}`,
+      })),
+    },
+  };
+  const breadcrumbs = generateBreadcrumbStructuredData(
+    [
+      { name: "Home", url: "/" },
+      { name: site.name, url: basePath },
+      {
+        name: kind === "topics" ? "Topics" : "Series",
+        url: buildBlogPath(basePath, kind),
+      },
+      { name: title, url: archivePath },
+    ],
+    { customDomain: domain },
+  );
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{
+        __html: structuredDataToJsonLd([collection, breadcrumbs]),
+      }}
+    />
+  );
+}

package/dist/components/ArticleVideo.tsx

@@ -0,0 +1,136 @@
+"use client";
+
+import React from "react";
+import Image, { type ImageLoader } from "next/image.js";
+import { Play } from "lucide-react";
+
+import { cn } from "../lib/utils";
+import {
+  buildYouTubeEmbedUrl,
+  buildYouTubeWatchUrl,
+  isYouTubeVideoId,
+} from "../lib/video";
+import type { PublishedArticleVideo } from "../types/contracts";
+
+interface ArticleVideoProps {
+  video: PublishedArticleVideo;
+  /** Poster image, normally the article's featured image. */
+  posterSrc?: string;
+  posterAlt?: string;
+  /**
+   * Image loader for the poster. Needed by hosts whose Next config sets
+   * `images.loader: "custom"` without a loader file.
+   */
+  posterLoader?: ImageLoader;
+  className?: string;
+}
+
+interface ArticleVideoViewProps extends ArticleVideoProps {
+  playing: boolean;
+  onPlay: () => void;
+}
+
+const PLAYER_ALLOW =
+  "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share";
+
+/**
+ * Stateless markup for the article video. Before `playing`, it is a link to
+ * the YouTube watch page showing the article's own poster, so nothing is
+ * requested from YouTube. Once playing, it renders the privacy-enhanced player.
+ */
+export function ArticleVideoView({
+  video,
+  posterSrc,
+  posterAlt,
+  posterLoader,
+  className,
+  playing,
+  onPlay,
+}: ArticleVideoViewProps) {
+  if (!isYouTubeVideoId(video.id)) {
+    return null;
+  }
+
+  const frameClassName =
+    "relative aspect-video w-full overflow-hidden rounded-3xl border border-[var(--blog-accent-border)] bg-black shadow-[0_24px_80px_rgb(168_85_247_/_0.14)]";
+
+  return (
+    <div className={cn("article-video", className)}>
+      {playing ? (
+        <div className={frameClassName}>
+          <iframe
+            src={buildYouTubeEmbedUrl(video.id)}
+            title={video.title}
+            allow={PLAYER_ALLOW}
+            allowFullScreen
+            referrerPolicy="strict-origin-when-cross-origin"
+            className="absolute inset-0 h-full w-full border-0"
+          />
+        </div>
+      ) : (
+        <a
+          href={buildYouTubeWatchUrl(video.id)}
+          aria-label={`Play video: ${video.title}`}
+          onClick={(event) => {
+            if (
+              event.button !== 0 ||
+              event.metaKey ||
+              event.ctrlKey ||
+              event.shiftKey ||
+              event.altKey
+            ) {
+              return;
+            }
+            event.preventDefault();
+            onPlay();
+          }}
+          className={cn(
+            frameClassName,
+            "group block focus-visible:ring-2 focus-visible:ring-[var(--blog-text-accent)] focus-visible:ring-offset-2 focus-visible:outline-none",
+          )}
+        >
+          {posterSrc ? (
+            <Image
+              src={posterSrc}
+              alt={posterAlt ?? ""}
+              {...(posterLoader && { loader: posterLoader })}
+              fill
+              sizes="(min-width: 896px) 896px, 100vw"
+              className="object-cover transition-opacity group-hover:opacity-90"
+              priority
+            />
+          ) : (
+            <span
+              aria-hidden="true"
+              className="absolute inset-0 bg-gradient-to-br from-[var(--blog-accent-bg)] to-black"
+            />
+          )}
+          <span
+            aria-hidden="true"
+            className="absolute inset-0 flex items-center justify-center bg-black/10 transition-colors group-hover:bg-black/25"
+          >
+            <span className="flex h-16 w-16 items-center justify-center rounded-full bg-white/95 text-black shadow-xl transition-transform group-hover:scale-105 sm:h-20 sm:w-20">
+              <Play className="ml-1 h-7 w-7 fill-current sm:h-9 sm:w-9" />
+            </span>
+          </span>
+        </a>
+      )}
+      <p className="text-muted-foreground mt-2 text-center text-xs">
+        Plays from YouTube
+      </p>
+    </div>
+  );
+}
+
+/** Click-to-play YouTube video for the top of an article. */
+export function ArticleVideo(props: ArticleVideoProps) {
+  const [playing, setPlaying] = React.useState(false);
+
+  return (
+    <ArticleVideoView
+      {...props}
+      playing={playing}
+      onPlay={() => setPlaying(true)}
+    />
+  );
+}

package/dist/components/SeriesArchivePages.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { ArchiveStructuredData } from "./ArchiveStructuredData";
 import Image from "next/image.js";
 import Link from "next/link.js";
 import { formatDistanceToNow } from "date-fns";
@@ -122,6 +123,15 @@ export function BlogSeriesArchivePage({
         className,
       )}
     >
+      {archive && (
+        <ArchiveStructuredData
+          articles={archive.articles}
+          title={archive.series.title}
+          kind="series"
+          slug={seriesSlug}
+          basePath={normalizedBasePath}
+        />
+      )}
       <header className="mb-10 space-y-3 text-center">
         <Link
           href={buildBlogPath(normalizedBasePath, "series")}

package/dist/components/TopicArchivePages.test.ts

@@ -2,10 +2,8 @@ import React from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it } from "vitest";
 
-import {
-  BlogTopicArchivePage,
-  BlogTopicsIndexPage,
-} from "./TopicArchivePages";
+import { BlogTopicArchivePage, BlogTopicsIndexPage } from "./TopicArchivePages";
+import { BlogSeriesArchivePage } from "./SeriesArchivePages";
 import type { PublishedArticle, PublishedSite } from "../types/contracts";
 
 const site: PublishedSite = {
@@ -99,3 +97,53 @@ describe("Blog topic archive pages", () => {
     expect(html).not.toContain("h-full w-full object-contain");
   });
 });
+
+function schemas(html: string): unknown[] {
+  return [
+    ...html.matchAll(/<script type="application\/ld\+json">(.*?)<\/script>/g),
+  ].flatMap((match): unknown[] => JSON.parse(match[1]!) as unknown[]);
+}
+
+it("renders topic archive collection and breadcrumbs for the listed articles", () => {
+  const data = schemas(
+    renderToStaticMarkup(
+      React.createElement(BlogTopicArchivePage, {
+        articles: [article],
+        topicSlug: "recurring-work-and-routines",
+        basePath: "/new-blog",
+      }),
+    ),
+  );
+  expect(JSON.stringify(data)).toContain(
+    "https://example.com/new-blog/useful-routines",
+  );
+  expect(JSON.stringify(data)).toContain("CollectionPage");
+  expect(JSON.stringify(data)).toContain("BreadcrumbList");
+});
+
+it("renders series archive collection and breadcrumbs for the listed articles", () => {
+  const seriesArticle = {
+    ...article,
+    series: {
+      id: "s",
+      title: "Routines",
+      slug: "routines",
+      position: 1,
+      total: 1,
+      articles: [],
+    },
+  };
+  const data = schemas(
+    renderToStaticMarkup(
+      React.createElement(BlogSeriesArchivePage, {
+        articles: [seriesArticle],
+        seriesSlug: "routines",
+      }),
+    ),
+  );
+  expect(JSON.stringify(data)).toContain(
+    "https://example.com/blog/useful-routines",
+  );
+  expect(JSON.stringify(data)).toContain("CollectionPage");
+  expect(JSON.stringify(data)).toContain("BreadcrumbList");
+});

package/dist/components/TopicArchivePages.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { ArchiveStructuredData } from "./ArchiveStructuredData";
 import Link from "next/link.js";
 import Image from "next/image.js";
 import { formatDistanceToNow } from "date-fns";
@@ -52,7 +53,7 @@ export function BlogTopicsIndexPage({
       <header className="mb-10 space-y-3 text-center">
         <Link
           href={normalizedBasePath}
-          className="text-muted-foreground hover:text-[var(--blog-accent)] text-sm font-medium transition-colors"
+          className="text-muted-foreground text-sm font-medium transition-colors hover:text-[var(--blog-accent)]"
         >
           Back to all articles
         </Link>
@@ -88,7 +89,7 @@ export function BlogTopicsIndexPage({
                 href={buildBlogPath(normalizedBasePath, `topics/${topic.slug}`)}
                 className="group rounded-2xl border border-[var(--blog-accent-border)] bg-[var(--blog-card-bg)] p-5 transition hover:border-[var(--blog-accent)] hover:no-underline"
               >
-                <h2 className="group-hover:text-[var(--blog-accent)] text-xl font-semibold transition-colors">
+                <h2 className="text-xl font-semibold transition-colors group-hover:text-[var(--blog-accent)]">
                   {topic.name}
                 </h2>
                 {topic.description && (
@@ -126,10 +127,19 @@ export function BlogTopicArchivePage({
         className,
       )}
     >
+      {archive && (
+        <ArchiveStructuredData
+          articles={archive.articles}
+          title={archive.topic.name}
+          kind="topics"
+          slug={topicSlug}
+          basePath={normalizedBasePath}
+        />
+      )}
       <header className="mb-10 space-y-3 text-center">
         <Link
           href={buildBlogPath(normalizedBasePath, "topics")}
-          className="text-muted-foreground hover:text-[var(--blog-accent)] text-sm font-medium transition-colors"
+          className="text-muted-foreground text-sm font-medium transition-colors hover:text-[var(--blog-accent)]"
         >
           Back to all topics
         </Link>
@@ -202,7 +212,7 @@ function TopicArticleCard({
         <span className="inline-flex rounded-full border border-[var(--blog-accent-border)] px-2.5 py-1 text-xs font-medium text-[var(--blog-text-accent)]">
           {topic.name}
         </span>
-        <h2 className="group-hover:text-[var(--blog-accent)] text-xl font-semibold text-balance transition-colors">
+        <h2 className="text-xl font-semibold text-balance transition-colors group-hover:text-[var(--blog-accent)]">
           {article.title}
         </h2>
         {article.excerpt && (

package/dist/{index-CKWrb9a4.d.mts → index-CmjKzrH-.d.mts}

@@ -44,6 +44,8 @@ interface PublishedAuthor {
     readonly pronouns?: string;
     /** Whether this is a guest author */
     readonly isGuest: boolean;
+    /** Areas of subject expertise. */
+    readonly expertise?: readonly string[];
     /** Tone adjectives that describe this author's writing style */
     readonly toneAdjectives: readonly string[];
 }
@@ -162,6 +164,31 @@ interface PublishedSeriesContext {
     /** Ordered article list for compact navigation and archive pages */
     readonly articles: readonly PublishedSeriesArticleLink[];
 }
+/**
+ * Optional video shown at the top of an article.
+ *
+ * Only YouTube is supported. The page renders a click-to-play preview and
+ * loads the privacy-enhanced player only after the reader presses play.
+ */
+interface PublishedArticleVideo {
+    /** Video host. Only "youtube" is supported. */
+    readonly provider: "youtube";
+    /** 11-character YouTube video id of the landscape video */
+    readonly id: string;
+    /** Video title, as on YouTube (used for the player label and VideoObject) */
+    readonly title: string;
+    /** Optional video description (VideoObject falls back to the article excerpt) */
+    readonly description?: string;
+    /** Upload date as an ISO 8601 date or date-time */
+    readonly uploadDate: string;
+    /** Optional ISO 8601 duration, e.g. "PT4M13S" */
+    readonly duration?: string;
+    /**
+     * Reserved: YouTube id of a vertical (Shorts) cut of the same video.
+     * Validated and stored, but not rendered yet.
+     */
+    readonly verticalId?: string;
+}
 /**
  * Represents a published article with all necessary metadata for rendering
  * on external blog platforms.
@@ -195,6 +222,8 @@ interface PublishedArticle {
     readonly topics?: readonly PublishedTopic[];
     /** Optional ordered series context for article navigation */
     readonly series?: PublishedSeriesContext;
+    /** Optional video shown in place of the featured image at the top */
+    readonly video?: PublishedArticleVideo;
     /** Featured image URL (optional) */
     readonly featuredImage?: string;
     /** Alt text for featured image */
@@ -268,4 +297,4 @@ interface PublishResult {
     readonly idempotencyKey: string;
 }
 
-export type { PublishedTopic as P, PublishedArticle as a, PublishedSite as b, PublishedAuthor as c, PublishedNewsletterSettings as d, PublishedArticleCta as e, PublishResult as f, PublishedSeriesContext as g, PublishPayload as h, PublishedAuthorSocialLinks as i };
+export type { PublishedTopic as P, PublishedArticle as a, PublishedSite as b, PublishedAuthor as c, PublishedNewsletterSettings as d, PublishedArticleCta as e, PublishResult as f, PublishedSeriesContext as g, PublishPayload as h, PublishedArticleVideo as i, PublishedAuthorSocialLinks as j };