Repository Map

Repository Map

A directory-by-directory guide to the repo. Authored code lives in six places: src/ (Rust engine), web/ (editor), server/ (self-host), app/ + lib/ + db/ + worker/ (Sites/Cloudflare app), desktop/ (Electron) and mcp/ (agent server). Everything else is build tooling, tests, docs, or generated output you should not edit by hand.

At a glance

Area	Directory	Language	Size (approx.)
Document engine	src/	Rust → WASM	~13k lines, 27 modules
Editor UI	web/	Vanilla ES modules + CSS + HTML	~250 files, ~3 MB source
Sites/Cloudflare app	app/, lib/, db/, drizzle/, worker/, components/	TypeScript / Next (vinext)	small
Self-hosted server	server/	Node ESM	17 files
Desktop	desktop/	Electron (CommonJS)	16 files
MCP server	mcp/	Node ESM	6 files
Build & ops scripts	scripts/	Node ESM	44 files
Tests	tests/	node:test, Playwright	~200 files
Docs	docs/, root *.md	Markdown	~37 docs
Product website	site/	Static HTML/CSS/JS	GitHub Pages

Top-level layout

pixlprfct/
├── src/                 Rust crate `pixlprfct-core` (cdylib + rlib) — documents, mutations, history, validation, layout
├── web/                 Browser editor (index.html, app.js hub, ~250 modules, CSS tokens, icon library)
│   ├── pkg/             ⚙ wasm-pack output (generated, gitignored)
│   ├── figma/           .fig parser/converter + worker source (bundled to web/vendor/)
│   ├── vendor/          ⚙ bundled workers (figma-import-worker.js, svg-animation-preview.js) + licenses
│   └── icon-library-assets/   pxlprfct icons (MIT): fonts, CSS, territory-track.json
├── app/                 Next (vinext) app router: Projects page + /api/documents routes
├── components/          React: project-home.tsx, connector-error.tsx, ui/ (shadcn scaffold)
├── lib/                 Cloud document storage (documents, bodies, versions, automatic history) + connectors
├── db/                  Drizzle schema (D1/SQLite) and client
├── drizzle/             SQL migrations 0000–0003 + snapshots
├── worker/              Cloudflare Worker entry (wraps vinext fetch handler with connector binding)
├── server/              Self-hosted Node server: auth, DB adapters, teams, libraries, live editing, admin
├── desktop/             Electron main/preload, policy, updates, MCP discovery, connect screen, builder config
├── mcp/                 MCP server (stdio) + bridge to live editors + saved-project mode + installer tools
├── scripts/             Build, static/desktop packaging, self-host setup, acceptance benchmarks, codegen
├── tests/               node:test suites (*.test.mjs), browser/ (Playwright), fixtures/, helpers/
├── docs/                Feature guides, audits, verification logs (see Docs-Index)
│   └── wiki/            ← this wiki
├── site/                Product website (deployed by .github/workflows/pages.yml)
├── .github/             Workflows (pages, desktop, windows-prerelease), dependabot, CODEOWNERS
├── vendor/              shadcn Tailwind 4 CSS (licensed)
├── examples/d1/         Template example of a D1 route (excluded from typecheck)
├── public/editor/       ⚙ copy of built editor for the Sites app (generated by prepare-editor)
├── dist/                ⚙ Sites build output (generated)
├── .static/             ⚙ static-host build output (generated)
├── .desktop/            ⚙ Electron staging (generated)
├── releases/            ⚙ desktop packages (generated, gitignored)
├── target/              ⚙ Cargo build output
├── roadmap.json         Machine-readable implemented / remaining scope + latest verification
├── inspector-parity.json  Observed Figma inspector controls per selection type
├── AGENTS.md            Standing product requirements for any contributor or AI agent
└── PROJECT_IDEAS.md     Saved direction and resume notes (dated 2026-10-28)

⚙ = generated; do not edit, do not commit.

Root files

File	Purpose
package.json	Version (0.1.1-alpha.19), all npm scripts, dependency pins and overrides
Cargo.toml / Cargo.lock	Rust crate pixlprfct-core; deps: serde, serde_json, wasm-bindgen, js-sys; release profile opt-level = "s", LTO; wasm-opt = false
vite.config.ts	Vite config for the vinext/Sites build (Cloudflare plugin, connector preview plugin)
next.config.ts	Empty Next config (vinext reads it)
drizzle.config.ts	dialect: "sqlite", schema db/schema.ts, out drizzle/
tsconfig.json	Strict TS, allowJs, @/* path alias, Cloudflare worker types; excludes examples, dist, outputs, work
eslint.config.mjs	Next core-web-vitals + TS rules; ignores generated output; allows require in desktop/**/*.cjs
playwright.config.mjs	Browser tests in tests/browser/**/*.spec.mjs, port 4198, 1440×1000 dark, reduced motion
components.json	shadcn/ui config (new-york style)
cloudflare-env.d.ts	Worker Env typings
.openai/hosting.json	Sites project binding: D1 DB, R2 BUCKET — preserve as-is
Dockerfile.selfhost, compose.selfhost.yaml, .dockerignore	Self-host container
.env.selfhost	⚠ Local secret written by selfhost:setup — never commit
LICENSE	Pixel Perfect Community License 1.0 (source-available)
README.md	Long feature log (~75 KB). Good for behavior details; this wiki is the structured entry point
CONTRIBUTING.md, SECURITY.md, PRIVACY.md, CODE_SIGNING.md	Policies
AGENTS.md	Interface requirements + gap-tally rules (see Interface Design Guidelines)

src/ — Rust engine

lib.rs (~3.9k lines) owns the document type, mutations, history and the #[wasm_bindgen] surface. Feature modules: layout.rs (auto layout), grid.rs (CSS-grid layout), components.rs, variants.rs, component_properties.rs, slots.rs, variables.rs, groups.rs, paint.rs, color_styles.rs, text_styles.rs, effect_styles.rs, guide_styles.rs, frame_enclosure.rs, layer_drop.rs, path_join.rs, path_split.rs, stroke_tips.rs, stroke_alignment.rs, arrangement.rs, stacking.rs, rotation.rs, document_order.rs, page_background.rs, starter_defaults.rs, editor_tools.rs. → Rust Document Engine

web/ — editor

Grouped by responsibility (see Web Editor Architecture for the dependency map):

Group	Representative files
Entry pages	index.html (editor), project-home.html, account.html, admin.html, setup.html, svg-animation.html, svg-animation-preview.html
Hub	app.js (~225 KB), editor-entry.js, editor-api.js (generated agent API)
Canvas & rendering	viewport-renderer.js, scene.js, canvas-tools.js, stroke-render.js, paint-shaders.js, css-renderer.js
Tools & editing	toolbelt.js, selection.js, snapping.js, scaling.js, resizing.js, rotation.js, vectors.js, vector-edit.js, pencil.js, text-editing.js, clipboard.js
Layout	auto-layout-inspector.js, layout-*.js, grid-*.js, layout-guides.js, breakpoint-preview.js
Components	variants.js, component-properties.js, slots.js, instance-context.js, assets.js
Styles & paints	variables.js, variable-manager.js, paints.js, paint-popover.js, gradients.js, *-style-controls.js, shadows.js
Prototype & motion	prototype*.js, motion.js, development.js, behaviors.js
Native controls	controls.js, control-inspector.js, input-base.js, dropdown-control.js, …
Inspector chrome	compact-inspector.js, inspector-*.js/.css, contextual-actions.js
Persistence	local-persistence.js, local-drafts.js, local-recovery.js, recovery-store.js, project-file.js, cloud-*.js
Teams & libraries	team-*.js, live-session.js, library-*.js, local-libraries.js
Import / export	design-import.js, figma/, svg-import.js, export.js, batch-export.js, code-export.js, framework-export.js
SVG animator	svg-animation*.js
Agent / desktop	agent-runtime.js, agent-transport.js, agent-connection.js, desktop-integration.js, native-pinch.js
Icons	icon-library.js, icons.js, icon-keywords.js, icon-library-assets/
Design tokens	ui-colors.css, ui-spacing.css, ui-radii.css, ui-typography.css, ui-shadows.css, ui-states.css, ui-motion.css
Hosting adapters	static-host.js, project-home*.js, account*.js, admin.js, setup*.js

scripts/

Folder / file	Purpose
build.mjs, prepare-editor.mjs, run-framework.mjs, build-static.mjs, serve.mjs	Editor bundling, copy into public/editor/, vinext dev/build wrapper, static build, local server :4173
generate-editor-api.mjs	Generates web/editor-api.js (command/model catalog for MCP); --check mode for CI
generate-preloader.mjs, build-figma-import.mjs	Startup animation; bundles web/figma/worker.js → web/vendor/
sites-env.mjs/.sh, install-ci.*, npm-install.mjs, pnpm-install.mjs, install-pnpm.sh, tool-environment.mjs, execution-profile.mjs	Environment and install helpers
self-host/	setup, migrate, backup, container
desktop/	prepare, build, signing, update-feed, release-check
acceptance/	benchmark, mcp-idle, desktop-sleep, pilot-report, complex-fixture, serve (:4198)
connector-preview/, vite/	Sites connector preview worker + Vite plugins
sync-icon-library.mjs, territory-icon-inventory.mjs, update-font-weights.mjs	Asset maintenance

tests/

~200 *.test.mjs files run by node --test (largest groups: grid, layout, prototype, svg, cloud, paint, team, mcp, desktop, component), tests/browser/*.spec.mjs for Playwright (editor, daily-workflow, libraries, library-overrides, live-editing, styles, product-site) with macOS snapshot folders, plus fixtures/ and helpers/. → Testing and Verification

Things that look important but aren't (yet)

• packages/ — empty.
• examples/d1/ — Sites starter example; excluded from tsconfig.
• components/ui/ and hooks/use-mobile.ts — shadcn scaffold from the Sites template; the editor itself does not use React.
• .local/, .agents/, .codex/, outputs/, work/ — local agent/workspace scratch (gitignored).

Related pages

Getting Started · Architecture Overview · Build System · Docs Index

Source of truth

.gitignore, package.json, tsconfig.json, eslint.config.mjs, directory listings at commit 6f3d74b (2026-11-01).