bsmnt 0.13.1 → 0.14.0

package/src/modules/features/forms/hubspot/files/_sanity-adapter/form-block.ts

@@ -7,9 +7,10 @@ import {
 import { hubspotFormField } from "./form-field"
 
 /**
- * Sample reusable HubSpot form block. Register it in your schema's document
- * list (and page-builder config, if you use one), then render its `form` with
- * <HubSpotForm /> from the integration core:
+ * Sample HubSpot form block. Register it in your schema's type list, then render
+ * its `form` with <HubSpotForm /> from the integration core. In a page-builder
+ * project re-declare it through `defineBlock` so it becomes an inline block —
+ * the `hubspot-pagebuilder-block` skill walks through it:
  *
  * @example
  * import { HubSpotForm } from "@/lib/integrations/hubspot/form"
@@ -51,10 +52,3 @@ export const hubspotFormBlock = defineType({
     },
   },
 })
-
-export const hubspotFormBlockReference = defineType({
-  name: "hubspotFormBlockReference",
-  title: "HubSpot Form Block",
-  type: "reference",
-  to: [{ type: "hubspotFormBlock" }],
-})

package/src/modules/features/forms/hubspot/files/lib/integrations/hubspot/README.md

@@ -105,10 +105,15 @@ selectable block. Adding this integration installs the
 HubSpot form into the page builder" and it makes the edits and verifies the
 typecheck. To do it by hand:
 
-1. `schemas/index.ts` — import `hubspotFormBlock`, add it to `schema.types`
+1. `schemas/components/reusable/hubspot-form.ts` — re-declare the adapter
+   through `defineBlock`, so the block is an inline object with Anchor ID and
+   Presentation Mode; export it from `schemas/components/index.ts` and add it to
+   `schema.types` in `schemas/index.ts`
 2. `page-builder-config.ts` — add `"hubspotFormBlock"` to
-   `PageBuilderDocumentType` and a `hubspotFormBlockReference` member
-3. `structure.ts` — add `S.documentTypeListItem("hubspotFormBlock")`
-4. `components/page-builder/renderer.tsx` — add a `case "hubspotFormBlock"` that
-   decodes `block.form` and renders `<HubSpotForm />`
+   `PageBuilderDocumentType` and a `pageBuilderBlockMembers` entry with
+   `pageTypes` and `category`
+3. `components/page-builder/registry.tsx` — one entry keyed `hubspotFormBlock`
+   that decodes `block.form` and renders `<HubSpotForm />`
+4. `components/page-builder/library.ts` — a fixture entry, which is what the
+   insert menu, Studio → Components and `/components` render
 5. `bun run sanity:typegen && bun typecheck`

package/src/modules/features/jobs/ashby/files/_sanity-adapter/job-board-block.ts

@@ -44,10 +44,3 @@ export const ashbyJobBoardBlock = defineType({
     },
   },
 })
-
-export const ashbyJobBoardBlockReference = defineType({
-  name: "ashbyJobBoardBlockReference",
-  title: "Ashby Job Board",
-  type: "reference",
-  to: [{ type: "ashbyJobBoardBlock" }],
-})

package/src/modules/features/jobs/ashby/files/lib/integrations/ashby/README.md

@@ -125,10 +125,16 @@ selectable block. Adding this integration installs the
 Ashby job board into the page builder" and it makes the edits and verifies the
 typecheck. To do it by hand:
 
-1. `schemas/index.ts` — import `ashbyJobBoardBlock`, add it to `schema.types`
+1. `schemas/components/reusable/ashby-job-board.ts` — re-declare the adapter
+   through `defineBlock`, so the block is an inline object with Anchor ID and
+   Presentation Mode; export it from `schemas/components/index.ts` and add it to
+   `schema.types` in `schemas/index.ts`
 2. `page-builder-config.ts` — add `"ashbyJobBoardBlock"` to
-   `PageBuilderDocumentType` and an `ashbyJobBoardBlockReference` member
-3. `structure.ts` — add `S.documentTypeListItem("ashbyJobBoardBlock")`
-4. `components/page-builder/renderer.tsx` — add a `case "ashbyJobBoardBlock"`
-   that awaits `getCareerJobs(block.boardName)` and renders the list
+   `PageBuilderDocumentType` and a `pageBuilderBlockMembers` entry with
+   `pageTypes` and `category`
+3. `components/page-builder/registry.tsx` — one entry keyed
+   `ashbyJobBoardBlock` that awaits `getCareerJobs(block.boardName)` and renders
+   the list
+4. `components/page-builder/library.ts` — a fixture entry, which is what the
+   insert menu, Studio → Components and `/components` render
 5. `bun run sanity:typegen && bun typecheck`

package/src/templates/next-pagebuilder/AGENTS.md

@@ -11,14 +11,24 @@ page.
 Studio with a slug, not a directory. `app/(content)/[[...slug]]/page.tsx`
 resolves every one of them; a hand-written route shadows that resolver and
 becomes a URL no editor can see, move or delete. The only things that belong in
-`app/` are non-page endpoints — the Studio, API handlers, sitemap, feed.
+`app/` are non-page endpoints — the Studio, API handlers, sitemap, feed, and
+`app/components`, the Studio's live block preview: it renders fixtures rather
+than content, is gated to Studio embeds by `isStudioEmbed()` and is `noindex`.
 
 ## Page-builder blocks
 
+**Blocks are inline objects, never documents.** A placement belongs to exactly
+one page, so the page's `pageBuilder` array stores the block itself and nothing
+is dereferenced at read time. Don't reintroduce a block-as-document with a
+reference member — that model was removed deliberately: no block was ever
+reused, and it cost a hop on every read plus a second id to address.
+
 **A block is `defineBlock` + a registry entry.** Define the schema with
 `defineBlock` (`lib/integrations/sanity/schemas/shared/block.ts`), never
-`defineType` — it implies `type: "document"` and appends **Anchor ID** and
-**Presentation Mode** for you. Register the component in
+`defineType` — it implies `type: "object"` and appends **Anchor ID** and
+**Presentation Mode** for you. The array member's type name *is* the block's
+`_type`, so the registry, the insert menu and the fixture library all key off
+the same string. Register the component in
 `components/page-builder/registry.tsx`; the renderer is driven by that map, so
 there is no switch to extend.
 
@@ -33,10 +43,12 @@ that was never registered — is a typecheck error.
 drives the insert menu; `misc` only when nothing else fits). Never collapse them
 into one field: that is what made the menu a single flat list.
 
-**And a preview image.** The insert menu renders one tile per block from a
-`studioPreview` document (Components → Component Previews) keyed
-`block.<memberName>`. A block without one falls back to its schema icon, which
-is what made the old menu unreadable.
+**And a fixture.** A block isn't done until `components/page-builder/library.ts`
+has an entry for it: a stand-in value typed as the block's query result, plus a
+one-line note. That entry is the block's preview everywhere — the live pane in
+the insert menu, its row in Studio → Components, and the `/components` route,
+all rendered by the production renderer. Without one the picker just says the
+component has no preview.
 
 **Never hardcode vertical padding in a block component.** The renderer wraps
 each block in `<Section>` (`components/page-builder/section.tsx`), which owns

package/src/templates/next-pagebuilder/README.md

@@ -18,14 +18,18 @@ bun dev
 
 ## Page-builder blocks
 
-A block is two halves — a schema document and a React component — and each half
-has one place that makes it a block rather than an ordinary document or a loose
+A block is two halves — a schema type and a React component — and each half has
+one place that makes it a block rather than an ordinary object type or a loose
 component. Use them and Anchor ID, Presentation Mode and the spacing scale come
 for free.
 
+Blocks are **inline objects** in the page's `pageBuilder` array, never documents
+and never referenced: a placement belongs to exactly one page, so the block
+lives on that page and nothing is dereferenced at read time.
+
 **Define the schema with `defineBlock`, never `defineType`**
 (`lib/integrations/sanity/schemas/shared/block.ts`). It implies
-`type: "document"` and appends two fields to every block:
+`type: "object"` and appends two fields to every block:
 
 - **Anchor ID** — optional. Left empty, the anchor is generated from the block's
   own title at render time (`headline` / `heading` / `teaserHeading` / `title` /
@@ -54,6 +58,14 @@ block in `<Section>` (`components/page-builder/section.tsx`), which owns the
 component returns its content only — no outer `<section>`, no `py-*` / `pt-*` /
 `pb-*` on its root. Internal gaps between a block's own parts are fine.
 
+**Every block ships a fixture in `components/page-builder/library.ts`**: a
+stand-in value typed as the block's query result, plus a one-line note. It is
+the block's only preview, and it is rendered by the production renderer at
+`/components` — a route the Studio embeds in an iframe, so the insert menu and
+**Components** in the Studio show the real block rather than a screenshot. The
+route is gated to Studio embeds and `noindex`; a block with no entry simply has
+no preview.
+
 ### The spacing scale is content, not code
 
 Editors own it at **Layout → Spacing Scale**: a list of steps, each with a name

package/src/templates/next-pagebuilder/app/actions/unlock-gated-content.ts

@@ -10,13 +10,14 @@ export type UnlockResult =
   | { ok: true; payload: GatedContentPayload }
   | { ok: false; error: string }
 
-type UnlockInput = { documentId: string; email: string }
+type UnlockInput = { pageId: string; blockKey: string; email: string }
 
 export async function unlockGatedContent({
-  documentId,
+  pageId,
+  blockKey,
   email,
 }: UnlockInput): Promise<UnlockResult> {
-  if (!documentId) return { ok: false, error: "Missing content id." }
+  if (!(pageId && blockKey)) return { ok: false, error: "Missing content id." }
   if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
     return { ok: false, error: "Enter a valid email address." }
   }
@@ -27,7 +28,7 @@ export async function unlockGatedContent({
 
   const { data } = await fetchSanity<GATED_CONTENT_QUERY_RESULT>({
     query: GATED_CONTENT_QUERY,
-    params: { id: documentId },
+    params: { pageId, blockKey },
     // stega must stay off: it injects invisible characters into strings, which
     // would corrupt the asset URLs returned for download/playback.
     stega: false,

package/src/templates/next-pagebuilder/app/components/page.tsx

@@ -0,0 +1,81 @@
+import type { Metadata } from "next"
+import { notFound } from "next/navigation"
+import { SpacingScale } from "@/components/layout/spacing-scale"
+import {
+  COMPONENT_LIBRARY,
+  COMPONENT_PREVIEW_PARAM,
+  getLibraryEntry,
+  type LibraryEntry,
+} from "@/components/page-builder/library"
+import { Renderer } from "@/components/page-builder/renderer"
+import { Stage } from "@/components/page-builder/stage"
+import { isStudioEmbed } from "@/lib/utils/studio-embed"
+
+export const metadata: Metadata = {
+  title: "Components",
+  robots: { index: false, follow: false, nocache: true },
+}
+
+type Props = {
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}
+
+const firstValue = (value: string | string[] | undefined) =>
+  Array.isArray(value) ? value[0] : value
+
+const PREVIEW_PAGE_ID = "component-preview"
+
+const EntryHeader = ({ entry }: { entry: LibraryEntry }) => (
+  <header className="sticky top-0 z-10 flex items-baseline gap-3 border-neutral-200 border-b bg-white/85 px-6 py-3 backdrop-blur">
+    <h2 className="font-mono text-neutral-900 text-xs uppercase">
+      {entry.title}
+    </h2>
+    <p className="text-neutral-500 text-xs">{entry.notes}</p>
+  </header>
+)
+
+const PreviewStage = ({ entry }: { entry: LibraryEntry }) => (
+  <Stage background={entry.background}>
+    <Renderer
+      blocks={[entry.block]}
+      pageId={PREVIEW_PAGE_ID}
+      pinnedCategory={null}
+      searchParams={undefined}
+    />
+  </Stage>
+)
+
+const Page = async ({ searchParams }: Props) => {
+  const [params, embedded] = await Promise.all([searchParams, isStudioEmbed()])
+
+  if (!embedded) notFound()
+
+  const requested = firstValue(params[COMPONENT_PREVIEW_PARAM])
+  const entry = getLibraryEntry(requested)
+
+  if (requested && !entry) notFound()
+
+  // Outside the `(content)` group, so `<SpacingScale />` is on this route.
+  if (entry) {
+    return (
+      <main className="flex flex-col">
+        <SpacingScale />
+        <PreviewStage entry={entry} />
+      </main>
+    )
+  }
+
+  return (
+    <main className="flex flex-col">
+      <SpacingScale />
+      {COMPONENT_LIBRARY.map((item) => (
+        <section key={item.documentType}>
+          <EntryHeader entry={item} />
+          <PreviewStage entry={item} />
+        </section>
+      ))}
+    </main>
+  )
+}
+
+export default Page

package/src/templates/next-pagebuilder/components/page-builder/components/gated-content/index.tsx

@@ -13,14 +13,15 @@ type GatedContentBlock = Extract<PageBuilderBlock, { _type: "gatedContent" }>
 
 type GatedContentProps = {
   block: GatedContentBlock
+  pageId: string
 }
 
 type GateState = "locked" | "loading" | "unlocked"
 
 const STORAGE_PREFIX = "gated-content:"
 
-export function GatedContent({ block }: GatedContentProps) {
-  const storageKey = `${STORAGE_PREFIX}${block._id}`
+export function GatedContent({ block, pageId }: GatedContentProps) {
+  const storageKey = `${STORAGE_PREFIX}${pageId}:${block._key}`
   const [state, setState] = useState<GateState>("locked")
   const [payload, setPayload] = useState<GatedContentPayload | null>(null)
   const [error, setError] = useState<string | null>(null)
@@ -33,7 +34,11 @@ export function GatedContent({ block }: GatedContentProps) {
     setState("loading")
     setError(null)
 
-    const result = await unlockGatedContent({ documentId: block._id, email })
+    const result = await unlockGatedContent({
+      pageId,
+      blockKey: block._key,
+      email,
+    })
 
     if (!result.ok) {
       setError(result.error)

package/src/templates/next-pagebuilder/components/page-builder/library.ts

@@ -0,0 +1,183 @@
+import type { PageBuilderDocumentType } from "@/lib/integrations/sanity/page-builder-config"
+import type { PageBuilderBlock } from "./types"
+
+/** One block's stand-in value, rendered by `/components` through `Renderer`. */
+export type LibraryEntry = {
+  documentType: PageBuilderDocumentType
+  title: string
+  notes: string
+  background: string
+  block: PageBuilderBlock
+}
+
+type BlockOf<T extends PageBuilderDocumentType> = Extract<
+  PageBuilderBlock,
+  { _type: T }
+>
+
+const span = (key: string, text: string) => ({
+  _type: "span" as const,
+  _key: key,
+  text,
+  marks: [],
+})
+
+const paragraph = (key: string, text: string) => ({
+  _type: "block" as const,
+  _key: key,
+  style: "normal" as const,
+  markDefs: [],
+  children: [span(`${key}-span`, text)],
+})
+
+const heading = (key: string, text: string) => ({
+  ...paragraph(key, text),
+  style: "h2" as const,
+})
+
+const PLACEHOLDER_KEY = "placeholder"
+
+const hero: BlockOf<"hero"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "hero",
+  headline: "A heading that says what this page is for.",
+}
+
+const description: BlockOf<"description"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "description",
+  description:
+    "One paragraph of standfirst copy under a heading — long enough to set up the page, short enough that nobody skips it.",
+}
+
+const richTextBlock: BlockOf<"richTextBlock"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "richTextBlock",
+  content: [
+    heading("rt-head", "What long-form copy looks like here"),
+    paragraph(
+      "rt-one",
+      "Rich Text is the block for body copy: headings, paragraphs, lists, links and quotes, all authored in the Studio and rendered with the site's own typography."
+    ),
+    paragraph(
+      "rt-two",
+      "Because it is Portable Text rather than HTML, the same content renders in the page, in the markdown route and in the feed without a second template."
+    ),
+  ],
+}
+
+const gatedContent: BlockOf<"gatedContent"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "gatedContent",
+  internalTitle: "Gated guide",
+  teaserHeading: "A guide worth an email address",
+  teaserBody: [
+    paragraph(
+      "gc-teaser",
+      "The teaser is public. The payload — rich text, a file or a video — is withheld from the page query until a visitor submits the form."
+    ),
+  ],
+  gateType: "form",
+  gateHeadline: "Read the full guide",
+  gateDescription: "We'll email you a copy as well.",
+  submitLabel: "Get the guide",
+  successMessage: "Sent — it's on its way.",
+  kind: "richText",
+  anchorId: null,
+  presentation: null,
+}
+
+const blogCollection: BlockOf<"blogCollection"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "blogCollection",
+  subtitle: "Everything else we've written",
+}
+
+const blogContent: BlockOf<"blogContent"> = {
+  _key: PLACEHOLDER_KEY,
+  _type: "blogContent",
+  title: "How this starter renders a blog post",
+  categories: [],
+  date: "2026-02-11",
+  author: {
+    _id: "placeholder-author",
+    name: "Jane Doe",
+    avatar: null,
+    role: "Engineer",
+  },
+  body: [
+    paragraph(
+      "bc-one",
+      "A blog post is an ordinary page whose page builder holds a Blog Posts block: byline, date, categories and body all live on the block."
+    ),
+    heading("bc-head", "One block, one article"),
+    paragraph(
+      "bc-two",
+      "The collection block reads the same fields, so an article added in the Studio shows up in the index without touching code."
+    ),
+  ],
+  relatedPosts: [],
+}
+
+export const COMPONENT_LIBRARY: LibraryEntry[] = [
+  {
+    documentType: "hero",
+    title: "Heading",
+    notes: "The page's opening statement. Headline only, no media.",
+    background: "bg-white",
+    block: hero,
+  },
+  {
+    documentType: "description",
+    title: "Description",
+    notes: "A single paragraph of standfirst copy under a heading.",
+    background: "bg-white",
+    block: description,
+  },
+  {
+    documentType: "richTextBlock",
+    title: "Rich Text",
+    notes: "Long-form body copy — headings, lists, links and quotes.",
+    background: "bg-white",
+    block: richTextBlock,
+  },
+  {
+    documentType: "gatedContent",
+    title: "Gated Content",
+    notes:
+      "A teaser with an email gate. The payload is withheld until a visitor submits, so the preview shows the locked state.",
+    background: "bg-white",
+    block: gatedContent,
+  },
+  {
+    documentType: "blogCollection",
+    title: "Blog Collection",
+    notes:
+      "The full article index with search and category filters. Reads real posts.",
+    background: "bg-white",
+    block: blogCollection,
+  },
+  {
+    documentType: "blogContent",
+    title: "Blog Posts",
+    notes:
+      "The body of an article — byline, date, categories and rich text. Only valid on a blog entry page.",
+    background: "bg-white",
+    block: blogContent,
+  },
+]
+
+export const getLibraryEntry = (documentType: string | undefined) =>
+  documentType
+    ? (COMPONENT_LIBRARY.find((entry) => entry.documentType === documentType) ??
+      null)
+    : null
+
+export const COMPONENT_PREVIEW_PATH = "/components"
+
+export const COMPONENT_PREVIEW_PARAM = "component"
+
+export const getComponentPreviewPath = (documentType?: string) =>
+  documentType
+    ? `${COMPONENT_PREVIEW_PATH}?${COMPONENT_PREVIEW_PARAM}=${encodeURIComponent(documentType)}`
+    : COMPONENT_PREVIEW_PATH

package/src/templates/next-pagebuilder/components/page-builder/registry.tsx

@@ -13,6 +13,7 @@ import { RichTextBlock } from "./components/rich-text-block"
 import type { PageBuilderBlock } from "./types"
 
 export type BlockContext = {
+  pageId: string
   searchParams: ContentCollectionSearchParams
   pinnedCategory: PinnedCollectionCategory
 }
@@ -48,7 +49,9 @@ const blockRegistry: {
     isEmpty: (block) => !block.description,
   },
   gatedContent: {
-    render: (block) => <GatedContent block={block} />,
+    render: (block, { pageId }) => (
+      <GatedContent block={block} pageId={pageId} />
+    ),
   },
   hero: {
     render: (block) => <Hero block={block} />,

package/src/templates/next-pagebuilder/components/page-builder/renderer.tsx

@@ -12,18 +12,20 @@ import type { PageBuilderBlock, PageBuilderBlocks } from "./types"
 
 type RendererProps = {
   blocks: PageBuilderBlocks
+  pageId: string
   searchParams: ContentCollectionSearchParams
   pinnedCategory: PinnedCollectionCategory
 }
 
 export function Renderer({
   blocks,
+  pageId,
   searchParams,
   pinnedCategory,
 }: RendererProps) {
   if (!blocks?.length) return null
 
-  const context: BlockContext = { searchParams, pinnedCategory }
+  const context: BlockContext = { pageId, searchParams, pinnedCategory }
 
   const reservedAnchorIds = reserveAnchorIds(blocks)
   const takenAnchorIds = new Set<string>()

package/src/templates/next-pagebuilder/components/page-builder/stage.tsx

@@ -0,0 +1,10 @@
+import type { PropsWithChildren } from "react"
+import { cn } from "@/lib/styles/cn"
+
+type StageProps = PropsWithChildren<{ background?: string }>
+
+export const Stage = ({ background, children }: StageProps) => (
+  <div className={cn("grid min-h-svh content-center", background)}>
+    {children}
+  </div>
+)

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

@@ -31,6 +31,7 @@ export const getPageSections = (
         <Renderer
           key="page-builder"
           blocks={page.pageBuilder}
+          pageId={page._id}
           searchParams={searchParams}
           pinnedCategory={stegaClean(page.collectionCategory)}
         />,