maket: Instructions file for Claude Code

Maket

Visual design tool for Claude — compose HTML/CSS documents with live preview, manage assets, apply brand chartes, export PDF, send via Gmail. MCP server exposed over Streamable HTTP at POST /mcp.

Quickstart

npm run dev       # server --watch + Vite HMR (the one you want 95 % of the time)
npm run dev:watch # server --watch + vite build --watch → public/ (prod-like preview on :24843)
npm run quality   # lint + typecheck + test — same gate as pre-commit
npm run lint:fix  # biome check --write

Node >=22. The server must be running before Claude Code connects (MCP is HTTP-based). The human usually runs it themselves; don't spawn a second dev server.

Coding principles

These aren't style preferences — they're the invariants the codebase depends on. Breaking any of them reliably breaks boot, tests, or the refactor safety net.

Dependency injection via Awilix — no exceptions

• Every service, tool pack, and HTTP route is a factory registered in bootstrap.ts. Consumers resolve by destructured param name. No module-level singletons, no new, no direct imports of concrete implementations.
• Interface first — declare export interface Foo { … } above createFoo. Consumers type against the interface; the factory implements it.
• Factories over classes everywhere — no class keyword in domain code (DocumentStore is the lone exception — a legitimate DB wrapper). Private state lives in factory closures.
• PROXY destructure trap — every destructured name on deps triggers a container lookup. Put optional test overrides on a separate opts arg (see LayoutService, PdfService).
• Container self-reference — bootstrap.ts registers container: asValue(container) so factories that need the container itself (createMcpRouter → mountTools) resolve it via DI.

Separation of concerns is hard-enforced

• If you catch yourself adding a runtime field to a persistence type (the old Document._pending shape), that's a new service. Persistence models hold persistent state; transient state gets its own home. packages/server/src/services/pending.ts is the template — factory + interface + private closures + bus-driven side effects.
• No deprecation shims — when moving state, remove the old field in the same diff and migrate every call site. "No baby-step migrations."