fuz-stack #

Overview
#

Coding conventions and patterns for the @fuzdev TypeScript and Svelte 5 ecosystem. These conventions keep agent-assisted development consistent across ~20 repos — from naming and file organization to error handling, testing, and validation patterns.

This content is AI-generated and mostly poorly reviewed. Not all patterns described here are endorsed, and some may be out of date or incorrect.

The full skill documentation is at skills/fuz-stack.

Conventions
#

Area	Convention
Naming	snake_case functions/variables, PascalCase types/components, SCREAMING_SNAKE_CASE constants
File organization	`src/lib/` for library code, `src/test/` for tests (not co-located), `src/routes/` for SvelteKit
Imports	Import by real source extension (`.ts`/`.svelte.ts`), directly from source (no barrels/re-exports)
Formatting	`tsv` with tabs, 100 char width
Breaking changes	Acceptable — delete unused code, don't shim or alias
Flat namespace	All exported identifiers unique across all modules; the `svelte-docinfo` analysis enforces
Build	`gro check` runs typecheck + test + gen --check + format --check + lint

// snake_case functions — domain-prefix when bare name would be ambiguous
function git_push() {}  // git_* cluster, "push" alone is ambiguous
function truncate() {}  // action-first, self-descriptive

// PascalCase types and components
type PackageJson = {};
// file: DocsLink.svelte

// real source extension in imports (.ts, not the old .js form)
import {git_push} from './git.ts';

Core patterns
#

Beyond surface conventions, several deeper patterns define how @fuzdev code is structured:

Pattern	Convention
Error handling	`Result<TValue, TError>` discriminated union — never throw for expected errors
Dependency injection	Small `*Deps` interfaces for all I/O, plain object mocks — no mocking libraries
Validation	`z.strictObject()` by default, PascalCase schema naming, `.brand()` for nominal types
Testing	Fixture-based testing for parsers — input files, generated `expected.json`, never manually edit

// Result pattern — properties directly on the result object
function parse_config(text: string): Result<{value: Config}, {error: ParseError}> {
	return {ok: true, value: JSON.parse(text)};
}

// Deps pattern — small interfaces, no god types
export interface FsDeps {
	read_file: (path: string) => Promise<string>;
	write_file: (path: string, content: string) => Promise<void>;
}

References
#

22 detailed reference documents:

Reference	Covers
Async Patterns	Concurrency primitives — semaphore, deferred, concurrent map/each
Code Generation	Gro gen system — .gen.* files, dependencies, output formats
Common Utilities	Result type, Logger, Timings, DAG execution
CSS Patterns	fuz_css styling — default-reliance, the styling ladder, variables, extraction
Dependency Injection	Injectable *Deps interfaces, mock factories, composition patterns
Documentation System	Docs pipeline — Tome system, layout architecture, project setup
File Organization	src/ tree, domain subdirectories, full-path imports, test mirroring
mdz — Strict Markdown Dialect	mdz dialect — grammar surface, component registration, rendering seam, autolink, preprocessor
Approved npm Dependencies	Approved external npm package allowlist for TS/Svelte repos
Path References in Documentation	Path typography — navigational vs src/lib module vs code-shaped
Approved Rust Dependencies	Approved external crate allowlist for Rust workspaces
Rust Patterns for the Fuz Ecosystem	Rust lints, errors, DI ladder, idioms, CLI patterns
Rust Performance Patterns	Rust perf — profiling, arenas, locks, hot-path idioms, SIMD
Rust Spine & Consumer Servers	Spine crate map, consumer servers, env, daemon lifecycle
Svelte 5 Patterns	Svelte 5 runes, contexts, snippets, attachments
Task Patterns	Gro task system — .task.ts files, TaskContext, error handling
Testing Patterns	Vitest patterns, fixtures, mocks, assertion helpers
TSDoc Comment Style Guide	TSDoc style guide — tags, conventions, drift detection
Twin Implementations (TS ↔ Rust)	TS ↔ Rust twin implementations — convergence, naming parity, wire crates
Type Utilities	Nominal typing (Flavored/Branded), strict utility types
WASM Patterns for the Fuz Ecosystem	WASM/N-API build targets — wasm-bindgen, component model, JS interop
Zod Schemas	Zod conventions — strictObject, branded types, introspection

Stack
#

fuz_util → gro + fuz_css → fuz_ui → fuz_* apps

gro is the durable web-dev workflow surface — its internals progressively adopt Rust (tsv, then fuz crates) while it stays complementary to fuz and zap. See stack for the full dependency graph and package details.

For cross-repo coordination patterns — planning, TODOs, and multi-repo goals — see grimoire.