@se-studio/project-build 1.0.61 → 1.0.63

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/project-build
 
+## 1.0.63
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.62
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
 ## 1.0.61
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/project-build",
-  "version": "1.0.61",
+  "version": "1.0.63",
   "description": "Build tools and management scripts for SE Studio projects",
   "repository": {
     "type": "git",

package/skills/se-marketing-sites/cms-routes-and-appshared/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: cms-routes-and-appshared
+description: Guide for the (cms-routes) route group and appShared pattern. Use when setting up or migrating CMS-driven routing, creating new route segments, or refactoring page structure.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# CMS Routes and appShared Pattern
+
+Reference apps: **example-se2026**, **example-brightline**.
+
+## Route Group: (cms-routes)
+
+All CMS-driven pages live under `src/app/(cms-routes)/`. The layout enables dynamic params:
+
+```tsx
+// layout.tsx
+export const dynamicParams = true;
+
+export default function CmsRoutesLayout({ children }: { children: React.ReactNode }) {
+  return children;
+}
+```
+
+## Route Structure
+
+| Path | File | Purpose |
+|------|------|---------|
+| `/` | `page.ts` | Home (slug: `index`) |
+| `/{slug}/` | `[level1]/page.ts` | Single-level page |
+| `/{slug1}/{slug2}/...` | `[level1]/[...slugs]/page.ts` | Multi-level pages |
+| `/articles/` | `articles/page.ts` | Articles index (uses ARTICLES_BASE) |
+| `/articles/{type}/` | `articles/[articleType]/page.ts` | Article type index |
+| `/articles/{type}/{tag}/` | `articles/[articleType]/[tag]/page.ts` | Article type + tag index |
+| `/articles/{type}/{tag}/{article}/` | `articles/[articleType]/[tag]/[...slugs]/page.ts` | Individual article |
+| `/tags/`, `/tags/{tag}/` | `tags/` | Tag index (if enabled) |
+| `/people/`, `/people/{person}/` | `people/` | People (if enabled) |
+
+Base paths come from `@/lib/constants` (e.g. ARTICLES_BASE = `/learning-hub` or `/articles`).
+
+## appShared Modules
+
+Route files are thin wrappers. Logic lives in `src/appShared/`:
+
+| Module | Exports | Used by |
+|--------|---------|---------|
+| `pageShared.tsx` | `generatePage`, `generatePageMetadata` | `/`, `[level1]`, `[level1]/[...slugs]` |
+| `articleShared.tsx` | `generateArticlePage`, `generateArticleMetadata` | Article detail |
+| `articleTypeShared.tsx` | `generateArticleTypePage`, `generateArticleTypeMetadata` | Article type index |
+| `articleTypesIndexShared.tsx` | `generateArticleTypesIndexPage`, `generateArticleTypesIndexMetadata` | Articles index |
+| `articleTypeTagShared.tsx` | `generateArticleTypeTagPage`, `generateArticleTypeTagMetadata` | Article type + tag index |
+| `customTypeShared.tsx` | `generateCustomTypePage`, `generateCustomTypeMetadata` | Custom types |
+| `personShared.tsx` | `generatePersonPage`, `generatePersonMetadata` | Person page |
+| `tagShared.tsx` | `generateTagPage`, `generateTagMetadata` | Tag index |
+| `tagsIndexShared.tsx` | `generateTagsIndexPage`, `generateTagsIndexMetadata` | Tags index |
+| `teamIndexShared.tsx` | `generateTeamIndexPage`, `generateTeamIndexMetadata` | People index |
+
+## Route Page Pattern
+
+Each route page:
+
+1. Exports `generateStaticParams() { return []; }` for dynamic routes
+2. Defines `extractDetails(props)` to derive slug/path from params
+3. Exports `generateMetadata(props, parent)` calling the shared metadata function
+4. Exports default async function calling the shared page function
+
+```typescript
+import type { ResolvingMetadata } from 'next';
+import { generatePage, generatePageMetadata } from '@/appShared/pageShared';
+
+export function generateStaticParams() {
+  return [];
+}
+
+async function extractDetails(props: PageProps<'/[level1]'>) {
+  const params = await props.params;
+  const { level1 } = params;
+  return { slug: level1, path: `/${level1}/` };
+}
+
+export async function generateMetadata(props: PageProps<'/[level1]'>, parent: ResolvingMetadata) {
+  const { slug, path } = await extractDetails(props);
+  return generatePageMetadata(slug, path, true, parent);
+}
+
+export default async function (props: PageProps<'/[level1]'>) {
+  const { slug, path } = await extractDetails(props);
+  return generatePage(slug, path, true);
+}
+```
+
+For article routes, use `converterContext.urlCalculators.article`, `articleType`, `articleTypeTag` from `@/lib/cms-server` to compute the path.
+
+## See Also
+
+- **create-page** – Creating new pages and routes
+- **lib-cms-structure** – lib directory layout

package/skills/se-marketing-sites/create-collection/SKILL.md

@@ -87,7 +87,7 @@ import {
 import { SectionLinks } from '@/elements/SectionLinks';
 import { Section } from '@/framework/Section';
 import type { ICollection, IComponent, IContent } from '@/lib/cms';
-import { getPreviewFieldIdProps } from '@/lib/cms';
+import { getPreviewFieldIdProps } from '@/lib/cms-server';
 import { getSizingInformation } from '@/lib/SizingInformation';
 // import MyCollectionClient from './MyCollectionClient'; // If needed
 
@@ -280,4 +280,4 @@ export const MyCollectionRegistration = defineCollection({
     *   If a carousel/slider/filter is needed, move that logic to `[Name]Client.tsx`.
     *   Pass server-rendered cards as `children` to the client wrapper.
 5.  **Register**:
-    *   Add to `componentRegistrations` in `src/lib/cms.ts`.
+    *   Add to `collectionRegistrations` in `src/lib/registrations.ts`.

package/skills/se-marketing-sites/create-component/SKILL.md

@@ -78,7 +78,7 @@ import {
 import { SectionLinks } from '@/elements/SectionLinks';
 import { Section } from '@/framework/Section';
 import type { IComponent, IContent } from '@/lib/cms';
-import { getPreviewFieldIdProps } from '@/lib/cms';
+import { getPreviewFieldIdProps } from '@/lib/cms-server';
 import { getSizingInformation } from '@/lib/SizingInformation';
 // If interactivity is needed:
 // import MyNewComponentClient from './MyNewComponentClient';
@@ -242,4 +242,4 @@ export const MyNewRegistration = defineComponent({
     *   **CRITICAL**: `name` must match CMS `componentType` exactly.
     *   Provide mock data for showcase.
 8.  **Register Component**:
-    *   Add to `componentRegistrations` array in `src/lib/cms.ts`.
+    *   Add to `componentRegistrations` in `src/lib/registrations.ts`.

package/skills/se-marketing-sites/create-page/SKILL.md

@@ -1,134 +1,127 @@
 ---
 name: create-page-route
-description: Guide for creating new Next.js App Router pages and dynamic routes in the SE Core Product framework.
+description: Guide for creating new Next.js App Router pages and dynamic routes in the SE Core Product framework. Use when creating CMS-driven pages, adding route segments, or setting up routing.
 license: Private
 metadata:
   author: se-core-product
-  version: "1.0.0"
+  version: "2.0.0"
 ---
 
 # Creating Pages and Routes
 
 This guide explains how to create new pages and handle routing in the SE Core Product Next.js framework. The system uses Next.js App Router with Contentful-driven dynamic routing.
 
-## Page Architecture
+Reference apps: **example-se2026**, **example-brightline**.
 
-### 1. Dynamic Catch-All Route (`[...slugs]`)
+## Page Architecture
 
-Most CMS pages are handled by a single catch-all route at `app/(pages)/[...slugs]/page.tsx`. This component:
-1.  Receives the URL slug.
-2.  Fetches the page data from Contentful.
-3.  Renders the `<CmsContent>` component.
+### 1. (cms-routes) Route Group
 
-### 2. Static Params Generation
+All CMS-driven pages live under `src/app/(cms-routes)/`. The layout enables dynamic params:
 
-To enable Static Site Generation (SSG), the page exports `generateStaticParams`:
+```tsx
+// layout.tsx
+export const dynamicParams = true;
 
-```typescript
-import { getAllPageLinks } from '@/lib/cms';
-
-export async function generateStaticParams() {
-  const links = await getAllPageLinks();
-  return links
-    .filter(link => link.slug !== 'index')
-    .map(link => ({
-      slugs: link.href?.split('/').filter(Boolean)
-    }));
+export default function CmsRoutesLayout({ children }: { children: React.ReactNode }) {
+  return children;
 }
 ```
 
-## Creating a New Specialized Route
+### 2. Route Structure
 
-Sometimes you need a route that behaves differently from standard CMS pages (e.g., a search page, a dashboard, or a specialized landing page).
+| Path | File | Purpose |
+|------|------|---------|
+| `/` | `page.ts` | Home (slug: `index`) |
+| `/{slug}/` | `[level1]/page.ts` | Single-level page |
+| `/{slug1}/{slug2}/...` | `[level1]/[...slugs]/page.ts` | Multi-level pages |
+| `/articles/` | `articles/page.ts` | Articles index (uses ARTICLES_BASE from constants) |
+| `/articles/{type}/` | `articles/[articleType]/page.ts` | Article type index |
+| `/articles/{type}/{tag}/` | `articles/[articleType]/[tag]/page.ts` | Article type + tag index |
+| `/articles/{type}/{tag}/{article}/` | `articles/[articleType]/[tag]/[...slugs]/page.ts` | Individual article |
+| `/tags/`, `/tags/{tag}/` | `tags/` | Tag index (if enabled) |
+| `/people/`, `/people/{person}/` | `people/` | People (if enabled) |
 
-### Step 1: Create the Route Directory
+Base paths (e.g. `/articles` vs `/learning-hub`) come from `@/lib/constants`.
 
-Create a new directory in `src/app` matching your desired URL structure.
+### 3. appShared Pattern
 
-*   Example: `src/app/search/page.tsx` -> `/search`
-*   Example: `src/app/team/[slug]/page.tsx` -> `/team/john-doe`
+Route files are thin wrappers. Data-fetching and rendering logic lives in `src/appShared/`:
 
-### Step 2: Implement the Page Component
+- `pageShared.tsx` – `generatePage`, `generatePageMetadata`
+- `articleShared.tsx` – articles
+- `articleTypeShared.tsx`, `articleTypesIndexShared.tsx`, `articleTypeTagShared.tsx` – article indices
+- `customTypeShared.tsx` – custom types
+- `personShared.tsx`, `tagShared.tsx`, `tagsIndexShared.tsx`, `teamIndexShared.tsx`
+
+## Route Page Template
+
+Each route page extracts params and delegates to the appropriate appShared function:
 
 ```typescript
-import type { Metadata } from 'next';
-import { notFound } from 'next/navigation';
-import { CmsContent } from '@se-studio/core-ui';
-import { contentfulPageRest, getContentfulConfig } from '@/lib/cms';
-import { projectRendererConfig } from '@/lib/cms';
-
-interface PageProps {
-  params: { slug: string };
-  searchParams: { [key: string]: string | string[] | undefined };
+import type { ResolvingMetadata } from 'next';
+import { generatePage, generatePageMetadata } from '@/appShared/pageShared';
+
+export function generateStaticParams() {
+  return [];
 }
 
-export default async function Page({ params, searchParams }: PageProps) {
-  const { slug } = params;
-  const isPreview = searchParams.preview === 'true';
-
-  // 1. Fetch content
-  const response = await contentfulPageRest(
-    getContentfulConfig(isPreview),
-    slug,
-    { preview: isPreview }
-  );
-
-  if (!response.data) {
-    notFound();
-  }
-
-  // 2. Render content with CmsContent
-  // This automatically handles the recursive rendering of components
-  return (
-    <main>
-      <CmsContent
-        content={response.data}
-        config={projectRendererConfig}
-        contentContext={{
-            // Pass any required context
-            analyticsContext: { ... }
-        }}
-      />
-    </main>
-  );
+async function extractDetails(props: PageProps<'/[level1]'>) {
+  const params = await props.params;
+  const { level1 } = params;
+  return { slug: level1, path: `/${level1}/` };
 }
-```
 
-### Step 3: Add Metadata
+export async function generateMetadata(props: PageProps<'/[level1]'>, parent: ResolvingMetadata) {
+  const { slug, path } = await extractDetails(props);
+  return generatePageMetadata(slug, path, true, parent);
+}
 
-Always export metadata for SEO:
+export default async function (props: PageProps<'/[level1]'>) {
+  const { slug, path } = await extractDetails(props);
+  return generatePage(slug, path, true);
+}
+```
 
-```typescript
-export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
-  const response = await contentfulPageRest(/* ... */);
-  const page = response.data;
+For the home page (`/`), use slug `'index'` and path `'/'` directly.
 
-  if (!page) return {};
+## CmsContent Usage
 
-  return {
-    title: page.seoTitle || page.title,
-    description: page.seoDescription,
-    // ... maps to Next.js metadata format
-  };
-}
+The appShared modules render content with:
+
+```tsx
+<CmsContent
+  contents={page.contents}
+  rendererConfig={projectRendererConfig}
+  pageContext={{ page }}
+/>
 ```
 
-## Custom Layouts
+- `contents` – array of page/article contents (not the full page object)
+- `rendererConfig` – from `@/lib/cms-server`
+- `pageContext` – provides page/article/customType to child components
 
-If your new route needs a different layout (e.g., no header/footer), create a `layout.tsx` in your route directory.
+## Creating a Specialized Route
 
-```typescript
-export default function CustomLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="custom-layout">
-      {children}
-    </div>
-  );
-}
-```
+For a route that behaves differently from standard CMS pages (e.g. search, dashboard):
+
+1. Create the route under `(cms-routes)` or a separate route group.
+2. Either create a new appShared module (if the pattern is reusable) or implement inline.
+3. Use `getPageWithErrors`, `getArticleWithErrors`, etc. from `@/lib/cms-server`.
+4. Use `projectRendererConfig` from `@/lib/cms-server`.
+5. Render with `CmsContent` using `contents`, `rendererConfig`, and `pageContext`.
+
+## Custom Layouts
+
+If a route needs a different layout (e.g. no header/footer), create `layout.tsx` in that route directory.
 
 ## Troubleshooting
 
-*   **404 on new route**: Ensure you've re-run the dev server or build if you added a new dynamic route segment.
-*   **Static params missing**: Check if your new content is published in Contentful and reachable via `getAllPageLinks` (or your custom fetcher).
-*   **Preview mode not working**: Ensure you are passing `preview: true` to the fetcher functions when `searchParams.preview` is set.
+- **404 on new route**: Re-run the dev server or build after adding a dynamic route segment.
+- **Static params missing**: Dynamic routes use `generateStaticParams() { return []; }` for on-demand rendering.
+- **Preview mode**: Handled by `draftOnly` in `@/lib/server-config`; appShared modules use it automatically.
+
+## See Also
+
+- **cms-routes-and-appshared** – Full route structure and appShared pattern
+- **lib-cms-structure** – lib directory layout and cms-server usage

package/skills/se-marketing-sites/lib-cms-structure/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: lib-cms-structure
+description: Guide for the lib directory structure in SE Core Product CMS apps. Use when setting up lib/, migrating from contentful-config, or adding new CMS configuration.
+license: Private
+metadata:
+  author: se-core-product
+  version: "1.0.0"
+---
+
+# Lib Directory Structure
+
+Reference apps: **example-se2026**, **example-brightline**.
+
+## File Responsibilities
+
+| File | Client-safe? | Purpose |
+|------|--------------|---------|
+| `cms.ts` | Yes | Types, build maps from registrations, createConverterContext |
+| `cms-server.ts` | No (server-only) | createAppHelpers, buildOptions, getContentfulConfig, projectRendererConfig |
+| `client-config.ts` | Yes | isProduction, isDevelopment |
+| `server-config.ts` | No | draftOnly, videoPrefix, baseUrl, revalidationSecret |
+| `constants.ts` | Yes | ARTICLES_BASE, TAGS_BASE, PEOPLE_BASE, enable flags, customer name |
+| `registrations.ts` | Yes | componentRegistrations, collectionRegistrations, externalComponentRegistrations |
+| `SizingInformation.ts` | Yes | getSizingInformation for dynamic heading sizes |
+
+## Server vs Client Boundary
+
+- **cms-server.ts** has `import 'server-only'`. Never import it in `'use client'` components.
+- **cms.ts** is client-safe: types, maps, converter context factory (no env access).
+- **registrations.ts** imports from cms.ts and project components; keep it client-safe.
+
+## constants.ts Shape
+
+```typescript
+export const ARTICLES_SLUG = 'articles';  // or 'learning-hub'
+export const TAGS_SLUG = 'tags';
+export const PEOPLE_SLUG = 'people';
+export const DEFAULT_TOPIC = 'other';
+
+export const ARTICLES_BASE = `/${ARTICLES_SLUG}`;
+export const TAGS_BASE = `/${TAGS_SLUG}`;
+export const PEOPLE_BASE = `/${PEOPLE_SLUG}`;
+
+export const customerName = '...';
+export const applicationName = '...';
+export const siteTitle = '...';
+export const siteDescription = '...';
+export const enablePerson = false;
+export const enablePeopleIndex = false;
+export const enableTag = false;
+export const enableTagsIndex = false;
+```
+
+## Data Flow
+
+```
+registrations.ts  →  cms.ts  →  builds maps  →  cms-server.ts
+                                      ↓
+                            projectRendererConfig
+```
+
+Add new components/collections in `registrations.ts`. The `cms.ts` imports from it and builds the maps used by `cms-server.ts`.
+
+## See Also
+
+- **register-cms-features** – Adding components and collections
+- **cms-routes-and-appshared** – Route structure and appShared

package/skills/se-marketing-sites/register-cms-features/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: register-cms-features
-description: Guide for registering new components, collections, and external integrations in the CMS configuration (src/lib/cms.ts).
+description: Guide for registering new components, collections, and external integrations in the CMS configuration (src/lib/registrations.ts).
 license: Private
 metadata:
   author: se-core-product
@@ -9,7 +9,7 @@ metadata:
 
 # Registering CMS Features
 
-The file `src/lib/cms.ts` is the central registry for the application. It connects Contentful content types to their React implementations.
+The file `src/lib/registrations.ts` is where you add new components, collections, and external components. The `cms.ts` module imports from `registrations.ts` and builds the maps used by the renderer; add new registrations in `registrations.ts`.
 
 ## How Registration Works
 
@@ -22,14 +22,14 @@ The system uses "Registration Objects" created via `defineComponent` or `defineC
 ## Registering a New Component
 
 1.  **Import the Registration**:
-    At the top of `src/lib/cms.ts`, import your component's registration export.
+    At the top of `src/lib/registrations.ts`, import your component's registration export.
 
     ```typescript
     import { MyNewComponentRegistration } from '@/project/components/MyNewComponent';
     ```
 
 2.  **Add to `componentRegistrations`**:
-    Find the `componentRegistrations` array and add your component.
+    Find the `componentRegistrations` array in `registrations.ts` and add your component.
 
     ```typescript
     const componentRegistrations = [
@@ -43,13 +43,13 @@ The system uses "Registration Objects" created via `defineComponent` or `defineC
 
 ## Registering a New Collection
 
-1.  **Import the Registration**:
+1.  **Import the Registration** in `src/lib/registrations.ts`:
 
     ```typescript
     import { MyCollectionRegistration } from '@/project/collections/MyCollection';
     ```
 
-2.  **Add to `collectionRegistrations`**:
+2.  **Add to `collectionRegistrations`** in `registrations.ts`:
 
     ```typescript
     const collectionRegistrations = [
@@ -61,14 +61,14 @@ The system uses "Registration Objects" created via `defineComponent` or `defineC
 
 ## Adding External Components
 
-External components (like 3rd party forms or iframes) use a separate registry.
+External components (like 3rd party forms or iframes) use a separate registry in `src/lib/registrations.ts`.
 
 1.  **Import**:
     ```typescript
     import { MyExternalWidgetRegistration } from '@/project/externalComponents/MyExternalWidget';
     ```
 
-2.  **Add to `externalComponentRegistrations`**:
+2.  **Add to `externalComponentRegistrations`** in `registrations.ts`:
     ```typescript
     const externalComponentRegistrations = [
         ExternalIFrameRegistration,
@@ -78,7 +78,7 @@ External components (like 3rd party forms or iframes) use a separate registry.
 
 ## Extending Type Definitions
 
-If you introduce new Color names, Button variants, or other enumerations, update the type definitions in `src/lib/cms.ts`:
+If you introduce new Color names, Button variants, or other enumerations, update the type definitions in `src/lib/cms.ts` (types are defined there; registrations live in `registrations.ts`):
 
 ```typescript
 export type CmsColourName = NonNullable<TypeComponentFields['backgroundColour']>['values'];

package/skills/se-marketing-sites/styling-system/SKILL.md

@@ -37,14 +37,18 @@ Styles are responsive and scale automatically based on the breakpoints defined i
 
 ### Best Practice: Dynamic Sizing
 
-Use `getSizingInformation(index)` to dynamically assign the correct heading class based on the component's position on the page or the CMS configuration.
+Use `getSizingInformation(index)` from `@/lib/SizingInformation` to dynamically assign the correct heading class based on the component's position on the page.
 
 ```typescript
+import { getSizingInformation } from '@/lib/SizingInformation';
+
 // Example usage in a component renderer
-const { Element, sizingInformation } = getSizingInformation(size, index);
+const { Element, sizingInformation } = getSizingInformation(index);
 <Element className={sizingInformation.h1}>{title}</Element>
 ```
 
+For embedded content (e.g. inside rich text), pass `embedded: true` as the second argument.
+
 ## Colors
 
 Colors are defined in `colorOptions` within `tailwind.config.json`. The build system generates TypeScript helpers in `@/generated/colors` to access these colors safely.