Codex Pet UI

UI rendering packages for Codex desktop pets.

The renderer supports both Codex pet atlas versions:

• spritesheet.webp
• 192 x 208 px per frame
• V1: 8 columns by 9 rows (1536x1872); spriteVersionNumber is omitted
• V2: 8 columns by 11 rows (1536x2288); spriteVersionNumber is 2
• pet.json with id, displayName, description, spritesheetPath, and the optional version field

Omitting the version preserves the legacy V1 behavior. V2 adds 16 clockwise look directions in rows 9-10, beginning with 000° at up/12 o'clock.

Default animation rows:

Name	Row	Frames
idle	0	6
runningRight	1	8
runningLeft	2	8
waving	3	4
jumping	4	5
failed	5	8
waiting	6	6
running	7	6
review	8	6

sleeping is kept as a compatibility alias for row 6.

Packages

• @petx/core: shared types, animation table, frame style helpers
• @petx/react: React component
• @petx/react-native: React Native component
• @petx/vue: Vue component
• @petx/webcomponent: framework-free custom element
• @petx/svelte: Svelte component
• @petx/solid: SolidJS component

AI agent integration

Give a code agent this guide when it needs to add PetX to another app: docs/AI_AGENT_INTEGRATION.md.

Release

The first public release is 0.1. npm package versions use the SemVer form 0.1.0.

React

import{PetX}from'@petx/react';import'@petx/react/styles.css';exportfunctionPreview(){return(<PetXsrc="/pets/frieren/spritesheet.webp"animation="idle"size={192}frameInterval={140}/>);}

React Native

import{PetX}from'@petx/react-native';exportfunctionPreview(){return(<PetXsource={require('./assets/pets/frieren/spritesheet.webp')}animation="idle"size={192}title="Frieren Codex pet"/>);}

Use src for remote spritesheets and source for bundled app assets. React Native does not need a PetX CSS import.

Vue

<script setup lang="ts">import { PetX } from'@petx/vue';import'@petx/vue/styles.css';</script>
<template>
<PetX src="/pets/frieren/spritesheet.webp" animation="waving" :size="192" />
</template>

Web Component

import{definePetXElement}from'@petx/webcomponent';definePetXElement();

<pet-xsrc="/pets/frieren/spritesheet.webp" animation="idle" size="192"></pet-x>

Svelte

<scriptlang="ts">importPetXfrom'@petx/svelte';import'@petx/svelte/styles.css';</script>
<PetXsrc="/pets/frieren/spritesheet.webp"animation="jumping"size={192} />

SolidJS

import{PetX}from'@petx/solid';import'@petx/solid/styles.css';exportfunctionPreview(){return<PetXsrc="/pets/frieren/spritesheet.webp"animation="review"size={192}/>;}

Manifest helper

import{resolvePetSpritesheet}from'@petx/core';consturl=resolvePetSpritesheet(pet,'/pets/frieren/pet.json');

Use animations when a pet package uses a different row or frame count.

V2 look directions

Pass the manifest through pet to select V2 automatically. lookDirection accepts clockwise degrees from up or a screen-space vector where positive x points right and positive y points down:

constpet={id: 'codey-v2',displayName: 'Codey V2',spriteVersionNumber: 2,spritesheetPath: '/pets/codey-v2/spritesheet.webp',};<PetXpet={pet}lookDirection={{x: 1,y: -1}}size={192}/>;

For a direct src, pass spriteVersionNumber={2}. A zero vector, a vector inside lookDeadzone, or an omitted lookDirection falls back to the selected standard animation. V1 manifests ignore look input and continue rendering the 9-row atlas.

Examples

Each example is a small Vite app using the same pet assets from examples/assets/pets.

pnpm dev # website
pnpm dev:site # same as pnpm dev
pnpm dev:example:react
pnpm dev:example:vue
pnpm dev:example:svelte
pnpm dev:example:solid
pnpm dev:example:webcomponent

All examples share the same interaction: choose an animation and preview /pets/frieren/spritesheet.webp.

Tests

pnpm test

The test command typechecks every workspace, builds every package and example, then runs Node tests against the published package entrypoints and shared example assets.