@nextsparkjs/core 0.1.0-beta.19 → 0.1.0-beta.190

package/templates/contents/themes/starter/tests/jest/setup.ts

@@ -0,0 +1,170 @@
+/**
+ * Jest Setup for Starter Theme
+ *
+ * This file provides complete Jest setup for npm mode.
+ * It includes all necessary polyfills and mocks.
+ */
+
+import '@testing-library/jest-dom'
+import { TextEncoder, TextDecoder } from 'util'
+
+// Polyfill TextEncoder/TextDecoder for jsdom
+global.TextEncoder = TextEncoder
+global.TextDecoder = TextDecoder as typeof global.TextDecoder
+
+// Polyfill Web APIs for Next.js server components testing
+class MockHeaders {
+  private _headers: Map<string, string> = new Map()
+
+  constructor(init?: HeadersInit) {
+    if (init) {
+      if (init instanceof MockHeaders) {
+        init._headers.forEach((value, key) => this._headers.set(key, value))
+      } else if (Array.isArray(init)) {
+        init.forEach(([key, value]) => this._headers.set(key.toLowerCase(), value))
+      } else {
+        Object.entries(init).forEach(([key, value]) => this._headers.set(key.toLowerCase(), value))
+      }
+    }
+  }
+
+  get(name: string) { return this._headers.get(name.toLowerCase()) || null }
+  set(name: string, value: string) { this._headers.set(name.toLowerCase(), value) }
+  has(name: string) { return this._headers.has(name.toLowerCase()) }
+  delete(name: string) { this._headers.delete(name.toLowerCase()) }
+  forEach(cb: (value: string, key: string) => void) { this._headers.forEach(cb) }
+  entries() { return this._headers.entries() }
+  keys() { return this._headers.keys() }
+  values() { return this._headers.values() }
+}
+
+class MockRequest {
+  url: string
+  method: string
+  headers: MockHeaders
+  private _body: any
+
+  constructor(input: string | URL, init?: RequestInit) {
+    this.url = typeof input === 'string' ? input : input.toString()
+    this.method = init?.method || 'GET'
+    this.headers = new MockHeaders(init?.headers as HeadersInit)
+    this._body = init?.body
+  }
+
+  async json() {
+    if (!this._body) return {}
+    return typeof this._body === 'string' ? JSON.parse(this._body) : this._body
+  }
+
+  async text() {
+    return this._body?.toString() || ''
+  }
+
+  clone() {
+    return new MockRequest(this.url, {
+      method: this.method,
+      headers: Object.fromEntries(this.headers.entries()),
+      body: this._body,
+    })
+  }
+}
+
+class MockResponse {
+  body: any
+  status: number
+  statusText: string
+  headers: MockHeaders
+  ok: boolean
+
+  constructor(body?: any, init?: ResponseInit) {
+    this.body = body
+    this.status = init?.status || 200
+    this.statusText = init?.statusText || 'OK'
+    this.headers = new MockHeaders(init?.headers as HeadersInit)
+    this.ok = this.status >= 200 && this.status < 300
+  }
+
+  async json() {
+    if (!this.body) return {}
+    return typeof this.body === 'string' ? JSON.parse(this.body) : this.body
+  }
+
+  async text() {
+    return this.body?.toString() || ''
+  }
+
+  clone() {
+    return new MockResponse(this.body, {
+      status: this.status,
+      statusText: this.statusText,
+      headers: Object.fromEntries(this.headers.entries()),
+    })
+  }
+
+  static json(data: any, init?: ResponseInit) {
+    return new MockResponse(JSON.stringify(data), {
+      ...init,
+      headers: { 'Content-Type': 'application/json', ...(init?.headers || {}) as object },
+    })
+  }
+}
+
+// Assign to global scope
+global.Headers = MockHeaders as any
+global.Request = MockRequest as any
+global.Response = MockResponse as any
+
+// Mock fetch
+global.fetch = jest.fn().mockResolvedValue(new MockResponse('{}', { status: 200 }))
+
+// Mock Web Crypto API
+const crypto = require('crypto')
+Object.defineProperty(global, 'crypto', {
+  value: {
+    getRandomValues: (arr: Uint8Array) => crypto.randomFillSync(arr),
+    randomUUID: () => crypto.randomUUID(),
+    subtle: {
+      digest: async (algorithm: string, data: BufferSource) => {
+        const hash = crypto.createHash(algorithm.toLowerCase().replace('-', ''))
+        hash.update(Buffer.from(data as ArrayBuffer))
+        return hash.digest().buffer
+      },
+      encrypt: jest.fn(),
+      decrypt: jest.fn(),
+      sign: jest.fn(),
+      verify: jest.fn(),
+      generateKey: jest.fn(),
+      importKey: jest.fn(),
+      exportKey: jest.fn(),
+    },
+  },
+})
+
+// Mock matchMedia for component tests with media queries
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: jest.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+})
+
+// Mock ResizeObserver
+global.ResizeObserver = jest.fn().mockImplementation(() => ({
+  observe: jest.fn(),
+  unobserve: jest.fn(),
+  disconnect: jest.fn(),
+}))
+
+// Mock IntersectionObserver
+global.IntersectionObserver = jest.fn().mockImplementation(() => ({
+  observe: jest.fn(),
+  unobserve: jest.fn(),
+  disconnect: jest.fn(),
+}))

package/templates/contents/themes/starter/tests/jest/tsconfig.jest.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../../../tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true
+  }
+}

package/templates/eslint.config.mjs

@@ -1,16 +1,140 @@
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-import { FlatCompat } from "@eslint/eslintrc";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
 
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
+/**
+ * Next's presets from the eslint-config-next the project installs, as flat config.
+ *
+ * Version 16 publishes flat config arrays on these subpaths; reaching them through FlatCompat
+ * throws `Converting circular structure to JSON` before a single file is read. Version 15 declares
+ * no `exports` and publishes eslintrc presets, which FlatCompat is the only way to read: importing
+ * the subpaths throws ERR_MODULE_NOT_FOUND, or, under a loader that adds file extensions, returns
+ * eslintrc objects. That is what a Next 15 project gets when `nextspark init` drops this file next
+ * to its eslint-config-next. FlatCompat ships in @eslint/eslintrc, which ESLint itself depends on,
+ * so it is resolved from there.
+ */
+async function nextPresets() {
+  let presets;
+  try {
+    presets = await Promise.all([
+      import("eslint-config-next/core-web-vitals"),
+      import("eslint-config-next/typescript"),
+    ]);
+  } catch (error) {
+    if (error?.code !== "ERR_MODULE_NOT_FOUND") throw error;
+  }
+
+  if (presets?.every((preset) => Array.isArray(preset.default))) {
+    return presets.flatMap((preset) => preset.default);
+  }
+
+  const { FlatCompat } = createRequire(require.resolve("eslint"))("@eslint/eslintrc");
+  return new FlatCompat({ baseDirectory: __dirname }).extends("next/core-web-vitals", "next/typescript");
+}
+
+/** A config object holding nothing but `ignores` applies to every other object in the array. */
+const isGlobalIgnore = (config) =>
+  Object.keys(config).every((key) => key === "ignores" || key === "name");
+
+const presets = await nextPresets();
+
+/** typescript-eslint's parser, which reads every syntax these trees use: JS, TS and JSX. */
+const typescriptParser = presets
+  .map((config) => config.languageOptions?.parser)
+  .find((parser) => parser?.meta?.name === "typescript-eslint/parser");
+
+const SOURCE_FILES = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
+
+// Tests and fixtures, the project's own and those every theme and plugin brings under contents/:
+// they mock, stub and cast by design, so Next's presets skip them and only the zod rule reaches
+// them. Everything else -- app/, contents/ and what the project adds -- gets the presets.
+const TEST_FILES = [
+  "**/tests/**",
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/fixtures/**",
+  "**/cypress/**",
+  "**/*.{test,spec,cy}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+  "**/{jest,cypress}.{config,setup}.{ts,mts,cts,js,mjs,cjs}",
+];
+
+/** "error", 2 or ["error", ...]. */
+const isError = (setting) => [setting, setting?.[0]].some((level) => level === "error" || level === 2);
+
+/**
+ * The severity this project gives the rules Next's presets configure.
+ *
+ * `@next/next/no-img-element` is an error: the presets only warn, which leaves `eslint .` passing,
+ * and next/image is what serves an image resized and in a modern format.
+ *
+ * eslint-plugin-react-hooks 7, which Next 16's presets load, adds to rules-of-hooks and
+ * exhaustive-deps the rules that flag code the React Compiler cannot compile. A NextSpark project
+ * does not build with the React Compiler, and the components NextSpark ships in app/ and its themes
+ * and plugins break several of those rules, so they report as warnings. Version 5, which Next 15
+ * loads, has none of them.
+ */
+function projectSeverity(rule, setting) {
+  if (rule === "@next/next/no-img-element") return "error";
+  const compilerRule = rule.startsWith("react-hooks/") && !["react-hooks/rules-of-hooks", "react-hooks/exhaustive-deps"].includes(rule);
+  return compilerRule && isError(setting) ? "warn" : setting;
+}
 
 const eslintConfig = [
-  ...compat.extends("next/core-web-vitals", "next/typescript"),
+  {
+    // Next writes next-env.d.ts itself; version 16's presets ignore it and version 15's do not.
+    ignores: [".next/**", ".nextspark/**", "next-env.d.ts"],
+  },
+  ...presets.map((config) =>
+    isGlobalIgnore(config)
+      ? config
+      : {
+          ...config,
+          ignores: [...(config.ignores ?? []), ...TEST_FILES],
+          ...(config.rules && {
+            rules: Object.fromEntries(Object.entries(config.rules).map(([rule, setting]) => [rule, projectSeverity(rule, setting)])),
+          }),
+        },
+  ),
+  {
+    // A .cjs file is CommonJS by definition, so `require` is the only spelling it has.
+    files: ["**/*.cjs"],
+    ignores: TEST_FILES,
+    rules: { "@typescript-eslint/no-require-imports": "off" },
+  },
+  {
+    // The presets would have supplied the parser here. Their plugins are registered so the disable
+    // comments in tests resolve the rules they name, without turning any of those rules on.
+    files: TEST_FILES,
+    languageOptions: {
+      parser: typescriptParser,
+      parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+    plugins: Object.assign({}, ...presets.map((config) => config.plugins ?? {})),
+    linterOptions: { reportUnusedDisableDirectives: "off" },
+  },
+  {
+    // Spelled out rather than inherited: a block naming these extensions is what makes ESLint lint
+    // a .ts file at all.
+    files: [SOURCE_FILES],
+    rules: {
+      // `no-restricted-imports` with `importNames: ["z"]` also rejects `import * as z`, so the
+      // named specifier is matched by syntax instead.
+      "no-restricted-syntax": [
+        "error",
+        {
+          // `imported` is an Identifier for `{ z }` and a Literal for `{ "z" as zod }`, so the
+          // name lives under a different property in each.
+          selector:
+            "ImportDeclaration[source.value='zod'] > ImportSpecifier:matches([imported.name='z'], [imported.value='z']), ExportNamedDeclaration[source.value='zod'] > ExportSpecifier:matches([local.name='z'], [local.value='z'])",
+          message:
+            "Use `import * as z from 'zod'`. Turbopack doesn't tree-shake the named `z` import and bundles all of zod, its 63 locales included.",
+        },
+      ],
+    },
+  },
 ];
 
 export default eslintConfig;

package/templates/features/blog/blocks/post-content/component.tsx

@@ -1,8 +1,10 @@
 import React from 'react'
 import { cn } from '@nextsparkjs/core/lib/utils'
 import { buildSectionClasses } from '@nextsparkjs/core/types/blocks'
+import { sanitizeBlockHtml } from '@nextsparkjs/core/lib/blocks/sanitize-html'
 import { sel } from '../../lib/selectors'
 import type { PostContentBlockProps } from './schema'
+import { withBasePathIfInApp } from '@nextsparkjs/core/lib/base-path'
 
 /**
  * Post Content Block Component
@@ -79,7 +81,7 @@ export function PostContentBlock({
 
   // Build section classes with background
   const sectionClasses = buildSectionClasses(
-    'py-16 px-4 md:py-24',
+    'py-16 px-4 @md:py-24',
     { backgroundColor, className }
   )
 
@@ -119,7 +121,7 @@ export function PostContentBlock({
         {/* Optional Section Title */}
         {title && (
           <div className={cn('mb-12 text-center', maxWidthClasses[maxWidth], 'mx-auto')}>
-            <h2 className="text-4xl font-bold md:text-5xl lg:text-6xl tracking-tight">
+            <h2 className="text-4xl font-bold @md:text-5xl @lg:text-6xl tracking-tight">
               {title}
             </h2>
           </div>
@@ -171,7 +173,7 @@ export function PostContentBlock({
             // Em/italic
             'prose-em:italic'
           )}
-          dangerouslySetInnerHTML={{ __html: content }}
+          dangerouslySetInnerHTML={{ __html: sanitizeBlockHtml(content) }}
         />
 
         {/* Optional Divider after content */}
@@ -181,7 +183,7 @@ export function PostContentBlock({
         {cta && (
           <div className={cn('mt-12 text-center', maxWidthClasses[maxWidth], 'mx-auto')}>
             <a
-              href={cta.link}
+              href={withBasePathIfInApp(cta.link)}
               target={cta.target}
               rel={cta.target === '_blank' ? 'noopener noreferrer' : undefined}
               className="inline-flex items-center justify-center rounded-md bg-primary px-8 py-3 text-sm font-medium text-primary-foreground hover:bg-primary/90 transition-colors shadow-md hover:shadow-lg"
@@ -195,3 +197,6 @@ export function PostContentBlock({
     </section>
   )
 }
+
+// The generated block registry imports this as the module's default.
+export default PostContentBlock

package/templates/features/blog/blocks/post-content/schema.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod'
+import * as z from 'zod'
 import { baseBlockSchema } from '@nextsparkjs/core/types/blocks'
 
 /**
@@ -41,6 +41,6 @@ export const postContentSpecificSchema = z.object({
  * Complete Post Content Block Schema
  * Note: postContentSpecificSchema.content overrides baseBlockSchema.content
  */
-export const schema = baseBlockSchema.merge(postContentSpecificSchema)
+export const schema = baseBlockSchema.extend(postContentSpecificSchema.shape)
 
 export type PostContentBlockProps = z.infer<typeof schema>

package/templates/features/blog/entities/posts/components/post-header.tsx

@@ -1,4 +1,5 @@
 import { Badge } from '@nextsparkjs/core/components/ui/badge'
+import { withBasePathIfInApp } from '@nextsparkjs/core/lib/base-path'
 import Image from 'next/image'
 
 interface Category {
@@ -24,7 +25,7 @@ export function PostHeader({ post }: PostHeaderProps) {
       {post.featuredImage && (
         <div className="relative w-full h-[400px] md:h-[500px] mb-8" data-cy="post-featured-image-display">
           <Image
-            src={post.featuredImage}
+            src={withBasePathIfInApp(post.featuredImage)}
             alt={post.title}
             fill
             className="object-cover rounded-lg"

package/templates/features/blog/entities/posts/posts.config.ts

@@ -81,6 +81,7 @@ export const postsEntityConfig: EntityConfig = {
   // ==========================================
   builder: {
     enabled: true,
+    showSlug: true, // Slug is user-editable (public content)
     sidebarFields: ['excerpt', 'featuredImage'], // Extra fields shown in sidebar
     seo: true, // Enable SEO fields panel in editor
   },

package/templates/features/pages/blocks/hero/component.tsx

@@ -1,9 +1,10 @@
 import React from 'react'
 import { Button } from '@nextsparkjs/core/components/ui/button'
 import { cn } from '@nextsparkjs/core/lib/utils'
-import { buildSectionClasses } from '@nextsparkjs/core/types/blocks'
+import { buildSectionClasses, resolveMediaUrl } from '@nextsparkjs/core/types/blocks'
 import { sel } from '../../lib/selectors'
 import type { HeroBlockProps } from './schema'
+import { withBasePathIfInApp } from '@nextsparkjs/core/lib/base-path'
 
 /**
  * Hero Block Component
@@ -45,6 +46,9 @@ export function HeroBlock({
   // Handle legacy subtitle/description props for backward compatibility
   const displayContent = content || legacyProps.subtitle || legacyProps.description
 
+  // Resolve media ref to URL (handles both legacy string and new object format)
+  const backgroundImageUrl = resolveMediaUrl(backgroundImage)
+
   // Alignment classes mapping
   const alignmentClasses = {
     left: 'text-left items-start',
@@ -64,11 +68,11 @@ export function HeroBlock({
   return (
     <section id={id} className={sectionClasses} data-cy={sel('blocks.hero.container')}>
       {/* Background Image */}
-      {backgroundImage && (
+      {backgroundImageUrl && (
         <div
           className="absolute inset-0 z-0"
           style={{
-            backgroundImage: `url(${backgroundImage})`,
+            backgroundImage: `url(${withBasePathIfInApp(backgroundImageUrl)})`,
             backgroundSize: 'cover',
             backgroundPosition: 'center',
           }}
@@ -83,13 +87,13 @@ export function HeroBlock({
         alignmentClasses[alignment]
       )}>
         {title && (
-          <h1 className="mb-6 text-5xl font-bold leading-tight md:text-6xl lg:text-7xl">
+          <h1 className="mb-6 text-5xl font-bold leading-tight @md:text-6xl @lg:text-7xl">
             {title}
           </h1>
         )}
 
         {displayContent && (
-          <p className="mb-8 text-xl md:text-2xl opacity-90 max-w-2xl">
+          <p className="mb-8 text-xl @md:text-2xl opacity-90 max-w-2xl">
             {displayContent}
           </p>
         )}
@@ -97,7 +101,7 @@ export function HeroBlock({
         {ctaConfig && (
           <Button asChild size="lg" className="text-lg px-8 py-6">
             <a
-              href={ctaConfig.link}
+              href={withBasePathIfInApp(ctaConfig.link)}
               target={ctaConfig.target}
               rel={ctaConfig.target === '_blank' ? 'noopener noreferrer' : undefined}
               data-cy={sel('blocks.hero.cta')}
@@ -110,3 +114,6 @@ export function HeroBlock({
     </section>
   )
 }
+
+// The generated block registry imports this as the module's default.
+export default HeroBlock

package/templates/features/pages/blocks/hero/schema.ts

@@ -1,6 +1,7 @@
-import { z } from 'zod'
+import * as z from 'zod'
 import {
   baseBlockSchema,
+  mediaRefSchema,
   type BaseBlockProps,
 } from '@nextsparkjs/core/types/blocks'
 
@@ -17,7 +18,7 @@ import {
  */
 export const heroSpecificSchema = z.object({
   // Hero-specific design fields
-  backgroundImage: z.string().url('Must be a valid URL').optional(),
+  backgroundImage: mediaRefSchema.optional(),
   textColor: z.enum(['light', 'dark']).default('light'),
   alignment: z.enum(['left', 'center', 'right']).default('center'),
 })
@@ -26,7 +27,7 @@ export const heroSpecificSchema = z.object({
  * Complete Hero Block Schema
  * Combines base fields + hero-specific fields
  */
-export const schema = baseBlockSchema.merge(heroSpecificSchema)
+export const schema = baseBlockSchema.extend(heroSpecificSchema.shape)
 
 export type HeroBlockProps = z.infer<typeof schema>
 

package/templates/features/pages/entities/pages/pages.config.ts

@@ -81,6 +81,7 @@ export const pagesEntityConfig: EntityConfig = {
   // ==========================================
   builder: {
     enabled: true,
+    showSlug: true, // Slug is user-editable (public content)
     sidebarFields: ['locale'], // Pages don't have extra sidebar fields beyond basic settings
     seo: true, // Enable SEO fields panel in editor
   },

package/templates/instrumentation.ts

@@ -0,0 +1,39 @@
+/**
+ * Next.js Instrumentation
+ *
+ * This file runs once when the server starts (not on every request).
+ * Used to initialize global systems like scheduled action handlers.
+ *
+ * Runs in both development and production environments.
+ * Initialization is idempotent - safe to call multiple times.
+ *
+ * @see https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
+ */
+
+export async function register() {
+  // Only run on server (not during build or in edge runtime)
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    console.log('[Instrumentation] Initializing scheduled actions system...')
+
+    try {
+      const {
+        initializeScheduledActions,
+        initializeRecurringActions,
+      } = await import('@nextsparkjs/core/lib/scheduled-actions')
+
+      // Register scheduled action handlers (includes entity hooks for automatic scheduling)
+      // This registers hooks like 'entity.contents.updated' that create scheduled actions
+      initializeScheduledActions()
+
+      // Register recurring scheduled actions (token refresh, cleanup jobs, etc.)
+      // These are background tasks that run on a schedule (e.g., every 30 minutes)
+      // Non-blocking: if DB is unavailable at cold start, the server still boots
+      await initializeRecurringActions()
+
+      console.log('[Instrumentation] ✅ Scheduled actions initialized')
+    } catch (error) {
+      console.warn(`[Instrumentation] ⚠️ Failed to initialize scheduled actions: ${error instanceof Error ? error.message : error}`)
+      console.warn('[Instrumentation] Server will continue without recurring actions')
+    }
+  }
+}

package/templates/lib/billing/polar-webhook-extensions.ts

@@ -0,0 +1,23 @@
+/**
+ * Polar Webhook Extensions
+ *
+ * Override this file in your project to handle one-time payments
+ * (credit packs, LTD purchases, upsells, etc.) via Polar checkout.
+ *
+ * Example: create lib/billing/polar-webhook-extensions.ts in your project:
+ *
+ *   import type { PolarWebhookExtensions } from '@nextsparkjs/core/lib/billing/polar-webhook'
+ *   import { handleCreditPackPurchase } from '@/lib/billing/credit-packs'
+ *
+ *   export const polarWebhookExtensions: PolarWebhookExtensions = {
+ *     onOneTimePaymentCompleted: async (order, context) => {
+ *       if (order.metadata?.type === 'credit_pack') {
+ *         await handleCreditPackPurchase(order, context)
+ *       }
+ *     }
+ *   }
+ */
+
+import type { PolarWebhookExtensions } from '@nextsparkjs/core/lib/billing/polar-webhook'
+
+export const polarWebhookExtensions: PolarWebhookExtensions = {}

package/templates/lib/billing/stripe-webhook-extensions.ts

@@ -0,0 +1,23 @@
+/**
+ * Stripe Webhook Extensions
+ *
+ * Override this file in your project to handle one-time payments
+ * (credit packs, LTD purchases, upsells, etc.) via Stripe checkout.
+ *
+ * Example: create lib/billing/stripe-webhook-extensions.ts in your project:
+ *
+ *   import type { StripeWebhookExtensions } from '@nextsparkjs/core/lib/billing/stripe-webhook'
+ *   import { handleCreditPackPurchase } from '@/lib/billing/credit-packs'
+ *
+ *   export const stripeWebhookExtensions: StripeWebhookExtensions = {
+ *     onOneTimePaymentCompleted: async (session, context) => {
+ *       if (session.metadata?.type === 'credit_pack') {
+ *         await handleCreditPackPurchase(session, context)
+ *       }
+ *     }
+ *   }
+ */
+
+import type { StripeWebhookExtensions } from '@nextsparkjs/core/lib/billing/stripe-webhook'
+
+export const stripeWebhookExtensions: StripeWebhookExtensions = {}