Skip to content

Commit 2acad3c

Browse files
JoviDeCroockJoviDeCroock
committed
Changes
1 parent 5163eff commit 2acad3c

File tree

8 files changed

+669
-97
lines changed

8 files changed

+669
-97
lines changed

‎CLAUDE.md

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the Preact Signals library - a performant state management solution that provides reactive primitives for JavaScript frameworks. The library is built as a monorepo with multiple packages for different framework integrations.
8+
9+
## Commands
10+
11+
### Building
12+
13+
- `pnpm build` - Build all packages
14+
- `pnpm build:core` - Build core signals package only
15+
- `pnpm build:preact` - Build Preact integration
16+
- `pnpm build:react` - Build React integration
17+
- `pnpm prebuild` - Clean all dist directories
18+
19+
### Testing
20+
21+
- `pnpm test` - Run all tests (Karma browser tests + Mocha Node tests)
22+
- `pnpm test:karma` - Run browser tests with coverage
23+
- `pnpm test:karma:watch` - Run browser tests in watch mode
24+
- `pnpm test:mocha` - Run Node.js tests with coverage
25+
- `pnpm test:prod` - Run tests in production mode with minification
26+
27+
### Development
28+
29+
- `pnpm lint` - Run linting (oxlint + TypeScript)
30+
- `pnpm lint:oxlint` - Run oxlint on TypeScript/JavaScript files
31+
- `pnpm lint:tsc` - Run TypeScript compiler checks
32+
- `pnpm format` - Format code with Prettier
33+
34+
## Architecture
35+
36+
### Monorepo Structure
37+
38+
- **packages/core/** - Core signals implementation (framework-agnostic)
39+
- **packages/preact/** - Preact framework integration
40+
- **packages/react/** - React framework integration
41+
- **packages/react/runtime/** - React runtime hooks
42+
- **packages/react/utils/** - React utility components
43+
- **packages/preact/utils/** - Preact utility components
44+
- **packages/debug/** - Debug extension for browser devtools
45+
- **packages/react-transform/** - Babel transform for React
46+
47+
### Package Dependencies
48+
49+
The core package (`@preact/signals-core`) contains the framework-agnostic signals implementation. Framework packages depend on core and add their specific integrations:
50+
51+
- Preact integration adds hooks and rendering optimizations
52+
- React integration provides compatibility with React components
53+
- Debug package adds browser devtools integration
54+
55+
## Development Notes
56+
57+
- Uses pnpm workspaces with specific Node.js version (18.18.0 via Volta)
58+
- All packages build to `dist/` directories which are cleaned before builds
59+
- TypeScript path aliases allow importing packages by their published names during development
60+
- Extension package provides Chrome devtools integration
61+
- Documentation is built with Vite and served from `docs/` directory
62+
63+
## Chrome Extension Development
64+
65+
### Architecture
66+
67+
The Chrome extension (`/extension`) integrates with the debug package (`packages/debug/src`) to provide visualization of signal updates and dependencies.
68+
69+
Use signals for everything rather than hooks, you can replace any hook with a `useSignal`, `useComputed`
70+
or `useSignalEffect` invocation instead.
71+
72+
### Panel Features
73+
74+
The Chrome extension provides two main visualization modes through a tabbed interface:
75+
76+
#### Updates Panel (Default Tab)
77+
78+
The updates panel provides real-time monitoring of signal changes:
79+
80+
**Core Features:**
81+
82+
- **Real-time Updates**: Live stream of signal value changes and effect executions
83+
- **Depth Visualization**: Indented display showing dependency depth (0 = root signals, 1+ = dependent updates)
84+
- **Update Statistics**: Header shows total update count and number of unique signals
85+
- **Value Comparison**: Side-by-side display of previous → new values with syntax highlighting
86+
- **Timestamp Information**: Each update shows when it occurred
87+
- **Type Differentiation**: Visual distinction between signal updates and effect executions
88+
- **Grouping Support**: Updates from the same trigger are grouped with divider lines
89+
90+
**Visual Indicators:**
91+
92+
- 🎯 Root signals (depth 0) - the original source of updates
93+
- ↪️ Dependent updates (depth 1+) - computed values and effects triggered by root signals
94+
- Color-coded borders: Blue for value updates, Orange for effect executions
95+
- Monospace font for values to maintain readability
96+
97+
**Interactive Controls:**
98+
99+
- **Pause/Resume**: Stop updates temporarily without losing connection
100+
- **Clear**: Reset the update history
101+
- **Settings**: Configure filtering, grouping, and update rate limiting
102+
- **Filter Patterns**: Regex-based filtering to focus on specific signals
103+
104+
#### Signal Dependency Graph
105+
106+
A new dependency graph visualization has been added to the Chrome extension panel:
107+
108+
#### Debug Package Changes (`packages/debug/src/`)
109+
110+
- **internal.ts**: Added `subscribedTo?: string` field to `UpdateInfo` interfaces to track signal dependencies
111+
- **index.ts**:
112+
- Added `signalDependencies` WeakMap to track what each signal depends on
113+
- Added `getSignalId()` function to create unique IDs for signals
114+
- Added `trackDependency()` function to record signal-to-signal relationships
115+
- Modified `Computed.prototype._refresh` to track dependencies via `subscribedTo` field
116+
- Modified `Effect.prototype._callback` to track dependencies via `subscribedTo` field
117+
118+
#### Chrome Extension Changes (`extension/src/`)
119+
120+
- **panel.tsx**:
121+
- Added `signalId` and `subscribedTo` fields to `SignalUpdate` interface
122+
- Added graph data structures: `GraphNode`, `GraphLink`, `GraphData`
123+
- Created `GraphVisualization` component with SVG-based dependency graph
124+
- Added tab system with "Updates" and "Dependency Graph" tabs
125+
- Graph uses depth-based layout positioning nodes by their dependency depth
126+
- **panel.css**:
127+
- Added tab styles with active state highlighting
128+
- Added graph visualization styles including node types (signal, computed, effect)
129+
- Added legend styles and responsive layout adjustments
130+
131+
#### Key Features
132+
133+
- **Depth-based Layout**: Nodes are positioned horizontally by their depth (0 = original signal, 1+ = dependent signals/effects)
134+
- **Visual Differentiation**: Different colors for signals (blue), computed values (orange), and effects (green)
135+
- **Dynamic Updates**: Graph rebuilds automatically as new signal updates are received
136+
- **Interactive Legend**: Shows the meaning of different node colors
137+
138+
#### Dependencies Tracked
139+
140+
- Depth 0: Original signals that trigger updates
141+
- Depth 1+: Computed signals and effects that depend on signals at previous depths
142+
- Links show the direction of dependency (source → target)
143+
144+
### Connection Management
145+
146+
The extension uses a multi-layer communication system:
147+
148+
1. **Background Script**: Manages devtools connection and message routing
149+
2. **Content Script**: Injects into the target page and bridges to debug package
150+
3. **Panel**: Receives updates and provides visualization interface
151+
4. **Debug Package**: Hooks into signal internals and sends updates
152+
153+
**Connection Status Indicators:**
154+
155+
- 🟢 Connected - Full communication established with signal debugging active
156+
- 🟠 Connecting/Warning - Partial connection or no signals detected
157+
- 🔴 Disconnected - No communication with target page
158+
159+
**Settings & Configuration:**
160+
161+
- **Enable/Disable**: Toggle debug monitoring on/off
162+
- **Grouping**: Control whether related updates are visually grouped
163+
- **Rate Limiting**: Prevent UI overload with configurable max updates per second
164+
- **Pattern Filtering**: Use regex patterns to show only relevant signals
165+
166+
## Package Manager
167+
168+
This project requires pnpm. All scripts should be run with `pnpm` rather than `npm` or `yarn`.

‎docs/demos/index.tsx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ function displayName(name: string) {
5858
}
5959

6060
function Counter() {
61-
const count = useSignal(0, "counter");
61+
const count = useSignal(0, { name: "counter" });
6262

6363
return (
6464
<div class="card">
@@ -69,7 +69,7 @@ function Counter() {
6969
);
7070
}
7171

72-
const globalCount = signal(0, "global-counter");
72+
const globalCount = signal(0, { name: "global-counter" });
7373
function GlobalCounter({ explain = true }) {
7474
return (
7575
<>

0 commit comments

Comments
 (0)