bsmnt 0.9.0 → 0.11.0

package/src/templates/next-pagebuilder/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-pagebuilder/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-pagebuilder/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"],
   },
@@ -68,7 +67,6 @@ const nextConfig: NextConfig = {
     browserToTerminal: true,
   },
   experimental: {
-    prefetchInlining: true,
     optimizePackageImports: [
       "@react-three/drei",
       "@react-three/fiber",
@@ -94,7 +92,8 @@ const nextConfig: NextConfig = {
   },
   headers: async () => [
     {
-      source: "/(.*)",
+      // Excludes /studio* — must stay mutually exclusive with the rule below.
+      source: "/((?!studio(?:/|$)).*)",
       headers: [
         {
           key: "X-Content-Type-Options",
@@ -126,6 +125,37 @@ const nextConfig: NextConfig = {
         },
       ],
     },
+    {
+      // X-Frame-Options can't allow a third-party origin, and Next can't unset
+      // it from another rule — the iframe needs it absent, not overridden.
+      source: "/studio/:path*",
+      headers: [
+        {
+          key: "X-Content-Type-Options",
+          value: "nosniff",
+        },
+        {
+          key: "Content-Security-Policy",
+          value: "frame-ancestors 'self' https://*.sanity.io;",
+        },
+        {
+          key: "X-XSS-Protection",
+          value: "1; mode=block",
+        },
+        {
+          key: "X-DNS-Prefetch-Control",
+          value: "on",
+        },
+        {
+          key: "Strict-Transport-Security",
+          value: "max-age=63072000; includeSubDomains; preload",
+        },
+        {
+          key: "Permissions-Policy",
+          value: "camera=(), microphone=(), geolocation=()",
+        },
+      ],
+    },
   ],
 }
 

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

@@ -21,16 +21,14 @@
     "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",
     "update:packages": "cross-env NPM_CHECK_INSTALLER=bun bunx npm-check -u"
   },
   "dependencies": {
     "class-variance-authority": "^0.7.1",
-    "next": "^16",
-    "react": "^19",
-    "react-dom": "^19",
+    "next": "^16.3.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "react-use": "^17.6.0",
     "tailwind-merge": "^3.5.0",
     "zod": "^4.3.6"
@@ -38,14 +36,13 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
     "@csstools/postcss-global-data": "^4.0.0",
-    "@next/bundle-analyzer": "^16.2.1",
+    "@next/bundle-analyzer": "^16.3.0",
     "@svgr/webpack": "^8.1.0",
     "@tailwindcss/postcss": "^4.2.2",
     "@types/bun": "^1.3.11",
     "@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",
@@ -53,12 +50,13 @@
     "postcss-functions": "^4.0.2",
     "postcss-preset-env": "^11.2.0",
     "tailwindcss": "^4.2.2",
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.2"
   },
   "trustedDependencies": [
     "@biomejs/biome",
     "@tailwindcss/oxide",
     "esbuild",
     "sharp"
-  ]
+  ],
+  "browserslist": "extends @sanity/browserslist-config"
 }

package/src/templates/next-pagebuilder-cache/.biome/plugins/README.md

@@ -0,0 +1,21 @@
+## Plugins
+
+### 1. `no-anchor-element.grit`
+Enforces using Next.js `<Link>` component instead of HTML `<a>` elements.
+
+### 2. `no-unnecessary-forwardref.grit`
+Checks for unnecessary `forwardRef` usage in React 19 with the compiler.
+
+### 3. `no-relative-parent-imports.grit`
+Forbids relative parent imports (`../`) and encourages alias imports (`@/`).
+
+## Plugin Configuration
+
+The plugins are configured in `biome.json`:
+```json
+"plugins": [
+  "./biome-plugins/no-anchor-element.grit",
+  "./biome-plugins/no-unnecessary-forwardref.grit",
+  "./biome-plugins/no-relative-parent-imports.grit"
+]
+``` 

package/src/templates/next-pagebuilder-cache/.biome/plugins/no-anchor-element.grit

@@ -0,0 +1,12 @@
+language js;
+
+`<a $attrs>$content</a>` as $anchor where {
+    !$anchor <: within `if ($condition) { return ($jsx) }` where {
+        $condition <: contains or { `isExternal`, `isExternalSSR` }
+    },
+    register_diagnostic(
+        span = $anchor,
+        message = "Use custom Link component instead of <a> element. The Link component handles both internal and external links automatically.",
+        severity = "error"
+    )
+} 

package/src/templates/next-pagebuilder-cache/.biome/plugins/no-relative-parent-imports.grit

@@ -0,0 +1,10 @@
+language js;
+
+`import $imports from $source` as $import where {
+    $source <: r"['\"]\.\.\/\.\.\/.*['\"]",
+    register_diagnostic(
+        span = $import,
+        message = "Use alias imports (~/dir/) instead of deep relative imports (../../). Single level imports (../) are allowed for colocated files.",
+        severity = "error"
+    )
+} 

package/src/templates/next-pagebuilder-cache/.biome/plugins/no-unnecessary-forwardref.grit

@@ -0,0 +1,9 @@
+language js;
+
+`forwardRef($func)` as $ref where {
+    register_diagnostic(
+        span = $ref,
+        message = "forwardRef is unnecessary in React 19 with the compiler",
+        severity = "warning"
+    )
+} 

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

@@ -0,0 +1,40 @@
+# ============================================
+# Basement Next Starter - Environment Variables
+# ============================================
+# bsmnt:if dotenvx
+# This project uses dotenvx (https://dotenvx.com): the committed `.env` holds
+# shared values, with secrets encrypted there. The private keys live in
+# `.env.keys` (gitignored) — restore them with `bun run env:setup`.
+#
+# Add or change a variable in `.env` (not .env.local):
+#   - Secret (API key, token, …):  bun run env:set KEY value   (--preview / --prod)
+#   - Trivial / NEXT_PUBLIC_*:      bun run env:set KEY value --plain
+#   - Bulk-encrypt a file edited by hand:  bun run env:encrypt-all  (--preview / --prod)
+#
+# Edge runtime (middleware, `runtime = "edge"`): dotenvx can't decrypt there.
+# Set any secret those read directly in Vercel's env vars, not here.
+#
+# This file just documents the available variables; real values live in `.env`.
+# ============================================
+# bsmnt:endif
+# bsmnt:if !dotenvx
+# Copy this file to `.env.local` and fill in the values you need.
+# `.env.local` is gitignored, so real values stay off version control.
+# Only NEXT_PUBLIC_* variables are exposed to the browser.
+# ============================================
+# bsmnt:endif
+
+# Base URL
+# Inlined at build time — scope this to the Production environment only in
+# Vercel so Preview deployments fall through to VERCEL_PROJECT_PRODUCTION_URL.
+NEXT_PUBLIC_BASE_URL=
+
+# Draft Mode
+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-cache/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Changes
+
+- 
+
+## Checklist
+
+- [ ] `bun lint` passes
+- [ ] Tested locally in dev mode
+- [ ] No breaking changes (or documented in summary)

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

@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Node version is read from .nvmrc — the single source of truth.
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+
+      # Bun version is read from package.json's "packageManager" field — the
+      # single source of truth. Do NOT pin a version here, or the two can drift.
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      # Cache Bun's global install cache so dependencies aren't re-downloaded
+      # on every run. Keyed on the lockfile so it busts when deps change.
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Type check
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      # bsmnt:if dotenvx
+      # dotenvx needs the private key to decrypt secrets at build time. It's
+      # pulled from 1Password via an org-wide service-account token + the op-ref
+      # committed in .env. Optional: builds pass without it (only plaintext /
+      # NEXT_PUBLIC_* is read), and a per-repo DOTENV_PRIVATE_KEY secret still
+      # works as a fallback.
+      - name: Install 1Password CLI
+        if: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN != '' }}
+        uses: 1password/install-cli-action@v1
+
+      - name: Build
+        env:
+          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+          DOTENV_PRIVATE_KEY: ${{ secrets.DOTENV_PRIVATE_KEY }}
+          # Sanity project ID and dataset are public (they ship in the client
+          # bundle), so they are stored as repository variables. The Sanity read
+          # token is secret — add it under Settings → Secrets and variables →
+          # Actions. All three are empty (and harmless) until Sanity is set up.
+          NEXT_PUBLIC_SANITY_PROJECT_ID: ${{ vars.NEXT_PUBLIC_SANITY_PROJECT_ID }}
+          NEXT_PUBLIC_SANITY_DATASET: ${{ vars.NEXT_PUBLIC_SANITY_DATASET }}
+          SANITY_API_READ_TOKEN: ${{ secrets.SANITY_API_READ_TOKEN }}
+        run: |
+          if [ -n "$OP_SERVICE_ACCOUNT_TOKEN" ]; then
+            ref="$(grep -m1 '^DOTENV_PRIVATE_KEY_OP_REF=' .env | cut -d= -f2-)"
+            if [ -n "$ref" ]; then
+              DOTENV_PRIVATE_KEY="$(op read "$ref")"
+              echo "::add-mask::$DOTENV_PRIVATE_KEY"
+              export DOTENV_PRIVATE_KEY
+            fi
+          fi
+          bun run build
+
+      # bsmnt:endif
+      # bsmnt:if !dotenvx
+      - name: Build
+        env:
+          # Sanity project ID and dataset are public (they ship in the client
+          # bundle), so they are stored as repository variables. The Sanity read
+          # token is secret — add it under Settings → Secrets and variables →
+          # Actions. All three are empty (and harmless) until Sanity is set up.
+          NEXT_PUBLIC_SANITY_PROJECT_ID: ${{ vars.NEXT_PUBLIC_SANITY_PROJECT_ID }}
+          NEXT_PUBLIC_SANITY_DATASET: ${{ vars.NEXT_PUBLIC_SANITY_DATASET }}
+          SANITY_API_READ_TOKEN: ${{ secrets.SANITY_API_READ_TOKEN }}
+        run: bun run build
+
+      # bsmnt:endif
+      # Runs your tests if any exist; a fresh project with none passes cleanly.
+      - name: Test
+        run: |
+          if git ls-files '*.test.*' '*.spec.*' '*_test.*' '*_spec.*' | grep -q .; then
+            bun test
+          else
+            echo "No test files found — skipping bun test."
+          fi
+
+      - name: Knip
+        run: bun run knip

package/src/templates/next-pagebuilder-cache/.vscode/extensions.json

@@ -0,0 +1,19 @@
+{
+  "recommendations": [
+    // Formatting & Linting
+    "biomejs.biome",
+
+    // CSS & Styling
+    "bradlc.vscode-tailwindcss",
+    "csstools.postcss",
+
+    // Sanity CMS (GROQ syntax + validation)
+    "sanity-io.vscode-sanity",
+
+    // Env (dotenvx — view decrypted .env values inline)
+    "dotenv.dotenvx-vscode",
+
+    // DX Enhancements
+    "yoavbls.pretty-ts-errors"
+  ]
+}

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

@@ -0,0 +1,103 @@
+{
+  // Language-specific formatters (explicit per-language ensures no fallback to other formatters)
+  "[css]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[postcss]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "colorize.languages": [
+    "javascript",
+    "typescript",
+    "css",
+    "scss",
+    "less",
+    "html",
+    "json",
+    "yaml",
+    "markdown",
+    "glsl"
+  ],
+  "css.lint.unknownAtRules": "ignore",
+
+  // CSS (Tailwind v4)
+  "css.lint.validProperties": ["user-drag"],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "always",
+    "source.organizeImports.biome": "always"
+  },
+  "editor.defaultFormatter": "biomejs.biome",
+
+  // Formatting
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+
+  // File associations
+  "files.associations": {
+    "*.css": "css",
+    "*.json": "jsonc"
+  },
+
+  // General
+  "files.eol": "\n",
+  "javascript.suggest.autoImports": true,
+  // Disable Prettier to prevent silent formatter conflicts
+  "prettier.enable": false,
+
+  // Search exclusions (performance)
+  "search.exclude": {
+    "**/.next": true,
+    "**/.vercel": true,
+    "**/bun.lock": true,
+    "**/lib/integrations/sanity/sanity.types.ts": true,
+    "**/node_modules": true
+  },
+  "tailwindCSS.classAttributes": [
+    "class",
+    "className",
+    ".*ClassName",
+    ".*Styles"
+  ],
+  "tailwindCSS.classFunctions": ["cn", "cva", "twMerge", "cx"],
+  "tailwindCSS.experimental.classRegex": [
+    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^\"'`]*)(?:'|\"|`)"],
+    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
+  ],
+  "tailwindCSS.experimental.configFile": "./lib/styles/css/tailwind.css",
+  "tailwindCSS.includeLanguages": {
+    "typescriptreact": "html"
+  },
+  "typescript.preferences.importModuleSpecifier": "non-relative",
+
+  // TypeScript
+  "typescript.suggest.autoImports": true,
+
+  // Editor labels (fixed for .tsx files)
+  "workbench.editor.customLabels.patterns": {
+    "**/app/**/layout.tsx": "${dirname(1)}/${dirname} <layout>",
+    "**/app/**/page.tsx": "${dirname(1)}/${dirname} <page>",
+    "**/app/api/**/route.ts": "${dirname(1)}/${dirname} <route>",
+    "**/components/**/index.tsx": "${dirname} <component>"
+  },
+  "workbench.editorAssociations": {
+    "*.svg": "default"
+  }
+}

package/src/templates/next-pagebuilder-cache/.zed/settings.json

@@ -0,0 +1,47 @@
+{
+  "format_on_save": "on",
+  "lsp": {
+    "vscode-css-language-server": {
+      "settings": {
+        "css": {
+          "lint": {
+            "unknownAtRules": "ignore"
+          }
+        }
+      }
+    }
+  },
+  "languages": {
+    "JavaScript": {
+      "language_servers": ["biome", "..."],
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    },
+    "TypeScript": {
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    },
+    "TSX": {
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    },
+    "CSS": {
+      "formatter": { "language_server": { "name": "biome" } }
+    },
+    "JSON": {
+      "formatter": { "language_server": { "name": "biome" } }
+    },
+    "JSONC": {
+      "formatter": { "language_server": { "name": "biome" } }
+    }
+  }
+}