npm - @cubis/foundry - Versions diffs - 0.3.31 → 0.3.33 - Mend

@cubis/foundry 0.3.31 → 0.3.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1494) hide show

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/next-best-practices/font.md ADDED Viewed

@@ -0,0 +1,245 @@
+# Font Optimization
+Use `next/font` for automatic font optimization with zero layout shift.
+## Google Fonts
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] })
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={inter.className}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+## Multiple Fonts
+```tsx
+import { Inter, Roboto_Mono } from 'next/font/google'
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter',
+})
+const robotoMono = Roboto_Mono({
+  subsets: ['latin'],
+  variable: '--font-roboto-mono',
+})
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+Use in CSS:
+```css
+body {
+  font-family: var(--font-inter);
+}
+code {
+  font-family: var(--font-roboto-mono);
+}
+```
+## Font Weights and Styles
+```tsx
+// Single weight
+const inter = Inter({
+  subsets: ['latin'],
+  weight: '400',
+})
+// Multiple weights
+const inter = Inter({
+  subsets: ['latin'],
+  weight: ['400', '500', '700'],
+})
+// Variable font (recommended) - includes all weights
+const inter = Inter({
+  subsets: ['latin'],
+  // No weight needed - variable fonts support all weights
+})
+// With italic
+const inter = Inter({
+  subsets: ['latin'],
+  style: ['normal', 'italic'],
+})
+```
+## Local Fonts
+```tsx
+import localFont from 'next/font/local'
+const myFont = localFont({
+  src: './fonts/MyFont.woff2',
+})
+// Multiple files for different weights
+const myFont = localFont({
+  src: [
+    {
+      path: './fonts/MyFont-Regular.woff2',
+      weight: '400',
+      style: 'normal',
+    },
+    {
+      path: './fonts/MyFont-Bold.woff2',
+      weight: '700',
+      style: 'normal',
+    },
+  ],
+})
+// Variable font
+const myFont = localFont({
+  src: './fonts/MyFont-Variable.woff2',
+  variable: '--font-my-font',
+})
+```
+## Tailwind CSS Integration
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter',
+})
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={inter.variable}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+```js
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['var(--font-inter)'],
+      },
+    },
+  },
+}
+```
+## Preloading Subsets
+Only load needed character subsets:
+```tsx
+// Latin only (most common)
+const inter = Inter({ subsets: ['latin'] })
+// Multiple subsets
+const inter = Inter({ subsets: ['latin', 'latin-ext', 'cyrillic'] })
+```
+## Display Strategy
+Control font loading behavior:
+```tsx
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap', // Default - shows fallback, swaps when loaded
+})
+// Options:
+// 'auto' - browser decides
+// 'block' - short block period, then swap
+// 'swap' - immediate fallback, swap when ready (recommended)
+// 'fallback' - short block, short swap, then fallback
+// 'optional' - short block, no swap (use if font is optional)
+```
+## Don't Use Manual Font Links
+Always use `next/font` instead of `<link>` tags for Google Fonts.
+```tsx
+// Bad: Manual link tag (blocks rendering, no optimization)
+<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
+// Bad: Missing display and preconnect
+<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
+// Good: Use next/font (self-hosted, zero layout shift)
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] })
+```
+## Common Mistakes
+```tsx
+// Bad: Importing font in every component
+// components/Button.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] }) // Creates new instance each time!
+// Good: Import once in layout, use CSS variable
+// app/layout.tsx
+const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+// Bad: Using @import in CSS (blocks rendering)
+/* globals.css */
+@import url('https://fonts.googleapis.com/css2?family=Inter');
+// Good: Use next/font (self-hosted, no network request)
+import { Inter } from 'next/font/google'
+// Bad: Loading all weights when only using a few
+const inter = Inter({ subsets: ['latin'] }) // Loads all weights
+// Good: Specify only needed weights (for non-variable fonts)
+const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
+// Bad: Missing subset - loads all characters
+const inter = Inter({})
+// Good: Always specify subset
+const inter = Inter({ subsets: ['latin'] })
+```
+## Font in Specific Components
+```tsx
+// For component-specific fonts, export from a shared file
+// lib/fonts.ts
+import { Inter, Playfair_Display } from 'next/font/google'
+export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+export const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-playfair' })
+// components/Heading.tsx
+import { playfair } from '@/lib/fonts'
+export function Heading({ children }) {
+  return <h1 className={playfair.className}>{children}</h1>
+}
+```

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/next-best-practices/functions.md ADDED Viewed

@@ -0,0 +1,108 @@
+# Functions
+Next.js function APIs.
+Reference: https://nextjs.org/docs/app/api-reference/functions
+## Navigation Hooks (Client)
+| Hook | Purpose | Reference |
+|------|---------|-----------|
+| `useRouter` | Programmatic navigation (`push`, `replace`, `back`, `refresh`) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-router) |
+| `usePathname` | Get current pathname | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-pathname) |
+| `useSearchParams` | Read URL search parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-search-params) |
+| `useParams` | Access dynamic route parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-params) |
+| `useSelectedLayoutSegment` | Active child segment (one level) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segment) |
+| `useSelectedLayoutSegments` | All active segments below layout | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segments) |
+| `useLinkStatus` | Check link prefetch status | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-link-status) |
+| `useReportWebVitals` | Report Core Web Vitals metrics | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals) |
+## Server Functions
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `cookies` | Read/write cookies | [Docs](https://nextjs.org/docs/app/api-reference/functions/cookies) |
+| `headers` | Read request headers | [Docs](https://nextjs.org/docs/app/api-reference/functions/headers) |
+| `draftMode` | Enable preview of unpublished CMS content | [Docs](https://nextjs.org/docs/app/api-reference/functions/draft-mode) |
+| `after` | Run code after response finishes streaming | [Docs](https://nextjs.org/docs/app/api-reference/functions/after) |
+| `connection` | Wait for connection before dynamic rendering | [Docs](https://nextjs.org/docs/app/api-reference/functions/connection) |
+| `userAgent` | Parse User-Agent header | [Docs](https://nextjs.org/docs/app/api-reference/functions/userAgent) |
+## Generate Functions
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `generateStaticParams` | Pre-render dynamic routes at build time | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) |
+| `generateMetadata` | Dynamic metadata | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) |
+| `generateViewport` | Dynamic viewport config | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-viewport) |
+| `generateSitemaps` | Multiple sitemaps for large sites | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps) |
+| `generateImageMetadata` | Multiple OG images per route | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-image-metadata) |
+## Request/Response
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `NextRequest` | Extended Request with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-request) |
+| `NextResponse` | Extended Response with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-response) |
+| `ImageResponse` | Generate OG images | [Docs](https://nextjs.org/docs/app/api-reference/functions/image-response) |
+## Common Examples
+### Navigation
+Use `next/link` for internal navigation instead of `<a>` tags.
+```tsx
+// Bad: Plain anchor tag
+<a href="/about">About</a>
+// Good: Next.js Link
+import Link from 'next/link'
+<Link href="/about">About</Link>
+```
+Active link styling:
+```tsx
+'use client'
+import Link from 'next/link'
+import { usePathname } from 'next/navigation'
+export function NavLink({ href, children }) {
+  const pathname = usePathname()
+  return (
+    <Link href={href} className={pathname === href ? 'active' : ''}>
+      {children}
+    </Link>
+  )
+}
+```
+### Static Generation
+```tsx
+// app/blog/[slug]/page.tsx
+export async function generateStaticParams() {
+  const posts = await getPosts()
+  return posts.map((post) => ({ slug: post.slug }))
+}
+```
+### After Response
+```tsx
+import { after } from 'next/server'
+export async function POST(request: Request) {
+  const data = await processRequest(request)
+  after(async () => {
+    await logAnalytics(data)
+  })
+  return Response.json({ success: true })
+}
+```

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/next-best-practices/hydration-error.md ADDED Viewed

@@ -0,0 +1,91 @@
+# Hydration Errors
+Diagnose and fix React hydration mismatch errors.
+## Error Signs
+- "Hydration failed because the initial UI does not match"
+- "Text content does not match server-rendered HTML"
+## Debugging
+In development, click the hydration error to see the server/client diff.
+## Common Causes and Fixes
+### Browser-only APIs
+```tsx
+// Bad: Causes mismatch - window doesn't exist on server
+<div>{window.innerWidth}</div>
+// Good: Use client component with mounted check
+'use client'
+import { useState, useEffect } from 'react'
+export function ClientOnly({ children }: { children: React.ReactNode }) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  return mounted ? children : null
+}
+```
+### Date/Time Rendering
+Server and client may be in different timezones:
+```tsx
+// Bad: Causes mismatch
+<span>{new Date().toLocaleString()}</span>
+// Good: Render on client only
+'use client'
+const [time, setTime] = useState<string>()
+useEffect(() => setTime(new Date().toLocaleString()), [])
+```
+### Random Values or IDs
+```tsx
+// Bad: Random values differ between server and client
+<div id={Math.random().toString()}>
+// Good: Use useId hook
+import { useId } from 'react'
+function Input() {
+  const id = useId()
+  return <input id={id} />
+}
+```
+### Invalid HTML Nesting
+```tsx
+// Bad: Invalid - div inside p
+<p><div>Content</div></p>
+// Bad: Invalid - p inside p
+<p><p>Nested</p></p>
+// Good: Valid nesting
+<div><p>Content</p></div>
+```
+### Third-party Scripts
+Scripts that modify DOM during hydration.
+```tsx
+// Good: Use next/script with afterInteractive
+import Script from 'next/script'
+export default function Page() {
+  return (
+    <Script
+      src="https://example.com/script.js"
+      strategy="afterInteractive"
+    />
+  )
+}
+```

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/next-best-practices/image.md ADDED Viewed

@@ -0,0 +1,173 @@
+# Image Optimization
+Use `next/image` for automatic image optimization.
+## Always Use next/image
+```tsx
+// Bad: Avoid native img
+<img src="/hero.png" alt="Hero" />
+// Good: Use next/image
+import Image from 'next/image'
+<Image src="/hero.png" alt="Hero" width={800} height={400} />
+```
+## Required Props
+Images need explicit dimensions to prevent layout shift:
+```tsx
+// Local images - dimensions inferred automatically
+import heroImage from './hero.png'
+<Image src={heroImage} alt="Hero" />
+// Remote images - must specify width/height
+<Image src="https://example.com/image.jpg" alt="Hero" width={800} height={400} />
+// Or use fill for parent-relative sizing
+<div style={{ position: 'relative', width: '100%', height: 400 }}>
+  <Image src="/hero.png" alt="Hero" fill style={{ objectFit: 'cover' }} />
+</div>
+```
+## Remote Images Configuration
+Remote domains must be configured in `next.config.js`:
+```js
+// next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'example.com',
+        pathname: '/images/**',
+      },
+      {
+        protocol: 'https',
+        hostname: '*.cdn.com', // Wildcard subdomain
+      },
+    ],
+  },
+}
+```
+## Responsive Images
+Use `sizes` to tell the browser which size to download:
+```tsx
+// Full-width hero
+<Image
+  src="/hero.png"
+  alt="Hero"
+  fill
+  sizes="100vw"
+/>
+// Responsive grid (3 columns on desktop, 1 on mobile)
+<Image
+  src="/card.png"
+  alt="Card"
+  fill
+  sizes="(max-width: 768px) 100vw, 33vw"
+/>
+// Fixed sidebar image
+<Image
+  src="/avatar.png"
+  alt="Avatar"
+  width={200}
+  height={200}
+  sizes="200px"
+/>
+```
+## Blur Placeholder
+Prevent layout shift with placeholders:
+```tsx
+// Local images - automatic blur hash
+import heroImage from './hero.png'
+<Image src={heroImage} alt="Hero" placeholder="blur" />
+// Remote images - provide blurDataURL
+<Image
+  src="https://example.com/image.jpg"
+  alt="Hero"
+  width={800}
+  height={400}
+  placeholder="blur"
+  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
+/>
+// Or use color placeholder
+<Image
+  src="https://example.com/image.jpg"
+  alt="Hero"
+  width={800}
+  height={400}
+  placeholder="empty"
+  style={{ backgroundColor: '#e0e0e0' }}
+/>
+```
+## Priority Loading
+Use `priority` for above-the-fold images (LCP):
+```tsx
+// Hero image - loads immediately
+<Image src="/hero.png" alt="Hero" fill priority />
+// Below-fold images - lazy loaded by default (no priority needed)
+<Image src="/card.png" alt="Card" width={400} height={300} />
+```
+## Common Mistakes
+```tsx
+// Bad: Missing sizes with fill - downloads largest image
+<Image src="/hero.png" alt="Hero" fill />
+// Good: Add sizes for proper responsive behavior
+<Image src="/hero.png" alt="Hero" fill sizes="100vw" />
+// Bad: Using width/height for aspect ratio only
+<Image src="/hero.png" alt="Hero" width={16} height={9} />
+// Good: Use actual display dimensions or fill with sizes
+<Image src="/hero.png" alt="Hero" fill sizes="100vw" style={{ objectFit: 'cover' }} />
+// Bad: Remote image without config
+<Image src="https://untrusted.com/image.jpg" alt="Image" width={400} height={300} />
+// Error: Invalid src prop, hostname not configured
+// Good: Add hostname to next.config.js remotePatterns
+```
+## Static Export
+When using `output: 'export'`, use `unoptimized` or custom loader:
+```tsx
+// Option 1: Disable optimization
+<Image src="/hero.png" alt="Hero" width={800} height={400} unoptimized />
+// Option 2: Global config
+// next.config.js
+module.exports = {
+  output: 'export',
+  images: { unoptimized: true },
+}
+// Option 3: Custom loader (Cloudinary, Imgix, etc.)
+const cloudinaryLoader = ({ src, width, quality }) => {
+  return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`
+}
+<Image loader={cloudinaryLoader} src="sample.jpg" alt="Sample" width={800} height={400} />
+```