@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/performance-optimization.md

@@ -0,0 +1,277 @@
+---
+name: performance-optimization
+description: Optimize web performance with code splitting, lazy loading, image optimization, Web Vitals, and bundle analysis.
+---
+
+# Performance Optimization
+
+## When to Use
+
+Apply these patterns when your application feels slow, when Lighthouse scores
+drop below 90, or proactively when building new features. Performance is a
+feature — every 100ms of load time costs measurable user engagement. Measure
+first, optimize the bottleneck, measure again.
+
+## How It Works
+
+### 1. Code Splitting
+
+Split your bundle so users download only the code they need for the current page.
+
+```typescript
+// Route-level splitting with React.lazy
+import { lazy, Suspense } from 'react';
+
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Settings = lazy(() => import('./pages/Settings'));
+const Analytics = lazy(() => import('./pages/Analytics'));
+
+function App() {
+  return (
+    <Suspense fallback={<PageSkeleton />}>
+      <Routes>
+        <Route path="/dashboard" element={<Dashboard />} />
+        <Route path="/settings" element={<Settings />} />
+        <Route path="/analytics" element={<Analytics />} />
+      </Routes>
+    </Suspense>
+  );
+}
+```
+
+```typescript
+// Component-level splitting for heavy libraries
+const CodeEditor = lazy(() => import('./components/CodeEditor'));
+
+function TaskDetail({ task }: { task: Task }) {
+  return (
+    <div>
+      <TaskHeader task={task} />
+      {task.hasCode && (
+        <Suspense fallback={<div className="h-64 animate-pulse bg-gray-100" />}>
+          <CodeEditor value={task.code} />
+        </Suspense>
+      )}
+    </div>
+  );
+}
+```
+
+### 2. Dynamic Import for Libraries
+
+Load heavy dependencies only when needed.
+
+```typescript
+// Bad — ships 500KB chart library to every page
+import { Chart } from 'chart.js';
+
+// Good — load only when user navigates to analytics
+async function renderChart(canvas: HTMLCanvasElement, data: ChartData) {
+  const { Chart, registerables } = await import('chart.js');
+  Chart.register(...registerables);
+  return new Chart(canvas, { type: 'line', data });
+}
+```
+
+### 3. Image Optimization
+
+```tsx
+// Next.js Image component — automatic optimization
+import Image from 'next/image';
+
+<Image
+  src="/hero.jpg"
+  alt="Dashboard preview"
+  width={1200}
+  height={630}
+  priority              // preload above-the-fold images
+  placeholder="blur"
+  blurDataURL={blurHash}
+/>
+
+// Below the fold — lazy load (default behavior)
+<Image
+  src="/feature.jpg"
+  alt="Feature screenshot"
+  width={800}
+  height={400}
+  loading="lazy"
+  sizes="(max-width: 768px) 100vw, 50vw"
+/>
+```
+
+For non-Next.js projects:
+
+```html
+<!-- Native lazy loading + responsive images -->
+<img
+  src="photo-800.webp"
+  srcset="photo-400.webp 400w, photo-800.webp 800w, photo-1200.webp 1200w"
+  sizes="(max-width: 600px) 100vw, 50vw"
+  loading="lazy"
+  decoding="async"
+  alt="Team photo"
+/>
+```
+
+Serve WebP/AVIF format. Use `<picture>` for format fallbacks.
+
+### 4. Web Vitals
+
+The three Core Web Vitals that matter for user experience and SEO:
+
+| Metric | Target | What it measures |
+|--------|--------|-----------------|
+| LCP (Largest Contentful Paint) | < 2.5s | When the main content becomes visible |
+| INP (Interaction to Next Paint) | < 200ms | Response time to user interactions |
+| CLS (Cumulative Layout Shift) | < 0.1 | Visual stability (things jumping around) |
+
+Measure in production:
+
+```typescript
+import { onLCP, onINP, onCLS } from 'web-vitals';
+
+function sendToAnalytics(metric: Metric) {
+  fetch('/api/vitals', {
+    method: 'POST',
+    body: JSON.stringify({
+      name: metric.name,
+      value: metric.value,
+      rating: metric.rating, // 'good' | 'needs-improvement' | 'poor'
+      url: window.location.href,
+    }),
+    keepalive: true, // survives page navigation
+  });
+}
+
+onLCP(sendToAnalytics);
+onINP(sendToAnalytics);
+onCLS(sendToAnalytics);
+```
+
+### 5. Fix Common LCP Problems
+
+```typescript
+// Preload the LCP image
+// In Next.js: priority prop on Image
+// In HTML: <link rel="preload" as="image" href="/hero.webp" />
+
+// Avoid render-blocking CSS
+// Move non-critical CSS to async loading
+<link rel="preload" href="/non-critical.css" as="style"
+      onload="this.onload=null;this.rel='stylesheet'" />
+
+// Inline critical CSS for above-the-fold content
+<style>{criticalCSS}</style>
+```
+
+### 6. Fix Common CLS Problems
+
+```css
+/* Reserve space for images */
+img, video {
+  max-width: 100%;
+  height: auto;
+  aspect-ratio: 16 / 9; /* prevent layout shift */
+}
+
+/* Reserve space for dynamic content */
+.ad-slot {
+  min-height: 250px;
+}
+
+/* Use transform for animations, not width/height/top/left */
+.toast-enter {
+  transform: translateY(100%);
+  transition: transform 0.3s ease;
+}
+```
+
+### 7. Profiling and Bundle Analysis
+
+```bash
+# Analyze bundle size
+npx vite-bundle-visualizer  # Vite
+npx @next/bundle-analyzer   # Next.js
+
+# Find large dependencies
+npx depcheck                # unused dependencies
+npx cost-of-modules         # install size per package
+```
+
+```typescript
+// Vite config — manual chunks for better caching
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+          charts: ['chart.js', 'recharts'],
+          editor: ['monaco-editor'],
+        },
+      },
+    },
+  },
+});
+```
+
+### 8. Runtime Performance
+
+```typescript
+// Virtualize long lists — render only visible items
+import { useVirtualizer } from '@tanstack/react-virtual';
+
+function VirtualList({ items }: { items: Item[] }) {
+  const parentRef = useRef<HTMLDivElement>(null);
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 48,
+  });
+
+  return (
+    <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
+      <div style={{ height: virtualizer.getTotalSize() }}>
+        {virtualizer.getVirtualItems().map((row) => (
+          <div key={row.key} style={{
+            position: 'absolute',
+            top: row.start,
+            height: row.size,
+          }}>
+            {items[row.index].name}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// Debounce expensive re-renders
+const debouncedSearch = useMemo(
+  () => debounce((query: string) => setSearch(query), 300),
+  [],
+);
+```
+
+## Examples
+
+| Problem | Solution | Impact |
+|---------|----------|--------|
+| 2MB JS bundle | Code splitting + lazy routes | 60-80% smaller initial load |
+| 5s LCP | Preload hero image + inline critical CSS | LCP < 2s |
+| Layout jumps | `aspect-ratio` on images + reserved ad slots | CLS < 0.05 |
+| Slow list of 10,000 items | Virtualization | Renders 20 items instead of 10,000 |
+| Heavy charting library | Dynamic import | Loaded only on analytics page |
+
+## Checklist
+
+- [ ] Routes are code-split with `React.lazy` or Next.js dynamic pages
+- [ ] Heavy libraries are dynamically imported, not in the main bundle
+- [ ] Images use modern formats (WebP/AVIF), responsive `srcset`, and `loading="lazy"`
+- [ ] Above-the-fold images use `priority` (Next.js) or `<link rel="preload">`
+- [ ] Web Vitals are measured in production and reported to analytics
+- [ ] LCP is under 2.5s, INP under 200ms, CLS under 0.1
+- [ ] Bundle analyzer is run in CI to catch size regressions
+- [ ] Lists with 100+ items use virtualization
+- [ ] `aspect-ratio` is set on images and media to prevent layout shift

package/assets/skills/php-patterns.md

@@ -0,0 +1,210 @@
+---
+name: php-patterns
+description: PHP patterns with PSR standards, Composer, type hints, enums, fibers, and attributes.
+---
+
+# Modern PHP Patterns
+
+## When to Use
+Apply these patterns when writing PHP 8.1+ code. Modern PHP has strict typing, enums, attributes, fibers, and match expressions that eliminate whole categories of bugs. Use this skill when starting new projects, upgrading legacy codebases, or reviewing PHP code for type safety and PSR compliance.
+
+## How It Works
+
+### Strict Types and Type Declarations
+
+Always declare strict types. Use union types, intersection types, and `never`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+function calculateDiscount(float $price, int $percent): float
+{
+    if ($percent < 0 || $percent > 100) {
+        throw new \InvalidArgumentException("Percent must be 0-100, got {$percent}");
+    }
+    return $price * (1 - $percent / 100);
+}
+
+// Union types (PHP 8.0+)
+function findUser(int|string $identifier): ?User
+{
+    return is_int($identifier)
+        ? UserRepository::findById($identifier)
+        : UserRepository::findByEmail($identifier);
+}
+
+// Intersection types (PHP 8.1+)
+function process(Countable&Iterator $collection): void
+{
+    foreach ($collection as $item) {
+        // $collection is guaranteed to be both Countable and Iterator
+    }
+}
+
+// DNF types (PHP 8.2+)
+function handle((Countable&Iterator)|null $items): void
+{
+    // Accepts a collection that is both Countable and Iterator, or null
+}
+```
+
+### Enums -- Replace Magic Strings
+
+```php
+enum OrderStatus: string
+{
+    case Pending   = 'pending';
+    case Paid      = 'paid';
+    case Shipped   = 'shipped';
+    case Cancelled = 'cancelled';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Pending   => 'Awaiting Payment',
+            self::Paid      => 'Payment Received',
+            self::Shipped   => 'In Transit',
+            self::Cancelled => 'Order Cancelled',
+        };
+    }
+
+    public function canTransitionTo(self $next): bool
+    {
+        return match ($this) {
+            self::Pending   => in_array($next, [self::Paid, self::Cancelled]),
+            self::Paid      => $next === self::Shipped,
+            self::Shipped   => false,
+            self::Cancelled => false,
+        };
+    }
+}
+
+// Usage
+$status = OrderStatus::from('pending');
+echo $status->label(); // "Awaiting Payment"
+$status->canTransitionTo(OrderStatus::Paid); // true
+```
+
+### Attributes -- Declarative Metadata
+
+Replace docblock annotations with native attributes:
+
+```php
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class Validate
+{
+    public function __construct(
+        public readonly string $rule,
+        public readonly string $message = '',
+    ) {}
+}
+
+class CreateUserRequest
+{
+    public function __construct(
+        #[Validate('email', 'Must be a valid email')]
+        public readonly string $email,
+
+        #[Validate('min:8', 'Must be at least 8 characters')]
+        public readonly string $password,
+
+        #[Validate('in:free,pro,enterprise', 'Invalid plan')]
+        public readonly string $plan = 'free',
+    ) {}
+}
+```
+
+### Constructor Property Promotion and Readonly
+
+```php
+class Money
+{
+    public function __construct(
+        public readonly int $amount,
+        public readonly string $currency = 'USD',
+    ) {}
+
+    public function add(self $other): self
+    {
+        if ($this->currency !== $other->currency) {
+            throw new CurrencyMismatch($this->currency, $other->currency);
+        }
+        return new self($this->amount + $other->amount, $this->currency);
+    }
+
+    public function format(): string
+    {
+        $formatter = new \NumberFormatter('en_US', \NumberFormatter::CURRENCY);
+        return $formatter->formatCurrency($this->amount / 100, $this->currency);
+    }
+}
+```
+
+### Fibers -- Cooperative Multitasking
+
+```php
+$fiber = new Fiber(function (): void {
+    $value = Fiber::suspend('waiting for input');
+    echo "Received: {$value}\n";
+});
+
+$result = $fiber->start();      // $result = 'waiting for input'
+$fiber->resume('hello world');  // prints "Received: hello world"
+```
+
+Fibers power async frameworks like ReactPHP and Revolt without callbacks.
+
+### Composer and PSR-4 Autoloading
+
+```json
+{
+    "autoload": {
+        "psr-4": {
+            "App\\": "src/",
+            "App\\Tests\\": "tests/"
+        }
+    },
+    "require": {
+        "php": ">=8.2"
+    },
+    "config": {
+        "sort-packages": true,
+        "optimize-autoloader": true
+    }
+}
+```
+
+Directory structure mirrors namespace: `src/Domain/User/UserRepository.php` maps to `App\Domain\User\UserRepository`.
+
+### PSR Standards Reference
+
+| PSR | Purpose | Tool |
+|-----|---------|------|
+| PSR-1/12 | Coding style | PHP-CS-Fixer, PHP_CodeSniffer |
+| PSR-3 | Logger interface | Monolog |
+| PSR-4 | Autoloading | Composer |
+| PSR-7 | HTTP messages | Guzzle, Nyholm |
+| PSR-11 | Container interface | PHP-DI, Symfony DI |
+| PSR-15 | HTTP middleware | Slim, Mezzio |
+
+## Examples
+
+| Pattern | Before (Legacy) | After (Modern PHP 8.2+) |
+|---------|-----------------|------------------------|
+| Constants | `const STATUS_PAID = 'paid'` | `enum Status: string { case Paid = 'paid'; }` |
+| Annotations | `@Route("/api")` docblock | `#[Route('/api')]` attribute |
+| Constructors | Manual `$this->x = $x` | Constructor promotion `public readonly` |
+| Null handling | `isset($x) ? $x : $default` | `$x ?? $default` or `?->` |
+| Switch | `switch` with break | `match` expression (exhaustive) |
+
+## Checklist
+- [ ] `declare(strict_types=1)` at top of every PHP file
+- [ ] All function parameters and return types declared
+- [ ] Magic strings replaced with backed enums
+- [ ] Docblock annotations migrated to native attributes
+- [ ] Constructor property promotion used for value objects
+- [ ] `readonly` on properties that should not change
+- [ ] `match` used instead of `switch` for value expressions
+- [ ] PSR-4 autoload with optimized autoloader enabled