bsmnt 0.13.0 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bsmnt",
-	"version": "0.13.0",
+	"version": "0.13.1",
 	"packageManager": "bun@1.3.14",
 	"description": "CLI to scaffold basement projects and add integrations",
 	"type": "module",

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/page-builder-config.ts

@@ -88,7 +88,7 @@ const reusablePageBuilderReferenceMembers: PageBuilderReferenceMember[] = [
 	{
 		documentType: "blogContent",
 		name: "blogContentReference",
-		title: "Blog Content",
+		title: "Blog Posts",
 		pageTypes: ["blogEntry"],
 		category: "content",
 	},

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/presentation.ts

@@ -7,6 +7,7 @@ import {
 	presentationTool,
 } from "sanity/presentation";
 import { previewURL } from "./env";
+import { pageBuilderReferenceMembers } from "./page-builder-config";
 import { getPinnedPageById, HOMEPAGE_PINNED_PAGE } from "./pinned-pages";
 
 const MAX_FOLDER_DEPTH = 6;
@@ -43,10 +44,52 @@ const pageResolvedSlugExpression = buildNestedSlugExpression(
 	"slug.current",
 );
 
-const CONTENT_TYPE_PREFIXES: Record<string, string> = {
-	blogContent: "blog",
+const PAGE_BUILDER_DOCUMENT_TYPES = new Set<string>(
+	pageBuilderReferenceMembers.map((member) => member.documentType),
+);
+
+const HOST_PAGES_QUERY = `*[_type == "page" && references($id)]{
+  _id,
+  title,
+  "resolvedSlug": ${pageResolvedSlugExpression}
+}`;
+
+type HostPage = {
+	_id: string;
+	title?: string;
+	resolvedSlug?: string;
 };
 
+const isDraftId = (id: string) => id.startsWith("drafts.");
+
+const resolveHostPageLocations = (
+	documentStore: DocumentStore,
+	id: string,
+): Observable<DocumentLocationsState> =>
+	documentStore.listenQuery(HOST_PAGES_QUERY, { id }, {}).pipe(
+		map((pages: HostPage[] | null) => {
+			const deduped = new Map<string, HostPage>();
+			for (const page of pages ?? []) {
+				const publishedId = page._id.replace(/^drafts\./, "");
+				const existing = deduped.get(publishedId);
+				if (!existing || isDraftId(existing._id)) {
+					deduped.set(publishedId, page);
+				}
+			}
+
+			return {
+				locations: [...deduped.values()].flatMap((page) => {
+					const pinned = getPinnedPageById(page._id);
+					const href =
+						pinned?.path ??
+						(page.resolvedSlug ? `/${page.resolvedSlug}` : null);
+					if (!href) return [];
+					return [{ title: page.title || pinned?.title || "Page", href }];
+				}),
+			};
+		}),
+	);
+
 const resolveSlugLocation = <T extends { title?: string }>(
 	documentStore: DocumentStore,
 	id: string,
@@ -73,10 +116,6 @@ export const presentation = presentationTool({
 				route: "/",
 				filter: `_type == "page" && _id == "${HOMEPAGE_PINNED_PAGE.id}"`,
 			},
-			...Object.entries(CONTENT_TYPE_PREFIXES).map(([type, prefix]) => ({
-				route: `/${prefix}/:slug`,
-				filter: `_type == "${type}" && slug.current == $slug`,
-			})),
 			{
 				route: "/:slug+",
 				filter: `_type == "page" && ${pageResolvedSlugExpression} == $slug`,
@@ -97,16 +136,9 @@ export const presentation = presentationTool({
 				);
 			}
 
-			const prefix = CONTENT_TYPE_PREFIXES[params.type];
-			if (!prefix) return null;
+			if (!PAGE_BUILDER_DOCUMENT_TYPES.has(params.type)) return null;
 
-			return resolveSlugLocation<{ title?: string; slug?: string }>(
-				documentStore,
-				params.id,
-				`title, "slug": slug.current`,
-				(doc) => (doc.slug ? `/${prefix}/${doc.slug}` : null),
-				"Untitled",
-			);
+			return resolveHostPageLocations(documentStore, params.id);
 		},
 	},
 	previewUrl: {

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/schemas/components/reusable/blog-content.ts

@@ -4,7 +4,7 @@ import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block";
 
 export const blogContent = defineBlock({
 	name: "blogContent",
-	title: "Blog Content",
+	title: "Blog Posts",
 	icon: contentIcon,
 	fields: [
 		defineField({
@@ -80,7 +80,7 @@ export const blogContent = defineBlock({
 		},
 		prepare({ title, date, media }) {
 			return {
-				title: title || "Blog Content",
+				title: title || "Blog Posts",
 				subtitle: date || "No date set",
 				media,
 			};

package/src/modules/features/cms/sanity-pagebuilder/files/lib/integrations/sanity/structure.ts

@@ -252,7 +252,7 @@ export const structure: StructureResolver = (S, context) =>
 
 			S.divider(),
 
-			// GROUP 2: Content -- authors, blog categories
+			// GROUP 2: Content -- blog posts, authors, blog categories
 			S.listItem()
 				.title("Content")
 				.icon(contentFolderIcon)
@@ -260,6 +260,9 @@ export const structure: StructureResolver = (S, context) =>
 					S.list()
 						.title("Content")
 						.items([
+							S.documentTypeListItem("blogContent")
+								.title("Blog Posts")
+								.icon(contentIcon),
 							S.documentTypeListItem("author")
 								.title("Authors")
 								.icon(authorIcon),
@@ -299,9 +302,6 @@ export const structure: StructureResolver = (S, context) =>
 							S.documentTypeListItem("gatedContent")
 								.title("Gated Content")
 								.icon(gatedContentIcon),
-							S.documentTypeListItem("blogContent")
-								.title("Blog Content")
-								.icon(contentIcon),
 							S.divider(),
 							S.documentTypeListItem("studioPreview")
 								.title("Component Previews")

package/src/modules/features/cms/sanity-pagebuilder-cache/files/lib/integrations/sanity/page-builder-config.ts

@@ -88,7 +88,7 @@ const reusablePageBuilderReferenceMembers: PageBuilderReferenceMember[] = [
 	{
 		documentType: "blogContent",
 		name: "blogContentReference",
-		title: "Blog Content",
+		title: "Blog Posts",
 		pageTypes: ["blogEntry"],
 		category: "content",
 	},

package/src/modules/features/cms/sanity-pagebuilder-cache/files/lib/integrations/sanity/presentation.ts

@@ -7,6 +7,7 @@ import {
 	presentationTool,
 } from "sanity/presentation";
 import { previewURL } from "./env";
+import { pageBuilderReferenceMembers } from "./page-builder-config";
 import { getPinnedPageById, HOMEPAGE_PINNED_PAGE } from "./pinned-pages";
 
 const MAX_FOLDER_DEPTH = 6;
@@ -43,10 +44,52 @@ const pageResolvedSlugExpression = buildNestedSlugExpression(
 	"slug.current",
 );
 
-const CONTENT_TYPE_PREFIXES: Record<string, string> = {
-	blogContent: "blog",
+const PAGE_BUILDER_DOCUMENT_TYPES = new Set<string>(
+	pageBuilderReferenceMembers.map((member) => member.documentType),
+);
+
+const HOST_PAGES_QUERY = `*[_type == "page" && references($id)]{
+  _id,
+  title,
+  "resolvedSlug": ${pageResolvedSlugExpression}
+}`;
+
+type HostPage = {
+	_id: string;
+	title?: string;
+	resolvedSlug?: string;
 };
 
+const isDraftId = (id: string) => id.startsWith("drafts.");
+
+const resolveHostPageLocations = (
+	documentStore: DocumentStore,
+	id: string,
+): Observable<DocumentLocationsState> =>
+	documentStore.listenQuery(HOST_PAGES_QUERY, { id }, {}).pipe(
+		map((pages: HostPage[] | null) => {
+			const deduped = new Map<string, HostPage>();
+			for (const page of pages ?? []) {
+				const publishedId = page._id.replace(/^drafts\./, "");
+				const existing = deduped.get(publishedId);
+				if (!existing || isDraftId(existing._id)) {
+					deduped.set(publishedId, page);
+				}
+			}
+
+			return {
+				locations: [...deduped.values()].flatMap((page) => {
+					const pinned = getPinnedPageById(page._id);
+					const href =
+						pinned?.path ??
+						(page.resolvedSlug ? `/${page.resolvedSlug}` : null);
+					if (!href) return [];
+					return [{ title: page.title || pinned?.title || "Page", href }];
+				}),
+			};
+		}),
+	);
+
 const resolveSlugLocation = <T extends { title?: string }>(
 	documentStore: DocumentStore,
 	id: string,
@@ -73,10 +116,6 @@ export const presentation = presentationTool({
 				route: "/",
 				filter: `_type == "page" && _id == "${HOMEPAGE_PINNED_PAGE.id}"`,
 			},
-			...Object.entries(CONTENT_TYPE_PREFIXES).map(([type, prefix]) => ({
-				route: `/${prefix}/:slug`,
-				filter: `_type == "${type}" && slug.current == $slug`,
-			})),
 			{
 				route: "/:slug+",
 				filter: `_type == "page" && ${pageResolvedSlugExpression} == $slug`,
@@ -97,16 +136,9 @@ export const presentation = presentationTool({
 				);
 			}
 
-			const prefix = CONTENT_TYPE_PREFIXES[params.type];
-			if (!prefix) return null;
+			if (!PAGE_BUILDER_DOCUMENT_TYPES.has(params.type)) return null;
 
-			return resolveSlugLocation<{ title?: string; slug?: string }>(
-				documentStore,
-				params.id,
-				`title, "slug": slug.current`,
-				(doc) => (doc.slug ? `/${prefix}/${doc.slug}` : null),
-				"Untitled",
-			);
+			return resolveHostPageLocations(documentStore, params.id);
 		},
 	},
 	previewUrl: {

package/src/modules/features/cms/sanity-pagebuilder-cache/files/lib/integrations/sanity/schemas/components/reusable/blog-content.ts

@@ -4,7 +4,7 @@ import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block";
 
 export const blogContent = defineBlock({
 	name: "blogContent",
-	title: "Blog Content",
+	title: "Blog Posts",
 	icon: contentIcon,
 	fields: [
 		defineField({
@@ -80,7 +80,7 @@ export const blogContent = defineBlock({
 		},
 		prepare({ title, date, media }) {
 			return {
-				title: title || "Blog Content",
+				title: title || "Blog Posts",
 				subtitle: date || "No date set",
 				media,
 			};

package/src/modules/features/cms/sanity-pagebuilder-cache/files/lib/integrations/sanity/structure.ts

@@ -252,7 +252,7 @@ export const structure: StructureResolver = (S, context) =>
 
 			S.divider(),
 
-			// GROUP 2: Content -- authors, blog categories
+			// GROUP 2: Content -- blog posts, authors, blog categories
 			S.listItem()
 				.title("Content")
 				.icon(contentFolderIcon)
@@ -260,6 +260,9 @@ export const structure: StructureResolver = (S, context) =>
 					S.list()
 						.title("Content")
 						.items([
+							S.documentTypeListItem("blogContent")
+								.title("Blog Posts")
+								.icon(contentIcon),
 							S.documentTypeListItem("author")
 								.title("Authors")
 								.icon(authorIcon),
@@ -299,9 +302,6 @@ export const structure: StructureResolver = (S, context) =>
 							S.documentTypeListItem("gatedContent")
 								.title("Gated Content")
 								.icon(gatedContentIcon),
-							S.documentTypeListItem("blogContent")
-								.title("Blog Content")
-								.icon(contentIcon),
 							S.divider(),
 							S.documentTypeListItem("studioPreview")
 								.title("Component Previews")

package/src/templates/next-default/lib/utils/README.md

@@ -45,6 +45,7 @@ export const metadata = generatePageMetadata({ title: 'About' })
 // next/image sizes — keys mirror the element's Tailwind variants
 buildImageSizes({ base: '100vw', desktop: '796px' })
 buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 })
+buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 }, { maxWidth: 1440 })
 
 // Refs — in a component, use the hook: an inline mergeRefs([...]) is a new
 // callback each render, so React detaches and reattaches every ref.

package/src/templates/next-default/lib/utils/image-sizes.ts

@@ -15,40 +15,55 @@ export type ByBreakpoint<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
 > = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
 
+export type ImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { breakpoints?: B }
+
+export type GridImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = ImageSizesOptions<B> & {
+  /** The grid container's `max-width` in px, past which columns stop growing. */
+  maxWidth?: number
+}
+
+type Condition<T> = { min: number; value: T }
+
 function columnWidth(columns: number): string {
   return `${Math.round(100 / columns)}vw`
 }
 
+function toConditions<T>(
+  overrides: Readonly<Record<string, T | undefined>>,
+  scale: BreakpointMap
+): Condition<T>[] {
+  return Object.entries(overrides).flatMap(([name, value]) => {
+    const min = scale[name]
+    return value !== undefined && min !== undefined ? [{ min, value }] : []
+  })
+}
+
 /**
  * Widest first, since `sizes` takes the first matching condition and the last
  * entry must be bare. `min-width` matches the Tailwind variant's boundary; a
  * `max-width: <next> - 1` one would leave a fractional-pixel gap.
  */
-function toSizes(
-  base: string,
-  overrides: Readonly<Record<string, string | undefined>>,
-  scale: BreakpointMap
-): string {
-  const conditions: string[] = []
-
-  for (const [name, min] of Object.entries(scale).sort(
-    ([, a], [, b]) => b - a
-  )) {
-    const value = overrides[name]
-    if (value !== undefined) {
-      conditions.push(`(min-width: ${min}px) ${value}`)
-    }
-  }
+function joinSizes(base: string, conditions: Condition<string>[]): string {
+  const sorted = [...conditions].sort((a, b) => b.min - a.min)
 
-  return [...conditions, base].join(", ")
+  return [
+    ...sorted.map(({ min, value }) => `(min-width: ${min}px) ${value}`),
+    base,
+  ].join(", ")
 }
 
 /** Builds `sizes` from the CSS length the image renders at per breakpoint. */
 export function buildImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(widths: ByBreakpoint<string, B>, breakpoints?: B): string {
+>(widths: ByBreakpoint<string, B>, options: ImageSizesOptions<B> = {}): string {
   const { base, ...overrides } = widths
-  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+  const scale = options.breakpoints ?? BASEMENT_BREAKPOINTS
+
+  return joinSizes(base, toConditions<string>(overrides, scale))
 }
 
 /**
@@ -58,15 +73,39 @@ export function buildImageSizes<
  */
 export function buildGridImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+>(
+  columns: ByBreakpoint<number, B>,
+  options: GridImageSizesOptions<B> = {}
+): string {
+  const { maxWidth, breakpoints } = options
   const { base, ...overrides } = columns
-  const widths: Record<string, string> = {}
+  const steps = toConditions<number>(
+    overrides,
+    breakpoints ?? BASEMENT_BREAKPOINTS
+  )
+  const cap =
+    maxWidth !== undefined && Number.isFinite(maxWidth) && maxWidth > 0
+      ? maxWidth
+      : undefined
+
+  // The cap rarely lands on a breakpoint, so it needs its own condition.
+  if (cap !== undefined && !steps.some(({ min }) => min === cap)) {
+    const below = steps
+      .filter(({ min }) => min < cap)
+      .sort((a, b) => a.min - b.min)
+      .at(-1)
 
-  for (const [name, count] of Object.entries(overrides)) {
-    if (count !== undefined) {
-      widths[name] = columnWidth(count)
-    }
+    steps.push({ min: cap, value: below?.value ?? base })
   }
 
-  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+  return joinSizes(
+    columnWidth(base),
+    steps.map(({ min, value }) => ({
+      min,
+      value:
+        cap !== undefined && min >= cap
+          ? `${Math.round(cap / value)}px`
+          : columnWidth(value),
+    }))
+  )
 }

package/src/templates/next-experiments/lib/utils/README.md

@@ -45,6 +45,7 @@ export const metadata = generatePageMetadata({ title: 'About' })
 // next/image sizes — keys mirror the element's Tailwind variants
 buildImageSizes({ base: '100vw', desktop: '796px' })
 buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 })
+buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 }, { maxWidth: 1440 })
 
 // Refs — in a component, use the hook: an inline mergeRefs([...]) is a new
 // callback each render, so React detaches and reattaches every ref.

package/src/templates/next-experiments/lib/utils/image-sizes.ts

@@ -15,40 +15,55 @@ export type ByBreakpoint<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
 > = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
 
+export type ImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { breakpoints?: B }
+
+export type GridImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = ImageSizesOptions<B> & {
+  /** The grid container's `max-width` in px, past which columns stop growing. */
+  maxWidth?: number
+}
+
+type Condition<T> = { min: number; value: T }
+
 function columnWidth(columns: number): string {
   return `${Math.round(100 / columns)}vw`
 }
 
+function toConditions<T>(
+  overrides: Readonly<Record<string, T | undefined>>,
+  scale: BreakpointMap
+): Condition<T>[] {
+  return Object.entries(overrides).flatMap(([name, value]) => {
+    const min = scale[name]
+    return value !== undefined && min !== undefined ? [{ min, value }] : []
+  })
+}
+
 /**
  * Widest first, since `sizes` takes the first matching condition and the last
  * entry must be bare. `min-width` matches the Tailwind variant's boundary; a
  * `max-width: <next> - 1` one would leave a fractional-pixel gap.
  */
-function toSizes(
-  base: string,
-  overrides: Readonly<Record<string, string | undefined>>,
-  scale: BreakpointMap
-): string {
-  const conditions: string[] = []
-
-  for (const [name, min] of Object.entries(scale).sort(
-    ([, a], [, b]) => b - a
-  )) {
-    const value = overrides[name]
-    if (value !== undefined) {
-      conditions.push(`(min-width: ${min}px) ${value}`)
-    }
-  }
+function joinSizes(base: string, conditions: Condition<string>[]): string {
+  const sorted = [...conditions].sort((a, b) => b.min - a.min)
 
-  return [...conditions, base].join(", ")
+  return [
+    ...sorted.map(({ min, value }) => `(min-width: ${min}px) ${value}`),
+    base,
+  ].join(", ")
 }
 
 /** Builds `sizes` from the CSS length the image renders at per breakpoint. */
 export function buildImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(widths: ByBreakpoint<string, B>, breakpoints?: B): string {
+>(widths: ByBreakpoint<string, B>, options: ImageSizesOptions<B> = {}): string {
   const { base, ...overrides } = widths
-  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+  const scale = options.breakpoints ?? BASEMENT_BREAKPOINTS
+
+  return joinSizes(base, toConditions<string>(overrides, scale))
 }
 
 /**
@@ -58,15 +73,39 @@ export function buildImageSizes<
  */
 export function buildGridImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+>(
+  columns: ByBreakpoint<number, B>,
+  options: GridImageSizesOptions<B> = {}
+): string {
+  const { maxWidth, breakpoints } = options
   const { base, ...overrides } = columns
-  const widths: Record<string, string> = {}
+  const steps = toConditions<number>(
+    overrides,
+    breakpoints ?? BASEMENT_BREAKPOINTS
+  )
+  const cap =
+    maxWidth !== undefined && Number.isFinite(maxWidth) && maxWidth > 0
+      ? maxWidth
+      : undefined
+
+  // The cap rarely lands on a breakpoint, so it needs its own condition.
+  if (cap !== undefined && !steps.some(({ min }) => min === cap)) {
+    const below = steps
+      .filter(({ min }) => min < cap)
+      .sort((a, b) => a.min - b.min)
+      .at(-1)
 
-  for (const [name, count] of Object.entries(overrides)) {
-    if (count !== undefined) {
-      widths[name] = columnWidth(count)
-    }
+    steps.push({ min: cap, value: below?.value ?? base })
   }
 
-  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+  return joinSizes(
+    columnWidth(base),
+    steps.map(({ min, value }) => ({
+      min,
+      value:
+        cap !== undefined && min >= cap
+          ? `${Math.round(cap / value)}px`
+          : columnWidth(value),
+    }))
+  )
 }

package/src/templates/next-pagebuilder/components/page-document/index.tsx

@@ -90,7 +90,7 @@ export const PageDocument = ({
   // Editor-selected page-level structured data (FAQ, Event, custom, etc.).
   const pageJsonLd = buildPageJsonLd(page.metadata?.jsonLd)
 
-  // Blog posts (pages with a Blog Content block) emit Article JSON-LD with
+  // Blog posts (pages with a Blog Posts block) emit Article JSON-LD with
   // fields derived from the post — no Custom block needed. Skipped when the
   // editor already supplied an Article (via a Custom block) to avoid duplicates.
   const blogBlock = page.pageBuilder?.find(

package/src/templates/next-pagebuilder/lib/utils/image-sizes.ts

@@ -15,40 +15,55 @@ export type ByBreakpoint<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
 > = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
 
+export type ImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { breakpoints?: B }
+
+export type GridImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = ImageSizesOptions<B> & {
+  /** The grid container's `max-width` in px, past which columns stop growing. */
+  maxWidth?: number
+}
+
+type Condition<T> = { min: number; value: T }
+
 function columnWidth(columns: number): string {
   return `${Math.round(100 / columns)}vw`
 }
 
+function toConditions<T>(
+  overrides: Readonly<Record<string, T | undefined>>,
+  scale: BreakpointMap
+): Condition<T>[] {
+  return Object.entries(overrides).flatMap(([name, value]) => {
+    const min = scale[name]
+    return value !== undefined && min !== undefined ? [{ min, value }] : []
+  })
+}
+
 /**
  * Widest first, since `sizes` takes the first matching condition and the last
  * entry must be bare. `min-width` matches the Tailwind variant's boundary; a
  * `max-width: <next> - 1` one would leave a fractional-pixel gap.
  */
-function toSizes(
-  base: string,
-  overrides: Readonly<Record<string, string | undefined>>,
-  scale: BreakpointMap
-): string {
-  const conditions: string[] = []
-
-  for (const [name, min] of Object.entries(scale).sort(
-    ([, a], [, b]) => b - a
-  )) {
-    const value = overrides[name]
-    if (value !== undefined) {
-      conditions.push(`(min-width: ${min}px) ${value}`)
-    }
-  }
+function joinSizes(base: string, conditions: Condition<string>[]): string {
+  const sorted = [...conditions].sort((a, b) => b.min - a.min)
 
-  return [...conditions, base].join(", ")
+  return [
+    ...sorted.map(({ min, value }) => `(min-width: ${min}px) ${value}`),
+    base,
+  ].join(", ")
 }
 
 /** Builds `sizes` from the CSS length the image renders at per breakpoint. */
 export function buildImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(widths: ByBreakpoint<string, B>, breakpoints?: B): string {
+>(widths: ByBreakpoint<string, B>, options: ImageSizesOptions<B> = {}): string {
   const { base, ...overrides } = widths
-  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+  const scale = options.breakpoints ?? BASEMENT_BREAKPOINTS
+
+  return joinSizes(base, toConditions<string>(overrides, scale))
 }
 
 /**
@@ -58,15 +73,39 @@ export function buildImageSizes<
  */
 export function buildGridImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+>(
+  columns: ByBreakpoint<number, B>,
+  options: GridImageSizesOptions<B> = {}
+): string {
+  const { maxWidth, breakpoints } = options
   const { base, ...overrides } = columns
-  const widths: Record<string, string> = {}
+  const steps = toConditions<number>(
+    overrides,
+    breakpoints ?? BASEMENT_BREAKPOINTS
+  )
+  const cap =
+    maxWidth !== undefined && Number.isFinite(maxWidth) && maxWidth > 0
+      ? maxWidth
+      : undefined
+
+  // The cap rarely lands on a breakpoint, so it needs its own condition.
+  if (cap !== undefined && !steps.some(({ min }) => min === cap)) {
+    const below = steps
+      .filter(({ min }) => min < cap)
+      .sort((a, b) => a.min - b.min)
+      .at(-1)
 
-  for (const [name, count] of Object.entries(overrides)) {
-    if (count !== undefined) {
-      widths[name] = columnWidth(count)
-    }
+    steps.push({ min: cap, value: below?.value ?? base })
   }
 
-  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+  return joinSizes(
+    columnWidth(base),
+    steps.map(({ min, value }) => ({
+      min,
+      value:
+        cap !== undefined && min >= cap
+          ? `${Math.round(cap / value)}px`
+          : columnWidth(value),
+    }))
+  )
 }

package/src/templates/next-pagebuilder-cache/components/page-document/index.tsx

@@ -92,7 +92,7 @@ export const PageDocument = ({
   // Editor-selected page-level structured data (FAQ, Event, custom, etc.).
   const pageJsonLd = buildPageJsonLd(page.metadata?.jsonLd)
 
-  // Blog posts (pages with a Blog Content block) emit Article JSON-LD with
+  // Blog posts (pages with a Blog Posts block) emit Article JSON-LD with
   // fields derived from the post — no Custom block needed. Skipped when the
   // editor already supplied an Article (via a Custom block) to avoid duplicates.
   const blogBlock = page.pageBuilder?.find(

package/src/templates/next-pagebuilder-cache/lib/utils/image-sizes.ts

@@ -15,40 +15,55 @@ export type ByBreakpoint<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
 > = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
 
+export type ImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { breakpoints?: B }
+
+export type GridImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = ImageSizesOptions<B> & {
+  /** The grid container's `max-width` in px, past which columns stop growing. */
+  maxWidth?: number
+}
+
+type Condition<T> = { min: number; value: T }
+
 function columnWidth(columns: number): string {
   return `${Math.round(100 / columns)}vw`
 }
 
+function toConditions<T>(
+  overrides: Readonly<Record<string, T | undefined>>,
+  scale: BreakpointMap
+): Condition<T>[] {
+  return Object.entries(overrides).flatMap(([name, value]) => {
+    const min = scale[name]
+    return value !== undefined && min !== undefined ? [{ min, value }] : []
+  })
+}
+
 /**
  * Widest first, since `sizes` takes the first matching condition and the last
  * entry must be bare. `min-width` matches the Tailwind variant's boundary; a
  * `max-width: <next> - 1` one would leave a fractional-pixel gap.
  */
-function toSizes(
-  base: string,
-  overrides: Readonly<Record<string, string | undefined>>,
-  scale: BreakpointMap
-): string {
-  const conditions: string[] = []
-
-  for (const [name, min] of Object.entries(scale).sort(
-    ([, a], [, b]) => b - a
-  )) {
-    const value = overrides[name]
-    if (value !== undefined) {
-      conditions.push(`(min-width: ${min}px) ${value}`)
-    }
-  }
+function joinSizes(base: string, conditions: Condition<string>[]): string {
+  const sorted = [...conditions].sort((a, b) => b.min - a.min)
 
-  return [...conditions, base].join(", ")
+  return [
+    ...sorted.map(({ min, value }) => `(min-width: ${min}px) ${value}`),
+    base,
+  ].join(", ")
 }
 
 /** Builds `sizes` from the CSS length the image renders at per breakpoint. */
 export function buildImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(widths: ByBreakpoint<string, B>, breakpoints?: B): string {
+>(widths: ByBreakpoint<string, B>, options: ImageSizesOptions<B> = {}): string {
   const { base, ...overrides } = widths
-  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+  const scale = options.breakpoints ?? BASEMENT_BREAKPOINTS
+
+  return joinSizes(base, toConditions<string>(overrides, scale))
 }
 
 /**
@@ -58,15 +73,39 @@ export function buildImageSizes<
  */
 export function buildGridImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+>(
+  columns: ByBreakpoint<number, B>,
+  options: GridImageSizesOptions<B> = {}
+): string {
+  const { maxWidth, breakpoints } = options
   const { base, ...overrides } = columns
-  const widths: Record<string, string> = {}
+  const steps = toConditions<number>(
+    overrides,
+    breakpoints ?? BASEMENT_BREAKPOINTS
+  )
+  const cap =
+    maxWidth !== undefined && Number.isFinite(maxWidth) && maxWidth > 0
+      ? maxWidth
+      : undefined
+
+  // The cap rarely lands on a breakpoint, so it needs its own condition.
+  if (cap !== undefined && !steps.some(({ min }) => min === cap)) {
+    const below = steps
+      .filter(({ min }) => min < cap)
+      .sort((a, b) => a.min - b.min)
+      .at(-1)
 
-  for (const [name, count] of Object.entries(overrides)) {
-    if (count !== undefined) {
-      widths[name] = columnWidth(count)
-    }
+    steps.push({ min: cap, value: below?.value ?? base })
   }
 
-  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+  return joinSizes(
+    columnWidth(base),
+    steps.map(({ min, value }) => ({
+      min,
+      value:
+        cap !== undefined && min >= cap
+          ? `${Math.round(cap / value)}px`
+          : columnWidth(value),
+    }))
+  )
 }

package/src/templates/next-webgl/lib/utils/README.md

@@ -45,6 +45,7 @@ export const metadata = generatePageMetadata({ title: 'About' })
 // next/image sizes — keys mirror the element's Tailwind variants
 buildImageSizes({ base: '100vw', desktop: '796px' })
 buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 })
+buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 }, { maxWidth: 1440 })
 
 // Refs — in a component, use the hook: an inline mergeRefs([...]) is a new
 // callback each render, so React detaches and reattaches every ref.

package/src/templates/next-webgl/lib/utils/image-sizes.ts

@@ -15,40 +15,55 @@ export type ByBreakpoint<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
 > = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
 
+export type ImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { breakpoints?: B }
+
+export type GridImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = ImageSizesOptions<B> & {
+  /** The grid container's `max-width` in px, past which columns stop growing. */
+  maxWidth?: number
+}
+
+type Condition<T> = { min: number; value: T }
+
 function columnWidth(columns: number): string {
   return `${Math.round(100 / columns)}vw`
 }
 
+function toConditions<T>(
+  overrides: Readonly<Record<string, T | undefined>>,
+  scale: BreakpointMap
+): Condition<T>[] {
+  return Object.entries(overrides).flatMap(([name, value]) => {
+    const min = scale[name]
+    return value !== undefined && min !== undefined ? [{ min, value }] : []
+  })
+}
+
 /**
  * Widest first, since `sizes` takes the first matching condition and the last
  * entry must be bare. `min-width` matches the Tailwind variant's boundary; a
  * `max-width: <next> - 1` one would leave a fractional-pixel gap.
  */
-function toSizes(
-  base: string,
-  overrides: Readonly<Record<string, string | undefined>>,
-  scale: BreakpointMap
-): string {
-  const conditions: string[] = []
-
-  for (const [name, min] of Object.entries(scale).sort(
-    ([, a], [, b]) => b - a
-  )) {
-    const value = overrides[name]
-    if (value !== undefined) {
-      conditions.push(`(min-width: ${min}px) ${value}`)
-    }
-  }
+function joinSizes(base: string, conditions: Condition<string>[]): string {
+  const sorted = [...conditions].sort((a, b) => b.min - a.min)
 
-  return [...conditions, base].join(", ")
+  return [
+    ...sorted.map(({ min, value }) => `(min-width: ${min}px) ${value}`),
+    base,
+  ].join(", ")
 }
 
 /** Builds `sizes` from the CSS length the image renders at per breakpoint. */
 export function buildImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(widths: ByBreakpoint<string, B>, breakpoints?: B): string {
+>(widths: ByBreakpoint<string, B>, options: ImageSizesOptions<B> = {}): string {
   const { base, ...overrides } = widths
-  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+  const scale = options.breakpoints ?? BASEMENT_BREAKPOINTS
+
+  return joinSizes(base, toConditions<string>(overrides, scale))
 }
 
 /**
@@ -58,15 +73,39 @@ export function buildImageSizes<
  */
 export function buildGridImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+>(
+  columns: ByBreakpoint<number, B>,
+  options: GridImageSizesOptions<B> = {}
+): string {
+  const { maxWidth, breakpoints } = options
   const { base, ...overrides } = columns
-  const widths: Record<string, string> = {}
+  const steps = toConditions<number>(
+    overrides,
+    breakpoints ?? BASEMENT_BREAKPOINTS
+  )
+  const cap =
+    maxWidth !== undefined && Number.isFinite(maxWidth) && maxWidth > 0
+      ? maxWidth
+      : undefined
+
+  // The cap rarely lands on a breakpoint, so it needs its own condition.
+  if (cap !== undefined && !steps.some(({ min }) => min === cap)) {
+    const below = steps
+      .filter(({ min }) => min < cap)
+      .sort((a, b) => a.min - b.min)
+      .at(-1)
 
-  for (const [name, count] of Object.entries(overrides)) {
-    if (count !== undefined) {
-      widths[name] = columnWidth(count)
-    }
+    steps.push({ min: cap, value: below?.value ?? base })
   }
 
-  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+  return joinSizes(
+    columnWidth(base),
+    steps.map(({ min, value }) => ({
+      min,
+      value:
+        cap !== undefined && min >= cap
+          ? `${Math.round(cap / value)}px`
+          : columnWidth(value),
+    }))
+  )
 }