Character Sheet Renderer — how a module ships a sheet

How to ship a sheet

The shape. Your module ships a React component; the platform ships the frame it sits in — the header with the Build-mode toggle (gated by the character's access level, as the quick view's is), History, the ⋯ menu with zoom and Export PDF, and the scroller — plus the data, the one write path, the field registry, the recent-changes feed, and your own pickers when the sheet asks for one. You draw the whole sheet; you write only through api.edit, so validation, history commits, permissions and the token fan-out stay the platform's whoever drew the field.

1. Register it from the client entry (Module API 1.39.0)

// src/client/index.ts — React, so the client entry; the server entry stays Node-renderable.
import { moduleRegistry } from '@purple-cat/shared';
import { MySheet } from './MySheet';

moduleRegistry.registerCharacterSheetRenderer({
  systemId: 'my-system',
  component: MySheet,                                   // React.ComponentType<SheetRendererProps>
  pages: [{ id: 'character', label: 'Character' }, { id: 'spells', label: 'Spells' }],
  supports: { print: true },
});

and on the server side, in your SystemModule, hasSheetRenderer: true, so the platform (and the module-version pins) can tell a module that draws its own sheet from one that takes the platform's without loading the client entry. The registration is validated at load: a page with no id throws there rather than at the first render. A module that registers none keeps the platform's sheet — the quick view — exactly as before.

2. What you are handed: SheetRendererProps

3. What you call: SheetApi

Your own fields (1.40.0, N5.4, NS-D7): declare what you keep under metadata.<systemId>.* — or under the metadataNamespace your sheet schema names, when one package serves several systems (5e's two editions share dnd5e) — in your sheetSchema.metadataFields — { path: 'alignment', label: 'Alignment', kind: 'text', section: 'Identity', importHint: 'the alignment, e.g. Chaotic Good' }. The write path type-checks a set-metadata intent against a declared field (an undeclared path is still yours to write: declaring earns the label and the check, it does not permit the write), the History panel files a change to it under your section with your label, and the importer asks the model for every field with an importHint and lands the answer under your namespace.

Intents (SheetEditIntent): the Character Sheet API's four — set-attribute-component, add-trait, remove-trait, adjust-ability — plus set-field (a simple platform field: name, level, notes, classes…), set-runtime (attribute:<name> → the attribute's current value), set-metadata (<systemId>.path.to.value, or <metadataNamespace>.… — your own namespace of the record, NS-D7: the boxes your system has no platform field for live here, declared in your sheet schema so validation, history diffs and the import know them), and patch (an explicit Partial<Character>, the escape hatch). An intent the platform cannot read is refused before the write path.

4. Build it from the kit

@purple-cat/sheet-kit — its README (packages/sheet-kit/README.md in the platform repository) lists every export. Two families: layout (Sheet, Page, Region, Field, Checkbox, Lines, Portrait) and editing (EditableField, FieldEditor, NumericStepper, Rollable, ActionButton, ValidationMark, RestButton, ResourcePips). Colours come from skin (the platform's --vtt-* tokens per skin), bands from zBand; a sheet that uses only the kit cannot break a skin, a z band or the write path (NS-D1).

Geometry from your PDF. A fillable PDF is a layout file. Read its fields into a layout.json — { name, page, x, y, w, h } per field, y from the top — and derive a PageLayout per page (pageLayoutFromFields, or your own grouping of fields into the regions your sheet actually draws, which keeps the grid coarse enough to reflow). Page turns it into a CSS grid whose tracks are the form's bands: at the design width (612 px, the page at 1 px/pt) a region sits exactly where the printed box does, and below the module's reflowBelow the grid reflows to one column in reading order (NS-D5). The layout is the form's; the chrome is yours (NS-D3).

The field editor contract. FieldEditor opens on focus of the field it wraps, closes on blur (focus leaving both the field and the popover) or Escape, traps focus while open, and returns focus to the field. In view and print it does not open. Ability scores are the canonical case: the popover shows at creation (read-only — generation set and froze it, NS-D10), the step component (asi / proficiency) on a stepper, other, and the final value; Regenerate is the only way back to base.

Stable ids and order. Give every field an id (dnd5e.abilities.str) and an order that is the form's reading order. The host keeps the registry, moves Tab / Shift-Tab between fields by order, and can focus a field on request — what the creation walkthrough (v0.108.0) will drive.

5. Modes and print

Read mode (or the kit's useSheetMode()): the kit's controls are inert outside build except the things a player does at the table — rollables, action buttons, rests, pips, and a NumericStepper marked always. In print the kit hides the tabs and every data-sheet-control, Sheet's media rules snap each Page to a sheet of paper and keep regions whole, and the host's stylesheet hides the app around the sheet. Export PDF on the ⋯ menu is the browser's print path; declare supports: { print: false } to disable it.

6. The fixture is the smallest complete example

@purple-cat/sheet-kit/fixture — FixtureSheet for the fixture-system: two pages, ten regions from a layout.json, every feature above once, and FixtureSheet.test.tsx running it end to end against a recording API. Read it before writing yours.

7. Where the sheet appears

The Sheet left-sidebar context ('sheet', the standard sidebar → floating-window logic), the route /characters/:id/sheet, and three entries: the character page's ⋯ → Sheet view, the Character context's header icon, and the token menu's View Character Sheet on /play.

8. The 5e sheet, read as a worked example (v0.106.0)

dnd5e is the first module to ship a renderer, and its files are worth reading in this order (modules/dnd5e/ in this repository):

Two traps it hit, which your sheet will hit too.

A form field is not the printed box. A region's rectangle derived from the PDF's fields is only as big as the fields; on the 5e sheet the skill and save NAMES are printed artwork, so those boxes came out 40pt wide and the first playtest showed a column of bare numbers with every name clipped. Where the printed box is bigger than what is inside it, say so (WIDEN_TO, SPREAD) and guard it.

A skin can undo your type. The sheet's labels fit their boxes at 6.5px — until the Retro skin's own rule widened their letter-spacing and pushed "INITIATIVE" out of its shield. A label that must fit a printed box is worth measuring in each skin you ship for (el.scrollWidth > el.clientWidth, and a one-word label whose box is two lines tall). --sk-region-padding is the other half of that budget.

The phase-3 automation re-read (NS.4)

Character sheet automation put the sheet's automation (damage helpers, rests, resource spends, derived actions) in the platform, called by the platform's sheet. Behind the API the direction is the same and the caller changes: the module's sheet calls api.damage, api.runAction, api.edit for a rest or a spend, and the platform's helpers do what they did — the module never re-implements a rule the platform already carries, and the platform never learns a system's vocabulary to call it.

The inventory: system-specific code still in apps/web (NS.1)

Where the platform still names a system, what the branch does, and where it goes when a module owns the sheet. Measured against the systemLiterals guard's baseline at v0.105.0 (13 apps/web files) plus the branches its regex does not catch (startsWith('dnd5e'), isSystem8, system5). Files marked dead are deleted by NS.7 of this release; the rest are the round-2 backlog, each with the module (or platform seam) that replaces it.

Not in apps/web but in the same round: packages/ui-components's CharacterSheet.tsx (28), FeatsList (10), AddFeatModal (8), SpellsList (8) and six more — the pre-overhaul sheet components nothing on the current sheet uses — and packages/shared's feats.service.ts (10) and dataTableApi.ts (4). They are the same sunset as PlayModeView a package over, and are judged the same way when the ui-components package is next opened; they are outside this release's scope because nothing here reads them.

The guard's baseline ratchets down with NS.7 (PlayModeView 3 → 0, CharacterDetail 4 → 0) and may never go up: a new system name in apps/web fails the build.