@sarimarcus/content-sites-core 0.61.0 → 0.62.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,14 @@
2
2
 
3
3
  All packages in the platform release in lockstep; entries are per release version.
4
4
 
5
+ ## 0.62.0 (2026-11-08)
6
+
7
+ Additive (SLA-3977); an article without `embeds` renders exactly as before.
8
+
9
+ - `ArticleSection`: new optional `embeds[]` (`provider: 'youtube'`, 11-character `id`, `title`, optional `caption`, `afterParagraph`), at most `ARTICLE_EMBED_MAX_PER_SECTION` (2) per section. New exports `ARTICLE_EMBED_PROVIDERS`, `ArticleEmbedProvider`, `YOUTUBE_ID_PATTERN`, `ARTICLE_EMBED_MAX_PER_SECTION`.
10
+ - Adoption: a site that defines its own article `sections` schema must add `embeds` or Zod drops it silently; `validate-embeds` fails an article with embeds on a site whose `content.config.ts` lacks the field.
11
+ - `relocateFeature`: an embed's paragraph counts as occupied when a card is relocated.
12
+
5
13
  ## 0.61.0 (2026-11-08)
6
14
 
7
15
  - No changes (lockstep release).
@@ -4,8 +4,8 @@ export { selectRecentlyUpdated, isUpdatedAfterPublication, RECENT_UPDATE_WINDOW_
4
4
  export type { ArticleDates } from './recent.ts';
5
5
  export { ARTICLE_FORMATS, ARTICLE_SHAPE_UNION, FORMATS, FORMAT_NAMES, LEGACY_SHAPE, shapeFor, checkFormat, checkCounts, checkKeyFactCount, checkWords, countBodyWords, validateShape, articleShapeIssues, } from './formats.ts';
6
6
  export type { ArticleFormat, ArticleMode, ArticleShape, FormatCard, Range, ShapeIssue, ShapeRanges } from './formats.ts';
7
- export { articleSchemaFields, articleSuperRefineIssues, createArticleSchema, } from './schema.ts';
8
- export type { ArticleSchemaOptions, ArticleTagMeta } from './schema.ts';
7
+ export { articleSchemaFields, articleSuperRefineIssues, createArticleSchema, ARTICLE_EMBED_PROVIDERS, ARTICLE_EMBED_MAX_PER_SECTION, YOUTUBE_ID_PATTERN, } from './schema.ts';
8
+ export type { ArticleSchemaOptions, ArticleTagMeta, ArticleEmbedProvider } from './schema.ts';
9
9
  export { ARTICLES_PAGE_SIZE, MIN_HUB_ARTICLES, MIN_INDEXABLE_HUB_ARTICLES, MIN_INDEXABLE_TAG_ARTICLES, publishedInstant, sortArticles, totalArticlePages, articlesForPage, articlePagePath, articleTagPath, topicNeighbours, hubCategories, hubNavCategories, tagArticles, populatedTags, indexableTags, topTags, topCategoryTags, } from './listing.ts';
10
10
  export type { ArticleHubCopy, ListableArticle, ListableArticleData } from './listing.ts';
11
11
  export { splitParagraphs, renderInlineMarkdown, toISO, mergeAnswerBoxFaqs, } from './render.ts';
@@ -2,6 +2,6 @@
2
2
  export { selectFeaturedArticles, FEATURED_SHELF_SIZE, FEATURED_MAX_AGE_DAYS } from "./featured.js";
3
3
  export { selectRecentlyUpdated, isUpdatedAfterPublication, RECENT_UPDATE_WINDOW_DAYS, RECENT_UPDATE_MAX } from "./recent.js";
4
4
  export { ARTICLE_FORMATS, ARTICLE_SHAPE_UNION, FORMATS, FORMAT_NAMES, LEGACY_SHAPE, shapeFor, checkFormat, checkCounts, checkKeyFactCount, checkWords, countBodyWords, validateShape, articleShapeIssues, } from "./formats.js";
5
- export { articleSchemaFields, articleSuperRefineIssues, createArticleSchema, } from "./schema.js";
5
+ export { articleSchemaFields, articleSuperRefineIssues, createArticleSchema, ARTICLE_EMBED_PROVIDERS, ARTICLE_EMBED_MAX_PER_SECTION, YOUTUBE_ID_PATTERN, } from "./schema.js";
6
6
  export { ARTICLES_PAGE_SIZE, MIN_HUB_ARTICLES, MIN_INDEXABLE_HUB_ARTICLES, MIN_INDEXABLE_TAG_ARTICLES, publishedInstant, sortArticles, totalArticlePages, articlesForPage, articlePagePath, articleTagPath, topicNeighbours, hubCategories, hubNavCategories, tagArticles, populatedTags, indexableTags, topTags, topCategoryTags, } from "./listing.js";
7
7
  export { splitParagraphs, renderInlineMarkdown, toISO, mergeAnswerBoxFaqs, } from "./render.js";
@@ -1,6 +1,11 @@
1
1
  import type { z as Zod } from 'astro/zod';
2
2
  import { type InterludeSchemaConfig } from '../interludes/index.ts';
3
3
  import type { FieldIssue } from '../internal/issues.ts';
4
+ /** Embed providers an article section can place. Instagram is deliberately absent (SLA-3977). */
5
+ export declare const ARTICLE_EMBED_PROVIDERS: readonly ["youtube"];
6
+ export type ArticleEmbedProvider = (typeof ARTICLE_EMBED_PROVIDERS)[number];
7
+ export declare const YOUTUBE_ID_PATTERN: RegExp;
8
+ export declare const ARTICLE_EMBED_MAX_PER_SECTION = 2;
4
9
  /** Metadata for a controlled article tag (used in `src/data/articleTags.ts` and `/articles/tag/[tag]` hubs). */
5
10
  export interface ArticleTagMeta {
6
11
  label: string;
@@ -127,6 +132,15 @@ export declare function articleSchemaFields(z: ZodLike, options: ArticleSchemaOp
127
132
  caption: Zod.ZodOptional<Zod.ZodString>;
128
133
  afterParagraph: Zod.ZodNumber;
129
134
  }, Zod.z.core.$strip>>>;
135
+ embeds: Zod.ZodOptional<Zod.ZodArray<Zod.ZodObject<{
136
+ provider: Zod.ZodEnum<{
137
+ youtube: "youtube";
138
+ }>;
139
+ id: Zod.ZodString;
140
+ title: Zod.ZodString;
141
+ caption: Zod.ZodOptional<Zod.ZodString>;
142
+ afterParagraph: Zod.ZodNumber;
143
+ }, Zod.z.core.$strip>>>;
130
144
  affiliateCarousels: Zod.ZodOptional<Zod.ZodArray<Zod.ZodObject<{
131
145
  ids: Zod.ZodOptional<Zod.ZodArray<Zod.ZodNumber>>;
132
146
  afterParagraph: Zod.ZodNumber;
@@ -232,6 +246,15 @@ export declare function articleSchemaFields(z: ZodLike, options: ArticleSchemaOp
232
246
  caption: Zod.ZodOptional<Zod.ZodString>;
233
247
  afterParagraph: Zod.ZodNumber;
234
248
  }, Zod.z.core.$strip>>>;
249
+ embeds: Zod.ZodOptional<Zod.ZodArray<Zod.ZodObject<{
250
+ provider: Zod.ZodEnum<{
251
+ youtube: "youtube";
252
+ }>;
253
+ id: Zod.ZodString;
254
+ title: Zod.ZodString;
255
+ caption: Zod.ZodOptional<Zod.ZodString>;
256
+ afterParagraph: Zod.ZodNumber;
257
+ }, Zod.z.core.$strip>>>;
235
258
  affiliateCarousels: Zod.ZodOptional<Zod.ZodArray<Zod.ZodObject<{
236
259
  ids: Zod.ZodOptional<Zod.ZodArray<Zod.ZodNumber>>;
237
260
  afterParagraph: Zod.ZodNumber;
@@ -343,6 +366,15 @@ export declare function createArticleSchema(z: ZodLike, options: ArticleSchemaOp
343
366
  caption: Zod.ZodOptional<Zod.ZodString>;
344
367
  afterParagraph: Zod.ZodNumber;
345
368
  }, Zod.z.core.$strip>>>;
369
+ embeds: Zod.ZodOptional<Zod.ZodArray<Zod.ZodObject<{
370
+ provider: Zod.ZodEnum<{
371
+ youtube: "youtube";
372
+ }>;
373
+ id: Zod.ZodString;
374
+ title: Zod.ZodString;
375
+ caption: Zod.ZodOptional<Zod.ZodString>;
376
+ afterParagraph: Zod.ZodNumber;
377
+ }, Zod.z.core.$strip>>>;
346
378
  affiliateCarousels: Zod.ZodOptional<Zod.ZodArray<Zod.ZodObject<{
347
379
  ids: Zod.ZodOptional<Zod.ZodArray<Zod.ZodNumber>>;
348
380
  afterParagraph: Zod.ZodNumber;
@@ -448,6 +480,15 @@ export declare function createArticleSchema(z: ZodLike, options: ArticleSchemaOp
448
480
  caption: Zod.ZodOptional<Zod.ZodString>;
449
481
  afterParagraph: Zod.ZodNumber;
450
482
  }, Zod.z.core.$strip>>>;
483
+ embeds: Zod.ZodOptional<Zod.ZodArray<Zod.ZodObject<{
484
+ provider: Zod.ZodEnum<{
485
+ youtube: "youtube";
486
+ }>;
487
+ id: Zod.ZodString;
488
+ title: Zod.ZodString;
489
+ caption: Zod.ZodOptional<Zod.ZodString>;
490
+ afterParagraph: Zod.ZodNumber;
491
+ }, Zod.z.core.$strip>>>;
451
492
  affiliateCarousels: Zod.ZodOptional<Zod.ZodArray<Zod.ZodObject<{
452
493
  ids: Zod.ZodOptional<Zod.ZodArray<Zod.ZodNumber>>;
453
494
  afterParagraph: Zod.ZodNumber;
@@ -2,6 +2,10 @@ import { eraSchemaFields, eraYearIssues } from "../eras/index.js";
2
2
  import { createInterludeSchema, INTERLUDE_MAX_PER_SECTION } from "../interludes/index.js";
3
3
  import { isObject } from "../internal/guards.js";
4
4
  import { ARTICLE_FORMATS, ARTICLE_SHAPE_UNION, articleShapeIssues } from "./formats.js";
5
+ /** Embed providers an article section can place. Instagram is deliberately absent (SLA-3977). */
6
+ export const ARTICLE_EMBED_PROVIDERS = ['youtube'];
7
+ export const YOUTUBE_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
8
+ export const ARTICLE_EMBED_MAX_PER_SECTION = 2;
5
9
  /**
6
10
  * Pure validation issues for an article object's `superRefine` block:
7
11
  * - format & section/FAQ count shape rules (`articleShapeIssues`)
@@ -123,6 +127,13 @@ export function articleSchemaFields(z, options) {
123
127
  caption: z.string().optional(),
124
128
  afterParagraph: z.number().int().min(0),
125
129
  })).max(2).optional(),
130
+ embeds: z.array(z.object({
131
+ provider: z.enum(ARTICLE_EMBED_PROVIDERS),
132
+ id: z.string().regex(YOUTUBE_ID_PATTERN, 'YouTube video id (11 chars), not a URL'),
133
+ title: z.string().trim().min(1),
134
+ caption: z.string().optional(),
135
+ afterParagraph: z.number().int().min(0),
136
+ })).max(ARTICLE_EMBED_MAX_PER_SECTION).optional(),
126
137
  affiliateCarousels: z.array(z.object({
127
138
  ids: z.array(z.number().int()).min(1).max(4).optional(),
128
139
  afterParagraph: z.number().int().min(0),
@@ -8,6 +8,7 @@ interface Section {
8
8
  } & Partial<Block>)[];
9
9
  affiliateCarousels?: Block[];
10
10
  inlineImages?: Block[];
11
+ embeds?: Block[];
11
12
  }
12
13
  /** The card's paragraph: the clear slot nearest the section's middle, else the middle clamped before the last paragraph. */
13
14
  export declare function pickFeatureParagraph(section: Section): number;
@@ -1,6 +1,6 @@
1
1
  const paragraphsOf = (s) => (s.body ?? '').split(/\n{2,}/).filter(Boolean).length;
2
- const occupied = (s) => [...(s.interludes ?? []), ...(s.affiliateCarousels ?? []), ...(s.inlineImages ?? [])].flatMap((b) => typeof b.afterParagraph === 'number' ? [b.afterParagraph] : []);
3
- const isFree = (s) => !(s.interludes?.length || s.affiliateCarousels?.length || s.inlineImages?.length);
2
+ const occupied = (s) => [...(s.interludes ?? []), ...(s.affiliateCarousels ?? []), ...(s.inlineImages ?? []), ...(s.embeds ?? [])].flatMap((b) => typeof b.afterParagraph === 'number' ? [b.afterParagraph] : []);
3
+ const isFree = (s) => !(s.interludes?.length || s.affiliateCarousels?.length || s.inlineImages?.length || s.embeds?.length);
4
4
  /** Slots at least two paragraphs from every block, so prose sits between; never the last paragraph of a multi-paragraph section. */
5
5
  const clearSlots = (section) => {
6
6
  const taken = occupied(section);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarimarcus/content-sites-core",
3
- "version": "0.61.0",
3
+ "version": "0.62.0",
4
4
  "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -10,8 +10,9 @@ export {
10
10
  export type { ArticleFormat, ArticleMode, ArticleShape, FormatCard, Range, ShapeIssue, ShapeRanges } from './formats.ts';
11
11
  export {
12
12
  articleSchemaFields, articleSuperRefineIssues, createArticleSchema,
13
+ ARTICLE_EMBED_PROVIDERS, ARTICLE_EMBED_MAX_PER_SECTION, YOUTUBE_ID_PATTERN,
13
14
  } from './schema.ts';
14
- export type { ArticleSchemaOptions, ArticleTagMeta } from './schema.ts';
15
+ export type { ArticleSchemaOptions, ArticleTagMeta, ArticleEmbedProvider } from './schema.ts';
15
16
  export {
16
17
  ARTICLES_PAGE_SIZE, MIN_HUB_ARTICLES, MIN_INDEXABLE_HUB_ARTICLES, MIN_INDEXABLE_TAG_ARTICLES,
17
18
  publishedInstant, sortArticles, totalArticlePages, articlesForPage, articlePagePath, articleTagPath,
@@ -9,6 +9,12 @@ import type { FieldIssue } from '../internal/issues.ts';
9
9
  import { isObject } from '../internal/guards.ts';
10
10
  import { ARTICLE_FORMATS, ARTICLE_SHAPE_UNION, articleShapeIssues } from './formats.ts';
11
11
 
12
+ /** Embed providers an article section can place. Instagram is deliberately absent (SLA-3977). */
13
+ export const ARTICLE_EMBED_PROVIDERS = ['youtube'] as const;
14
+ export type ArticleEmbedProvider = (typeof ARTICLE_EMBED_PROVIDERS)[number];
15
+ export const YOUTUBE_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
16
+ export const ARTICLE_EMBED_MAX_PER_SECTION = 2;
17
+
12
18
  /** Metadata for a controlled article tag (used in `src/data/articleTags.ts` and `/articles/tag/[tag]` hubs). */
13
19
  export interface ArticleTagMeta {
14
20
  label: string;
@@ -180,6 +186,13 @@ export function articleSchemaFields(z: ZodLike, options: ArticleSchemaOptions) {
180
186
  caption: z.string().optional(),
181
187
  afterParagraph: z.number().int().min(0),
182
188
  })).max(2).optional(),
189
+ embeds: z.array(z.object({
190
+ provider: z.enum(ARTICLE_EMBED_PROVIDERS),
191
+ id: z.string().regex(YOUTUBE_ID_PATTERN, 'YouTube video id (11 chars), not a URL'),
192
+ title: z.string().trim().min(1),
193
+ caption: z.string().optional(),
194
+ afterParagraph: z.number().int().min(0),
195
+ })).max(ARTICLE_EMBED_MAX_PER_SECTION).optional(),
183
196
  affiliateCarousels: z.array(z.object({
184
197
  ids: z.array(z.number().int()).min(1).max(4).optional(),
185
198
  afterParagraph: z.number().int().min(0),
@@ -4,14 +4,15 @@ interface Section {
4
4
  interludes?: ({ type: string } & Partial<Block>)[];
5
5
  affiliateCarousels?: Block[];
6
6
  inlineImages?: Block[];
7
+ embeds?: Block[];
7
8
  }
8
9
 
9
10
  const paragraphsOf = (s: Section) => (s.body ?? '').split(/\n{2,}/).filter(Boolean).length;
10
11
  const occupied = (s: Section) =>
11
- [...(s.interludes ?? []), ...(s.affiliateCarousels ?? []), ...(s.inlineImages ?? [])].flatMap((b) =>
12
+ [...(s.interludes ?? []), ...(s.affiliateCarousels ?? []), ...(s.inlineImages ?? []), ...(s.embeds ?? [])].flatMap((b) =>
12
13
  typeof b.afterParagraph === 'number' ? [b.afterParagraph] : [],
13
14
  );
14
- const isFree = (s: Section) => !(s.interludes?.length || s.affiliateCarousels?.length || s.inlineImages?.length);
15
+ const isFree = (s: Section) => !(s.interludes?.length || s.affiliateCarousels?.length || s.inlineImages?.length || s.embeds?.length);
15
16
 
16
17
  /** Slots at least two paragraphs from every block, so prose sits between; never the last paragraph of a multi-paragraph section. */
17
18
  const clearSlots = (section: Section): number[] => {