@shaykec/bridge 0.4.25 → 0.4.26

package/modules/rag-fundamentals/walkthrough.md

@@ -0,0 +1,75 @@
+# RAG Fundamentals Walkthrough — Learn by Doing
+
+## Before We Begin
+
+**Diagnostic Question:** When you ask an LLM a question about your company docs, how does it "know" the answer? What if the answer wasn't in its training data?
+
+**Checkpoint:** You recognize that RAG (Retrieval-Augmented Generation) lets LLMs use external knowledge. You fetch relevant chunks, add them to the prompt, and the model answers from that context.
+
+---
+
+## Step 1: Chunk a Document
+
+<!-- hint:code language="text" highlight="1,3" -->
+
+**Task:** Take a 1–2 page document (or create one). Chunk it three ways: (a) fixed 100 tokens, (b) by paragraph, (c) recursive (try sentence, then paragraph). For each, note: chunk count, whether any chunk loses context, and where boundaries feel wrong.
+
+**Question:** When would fixed-size fail? When would paragraph boundaries be better?
+
+**Checkpoint:** The user produces chunks for all three strategies. They observe that fixed-size can split mid-sentence; paragraph preserves semantics but chunks may be uneven.
+
+---
+
+## Step 2: Understand Embeddings (Conceptually)
+
+<!-- hint:card type="concept" title="Embeddings" -->
+
+**Task:** Without coding, reason about similarity. For "How do I reset my password?", rank these by how semantically close they are: (A) "Password reset instructions", (B) "The sky is blue", (C) "Forgot password? Click here." Explain your ranking.
+
+**Question:** Why might keyword search match (A) and (C) but miss (B)? Why do embeddings help?
+
+**Checkpoint:** The user ranks: (A) or (C) closest, (B) farthest. They understand embeddings capture meaning; "reset" and "forgot" are related even without shared words.
+
+---
+
+## Step 3: Design the RAG Pipeline
+
+<!-- hint:diagram mermaid-type="flowchart" topic="RAG pipeline" -->
+
+**Task:** Sketch the full pipeline for "Answer questions from our company handbook." List: (1) What gets indexed, (2) Chunking strategy, (3) How retrieval works, (4) How the prompt is augmented, (5) What the model receives.
+
+**Question:** What metadata would you store with each chunk? How would you filter (e.g., by section, date)?
+
+**Checkpoint:** The user designs: handbook → chunk → embed → store; query → embed → retrieve → augment → generate. They propose metadata (section, page) and filtering.
+
+---
+
+## Step 4: Tune Top-k
+
+<!-- hint:buttons type="single" prompt="When would you choose 3 chunks vs 10?" options="3 for focus,10 for breadth,Depends on doc size" -->
+
+**Task:** If you retrieve 3 chunks vs. 10 chunks, what changes? List pros and cons. When would you choose 3? When 10? What problem does re-ranking address?
+
+**Question:** Why might more chunks hurt? How does re-ranking help?
+
+**Checkpoint:** The user explains: 3 = focused, may miss context; 10 = broader, may add noise and use context. Re-ranking improves precision of top results before passing to the LLM.
+
+---
+
+## Step 5: Build a Minimal RAG (Hands-On)
+
+**Task:** Using a library (LangChain, LlamaIndex, or similar), build a minimal RAG: load 2–3 paragraphs, chunk them, embed, store in an in-memory vector store. Query and print the retrieved chunks. Then augment a prompt and call an LLM. Confirm the answer cites the retrieved text.
+
+**Question:** What would you add for production? (Persistence? Metadata? Evaluation?)
+
+**Checkpoint:** The user has a working pipeline: load → chunk → embed → store → query → retrieve → augment → generate. They can list next steps (persistence, eval, etc.).
+
+---
+
+## Step 6: Identify a Pitfall
+
+**Task:** A RAG system returns wrong answers. It retrieves 5 chunks and passes them to the model. List 4 possible causes (chunking, retrieval, prompt, model) and one fix for each.
+
+**Question:** How would you debug? What would you measure first?
+
+**Checkpoint:** The user identifies: bad chunks (fix: better chunking), irrelevant retrieval (fix: tune k, threshold, re-rank), weak prompt (fix: clarify "only use provided context"), or model ignoring context (fix: stronger instructions, eval faithfulness).

package/modules/react-fundamentals/content.md

@@ -0,0 +1,140 @@
+# React — Components, Hooks, and State Management
+
+## What is React?
+
+React is a JavaScript library for building user interfaces. It uses a component-based architecture where UIs are composed of reusable, isolated pieces.
+
+## JSX
+
+JSX is syntax extension that lets you write HTML-like markup inside JavaScript:
+
+```jsx
+const element = <h1>Hello, world!</h1>;
+```
+
+Under the hood, JSX compiles to `React.createElement()` calls. You can embed JavaScript expressions with `{expression}`:
+
+```jsx
+const name = "Alice";
+const element = <h1>Hello, {name}!</h1>;
+```
+
+## Components (Functional)
+
+Modern React uses **functional components** — plain JavaScript functions that return JSX:
+
+```jsx
+function Greeting({ name }) {
+  return <h1>Hello, {name}!</h1>;
+}
+```
+
+Components accept **props** (properties) as their single argument. Props are read-only.
+
+## Props
+
+Props flow down from parent to child. They're the primary way to pass data:
+
+```jsx
+<Greeting name="Alice" />
+function Greeting({ name }) {
+  return <p>Hi, {name}</p>;
+}
+```
+
+## State (useState)
+
+**State** is data that changes over time. Use the `useState` hook:
+
+```jsx
+function Counter() {
+  const [count, setCount] = useState(0);
+  return (
+    <button onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+- `useState(0)` returns `[value, setter]`
+- Calling the setter triggers a re-render
+- State is isolated per component instance
+
+## Effects (useEffect)
+
+**Effects** handle side effects: fetching data, subscribing, DOM manipulation:
+
+```jsx
+useEffect(() => {
+  document.title = `Count: ${count}`;
+}, [count]); // Re-run when count changes
+```
+
+- First argument: function to run
+- Second argument: dependency array — effect runs when any dependency changes
+- Empty array `[]` = run once on mount
+
+## Event Handling
+
+Attach handlers with camelCase props:
+
+```jsx
+<button onClick={handleClick}>Click</button>
+<input onChange={(e) => setValue(e.target.value)} />
+```
+
+React uses synthetic events (cross-browser wrapper). Call `e.preventDefault()` to prevent default behavior.
+
+## Conditional Rendering
+
+Render conditionally with `&&`, ternaries, or early returns:
+
+```jsx
+{isLoggedIn && <Dashboard />}
+{status === 'loading' ? <Spinner /> : <Content />}
+if (!user) return <Login />;
+```
+
+## Lists and Keys
+
+Map arrays to elements. **Keys** help React track identity:
+
+```jsx
+{items.map(item => (
+  <li key={item.id}>{item.name}</li>
+))}
+```
+
+Keys must be unique among siblings. Use stable IDs, not array indices for dynamic lists.
+
+## The React Rendering Cycle
+
+When state changes, React re-renders. Here's the flow:
+
+```mermaid
+flowchart LR
+    A[State Change] --> B[Re-render]
+    B --> C[Virtual DOM Diff]
+    C --> D[DOM Update]
+```
+
+```mermaid
+flowchart LR
+    A[State Change] --> B[Virtual DOM Diff]
+    B --> C[Reconciliation]
+    C --> D[Real DOM Update]
+```
+
+1. **State Change** — `setState` or similar triggers update
+2. **Virtual DOM Diff** — React compares new tree with previous
+3. **Reconciliation** — Determines minimal DOM operations
+4. **Real DOM Update** — Only changed nodes are updated
+
+This makes React efficient: full re-renders are cheap in memory; only minimal DOM mutations occur.
+
+## Rules of Hooks
+
+- Call hooks only at the **top level** — not inside loops, conditions, or nested functions
+- Call hooks only from **React function components** or custom hooks
+- Custom hook names must start with `use`

package/modules/react-fundamentals/exercises.md

@@ -0,0 +1,81 @@
+# React Exercises
+
+## Exercise 1: Toggle Button
+
+**Task:** Create a `Toggle` component that shows "ON" or "OFF" and switches when clicked. Use `useState` with a boolean.
+
+**Validation:**
+- [ ] Clicking toggles between ON and OFF
+- [ ] The displayed text updates on every click
+- [ ] State is managed with a single boolean
+
+**Hints:**
+1. `useState(false)` gives you `[value, setValue]`
+2. Toggle with `setValue(!value)` or `setValue(prev => !prev)`
+3. Use a ternary or template literal for the display text
+
+---
+
+## Exercise 2: Input Mirror
+
+**Task:** Create a component with a text input. Whatever the user types should appear in a `<p>` below in real time (controlled input).
+
+**Validation:**
+- [ ] Typing updates the paragraph immediately
+- [ ] The input value is controlled by state
+- [ ] Clearing the input clears the paragraph
+
+**Hints:**
+1. Use `useState("")` for the value
+2. `onChange={(e) => setValue(e.target.value)}`
+3. `value={value}` makes it a controlled input
+
+---
+
+## Exercise 3: Timer with useEffect
+
+**Task:** Create a timer that counts up every second when mounted. Use `useEffect` with `setInterval`. Clean up the interval when the component unmounts.
+
+**Validation:**
+- [ ] The displayed number increments every second
+- [ ] No interval leak on unmount (return cleanup from useEffect)
+- [ ] Uses `useState` for the displayed count
+
+**Hints:**
+1. `useEffect` with `[count]` or `[]` — which do you need?
+2. `return () => clearInterval(id)` in the effect
+3. `setCount(c => c + 1)` avoids stale closures
+
+---
+
+## Exercise 4: Search Filter
+
+**Task:** Given a static array of names (e.g., `["Alice", "Bob", "Carol", "Dave"]`), render them in a list. Add a search input that filters the list as the user types (case-insensitive).
+
+**Validation:**
+- [ ] Typing "al" shows only "Alice"
+- [ ] Clearing the input shows all names
+- [ ] Filtering is case-insensitive
+- [ ] Uses `filter()` and does not mutate the original array
+
+**Hints:**
+1. Store the search term in state, not the filtered list
+2. Derive filtered list: `names.filter(n => n.toLowerCase().includes(search.toLowerCase()))`
+3. The list is derived state — no need for separate state
+
+---
+
+## Exercise 5: Form with Validation
+
+**Task:** Create a simple form with a name input (required) and an email input (required, must contain `@`). Show an error message below each invalid field. Disable the submit button until the form is valid.
+
+**Validation:**
+- [ ] Submitting with empty fields shows errors
+- [ ] Invalid email format shows an error
+- [ ] Submit button is disabled when invalid
+- [ ] Valid form enables submit
+
+**Hints:**
+1. Track `name`, `email`, and optionally `touched` / `errors` in state
+2. Compute validity: `name.trim() && email.includes('@')`
+3. Optionally show errors only after first submit or on blur

package/modules/react-fundamentals/game.yaml

@@ -0,0 +1,145 @@
+games:
+  - type: bug-hunt
+    title: "React Anti-Pattern Detective"
+    snippets:
+      - code: |
+          function Counter() {
+            const [count, setCount] = useState(0);
+            return (
+              <button onClick={() => count++}>Count: {count}</button>
+            );
+          }
+        bugLine: 4
+        explanation: "Mutating state directly — count++ mutates state in place. React won't re-render. Use setCount(count + 1) instead."
+        hint: "Does count++ actually trigger a re-render?"
+      - code: |
+          function TodoList({ items }) {
+            return (
+              <ul>
+                {items.map((item) => (
+                  <li>{item.text}</li>
+                ))}
+              </ul>
+            );
+          }
+        bugLine: 5
+        explanation: "Missing key prop — React needs a unique key for each list item to track identity and avoid rendering bugs. Use key={item.id} or a stable identifier."
+        hint: "What does React need to efficiently reconcile list items?"
+      - code: |
+          function DataFetcher() {
+            const [data, setData] = useState(null);
+            useEffect(() => {
+              fetch('/api/data')
+                .then((res) => res.json())
+                .then(setData);
+            }, [data]);
+            return <div>{data ? data.name : 'Loading...'}</div>;
+          }
+        bugLine: 6
+        explanation: "Infinite useEffect loop — the dependency array includes [data], so every time setData runs, the effect re-fires. Use [] for one-time fetch."
+        hint: "What happens when setData runs? Does the effect run again?"
+      - code: |
+          function SearchBar() {
+            const [query, setQuery] = useState('');
+            const handleSearch = () => {
+              setTimeout(() => {
+                fetchResults(query);
+              }, 500);
+            };
+            return <input onChange={(e) => setQuery(e.target.value)} />;
+          }
+        bugLine: 5
+        explanation: "Stale closure — the setTimeout callback captures query at callback creation. If the user types during the 500ms delay, fetchResults gets the old query. Use a ref or pass query explicitly."
+        hint: "What value of query does the setTimeout callback see when it runs?"
+      - code: |
+          function Parent() {
+            const [count, setCount] = useState(0);
+            const handleClick = () => setCount(count + 1);
+            return <Child onClick={handleClick} />;
+          }
+          function Child({ onClick }) {
+            return <button onClick={onClick}>Increment</button>;
+          }
+        bugLine: 3
+        explanation: "Recreated callback on every render — handleClick is a new function each render, causing Child to re-render unnecessarily. Wrap in useCallback for stable reference."
+        hint: "Is handleClick stable across Parent re-renders?"
+      - code: |
+          function ExpensiveList({ items }) {
+            const sorted = items.sort((a, b) => a.name.localeCompare(b.name));
+            return (
+              <ul>
+                {sorted.map((item) => <li key={item.id}>{item.name}</li>)}
+              </ul>
+            );
+          }
+        bugLine: 3
+        explanation: "Sort mutates and runs every render — .sort() mutates the original array (can cause bugs) and recomputes on every render. Use useMemo with a copy: [...items].sort(...)."
+        hint: "Does sort mutate? Does this run on every render?"
+
+  - type: speed-round
+    title: "Hook Quick Fire"
+    rounds:
+      - question: "You need to store a number that changes when the user clicks a button. Which hook?"
+        options:
+          - "useEffect"
+          - "useState"
+          - "useRef"
+          - "useMemo"
+        answer: 1
+        timeLimit: 14
+      - question: "You need to fetch data when the component mounts. Which hook?"
+        options:
+          - "useState"
+          - "useEffect"
+          - "useCallback"
+          - "useRef"
+        answer: 1
+        timeLimit: 14
+      - question: "You need a mutable value that persists across renders but doesn't trigger re-renders when it changes. Which hook?"
+        options:
+          - "useState"
+          - "useEffect"
+          - "useRef"
+          - "useMemo"
+        answer: 2
+        timeLimit: 16
+      - question: "You're computing an expensive derived value from props. You want to avoid recomputing when other state changes. Which hook?"
+        options:
+          - "useCallback"
+          - "useEffect"
+          - "useMemo"
+          - "useRef"
+        answer: 2
+        timeLimit: 16
+      - question: "You're passing a callback to a memoized child; the callback depends on parent state. Which hook keeps the callback stable?"
+        options:
+          - "useMemo"
+          - "useEffect"
+          - "useCallback"
+          - "useRef"
+        answer: 2
+        timeLimit: 16
+      - question: "You need to share data (e.g. theme) with many components without prop drilling. Which hook?"
+        options:
+          - "useState"
+          - "useContext"
+          - "useMemo"
+          - "useRef"
+        answer: 1
+        timeLimit: 14
+      - question: "You need to store a DOM reference so you can call .focus() or .scrollIntoView(). Which hook?"
+        options:
+          - "useState"
+          - "useEffect"
+          - "useRef"
+          - "useContext"
+        answer: 2
+        timeLimit: 14
+      - question: "You need to run a side effect (e.g. subscribe to an event) when the component mounts and clean up when it unmounts. Which hook?"
+        options:
+          - "useState"
+          - "useEffect"
+          - "useCallback"
+          - "useMemo"
+        answer: 1
+        timeLimit: 14

package/modules/react-fundamentals/module.yaml

@@ -0,0 +1,45 @@
+slug: react-fundamentals
+title: "React — Components, Hooks, and State Management"
+version: 1.0.0
+description: "Master React's component model, hooks, and state management with hands-on exercises."
+category: frameworks
+tags: [react, javascript, frontend, components, hooks, state]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+  game: 25
+  game-perfect-bonus: 15
+
+time:
+  quick: 5
+  read: 15
+  guided: 45
+
+prerequisites: [typescript-fundamentals]
+related: [react-native-fundamentals]
+
+triggers:
+  - "How do React hooks work?"
+  - "What is useState and useEffect?"
+  - "How do I manage state in React?"
+  - "What are React components?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-flow]
+  quiz-types: [quiz-drag-order, quiz-timed-choice, quiz-fill-blank]
+  game-types: [bug-hunt, speed-round]
+  playground: javascript
+  web-embeds: true
+
+sources:
+  - url: "https://react.dev"
+    label: "React Official Docs"
+    type: docs
+  - url: "https://react.dev/reference/react"
+    label: "React API Reference"
+    type: docs

package/modules/react-fundamentals/quick-ref.md

@@ -0,0 +1,62 @@
+# React Quick Reference
+
+## Hooks
+
+| Hook | Purpose | Example |
+|------|---------|---------|
+| `useState(init)` | Local state | `const [v, setV] = useState(0)` |
+| `useEffect(fn, deps)` | Side effects | `useEffect(() => {...}, [dep])` |
+| `useRef(init)` | Mutable ref (no re-render) | `const ref = useRef(null)` |
+
+## State Updates
+
+| Pattern | Use When |
+|--------|----------|
+| `setValue(x)` | New value is independent |
+| `setValue(prev => prev + 1)` | Depends on previous state |
+| `setValue(prev => ({...prev, key: v}))` | Updating object state |
+
+## useEffect Dependencies
+
+| Array | Behavior |
+|-------|----------|
+| `[a, b]` | Run when a or b changes |
+| `[]` | Run once on mount |
+| Omitted | Run after every render (rare) |
+| Return fn | Cleanup runs before next effect / unmount |
+
+## Event Handlers
+
+| Event | Handler |
+|-------|---------|
+| Click | `onClick={fn}` |
+| Input | `onChange={(e) => setValue(e.target.value)}` |
+| Submit | `onSubmit={(e) => { e.preventDefault(); ... }}` |
+| Focus/Blur | `onFocus`, `onBlur` |
+
+## Conditional Rendering
+
+| Pattern | Use Case |
+|---------|----------|
+| `{cond && <A />}` | Render A or nothing |
+| `{cond ? <A /> : <B />}` | Render A or B |
+| `if (!cond) return null` | Early exit |
+
+## Lists
+
+```jsx
+{items.map(item => (
+  <li key={item.id}>{item.name}</li>
+))}
+```
+
+- Keys must be unique among siblings
+- Prefer stable IDs over array index
+
+## Decision: State vs Prop vs Derived
+
+| Source | When to Use |
+|--------|-------------|
+| State | Data that changes, user can modify |
+| Prop | Data from parent |
+| Derived | Computed from state/props (filter, map, etc.) |

package/modules/react-fundamentals/quiz.md

@@ -0,0 +1,106 @@
+# React Quiz
+
+## Question 1
+
+What does `useState` return?
+
+A) The current state value only
+B) The setter function only
+C) An array of [value, setter]
+D) The previous state value
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: useState returns a two-element array: [currentValue, setterFunction]. You typically destructure it as const [value, setValue] = useState(initial). -->
+
+## Question 2
+
+When does `useEffect` run if the dependency array is `[count]`?
+
+A) Never
+B) Only on initial mount
+C) On every render
+D) When count changes (and on mount)
+
+<!-- ANSWER: D -->
+<!-- EXPLANATION: The dependency array tells React when to re-run the effect. [count] means run when count changes. It also runs once on mount with the initial value. -->
+
+## Question 3
+
+Which is the correct way to update state based on the previous value?
+
+A) `setCount(count + 1)`
+B) `setCount(prev => prev + 1)`
+C) `count = count + 1`
+D) `this.setState({ count: count + 1 })`
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: When the new state depends on the previous state, use the functional form setCount(prev => prev + 1) to avoid stale closure bugs, especially in async or batched updates. -->
+
+## Question 4
+
+Why do we need keys when rendering a list in React?
+
+A) To improve performance
+B) To help React identify which items changed, were added, or removed
+C) For accessibility
+D) Keys are optional and not required
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Keys help React's reconciliation algorithm track element identity across renders. Without stable keys, React may reuse DOM nodes incorrectly, leading to bugs when reordering or deleting items. -->
+
+## Question 5
+
+What is a controlled component?
+
+A) A component that controls its children
+B) An input whose value is driven by React state
+C) A component that uses useController
+D) A component wrapped in a form library
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: A controlled component is an form input whose value is set by React state (value={state}) and updated via onChange. The React component is the single source of truth. -->
+
+## Question 6
+
+Where can you call hooks?
+
+A) Anywhere in the function body
+B) Only inside event handlers
+C) Only at the top level of a function component or custom hook
+D) In class components
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: Hooks must be called at the top level — not inside loops, conditions, or nested functions. This ensures hooks are called in the same order on every render, which React relies on. -->
+
+## Question 7
+
+<!-- VISUAL: drag-order -->
+
+Put these React render lifecycle stages in the correct order:
+
+A) Component returns JSX (render output)
+B) useState/useReducer initialize or return current state
+C) DOM updates (browser paints)
+D) useEffect runs (after paint)
+
+<!-- ANSWER: B,A,C,D -->
+<!-- EXPLANATION: React first runs the component function; hooks like useState return values (B). The component returns JSX (A). React commits to the DOM, browser paints (C). Then useEffect runs as a post-commit effect (D). -->
+
+## Question 8
+
+<!-- VISUAL: fill-blank -->
+
+Complete the controlled input pattern:
+
+```jsx
+const [value, setValue] = useState('');
+return (
+  <input
+    value={___0___}
+    onChange={(e) => setValue(e.target.value)}
+  />
+);
+```
+
+<!-- ANSWER: value -->
+<!-- EXPLANATION: A controlled input's value prop is driven by React state. The value variable holds the current state, so value={value} makes React the single source of truth. -->