@se-studio/project-build 1.0.131 → 1.0.133

package/skills/se-marketing-sites/curate-showcase-mocks/SKILL.md

@@ -1,343 +0,0 @@
----
-name: curate-showcase-mocks
-description: Extracts real component/collection data from Contentful and curates the best examples into showcase-mocks.json, making the CMS showcase display realistic content instead of generic placeholder text.
-license: Private
-metadata:
-  author: se-core-product
-  version: "2.1.0"
----
-
-# Curate Showcase Mocks
-
-This skill refreshes the CMS showcase with realistic content from the live Contentful space.
-It uses a **two-phase CLI pipeline** — extraction followed by LLM-driven curation — to produce
-`src/generated/showcase-mocks.json`, which the showcase loads at runtime.
-
-It is **Step 2** of **`update-cms-guidelines`** mode **`fresh`** (after the clean slate). Realistic mocks and `accepted-variants` files are **required** before bulk screenshot capture in **generate-all-guidelines**.
-
-## When to use
-
-Run this skill when:
-- A new app has been populated in Contentful and the showcase still shows placeholder text
-- The CMS content has been significantly updated and the showcase looks stale
-- New component or collection types have been added and need good mock data
-- You are doing a **full CMS guidelines regeneration** and need fresh showcase data before Phase 1 / 1b screenshots
-
-## Prerequisites
-
-- The app's `.env.local` must contain `CONTENTFUL_SPACE_ID`, `CONTENTFUL_ACCESS_TOKEN`, and `CONTENTFUL_ENVIRONMENT_NAME`
-- An LLM API key in `.env.local`: `OPENAI_API_KEY` (preferred) or `ANTHROPIC_API_KEY`
-- Optional: `CONTENTFUL_PREVIEW_ACCESS_TOKEN` to also include draft/unpublished entries
-- For monorepo apps: all packages must be built (`pnpm build` from repo root)
-- The app must be fully set up (see **First-time setup** below if not yet done)
-
-## First-time setup (new apps)
-
-Before running this skill on a new app, four one-time changes are required.
-
-### 1 — Add scripts to `package.json`
-
-**Monorepo app** (uses local packages via relative paths):
-
-```json
-"generate-showcase": "node ../../packages/project-build/dist/generate-showcase-data.js",
-"generate-showcase-mocks": "node ../../packages/project-build/dist/generate-showcase-mocks.js"
-```
-
-**External/standalone project** (uses npm-installed packages):
-
-```json
-"generate-showcase": "node node_modules/@se-studio/project-build/dist/generate-showcase-data.js",
-"generate-showcase-mocks": "node node_modules/@se-studio/project-build/dist/generate-showcase-mocks.js"
-```
-
-Alternatively for external projects, use the installed binaries directly (available on PATH after install):
-
-```bash
-generate-showcase-data       # runs in-place from the project root
-generate-showcase-mocks
-```
-
-### 2 — Gitignore the generated files
-
-In the app's `.gitignore`, add:
-
-```
-# Generated showcase files (large, regenerable — curated mocks committed separately)
-src/generated/showcase-examples.json
-src/generated/showcase-mocks-draft.json
-src/generated/cms-discovery/accepted-variants/
-```
-
-### 3 — Wire the render pages to use curated mocks
-
-Both `src/app/(cms-dev)/cms/showcase/render/page.tsx` and `render-all/page.tsx` need to import
-`mergeShowcaseMocks` and the curated mocks file.
-
-**`render/page.tsx`** — change from:
-
-```tsx
-import { DEFAULT_SHOWCASE_CONTROL_STATE, ShowcaseRenderPage } from '@se-studio/core-ui';
-// ... other imports ...
-
-export default async function Page(...) {
-  return (
-    <ShowcaseRenderPage
-      componentMockMap={componentMockMap}
-      collectionMockMap={collectionMockMap}
-      collectionCardMockMap={collectionCardMockMap}
-      ...
-    />
-  );
-}
-```
-
-to:
-
-```tsx
-import { DEFAULT_SHOWCASE_CONTROL_STATE, ShowcaseRenderPage, mergeShowcaseMocks } from '@se-studio/core-ui';
-// ... other imports ...
-import curatedMocks from '@/generated/showcase-mocks.json';
-
-const { componentMockMap: mergedComponentMocks, collectionMockMap: mergedCollectionMocks, collectionCardMockMap: mergedCardMocks } =
-  mergeShowcaseMocks(curatedMocks, { componentMockMap, collectionMockMap, collectionCardMockMap });
-
-export default async function Page(...) {
-  return (
-    <ShowcaseRenderPage
-      componentMockMap={mergedComponentMocks}
-      collectionMockMap={mergedCollectionMocks}
-      collectionCardMockMap={mergedCardMocks}
-      ...
-    />
-  );
-}
-```
-
-Apply the same pattern to **`render-all/page.tsx`**.
-
-### 4 — Create an empty `showcase-mocks.json` stub
-
-Create `src/generated/showcase-mocks.json` so the import compiles before curated data exists:
-
-```json
-{
-  "curatedAt": "2026-01-01T00:00:00.000Z",
-  "components": {},
-  "collections": {}
-}
-```
-
-Once these four steps are done, proceed with the steps below.
-
----
-
-## Pipeline Overview
-
-The workflow is now a **three-step pipeline**:
-
-```
-Step 1: generate-showcase-data   → showcase-examples.json  (all CMS data, sorted by completeness)
-Step 2: generate-showcase-mocks  → showcase-mocks-draft.json  (LLM selects best + proposes variants)
-Step 3: AI review (this skill)   → showcase-mocks.json  (final curated mocks, committed)
-```
-
-Steps 1 and 2 are automated CLI commands. Step 3 is where you (the AI) review the draft,
-adjust anything the LLM got wrong, handle layout variants, and write the final committed file.
-
----
-
-## Steps
-
-### Step 1 — Run the extraction script
-
-Run the CLI to fetch all component/collection entries from Contentful:
-
-**Monorepo:**
-```bash
-pnpm --filter {appName} generate-showcase
-```
-
-**External project (from project root):**
-```bash
-node node_modules/@se-studio/project-build/dist/generate-showcase-data.js
-```
-
-**Optional flags:**
-- `--include-drafts` — also fetches draft/unpublished entries via the Preview API (requires `CONTENTFUL_PREVIEW_ACCESS_TOKEN`)
-- `--all-types` — fetches all entry content types without a filter (instead of fetching component and collection separately)
-
-This writes `src/generated/showcase-examples.json` — every example grouped by type, sorted by
-`fieldCompleteness` descending. This file is gitignored.
-
-### Step 2 — Run the LLM curation script
-
-**Monorepo:**
-```bash
-pnpm --filter {appName} generate-showcase-mocks
-```
-
-**External project:**
-```bash
-node node_modules/@se-studio/project-build/dist/generate-showcase-mocks.js
-```
-
-This reads `showcase-examples.json`, calls the LLM (OpenAI or Anthropic — auto-detected from
-`.env.local`), and produces:
-- `src/generated/showcase-mocks-draft.json` — best mock per type + proposed variant param sets
-- `src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<slug>.json` — per-type variant files (in mode subdir)
-
-**Optional flags:**
-- `--model <model>` — override the LLM model (e.g. `--model gpt-4o`)
-- `--types <Type1,Type2>` — limit to specific type names (comma-separated, useful for re-running single types)
-
-### Step 3 — Read the draft and registrations
-
-Read these files:
-
-1. `src/generated/showcase-mocks-draft.json` — the LLM's selected mocks + variant proposals
-2. `src/lib/registrations.ts` — the app's component/collection registrations
-
-From the registrations file, collect:
-- The full list of registered component type names
-- The full list of registered collection type names
-- Any registrations with `showcaseExclude: true` — these types must be skipped entirely
-
-Check the draft against the registrations: are there registered types missing from the draft?
-If so, check `showcase-examples.json` directly to find examples for those types.
-
-### Step 4 — Review and refine mocks
-
-For each type in the draft:
-
-**Validate the LLM selection:**
-- Confirm the selected mock has a real heading (not a test entry)
-- Confirm it has a working visual URL (if the field exists)
-- Confirm the mock fields are complete and reflect real brand content
-
-**Add layout variants not in the CMS:**
-Some types have meaningful variants that may not exist as separate CMS entries — a flipped
-layout, a narrow/wide version, or a no-visual state. These can be represented by adjusting
-the base mock with URL param overrides. Review each type's variant proposals from the LLM
-(in `showcase-mocks-draft.json`) and add any important ones that are missing:
-
-- For a Hero with a left-layout variant: add a variant with `{ "showcaseParams": { "flip": "true" } }` or similar
-- For a content block with a narrow option: `{ "showcaseParams": { "width": "narrow" } }`
-- Adjust the LLM's proposed params to match the actual param names used in the component's showcase controls
-
-**For collections — curating cards:**
-- Select ALL cards from the best example (do not cap — use the real count)
-- If fewer than 4 cards, check the next-best example for additional cards
-- Cards with no heading and no body are useless — skip them
-
-### Step 5 — Write showcase-mocks.json
-
-Write the curated data to `src/generated/showcase-mocks.json`. This file IS committed to git.
-
-Use the LLM draft as the starting point and apply your corrections from Step 4.
-
-**Format:**
-
-```json
-{
-  "curatedAt": "2026-02-28T14:00:00.000Z",
-  "components": {
-    "Hero": {
-      "heading": "Mental health care for kids and teens. Parenting support for you.",
-      "preHeading": "Brightline",
-      "body": { "json": { "nodeType": "document", "content": [...] } },
-      "visual": { "width": 1200, "height": 800, "url": "https://images.ctfassets.net/..." },
-      "backgroundColour": "Off White"
-    }
-  },
-  "collections": {
-    "FAQ": {
-      "mock": { "heading": "Top FAQs" },
-      "cards": [
-        { "heading": "Who is Brightline?", "body": { "json": { ... } } }
-      ]
-    }
-  }
-}
-```
-
-**Rules for the output:**
-- Set `curatedAt` to the current ISO timestamp
-- Only include types that have real CMS data
-- For component mocks: include only fields present in the source data
-- For collection mocks: always include `mock` and `cards`
-- Rich Text body fields must be `{ "json": <Document> }` — copy as-is
-- Visual fields must include `width`, `height`, AND `url` — never strip `url`
-- Include `widthPercent` when present on media/externalVideo entries
-- Include `otherMedia` when present — copy the full array including `url` and `widthPercent`
-- Do NOT invent or modify content — use the real data from the examples file
-- Include `backgroundColour` and `textColour` where the source has them
-- For cards: include ALL fields present in source, including `backgroundColour`, `textColour`, `links`
-
-### Step 6 — Verify
-
-After writing, briefly confirm:
-- The file is valid JSON
-- Component and collection counts look reasonable (non-zero)
-- Key types (Hero, main collections) have entries
-- Visual fields include `url` properties
-
----
-
-## Output files
-
-| File | Location | Committed |
-|------|----------|-----------|
-| `showcase-examples.json` | `src/generated/showcase-examples.json` | No (gitignored) |
-| `showcase-mocks-draft.json` | `src/generated/showcase-mocks-draft.json` | No (gitignored) |
-| `accepted-variants/` | `src/generated/cms-discovery/accepted-variants/{components\|collections\|externals}/` | No (gitignored) |
-| `showcase-mocks.json` | `src/generated/showcase-mocks.json` | Yes |
-
----
-
-## How the showcase uses this
-
-The showcase uses a **two-layer model**:
-
-1. **Base: mock data** — `showcase-mocks.json` is merged over inline registration mocks via
-   `mergeShowcaseMocks()` from `@se-studio/core-ui`. Curated data takes precedence; types without
-   curated data fall back to their inline `mock:` in the registration.
-
-2. **Patch: URL params** — Any control field in the URL (e.g. `?backgroundColour=Navy`) overrides
-   the mock. The control bar encodes only values that differ from the mock baseline.
-
-`?clean=true` skips mock data entirely and uses the default showcase control state only.
-
----
-
-## External project setup (seskills)
-
-### Installing skills
-
-For standalone projects not in the monorepo, install or update skills via:
-
-```bash
-seskills sync
-```
-
-This copies all SE Studio cursor skills (including this one) into the project's `.agents/skills/`
-directory. The `seskills` binary is provided by `@se-studio/project-build`.
-
-### Auto-sync on package update
-
-Add a `postinstall` script to the project's `package.json` so skills automatically sync
-whenever `pnpm install` is run (including after bumping `@se-studio/project-build`):
-
-```json
-"postinstall": "seskills sync --if-installed"
-```
-
-The `--if-installed` flag makes the sync a no-op if run inside the monorepo itself
-(where `project-build` is a workspace package, not an installed npm package), so it
-is safe to add to any project.
-
-### Script paths
-
-The CLI scripts are available as installed binaries after `npm install @se-studio/project-build`.
-Both `generate-showcase-data` and `generate-showcase-mocks` read `.env.local` from `process.cwd()`,
-so run them from the project root.

package/skills/se-marketing-sites/handling-media/SKILL.md

@@ -1,195 +0,0 @@
----
-name: handling-media
-description: Guide for using images, videos, and animations in marketing sites using the ResponsiveVisual and VisualComponent systems.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.0.0"
----
-
-# Handling Media
-
-This project uses a unified media system to handle images, videos, and animations efficiently.
-
-## Core Components
-
-### 1. `ResponsiveVisual` (or `VisualComponent`)
-
-This is the main component for rendering media from Contentful. It handles:
-*   Responsive image sources (desktop/mobile).
-*   Format optimization (WebP/AVIF).
-*   Video auto-play/looping.
-*   Lottie animations.
-*   Lazy loading & Priority hints.
-
-```typescript
-import VisualComponent from '@/framework/VisualComponent';
-// or
-import { Visual } from '@se-studio/core-ui';
-```
-
-## Usage Pattern
-
-### Basic Usage
-
-```typescript
-<VisualComponent
-  visual={field.visual}
-  className="w-full h-auto"
-/>
-```
-
-### Responsive Sizing (`visualSizes`)
-
-You **MUST** provide `visualSizes` to ensure the browser loads the correct image size. This uses the `sizes` attribute.
-
-```typescript
-import { calculateVisualSizes } from '@se-studio/core-ui';
-
-// Example: Full width on mobile, 50% width on laptop
-const sizes = calculateVisualSizes(1, { laptop: 0.5 });
-
-<VisualComponent
-  visual={visual}
-  visualSizes={sizes}
-/>
-```
-
-*   `1`: 100vw (Mobile default)
-*   `laptop: 0.5`: 50vw (Laptop breakpoint)
-
-### visualSizes Must Mirror Col-Span
-
-`visualSizes` **must** match the visual's layout (col-span, container width). The browser uses these values to pick the right image size.
-
-*   **Rule**: `col-span-N` in a 12-col grid → use `N/12` (e.g. 6 cols → 0.5, 5 cols → 5/12).
-*   **Full width** (`col-span-full`) → use `1`.
-*   **First arg** = mobile/default; breakpoint keys (`laptop`, `tablet`, `desktop`) = that breakpoint.
-*   **Common mistake**: Reversing mobile vs laptop. If mobile is full width and laptop is smaller, use `(1, { laptop: 0.5 })`, **not** `(0.5, { laptop: 1 })`.
-*   **Fixed-size icons** (~96–128px): use small ratios like `0.2`–`0.25`; **never** use values > 1 (e.g. `(100)` is invalid and causes massive over-fetch).
-*   **Example table**:
-
-| Layout | visualSizes |
-|--------|-------------|
-| Full width | `(1)` |
-| 6 cols on laptop, full on mobile | `(1, { laptop: 0.5 })` |
-| 5 cols on laptop, full on mobile | `(1, { laptop: 5/12 })` |
-| 2 cols in 12 on laptop, half on mobile | `(0.5, { laptop: 2/12 })` |
-| Small icon (~96px) | `(0.25)` |
-
-### CMS Width & Position (`widthPercent`, `horizontalPosition`)
-
-Visuals in Contentful can have a `widthPercent` (e.g. 50%) and `horizontalPosition` (Left / Middle / Right). These control how wide the visual renders on laptop+ and where it aligns within its container. **How these fields are applied depends on the component rendering the visual.**
-
-**Key principle**: The `Visual` component is a "fill my container" renderer — it does **not** apply width constraints itself. Width and position are always the responsibility of the wrapping component.
-
-#### Which components handle it automatically
-
-*   **`VisualComponent`** (framework, `@/framework/VisualComponent`): Handles `widthPercent` and `horizontalPosition` in both embedded and non-embedded modes. Also adjusts `visualSizes` so the browser fetches an appropriately sized image.
-*   **`ResponsiveVisual`** (core-ui): Wraps the `Visual` in a div that applies `--image-width` and horizontal positioning. Components using `ResponsiveVisual` get this for free.
-
-#### Custom components using `Visual` directly
-
-If your component renders `Visual` directly and the visual may have a `widthPercent`, you must handle it yourself:
-
-1.  **Wrap in a positioning div** using helpers from `core-ui`:
-
-```typescript
-import { getVisualWidthPercent } from '@se-studio/core-data-types';
-import {
-  calculateHorizontalPositionClassName,
-  calculateImageWidthStyleVariable,
-  calculateVisualSizes,
-  Visual,
-  cn,
-} from '@se-studio/core-ui';
-
-const imageWidthStyle = calculateImageWidthStyleVariable(visual);
-const imageHorizontalPosition = imageWidthStyle
-  ? calculateHorizontalPositionClassName(visual)
-  : undefined;
-
-<div
-  className={cn(
-    'w-full',
-    imageHorizontalPosition,
-    imageWidthStyle && 'laptop:w-(--image-width)',
-  )}
-  style={imageWidthStyle}
->
-  <Visual visual={visual} visualSizes={visualSizes} />
-</div>
-```
-
-2.  **Factor width into `visualSizes`** so the browser doesn't over-fetch:
-
-```typescript
-const widthPercent = getVisualWidthPercent(visual);
-const laptopRatio = widthPercent ? widthPercent / 100 : undefined;
-const visualSizes = laptopRatio
-  ? calculateVisualSizes(1, { laptop: laptopRatio })
-  : calculateVisualSizes(1);
-```
-
-#### Collections with multiple visuals
-
-Collections like `SeparatedVisualsCollection` may interpret `widthPercent` differently — as relative proportions between visuals rather than absolute percentages. The collection controls the layout and passes the computed slot width to `visualSizes`. Don't apply the standard wrapper pattern blindly in collections; match `visualSizes` to the actual rendered slot width.
-
-### LCP Optimization (`calculateImagePriority`)
-
-For the Hero component (or whatever is at the top of the page), you must prioritize the image load to improve LCP (Largest Contentful Paint).
-
-Use `calculateImagePriority(index)` where `index` is the component's position on the page.
-
-```typescript
-import { calculateImagePriority } from '@se-studio/core-ui';
-
-<VisualComponent
-  visual={visual}
-  {...calculateImagePriority(index)}
-/>
-```
-
-If `index` is `0`, this sets `priority={true}` (or `fetchPriority="high"`). If `index > 0`, it defaults to lazy loading.
-
-### Analytics Tracking
-
-Pass `componentLabel` (usually `cmsLabel`) and `analyticsContext` to enable click tracking on media elements (if they are linked).
-
-```typescript
-<VisualComponent
-  visual={visual}
-  componentLabel={cmsLabel}
-  analyticsContext={contentContext.analyticsContext}
-/>
-```
-
-## Media Types
-
-The `IResponsiveVisual` type (from `@se-studio/core-data-types`) supports:
-
-1.  **Image**: Standard Contentful image asset.
-2.  **Video**: Hosted video file (mp4/webm). The component handles `<video>` tag rendering with autoplay/loop/muted attributes suitable for background videos.
-3.  **Animation**: Lottie JSON file. Renders using a Lottie player.
-
-The component automatically detects the type and renders the appropriate element.
-
-## Mobile Specific Visuals
-
-Contentful models often support a separate `mobileVisual` field. The `VisualComponent` handles switching between them using `<picture>` tags or CSS media queries internally.
-
-You typically pass the combined object or handle it via props if the component exposes both:
-
-```typescript
-// If your component merges them into one responsive object before rendering:
-<VisualComponent visual={combinedVisual} />
-```
-
-Or if using raw fields:
-
-```typescript
-<VisualComponent
-  visual={visual}
-  mobileVisual={mobileVisual}
-/>
-```

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

@@ -1,83 +0,0 @@
----
-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**, **example-om1**.
-
-## File Responsibilities
-
-| File | Client-safe? | Purpose |
-|------|--------------|---------|
-| `cms.ts` | Yes | Types, buildComponentRecord / buildCollectionRecord / buildExternalRecord (array → Record), then build*Maps from those Records, createConverterContext |
-| `cms-server.ts` | No (server-only) | createAppHelpers, buildOptions, getContentfulConfig, projectRendererConfig |
-| `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 | componentRegistrationsList, collectionRegistrationsList, externalComponentRegistrationsList (arrays) |
-| `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 (*RegistrationsList arrays)
-       →  cms.ts (build*Record from arrays, then build*Maps)
-       →  builds maps  →  cms-server.ts
-                                ↓
-                      projectRendererConfig
-```
-
-Add new components/collections to the appropriate *RegistrationsList array in `registrations.ts`. The `cms.ts` imports those arrays, builds Records via `buildComponentRecord` / `buildCollectionRecord` / `buildExternalRecord` (which enforce that every CMS type has a registration), then builds the maps used by `cms-server.ts`.
-
-## Circular Dependency: Do Not Import cms-server in Components/Collections
-
-Components and collections in the registration chain (imported by `registrations.ts`) must **not** import from `cms-server` directly. Doing so creates a circular dependency (cms-server → cms → registrations → components → cms-server) that causes TDZ errors during RSC serialization.
-
-**Instead**, use the helpers from `@se-studio/core-ui`:
-
-- `getPreviewFieldProps(rendererConfig, id, fieldId)` – for field preview props
-- `getPreviewResponsiveVisualFieldProps(rendererConfig, id, visualFieldId, mobileVisualFieldId)` – for responsive visuals
-- `rendererConfig.previewHelpers?.getPreviewParentProps?.(information)`
-- `rendererConfig.fetchHelpers?.getAllArticleLinks?.()`
-- `rendererConfig.fetchHelpers?.getRelatedArticles?.(information, contentContext, count)`
-
-These are passed via `projectRendererConfig` in `cms-server.ts`. `Section` and `SectionLinks` accept `previewHelpers` / `rendererConfig` props. See `docs/SERVER_CLIENT_BOUNDARIES.md`.
-
-## See Also
-
-- **register-cms-features** – Adding components and collections
-- **cms-routes-and-appshared** – Route structure and appShared