@jgamaraalv/ts-dev-kit 1.0.0

package/skills/postgresql/references/queries.md

@@ -0,0 +1,287 @@
+# PostgreSQL Queries Reference
+
+## Table of Contents
+
+1. [SELECT anatomy](#select-anatomy)
+2. [JOINs](#joins)
+3. [Subqueries](#subqueries)
+4. [CTEs (WITH clauses)](#ctes)
+5. [Window functions](#window-functions)
+6. [Aggregation](#aggregation)
+7. [Set operations](#set-operations)
+8. [INSERT / UPDATE / DELETE / UPSERT](#dml)
+9. [LATERAL joins](#lateral)
+
+---
+
+## SELECT anatomy
+
+```sql
+SELECT [DISTINCT] expression [AS alias], ...
+FROM table [AS alias]
+[JOIN ...]
+[WHERE condition]
+[GROUP BY expression, ...]
+[HAVING condition]
+[WINDOW w AS (window_def)]
+[ORDER BY expression [ASC|DESC] [NULLS FIRST|LAST]]
+[LIMIT n] [OFFSET n]
+[FOR UPDATE | FOR SHARE]
+```
+
+Execution order (logical): FROM → JOIN → WHERE → GROUP BY → HAVING → SELECT → DISTINCT → ORDER BY → LIMIT/OFFSET.
+
+```sql
+-- DISTINCT ON — keep first row per group (PostgreSQL extension)
+SELECT DISTINCT ON (department_id) department_id, name, salary
+FROM employees
+ORDER BY department_id, salary DESC;
+
+-- Return row if exists, else nothing
+SELECT * FROM users WHERE email = $1 FOR UPDATE;
+```
+
+---
+
+## JOINs
+
+```sql
+-- INNER JOIN (default)
+SELECT o.id, c.name FROM orders o JOIN customers c ON o.customer_id = c.id;
+
+-- LEFT JOIN — all rows from left, NULL for unmatched right
+SELECT c.name, COUNT(o.id) FROM customers c LEFT JOIN orders o ON o.customer_id = c.id GROUP BY c.id;
+
+-- FULL OUTER JOIN
+SELECT a.id, b.id FROM a FULL OUTER JOIN b ON a.key = b.key;
+
+-- CROSS JOIN — cartesian product
+SELECT * FROM sizes CROSS JOIN colors;
+
+-- Self-join
+SELECT e.name, m.name AS manager FROM employees e LEFT JOIN employees m ON e.manager_id = m.id;
+
+-- Multiple join conditions
+SELECT * FROM a JOIN b ON a.x = b.x AND a.y > b.y;
+```
+
+---
+
+## Subqueries
+
+```sql
+-- In WHERE
+SELECT * FROM orders WHERE customer_id IN (SELECT id FROM customers WHERE country = 'BR');
+
+-- EXISTS (stops at first match — efficient)
+SELECT * FROM customers c WHERE EXISTS (SELECT 1 FROM orders o WHERE o.customer_id = c.id);
+
+-- Correlated subquery in SELECT (runs once per row — can be slow)
+SELECT name, (SELECT COUNT(*) FROM orders o WHERE o.customer_id = c.id) AS order_count
+FROM customers c;
+
+-- Scalar subquery
+SELECT * FROM orders WHERE total > (SELECT AVG(total) FROM orders);
+
+-- Derived table (subquery in FROM)
+SELECT dept, avg_sal FROM (
+  SELECT department, AVG(salary) AS avg_sal FROM employees GROUP BY department
+) AS dept_avg
+WHERE avg_sal > 50000;
+```
+
+---
+
+## CTEs
+
+```sql
+-- Basic CTE
+WITH recent_orders AS (
+  SELECT * FROM orders WHERE created_at > NOW() - INTERVAL '7 days'
+)
+SELECT customer_id, COUNT(*) FROM recent_orders GROUP BY customer_id;
+
+-- Multiple CTEs
+WITH
+  a AS (SELECT ...),
+  b AS (SELECT ... FROM a)
+SELECT * FROM b;
+
+-- Writable CTE (INSERT/UPDATE/DELETE returning rows)
+WITH deleted AS (
+  DELETE FROM sessions WHERE expires_at < NOW() RETURNING user_id
+)
+INSERT INTO audit_log (user_id, event) SELECT user_id, 'session_expired' FROM deleted;
+
+-- Recursive CTE (e.g., tree traversal)
+WITH RECURSIVE tree AS (
+  -- Base case
+  SELECT id, parent_id, name, 0 AS depth FROM categories WHERE parent_id IS NULL
+  UNION ALL
+  -- Recursive case
+  SELECT c.id, c.parent_id, c.name, t.depth + 1
+  FROM categories c JOIN tree t ON c.parent_id = t.id
+)
+SELECT * FROM tree ORDER BY depth, name;
+```
+
+CTE materialization: By default CTEs are optimization fences (materialized once). Add `NOT MATERIALIZED` to allow the planner to inline them:
+
+```sql
+WITH data AS NOT MATERIALIZED (SELECT * FROM big_table WHERE ...)
+SELECT * FROM data WHERE extra_filter;
+```
+
+---
+
+## Window functions
+
+```sql
+-- Syntax
+function() OVER ([PARTITION BY col] [ORDER BY col] [frame_clause])
+
+-- ROW_NUMBER, RANK, DENSE_RANK
+SELECT name, salary,
+  ROW_NUMBER() OVER (PARTITION BY dept ORDER BY salary DESC) AS rn,
+  RANK()       OVER (PARTITION BY dept ORDER BY salary DESC) AS rnk,
+  DENSE_RANK() OVER (PARTITION BY dept ORDER BY salary DESC) AS drnk
+FROM employees;
+
+-- Running total
+SELECT date, amount, SUM(amount) OVER (ORDER BY date) AS running_total FROM sales;
+
+-- Moving average (last 7 rows)
+SELECT date, amount,
+  AVG(amount) OVER (ORDER BY date ROWS BETWEEN 6 PRECEDING AND CURRENT ROW) AS moving_avg
+FROM sales;
+
+-- LAG / LEAD — access adjacent rows
+SELECT date, amount,
+  LAG(amount, 1) OVER (ORDER BY date) AS prev_day,
+  amount - LAG(amount, 1) OVER (ORDER BY date) AS delta
+FROM sales;
+
+-- FIRST_VALUE / LAST_VALUE
+SELECT dept, name, salary,
+  FIRST_VALUE(name) OVER (PARTITION BY dept ORDER BY salary DESC) AS top_earner
+FROM employees;
+
+-- Named WINDOW clause (reuse)
+SELECT name, salary,
+  RANK() OVER w,
+  DENSE_RANK() OVER w
+FROM employees
+WINDOW w AS (PARTITION BY dept ORDER BY salary DESC);
+```
+
+Frame clauses: `ROWS BETWEEN n PRECEDING AND CURRENT ROW`, `RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`, `ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING`.
+
+---
+
+## Aggregation
+
+```sql
+SELECT dept,
+  COUNT(*),
+  COUNT(DISTINCT manager_id),
+  SUM(salary),
+  AVG(salary),
+  MIN(salary), MAX(salary),
+  ARRAY_AGG(name ORDER BY salary DESC),
+  STRING_AGG(name, ', ' ORDER BY name),
+  PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY salary) AS median
+FROM employees
+WHERE active = true
+GROUP BY dept
+HAVING COUNT(*) > 5
+ORDER BY AVG(salary) DESC;
+
+-- FILTER clause (conditional aggregate)
+SELECT
+  COUNT(*) FILTER (WHERE status = 'active') AS active_count,
+  COUNT(*) FILTER (WHERE status = 'inactive') AS inactive_count
+FROM users;
+
+-- GROUPING SETS / ROLLUP / CUBE
+SELECT region, product, SUM(revenue)
+FROM sales
+GROUP BY ROLLUP (region, product);   -- subtotals per region + grand total
+```
+
+---
+
+## Set operations
+
+```sql
+UNION     -- deduplicate
+UNION ALL -- keep duplicates (faster)
+INTERSECT -- rows in both
+EXCEPT    -- rows in first but not second
+
+SELECT id FROM table_a
+UNION ALL
+SELECT id FROM table_b
+ORDER BY id;           -- ORDER BY applies to the combined result
+```
+
+---
+
+## DML
+
+```sql
+-- INSERT
+INSERT INTO users (name, email, created_at)
+VALUES ('Alice', 'alice@example.com', NOW())
+RETURNING id, created_at;
+
+-- INSERT multiple rows
+INSERT INTO tags (name) VALUES ('dogs'), ('cats'), ('pets');
+
+-- UPSERT (ON CONFLICT)
+INSERT INTO user_prefs (user_id, key, value)
+VALUES ($1, $2, $3)
+ON CONFLICT (user_id, key) DO UPDATE SET value = EXCLUDED.value, updated_at = NOW();
+
+-- ON CONFLICT DO NOTHING
+INSERT INTO events (id, payload) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING;
+
+-- UPDATE
+UPDATE orders
+SET status = 'shipped', updated_at = NOW()
+WHERE id = $1 AND status = 'processing'
+RETURNING *;
+
+-- UPDATE with JOIN (using FROM)
+UPDATE employees e
+SET salary = e.salary * 1.1
+FROM departments d
+WHERE e.dept_id = d.id AND d.name = 'Engineering';
+
+-- DELETE
+DELETE FROM sessions WHERE expires_at < NOW() RETURNING id;
+
+-- TRUNCATE (faster than DELETE for full table, unlogged)
+TRUNCATE TABLE audit_log RESTART IDENTITY CASCADE;
+```
+
+---
+
+## LATERAL
+
+`LATERAL` allows a subquery in `FROM` to reference columns from preceding tables:
+
+```sql
+-- Get latest N orders per customer
+SELECT c.name, o.*
+FROM customers c,
+LATERAL (
+  SELECT * FROM orders WHERE customer_id = c.id ORDER BY created_at DESC LIMIT 3
+) o;
+
+-- With LEFT JOIN LATERAL (include customers with no orders)
+SELECT c.name, o.id
+FROM customers c
+LEFT JOIN LATERAL (
+  SELECT id FROM orders WHERE customer_id = c.id ORDER BY created_at DESC LIMIT 1
+) o ON true;
+```

package/skills/postgresql/references/transactions.md

@@ -0,0 +1,280 @@
+# PostgreSQL Transactions Reference
+
+## Table of Contents
+
+1. [Transaction basics](#basics)
+2. [Savepoints](#savepoints)
+3. [Isolation levels](#isolation-levels)
+4. [Locking](#locking)
+5. [Advisory locks](#advisory-locks)
+6. [MVCC overview](#mvcc)
+7. [Common patterns](#patterns)
+
+---
+
+## Basics
+
+Every SQL statement runs inside a transaction. Without `BEGIN`, each statement has an implicit `BEGIN` + `COMMIT`.
+
+```sql
+-- Explicit transaction block
+BEGIN;
+  UPDATE accounts SET balance = balance - 100 WHERE id = 1;
+  UPDATE accounts SET balance = balance + 100 WHERE id = 2;
+COMMIT;
+
+-- Rollback on error
+BEGIN;
+  DELETE FROM orders WHERE id = 42;
+  -- Discovered wrong order, cancel:
+ROLLBACK;
+
+-- Set isolation level (must be first statement after BEGIN)
+BEGIN;
+SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;
+  SELECT ...;
+COMMIT;
+
+-- Shorthand
+BEGIN ISOLATION LEVEL REPEATABLE READ;
+```
+
+DDL statements (`CREATE TABLE`, `ALTER TABLE`, `DROP`) are transactional in PostgreSQL — they can be rolled back.
+
+---
+
+## Savepoints
+
+Savepoints allow partial rollback within a transaction:
+
+```sql
+BEGIN;
+  INSERT INTO orders (customer_id, total) VALUES (1, 100) RETURNING id;  -- id = 42
+
+  SAVEPOINT sp1;
+
+  INSERT INTO order_items (order_id, product_id, qty)
+  VALUES (42, 999, 1);  -- product 999 doesn't exist → error
+
+  ROLLBACK TO SAVEPOINT sp1;  -- undo order_items insert, keep orders insert
+
+  INSERT INTO order_items (order_id, product_id, qty)
+  VALUES (42, 1, 1);   -- correct product
+
+  RELEASE SAVEPOINT sp1;  -- optional cleanup
+COMMIT;
+```
+
+After `ROLLBACK TO SAVEPOINT`, the savepoint still exists and can be rolled back to again. Use `RELEASE SAVEPOINT` to free it.
+
+---
+
+## Isolation levels
+
+PostgreSQL supports four isolation levels. Default is **Read Committed**.
+
+| Level                        | Dirty Read     | Non-repeatable Read | Phantom Read     | Serialization Anomaly |
+| ---------------------------- | -------------- | ------------------- | ---------------- | --------------------- |
+| Read Uncommitted             | Not possible\* | Possible            | Possible         | Possible              |
+| **Read Committed** (default) | Not possible\* | **Possible**        | **Possible**     | **Possible**          |
+| Repeatable Read              | Not possible   | Not possible        | Not possible\*\* | **Possible**          |
+| Serializable                 | Not possible   | Not possible        | Not possible     | Not possible          |
+
+\* PostgreSQL never allows dirty reads even at Read Uncommitted.
+\*\* PostgreSQL's Repeatable Read prevents phantoms using MVCC snapshots.
+
+### Read Committed (default)
+
+Each statement sees its own snapshot (data committed before the statement started). Safe for most OLTP. Vulnerable to "lost update" in read-modify-write patterns without locking.
+
+```sql
+-- Common pattern: SELECT FOR UPDATE to prevent lost update
+BEGIN;
+SELECT * FROM products WHERE id = $1 FOR UPDATE;  -- lock the row
+UPDATE products SET stock = stock - 1 WHERE id = $1;
+COMMIT;
+```
+
+### Repeatable Read
+
+The entire transaction sees a single consistent snapshot (taken at first statement). Prevents non-repeatable reads and phantoms. May abort with:
+`ERROR: could not serialize access due to concurrent update` — retry the transaction.
+
+```sql
+BEGIN ISOLATION LEVEL REPEATABLE READ;
+SELECT SUM(balance) FROM accounts;   -- snapshot taken here
+-- Other transactions' commits won't affect our subsequent reads
+COMMIT;
+```
+
+### Serializable
+
+Strongest guarantee. Transactions execute as if run serially. Uses Serializable Snapshot Isolation (SSI). May abort with:
+`ERROR: could not serialize access due to read/write dependencies among transactions` — must retry.
+
+```sql
+BEGIN ISOLATION LEVEL SERIALIZABLE;
+-- Safe for concurrent write-skew prevention
+COMMIT;
+```
+
+---
+
+## Locking
+
+### Row-level locks
+
+```sql
+-- FOR UPDATE — exclusive lock; blocks other FOR UPDATE, FOR SHARE, UPDATE, DELETE
+SELECT * FROM orders WHERE id = $1 FOR UPDATE;
+
+-- FOR SHARE — shared lock; blocks FOR UPDATE but not other FOR SHARE
+SELECT * FROM users WHERE id = $1 FOR SHARE;
+
+-- SKIP LOCKED — skip rows currently locked (queue processing)
+SELECT * FROM jobs WHERE status = 'pending' LIMIT 1 FOR UPDATE SKIP LOCKED;
+
+-- NOWAIT — fail immediately if lock unavailable
+SELECT * FROM orders WHERE id = $1 FOR UPDATE NOWAIT;
+
+-- Lock specific tables (usually not needed)
+LOCK TABLE orders IN EXCLUSIVE MODE;
+LOCK TABLE orders IN ACCESS SHARE MODE;  -- weakest, just prevents DROP TABLE
+```
+
+### Table-level lock modes (strongest to weakest)
+
+| Mode                     | Blocks                             | When acquired                              |
+| ------------------------ | ---------------------------------- | ------------------------------------------ |
+| `ACCESS EXCLUSIVE`       | Everything                         | ALTER TABLE, DROP TABLE, VACUUM FULL       |
+| `EXCLUSIVE`              | All writes + ACCESS SHARE          | Rare                                       |
+| `SHARE ROW EXCLUSIVE`    | Row writes + SHARE                 | CREATE TRIGGER                             |
+| `SHARE`                  | Row writes                         | CREATE INDEX (non-concurrent)              |
+| `SHARE UPDATE EXCLUSIVE` | Schema changes                     | VACUUM, ANALYZE, CREATE INDEX CONCURRENTLY |
+| `ROW EXCLUSIVE`          | ACCESS EXCLUSIVE, EXCLUSIVE, SHARE | INSERT, UPDATE, DELETE                     |
+| `ROW SHARE`              | ACCESS EXCLUSIVE, EXCLUSIVE        | SELECT FOR UPDATE/SHARE                    |
+| `ACCESS SHARE`           | ACCESS EXCLUSIVE only              | SELECT                                     |
+
+### Detecting lock conflicts
+
+```sql
+-- See current locks
+SELECT pid, relation::regclass, mode, granted
+FROM pg_locks
+WHERE relation IS NOT NULL;
+
+-- Find blocking queries
+SELECT blocked.pid, blocked.query, blocking.pid AS blocking_pid, blocking.query
+FROM pg_stat_activity blocked
+JOIN pg_stat_activity blocking ON blocking.pid = ANY(pg_blocking_pids(blocked.pid))
+WHERE NOT blocked.granted;
+```
+
+---
+
+## Advisory locks
+
+Application-level locks not tied to any table — useful for mutual exclusion across processes.
+
+```sql
+-- Session-level (auto-released on disconnect)
+SELECT pg_advisory_lock(12345);        -- exclusive
+SELECT pg_advisory_lock_shared(12345); -- shared
+SELECT pg_advisory_unlock(12345);
+SELECT pg_advisory_unlock_all();
+
+-- Transaction-level (auto-released at COMMIT/ROLLBACK)
+SELECT pg_advisory_xact_lock(12345);
+SELECT pg_advisory_xact_lock_shared(12345);
+
+-- Try to acquire without blocking (returns bool)
+SELECT pg_try_advisory_lock(12345);
+
+-- Use hash of text for namespacing
+SELECT pg_advisory_lock(hashtext('my-job-lock'));
+```
+
+---
+
+## MVCC
+
+PostgreSQL uses Multi-Version Concurrency Control: readers never block writers; writers never block readers.
+
+Key concepts:
+
+- Each row has `xmin` (transaction that inserted) and `xmax` (transaction that deleted/updated).
+- A transaction sees rows where `xmin` is committed and visible, and `xmax` is not yet committed.
+- Dead tuples (old row versions) accumulate and must be reclaimed by `VACUUM`.
+
+```sql
+-- See transaction ID (xmin) of rows
+SELECT *, xmin, xmax FROM users LIMIT 5;
+
+-- Current transaction ID (txid_current() is deprecated since PG 13)
+SELECT pg_current_xact_id();
+```
+
+For VACUUM and maintenance, see [performance.md](performance.md).
+
+---
+
+## Common patterns
+
+### Optimistic locking (application-level)
+
+```sql
+-- Add version column
+ALTER TABLE products ADD COLUMN version integer NOT NULL DEFAULT 0;
+
+-- Read
+SELECT id, price, version FROM products WHERE id = $1;
+
+-- Update — fail if version changed since read
+UPDATE products
+SET price = $new_price, version = version + 1
+WHERE id = $1 AND version = $expected_version;
+-- Check affected rows: if 0, conflict detected → retry
+```
+
+### Queue processing with SKIP LOCKED
+
+```sql
+BEGIN;
+SELECT id, payload FROM jobs
+WHERE status = 'pending'
+ORDER BY created_at
+LIMIT 1
+FOR UPDATE SKIP LOCKED;
+
+-- Process the job...
+
+UPDATE jobs SET status = 'done', processed_at = NOW() WHERE id = $1;
+COMMIT;
+```
+
+### Deferred constraint checking
+
+```sql
+-- Useful for circular references or bulk data loading
+BEGIN;
+SET CONSTRAINTS ALL DEFERRED;
+  INSERT INTO a (id, b_id) VALUES (1, 2);
+  INSERT INTO b (id, a_id) VALUES (2, 1);  -- FK to a(1) is deferred
+COMMIT;  -- constraints checked here
+```
+
+### Two-phase commit (distributed transactions)
+
+```sql
+-- Prepare
+BEGIN;
+  UPDATE ...;
+PREPARE TRANSACTION 'my-txn-id';
+
+-- Commit or rollback from any connection
+COMMIT PREPARED 'my-txn-id';
+ROLLBACK PREPARED 'my-txn-id';
+
+-- View prepared transactions
+SELECT * FROM pg_prepared_xacts;
+```

package/skills/react-best-practices/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: react-best-practices
+description: "React and Next.js performance patterns. Use when writing, reviewing, or optimizing React components."
+---
+
+# React & Next.js Performance Patterns
+
+Performance optimization guide for React and Next.js applications, based on Vercel Engineering practices. 8 categories organized by impact.
+
+## Table of Contents
+
+- [When to Apply](#when-to-apply)
+- [Quick Reference](#quick-reference)
+  - [Async Patterns (CRITICAL)](#1-async-patterns-critical)
+  - [Bundle Optimization (CRITICAL)](#2-bundle-optimization-critical)
+  - [Server-Side Performance (HIGH)](#3-server-side-performance-high)
+  - [Client-Side Patterns (MEDIUM-HIGH)](#4-client-side-patterns-medium-high)
+  - [Re-render Optimization (MEDIUM)](#5-re-render-optimization-medium)
+  - [Rendering Performance (MEDIUM)](#6-rendering-performance-medium)
+  - [JavaScript Performance (LOW-MEDIUM)](#7-javascript-performance-low-medium)
+  - [Advanced Patterns (LOW)](#8-advanced-patterns-low)
+
+## When to Apply
+
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Optimizing bundle size or load times
+
+## Quick Reference
+
+### 1. Async Patterns (CRITICAL)
+
+[references/async-patterns.md](references/async-patterns.md)
+
+- Prevent waterfall chains in API routes -- start promises early, await late
+- Defer await until needed -- move await into branches that use it
+- Dependency-based parallelization -- `Promise.all()` with `.then()` chaining
+- Strategic Suspense boundaries -- stream content with `<Suspense>`
+
+### 2. Bundle Optimization (CRITICAL)
+
+[references/bundle-optimization.md](references/bundle-optimization.md)
+
+- Avoid barrel file imports -- import directly from source files
+- Conditional module loading -- load only when feature is activated
+- Defer non-critical third-party libraries -- load after hydration
+- Dynamic imports for heavy components -- `next/dynamic` with `ssr: false`
+- Preload on user intent -- preload on hover/focus
+
+### 3. Server-Side Performance (HIGH)
+
+[references/server-performance.md](references/server-performance.md)
+
+- `after()` for non-blocking operations -- logging, analytics after response
+- Authenticate Server Actions -- treat as public endpoints
+- Cross-request LRU caching -- share data across sequential requests
+- `React.cache()` deduplication -- per-request with primitive args
+- Avoid duplicate RSC serialization -- transform in client, not server
+- Parallel fetching via composition -- restructure component tree
+- Minimize serialization at boundaries -- pass only needed fields
+
+### 4. Client-Side Patterns (MEDIUM-HIGH)
+
+[references/client-patterns.md](references/client-patterns.md)
+
+- Deduplicate global event listeners -- `useSWRSubscription`
+- Version and minimize localStorage -- schema versioning, try-catch
+- Passive event listeners -- `{ passive: true }` for scroll performance
+- SWR for automatic deduplication -- caching and revalidation
+
+### 5. Re-render Optimization (MEDIUM)
+
+[references/rerender-optimization.md](references/rerender-optimization.md)
+
+- Defer state reads to usage point -- read in callbacks, not render
+- Narrow effect dependencies -- use primitives, not objects
+- Derive state during render -- no state + effect for computed values
+- Functional setState -- stable callbacks, no stale closures
+- Hoist default non-primitive props -- stable defaults for `memo()`
+- Extract to memoized components -- skip computation with early returns
+- Interaction logic in event handlers -- not state + effect
+- useRef for transient values -- avoid re-render on frequent updates
+
+### 6. Rendering Performance (MEDIUM)
+
+[references/rendering-performance.md](references/rendering-performance.md)
+
+- Animate SVG wrapper -- hardware-accelerated CSS on `<div>`, not `<svg>`
+- CSS `content-visibility: auto` -- defer off-screen rendering
+- Hoist static JSX -- extract constants outside components
+- Prevent hydration mismatch -- inline script for client-only data
+- `useTransition` over manual loading states -- built-in pending state
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+[references/js-performance.md](references/js-performance.md)
+
+- Avoid layout thrashing -- batch DOM reads and writes
+- Cache repeated function calls -- module-level Map
+- Cache storage API calls -- in-memory cache for localStorage/cookies
+- Build index Maps for lookups -- O(1) instead of O(n) `.find()`
+- Loop for min/max -- O(n) instead of O(n log n) sort
+
+### 8. Advanced Patterns (LOW)
+
+[references/advanced-patterns.md](references/advanced-patterns.md)
+
+- Store event handlers in refs -- stable effect subscriptions
+- Initialize app once per load -- module-level guard