Library contract (agents)

Stable reference for AI agents working with @franksauvag/rpg-commons.

Primary rules remain in repository root AGENTS.md.

npm entry points

Import	Content
@franksauvag/rpg-commons	UI components, utilities
@franksauvag/rpg-commons/srd	SRD HTTP clients, types, runtime
@franksauvag/rpg-commons/character	DndCharacter types (C-min)
@franksauvag/rpg-commons/style	Compiled CSS
@franksauvag/rpg-commons/fonts	Font faces

Forbidden in src/

• react-router, @tanstack/react-router, useNavigate
• import.meta.env
• Application lifecycle hooks (useSrdResource, app preloaders)

Do not import

• src/srd/transform/* (internal normalizers/adapters)
• Deep paths bypassing package exports

SRD API choice

1. createSrdRuntime — default
2. createSrdClient — bundles only, lower level
3. createSrdEntryListClient — entry rows only

Publish sequence

1. Merge to rpg-commons main → wait for npm publish + tag
2. Then bump version in consumer apps (character-creator-studio, etc.)

No file:../, long-lived pnpm link, or npm pack for shared merges.

Documentation

• Site: https://libs.heritiersdudonjon.com
• API HTML (full URL so the doc SPA does not capture the link): srd, character
• Pipeline: Documentation pipeline

Backend contract

SRD e2e tests in src/srd/__tests__/*.e2e.test.ts define expected API behavior.