Design specifications · Patties specs

Framework · draft 2

Monorepo React single-copy resolutionThe --monorepo scaffold option ([[cli/18-create-patties-redesign]]) puts each Task runner + output cache (patties run)Give Bun-workspace monorepos ([[cli/18-create-patties-redesign]]) the one thing

Framework · archive 27

Patties Framework — OverviewPatties is a Bun-native full-stack meta-framework with React for UI and Bun's own Bun.serve for HTTP, in a single bun dev command, deployable to the edge wit… Conventions & Critical RulesThese are the bright lines. An agent violating any of them is wrong, regardless of how reasonable the change looks. CI PipelinePatties is Bun-native and edge-first (00-overview, pillars 1 and 4). The CI pipeline must defend both: it runs entirely on Bun (no Node toolchain in the inst… Dev-time island bundling — design decisionThis spec exists to decide how Patties produces hydrated islands during Dev island bundler — implementationImplements the design decided in spec 17: Request IDs — ctx.requestId + X-Request-Id echoThis spec encodes [[rfc-bun-random-uuidv7]]. It supersedes the relevant Server-Timing — dev-only response duration headerThis spec encodes [[rfc-bun-nanoseconds]]. It extends the response Embedded files — single-binary deploy with embedded static assetsThis spec encodes [[rfc-bun-embedded-files]]. It extends the build Image pipeline — build-time variants + runtime endpoint + signed cacheThis spec encodes [[rfc-bun-image]]. It introduces a next/image-class Markdown pages — .md/.mdx routes with islands-in-markdownThis spec encodes [[rfc-bun-markdown]]. Mount .md and .mdx files Bun-builtin policy — Archive, ANSI helpers, one-shot hashingThis spec encodes three RFCs at once — [[rfc-bun-archive]], patties.config.ts — optional `ui` blockshadcn centralizes UI scaffolding config in components.json. patties replaces ServerBoot the HTTP server that hosts the user's Patties app. The framework wraps Bun.serve() and uses its native routes: map (introduced in Bun 1.2) as the dispat… RouterCompile the user's app/routes/ directory into the routes: object consumed by 01-server. This spec is the integration point between the filesystem layout and … Filesystem RouterScan app/routes/ with Bun.Glob and produce a sorted, deterministic list of RouteEntry records consumed by 02-router. Server RenderRender page route modules to HTML using React (react-dom/server). Stream the response by default; the renderer always returns a ReadableStream-backed Response. Claude Code Scaffold (CLAUDE.md + .claude/)Invoked by create-patties --agent claude-code (CLI 05). BuildProduce the client JavaScript bundle for islands and the deployable server bundle for the configured target. The only bundler is Bun.build. Dev / HMRProvide the dev-time feedback loop: reload changed modules in place and tell connected browsers to refresh. The dev runner is bun --hot by default (state-pre… Client IslandsHydrate interactive components in the browser using React (react-dom/client). Pages are static SSR HTML; islands are the only interactive units. Each island … MiddlewareAllow users to wire one global middleware in front of every route. This is also the answer to "where do I do auth / logging / headers?" — replacing Next-styl… Testing (Fixture-Driven)Every framework feature is verified by a real Patties app that exercises it. Fixtures are the source of truth — unit tests support them, they do not replace … ConfigSingle configuration file for a Patties project. Optional — sensible defaults must work without it. Edge AdaptersTranslate the framework's built server bundle into a form the target runtime can execute. The framework ships two built-in adapters — bun and edge — and stay… Agents & Tools (AI-Native Layer)This is the layer that separates Patties from HonoX. Agents and tools are first-class filesystem entries — not configuration, not plugins. The framework wire… AGENTS.md GeneratorEmit AGENTS.md at the project root on every build. The file tells any AI agent (Claude Code, etc.) exactly how this specific app is structured, so it can add… PluginsAllow third parties to extend Patties without forking. The contract is small on purpose: plugins receive a small route-registration API and a set of hooks; t…

CLI · draft 3

create-patties redesign — guided scaffold + agent handoffSpec 09 turned the scaffolder into a real interactive prompt with a working /patties skill + /patties-init flow — components & pattern modulesThe redesigned scaffolder (spec 18) stops patties doctor — project hygiene checksGive a patties project a single "is this project healthy?" command. The scaffold

CLI · archive 17

Patties CLI — Overviewpatties is the single command-line entry point developers use to work with a Patties project. Three verbs cover the daily loop — dev, build, deploy — plus a … Entry & DispatchThe shebang'd executable that package.json#bin points at. Parses argv, picks a command handler, and exits with the handler's return code. patties devStart the local development server with hot reload, ready to use in one command. patties buildProduce a production artifact in outDir (default .patties/ → dist/ for the deploy adapter), tailored to the configured target. patties deployTake a built Patties app and push it to the configured host. The framework core is vendor-neutral — the actual deploy step is owned by an installed deploy pl… create-patties Scaffolderbunx create-patties my-app produces a new Patties project that runs immediately with bun dev. This is the developer's first impression of the framework; it m… Config LoadingA single shared routine every CLI command calls to find, load, and validate patties.config.ts. The framework spec 08-config defines the file's shape; this sp… Logging, Errors, Exit CodesMake the CLI's output predictable and useful — for humans, for CI logs, and for agents reading transcripts. patties secretManage dev-time secrets stored in the OS keychain via Bun.secrets. This is the developer-facing companion to the secrets: config field in framework 08-config… create-patties DX overhaulThe Phase-0 scaffolder (spec 05) gets users a project directory. It does not Scaffold tool probes — bun (fail) + git (warn) via Bun.whichThis spec encodes [[rfc-bun-which]]. It extends the create-patties patties ui initshadcn's init bootstraps components.json, installs base deps, writes CSS patties add --diff / patties updateThe copy-in model's single biggest weakness is upstream drift: once a patties add --view / patties viewshadcn lets you preview a registry item's source before installing (view / patties add --pathThe destination for patties add is hard-coded to app/components/ui/. shadcn's Registry distribution — remote/URL/namespaced installs + patties ui buildshadcn resolves components from a built registry.json that can live at an patties migrate (rtl, radix)shadcn ships migrate rtl (rewrite physical CSS props → logical props) and

UI · archive 63

RFCS · accepted 27

Bun.Archive — tar/zip packaging for deploy pluginsAccept as a policy adoption — not a standalone spec feature. Bun.stringWidth / stripANSI / wrapAnsi — terminal output utilitiesAccept as a policy adoption. Patties' CLI surface Bun.Cookie / Bun.CookieMap — adopt native cookie API in middlewareAccept. Closes the auth-shaped hole in spec 07. With Hono removed, the cookie story gets simpler — ctx.cookies is a thin pass-through to Bun.CookieMap rather… Bun.cron — first-class scheduled jobs conventionAccept. app/jobs/ is the natural parallel to app/agents/ and app/tools/ — closes the gap where spec 10 mentions cron callers without defining them. Bun.CSRF — native CSRF token generation/verification in middlewareAccept, depends on [[rfc-bun-cookies]] and (for renderer auto-injection) [[rfc-bun-htmlrewriter]]. Bun.embeddedFiles — single-binary deploy with embedded static assetsAccept. This is the only acceptance in the bucket-A pass that Bun.hash / Bun.sha — one-shot hash helpersAccept as a policy adoption — and an active complement to bun --hot — state-preserving reload as alternative to --watchAccept. The most important RFC in this batch — spec 05 was designed around --watch's teardown problem, and --hot eliminates the problem rather than working a… HTMLRewriter — streaming HTML transforms for SSR + edgeAccept, Phase 2 — not blocking Phase 0/1. Architecturally correct (same API on Bun and Workers). The "unlocks streaming SSR" framing in the summary is overst… Bun.Image — in-process image transforms for static assetsAccept. Image optimization is one of next/image's most-loved Import attributes — macros, text, toml, file imports as first-classAccept with scoped policy. Spec 00 promises Bun macros; this RFC redeems that promise. Bun.markdown — built-in MD parser for content pagesAccept. Content pages (blog, docs, marketing) are a recurring Bun.nanoseconds — high-resolution clock for Server-TimingAccept. The response finalizer introduced in spec 19 already bun patch / audit / outdated — project hygiene CLIAccept — encoded as [[cli/20-doctor]]. Pulled forward from post-1.0 to the Bun.randomUUIDv7 — time-ordered request IDs in middlewareAccept. Closes the "where does the request id come from?" gap that spec Bun.secrets — OS keychain-backed dev secretsAccept, scoped tightly to dev. Resolves the "where do my dev secrets live" gap in spec 08. Bun.serve routes — adopt native routes map (Hono removed)Accept — and promote to the primary routing mechanism. Originally rejected because Hono's middleware model would diverge from Bun.serve({ routes }). With the… Bun-native task-output cache + affected detection (monorepo runner)Accept, encoded as framework spec 27 Bun.which — scaffold tool probes (bun + git)Accept. Smallest possible scope: two probes, no new flags, no patties add --path — per-invocation stamp destinationAccept. The only hard-coded convention shadcn users hit immediately. --path Optional `ui` block in patties.config.ts — redirectable stamp pathsAccept — narrowly. patties' "config = convention" stance is a legitimate patties ui init — front-load theming + helper setupAccept — as an optional convenience, not a prerequisite. Today tokens.css + patties migrate (rtl, radix) — codemods for user-authored UI codeAccept, scoped to user-authored code. First-party stamped components already use Remote / URL / namespaced registries + patties ui buildAccept — promoted from backlog. Previously parked as the lowest-priority parity Theming — @theme inline wiring + base-color token presetsAccept the two buildable theming slices; the live editor is split out as deferred patties add --diff / patties update — reconcile copy-in driftAccept — highest-leverage parity work now the catalog is shipped. The copy-in patties add --view / patties view — pre-install source previewAccept — cheap win. --dry-run already shows the file/dep plan; --view adds

RFCS · backlog 7

Bun.deflateSync / Bun.zstdCompress — alternate asset compressionBun.deflateSync (raw deflate / zlib), Bun.zstdCompress (zstd, sync + streaming). Adds alternate algorithms to the build's asset pre-compression step. Note: b… Bun.ArrayBufferSink — streaming buffer builder for SSRBun.ArrayBufferSink lets you accumulate bytes from many writes into a single ArrayBuffer or stream them out, with fewer intermediate allocations than Uint8Ar… --bytecode flag — pre-compile JS to JSC bytecode at buildbun build --bytecode pre-compiles JS to JavaScriptCore bytecode and embeds it in the bundle. Cuts parse time at startup. bun pm — catalogs / workspaces for monoreposMoved deferred → backlog — the named trigger fired. The 2026-05-27 deferral Bun.resolveSync — module resolution outside the build contextBun.resolveSync(specifier, parent) resolves a module specifier to an absolute path using Bun's resolver. Useful outside of Bun.build's native resolution. --smol flag — memory-constrained runtime modebun --smol runs Bun with a smaller initial allocator footprint. Trades throughput for memory headroom. Bun.Transpiler — on-demand single-file TS/TSX transpileBun.Transpiler returns a transpiler instance that runs TS→JS / JSX→JS per file without wrapping into a build graph. Faster than SWC for many workloads; sync …

RFCS · deferred 3

Bun.YAML / Bun.TOML / Bun.JSON5 (and JSONL) — non-TS config formatsConfirmed deferred, with the pickup trigger retargeted to the plugin system: Bun.Cookie signing — HMAC-signed cookies for sessions / authStays deferred — not promoted, not dismissed. The blessed auth story is Bun fullstack HTML imports — evaluate as alternative build pathReject for v1; keep as future-work RFC. The RFC itself frames the right question — "is there any phase 0–4 use case that needs this?" — and answers it correc…

RFCS · out-of-scope 7

Bun.color — color parsing / conversion utilityMoved deferred → out-of-scope. Re-checked against the now-shipped Patties UI Bun.fileURLToPath / Bun.pathToFileURL — file URL ↔ pathMoved backlog → out-of-scope. Identical surface to node:url with no Bun.peek — synchronously introspect a Promise's settled stateMoved backlog → out-of-scope. An internals-only microtask optimization with Bun.sleep / Bun.sleepSync — delay helpersMoved deferred → out-of-scope. There is no realistic future in which Bun.connect / Bun.listen — raw TCPMoved backlog → out-of-scope. Raw TCP sits one rung below where a Bun.udpSocket — UDP socketsMoved backlog → out-of-scope alongside [[rfc-bun-tcp]] (same reasoning — Live theme editor / shareable preset codesMoved deferred → out-of-scope. Re-surveyed the shadcn ecosystem: the visual

Research 5

Bun cliRaw research capture (plain text). Bun globalsRaw research capture (plain text). Bun modulesRaw research capture (plain text). Bun API Coverage Matrix — Patties FrameworkThe catalogue covers every Bun. global, every bun: built-in module, the notable bun CLI verbs/flags, and Bun-specific language features (import attribute typ… shadcn/ui → patties-ui Parity MatrixThis catalogue covers every shadcn CLI command, every add flag, the components.json config keys, the registry/distribution model, the theming surface, and th…