Initial Commit
This commit is contained in:
@@ -0,0 +1,180 @@
|
||||
# OpenSpec Change: enterprise-gaming-character-vehicle-picker
|
||||
|
||||
- **Change ID**: enterprise-gaming-character-vehicle-picker
|
||||
- **Package**: `@suaveplan/character-vehicle-picker`
|
||||
- **Category**: gaming/rigs
|
||||
- **Target path**: `gaming/rigs/character-vehicle-picker`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/character-vehicle-picker.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/character-vehicle-picker` on the genesis branch from scratch at enterprise quality. The package provides character/vehicle picker schemas, catalogs, and state management with BitPacker compression. A `CharacterCatalog` and `VehicleCatalog` hold typed descriptors; a `PickerState` tracks the active character/vehicle selection with undo/redo history; `BitPacker` from `@suaveplan/game-state-schemas` compresses selection state for network transmission. Genesis adds Zod schemas for all catalog entries, structured errors, OTel picker-event counter, and 100% coverage.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis yet — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `PickerError`; `PICKER.*` codes |
|
||||
| `@suaveplan/types` (`workspace:^`) | Shared primitives |
|
||||
| `@suaveplan/events` (`workspace:^`) | `picker:select`, `picker:confirm` events |
|
||||
| `@suaveplan/game-state-schemas` (`workspace:^`) | `BitPacker` for selection compression |
|
||||
| `zod` (`catalog:forms`) | Catalog entry schemas |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Selection event counter |
|
||||
|
||||
---
|
||||
|
||||
## Public API surface
|
||||
|
||||
```ts
|
||||
// Catalog entry types
|
||||
interface CharacterEntry {
|
||||
id: string
|
||||
displayName: string
|
||||
thumbnailUrl?: string
|
||||
tags: string[]
|
||||
unlocked: boolean
|
||||
customization?: CharacterCustomization
|
||||
}
|
||||
|
||||
interface VehicleEntry {
|
||||
id: string
|
||||
displayName: string
|
||||
type: 'car' | 'bike' | 'boat' | 'aircraft' | 'custom'
|
||||
thumbnailUrl?: string
|
||||
tags: string[]
|
||||
unlocked: boolean
|
||||
customization?: VehicleCustomization
|
||||
}
|
||||
|
||||
// Catalogs
|
||||
function createCharacterCatalog(entries: CharacterEntry[]): CharacterCatalog
|
||||
function createVehicleCatalog(entries: VehicleEntry[]): VehicleCatalog
|
||||
|
||||
interface CharacterCatalog {
|
||||
getById(id: string): CharacterEntry | undefined
|
||||
list(filter?: CatalogFilter): CharacterEntry[]
|
||||
unlock(id: string): void
|
||||
lock(id: string): void
|
||||
}
|
||||
|
||||
interface VehicleCatalog {
|
||||
getById(id: string): VehicleEntry | undefined
|
||||
list(filter?: CatalogFilter): VehicleEntry[]
|
||||
unlock(id: string): void
|
||||
lock(id: string): void
|
||||
}
|
||||
|
||||
interface CatalogFilter {
|
||||
tags?: string[]
|
||||
unlockedOnly?: boolean
|
||||
type?: string
|
||||
}
|
||||
|
||||
// Picker state manager
|
||||
function createPickerState(options: PickerStateOptions): PickerState
|
||||
|
||||
interface PickerStateOptions {
|
||||
characterCatalog: CharacterCatalog
|
||||
vehicleCatalog: VehicleCatalog
|
||||
maxHistory?: number
|
||||
}
|
||||
|
||||
interface PickerState {
|
||||
selectCharacter(id: string): void
|
||||
selectVehicle(id: string): void
|
||||
confirm(): PickerSelection
|
||||
undo(): void
|
||||
redo(): void
|
||||
readonly current: PickerSelection
|
||||
readonly canUndo: boolean
|
||||
readonly canRedo: boolean
|
||||
}
|
||||
|
||||
interface PickerSelection {
|
||||
characterId: string | null
|
||||
vehicleId: string | null
|
||||
confirmedAt?: number
|
||||
}
|
||||
|
||||
// Compressed state
|
||||
function encodePickerSelection(selection: PickerSelection, schema: StateSchema<PickerSelection>): Uint8Array
|
||||
function decodePickerSelection(buffer: Uint8Array, schema: StateSchema<PickerSelection>): PickerSelection
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
type PickerErrorCode =
|
||||
| 'PICKER_ENTRY_NOT_FOUND'
|
||||
| 'PICKER_ENTRY_LOCKED'
|
||||
| 'PICKER_CATALOG_EMPTY'
|
||||
| 'PICKER_NO_SELECTION'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **Undo/redo history** — configurable history depth with pointer-based redo.
|
||||
2. **Locked-entry guard** — selecting a locked entry throws `PICKER_ENTRY_LOCKED`.
|
||||
3. **Compressed wire format** — `encodePickerSelection` uses `game-state-schemas` BitPacker for minimal payload.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
gaming/rigs/character-vehicle-picker/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
error-codes.ts
|
||||
constants/index.ts
|
||||
types/common.ts
|
||||
types/common.md
|
||||
core/
|
||||
character-catalog/
|
||||
character-catalog.ts
|
||||
character-catalog.md
|
||||
character-catalog.types.ts
|
||||
character-catalog.test.ts
|
||||
index.ts
|
||||
vehicle-catalog/
|
||||
vehicle-catalog.ts
|
||||
vehicle-catalog.md
|
||||
vehicle-catalog.types.ts
|
||||
vehicle-catalog.test.ts
|
||||
index.ts
|
||||
picker-state/
|
||||
picker-state.ts
|
||||
picker-state.md
|
||||
picker-state.types.ts
|
||||
picker-state.test.ts
|
||||
index.ts
|
||||
utils/
|
||||
encoding.ts
|
||||
encoding.md
|
||||
encoding.test.ts
|
||||
tests/
|
||||
integration.test.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
**Downstream**: `@suaveplan/r3f-character-vehicle-picker` wraps picker state in 3D preview UI. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/game-state-schemas`.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Tasks: enterprise-gaming-character-vehicle-picker
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## Phase 1 — Scaffold
|
||||
|
||||
- [ ] Create `gaming/rigs/character-vehicle-picker/` (`@suaveplan/character-vehicle-picker`, `0.1.0`, `sideEffects: false`)
|
||||
- [ ] `tsconfig.json`, `vitest.config.ts`
|
||||
|
||||
## Phase 2 — Error codes & constants
|
||||
|
||||
- [ ] `src/error-codes.ts` + `src/constants/index.ts`
|
||||
|
||||
## Phase 3 — Types
|
||||
|
||||
- [ ] `src/types/common.ts` + `common.md`
|
||||
|
||||
## Phase 4 — Character catalog
|
||||
|
||||
- [ ] `src/core/character-catalog/character-catalog.ts` — list/filter/unlock/lock
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 5 — Vehicle catalog
|
||||
|
||||
- [ ] `src/core/vehicle-catalog/vehicle-catalog.ts` — same surface, vehicle-specific type field
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 6 — Picker state
|
||||
|
||||
- [ ] `src/core/picker-state/picker-state.ts` — selectCharacter/selectVehicle/confirm/undo/redo, locked guard, events
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 7 — Encoding utils
|
||||
|
||||
- [ ] `src/utils/encoding.ts` — `encodePickerSelection` / `decodePickerSelection` via `game-state-schemas`
|
||||
- [ ] Tests + docs
|
||||
|
||||
## Phase 8 — Integration tests
|
||||
|
||||
- [ ] `tests/integration.test.ts` — full pick → confirm → encode → decode round-trip
|
||||
|
||||
## Phase 9 — Pre-publish gate
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/character-vehicle-picker` green
|
||||
- [ ] 100% coverage
|
||||
- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/character-vehicle-picker`
|
||||
Reference in New Issue
Block a user