@cubis/foundry 0.3.31 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/next-best-practices/metadata.md

@@ -0,0 +1,301 @@
+# Metadata
+
+Add SEO metadata to Next.js pages using the Metadata API.
+
+## Important: Server Components Only
+
+The `metadata` object and `generateMetadata` function are **only supported in Server Components**. They cannot be used in Client Components.
+
+If the target page has `'use client'`:
+1. Remove `'use client'` if possible, move client logic to child components
+2. Or extract metadata to a parent Server Component layout
+3. Or split the file: Server Component with metadata imports Client Components
+
+## Static Metadata
+
+```tsx
+import type { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  title: 'Page Title',
+  description: 'Page description for search engines',
+}
+```
+
+## Dynamic Metadata
+
+```tsx
+import type { Metadata } from 'next'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  const post = await getPost(slug)
+  return { title: post.title, description: post.description }
+}
+```
+
+## Avoid Duplicate Fetches
+
+Use React `cache()` when the same data is needed for both metadata and page:
+
+```tsx
+import { cache } from 'react'
+
+export const getPost = cache(async (slug: string) => {
+  return await db.posts.findFirst({ where: { slug } })
+})
+```
+
+## Viewport
+
+Separate from metadata for streaming support:
+
+```tsx
+import type { Viewport } from 'next'
+
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  themeColor: '#000000',
+}
+
+// Or dynamic
+export function generateViewport({ params }): Viewport {
+  return { themeColor: getThemeColor(params) }
+}
+```
+
+## Title Templates
+
+In root layout for consistent naming:
+
+```tsx
+export const metadata: Metadata = {
+  title: { default: 'Site Name', template: '%s | Site Name' },
+}
+```
+
+## Metadata File Conventions
+
+Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions
+
+Place these files in `app/` directory (or route segments):
+
+| File | Purpose |
+|------|---------|
+| `favicon.ico` | Favicon |
+| `icon.png` / `icon.svg` | App icon |
+| `apple-icon.png` | Apple app icon |
+| `opengraph-image.png` | OG image |
+| `twitter-image.png` | Twitter card image |
+| `sitemap.ts` / `sitemap.xml` | Sitemap (use `generateSitemaps` for multiple) |
+| `robots.ts` / `robots.txt` | Robots directives |
+| `manifest.ts` / `manifest.json` | Web app manifest |
+
+## SEO Best Practice: Static Files Are Often Enough
+
+For most sites, **static metadata files provide excellent SEO coverage**:
+
+```
+app/
+├── favicon.ico
+├── opengraph-image.png     # Works for both OG and Twitter
+├── sitemap.ts
+├── robots.ts
+└── layout.tsx              # With title/description metadata
+```
+
+**Tips:**
+- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
+- Static `title` and `description` in layout metadata is sufficient for most pages
+- Only use dynamic `generateMetadata` when content varies per page
+
+---
+
+# OG Image Generation
+
+Generate dynamic Open Graph images using `next/og`.
+
+## Important Rules
+
+1. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
+2. **No searchParams** - OG images can't access search params, use route params instead
+3. **Avoid Edge runtime** - Use default Node.js runtime
+
+```tsx
+// Good
+import { ImageResponse } from 'next/og'
+
+// Bad
+// import { ImageResponse } from '@vercel/og'
+// export const runtime = 'edge'
+```
+
+## Basic OG Image
+
+```tsx
+// app/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export const alt = 'Site Name'
+export const size = { width: 1200, height: 630 }
+export const contentType = 'image/png'
+
+export default function Image() {
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          fontSize: 128,
+          background: 'white',
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        Hello World
+      </div>
+    ),
+    { ...size }
+  )
+}
+```
+
+## Dynamic OG Image
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export const alt = 'Blog Post'
+export const size = { width: 1200, height: 630 }
+export const contentType = 'image/png'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export default async function Image({ params }: Props) {
+  const { slug } = await params
+  const post = await getPost(slug)
+
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          fontSize: 48,
+          background: 'linear-gradient(to bottom, #1a1a1a, #333)',
+          color: 'white',
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: 48,
+        }}
+      >
+        <div style={{ fontSize: 64, fontWeight: 'bold' }}>{post.title}</div>
+        <div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
+      </div>
+    ),
+    { ...size }
+  )
+}
+```
+
+## Custom Fonts
+
+```tsx
+import { ImageResponse } from 'next/og'
+import { join } from 'path'
+import { readFile } from 'fs/promises'
+
+export default async function Image() {
+  const fontPath = join(process.cwd(), 'assets/fonts/Inter-Bold.ttf')
+  const fontData = await readFile(fontPath)
+
+  return new ImageResponse(
+    (
+      <div style={{ fontFamily: 'Inter', fontSize: 64 }}>
+        Custom Font Text
+      </div>
+    ),
+    {
+      width: 1200,
+      height: 630,
+      fonts: [{ name: 'Inter', data: fontData, style: 'normal' }],
+    }
+  )
+}
+```
+
+## File Naming
+
+- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
+- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)
+
+## Styling Notes
+
+ImageResponse uses Flexbox layout:
+- Use `display: 'flex'`
+- No CSS Grid support
+- Styles must be inline objects
+
+## Multiple OG Images
+
+Use `generateImageMetadata` for multiple images per route:
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export async function generateImageMetadata({ params }) {
+  const images = await getPostImages(params.slug)
+  return images.map((img, idx) => ({
+    id: idx,
+    alt: img.alt,
+    size: { width: 1200, height: 630 },
+    contentType: 'image/png',
+  }))
+}
+
+export default async function Image({ params, id }) {
+  const images = await getPostImages(params.slug)
+  const image = images[id]
+  return new ImageResponse(/* ... */)
+}
+```
+
+## Multiple Sitemaps
+
+Use `generateSitemaps` for large sites:
+
+```tsx
+// app/sitemap.ts
+import type { MetadataRoute } from 'next'
+
+export async function generateSitemaps() {
+  // Return array of sitemap IDs
+  return [{ id: 0 }, { id: 1 }, { id: 2 }]
+}
+
+export default async function sitemap({
+  id,
+}: {
+  id: number
+}): Promise<MetadataRoute.Sitemap> {
+  const start = id * 50000
+  const end = start + 50000
+  const products = await getProducts(start, end)
+
+  return products.map((product) => ({
+    url: `https://example.com/product/${product.id}`,
+    lastModified: product.updatedAt,
+  }))
+}
+```
+
+Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/next-best-practices/parallel-routes.md

@@ -0,0 +1,287 @@
+# Parallel & Intercepting Routes
+
+Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.
+
+## File Structure
+
+```
+app/
+├── @modal/                    # Parallel route slot
+│   ├── default.tsx            # Required! Returns null
+│   ├── (.)photos/             # Intercepts /photos/*
+│   │   └── [id]/
+│   │       └── page.tsx       # Modal content
+│   └── [...]catchall/         # Optional: catch unmatched
+│       └── page.tsx
+├── photos/
+│   └── [id]/
+│       └── page.tsx           # Full page (direct access)
+├── layout.tsx                 # Renders both children and @modal
+└── page.tsx
+```
+
+## Step 1: Root Layout with Slot
+
+```tsx
+// app/layout.tsx
+export default function RootLayout({
+  children,
+  modal,
+}: {
+  children: React.ReactNode;
+  modal: React.ReactNode;
+}) {
+  return (
+    <html>
+      <body>
+        {children}
+        {modal}
+      </body>
+    </html>
+  );
+}
+```
+
+## Step 2: Default File (Critical!)
+
+**Every parallel route slot MUST have a `default.tsx`** to prevent 404s on hard navigation.
+
+```tsx
+// app/@modal/default.tsx
+export default function Default() {
+  return null;
+}
+```
+
+Without this file, refreshing any page will 404 because Next.js can't determine what to render in the `@modal` slot.
+
+## Step 3: Intercepting Route (Modal)
+
+The `(.)` prefix intercepts routes at the same level.
+
+```tsx
+// app/@modal/(.)photos/[id]/page.tsx
+import { Modal } from '@/components/modal';
+
+export default async function PhotoModal({
+  params
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+
+  return (
+    <Modal>
+      <img src={photo.url} alt={photo.title} />
+    </Modal>
+  );
+}
+```
+
+## Step 4: Full Page (Direct Access)
+
+```tsx
+// app/photos/[id]/page.tsx
+export default async function PhotoPage({
+  params
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+
+  return (
+    <div className="full-page">
+      <img src={photo.url} alt={photo.title} />
+      <h1>{photo.title}</h1>
+    </div>
+  );
+}
+```
+
+## Step 5: Modal Component with Correct Closing
+
+**Critical: Use `router.back()` to close modals, NOT `router.push()` or `<Link>`.**
+
+```tsx
+// components/modal.tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useCallback, useEffect, useRef } from 'react';
+
+export function Modal({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+  const overlayRef = useRef<HTMLDivElement>(null);
+
+  // Close on escape key
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        router.back(); // Correct
+      }
+    }
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [router]);
+
+  // Close on overlay click
+  const handleOverlayClick = useCallback((e: React.MouseEvent) => {
+    if (e.target === overlayRef.current) {
+      router.back(); // Correct
+    }
+  }, [router]);
+
+  return (
+    <div
+      ref={overlayRef}
+      onClick={handleOverlayClick}
+      className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
+    >
+      <div className="bg-white rounded-lg p-6 max-w-2xl w-full mx-4">
+        <button
+          onClick={() => router.back()} // Correct!
+          className="absolute top-4 right-4"
+        >
+          Close
+        </button>
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+### Why NOT `router.push('/')` or `<Link href="/">`?
+
+Using `push` or `Link` to "close" a modal:
+1. Adds a new history entry (back button shows modal again)
+2. Doesn't properly clear the intercepted route
+3. Can cause the modal to flash or persist unexpectedly
+
+`router.back()` correctly:
+1. Removes the intercepted route from history
+2. Returns to the previous page
+3. Properly unmounts the modal
+
+## Route Matcher Reference
+
+Matchers match **route segments**, not filesystem paths:
+
+| Matcher | Matches | Example |
+|---------|---------|---------|
+| `(.)` | Same level | `@modal/(.)photos` intercepts `/photos` |
+| `(..)` | One level up | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |
+| `(..)(..)` | Two levels up | Rarely used |
+| `(...)` | From root | `@modal/(...)photos` intercepts `/photos` from anywhere |
+
+**Common mistake**: Thinking `(..)` means "parent folder" - it means "parent route segment".
+
+## Handling Hard Navigation
+
+When users directly visit `/photos/123` (bookmark, refresh, shared link):
+- The intercepting route is bypassed
+- The full `photos/[id]/page.tsx` renders
+- Modal doesn't appear (expected behavior)
+
+If you want the modal to appear on direct access too, you need additional logic:
+
+```tsx
+// app/photos/[id]/page.tsx
+import { Modal } from '@/components/modal';
+
+export default async function PhotoPage({ params }) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+
+  // Option: Render as modal on direct access too
+  return (
+    <Modal>
+      <img src={photo.url} alt={photo.title} />
+    </Modal>
+  );
+}
+```
+
+## Common Gotchas
+
+### 1. Missing `default.tsx` → 404 on Refresh
+
+Every `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).
+
+### 2. Modal Persists After Navigation
+
+You're using `router.push()` instead of `router.back()`.
+
+### 3. Nested Parallel Routes Need Defaults Too
+
+If you have `@modal` inside a route group, each level needs its own `default.tsx`:
+
+```
+app/
+├── (marketing)/
+│   ├── @modal/
+│   │   └── default.tsx     # Needed!
+│   └── layout.tsx
+└── layout.tsx
+```
+
+### 4. Intercepted Route Shows Wrong Content
+
+Check your matcher:
+- `(.)photos` intercepts `/photos` from the same route level
+- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`
+
+### 5. TypeScript Errors with `params`
+
+In Next.js 15+, `params` is a Promise:
+
+```tsx
+// Correct
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+}
+```
+
+## Complete Example: Photo Gallery Modal
+
+```
+app/
+├── @modal/
+│   ├── default.tsx
+│   └── (.)photos/
+│       └── [id]/
+│           └── page.tsx
+├── photos/
+│   ├── page.tsx           # Gallery grid
+│   └── [id]/
+│       └── page.tsx       # Full photo page
+├── layout.tsx
+└── page.tsx
+```
+
+Links in the gallery:
+
+```tsx
+// app/photos/page.tsx
+import Link from 'next/link';
+
+export default async function Gallery() {
+  const photos = await getPhotos();
+
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {photos.map(photo => (
+        <Link key={photo.id} href={`/photos/${photo.id}`}>
+          <img src={photo.thumbnail} alt={photo.title} />
+        </Link>
+      ))}
+    </div>
+  );
+}
+```
+
+Clicking a photo → Modal opens (intercepted)
+Direct URL → Full page renders
+Refresh while modal open → Full page renders