@se-studio/core-ui 0.0.0-next16-20260822103555

package/dist/utils/wcagRelativeLuminanceFromHex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wcagRelativeLuminanceFromHex.js","sourceRoot":"","sources":["../../src/utils/wcagRelativeLuminanceFromHex.ts"],"names":[],"mappings":"AAAA,MAAM,eAAe,GAAG,oCAAoC,CAAC;AAE7D,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AACnE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,GAAW;IACtD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;IAE1F,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IAC7C,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IAC5C,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IAErC,OAAO,MAAM,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC;AAC9C,CAAC"}

package/dist/utils/wrapHtmlComponentJs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Wraps HtmlComponent `customJs` so `hcRoot` is function-scoped.
+ *
+ * `@se-studio/core-ui` prepends `const hcRoot = …` so authors can query this
+ * instance. Inline `next/script` payloads on one page share a JS realm, so a
+ * second top-level `const hcRoot` throws and the later script never runs.
+ * An IIFE keeps the documented `hcRoot` name without colliding.
+ */
+export declare function wrapHtmlComponentJs(id: string, customJs: string): string;
+//# sourceMappingURL=wrapHtmlComponentJs.d.ts.map

package/dist/utils/wrapHtmlComponentJs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapHtmlComponentJs.d.ts","sourceRoot":"","sources":["../../src/utils/wrapHtmlComponentJs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/utils/wrapHtmlComponentJs.js

@@ -0,0 +1,12 @@
+/**
+ * Wraps HtmlComponent `customJs` so `hcRoot` is function-scoped.
+ *
+ * `@se-studio/core-ui` prepends `const hcRoot = …` so authors can query this
+ * instance. Inline `next/script` payloads on one page share a JS realm, so a
+ * second top-level `const hcRoot` throws and the later script never runs.
+ * An IIFE keeps the documented `hcRoot` name without colliding.
+ */
+export function wrapHtmlComponentJs(id, customJs) {
+    return `(function () {\n  const hcRoot = document.querySelector('[data-hc-id="' + ${JSON.stringify(id)} + '"]');\n${customJs}\n})();`;
+}
+//# sourceMappingURL=wrapHtmlComponentJs.js.map

package/dist/utils/wrapHtmlComponentJs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapHtmlComponentJs.js","sourceRoot":"","sources":["../../src/utils/wrapHtmlComponentJs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAU,EAAE,QAAgB;IAC9D,OAAO,6EAA6E,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,cAAc,QAAQ,SAAS,CAAC;AACxI,CAAC"}

package/docs/PACKAGE_EXPORT_BOUNDARIES.md

@@ -0,0 +1,98 @@
+# `@se-studio/core-ui` — package export boundaries
+
+This doc is for **core-ui maintainers** and **consumer-site developers**. It explains which entry point to use, how to avoid leaking server CMS code into client bundles, and what to do when Next.js reports `server-only` / `contentful-rest-api` errors.
+
+See also: monorepo [`docs/SERVER_CLIENT_BOUNDARIES.md`](../../../docs/SERVER_CLIENT_BOUNDARIES.md) (app-level `cms-server` rules).
+
+## Mental model (SSR is not “server-only”)
+
+Next.js App Router mixes **Server Components** and **Client Components** (`'use client'`) in one module graph. Anything reachable from a client file must be **client-bundle safe**.
+
+| Entry | Who may import | Contents |
+|-------|----------------|----------|
+| `@se-studio/core-ui` | **Everyone** — `'use client'` files, server components, registrations | React UI, hooks, `cn`, CMS renderers, registration helpers, shared types |
+| `@se-studio/core-ui/server` | **Server only** — `import 'server-only'` at top | `createAppHelpers`, `createRouteHandlers`, `getRelated*`, `filterRelatedArticles`, listing structured-data helpers, etc. |
+| `@se-studio/core-ui/route-handlers` | **App route modules** (Node `fs`) | Discovery/guidelines/cms.txt handlers |
+
+**Do not add a `/client` entry** unless you want stricter enforcement. The main barrel *is* the client-safe surface; `/server` is the explicit server escape hatch.
+
+## Rules for maintainers (adding exports to core-ui)
+
+Before exporting a new symbol from `src/index.ts`:
+
+1. **No runtime imports** of `@se-studio/contentful-rest-api` in the main-barrel graph. Type-only imports (`import type`) are OK.
+2. **No `import 'server-only'`** modules re-exported with runtime bindings from `src/index.ts`. Types-only re-exports from server modules are OK (e.g. `export type { AppHelpers } from './app-helpers'`).
+3. **Async CMS fetch helpers** (`getAll*Links`, `filterRelatedArticles`, structured-data builders) belong on **`src/server/index.ts`**, with `import 'server-only'` in the implementing file.
+4. **Pure utilities** (`cn`, breadcrumbs, metadata builders without CMS fetch) stay on the main barrel.
+5. **Dev-only surfaces** (showcase mocks) should eventually move to `@se-studio/core-ui/showcase` so production apps do not pull them through the main barrel.
+
+### Checklist when opening a core-ui PR
+
+- [ ] New CMS / Contentful / Node API code is behind `/server` or `/route-handlers`, not `src/index.ts`.
+- [ ] New server modules include `import 'server-only'` at the top.
+- [ ] `pnpm --filter @se-studio/core-ui test` passes (includes `main-barrel-boundary.test.ts`).
+- [ ] `docs/llms.md` and `README.md` list new server exports under “Server-only exports”.
+- [ ] Consumer apps import new server helpers from `@se-studio/core-ui/server`, not the main entry.
+
+## Rules for consumer sites
+
+### Safe (main entry)
+
+```ts
+import { cn, Visual, CmsContent, getPreviewFieldProps } from '@se-studio/core-ui';
+```
+
+Use in server components **and** `'use client'` files.
+
+### Server only (`/server`)
+
+```ts
+import {
+  createAppHelpers,
+  buildListingStructuredDataContext,
+  filterRelatedArticles,
+} from '@se-studio/core-ui/server';
+```
+
+Use only in server modules (`import 'server-only'` app files, route handlers, `generateMetadata`, etc.). **Never** in `'use client'` files or files imported by registrations that client components transitively load.
+
+### App `cms-server`
+
+Each marketing site’s `src/lib/cms-server.ts` must keep `import 'server-only'`. Client components must not import it. See `docs/SERVER_CLIENT_BOUNDARIES.md`.
+
+## How mistakes surface
+
+Typical Next.js / Turbopack error:
+
+```
+'server-only' cannot be imported from a Client Component module.
+The error was caused by importing '@se-studio/contentful-rest-api/dist/converters'
+```
+
+Import trace often shows:
+
+- `'use client'` file → `@se-studio/core-ui` (main barrel) → server CMS module → `contentful-rest-api`
+
+**Root cause:** a server CMS helper was exported from the main barrel, or a client file imports `/server` / `cms-server`.
+
+## Workarounds (consumer sites, until package is fixed)
+
+Prefer fixing and publishing core-ui. If blocked on an older version:
+
+| Workaround | Use when | Caveats |
+|------------|----------|---------|
+| Import server helpers from `@se-studio/core-ui/server` | You added a server util on the wrong entry in an older core-ui | Requires that symbol to exist on `/server` in your installed version |
+| Local `cn` via `clsx` + `tailwind-merge` | Build fails on `EmailInputForm` / UI importing `cn` from main barrel | Forks a one-liner utility; remove after package fix |
+| `experimental.optimizePackageImports: ['@se-studio/core-ui']` in `next.config` | Turbopack pulls whole barrel for named imports | **Experimental**; Next docs say not recommended for production; behavior differs Webpack vs Turbopack |
+| `pnpm pack` + install local tarball | Verify fix before npm publish | See `scripts/pack-local-packages-for-consumer.sh` |
+
+**Do not** duplicate `ExternalVideoPlayButtonProvider` locally — core-ui video embeds read the package’s own React context module; a local copy breaks custom play buttons.
+
+## Regression test
+
+`packages/core-ui/src/__tests__/main-barrel-boundary.test.ts` asserts the main barrel does not re-export known server CMS modules. Extend it when moving additional exports to `/server`.
+
+## Related incidents
+
+- **filterRelatedArticles** removed from main barrel (core-ui ~1.11) — same class of bug.
+- **listingStructuredData** moved to `/server` (core-ui 1.13.1) — `buildListingItems` / `buildListingStructuredDataContext` had runtime `contentful-rest-api` import on main entry.

package/docs/llms.md

@@ -0,0 +1,358 @@
+# @se-studio/core-ui — LLM Reference
+
+Shared React component library for SE Studio Next.js apps. Provides the CMS rendering system, media components, analytics, and utility hooks.
+
+> **Critical:** This package has a server/client boundary. `@se-studio/core-ui/server` is server-only. Never import server exports in `'use client'` files. Never import from `cms-server` inside component/collection registrations (circular dependency). The **main** entry must stay client-safe — do not add runtime `@se-studio/contentful-rest-api` imports to `src/index.ts`. See `docs/PACKAGE_EXPORT_BOUNDARIES.md` and the server import rules below.
+
+## CMS Rendering System
+
+### CmsContent — primary page renderer
+```tsx
+import { CmsContent } from '@se-studio/core-ui';
+
+// Renders a full page's content array using the app's registered components
+<CmsContent
+  content={page}               // IBasePage (or IBaseArticle, etc.)
+  config={rendererConfig}      // CmsRendererConfig from the app's cms.ts
+  context={{ pageLink: { slug: page.slug, title: page.title } }}
+/>
+```
+
+### CmsComponent / CmsCollection — render a single item
+```tsx
+import { CmsComponent, CmsCollection } from '@se-studio/core-ui';
+
+<CmsComponent information={component} config={rendererConfig} index={0} />
+<CmsCollection information={collection} config={rendererConfig} index={0} />
+```
+
+### CmsRoutesLayout — wraps CMS pages
+```tsx
+import { CmsRoutesLayout } from '@se-studio/core-ui';
+
+// Used in app/[...slug]/layout.tsx to provide breadcrumbs, structured data, etc.
+```
+
+## Registration System
+
+Use these to define components and collections (in the app, not in this package):
+
+```ts
+import { defineComponent, defineCollection, defineDataType } from '@se-studio/core-ui';
+
+export const myComponent = defineComponent({
+  name: 'myComponentType',    // must match Contentful componentType field
+  renderer: MyRenderer,
+  mockData: { ... },
+});
+
+export const myCollection = defineCollection({
+  name: 'myCollectionType',
+  renderer: MyCollectionRenderer,
+  mockData: { ... },
+});
+```
+
+## Heading Hierarchy — getSizingInformation
+
+Use this to pick the correct heading element per component index on the page:
+
+```tsx
+// From the app's SizingInformation module (per-project), not core-ui/server
+
+// In a component renderer:
+const { Element, ChildElement } = getSizingInformation(index);
+// Element     → 'h1' | 'h2' | 'h3' (for the component's main heading)
+// ChildElement → 'h2' | 'h3' | 'h4' (for child headings within the component)
+
+// Render pre/post headings as <p>, never as heading tags:
+<p className="text-sm font-medium">{preHeading}</p>
+<Element className="text-4xl">{heading}</Element>
+```
+
+## Preview (Contentful Live Preview)
+
+```ts
+import {
+  getPreviewFieldProps,
+  getPreviewResponsiveVisualFieldProps,
+} from '@se-studio/core-ui';
+
+// Pass to JSX elements to enable Contentful live preview highlighting
+const fieldProps = getPreviewFieldProps(rendererConfig, entryId, 'heading');
+const visualProps = getPreviewResponsiveVisualFieldProps(rendererConfig, entryId, 'visual', 'mobileVisual');
+```
+
+Do NOT import these from `cms-server`. Import them from `@se-studio/core-ui` in components/collections.
+
+## Visual Components
+
+```tsx
+import { Visual } from '@se-studio/core-ui';
+import { ResponsiveVisual, ContainedVisual } from '@se-studio/core-ui';
+
+// Renders IVisual (image, video, animation, SVG)
+<Visual visual={imageOrVideoData} className="w-full" priority />
+
+// Renders IResponsiveVisual (desktop + optional mobile)
+<ResponsiveVisual visual={responsiveVisual} className="w-full" />
+```
+
+## Rich Text
+
+```tsx
+import { RTF } from '@se-studio/core-ui';
+import { RtfOrString } from '@se-studio/core-ui';
+
+// Render Contentful rich text
+<RTF document={richTextDocument} rendererConfig={rendererConfig} />
+
+// Render either rich text or a plain string
+<RtfOrString value={headingOrRichText} />
+```
+
+## Analytics
+
+```tsx
+import { AnalyticsProvider, useAnalytics, useAnalyticsContext } from '@se-studio/core-ui';
+import { GoogleTagManagerAdapter, ConsentAwareAdapter } from '@se-studio/core-ui';
+
+// Wrap the app:
+<AnalyticsProvider adapters={[new GoogleTagManagerAdapter()]}>
+  {children}
+</AnalyticsProvider>
+
+// Track clicks:
+const { trackClick } = useAnalytics();
+trackClick({ label: 'CTA Button', href: '/signup' });
+```
+
+### Video engagement events
+
+Interactive (non-autoplay) Vimeo, YouTube, and local videos fire `trackEvent` with:
+
+`video_impression` · `video_start` · `video_progress` · `video_complete` · `video_seek` · `video_unmute` · `video_fullscreen` · `video_exit`
+
+Export `VIDEO_ENGAGEMENT_EVENTS` / `VIDEO_ENGAGEMENT_EVENT_NAMES` for GTM or HubSpot `eventNameMap`. Requires `analyticsContext` on the visual chain. Autoplay/background videos are not tracked.
+
+### Play button (external + local)
+
+- Site-wide brand: wrap the app in `ExternalVideoPlayButtonProvider` with a custom icon (see Brightline / SE website / HopSkipDrive).
+- Default: red `DefaultExternalVideoPlayButton`.
+- Non-autoplay **local** ImageKit videos get built-in click-to-play using the same context.
+- Escape hatch: `LocalVideoPlayOverlay` for wrapping an arbitrary `<video>` tree.
+
+## Page Metadata
+
+Validate `baseUrl` at module init (fails the build on misconfiguration). No trailing slash — paths are joined as `` `${baseUrl}${path}` ``:
+
+```ts
+import { assertValidSiteBaseUrl, buildPageMetadata } from '@se-studio/core-ui';
+
+export const baseUrl = assertValidSiteBaseUrl(process.env.URL!);
+
+export async function generateMetadata(): Promise<Metadata> {
+  return buildPageMetadata(page, {
+    baseUrl,
+    customerName: 'point.me',
+    isProduction: process.env.NODE_ENV === 'production',
+    isDevelopment: process.env.NODE_ENV === 'development',
+  }, parent);
+}
+```
+
+### Author and generator meta tags
+
+`buildPageMetadata` sets:
+
+| Page | `<meta name="author">` / `<link rel="author">` | `<meta name="generator">` |
+|------|--------------------------------------------------|---------------------------|
+| Article with CMS author | Primary author name + person page URL | Default: `Something Else (https://www.se.studio)` |
+| Article without author | `customerName` + `baseUrl` | Same |
+| Other pages (pages, listings, person profiles, etc.) | `customerName` + `baseUrl` | Same |
+
+- **Article authors:** only article `generateMetadata` passes `author` / `authors` on the model; other routes omit those fields and get the site default.
+- **Generator override:** `siteGenerator` on `IBuildInformation` — full string, `{ name, url }` parts, or `null` to omit the tag.
+- **Helpers:** `resolveMetadataAuthors`, `formatSiteGeneratorContent`, `SiteGeneratorAttribution`.
+
+JSON-LD (`buildStructuredDataContext`) remains the primary signal for multi-author articles and person entities.
+
+## robots.txt
+
+### Metadata route (no Content-Signal)
+
+Use `createRobotsConfig` in `src/app/robots.ts` when you do not need Content Signals:
+
+```ts
+import { createRobotsConfig } from '@se-studio/core-ui';
+import { isProduction } from '@/lib/config';
+import { baseUrl } from '@/lib/server-config';
+
+export default function robots() {
+  return createRobotsConfig({ isProduction, baseUrl });
+}
+```
+
+Default production disallows: `/*?_rsc=*`, `/_next/data/`, `/api/`, `/preview/`, `/page-test/`, `/cms/`, `/og/`.
+
+**Split-domain sites (Point Me):** pass `pathPrefix` (`SITE_PREFIX`), extra `apiPrefixes` (`/marketing-api/`), `disallowExtra`, `disallowOmit`, and `blockTrackingQueryParams` as needed. Query-string disallows help non-Google crawlers; Google matches path only — pair with strong canonicals.
+
+### Content Signals (recommended for agent readiness)
+
+Next.js `MetadataRoute.Robots` cannot emit `Content-Signal`. Use a route handler:
+
+```ts
+// src/app/robots.txt/route.ts
+import { createRobotsTxtResponse } from '@se-studio/core-ui';
+import { isProduction } from '@/lib/config';
+import { baseUrl } from '@/lib/server-config';
+
+export function GET() {
+  return createRobotsTxtResponse({
+    isProduction,
+    baseUrl,
+    contentSignals: { search: 'yes', aiTrain: 'no', aiInput: 'yes' },
+    // disallowExtra: ['/private/'],
+    // Public agent APIs under /api/ (Google: specific Allow can win over Disallow: /api/):
+    // allowExtra: ['/api/mcp', '/api/search'],
+  });
+}
+```
+
+Also: `formatRobotsTxt`, `formatContentSignalLine`, `buildRobotsDisallow`. `allowExtra` emits extra production `Allow:` lines.
+
+## Agent readiness (Band A)
+
+Helpers for marketing sites that already expose `/{path}.md` and `/llms.txt`:
+
+```ts
+// src/proxy.ts (Next 16) or src/middleware.ts (Next 15) — before A/B rewrites
+import {
+  apiPathNeedingTrailingSlash,
+  appendAgentDiscoveryLinkHeaders,
+  resolveMarkdownNegotiationPath,
+} from '@se-studio/core-ui';
+import { type NextRequest, NextResponse } from 'next/server';
+
+export function proxy(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  // Requires next.config: trailingSlash: true + skipTrailingSlashRedirect: true
+  // (built-in slash 308 runs before proxy and ignores rewrites).
+  // Rewrite bare /api/* so MCP POST is not 308’d; 308 HTML paths yourself if needed.
+  const apiSlashPath = apiPathNeedingTrailingSlash(pathname);
+  if (apiSlashPath) {
+    const url = request.nextUrl.clone();
+    url.pathname = apiSlashPath;
+    return NextResponse.rewrite(url);
+  }
+
+  const markdownPath = resolveMarkdownNegotiationPath(
+    pathname,
+    request.headers.get('accept'),
+  );
+  if (markdownPath) {
+    const url = request.nextUrl.clone();
+    url.pathname = markdownPath;
+    const response = NextResponse.rewrite(url);
+    response.headers.set('Vary', 'Accept');
+    return response;
+  }
+
+  const response = NextResponse.next();
+  appendAgentDiscoveryLinkHeaders(response.headers, pathname);
+  // Ensure caches vary on Accept if you also negotiate elsewhere
+  const vary = response.headers.get('Vary');
+  if (!vary?.toLowerCase().includes('accept')) {
+    response.headers.set('Vary', vary ? `${vary}, Accept` : 'Accept');
+  }
+  return response;
+}
+```
+
+| Helper | Purpose |
+|--------|---------|
+| `prefersMarkdownAccept` | Parse Accept; true when markdown preferred over HTML |
+| `htmlPathToMarkdownPath` | `/` → `/index.md`, `/about/` → `/about.md` |
+| `resolveMarkdownNegotiationPath` | Combine both for middleware rewrite target |
+| `apiPathNeedingTrailingSlash` | Bare `/api/*` → `/api/*/` rewrite target when `trailingSlash: true` (MCP-safe) |
+| `buildAgentDiscoveryLinkValues` / `appendAgentDiscoveryLinkHeaders` | `Link: </llms.txt>; rel="describedby"` + alternate markdown; opt-in `{ mcpServerCard: true }` for `rel="mcp-server-card"` |
+
+**Band B (public site MCP):** use `@se-studio/site-mcp` for a public read-only MCP (typically `/api/mcp`). Pair robots with `allowExtra: ['/api/mcp', '/api/search']` when those endpoints live under a broad `Disallow: /api/`. With Next `trailingSlash: true`, wire `apiPathNeedingTrailingSlash` so POST to `/api/mcp` is not 308’d.
+
+Pure agent path helpers are also available without the main React barrel:
+
+```ts
+import { htmlPathToMarkdownPath } from '@se-studio/core-ui/agent-ready';
+```
+
+### Person profile pages
+
+Best practice:
+
+- **JSON-LD `Person`** (via CMS structured-data templates + `context.person`) is what search engines use for identity, job title, and profile URLs.
+- **`<meta name="author">`:** optional. Common choices:
+  - **Person as author** (name + self URL) — good for dedicated author/bio pages where the person is the content creator.
+  - **Site default** (`customerName`) — fine for corporate team directories where the publisher is the brand.
+- This package currently uses the **site default** on person routes; switch to person-as-author later if SEO requires it (pass person name/href into `buildPageMetadata` from `generatePersonMetadata`).
+
+## Sitemap
+
+```ts
+import { generateNextSitemap, buildSitemap } from '@se-studio/core-ui';
+```
+
+Higher-level marketing site sitemap generation (with article/tag/people indexes, download handling, locales) is enabled by passing `marketingSiteSitemap` config to `createAppHelpers`. The config + your `UrlCalculators` must stay in sync with routes. Full guidance + examples from multiple consumers: see the monorepo `docs/routing.md`.
+
+## Utility Hooks
+
+```ts
+import { useClickTracking } from '@se-studio/core-ui';
+import {
+  useVisibleToUser,
+  useFirstVisibleToUser,
+  useClientOnly,
+} from '@se-studio/core-ui';
+```
+
+## Utility Functions
+
+```ts
+import { cn } from '@se-studio/core-ui';           // clsx/tailwind-merge
+import { convertText } from '@se-studio/core-ui';  // process text content
+import { getCurrentPageUrl } from '@se-studio/core-ui';
+import { handleCmsError } from '@se-studio/core-ui';
+```
+
+## Server-Only Exports (`@se-studio/core-ui/server`)
+
+These are server-only — do NOT import in `'use client'` files or component registrations:
+
+```ts
+import { createRouteHandlers } from '@se-studio/core-ui/server';
+import { getRelatedArticles, getRelatedPeople, getRelatedTags } from '@se-studio/core-ui/server';
+import { filterRelatedArticles, type RelatedArticlesOptions } from '@se-studio/core-ui/server';
+import {
+  buildListingItems,
+  buildListingStructuredDataContext,
+} from '@se-studio/core-ui/server';
+import type { CmsRouteConfig } from '@se-studio/core-ui/server';
+```
+
+`CmsRouteConfig.requireArticleContent` (default `true`): set to `false` on article detail routes to allow metadata/template-only articles without body components.
+
+**A/B page-test routes** (`/page-test/[...slugs]`): use the paired handlers from `createRouteHandlers`:
+
+- `generatePageTestMetadata(variantSlug, canonicalSlug, canonicalPath, routeConfig, parent)` — merges control `indexed` into `<head>` metadata
+- `generatePageTest(variantSlug, canonicalSlug, canonicalPath, routeConfig)` — renders variant `contents` but overlays control `href` and `breadcrumbTitle` on the layout model; passes `currentPath={canonicalPath}` to `LayoutComponent`
+
+Resolve canonical path with `findCanonicalPath(testsByPath, variantSlug)` from `@se-studio/ab-testing`.
+
+`getRelatedArticles` tag criteria: explicit tag links in the collection → `pageContext.tag` → `pageContext.article.tags`. Pass via `rendererConfig.fetchHelpers.getRelatedArticles` in collections (do not import `cms-server` in registrations). Curated article/person/tag refs in `contents` are **selection and order only** — `getRelated*` helpers always hydrate from `getAll*Links` so publish webhooks revalidate link-shaped UI. For full-list cases (News Grids, Publications Lists, person-scoped or tag-filtered indexes) use `rendererConfig.fetchHelpers.getAllArticleLinks?.({ articleTypeSlugs: [...], tagSlugs: [...], authorIds: [...], strictAuthorMatch: true, ... })` — the wrapper applies `filterRelatedArticles` (OR semantics, scoring, indexed rules). Import `filterRelatedArticles` / `RelatedArticlesOptions` (and the richer `LinkFetchOptions`) from `@se-studio/core-ui/server`. For all people (e.g. team index collections), use `rendererConfig.fetchHelpers.getAllPersonLinks?.()` — returns `CmsResponse<IPersonLink[]>` including resolved `bio` when set. For related tag chips/lists, use `rendererConfig.fetchHelpers.getRelatedTags?.(information, contentContext, count)`.
+
+## Server/Client Rules
+
+1. Never import `cms-server` (or anything that imports it) in a client component.
+2. Never import preview helpers from `cms-server` inside component/collection files — use `getPreviewFieldProps` from `@se-studio/core-ui` instead.
+3. Pass `previewHelpers` as a prop to `<Section>` and `rendererConfig` to `<SectionLinks>`.
+4. Server components can call Contentful fetch functions; client components cannot.

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@se-studio/core-ui",
+  "version": "0.0.0-next16-20260822103555",
+  "description": "Shared React UI component library with Tailwind CSS v4 for SE Studio applications",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Something-Else-Studio/se-core-product",
+    "directory": "packages/core-ui"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./route-handlers": {
+      "types": "./dist/route-handlers/index.d.ts",
+      "import": "./dist/route-handlers/index.js"
+    },
+    "./agent-ready": {
+      "types": "./dist/utils/agent-ready.d.ts",
+      "import": "./dist/utils/agent-ready.js"
+    }
+  },
+  "files": [
+    "dist",
+    "*.md",
+    "docs",
+    "src/showcase/README.md"
+  ],
+  "keywords": [
+    "react",
+    "components",
+    "ui",
+    "tailwind",
+    "tailwindcss",
+    "design-system",
+    "typescript",
+    "contentful",
+    "cms",
+    "nextjs",
+    "next.js",
+    "ui-library",
+    "component-library",
+    "rich-text",
+    "analytics"
+  ],
+  "homepage": "https://github.com/Something-Else-Studio/se-core-product#readme",
+  "bugs": {
+    "url": "https://github.com/Something-Else-Studio/se-core-product/issues"
+  },
+  "peerDependencies": {
+    "@lottiefiles/dotlottie-react": "^0.19.0",
+    "@lottiefiles/lottie-player": "^2.0.0",
+    "next": ">=15.5.0 <17",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@lottiefiles/dotlottie-react": {
+      "optional": true
+    },
+    "@lottiefiles/lottie-player": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@contentful/live-preview": "^4.10.12",
+    "@contentful/rich-text-react-renderer": "^16.2.1",
+    "@contentful/rich-text-types": "^17.2.7",
+    "@radix-ui/react-slot": "^1.3.3",
+    "@types/mustache": "4.2.6",
+    "@vimeo/player": "^2.30.4",
+    "clsx": "^2.1.1",
+    "hls.js": "^1.6.16",
+    "html-entities": "^2.6.0",
+    "mustache": "4.2.0",
+    "server-only": "0.0.1",
+    "tailwind-merge": "^3.6.0",
+    "@se-studio/contentful-rest-api": "0.0.0-next16-20260822103555",
+    "@se-studio/core-data-types": "1.12.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.5",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^29.1.1",
+    "next": "^16.3.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "dev": "tsc --project tsconfig.build.json --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "biome lint .",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
+}