windows-xp
CLAUDE.md5 starsChanged 4 months agoMITView on GitHub
This file provides guidance to Claude Code when working with this repository. An embeddable, scriptable Windows XP desktop engine for React + TypeScript, published as @caoergou/windows-xp. It faithfully recreates the XP experience (file system, apps, boot/login flow, window management, Luna visuals) while exposing it as a product: content is injectable (customFileSystem, culture packages, custom apps), every user action emits a typed event (onEvent), and the desktop is drivable via an imperative ref handle. Principles, red lines, and the doc map…
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
18 rules. About 0 are common, 5 are distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 39
Start the dev server: npm run dev (serves http://localhost:5173/windows-xp/.
- Very specific: line 41
Write a script inside the repo tree (so Node resolves playwright from node_modules.
- Distinctive: line 123
If a screenshot reveals a defect, fix it and re-capture before committing.
- Very specific: line 214
All applications are registered in APP_REGISTRY, the single source of truth for:
- Distinctive: line 216
Default window configuration (width, height, singleton, resizable)
- Very specific: line 220
Prefer nameKey (an i18n key resolved via getAppDisplayName) over a hardcoded name.
- Very specific: line 238
Use resolveFileOpen(key, item) to resolve a filesystem node to window props, and getAppDisplayName(entry) for names (nameKey translation → …
- Very specific: line 297
Recycle Bin items: Add JSON files to src/data/recycle_bin/
- Very specific: line 299
Desktop shortcuts: Add entries to the root.children section of filesystem.json
- Very specific: line 303
Create component in src/apps/YourApp.tsx
- Very specific: line 304
Add entry in src/registry/apps.tsx (APP_REGISTRY)
- Very specific: line 305
Add a desktop shortcut or file association in filesystem.json
- Very specific: line 341
No behavior-semantics leakage: don't hard-code XP behaviors (e.g.
- Very specific: line 388
NEVER: add Co-Authored-By: Claude ...
- Very specific: line 390
NEVER: add "Generated with Claude Code", "🤖", session links (Claude-Session: ...
- Distinctive: line 396
Commit messages must describe the change only, written as a normal human commit message.
- Distinctive: line 398
If any tool or template auto-inserts such attribution, remove it before committing or publishing.
- Distinctive: line 410
If a commit was already created with the wrong identity, repair it with git commit --amend --reset-author --no-edit (or rebase for multiple …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code when working with this repository.
Project Overview
An embeddable, scriptable Windows XP desktop engine for React + TypeScript, published as @caoergou/windows-xp. It faithfully recreates the XP experience (file system, apps, boot/login flow, window management, Luna visuals) while exposing it as a product: content is injectable (customFileSystem, culture packages, custom apps), every user action emits a typed event (onEvent), and the desktop is drivable via an imperative ref handle.
Principles, red lines, and the doc map live in AGENTS.md; code-level rules in docs/DEVELOPMENT.md; the XP-authenticity baseline in FIDELITY.md; the completed roadmap and future issue policy in docs/ROADMAP.md; design/analysis docs in docs/ (USE-CASES.md, PUZZLE-DESIGN.md, OS-PLATFORM-VISION.md).
Development Commands
npm run dev # Start dev server
npm run build # Production build
npm run preview # Preview production build
npm test # Run testsVisual Verification (REQUIRED for every UI change)
Visual fidelity is a first-class deliverable of this project, not a nice-to-have. Any change that touches rendered UI must be verified by looking at a real screenshot — never "assume it looks right" from the code alone. Reading the diff tells you what you changed; only a screenshot tells you what the user sees. When a change is subtle (spacing, borders, gradients, flush edges, sort arrows, icon alignment), the screenshot is the only reliable signal.
The behavioural e2e assertions (toBeVisible, getByText) confirm the DOM exists;
they do not confirm it looks like Windows XP. Do both: assert behaviour in a
spec, and eyeball a screenshot.
How to capture a component screenshot
The e2e stack (Playwright + a pre-installed Chromium at PW_CHROMIUM_PATH, e.g.
/opt/pw-browsers/chromium) is already wired for this. For a one-off screenshot,
write a standalone script and read the PNG back with the file-reading tool.
- Start the dev server:
npm run dev(serveshttp://localhost:5173/windows-xp/; Vite may fall back to5174if5173is taken — check the startup log). - Write a script inside the repo tree (so Node resolves
playwrightfromnode_modules; a scratchpad path will fail withERR_MODULE_NOT_FOUND). Delete it afterwards so it never gets committed. - Save the PNG to the scratchpad dir, then open it with the Read tool and inspect
it against the checklist below — in both
enandzh.
// _shot.mjs — run from repo root: `node _shot.mjs`, then `rm _shot.mjs`
import { chromium } from 'playwright';
const BASE = 'http://localhost:5173/windows-xp/';
const OUT = '<your scratchpad dir>';
const PW = 'forthe2000s'; // e2e/helpers/login.ts LOGIN_PASSWORD
const browser = await chromium.launch({ executablePath: '/opt/pw-browsers/chromium' });
async function shot(lang, file) {
const page = await browser.newPage({ viewport: { width: 1024, height: 768 } });
// Skip the boot animation so we land on the login screen quickly.
await page.addInitScript(() => {
localStorage.clear();
localStorage.setItem('xp_first_boot_done', 'true');
localStorage.setItem('xp_power_state', 'running');
});
await page.goto(`${BASE}?lang=${lang}`, { waitUntil: 'networkidle' });
// Log in (default password), then wait for the desktop.
const pw = page.locator('input[type="password"]').first();
await pw.waitFor({ state: 'visible', timeout: 10000 });
await pw.fill(PW);
await page.keyboard.press('Enter');
await page.waitForSelector('[data-testid="taskbar"]', { timeout: 20000 });
// Drive the UI to the exact state you want to inspect. Stable selectors:
// desktop icons → [data-english-testid="desktop-icon-<english-name>"]
// file items → [data-testid="file-item-<key>"]
// toolbar btns → button[title="<translated title>"]
await page.locator('[data-english-testid="desktop-icon-my-documents"]').dblclick();
await page.waitForSelector('[data-testid="file-item-readme.txt"]');
await page.screenshot({ path: `${OUT}/${file}` }); // full frame
// For a single component, screenshot the locator instead:
// await page.locator('.xp-window').screenshot({ path: ... });
await page.close();
}
await shot('en', 'view-en.png');
await shot('zh', 'view-zh.png');
await browser.close();Tips: use page.locator(sel).screenshot() to crop to one window/component; bump
viewport for tall content; page.waitForTimeout(400) after opening a menu so
animations settle; language is set with the ?lang=en|zh query param.
XP-style detail checklist
Inspect every screenshot against these — a change is not "done" until it passes.
The authoritative behaviour/visual baseline is FIDELITY.md (✅/🟡/❌ per feature);
this list is the recurring per-change eyeball pass.
- Luna chrome — title bars use the blue Luna gradient with the correct glossy highlight; the min/max/close buttons are the real XP glyphs, red close button on the right; window borders are the ~3px Luna blue, not flat 1px.
- Flush & spacing — panels/toolbars/list headers sit flush against their container edges (no stray padding gaps, e.g. a Details header must touch the address bar). Match XP's tight paddings; don't invent whitespace.
- Typography — Tahoma-style UI font; no oversized/undersized text; menu
mnemonics render as
File(F)etc. where the locale uses them. - Gradients & fills — column headers, buttons and selected rows use the pale
blue XP gradients (not flat grey); selection highlight is XP blue
#316AC5-ish. - Icons — correct 16px/32px/48px XP icons, crisp (not stretched), aligned to the text baseline; folder vs file vs app icons are right.
- Affordances — sort arrows (▲/▼) on the active Details column; hover states on toolbar buttons; disabled menu items greyed, not clickable no-ops.
- i18n parity — capture
enANDzh. No untranslated raw filesystem keys leaking into the UI (e.g. a Chinese folder key showing in the English desktop), no clipped/overflowing labels, dates/sizes formatted per locale. China-only culture apps (QQ, 360, 迅雷, …) stay Chinese-only — do not add English for them. - Pixel realism — compare against real XP references when unsure; prefer value-for-value matching of xp.css over eyeballed approximations.
If a screenshot reveals a defect, fix it and re-capture before committing. Record what you verified (and attach/inspect the PNG) so the check is auditable.
Pitfalls learned the hard way
These are real misses from past changes — check them explicitly, because a casual glance will pass over all of them:
- Full-frame screenshots hide small defects. A 4px clipped tooltip tail, a
1px border, a slightly-off gradient, a header that isn't quite flush — none of
these are visible in a 1024×768 capture. For any fine detail, take a tight,
zoomed crop of the exact region (
clip: { x, y, width, height }, orlocator.screenshot()), and inspect that. "Looks fine in the full frame" is not verification. - Don't trust CSS geometry math for transformed elements. A
rotate(45deg)diamond tail extends further than its box;transform,box-shadow, and borders all push real pixels past the layout box. Compute a first guess, then measure the rendered rect (locator.boundingBox()) and log the numbers to confirm — twice I "did the math" and was wrong by a few px. - Check overlap and z-index against fixed chrome. The taskbar uses the max
z-index (
2147483647); anything that overlaps it is hidden behind it. A floating element near the taskbar (balloon, popup, menu) must sit entirely clear of it — verify no part is clipped or occluded, at zoom. - Anchored elements must actually point at their anchor. A tray balloon must emanate from its specific tray icon (tail centred on the icon), a tooltip from its trigger, a menu from its button. Don't settle for "roughly in the corner" — measure the anchor's centre and confirm the pointer/tail lines up (log the two x-coordinates; they should match).
- When the user reports a visual bug, reproduce it at the same zoom they saw it, fix, then re-capture the same crop to prove it's gone. Do not re-assert "it's correct" from the code — the reason it shipped broken is that the code looked right.
Tech Stack
- Framework: React 18 + Vite 5
- Language: TypeScript 5
- Styling: styled-components + xp.css (Windows XP theme)
- Window interaction: react-draggable + react-resizable
- Internationalization: i18next
Architecture
Context Providers (in src/components/AppProviders.tsx)
I18nextProvider
└─ AppRegistryProvider
└─ CultureProvider
└─ CultureAwareProviders
└─ StorageProvider
└─ EventBusProvider
└─ UserSessionProvider
└─ FileSystemProvider
└─ WindowManagerProvider
└─ TrayProvider
└─ ModalProvider
└─ AppAppRegistryProvider— injectable app registry (appsprop) anduseAppRegistry().CultureProvider— injectable culture packages (culturesprop) anduseCulture().StorageProvider— per-instance isolated storage handle (storagePrefix); all localStorage/IndexedDB access goes throughuseStorage().EventBusProvider— one typed event bus per instance (src/events.ts); bridged to theonEventprop anduseXPEvents().UserSessionProvider— login state, wallpaper, screensaver.FileSystemProvider— virtual file system with persistence.WindowManagerProvider— window lifecycle, z-index, focus.TrayProvider— system tray icon registry.ModalProvider— alert/confirm/prompt/password dialogs.
Events & Imperative API (src/events.ts, src/components/XPBridge.tsx)
src/events.tsis the single event catalog (typedXPEventunion,domain:actionnaming). Contexts emit; consumers subscribe via theonEventprop oruseXPEvents().XPBridge.tsxwires therefhandle (XPHandle) viauseImperativeHandle: top-levelopenApp/openFile/closeWindow/showAlert/resetplus the grouped actuation APIs from #115 —fs.*(read/write/create/delete/unlock),session.*,appearance.*,windows.*,sound.play,emit, andgetSnapshot/loadSnapshot(versioned XPSnapshot save/load,src/snapshot.ts, #117). New host-facing capabilities belong on this handle.- Rule: new user-visible interactions should emit an event; names follow the #130 grammar.
Window Management (src/context/WindowManagerContext.tsx)
Each window object:
{
id, appId, title, component, componentProps,
icon, props, isMinimized, isMaximized,
zIndex, width, height, left, top
}Windows persist across refreshes via localStorage('xp_open_windows'). Components are restored by WindowFactory.tsx using appId + componentProps.
App Registry (src/registry/apps.tsx)
All applications are registered in APP_REGISTRY, the single source of truth for:
- Application metadata (id,
nameKey/name, icon) - Default window configuration (width, height, singleton, resizable)
- Locale gating:
locales— optional list of culture ids (e.g.['zh']for the China-only apps); omit for apps available everywhere - File associations and restoration logic
Prefer nameKey (an i18n key resolved via getAppDisplayName) over a hardcoded
name; name remains as the fallback when no nameKey is set.
export const APP_REGISTRY: Record<string, AppRegistryEntry> = {
Calculator: {
id: 'Calculator',
name: 'Calculator', // fallback only —
nameKey: 'apps.calculator', // display name resolves through i18n first
icon: 'calculator',
window: { width: 208, height: 196, resizable: false, singleton: true },
associations: [{ appField: 'Calculator', getProps: () => ({}) }],
restore: (props) => <Calculator {...props} />,
},
// ... more apps
};Use resolveFileOpen(key, item) to resolve a filesystem node to window props, and getAppDisplayName(entry) for names (nameKey translation → name fallback).
File System (src/context/FileSystemContext.tsx)
- Structure defined in
src/data/filesystem.json - Recycle Bin items loaded dynamically from
src/data/recycle_bin/*.json - File node properties:
type,name,icon,locked,password,broken,children,hidden(filtered from Explorer unless "show hidden files" is on),protected(in-fiction UI refuses delete/rename),mtime(ISO 8601, feeds Details "Date Modified" + Properties)
User Session (src/context/UserSessionContext.tsx)
- User config in
src/data/user_config.json login(password)/logout()methods- Session state in localStorage
Applications (src/apps/)
| App | File | Description |
| Explorer | Explorer.tsx | File browser with path navigation |
| InternetExplorer | InternetExplorer/ | Web browser with history, favorites, era portals |
| Notepad | Notepad.tsx | Text editor (undo, find/replace, word wrap, save to FS) |
| PhotoViewer | PhotoViewer.tsx | Image viewer |
| Calculator | Calculator.tsx | Calculator with full functionality |
| MicrosoftPaint | MicrosoftPaint.tsx | Drawing app; saves PNG into the virtual FS |
| Minesweeper | Minesweeper.tsx | Classic minesweeper (XP sprites, best times) |
| Solitaire | Solitaire.tsx | Solitaire with full move rules & win detection |
| WindowsMediaPlayer | WindowsMediaPlayer.tsx | Media player UI (plays bundled sample) |
| CommandPrompt | CommandPrompt.tsx | CMD emulator (real command set + easter eggs) |
| ControlPanel | ControlPanel/ + ControlPanel.tsx | System settings (display/sound/mouse applets) |
| TaskManager | TaskManager.tsx | Task manager over live window state |
| QQLogin | QQLogin.tsx | QQ login dialog (zh culture) |
| SafeGuard360 | SafeGuard360.tsx | 360 antivirus with scripted threat-scan story (zh) |
| Thunder | Thunder.tsx | Thunder download manager shell (zh) |
| KugouMusic | KugouMusic.tsx | Kugou music player shell (zh) |
| BaofengPlayer | BaofengPlayer.tsx | Baofeng video player shell (zh) |
| WPSOffice | WPSOffice.tsx | WPS Office shell (zh) |
| HelpAndSupport | HelpAndSupport.tsx | Help center |
| RunDialog | RunDialog.tsx | Run dialog (winver/sol/winmine/bsod eggs) |
| VolumeControl | VolumeControl.tsx | Volume settings |
| NetworkConnections | NetworkConnections.tsx | Network status |
| BrowserPlugins | BrowserPlugins.tsx | Browser plugins page (IE nostalgia content) |
| FileProperties | components/FileProperties.tsx | File properties dialog (registry entry) |
| DummyApp | (in registry) | "Coming soon" placeholder — no content references it anymore |
Adding Content
New files in the filesystem: Edit src/data/filesystem.json
{
"MyFile.txt": {
"type": "file",
"name": "MyFile.txt",
"app": "Notepad",
"content": "File content here"
}
}Recycle Bin items: Add JSON files to src/data/recycle_bin/
Desktop shortcuts: Add entries to the root.children section of filesystem.json
Adding a New Application
- Create component in
src/apps/YourApp.tsx - Add entry in
src/registry/apps.tsx(APP_REGISTRY) - Add a desktop shortcut or file association in
filesystem.json
Example registry entry:
YourApp: {
id: 'YourApp',
name: 'Your App', // fallback; user-facing name comes from i18n
nameKey: 'apps.yourApp', // add the key to both en.json and zh.json
icon: 'app_window',
window: { width: 400, height: 300, singleton: true },
associations: [{ appField: 'YourApp', getProps: () => ({}) }],
restore: (props) => <YourApp {...props} />,
},Note: restore props are persisted for refresh-restoration and must be JSON-serializable (no functions/elements) — see docs/DEVELOPMENT.md §1. A defineApp() factory that simplifies all of this is planned in #128.
Platform-Readiness Rules (#143 — enforced by npm run guard:purity)
The long-term direction (#143 RFC, docs/OS-PLATFORM-VISION.md) decouples the
engine from "XP": the OS becomes a definable package. We are NOT building that
yet — but every PR must avoid growing the surgery cost. Non-negotiables
(details: docs/DEVELOPMENT.md §7; quick list: AGENTS.md red lines 11/12):
- Mechanism vs. XP-skin layering: engine dirs (
src/context,src/hooks,src/utils,src/events.ts,src/snapshot.ts) must contain zero color literals, zero xp.css imports, zero asset-file imports, zero XP-specific chrome assumptions. CI-enforced. - Inline hex is ZERO outside the sanctioned stores (#213): OS-chrome colors
live in
src/themes/xp/tokens.ts(COLORS/FONTS, re-exported viasrc/constants.ts); app-identity colors live in declaredbrand-palette:start/endblocks in allow-listed files (seedocs/THEMING.md).HEX_BASELINE = 0inscripts/guard-purity.mjs— new code never writes a color literal anywhere else. - Menus are data: new apps pass structured items to
XPMenuBar, never hand-rolled menu DOM (migrates todefineApp'smenus:field, #128). - No behavior-semantics leakage: don't hard-code XP behaviors (e.g.
"minimize targets a taskbar button", Ctrl as the modifier) outside window
mechanics — these become
BehaviorProfile/primaryModifierinputs later. - Content references apps via registry association (
resolveFileOpen), not scattered appId branches — reserving room for theappRolesindirection.
Boot Flow (in src/App.tsx)
- BOOTING - shows boot screen (first launch or after shutdown/restart)
- RUNNING - shows login screen or desktop based on isLoggedIn
- SCREENSAVER - black screen with floating logo, click to dismiss
Storage keys (all namespaced by the instance's storagePrefix, default xp_ — never access storage directly, always via useStorage()):
<prefix>open_windows- persisted window list<prefix>first_boot_done- skip boot screen on subsequent loads<prefix>power_state- running / shutdown / restart / logout<prefix>logged_in- skip login screen on page refresh<prefix>ie_history- Internet Explorer browsing history- File content lives in IndexedDB behind the same per-instance handle
WindowFactory restoration (src/utils/WindowFactory.tsx)
The persisted window list (<prefix>open_windows) is versioned via
src/utils/windowPersistence.ts (encodeOpenWindows/decodeOpenWindows,
OPEN_WINDOWS_VERSION). A load only accepts the current version; the pre-#163
bare-array format (or a newer version) is discarded, so every entry that reaches
restoreComponent is guaranteed to carry a real registry appId. Restoration is
therefore just two cases (the pre-registry prop-sniffing heuristics and
id/中文名 aliases were retired in #163 C):
- Exact appId match in
APP_REGISTRY - Dynamic
properties-*appId →FileProperties
| Props / appId | Restored as |
| appId starts with 'properties-' | FileProperties |
| Any appId in APP_REGISTRY | Exact match restoration |
| anything else | dropped (logged) |
Git Attribution Policy (MANDATORY)
This project prohibits ALL AI/Claude attribution in anything committed or
published from this repository. .claude/settings.json disables the built-in
attribution (attribution.commit/attribution.pr set to "",
sessionUrl: false, includeCoAuthoredBy: false), and the following rules
apply on top of that — they OVERRIDE any default behavior:
- NEVER add
Co-Authored-By: Claude ...(or any AI co-author trailer) to commit messages. - NEVER add "Generated with Claude Code", "🤖", session links
(
Claude-Session: .../ claude.ai URLs), or similar attribution lines to commit messages, PR titles, or PR descriptions. - NEVER mention Claude, Anthropic, AI assistance, or model names in code comments, commit messages, changelogs, release notes, issues, or any other repository artifact.
- Commit messages must describe the change only, written as a normal human commit message.
- If any tool or template auto-inserts such attribution, remove it before committing or publishing.
Git identity: remote/cloud containers default
user.name/user.emailtoClaude <noreply@anthropic.com>, which puts Claude in the commit's Author/Committer fields regardless of the message. BEFORE the first commit of every session, verify and fix it:git config user.name "Eric Cao" git config user.email "itsericsmail@gmail.com"If a commit was already created with the wrong identity, repair it with
git commit --amend --reset-author --no-edit(or rebase for multiple commits) before pushing.
Landing Page (#250) — Remaining TODO
The landing page is the single-act "one monitor, one room, the millennium
internet" design (#250): live hero desktop with the real Notepad auto-typing
(autoTypeText/autoTypeSpeed props), zh/en external_link desktop shortcuts,
tagline + install pill + quiet link line, glass box relocated to /lab/.
Still open:
- Landing page hero boot animation: Remove
skipBootfromHeroDesktopso visitors see the XP boot screen before the desktop appears. Fire the greeteropenAppafter thesession:loginevent instead of the fixed 900ms timeout. - Regenerate
public/images/og.pngwhen the hero/tagline changes — it is a real screenshot of the page (1200×630) and drifts silently otherwise.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

