bsmnt 0.10.0 → 0.11.0

package/src/templates/next-experiments/components/ui/image/index.tsx

@@ -9,8 +9,7 @@
 import cn from "clsx"
 import NextImage, { type ImageProps as NextImageProps } from "next/image"
 import type { CSSProperties, Ref } from "react"
-
-const DESKTOP_BREAKPOINT = 1440
+import { buildImageSizes } from "@/lib/utils/image-sizes"
 
 /**
  * Enhanced Image component props extending Next.js Image.
@@ -167,8 +166,7 @@ export function Image({
 }: ImageProps) {
   // Generate responsive sizes if not provided
   const finalSizes =
-    sizes ||
-    `(max-width: ${DESKTOP_BREAKPOINT}px) ${mobileSize}, ${desktopSize}`
+    sizes || buildImageSizes({ base: mobileSize, desktop: desktopSize })
 
   // Early return after hooks
   if (!src) return null

package/src/templates/next-experiments/knip.json

@@ -20,5 +20,5 @@
     "zustand"
   ],
   "ignoreBinaries": ["op", "gh", "vercel"],
-  "ignoreFiles": [".agents/**", ".claude/**", "hooks/**"]
+  "ignoreFiles": [".agents/**", ".claude/**", "hooks/**", "lib/integrations/hubspot/**"]
 }

package/src/templates/next-experiments/lefthook.yml

@@ -11,7 +11,7 @@ pre-commit:
       stage_fixed: true
     typecheck:
       glob: '*.{ts,tsx}'
-      run: bunx tsgo --noEmit --incremental false
+      run: bunx tsc --noEmit --incremental false
       stage_fixed: false
 
 post-merge:

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

@@ -5,10 +5,12 @@ Pure utility functions organized by concern.
 Use explicit imports for clarity and better tree-shaking:
 
 ```tsx
-import { clamp, lerp, mapRange } from '@/utils/math'
-import { slugify } from '@/utils/strings'
-import { generatePageMetadata } from '@/utils/metadata'
-import { tovw, torem, toem } from '@/utils/viewport'
+import { clamp, lerp, mapRange } from '@/lib/utils/math'
+import { slugify } from '@/lib/utils/strings'
+import { generatePageMetadata } from '@/lib/utils/metadata'
+import { tovw, torem, toem } from '@/lib/utils/viewport'
+import { buildImageSizes, buildGridImageSizes } from '@/lib/utils/image-sizes'
+import { useMergeRefs } from '@/lib/utils/merge-refs'
 ```
 
 ## Modules
@@ -18,8 +20,10 @@ import { tovw, torem, toem } from '@/utils/viewport'
 | `math` | `clamp`, `lerp`, `mapRange`, `modulo`, `normalize`, `distance` |
 | `easings` | All easing functions (`easeOutCubic`, etc.) |
 | `viewport` | `tovw`, `torem`, `toem` |
-| `strings` | `slugify`, `mergeRefs`, `capitalizeFirstLetter` |
+| `strings` | `slugify`, `capitalizeFirstLetter`, `twoDigits`, `numberWithCommas` |
 | `metadata` | `generatePageMetadata` |
+| `image-sizes` | `buildImageSizes`, `buildGridImageSizes` |
+| `merge-refs` | `mergeRefs`, `useMergeRefs`, `assignRef` |
 
 ## Common Patterns
 
@@ -37,4 +41,13 @@ toem(16, 14) // → "1.14em"
 
 // SEO
 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 })
+
+// Refs — in a component, use the hook: an inline mergeRefs([...]) is a new
+// callback each render, so React detaches and reattaches every ref.
+const mergedRef = useMergeRefs([localRef, ref])
+return <input ref={mergedRef} />
 ```

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

@@ -0,0 +1,72 @@
+/** Mirrors the theme's `--breakpoint-*` scale, which clears Tailwind's defaults. */
+export const BASEMENT_BREAKPOINTS = {
+  mobile: 640,
+  tablet: 768,
+  "tablet-lg": 1024,
+  desktop: 1440,
+  "desktop-large": 1920,
+} as const
+
+export type BreakpointMap = Readonly<Record<string, number>>
+
+/** Mirrors the element's variants: `grid-cols-1 tablet:grid-cols-2` → `{ base: 1, tablet: 2 }`. */
+export type ByBreakpoint<
+  T,
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
+
+function columnWidth(columns: number): string {
+  return `${Math.round(100 / columns)}vw`
+}
+
+/**
+ * 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}`)
+    }
+  }
+
+  return [...conditions, 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 {
+  const { base, ...overrides } = widths
+  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+}
+
+/**
+ * Builds `sizes` from a grid's column count per breakpoint. Rounded: `sizes`
+ * only steers which srcset candidate the browser picks, and gaps make the real
+ * column narrower than `100 / N` anyway.
+ */
+export function buildGridImageSizes<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+>(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+  const { base, ...overrides } = columns
+  const widths: Record<string, string> = {}
+
+  for (const [name, count] of Object.entries(overrides)) {
+    if (count !== undefined) {
+      widths[name] = columnWidth(count)
+    }
+  }
+
+  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+}

package/src/templates/next-experiments/lib/utils/merge-refs.ts

@@ -0,0 +1,56 @@
+import { type Ref, type RefCallback, useRef } from "react"
+
+/** Returns the ref's own cleanup callback when it provides one (React 19). */
+export function assignRef<T>(
+  ref: Ref<T> | undefined,
+  value: T | null
+): ReturnType<RefCallback<T>> {
+  if (typeof ref === "function") {
+    return ref(value)
+  }
+  if (ref) {
+    ref.current = value
+  }
+  return undefined
+}
+
+/** Merges object/callback refs into one callback ref, with React 19 ref cleanup. */
+export function mergeRefs<T>(refs: (Ref<T> | undefined)[]): RefCallback<T> {
+  return (value) => {
+    const cleanups = refs.map((ref) => {
+      const cleanup = assignRef(ref, value)
+      return typeof cleanup === "function"
+        ? cleanup
+        : () => assignRef(ref, null)
+    })
+    return () => {
+      for (const cleanup of cleanups) {
+        cleanup()
+      }
+    }
+  }
+}
+
+/**
+ * Memoized {@link mergeRefs}, stable across renders for the same ref list.
+ * Compares the list here rather than passing it as `useMemo` deps: React only
+ * compares the common prefix, so a list that grows or shrinks would silently
+ * reuse the old callback and leave a ref unattached or stale.
+ */
+export function useMergeRefs<T>(refs: (Ref<T> | undefined)[]): RefCallback<T> {
+  const cache = useRef<{
+    refs: (Ref<T> | undefined)[]
+    merged: RefCallback<T>
+  } | null>(null)
+
+  if (
+    !cache.current ||
+    cache.current.refs.length !== refs.length ||
+    cache.current.refs.some((ref, i) => ref !== refs[i])
+  ) {
+    // Snapshot: a caller may hand us a persistent array it mutates in place.
+    cache.current = { refs: [...refs], merged: mergeRefs(refs) }
+  }
+
+  return cache.current.merged
+}

package/src/templates/next-experiments/lib/utils/strings.ts

@@ -1,11 +1,9 @@
 /**
  * String & Object Utilities
  *
- * Helper functions for string manipulation, object operations, and refs.
+ * Helper functions for string manipulation and object operations.
  */
 
-import type { Ref } from "react"
-
 // =============================================================================
 // STRING UTILITIES
 // =============================================================================
@@ -196,51 +194,3 @@ export function iterableObject(
     return value
   })
 }
-
-// =============================================================================
-// REF UTILITIES
-// =============================================================================
-
-/**
- * Merges multiple React refs into a single ref callback.
- *
- * Useful when you need to assign multiple refs to the same element,
- * such as combining a local ref with a forwarded ref.
- *
- * @param refs - Refs to merge (functions and ref objects supported)
- * @returns A ref callback that updates all provided refs
- *
- * @example
- * ```tsx
- * // Component that needs both local and forwarded ref
- * function MyComponent({ ref }: { ref: React.Ref<HTMLDivElement> }) {
- *   const localRef = useRef<HTMLDivElement>(null)
- *   const mergedRef = mergeRefs(localRef, ref)
- *
- *   return <div ref={mergedRef}>Content</div>
- * }
- *
- * // Forward ref pattern
- * const ForwardedComponent = forwardRef(MyComponent)
- * ```
- */
-export function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): Ref<T> {
-  return (value) => {
-    const cleanups = refs.reduce<VoidFunction[]>((accumulator, ref) => {
-      if (typeof ref === "function") {
-        const cleanup = ref(value)
-        if (typeof cleanup === "function") {
-          accumulator.push(cleanup)
-        }
-      } else if (ref) {
-        ref.current = value
-      }
-
-      return accumulator
-    }, [])
-
-    return () => {
-      for (const cleanup of cleanups) cleanup()
-    }
-  }
-}

package/src/templates/next-experiments/next.config.ts

@@ -5,9 +5,8 @@ const nextConfig: NextConfig = {
   reactStrictMode: true,
   reactCompiler: true,
   typedRoutes: true,
-  // Bundle the committed encrypted env files into serverless functions so
-  // instrumentation.ts can decrypt them at runtime. .env.keys is never listed
-  // (and is git/vercel-ignored); missing files are skipped.
+  // Bundle the committed encrypted env files so instrumentation.ts can decrypt
+  // them at runtime. `.env.keys` is never listed; missing files are skipped.
   outputFileTracingIncludes: {
     "/**": ["./.env", "./.env.production", "./.env.preview"],
   },

package/src/templates/next-experiments/package.json

@@ -22,9 +22,7 @@
     "lint:fix": "biome check --write --unsafe --max-diagnostics=200",
     "prepare": "lefthook install",
     "start": "next start",
-    "typecheck": "tsgo --noEmit",
-    "typecheck:compare": "bun run typecheck:tsc && bun run typecheck",
-    "typecheck:tsc": "tsc --noEmit --incremental false"
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@radix-ui/react-navigation-menu": "^1.2.5",
@@ -47,7 +45,6 @@
     "@types/node": "^24.13.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@typescript/native-preview": "^7.0.0-dev.20260323.1",
     "babel-plugin-react-compiler": "^1.0.0",
     "cross-env": "^10.1.0",
     "knip": "^6.16.1",
@@ -55,7 +52,7 @@
     "postcss-preset-env": "^10.6.1",
     "schema-dts": "^2.0.0",
     "tailwindcss": "^4.2.2",
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.2"
   },
   "trustedDependencies": [
     "@biomejs/biome",

package/src/templates/next-pagebuilder/.env.example

@@ -35,5 +35,6 @@ DRAFT_MODE_TOKEN=
 # Sanity CMS
 NEXT_PUBLIC_SANITY_PROJECT_ID=
 NEXT_PUBLIC_SANITY_DATASET=production
+NEXT_PUBLIC_SANITY_API_VERSION=2025-02-19
 SANITY_API_READ_TOKEN=
 SANITY_REVALIDATE_SECRET=

package/src/templates/next-pagebuilder/.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
         run: bun install --frozen-lockfile
 
       - name: Type check
-        run: bun run typecheck:compare
+        run: bun run typecheck
 
       - name: Lint
         run: bun run lint

package/src/templates/next-pagebuilder/.vscode/settings.json

@@ -58,7 +58,6 @@
 
   // General
   "files.eol": "\n",
-  // "typescript.experimental.useTsgo": true, // Disabled: tsgo doesn't support Next.js plugin
   "javascript.suggest.autoImports": true,
   // Disable Prettier to prevent silent formatter conflicts
   "prettier.enable": false,
@@ -90,7 +89,6 @@
 
   // TypeScript
   "typescript.suggest.autoImports": true,
-  "typescript.tsdk": "node_modules/typescript/lib",
 
   // Editor labels (fixed for .tsx files)
   "workbench.editor.customLabels.patterns": {

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

@@ -95,6 +95,70 @@ for *any* framing failure, including a wrong registered URL with already-correct
 headers. Trust the browser console's `Framing '<url>' violates …` line instead —
 it names the URL actually being framed.
 
+## Content invalidation (publish webhook) — required
+
+Cached content is cleared on publish by `app/api/revalidate/route.ts`, which only
+runs if a Sanity webhook calls it. **Until you create that webhook, published
+changes won't appear on the deployed site until its cache entries expire.**
+
+`SANITY_REVALIDATE_SECRET` is generated for you during `bsmnt create` (see your
+env file). The webhook itself is manual, because the deployed URL isn't known at
+scaffold time. Once deployed, in **sanity.io/manage → API → Webhooks → Create**:
+
+| Field | Value |
+| --- | --- |
+| URL | `https://<your-domain>/api/revalidate` |
+| Dataset | `production` |
+| Trigger on | Create, Update, Delete |
+| Filter | leave empty (the route decides what to invalidate) |
+| Projection | see below — the route needs `operation` and `before()` |
+| HTTP method | `POST` |
+| API version | `v2021-03-25` or later |
+| Secret | the `SANITY_REVALIDATE_SECRET` value from your env |
+
+The projection is not optional: the route reads `operation` and the pre-delete
+document to invalidate a removed page, and neither is in the default payload.
+
+```groq
+{
+  "_id": _id,
+  "_type": _type,
+  "operation": delta::operation(),
+  "before": before(),
+  "after": after()
+}
+```
+
+Make sure the same secret is set in your hosting provider's environment, not just
+locally. To check it end to end: publish a change in the Studio, then reload the
+affected page — it should update without a redeploy. Close any other tab on the
+site first: in draft mode `<SanityLive>` refreshes the router on its own, which can
+make a broken webhook look like it works.
+
+**sanity.io/manage → API → Webhooks → your webhook → Delivery log** is where to
+check. A 401 means the secret doesn't match; repeated 5xx means the route is
+erroring; no attempts at all means the filter or dataset is wrong.
+
+### Why every route here is cached
+
+`sanityFetch` from `next-sanity`'s `defineLive` issues **two** Sanity requests per
+call: an uncached probe for the Live API's sync tags, then the real query with
+`next: { revalidate: false, tags }`. Only the second is cached, so a route that
+renders per request pays a Sanity round trip on every hit no matter what the Data
+Cache holds.
+
+That is why nothing in this template sets `dynamic = "force-dynamic"` — including
+`/sitemap.xml`, `/sitemap.md` and `/feed.xml`, which are crawler-driven and used
+to. With the route output cached, the probe runs when a route revalidates rather
+than when someone visits it.
+
+The exception is server actions, which by definition run per invocation:
+`unlockGatedContent` costs two Sanity requests per form submission. If you add
+actions that read Sanity on a hot path, read through `client.fetch` directly
+rather than `sanityFetch` — but note that `client.fetch` does not resolve the
+draft-mode perspective from cookies, so an editor previewing drafts would see
+published content unless you thread that through yourself.
+
 ## Continuous Integration
 
 A GitHub Actions workflow (`.github/workflows/ci.yml`) runs on every pull request to `main` and on pushes to `main`. It runs type checking, linting, the production build, tests, and `knip`.

package/src/templates/next-pagebuilder/app/sitemap.xml/route.ts

@@ -3,7 +3,9 @@ import { isSanityConfigured } from "@/lib/integrations/check-integration"
 import type { PAGE_SITEMAP_QUERY_RESULT } from "@/lib/integrations/sanity/sanity.types"
 import { getPageUrl, getSitemap, getSitemapBaseUrl } from "@/lib/utils/sitemap"
 
-export const dynamic = "force-dynamic"
+// Not `force-dynamic`: per-request rendering meant a Sanity round trip per crawler
+// hit. No `Cache-Control` either — a CDN copy is a second cache the webhook
+// can't purge.
 
 type PageDoc = PAGE_SITEMAP_QUERY_RESULT[number]
 

package/src/templates/next-pagebuilder/biome.json

@@ -35,7 +35,8 @@
       "!**/*.md",
       "!**/*.mdx",
       "!**/tailwind.css",
-      "!**/*.grit"
+      "!**/*.grit",
+      "!**/sanity.types.ts"
     ]
   },
   "formatter": {

package/src/templates/next-pagebuilder/components/layout/footer/index.tsx

@@ -3,8 +3,7 @@ import { SanityImage } from "@/components/ui/sanity-image"
 import {
   type CompanyData,
   type FooterData,
-  getCompanyData,
-  getFooterData,
+  getLayoutData,
 } from "@/lib/integrations/sanity/fetchers/layout"
 
 type FooterLinkGroup = NonNullable<FooterData["links"]>[number]
@@ -12,10 +11,8 @@ type FooterLinkItem = NonNullable<FooterLinkGroup["items"]>[number]
 type SocialLink = NonNullable<CompanyData["socialLinks"]>[number]
 
 export const Footer = async () => {
-  const [footer, companyData] = await Promise.all([
-    getFooterData(),
-    getCompanyData(),
-  ])
+  // Shares one request-scoped fetch with the header and json-ld.
+  const { footer, companyData } = await getLayoutData()
 
   const links = footer?.links ?? []
 

package/src/templates/next-pagebuilder/components/layout/header/index.tsx

@@ -1,8 +1,9 @@
-import { getNavbarData } from "@/lib/integrations/sanity/fetchers/layout"
+import { getLayoutData } from "@/lib/integrations/sanity/fetchers/layout"
 import { HeaderClient } from "./header-client"
 
 export const Header = async () => {
-  const navbar = await getNavbarData()
+  // Shares one request-scoped fetch with the footer and json-ld.
+  const { navbar } = await getLayoutData()
 
   return <HeaderClient data={navbar} />
 }

package/src/templates/next-pagebuilder/components/layout/json-ld/index.tsx

@@ -1,8 +1,5 @@
 import { stegaClean } from "next-sanity"
-import {
-  getNavbarData,
-  getStructuredData,
-} from "@/lib/integrations/sanity/fetchers/layout"
+import { getLayoutData } from "@/lib/integrations/sanity/fetchers/layout"
 import {
   generateOrganizationJsonLd,
   generateWebSiteJsonLd,
@@ -13,10 +10,8 @@ const nonEmpty = (value: unknown): string | undefined =>
   typeof value === "string" && value.trim() !== "" ? value : undefined
 
 export const JsonLd = async () => {
-  const [structuredData, navbar] = await Promise.all([
-    getStructuredData(),
-    getNavbarData(),
-  ])
+  // Shares one request-scoped fetch with the header and footer.
+  const { structuredData, navbar } = await getLayoutData()
 
   // Deep-clean stega artifacts before any value reaches the emitted markup.
   const data = stegaClean(structuredData)

package/src/templates/next-pagebuilder/components/page-builder/components/content-collection/content-filters.tsx

@@ -1,29 +1,30 @@
-"use client"
-
-import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { Link } from "@/components/ui/link"
 import { cn } from "@/lib/styles/cn"
 import type { ContentCategory } from "./types"
 
 type ContentFiltersProps = {
   categories: ContentCategory[]
   activeCategory: string
-  totalCount: number
-  filteredCount: number
+  count: number
+  /** Category slug → the page pinned to it. Categories without one are omitted. */
+  categoryHrefs: Record<string, string>
+  /** Where "All content" goes. */
+  indexHref: string
 }
 
 function FilterChip({
   active,
   label,
-  onClick,
+  href,
 }: {
   active: boolean
   label: string
-  onClick: () => void
+  href: string
 }) {
   return (
-    <button
-      type="button"
-      onClick={onClick}
+    <Link
+      href={href}
+      aria-current={active ? "page" : undefined}
       className={cn(
         "rounded-full border px-4 py-2 text-sm transition-colors",
         active
@@ -32,61 +33,43 @@ function FilterChip({
       )}
     >
       {label}
-    </button>
+    </Link>
   )
 }
 
 export function ContentFilters({
   categories,
   activeCategory,
-  totalCount,
-  filteredCount,
+  count,
+  categoryHrefs,
+  indexHref,
 }: ContentFiltersProps) {
-  const pathname = usePathname()
-  const router = useRouter()
-  const searchParams = useSearchParams()
-
-  const navigate = (category: string) => {
-    const nextParams = new URLSearchParams(searchParams.toString())
-
-    if (category) nextParams.set("category", category)
-    else nextParams.delete("category")
-
-    nextParams.delete("page")
-
-    const href = nextParams.toString()
-      ? `${pathname}?${nextParams.toString()}`
-      : pathname
-
-    // biome-ignore lint/suspicious/noExplicitAny: typed routes do not accept dynamic query string helpers cleanly
-    router.push(href as any, { scroll: false })
-  }
-
   return (
     <div className="flex flex-col gap-4 rounded-[1.5rem] border border-black/10 bg-black/[0.02] p-4 sm:p-5">
-      <div className="flex flex-wrap gap-2">
+      <nav aria-label="Filter by category" className="flex flex-wrap gap-2">
         <FilterChip
           active={activeCategory === ""}
           label="All content"
-          onClick={() => navigate("")}
+          href={indexHref}
         />
         {categories.map((category) => {
           const slug = category.slug?.current
-          if (!slug) return null
+          const href = slug ? categoryHrefs[slug] : undefined
+          // A category with no page of its own has nowhere to link to.
+          if (!slug || !href) return null
 
           return (
             <FilterChip
               key={category._id}
               active={activeCategory === slug}
               label={category.title || "Untitled"}
-              onClick={() => navigate(slug)}
+              href={href}
             />
           )
         })}
-      </div>
+      </nav>
       <p className="text-current/60 text-sm">
-        Showing {filteredCount} {filteredCount === 1 ? "item" : "items"}
-        {filteredCount !== totalCount ? ` out of ${totalCount}` : ""}
+        Showing {count} {count === 1 ? "item" : "items"}
       </p>
     </div>
   )