create-asciitorium 0.1.46 → 0.1.48

package/dist/templates/base/ASCIITORIUM_REFERENCE.md

@@ -246,7 +246,7 @@ align="center"                 // Alignment (layout-specific)
 
 ```tsx
 <Column align="center" width="100%" gap={2}>
-  <Art src="logo" />
+  <Art sprite="logo" />
   <Text>Welcome</Text>
   <Button>Start</Button>
 </Column>
@@ -808,63 +808,78 @@ const text = new State('initial');
 ### Basic Usage
 
 ```tsx
-// Load from file
-<Art src="logo" />
-
-// ASCII art from figlet font
-<Art font="standard" text="Hello" />
+// Load sprite from file
+<Art sprite="logo" />
 
 // Align center
-<Art src="banner" align="center" />
+<Art sprite="banner" align="center" />
 ```
 
 ### Props
 
-| Prop     | Type                            | Default  | Description                      |
-| -------- | ------------------------------- | -------- | -------------------------------- |
-| `src`    | `string`                        | -        | Art file name (from art/ folder) |
-| `font`   | `string`                        | -        | Figlet font name                 |
-| `text`   | `string`                        | -        | Text to render with font         |
-| `width`  | `number \| 'auto'`              | `'auto'` | Component width                  |
-| `height` | `number \| 'auto'`              | `'auto'` | Component height                 |
-| `align`  | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment             |
-| `border` | `boolean`                       | `false`  | Show border                      |
+| Prop     | Type                            | Default  | Description                          |
+| -------- | ------------------------------- | -------- | ------------------------------------ |
+| `sprite` | `string`                        | -        | Sprite file name (from art/sprites/) |
+| `width`  | `number \| 'auto'`              | `'auto'` | Component width                      |
+| `height` | `number \| 'auto'`              | `'auto'` | Component height                     |
+| `align`  | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment                 |
+| `border` | `boolean`                       | `false`  | Show border                          |
 
 ### Common Patterns
 
-**Pattern 1: Logo from File**
+**Pattern 1: Static Sprite**
 
 ```tsx
-// Loads from art/logo.art
-<Art src="logo" align="center" />
+// Loads from art/sprites/logo.art
+<Art sprite="logo" align="center" />
 ```
 
-**Pattern 2: Generated ASCII Text**
+**Pattern 2: Animated Sprite**
 
 ```tsx
-<Art font="standard" text="Game Over" align="center" />
+// Loads animated art (auto-plays)
+<Art sprite="beating-heart" width={20} />
 ```
 
-**Pattern 3: Animated Sprite**
+
+
+## Banner
+
+### Basic Usage
 
 ```tsx
-// Loads animated art (auto-plays)
-<Art src="beating-heart" width={20} />
+// Render text with font
+<Banner font="standard" text="Hello" />
+
+// Align center
+<Banner font="shadows" text="Game Over" align="center" />
 ```
 
-### Common Mistakes
+### Props
 
-❌ **WRONG** - Using both src and font
+| Prop            | Type                            | Default  | Description                       |
+| --------------- | ------------------------------- | -------- | --------------------------------- |
+| `font`          | `string`                        | -        | Font name (from art/fonts/)       |
+| `text`          | `string \| State<string>`       | -        | Text to render with font          |
+| `letterSpacing` | `number`                        | `0`      | Additional spacing between chars  |
+| `width`         | `number \| 'auto'`              | `'auto'` | Component width                   |
+| `height`        | `number \| 'auto'`              | `'auto'` | Component height                  |
+| `align`         | `'left' \| 'center' \| 'right'` | `'left'` | Horizontal alignment              |
+| `border`        | `boolean`                       | `false`  | Show border                       |
+
+### Common Patterns
+
+**Pattern 1: Title Screen**
 
 ```tsx
-<Art src="logo" font="standard" /> // Conflicting props
+<Banner font="shadows" text="asciitorium" align="center" />
 ```
 
-✅ **CORRECT** - Use one or the other
+**Pattern 2: Reactive Text**
 
 ```tsx
-<Art src="logo" />        // From file
-<Art font="standard" text="Title" />  // Generated
+const score = new State(0);
+<Banner font="pixel" text={score} letterSpacing={1} />
 ```
 
 

package/dist/templates/base/public/art/README.md

@@ -1,115 +1,114 @@
 # Art Directory
 
-This directory contains ASCII art assets for a project. It is organized into subfolders for maps, materials, and sprites. Each file uses plain text or JSON for easy editing and integration.
+This directory contains asciitorium art assets for the asciitorium framework. They are organized into categories: fonts, maps, materials, sounds, and sprites.
 
-## Asset Loading and Caching
+## Asset Resolution and Library Assets
 
-**IMPORTANT:** All assets are automatically loaded and cached by `AssetManager` using reactive `State` objects. When developing components that use assets:
+The asciitorium framework uses a **fallback resolution system** for assets:
 
-### For Component Developers
+1. **Project Assets First**: `public/art/{type}/{name}.art` in your project
+2. **Library Assets Fallback**: `node_modules/asciitorium/public/art/{type}/{name}.art`
 
-**✅ DO:**
-- Use `AssetManager.getMapState(name)` to get a reactive State for maps
-- Use `AssetManager.getMaterialState(name)` to get a reactive State for materials
-- Subscribe to the returned State to react to loading completion or changes
-- Use `GameWorld.getMapState()` when working with GameWorld instances
-- Share State references across components - the cache handles deduplication
+This means you automatically have access to all library assets without copying them!
 
-**❌ DON'T:**
-- Create local caches in components (Map, Set, plain objects)
-- Use the legacy non-reactive methods (`getMap()`, `getMaterial()`) for new code
-- Load the same asset multiple times - AssetManager caches automatically
-- Store asset data in component properties - subscribe to State instead
+### Using Library Assets
 
-### Example Usage
+The asciitorium library includes starter assets:
+
+**Materials**: `wall-brick`, `wall-wireframe`, `bone`, `door-wooden`
+**Sprites**: `beating-heart`, `balloon`, `castle`, `eyes`, `firework`, `heart`, `pyramid`, `welcome`, and more
+**Fonts**: `marker`, `pencil`, `pixel`, `shadows`
+**Maps**: `example` (with legend)
+**Sounds**: `door-open.mp3`, `door-close.mp3`, `taps.mp3`
+
+Simply reference them by name - no need to copy files:
 
 ```typescript
-// ✅ Correct: Use reactive State from AssetManager
-const materialState = AssetManager.getMaterialState('brick-wall');
-
-// Subscribe to get the value when loaded
-materialState.subscribe((material) => {
-  if (material) {
-    // Material is loaded, use it
-    console.log('Material loaded:', material);
-  }
-});
-
-// Check current value (may be null if still loading)
-if (materialState.value) {
-  // Material already loaded from cache
-}
-
-// ✅ Correct: GameWorld automatically uses AssetManager's State cache
-const gameWorld = new GameWorld({ mapName: 'dungeon' });
-gameWorld.getMapState().subscribe((mapAsset) => {
-  // Automatically updates when map loads
-});
-
-// ❌ Wrong: Don't create your own cache
-class MyComponent {
-  private myCache: Map<string, Material> = new Map(); // DON'T DO THIS!
-}
+import { AssetManager, Art, Banner } from 'asciitorium';
+
+// Use library sprite
+<Art sprite="beating-heart" />
+
+// Use library font
+<Banner font="shadows" text="Hello" />
+
+// Use library material (in map legend)
+const materialAsset = await AssetManager.getMaterial('wall-brick');
 ```
 
-### Architecture Benefits
+### Customizing Assets
 
-- **Single source of truth**: AssetManager is the only cache
-- **Automatic updates**: Components react when assets load or change
-- **Memory efficient**: One copy of each asset shared across all components
-- **Hot-reload ready**: Asset changes propagate automatically to all subscribers
-- **No manual cache management**: State handles all invalidation and updates
+**To use library asset as-is**: Just reference it by name (nothing to do!)
 
-## Directory Structure
+**To customize a library asset**:
+1. Copy the asset from `node_modules/asciitorium/public/art/{type}/{name}.art`
+2. Paste into your project's `public/art/{type}/{name}.art`
+3. Edit as desired
+4. Your version now takes precedence over the library version
+
+**To create custom assets**:
+1. Create a new `.art` file in `public/art/{type}/{custom-name}.art`
+2. Follow the format documented in the type-specific README
+3. Reference by name in your code
 
+### Asset Updates
+
+When you run `npm update asciitorium`:
+- Library assets are automatically updated in `node_modules/asciitorium/public/art/`
+- Your project assets in `public/art/` are never touched
+- Any library assets you haven't overridden get the latest improvements
+- Any assets you've copied to your project stay as-is (your responsibility to update)
+
+**Best Practice**: Only copy library assets to your project if you need to customize them. Use library assets directly whenever possible to benefit from automatic updates.
+
+### Listing Available Library Assets
+
+To see all available library assets, check:
 ```bash
-public/art/
-├─ maps/
-│ └─ example/
-│ ├─ map.art
-│ └─ legend.json
-│
-├─ materials/
-│ ├─ brick-wall.art
-│ └─ wooden-door.art
-│
-├─ sprites/
-├─ giant-rat.art
-└─ wolf.art
+ls node_modules/asciitorium/public/art/materials/
+ls node_modules/asciitorium/public/art/sprites/
+ls node_modules/asciitorium/public/art/fonts/
+ls node_modules/asciitorium/public/art/maps/
+ls node_modules/asciitorium/public/art/sounds/
 ```
 
-## maps/
+Or view the latest assets in the [asciitorium repository](https://github.com/tgruby/asciitorium/tree/main/packages/asciitorium/public/art).
 
-Contains map layouts and legends for game environments. Maps are typically stored as text files with ASCII characters representing different terrain types, while legend files (JSON format) define what each character represents, including visual assets, collision properties, and gameplay entity types.
+## Asset Loading
 
-**Contents:**
+Assets are automatically loaded and cached by `AssetManager` using reactive
+`State` objects. The AssetManager provides a single source of truth with
+automatic caching and updates.
 
-- `example/` - Sample map directory containing:
-  - `map.art` - ASCII representation of the map layout
-  - `legend.json` - Character-to-entity mapping with visual assets, collision, and behavior definitions
+## Directory Structure
+
+``` bash
+art/
+├── fonts/         # ASCII font definitions
+├── maps/          # Game map layouts with legends
+├── materials/     # Wall textures and environmental materials
+├── sounds/        # Audio files (MP3)
+└── sprites/       # Animated character and object sprites
+```
 
-See [maps/README.md](maps/README.md) for detailed information on map file format, legend properties, and the entity/variant system.
+## Subdirectories
 
-## materials/
+### [fonts/](fonts/README.md)
 
-Includes ASCII representations of various materials and textures that can be used in game environments. Materials define layered visual representations at different distances (here, near, middle, far) and can include proximity-based sound effects and ambient events.
+ASCII font definitions for `Banner` component rendering. See the fonts README for file format details.
 
-**Contents:**
+### [maps/](maps/README.md)
 
-- `brick-wall.art` - ASCII pattern for brick wall textures
-- `bone.art` - Ground-placed bone material with placement metadata
-- `door-on-brick.art` - Door material overlaid on brick wall background
-- `wireframe-wall.art` - Complex wireframe demonstrating layered perspective rendering
+Map layouts paired with legend metadata define the position of terrain and entities. See the maps README for format specifications and the entity system.
 
-See [materials/README.md](materials/README.md) for detailed information on material file format, layer system, placement properties, and the relationship between materials and legend entities.
+### [materials/](materials/README.md)
 
-## sprites/
+Materials are used for `FirstPersonView` textures with layered depth rendering (here, near, middle, far). Materials can include placement metadata and sound effects. See the materials README for layer syntax and properties.
 
-Stores animated sprite files for characters, creatures, and other game entities. Sprites support multiple frames with configurable timing and can be referenced by legend entities for dynamic visual representation.
+### [sounds/](sounds/README.md)
 
-**Contents:**
+Audio files in MP3 format used throughout the application. See the sounds README for usage details.
 
-- `giant-rat.art` - ASCII sprite for giant rat creature
-- `wolf.art` - ASCII sprite for wolf creature
+### [sprites/](sprites/README.md)
 
-Sprites are referenced in map legends via the `asset` property and can be combined with entity types to define interactive game objects.
+Static or animated ASCII art with frame timing are in the sprites directory. They can be added using the `Art` component. See the sprites README for animation format details.

package/dist/templates/base/public/art/fonts/README.md

@@ -0,0 +1,115 @@
+# Asciitorium Fonts
+
+> **Note**: This directory is empty by default. The asciitorium library includes starter assets in `node_modules/asciitorium/public/art/fonts/` that are automatically available without copying. See the main [art/README.md](../README.md) for details on using and customizing library assets.
+
+This directory contains ASCII font files for the **Banner** component. Fonts
+allow you to display large, stylized text using ASCII art characters.
+
+## Font File Format
+
+Font files use the `.art` extension and follow a structured format with metadata
+separators:
+
+### File Structure
+
+``` txt
+§ {"kind":"font"}
+¶ {"character":"A"}
+╭─╮
+│ │
+├─┤
+╵ ╵
+
+¶ {"character":"a"}
+
+╭─╮
+╭─┤
+╰─╰
+
+¶ {"character":["b", "B"]}
+╷
+├─╮
+│ │
+╯─╯
+```
+
+### Key Components
+
+1. **File Header** (`§` separator)
+   - Must start with `§ {"kind":"font"}`
+   - Indicates this is a font asset
+
+2. **Glyph Sections** (`¶` separator)
+   - Each glyph begins with `¶ {"character":"x"}` where `x` is the character
+   - Character can be a single string: `"a"`
+   - Or an array for multiple mappings: `["b", "B"]` (both lowercase and
+     uppercase)
+   - Glyph content follows immediately after the metadata line
+
+3. **Glyph Content**
+   - ASCII art representation of the character
+   - Each glyph can be any width/height
+   - Vertical positioning is preserved (blank lines matter!)
+   - Maximum font height is determined by the tallest glyph
+
+**Tips:**
+
+- Empty lines within glyphs are preserved to maintain vertical alignment
+- The first line after the glyph metadata is part of the character (no automatic
+  trimming)
+- Map multiple characters to the same glyph using arrays:
+  `{"character":["a","A"]}`
+- All glyphs should have consistent height for best results (pad with empty
+  lines if needed)
+
+## Using Fonts in Your App
+
+### Basic Usage
+
+```tsx
+<Banner font="pencil" text="asciitorium" />
+```
+
+### With Letter Spacing
+
+```tsx
+<Banner font="marker" text="HELLO" letterSpacing={1} />
+```
+
+### With Reactive State
+
+```tsx
+import { State } from 'asciitorium';
+
+const titleText = new State<string>("Welcome");
+
+<Banner font="shadows" text={titleText} align="center" />
+```
+
+### Available Props
+
+- `font` (required): Name of the font file (without `.art` extension)
+- `text`: String or `State<string>` to render
+- `letterSpacing`: Additional spacing between characters (default: 0)
+- Plus all standard component props: `position`, `border`, `align`, `style`,
+  etc.
+
+## Technical Details
+
+### Loading
+
+Fonts are loaded asynchronously via the `AssetManager`:
+
+```typescript
+const fontAsset = await AssetManager.getFont('myfont');
+```
+
+### Caching
+
+Font assets are cached on first load - subsequent uses of the same font reuse
+the cached data.
+
+### Fallback Rendering
+
+If a character is not found in the font, the Banner component renders the
+character itself as a single-width glyph on the top line.