@jgamaraalv/ts-dev-kit 1.0.0

package/skills/service-worker/references/push-and-sync.md

@@ -0,0 +1,261 @@
+# Push Notifications & Background Sync
+
+## Table of Contents
+
+- [Push Notifications](#push-notifications)
+  - [Subscribe from the Page](#subscribe-from-the-page)
+  - [Send Push from Server](#send-push-from-server)
+  - [Handle Push in SW](#handle-push-in-sw)
+  - [Handle Notification Click](#handle-notification-click)
+  - [VAPID Keys](#vapid-keys)
+- [Background Sync](#background-sync)
+  - [Register Sync from Page](#register-sync-from-page)
+  - [Handle Sync in SW](#handle-sync-in-sw)
+  - [Retry Pattern](#retry-pattern)
+- [Periodic Background Sync](#periodic-background-sync)
+
+## Push Notifications
+
+### Subscribe from the Page
+
+```js
+async function subscribeToPush() {
+  const reg = await navigator.serviceWorker.ready;
+
+  // Check permission
+  const permission = await Notification.requestPermission();
+  if (permission !== "granted") return null;
+
+  // Subscribe with VAPID public key
+  const subscription = await reg.pushManager.subscribe({
+    userVisibleOnly: true, // Required: must show a notification for each push
+    applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
+  });
+
+  // Send subscription to your server
+  await fetch("/api/push/subscribe", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(subscription),
+  });
+
+  return subscription;
+}
+
+// Helper: convert VAPID key
+function urlBase64ToUint8Array(base64String) {
+  const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const raw = atob(base64);
+  return Uint8Array.from([...raw].map((char) => char.charCodeAt(0)));
+}
+```
+
+### Send Push from Server
+
+Using the `web-push` npm package (Node.js):
+
+```js
+import webpush from "web-push";
+
+webpush.setVapidDetails(
+  "mailto:admin@example.com",
+  process.env.VAPID_PUBLIC_KEY,
+  process.env.VAPID_PRIVATE_KEY,
+);
+
+// subscription = the PushSubscription JSON from the client
+await webpush.sendNotification(
+  subscription,
+  JSON.stringify({
+    title: "New message",
+    body: "You have a new notification",
+    icon: "/icon-192.png",
+    url: "/messages",
+  }),
+);
+```
+
+Generate VAPID keys: `npx web-push generate-vapid-keys`
+
+### Handle Push in SW
+
+```js
+self.addEventListener("push", (event) => {
+  const data = event.data?.json() ?? {};
+  const { title = "Notification", body, icon, url } = data;
+
+  event.waitUntil(
+    self.registration.showNotification(title, {
+      body,
+      icon: icon || "/icon-192.png",
+      badge: "/badge-72.png",
+      data: { url }, // Pass URL to notificationclick handler
+      vibrate: [100, 50, 100],
+      actions: [
+        { action: "open", title: "Open" },
+        { action: "dismiss", title: "Dismiss" },
+      ],
+    }),
+  );
+});
+```
+
+### Handle Notification Click
+
+```js
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+
+  if (event.action === "dismiss") return;
+
+  const url = event.notification.data?.url || "/";
+
+  event.waitUntil(
+    self.clients.matchAll({ type: "window", includeUncontrolled: true }).then((clients) => {
+      // Focus existing tab if one matches
+      for (const client of clients) {
+        if (client.url === url && "focus" in client) {
+          return client.focus();
+        }
+      }
+      // Otherwise open a new window
+      return self.clients.openWindow(url);
+    }),
+  );
+});
+
+self.addEventListener("notificationclose", (event) => {
+  // Track dismissals (analytics)
+});
+```
+
+### VAPID Keys
+
+VAPID (Voluntary Application Server Identification) authenticates your server to the push service.
+
+```bash
+# Generate keys (do this once, store securely)
+npx web-push generate-vapid-keys
+```
+
+Output:
+
+```
+Public Key:  BNbxG...  (use in client subscribe call)
+Private Key: 3KW9e...  (use on server only, keep secret)
+```
+
+Store as environment variables:
+
+```
+VAPID_PUBLIC_KEY=BNbxG...
+VAPID_PRIVATE_KEY=3KW9e...
+```
+
+## Background Sync
+
+Defers actions until the user has connectivity. Chromium-only (Chrome, Edge).
+
+> **Safari/iOS caveat:** Background Sync is not supported in Safari/iOS. Use periodic polling as fallback.
+
+### Register Sync from Page
+
+```js
+async function saveForSync(data) {
+  // Store the pending action in IndexedDB
+  await saveToIndexedDB("pending-actions", data);
+
+  // Register a sync
+  const reg = await navigator.serviceWorker.ready;
+  await reg.sync.register("sync-pending-actions");
+}
+```
+
+### Handle Sync in SW
+
+```js
+self.addEventListener("sync", (event) => {
+  if (event.tag === "sync-pending-actions") {
+    event.waitUntil(processPendingActions());
+  }
+});
+
+async function processPendingActions() {
+  const actions = await getFromIndexedDB("pending-actions");
+
+  for (const action of actions) {
+    try {
+      await fetch("/api/action", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(action),
+      });
+      await removeFromIndexedDB("pending-actions", action.id);
+    } catch {
+      // Will retry on next sync event
+      throw new Error("Sync failed, will retry");
+    }
+  }
+}
+```
+
+### Retry Pattern
+
+The browser retries `sync` events with exponential backoff when the promise passed to `waitUntil` rejects. The event includes `event.lastChance` — if `true`, this is the final retry:
+
+```js
+self.addEventListener("sync", (event) => {
+  if (event.tag === "sync-form-data") {
+    event.waitUntil(
+      submitFormData().catch((err) => {
+        if (event.lastChance) {
+          // Final attempt failed — notify user via notification
+          return self.registration.showNotification("Sync failed", {
+            body: "Your data could not be submitted. Please try again.",
+          });
+        }
+        throw err; // Reject to trigger retry
+      }),
+    );
+  }
+});
+```
+
+## Periodic Background Sync
+
+Runs at periodic intervals even when the page is closed. Chromium-only, requires site engagement score.
+
+```js
+// Register from page
+const reg = await navigator.serviceWorker.ready;
+const status = await navigator.permissions.query({ name: "periodic-background-sync" });
+
+if (status.state === "granted") {
+  await reg.periodicSync.register("update-content", {
+    minInterval: 24 * 60 * 60 * 1000, // Once per day minimum
+  });
+}
+
+// Handle in SW
+self.addEventListener("periodicsync", (event) => {
+  if (event.tag === "update-content") {
+    event.waitUntil(updateCachedContent());
+  }
+});
+
+async function updateCachedContent() {
+  const cache = await caches.open("content-v1");
+  const response = await fetch("/api/latest-content");
+  if (response.ok) {
+    await cache.put("/api/latest-content", response);
+  }
+}
+```
+
+**Notes:**
+
+- `minInterval` is a hint — the browser decides actual frequency based on site engagement
+- Requires a minimum site engagement score (user must visit regularly)
+- Not supported in Firefox or Safari
+- Always check for API availability before registering

package/skills/typescript-conventions/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: typescript-conventions
+description: "TypeScript coding conventions for strict, type-safe projects. Use when: (1) writing or reviewing TypeScript code, (2) choosing between `any` and `unknown`, (3) structuring imports with verbatimModuleSyntax, (4) naming functions, booleans, queries, and commands, (5) handling errors with guard clauses and early returns, or (6) avoiding common anti-patterns like primitive obsession, magic strings, and premature abstraction."
+---
+
+# TypeScript Conventions
+
+Project-wide TypeScript standards that complement agent-specific instructions.
+
+## Type Safety
+
+- **No `any`**: Use `unknown` if the type is truly dynamic, then narrow.
+- **Strict config**: `strict: true`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`.
+- Use `Readonly<T>`, `Pick`, `Omit`, and `Record` for precise types.
+- Use branded types for entity IDs (e.g., `UserId`, `OrderId`) to prevent mixing.
+- Prefer `z.infer<typeof schema>` over hand-written types when a Zod schema exists.
+
+## Imports
+
+```typescript
+// Type-only imports (required by verbatimModuleSyntax)
+import type { FastifyInstance } from "fastify";
+
+// Mixed imports: separate values and types
+import { z } from "zod/v4";
+import type { ZodType } from "zod/v4";
+
+// ioredis: always named import
+import { Redis } from "ioredis";
+```
+
+## Error Handling
+
+- Handle errors at the beginning of functions with early returns / guard clauses.
+- Avoid deep nesting -- use if-return pattern instead of else chains.
+- In Fastify routes, throw `httpErrors` or use `reply.status().send()` -- the centralized `setErrorHandler` formats the response.
+- Custom error classes for domain-specific errors (e.g., `NotFoundError`, `ConflictError`).
+
+## Naming
+
+- **Functions**: `getUserById`, `createReport`, `isActive`, `hasPermission`
+- **Booleans**: `is/has/can/should` prefix
+- **Query** (returns data): `get`, `find`, `list`, `fetch`
+- **Command** (changes state): `create`, `update`, `delete`, `add`, `remove`
+
+## Anti-Patterns
+
+- **Primitive obsession**: Use branded types or Zod enums, not raw strings for IDs and statuses.
+- **Magic numbers/strings**: Use constants from a shared package (e.g., `RATE_LIMITS`, `PAGINATION`, `CACHE`).
+- **Long parameter lists**: Use an options object or a Zod schema.
+- **Premature abstraction**: Three similar lines > one premature helper. Abstract on the third repetition.

package/skills/ui-ux-guidelines/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ui-ux-guidelines
+description: "Review UI code for Web Interface Guidelines compliance. Use when asked to review UI, check accessibility, audit design, review UX, or check against best practices."
+---
+
+# Web Interface Guidelines
+
+Dispatch hub for UI/UX rules. Load the relevant reference file for full details.
+
+## Contents
+
+1. [Rule Categories](#rule-categories-by-priority)
+2. [Workflows](#workflows)
+3. [Anti-patterns](#anti-patterns-flag-these)
+4. [Output Format](#code-review-output-format)
+5. [Reference Files](#reference-files)
+
+---
+
+## Rule Categories by Priority
+
+| Priority | Category             | Impact   | Reference File                  |
+| -------- | -------------------- | -------- | ------------------------------- |
+| 1        | Accessibility        | CRITICAL | `accessibility-and-interaction` |
+| 2        | Touch & Interaction  | CRITICAL | `accessibility-and-interaction` |
+| 3        | Performance          | HIGH     | `layout-typography-animation`   |
+| 4        | Layout & Responsive  | HIGH     | `layout-typography-animation`   |
+| 5        | Typography & Color   | MEDIUM   | `layout-typography-animation`   |
+| 6        | Animation            | MEDIUM   | `layout-typography-animation`   |
+| 7        | Forms                | HIGH     | `forms-content-checklist`       |
+| 8        | Content & Navigation | MEDIUM   | `forms-content-checklist`       |
+| 9        | Charts & Data        | LOW      | `layout-typography-animation`   |
+
+---
+
+## Workflows
+
+### 1. Review UI code
+
+1. Read the target file(s).
+2. Load the relevant reference file(s) from `references/` based on what the code contains.
+3. Check each applicable rule. Report violations in the output format below.
+
+### 2. Build new component
+
+1. Load `references/accessibility-and-interaction.md` -- all components must meet CRITICAL rules.
+2. Load additional references based on component type:
+   - Form component -> `references/forms-content-checklist.md`
+   - Layout/visual component -> `references/layout-typography-animation.md`
+3. Follow rules during implementation.
+
+### 3. Pre-delivery checklist
+
+1. Load `references/forms-content-checklist.md` for the full checklist.
+2. Load `references/accessibility-and-interaction.md` for the interaction checklist.
+3. Walk through every checkbox before shipping.
+
+---
+
+## Anti-patterns (flag these)
+
+- `user-scalable=no` or `maximum-scale=1` -- disables zoom
+- `onPaste` with `preventDefault` -- blocks paste
+- `transition: all` -- list properties explicitly
+- `outline-none` without `:focus-visible` replacement
+- `<div>`/`<span>` with click handlers -- use `<button>` or `<a>`
+- `<img>` without `width` and `height` (causes CLS)
+- Inline `onClick` navigation without `<a>` (breaks Cmd+click)
+- Large `.map()` without virtualization (>50 items)
+- Hardcoded date/number formats -- use `Intl.*`
+- Icon-only buttons without `aria-label`
+
+---
+
+## Code Review Output Format
+
+Group findings by file. Use `file:line` format (VS Code clickable). Be terse -- state issue and location. Skip explanation unless fix is non-obvious.
+
+```text
+## src/Button.tsx
+
+src/Button.tsx:42 - icon button missing aria-label
+src/Button.tsx:18 - input lacks label
+src/Button.tsx:55 - animation missing prefers-reduced-motion
+src/Button.tsx:67 - transition: all -> list properties explicitly
+
+## src/Modal.tsx
+
+src/Modal.tsx:12 - missing overscroll-behavior: contain
+src/Modal.tsx:34 - "..." -> "..."
+
+## src/Card.tsx
+
+pass
+```
+
+---
+
+## Reference Files
+
+Load these as needed during reviews and implementation:
+
+- **[Accessibility & Interaction](references/accessibility-and-interaction.md)** -- Focus, ARIA, keyboard, touch targets, cursors, drag UX
+- **[Layout, Typography & Animation](references/layout-typography-animation.md)** -- Performance, responsive, fonts, color, motion, charts
+- **[Forms, Content & Checklist](references/forms-content-checklist.md)** -- Forms, content handling, navigation, dark mode, locale, hydration, pre-delivery checklist

package/skills/ui-ux-guidelines/references/accessibility-and-interaction.md

@@ -0,0 +1,74 @@
+# Accessibility & Interaction Reference
+
+Rules for accessible, touch-friendly interfaces. Loaded by the dispatch hub when reviewing accessibility or interaction code.
+
+---
+
+## Accessibility (CRITICAL)
+
+### Focus & Keyboard
+
+- `focus-states` — Visible focus rings on all interactive elements; use `:focus-visible` over `:focus`
+- `keyboard-nav` — Tab order matches visual order; interactive elements need `onKeyDown`/`onKeyUp` handlers
+- `focus-within` — Use `:focus-within` for compound controls (e.g., search with icon)
+- `scroll-margin` — `scroll-margin-top` on heading anchors to avoid content hidden behind fixed headers
+- `heading-hierarchy` — `<h1>`--`<h6>` hierarchical; include skip link for main content
+
+### ARIA & Semantics
+
+- `aria-labels` — `aria-label` for icon-only buttons; `aria-hidden="true"` for decorative icons
+- `aria-live` — Async updates (toasts, loading, validation) need `aria-live="polite"`
+- `semantic-first` — Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before reaching for ARIA
+- `color-contrast` — Minimum 4.5:1 ratio for normal text; color must not be the only indicator
+
+### Form Accessibility
+
+- `form-labels` — Use `<label>` with `htmlFor` or wrapping control on all inputs
+- Checkboxes/radios: label and control share a single hit target (no dead zones)
+
+---
+
+## Touch & Interaction (CRITICAL)
+
+### Touch Targets
+
+- `touch-target-size` — Minimum 44x44px touch targets
+- `touch-action` — Add `touch-action: manipulation` to interactive elements (prevents double-tap zoom delay)
+- `tap-highlight` — Set `-webkit-tap-highlight-color` intentionally (don't leave as default)
+
+### Click & Hover
+
+- `hover-vs-tap` — Use click/tap for primary interactions, never hover-only
+- `cursor-pointer` — Add `cursor-pointer` to all clickable elements
+- `loading-buttons` — Disable button during async operations; show loading state
+- `error-feedback` — Clear error messages placed near the problem field
+
+### Containment & Drag
+
+- `overscroll` — Add `overscroll-behavior: contain` in modals, drawers, and sheets
+- `drag-ux` — During drag operations: disable text selection, use `inert` on dragged elements
+- `autofocus` — Use `autoFocus` sparingly — desktop only, single primary input; avoid on mobile
+
+---
+
+## Anti-patterns to Flag
+
+- `user-scalable=no` or `maximum-scale=1` — disables zoom (accessibility violation)
+- `outline-none` / `outline: 0` without a `:focus-visible` replacement
+- `<div>` or `<span>` with click handlers — use `<button>` or `<a>`
+- Icon-only buttons without `aria-label`
+- Form inputs without associated labels
+- `autoFocus` without clear justification on mobile
+
+---
+
+## Interaction Review Checklist
+
+- [ ] All clickable elements have `cursor-pointer`
+- [ ] Hover states provide clear visual feedback without layout shift
+- [ ] Transitions are smooth (150--300ms)
+- [ ] Focus states visible for keyboard navigation (`:focus-visible`)
+- [ ] Destructive actions have confirmation modal or undo
+- [ ] All images have descriptive alt text (or `alt=""` for decorative)
+- [ ] Async updates (toasts, validation) use `aria-live="polite"`
+- [ ] Interactive elements have keyboard handlers

package/skills/ui-ux-guidelines/references/forms-content-checklist.md

@@ -0,0 +1,126 @@
+# Forms, Content & Pre-Delivery Checklist
+
+Rules for forms, content handling, navigation, dark mode, locale, and hydration. Includes the pre-delivery checklist. Loaded by the dispatch hub for form reviews and final delivery checks.
+
+---
+
+## Forms
+
+- Inputs need `autocomplete` attribute and meaningful `name`
+- Use correct `type` (`email`, `tel`, `url`, `number`, `search`) and `inputmode` for virtual keyboards
+- Never block paste (`onPaste` + `preventDefault`)
+- Labels must be clickable: use `htmlFor` matching `id`, or wrap control in `<label>`
+- Disable spellcheck on emails, codes, and usernames: `spellCheck={false}`
+- Checkboxes/radios: label and control share a single hit target (no dead zones)
+- Submit button stays enabled until request starts; show spinner during request
+- Errors inline next to fields; focus the first error field on submit
+- Placeholders end with `…` and show an example pattern (e.g., `"Ex: nome@email.com…"`)
+- Use `autocomplete="off"` on non-auth fields where password manager triggers are unwanted
+- Warn before navigation with unsaved changes (`beforeunload` event or router guard)
+
+---
+
+## Content Handling
+
+- Text containers must handle long content: use `truncate`, `line-clamp-*`, or `break-words`
+- Flex children that contain text need `min-w-0` to allow text truncation to work
+- Always handle empty states — never render broken UI for empty strings or arrays
+- User-generated content: design and test for short, average, and very long inputs
+
+---
+
+## Navigation & State
+
+- URL reflects state — filters, tabs, pagination, and expanded panels belong in query params
+- Links must use `<a>`/`<Link>` to support Cmd/Ctrl+click and middle-click
+- Deep-link all stateful UI — if it uses `useState`, consider URL sync via `nuqs` or similar
+- Destructive actions require a confirmation modal or undo window — never immediate execution
+
+---
+
+## Dark Mode & Theming
+
+- Set `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar and native input appearance)
+- `<meta name="theme-color">` must match the page background color
+- Native `<select>` elements need explicit `background-color` and `color` for Windows dark mode
+
+---
+
+## Locale & i18n
+
+- Dates and times: use `Intl.DateTimeFormat` — never hardcode date formats
+- Numbers and currency: use `Intl.NumberFormat` — never hardcode number/currency formats
+- Detect language via `Accept-Language` header or `navigator.languages` — not by IP geolocation
+
+---
+
+## Hydration Safety
+
+- Controlled inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
+- Date/time rendering: guard against hydration mismatch between server and client
+- `suppressHydrationWarning` only where truly necessary (e.g., system clock, browser extensions)
+
+---
+
+## Content & Copy
+
+- Active voice: "Install the CLI" not "The CLI will be installed"
+- Sentence case for headings (e.g., "Configure notifications")
+- Numerals for counts: "8 items" not "eight items"
+- Specific button labels: "Save API Key" not "Continue"
+- Error messages include the fix or next step — not just the problem description
+- Second person ("you"); avoid first person ("I")
+- Use `&` over "and" where space is constrained
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify all items below.
+
+### Visual Quality
+
+- [ ] No emojis used as icons (SVG only)
+- [ ] All icons from a consistent icon set (Lucide for this project)
+- [ ] Brand logos verified from Simple Icons
+- [ ] Hover states do not cause layout shift
+- [ ] Theme colors used directly (e.g., `bg-primary`), not wrapped in `var()`
+
+### Forms
+
+- [ ] All inputs have `autocomplete` and meaningful `name`
+- [ ] Correct `type` and `inputmode` on inputs
+- [ ] Paste is not blocked
+- [ ] All labels are clickable (`htmlFor` or wrapping)
+- [ ] Submit button disabled + spinner during request
+- [ ] Errors shown inline; first error focused on submit
+
+### Light/Dark Mode
+
+- [ ] Light mode text meets 4.5:1 contrast minimum
+- [ ] Glass/transparent elements are visible in light mode
+- [ ] Borders visible in both light and dark modes
+- [ ] Both modes tested before delivery
+- [ ] `color-scheme` set on `<html>` for dark themes
+
+### Layout
+
+- [ ] Floating elements have proper spacing from viewport edges
+- [ ] No content hidden behind fixed navbars
+- [ ] Responsive at 375px, 768px, 1024px, 1440px
+- [ ] No horizontal scroll on mobile
+- [ ] Safe area insets applied for full-bleed layouts
+
+### Typography & Copy
+
+- [ ] `…` (U+2026) used instead of `...` (three dots)
+- [ ] Loading states end with `…`
+- [ ] `font-variant-numeric: tabular-nums` on number columns
+- [ ] `text-wrap: balance` on headings
+- [ ] Error messages include the next step, not just the problem
+
+### i18n & Hydration
+
+- [ ] Dates use `Intl.DateTimeFormat`
+- [ ] Numbers/currency use `Intl.NumberFormat`
+- [ ] Controlled inputs have `onChange`; date/time rendering guarded against hydration mismatch