@vttforge/cli 0.0.0 → 0.5.1

package/templates/system-js/templates/actor/character-sheet.hbs

@@ -0,0 +1,168 @@
+{{!--
+  Character sheet — markup mirrors the canonical Figma reference
+  (character-sheet.jsx + Theme Explorations .sh-* classes).
+
+  Tabs nav uses `data-tab`/`data-group` + `data-action="vttforgeTab"` so
+  BaseActorSheet's default tab action routes clicks. `context.tabs.primary`
+  is auto-populated by BaseActorSheet's _prepareContext.
+
+  `<img data-edit="img">` is handled by DocumentSheetV2's built-in editImage
+  action. `<prose-mirror>` is the v13 rich text element for biography.
+--}}
+<form autocomplete="off">
+
+  {{!-- ════════ HEAD (.sh-head) ════════ --}}
+  <div class="sh-head">
+    <img class="sh-portrait" src="{{actor.img}}" alt="{{actor.name}}" data-edit="img" />
+    <div class="sh-id">
+      <div class="sh-id-top">
+        <input class="sh-name" type="text" name="name" value="{{actor.name}}"
+               placeholder="{{localize '{{LOCALE_PREFIX}}.Sheet.NamePlaceholder'}}" />
+        <div class="sh-sub">
+          <span>{{localize "{{LOCALE_PREFIX}}.Sheet.Level"}}</span>
+          <input type="number" name="system.level" value="{{system.level}}" min="1" max="20" />
+        </div>
+      </div>
+      <div class="sh-quick">
+        <div class="q">
+          <div class="qv">
+            <input type="number" name="system.health.value" value="{{system.health.value}}" min="0" />
+            <span class="qv-sep">/</span>
+            <span class="qv-max">{{system.health.max}}</span>
+          </div>
+          <div class="qk">{{localize "{{LOCALE_PREFIX}}.Sheet.Quick.HP"}}</div>
+        </div>
+        <div class="q">
+          <div class="qv">{{system.armorClass}}</div>
+          <div class="qk">{{localize "{{LOCALE_PREFIX}}.Sheet.Quick.AC"}}</div>
+        </div>
+        <div class="q">
+          <div class="qv">
+            <input type="number" name="system.speed" value="{{system.speed}}" min="0" />
+          </div>
+          <div class="qk">{{localize "{{LOCALE_PREFIX}}.Sheet.Quick.SPD"}}</div>
+        </div>
+        <div class="q">
+          <div class="qv">{{numberFormat system.initiative sign=true}}</div>
+          <div class="qk">{{localize "{{LOCALE_PREFIX}}.Sheet.Quick.INIT"}}</div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  {{!-- ════════ TABS (.sh-tabs) ════════ --}}
+  <nav class="sh-tabs" data-group="primary">
+    {{#each tabs as |tab|}}
+      <button type="button" class="sh-tab {{#if tab.active}}on{{/if}}"
+              data-tab="{{tab.id}}"
+              data-group="primary"
+              data-action="vttforgeTab"
+              title="{{localize tab.label}}">
+        {{#if tab.icon}}<i class="{{tab.icon}}"></i>{{/if}}
+        <span>{{localize tab.label}}</span>
+      </button>
+    {{/each}}
+  </nav>
+
+  {{!-- ════════ BODY (.sh-body) ════════ --}}
+  <section class="sh-body">
+
+    {{!-- ABILITIES --}}
+    <section class="tab abilities {{tabs.abilities.cssClass}}"
+             data-tab="abilities" data-group="primary">
+      <h3 class="sh-section-title">{{localize "{{LOCALE_PREFIX}}.Sheet.AbilityScores"}}</h3>
+      <div class="sh-abilities">
+        {{#each abilities as |ability|}}
+          <div class="sh-abil">
+            <div class="lbl" title="{{ability.label}}">{{ability.key}}</div>
+            <input class="val" type="number"
+                   name="system.abilities.{{ability.key}}"
+                   value="{{ability.value}}" min="1" max="30" />
+            <button type="button" class="mod sh-abil-roll"
+                    data-action="rollAbility" data-ability="{{ability.key}}"
+                    title="{{localize '{{LOCALE_PREFIX}}.Sheet.Roll.label'}}">
+              {{numberFormat ability.mod sign=true}}
+            </button>
+          </div>
+        {{/each}}
+      </div>
+    </section>
+
+    {{!-- INVENTORY --}}
+    <section class="tab inventory {{tabs.inventory.cssClass}}"
+             data-tab="inventory" data-group="primary">
+      <header class="sh-section-head">
+        <h3 class="sh-section-title">{{localize "{{LOCALE_PREFIX}}.Sheet.Inventory"}}</h3>
+        <button type="button" class="sh-action" data-action="createGear"
+                title="{{localize '{{LOCALE_PREFIX}}.Sheet.NewGear'}}">
+          <i class="fa-solid fa-plus"></i>
+          <span>{{localize "{{LOCALE_PREFIX}}.Sheet.NewGear"}}</span>
+        </button>
+      </header>
+      <div class="sh-items">
+        {{#each gear as |item|}}
+          <div class="sh-item" data-item-id="{{item.id}}" draggable="true">
+            <div class="sh-item-ico">
+              {{#if item.img}}
+                <img src="{{item.img}}" alt="{{item.name}}" />
+              {{else}}
+                <i class="fa-solid fa-box"></i>
+              {{/if}}
+            </div>
+            <div>
+              <div class="sh-item-name">{{item.name}}</div>
+              <div class="sh-item-meta">{{numberFormat item.weight}} lb</div>
+            </div>
+            <span class="sh-tag {{#if (eq item.kind "stowed")}}muted{{/if}}">
+              {{localize (concat "{{LOCALE_PREFIX}}.Gear.Kind." item.kind)}}
+            </span>
+            <span class="sh-qty">×{{item.quantity}}</span>
+            <button type="button" class="sh-item-delete" data-action="deleteItem"
+                    title="{{localize '{{LOCALE_PREFIX}}.Sheet.Delete'}}">
+              <i class="fa-solid fa-trash"></i>
+            </button>
+          </div>
+        {{else}}
+          <div class="sh-items-empty">{{localize "{{LOCALE_PREFIX}}.Sheet.NoGear"}}</div>
+        {{/each}}
+      </div>
+
+      <div class="sh-drop">
+        <div class="lbl">{{localize "{{LOCALE_PREFIX}}.Sheet.Drop.label"}}</div>
+        <div class="sub">onDropItem(item, event)</div>
+      </div>
+    </section>
+
+    {{!-- SPELLS (placeholder) --}}
+    <section class="tab spells {{tabs.spells.cssClass}}"
+             data-tab="spells" data-group="primary">
+      <h3 class="sh-section-title">{{localize "{{LOCALE_PREFIX}}.Sheet.Spells"}}</h3>
+      <div class="sh-empty">{{localize "{{LOCALE_PREFIX}}.Sheet.SpellsEmpty"}}</div>
+    </section>
+
+    {{!-- BIOGRAPHY --}}
+    <section class="tab biography {{tabs.biography.cssClass}}"
+             data-tab="biography" data-group="primary">
+      <h3 class="sh-section-title">{{localize "{{LOCALE_PREFIX}}.Sheet.Biography"}}</h3>
+      {{#if isEditable}}
+        <prose-mirror name="system.biography"
+                      button="true"
+                      editable="{{isEditable}}"
+                      toggled="false"
+                      value="{{system.biography}}">
+          {{{enrichedBiography}}}
+        </prose-mirror>
+      {{else}}
+        <div class="sh-biography-readonly">{{{enrichedBiography}}}</div>
+      {{/if}}
+    </section>
+
+  </section>
+
+  {{!-- ════════ FOOT (.sh-foot) ════════ --}}
+  <footer class="sh-foot">
+    <span class="nm">VTTFORGE · FORGE</span>
+    <span>@vttforge/styles · v0.2</span>
+  </footer>
+
+</form>

package/templates/system-js/templates/item/gear-sheet.hbs

@@ -0,0 +1,54 @@
+{{!-- Gear sheet — minimal demo of BaseItemSheet on ItemSheetV2. --}}
+<form autocomplete="off">
+
+  <header class="sheet-header">
+    <img class="portrait" src="{{item.img}}" alt="{{item.name}}" data-edit="img" />
+    <input type="text" name="name" value="{{item.name}}"
+           placeholder="{{localize '{{LOCALE_PREFIX}}.Sheet.NamePlaceholder'}}" />
+  </header>
+
+  <nav class="sheet-tabs" data-group="primary">
+    {{#each tabs as |tab|}}
+      <button type="button" class="item {{tab.cssClass}}"
+              data-tab="{{tab.id}}"
+              data-group="primary"
+              data-action="vttforgeTab"
+              title="{{localize tab.label}}">
+        {{#if tab.icon}}<i class="{{tab.icon}}"></i>{{/if}}
+        <span>{{localize tab.label}}</span>
+      </button>
+    {{/each}}
+  </nav>
+
+  <section class="sheet-body">
+    {{!-- DETAILS --}}
+    <section class="tab details {{tabs.details.cssClass}}"
+             data-tab="details" data-group="primary">
+      <div class="field">
+        <label>{{localize "{{LOCALE_PREFIX}}.Gear.Quantity"}}</label>
+        <input type="number" name="system.quantity" value="{{system.quantity}}" min="0" />
+      </div>
+      <div class="field">
+        <label>{{localize "{{LOCALE_PREFIX}}.Gear.Weight"}}</label>
+        <input type="number" name="system.weight" value="{{system.weight}}" min="0" step="0.1" />
+      </div>
+    </section>
+
+    {{!-- DESCRIPTION --}}
+    <section class="tab description {{tabs.description.cssClass}}"
+             data-tab="description" data-group="primary">
+      {{#if isEditable}}
+        <prose-mirror name="system.description"
+                      button="true"
+                      editable="{{isEditable}}"
+                      toggled="false"
+                      value="{{system.description}}">
+          {{{enrichedDescription}}}
+        </prose-mirror>
+      {{else}}
+        <div class="description-readonly">{{{enrichedDescription}}}</div>
+      {{/if}}
+    </section>
+  </section>
+
+</form>

package/templates/system-js/vite.config.mjs

@@ -0,0 +1,16 @@
+import vttforge from '@vttforge/vite-plugin';
+import { defineConfig } from 'vite';
+
+/**
+ * Vite config for {{TITLE}}.
+ *
+ * `@vttforge/vite-plugin` owns the build contract — it bundles
+ * `scripts/main.mjs` into `dist/main.mjs` (no hash, no bare specifiers),
+ * resolves `@import "@vttforge/styles"` at build time, copies the manifest +
+ * `lang/` + `templates/` to `dist/`, and syncs the manifest version from
+ * `package.json` on every build. The result under `dist/` is the deployable
+ * artefact you symlink into Foundry's `Data/systems/{{ID}}/`.
+ */
+export default defineConfig({
+  plugins: [vttforge({ id: '{{ID}}' })],
+});

package/templates/system-ts/.github/workflows/release.yml

@@ -0,0 +1,92 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve version from tag
+        id: version
+        env:
+          REF: ${{ github.ref_name }}
+        run: |
+          version="${REF#v}"
+          # Git allows surprising characters in tag names. Reject anything
+          # that isn't a strict semver-ish identifier so downstream node -e
+          # / shell interpolations can't be turned into command injection
+          # by a malicious tag push.
+          if ! [[ "$version" =~ ^[0-9A-Za-z._+-]+$ ]]; then
+            echo "Refusing tag with unsafe characters: $version" >&2
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: pnpm install
+
+      - name: Sync manifest version
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          node -e "const fs=require('node:fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));p.version=process.env.VERSION;fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\n');"
+
+      # We invoke vite directly (not `pnpm build` → `vttforge build`) because
+      # the release workflow needs to:
+      #   1. Run vite build → emit dist/system.json
+      #   2. Patch manifest/download URLs into dist/system.json
+      #   3. Zip dist/ → release artifact (so the zipped manifest carries URLs)
+      # `vttforge build` zips at step 1, which would freeze the un-patched
+      # manifest. Eventually the vite-plugin will support env-driven URL
+      # injection and this dance disappears.
+      - run: pnpm exec vite build
+
+      - name: Inject release URLs into manifest
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          REPO: ${{ github.repository }}
+          PKG_ID: '{{ID}}'
+        run: |
+          node -e "const fs=require('node:fs');const path='dist/system.json';const m=JSON.parse(fs.readFileSync(path,'utf8'));const r=process.env.REPO;const v=process.env.VERSION;const id=process.env.PKG_ID;m.manifest=\`https://github.com/\${r}/releases/latest/download/system.json\`;m.download=\`https://github.com/\${r}/releases/download/v\${v}/\${id}-\${v}.zip\`;fs.writeFileSync(path,JSON.stringify(m,null,2)+'\n');"
+
+      - name: Build release zip
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          PKG_ID: '{{ID}}'
+        run: |
+          cd dist
+          zip -r "../${PKG_ID}-${VERSION}.zip" .
+
+      - name: Create GitHub Release
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          PKG_ID: '{{ID}}'
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            ${{ env.PKG_ID }}-${{ env.VERSION }}.zip
+            dist/system.json
+          generate_release_notes: true
+          body: |
+            ## Foundry installation
+
+            Install via Foundry's setup wizard with this manifest URL:
+
+            ```
+            https://github.com/${{ github.repository }}/releases/latest/download/system.json
+            ```

package/templates/system-ts/README.md

@@ -0,0 +1,57 @@
+# {{TITLE}}
+
+{{DESCRIPTION}}
+
+Built on [VTTForge](https://github.com/vttforge/vttforge) — typed data models, declarative sheet boilerplate, migration runner, error catalogue, and a Vite-based build pipeline.
+
+> **Note** — VTTForge is currently in pre-release and not yet published to npm. The dependencies in `package.json` (`@vttforge/core`, `@vttforge/styles`, `@vttforge/vite-plugin`) will resolve once VTTForge ships its first public release. Until then, work from a local checkout: `pnpm link --global` from each VTTForge package, then `pnpm link --global @vttforge/core @vttforge/styles @vttforge/vite-plugin` here.
+
+## Quick start
+
+```bash
+pnpm install
+pnpm dev      # vite build --watch + auto-symlinks dist/ into Foundry's Data
+pnpm build    # one-shot build + emits {{ID}}-<version>.zip for foundryvtt.com
+```
+
+`pnpm dev` (`vttforge dev` under the hood) auto-detects your Foundry user-data
+directory on the first run, prompts you to confirm it, and saves the choice to
+`.vttforge/config.json` for next time. Override with `--data-dir <path>` or set
+`FOUNDRY_DATA_DIR` in your environment.
+
+Run Foundry with `--hotReload` so saved files reload the world without a page
+refresh — `dev` watches `dist/` for changes, and Foundry's built-in dispatcher
+swaps CSS / Handlebars / JSON on the fly.
+
+Then launch Foundry, create a world that uses **{{TITLE}}**, and open a character — the sheet is the `CharacterSheet` shipped in `scripts/sheets/`.
+
+## What's inside
+
+| Path | Purpose |
+|---|---|
+| `system.json` | Manifest (id, compatibility, document types, manifest-side sanitization paths) |
+| `template.json` | Foundry document type declarations (Actor + Item subtypes) |
+| `scripts/main.ts` | Entry point — one call to `registerSystem` from `@vttforge/core` |
+| `scripts/data/*.ts` | Typed data models (`BaseTypeDataModel()` from `@vttforge/core`) |
+| `scripts/sheets/*.ts` | Sheet boilerplate eliminators (`BaseActorSheet()` / `BaseItemSheet()`) |
+| `scripts/migrations.ts` | `createMigrationRunner()` — versioned data migrations |
+| `templates/` | Handlebars templates for sheets |
+| `styles/main.css` | Stylesheet — imports `@vttforge/styles` as the design system base |
+| `lang/en.json` | Localization strings |
+
+## Releasing to Foundry
+
+Tag-push triggers `.github/workflows/release.yml`, which builds the system, zips `dist/`, and attaches both `{{ID}}-<version>.zip` and `dist/system.json` to a GitHub Release.
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+Foundry installs from the `system.json` URL on the Release — point users at the `latest/download/system.json` URL in the release notes so they auto-update on every tag.
+
+For foundryvtt.com submissions, submit the same manifest URL pattern.
+
+## License
+
+{{LICENSE}} © {{YEAR}} {{AUTHOR}}

package/templates/system-ts/_gitignore

@@ -0,0 +1,12 @@
+node_modules
+dist
+.turbo
+.vscode
+.DS_Store
+*.log
+
+# vttforge dev — saved Foundry data-dir path
+.vttforge/
+
+# vttforge build — release artifact
+*.zip

package/templates/system-ts/lang/en.json

@@ -0,0 +1,55 @@
+{
+  "TYPES.Actor.character": "Character",
+  "TYPES.Item.gear": "Gear",
+
+  "{{LOCALE_PREFIX}}.System.title": "{{TITLE}}",
+  "{{LOCALE_PREFIX}}.System.description": "{{DESCRIPTION}}",
+
+  "{{LOCALE_PREFIX}}.Sheet.Character.title": "Character",
+  "{{LOCALE_PREFIX}}.Sheet.Gear.title": "Gear",
+  "{{LOCALE_PREFIX}}.Sheet.NamePlaceholder": "Name…",
+  "{{LOCALE_PREFIX}}.Sheet.Level": "LV",
+  "{{LOCALE_PREFIX}}.Sheet.AbilityScores": "Ability scores",
+  "{{LOCALE_PREFIX}}.Sheet.Inventory": "Inventory",
+  "{{LOCALE_PREFIX}}.Sheet.Biography": "Biography",
+  "{{LOCALE_PREFIX}}.Sheet.NewGear": "New gear",
+  "{{LOCALE_PREFIX}}.Sheet.NewGearName": "New Gear",
+  "{{LOCALE_PREFIX}}.Sheet.NoGear": "No gear yet — drag items here or click New gear.",
+  "{{LOCALE_PREFIX}}.Sheet.Delete": "Delete",
+
+  "{{LOCALE_PREFIX}}.Sheet.Quick.HP": "HP",
+  "{{LOCALE_PREFIX}}.Sheet.Quick.AC": "AC",
+  "{{LOCALE_PREFIX}}.Sheet.Quick.SPD": "SPD",
+  "{{LOCALE_PREFIX}}.Sheet.Quick.INIT": "INIT",
+
+  "{{LOCALE_PREFIX}}.Sheet.Tabs.abilities": "Abilities",
+  "{{LOCALE_PREFIX}}.Sheet.Tabs.inventory": "Inventory",
+  "{{LOCALE_PREFIX}}.Sheet.Tabs.spells": "Spells",
+  "{{LOCALE_PREFIX}}.Sheet.Tabs.biography": "Biography",
+  "{{LOCALE_PREFIX}}.Sheet.Tabs.details": "Details",
+  "{{LOCALE_PREFIX}}.Sheet.Tabs.description": "Description",
+  "{{LOCALE_PREFIX}}.Sheet.Spells": "Spells",
+  "{{LOCALE_PREFIX}}.Sheet.SpellsEmpty": "Spells slot reserved for a follow-up release.",
+
+  "{{LOCALE_PREFIX}}.Sheet.Roll.label": "Roll",
+  "{{LOCALE_PREFIX}}.Sheet.Roll.flavor": "{ability} check",
+  "{{LOCALE_PREFIX}}.Sheet.Drop.label": "Drop item to add",
+  "{{LOCALE_PREFIX}}.Sheet.Drop.rejected": "Cannot drop {type} items here — only gear is accepted.",
+
+  "{{LOCALE_PREFIX}}.Ability.str": "Strength",
+  "{{LOCALE_PREFIX}}.Ability.dex": "Dexterity",
+  "{{LOCALE_PREFIX}}.Ability.con": "Constitution",
+  "{{LOCALE_PREFIX}}.Ability.int": "Intelligence",
+  "{{LOCALE_PREFIX}}.Ability.wis": "Wisdom",
+  "{{LOCALE_PREFIX}}.Ability.cha": "Charisma",
+
+  "{{LOCALE_PREFIX}}.Gear.Quantity": "Quantity",
+  "{{LOCALE_PREFIX}}.Gear.Weight": "Weight (lb)",
+  "{{LOCALE_PREFIX}}.Gear.Kind": "Kind",
+  "{{LOCALE_PREFIX}}.Gear.Kind.equipped": "equipped",
+  "{{LOCALE_PREFIX}}.Gear.Kind.valued": "valued",
+  "{{LOCALE_PREFIX}}.Gear.Kind.stowed": "stowed",
+
+  "{{LOCALE_PREFIX}}.Settings.showTutorial.name": "Show tutorial",
+  "{{LOCALE_PREFIX}}.Settings.showTutorial.hint": "Display the welcome banner on world load."
+}

package/templates/system-ts/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "{{ID}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{DESCRIPTION}}",
+  "type": "module",
+  "license": "{{LICENSE}}",
+  "author": "{{AUTHOR}}",
+  "scripts": {
+    "build": "vttforge build",
+    "dev": "vttforge dev",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@vttforge/core": "^0.10.0",
+    "@vttforge/styles": "^0.3.0"
+  },
+  "devDependencies": {
+    "@vttforge/cli": "^0.5.0",
+    "@vttforge/vite-plugin": "^0.4.0",
+    "typescript": "^5.4.0",
+    "vite": "^8.2.2"
+  },
+  "engines": {
+    "node": ">=26"
+  }
+}

package/templates/system-ts/scripts/data/character-data.ts

@@ -0,0 +1,81 @@
+/**
+ * CharacterData — typed schema for the `character` Actor type.
+ *
+ * Quick stats are HP / AC / SPD / INIT, abilities are the six classic
+ * scores (str/dex/con/int/wis/cha). Derived state (modifiers, max HP,
+ * armor class, initiative) is computed in-memory in `prepareDerivedData`.
+ *
+ * `prepareBaseData` initialises fields that Active Effects need to mutate
+ * (base max HP before any AE bonus); `prepareDerivedData` then computes
+ * the AE-aware values (modifiers, percentages, totals). Never write to the
+ * database in either hook — they're purely in-memory derivations.
+ */
+import { BaseTypeDataModel, fields } from '@vttforge/core';
+
+export class CharacterData extends BaseTypeDataModel() {
+  static defineSchema() {
+    const f = fields();
+    // The six ability scores are written once, as a factory rather than a
+    // shared options object: a field keeps the options it was handed, and
+    // some field classes write back into them.
+    const score = () =>
+      new f.NumberField({
+        required: true,
+        nullable: false,
+        integer: true,
+        min: 1,
+        max: 30,
+        initial: 10,
+      });
+    return {
+      level: new f.NumberField({
+        required: true,
+        nullable: false,
+        integer: true,
+        min: 1,
+        max: 20,
+        initial: 1,
+      }),
+      speed: new f.NumberField({
+        required: true,
+        nullable: false,
+        integer: true,
+        min: 0,
+        initial: 30,
+      }),
+      abilities: new f.SchemaField({
+        str: score(),
+        dex: score(),
+        con: score(),
+        int: score(),
+        wis: score(),
+        cha: score(),
+      }),
+      health: new f.SchemaField({
+        value: new f.NumberField({ required: true, nullable: false, integer: true, min: 0, initial: 10 }),
+        max: new f.NumberField({ required: true, nullable: false, integer: true, min: 0, initial: 10 }),
+      }),
+      power: new f.SchemaField({
+        value: new f.NumberField({ required: true, nullable: false, integer: true, min: 0, initial: 5 }),
+        max: new f.NumberField({ required: true, nullable: false, integer: true, min: 0, initial: 5 }),
+      }),
+      biography: new f.HTMLField(),
+    };
+  }
+
+  prepareDerivedData() {
+    // biome-ignore lint/suspicious/noExplicitAny: schema-driven types ship in a later @vttforge/types release
+    const self = this as any;
+    for (const [key, value] of Object.entries(self.abilities)) {
+      const score = typeof value === 'number' ? value : ((value as { value?: number })?.value ?? 10);
+      const mod = Math.floor((score - 10) / 2);
+      self.abilities[key] = { value: score, mod };
+    }
+
+    const conMod = self.abilities.con.mod;
+    self.health.max = 10 + self.level + conMod;
+
+    self.armorClass = 10 + self.abilities.dex.mod;
+    self.initiative = self.abilities.dex.mod;
+  }
+}

package/templates/system-ts/scripts/data/gear-data.ts

@@ -0,0 +1,37 @@
+/**
+ * GearData — typed schema for the `gear` Item type.
+ *
+ * `kind` is an enum that drives the inventory pill on the character sheet:
+ * `equipped` and `valued` render with the accent pill, `stowed` renders
+ * muted.
+ */
+import { BaseTypeDataModel, fields } from '@vttforge/core';
+
+const GEAR_KINDS = ['equipped', 'valued', 'stowed'] as const;
+
+export class GearData extends BaseTypeDataModel() {
+  static defineSchema() {
+    const f = fields();
+    return {
+      quantity: new f.NumberField({
+        required: true,
+        nullable: false,
+        integer: true,
+        min: 0,
+        initial: 1,
+      }),
+      weight: new f.NumberField({
+        required: true,
+        nullable: false,
+        min: 0,
+        initial: 0,
+      }),
+      kind: new f.StringField({
+        required: true,
+        choices: GEAR_KINDS as unknown as string[],
+        initial: 'stowed',
+      }),
+      description: new f.HTMLField(),
+    };
+  }
+}

package/templates/system-ts/scripts/foundry-globals.ts

@@ -0,0 +1,33 @@
+/**
+ * Minimal Foundry runtime globals.
+ *
+ * These declarations let the scaffold compile cleanly without an external
+ * type package. Replace with `fvtt-types` (community-maintained, pinned to
+ * a known-working commit SHA) or `@vttforge/types` (coming in a later
+ * VTTForge release) for full type coverage:
+ *
+ *   pnpm add -D 'github:League-of-Foundry-Developers/foundry-vtt-types#main'
+ *
+ * Then declare `types: ["fvtt-types"]` in `tsconfig.json` and delete this
+ * file.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+declare global {
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const game: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const CONFIG: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const Hooks: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const ui: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const ChatMessage: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const Roll: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const foundry: any;
+}
+
+export {};