create-asciitorium 0.1.47 → 0.1.48

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

@@ -2,6 +2,78 @@
 
 This directory contains asciitorium art assets for the asciitorium framework. They are organized into categories: fonts, maps, materials, sounds, and sprites.
 
+## Asset Resolution and Library Assets
+
+The asciitorium framework uses a **fallback resolution system** for assets:
+
+1. **Project Assets First**: `public/art/{type}/{name}.art` in your project
+2. **Library Assets Fallback**: `node_modules/asciitorium/public/art/{type}/{name}.art`
+
+This means you automatically have access to all library assets without copying them!
+
+### Using Library Assets
+
+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
+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');
+```
+
+### Customizing Assets
+
+**To use library asset as-is**: Just reference it by name (nothing to do!)
+
+**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
+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/
+```
+
+Or view the latest assets in the [asciitorium repository](https://github.com/tgruby/asciitorium/tree/main/packages/asciitorium/public/art).
+
 ## Asset Loading
 
 Assets are automatically loaded and cached by `AssetManager` using reactive

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

@@ -1,5 +1,7 @@
 # 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.
 

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

@@ -1,5 +1,7 @@
 # Asciitorium Maps
 
+> **Note**: This directory is empty by default. The asciitorium library includes starter assets in `node_modules/asciitorium/public/art/maps/` 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 map layouts and legends for the **MapView** and
 **FirstPersonView** components. Maps use ASCII characters for layout, with JSON
 legends defining character properties.

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

@@ -1,5 +1,7 @@
 # Asciitorium Materials
 
+> **Note**: This directory is empty by default. The asciitorium library includes starter assets in `node_modules/asciitorium/public/art/materials/` 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 art material files for the **FirstPersonView** and
 **MapView** components. Materials define the visual appearance of walls, floors,
 and other environmental surfaces with depth-based layering.

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

@@ -1,5 +1,7 @@
 # Sounds Directory
 
+> **Note**: This directory is empty by default. The asciitorium library includes starter assets in `node_modules/asciitorium/public/art/sounds/` 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 audio assets in MP3 format used throughout the
 application.
 

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

@@ -1,5 +1,7 @@
 # Asciitorium Sprites
 
+> **Note**: This directory is empty by default. The asciitorium library includes starter assets in `node_modules/asciitorium/public/art/sprites/` 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 sprite files for the **Art** component. Sprites
 allow you to display static or animated ASCII art via the Art component.
 

package/dist/templates/base/vite.config.ts

@@ -1,4 +1,5 @@
 import { defineConfig, Plugin } from 'vite';
+import path from 'path';
 
 // Minimal virtual shim for Node built-ins on the web build
 function nodeBuiltinsShim(): Plugin {
@@ -26,14 +27,24 @@ function nodeBuiltinsShim(): Plugin {
 }
 
 export default defineConfig({
-  esbuild: { 
+  esbuild: {
     target: 'esnext',
     jsx: 'automatic',
     jsxImportSource: 'asciitorium',
   },
   build: { target: 'esnext' },
   plugins: [nodeBuiltinsShim()],
+  resolve: {
+    alias: {
+      // Alias /lib-assets to node_modules/asciitorium/public for library asset fallback
+      '/lib-assets': path.resolve(__dirname, 'node_modules/asciitorium/public'),
+    },
+  },
   server: {
     port: 5173,
+    fs: {
+      // Allow serving files from node_modules/asciitorium
+      allow: ['..'],
+    },
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciitorium",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "private": false,
   "description": "Scaffold a Vite + TypeScript project prewired for asciitorium (web + cli).",
   "bin": {

package/dist/templates/base/public/art/ART-DESIGN-SPEC.md

@@ -1,375 +0,0 @@
-# Art Asset Format Specification
-
-This document defines the metadata format for ASCII art assets in asciitorium, including fonts, materials, and sprites.
-
-## Overview
-
-Art assets use a text-based format that combines:
-
-- **Section headers** (`§`) defining global asset properties
-- **Layer/frame separators** (`¶`) with metadata for each section
-- **ASCII art content** following each separator
-
-## Design Goals
-
-1. **Human-readable**: Artists should be able to read and write metadata without tooling
-2. **Simple**: Use standard JSON format with flat key-value structure
-3. **No nesting**: Flat data structures only - no nested objects or arrays
-4. **Consistent**: Same format works for materials, sprites, and font asset types
-5. **Extensible**: Easy to add new properties without breaking existing assets
-
-## Format Syntax
-
-### File Header (`§`)
-
-The file header appears once at the beginning of the file and defines the asset type and global properties.
-
-**Format:**
-
-```json
-§ {"key":"value","key":"value"}
-```
-
-**Example:**
-
-```json
-§ {"kind":"material","usage":"first-person","placement":"scenery"}
-```
-
-### Layer/Frame Separator (`¶`)
-
-Separates different layers (materials), characters (fonts) or frames (sprites) with section-specific metadata.
-
-**Format:**
-
-```json
-¶ {"key":"value","key":"value"}
-[ASCII art content follows]
-```
-
-**Example:**
-
-```json
-¶ {"layer":"here","pos":"center"}
-   |‽‽‽‽‽‽‽|
-   |‽‽‽‽‽‽‽|
-```
-
-## Parsing Rules
-
-### JSON Format
-
-1. **Parse as JSON**: Standard JSON.parse() after removing separator character
-2. **Primitive values only**: All values must be strings, numbers, or booleans
-3. **No nesting**: Objects must be flat - no nested objects or arrays
-4. **Empty metadata**: Empty separator `¶` or `§` is valid (inherits defaults)
-
-### Single-Frame Sprites
-
-If a file does not start with a `§` file header, it is assumed to be a single-frame sprite with no metadata:
-
-```txt
-  ___
- /   \
-|  o  |
- \___/
-```
-
-This is equivalent to:
-
-```json
-§ {"kind":"sprite","loop":"false"}
-¶
-  ___
- /   \
-|  o  |
- \___/
-```
-
-### Empty Separators
-
-A separator with no metadata is valid for sprites:
-
-```txt
-¶
-[ASCII art content]
-```
-
-This inherits defaults or indicates a frame with no special properties.
-
-## Font Assets
-
-Fonts define ASCII art representations of characters for rendering text in stylized formats.
-
-### File Header Properties
-
-| Key    | Values | Required | Description           |
-| ------ | ------ | -------- | --------------------- |
-| `kind` | `font` | Yes      | Asset type identifier |
-
-### Character Separator Properties
-
-| Key         | Values | Required | Description                         |
-| ----------- | ------ | -------- | ----------------------------------- |
-| `character` | string | Yes      | The character this glyph represents |
-
-### Font Example
-
-``` json
-§ {"kind":"font"}
-¶ {"character":"a"}
-
-╭─╮
-╭─┤
-╰─╰
-
-¶ {"character":"b"}
-│
-├─╮
-│ │
-╯─╯
-
-¶ {"character":"c"}
-
-╭─╮
-│
-╰─╯
-```
-
-### Font Design Rules
-
-- Each character glyph should have consistent height (including leading/trailing blank lines)
-- Characters can have variable width
-- Blank lines before/after the glyph art create vertical spacing
-- The `character` property must be a single character (letter, number, punctuation, etc.)
-- Fonts are typically loaded by name and used to render styled text
-
-## Sprite Assets
-
-Sprites define animated ASCII art with multiple frames.
-
-### File Header Properties
-
-| Key                  | Values          | Required | Description                                |
-| -------------------- | --------------- | -------- | ------------------------------------------ |
-| `kind`               | `sprite`        | Yes      | Asset type identifier                      |
-| `loop`               | `true`, `false` | No       | Whether animation loops (default: `false`) |
-| `default-frame-rate` | number (ms)     | No       | Default frame duration in milliseconds (default is 250 if none is supplied)     |
-
-### Frame Separator Properties
-
-| Key        | Values      | Required | Description                        |
-| ---------- | ----------- | -------- | ---------------------------------- |
-| `duration` | number (ms) | No       | Frame duration (overrides default) |
-| `sound`    | filename    | No       | Sound to play when frame displays  |
-| `event`    | string      | No       | Custom event name to trigger       |
-
-### Sprite Example
-
-```
-§ {"kind":"sprite","loop":true,"default-frame-rate":120}
-¶ {"duration":1000}
-                _ _ _             _
-  __ _ ___  ___(_|_) |_ ___  _ __(_)_   _ _ __ ___
- / _` / __|/ __| | | __/ _ \| '__| | | | | '_ ` _ \
-| (_| \__ \ (__| | | || (_) | |  | | |_| | | | | | |
- \__,_|___/\___|_|_|\__\___/|_|  |_|\__,_|_| |_| |_|
-¶ {"duration":500}
-              .   _ * _             *     .
-  __ _ ___  ___(_|_).|_   *  _ __(_)_   _   *  __
- / _` / __|/ _ .  |  __/  . \ '__| | | | '   `  \ .
-| (_| \__  (__| *|.| || (_) |  * | | |_|  *| | | │ .
- \__,_|___/\__ ._|_|\__\  * /|_|   .|\__   |_| |_│
-¶
-          *      _    *     .    *     .    *
-  __   *      (_|_)   .  *   _ __   .     .    __
- /   `    __|  |    __/   * \ '__|     *      ` \
-| *   * \__    | | || (_) |   .  |  *  *   |   | │
-   .  .|___/   |_| \__\___/|_|   .    .  |_|  . |_│
-```
-
-### Animation Control
-
-- **loop:true**: Animation repeats from first frame after last frame
-- **loop:false**: Animation plays once and stops on last frame
-
-## Material Assets
-
-Materials define visual representations at different distances in first-person view.
-
-### File Header Properties
-
-| Key            | Values                                      | Required | Description                       |
-| -------------- | ------------------------------------------- | -------- | --------------------------------- |
-| `kind`         | `material`                                  | Yes      | Asset type identifier             |
-| `usage`        | `first-person`, `top-down`, `side-scroller` | Yes      | Rendering context                 |
-| `placement`    | `scenery`, `ground`, `ceiling`              | No       | Surface type (default: `scenery`) |
-| `onEnterSound` | filename                                    | No       | Sound when player enters tile     |
-| `onExitSound`  | filename                                    | No       | Sound when player exits tile      |
-| `ambientSound` | filename                                    | No       | Looping sound near this material  |
-
-### Layer Separator Properties
-
-| Key     | Values                          | Required | Description                     |
-| ------- | ------------------------------- | -------- | ------------------------------- |
-| `layer` | `here`, `near`, `middle`, `far` | Yes      | Distance layer                  |
-| `pos`   | `left`, `center`, `right`       | Yes      | Horizontal position             |
-| `x`     | number                          | No       | Horizontal offset for alignment |
-
-### Material Example
-
-```
-§ {"kind":"material","usage":"first-person","placement":"scenery","onEnterSound":"door-open.mp3","onExitSound":"door-close.mp3"}
-¶ {"layer":"here","pos":"left"}
- ╲
- ┊╲
-╲┊ ╲
-¶ {"layer":"here","pos":"center"}
-   |‽‽‽‽‽‽‽‽‽‽|
-   |‽‽‽‽‽‽‽‽‽‽|
-   |‽‽‽‽‽‽‽‽‽‽|
-¶ {"layer":"here","pos":"right"}
-      ╱
-     ╱┊
-    ╱ ┊╱
-¶ {"layer":"near","pos":"center"}
- …… ……… ……… …
-┊……┊………┊………┊…┊
-┊┊…╭───────╮…┊
-┊……|┋┋┋┋┋┋┋|…┊
-¶ {"layer":"middle","pos":"center"}
- … … ……
-┊…┊…┊……┊
-┊…╭──╮…┊
-┊…|┋┋|…┊
-¶ {"layer":"far","pos":"center"}
- ……
-┊……┊
-┊||┊
-```
-
-### Layer System
-
-Materials use a layered perspective system that adapts to different usage contexts:
-
-#### First-Person Usage
-
-- **here**: Immediate foreground (player is on this tile)
-- **near**: Close distance (1-2 tiles away)
-- **middle**: Mid distance (3-5 tiles away)
-- **far**: Far distance (6+ tiles away)
-
-#### Side-Scroller Usage (Parallax Layers)
-
-- **here**: Interactive elements (platforms player stands on, walls player collides with)
-- **near**: Foreground elements (close platforms, foreground decorations)
-- **middle**: Midground elements (trees, buildings, mid-distance scenery)
-- **far**: Background elements (mountains, clouds, distant scenery)
-
-#### Top-Down Usage
-
-- **here**: Ground level elements (floors, paths the player walks on)
-- **near**: Low obstacles and ground decorations
-- **middle**: Medium height elements (furniture, props)
-- **far**: Tall elements and ceiling details
-
-Each layer can have `left`, `center`, and `right` positioned elements for additional composition control.
-
-### Sound Triggers
-
-Sound properties are defined once in the file header and apply to the entire material:
-
-- **onEnterSound**: Plays once when player steps onto the tile
-- **onExitSound**: Plays once when player leaves the tile
-- **ambientSound**: Looping sound while material is visible (future feature)
-
-Sound files must be placed in `art/sounds/` directory.
-
-### Side-Scroller Material Example
-
-Here's an example of materials for a side-scrolling platformer game:
-
-**Ground Platform:**
-
-```
-§ {"kind":"material","usage":"side-scroller","placement":"ground","onEnterSound":"step.mp3"}
-¶ {"layer":"here","pos":"center"}
-═══════════════════════
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
-```
-
-**Brick Wall:**
-
-```
-§ {"kind":"material","usage":"side-scroller","placement":"scenery"}
-¶ {"layer":"here","pos":"center"}
-█▓▒░█▓▒░█▓▒░
-░▒▓█░▒▓█░▒▓█
-█▓▒░█▓▒░█▓▒░
-░▒▓█░▒▓█░▒▓█
-```
-
-**Background Mountain (Parallax):**
-
-```
-§ {"kind":"material","usage":"side-scroller","placement":"scenery"}
-¶ {"layer":"far","pos":"center"}
-      /\
-     /  \
-    /    \
-   /      \
-  /        \
-¶ {"layer":"middle","pos":"center"}
-    /\  /\
-   /  \/  \
-  /        \
-¶ {"layer":"near","pos":"center"}
- /\/\
-/    \
-```
-
-In side-scrollers, the layer system naturally supports parallax scrolling where `far` layers move slower than `here` layers, creating depth perception.
-
-## Validation Rules
-
-### Required Properties
-
-- File header MUST have `kind` property
-- Material layers MUST have `layer` and `pos` properties
-- Sprite frames MAY omit all properties (inherits defaults)
-
-### No Nesting Rule
-
-- All values MUST be primitives (string, number, or boolean)
-- Nested objects are NOT allowed
-- Arrays are NOT allowed
-- This keeps the format simple and predictable
-
-**Invalid (nested object):**
-
-```json
-{ "onEnter": { "sound": "door.mp3" } }
-```
-
-**Valid (flat structure with primitives):**
-
-```json
-{ "onEnterSound": "door.mp3", "duration": 1000, "loop": true }
-```
-
-### Value Constraints
-
-- **layer**: Must be one of `here`, `near`, `middle`, `far`
-- **pos**: Must be one of `left`, `center`, `right`
-- **placement**: Must be one of `scenery`, `ground`, `ceiling`
-- **usage**: Must be one of `first-person`, `top-down`, `side-scroller`
-- **loop**: Must be boolean `true` or `false`
-- **duration**: Must be positive number (milliseconds)
-- **default-frame-rate**: Must be positive number (milliseconds)
-- **x**: Must be number (integer)
-
-### Sound File References
-
-- Sound properties contain filename only (no path)
-- Files resolved relative to `art/sounds/` directory
-- Format: `"onEnterSound":"door-open.mp3"` not `"onEnterSound":"art/sounds/door-open.mp3"`

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

@@ -1,113 +0,0 @@
-# Asciitorium Fonts
-
-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.