AGENTS.md

Project Overview

Dawncaster is a mobile rogue-like card game similar to Slay The Spire. This is a static website that provides an alternative interface for browsing Dawncaster game data from the Blightbane API.

The site should follow best practices from the Web Content Accessibility Guidelines and be responsive for ease of use on small screens.

The site consists of two main pages:

```
cards.html
```
- Browse and filter game cards, alternate interface for https://blightbane.io/cards
```
talents.html
```
- Browse and filter talent information, alternate interface for https://blightbane.io/talents

Both pages are standalone HTML files with embedded CSS and JavaScript. There is no build process, package manager, or dependencies beyond dependencies loaded from CDN.

Architecture

API Integration

All data comes from the Blightbane API at

https://blightbane.io/api

Search:

GET /api/cards?search=&rarity=&category=&type=&banner=&exp=

, cards returned from this endpoint don't have costs

Card details:
```
GET /api/card/{id}
```
Talent details:
```
GET /api/card/{id}?talent=true
```

API Query Requirements

CRITICAL: All query parameters must be present even if empty. The search API expects:

/api/cards?search=&rarity=&category=&type=&banner=&exp=

Missing parameters will cause the query to fail. Empty values are valid and return unfiltered results for that parameter.

API Best Practices

NEVER spam the API. Do NOT:

Loop through large ranges of card IDs (e.g.,
```
for id in range(1, 2000)
```
)
Make rapid sequential requests without rate limiting
Perform exhaustive searches when targeted queries are possible

DO use filter parameters intelligently:

If you know a card is "rare gold", use
```
?rarity=2&banner=8
```
If you know the card category, include it in the query
Use the search parameter for text-based queries
Combine filters to narrow results before fetching individual card details

API Response Format

The API returns HTML markup in description fields, including:

```

```
tags for bold text
```
 
```
or
```
 
```
tags for line breaks
Other formatting tags as needed

Descriptions must be sanitized before rendering to prevent XSS attacks.

Extracting Filter Values from Blightbane

The Blightbane website is a client-side JavaScript application. The raw HTML does not contain dropdown options - they are dynamically generated by JavaScript. To get the authoritative, up-to-date filter values for use in the search endpoint:

Find the current bundle version:

curl -s 'https://blightbane.io' | grep -o 'index.bundle.js?v=[0-9.]*'

Example output:

index.bundle.js?v=0.20.5

Fetch the JavaScript bundle:

VERSION="0.20.5"  # Use version from step 1
curl -s "https://blightbane.io/js/index.bundle.js?v=${VERSION}" > bundle.js

Extract filter arrays using regex patterns:

# Categories
grep -oP '"Action","Item"[^]]*' bundle.js | head -1

# Types
grep -oP '"Melee","Magic"[^]]*' bundle.js | head -1

# Rarities
grep -oP '"Common","Uncommon"[^]]*' bundle.js | head -1

# Banners/Colors
grep -oP '"Green","Blue","Red","Purple"[^]]*' bundle.js | head -1

# Expansions
grep -oP '"Core","Metaprogress"[^]]*' bundle.js | head -1

Array index corresponds to the API filter value (e.g., "Rare" is at index 2, so use
```
?rarity=2
```
)
Some filters prepend "None" at index 0 (banners/colors and expansions)

Local Database Approach

The html files have JavaScript which queries an SQLite database. The database needs to be generated ahead of time by crawling the API.

The

create-db/run.py

script builds a complete SQLite database from the Blightbane API:

python run create-db/run.py dawncaster-cards.db

Fetches filter values from Blightbane JavaScript bundle (always up-to-date)
Queries all 96 rarity/color combinations to collect all card IDs
Fetches detailed info for each card with 0.5s rate limiting (respects API)
Sanitizes HTML descriptions (keeps
```
 
```
tags, strips everything else)
FetchesDoes something similar to fetch all talents5. Stores everything in SQLite with STRICT tables and foreign key enforcement

Database contains:

~1,672 cards
Lookup tables: categories, types, rarities, expansions, colors
Main cards table with foreign keys
Costs table with resource breakdowns
Talents

Functional Programming Style

The code follows a functional approach with:

Pure render functions that map data to HTML strings
Separate functions for data fetching and DOM updates
Immutable data transformations using
```
map
```
,
```
filter
```
, and
```
join
```

Development

Install dependencies with

npm i

, only used for running tests.

npm run start

to start a development server, then open a web browser and go to http://127.0.0.1:4173/cards.html

To run Playwright tests:

npm run test

. Note: this command also runs the development server

AGENTS.md

Project Overview

Dawncaster is a mobile rogue-like card game similar to Slay The Spire. This is a static website that provides an alternative interface for browsing Dawncaster game data from the Blightbane API.

The site should follow best practices from the Web Content Accessibility Guidelines and be responsive for ease of use on small screens.

The site consists of two main pages:

```
cards.html
```
- Browse and filter game cards, alternate interface for https://blightbane.io/cards
```
talents.html
```
- Browse and filter talent information, alternate interface for https://blightbane.io/talents

Both pages are standalone HTML files with embedded CSS and JavaScript. There is no build process, package manager, or dependencies beyond dependencies loaded from CDN.

Architecture

API Integration

All data comes from the Blightbane API at

https://blightbane.io/api

Search:

GET /api/cards?search=&rarity=&category=&type=&banner=&exp=

, cards returned from this endpoint don't have costs

Card details:
```
GET /api/card/{id}
```
Talent details:
```
GET /api/card/{id}?talent=true
```

API Query Requirements

CRITICAL: All query parameters must be present even if empty. The search API expects:

/api/cards?search=&rarity=&category=&type=&banner=&exp=

Missing parameters will cause the query to fail. Empty values are valid and return unfiltered results for that parameter.

API Best Practices

NEVER spam the API. Do NOT:

Loop through large ranges of card IDs (e.g.,
```
for id in range(1, 2000)
```
)
Make rapid sequential requests without rate limiting
Perform exhaustive searches when targeted queries are possible

DO use filter parameters intelligently:

If you know a card is "rare gold", use
```
?rarity=2&banner=8
```
If you know the card category, include it in the query
Use the search parameter for text-based queries
Combine filters to narrow results before fetching individual card details

API Response Format

The API returns HTML markup in description fields, including:

```

```
tags for bold text
```
 
```
or
```
 
```
tags for line breaks
Other formatting tags as needed

Descriptions must be sanitized before rendering to prevent XSS attacks.

Extracting Filter Values from Blightbane

Find the current bundle version:

curl -s 'https://blightbane.io' | grep -o 'index.bundle.js?v=[0-9.]*'

Example output:

index.bundle.js?v=0.20.5

Fetch the JavaScript bundle:

VERSION="0.20.5"  # Use version from step 1
curl -s "https://blightbane.io/js/index.bundle.js?v=${VERSION}" > bundle.js

Extract filter arrays using regex patterns:

# Categories
grep -oP '"Action","Item"[^]]*' bundle.js | head -1

# Types
grep -oP '"Melee","Magic"[^]]*' bundle.js | head -1

# Rarities
grep -oP '"Common","Uncommon"[^]]*' bundle.js | head -1

# Banners/Colors
grep -oP '"Green","Blue","Red","Purple"[^]]*' bundle.js | head -1

# Expansions
grep -oP '"Core","Metaprogress"[^]]*' bundle.js | head -1

Array index corresponds to the API filter value (e.g., "Rare" is at index 2, so use
```
?rarity=2
```
)
Some filters prepend "None" at index 0 (banners/colors and expansions)

Local Database Approach

The html files have JavaScript which queries an SQLite database. The database needs to be generated ahead of time by crawling the API.

The

create-db/run.py

script builds a complete SQLite database from the Blightbane API:

python run create-db/run.py dawncaster-cards.db

Fetches filter values from Blightbane JavaScript bundle (always up-to-date)
Queries all 96 rarity/color combinations to collect all card IDs
Fetches detailed info for each card with 0.5s rate limiting (respects API)
Sanitizes HTML descriptions (keeps
```
 
```
tags, strips everything else)
FetchesDoes something similar to fetch all talents5. Stores everything in SQLite with STRICT tables and foreign key enforcement

Database contains:

~1,672 cards
Lookup tables: categories, types, rarities, expansions, colors
Main cards table with foreign keys
Costs table with resource breakdowns
Talents

Functional Programming Style

The code follows a functional approach with:

Pure render functions that map data to HTML strings
Separate functions for data fetching and DOM updates
Immutable data transformations using
```
map
```
,
```
filter
```
, and
```
join
```

Development

Install dependencies with

npm i

, only used for running tests.

npm run start

to start a development server, then open a web browser and go to http://127.0.0.1:4173/cards.html

To run Playwright tests:

npm run test

. Note: this command also runs the development server

AGENTS.md

AGENTS.md

Project Overview

Architecture

API Integration

API Query Requirements

API Best Practices

API Response Format

Extracting Filter Values from Blightbane

Local Database Approach

Functional Programming Style

Development

Related Skills

Markdown Converter

Nano Banana Pro

1password

AGENTS.md

Project Overview

Architecture

API Integration

API Query Requirements

API Best Practices

API Response Format

Extracting Filter Values from Blightbane

Local Database Approach

Functional Programming Style

Development