@whykusanagi/corrupted-theme 0.1.1 → 0.1.3

package/docs/CHARACTER_LEVEL_CORRUPTION.md

@@ -0,0 +1,264 @@
+# Character-Level Corruption - Implementation Guide
+
+**Date**: 2025-12-12
+**Issue Fixed**: Dashboard titles now use character-level Japanese mixing instead of word replacement
+
+---
+
+## The Problem
+
+The old dashboard had Japanese characters mixed **INTO** English words like:
+```
+👁️  US使AGE ANア統LYTICS  👁️
+```
+
+But the implementation was using word-level replacement:
+```
+👁️  使用 tōkei  👁️  (replaces whole words)
+```
+
+This didn't match the style guide examples like:
+- `"loaディング"` - Japanese mixed into "loading"
+- `"pro理cessing"` - Japanese mixed into "processing"
+- `"ana分lysing"` - Japanese mixed into "analyzing"
+
+---
+
+## The Solution
+
+### New Function: `CorruptTextJapanese()`
+
+**Location**: `cmd/celeste/tui/streaming.go` (line 252) and `cmd/celeste/commands/corruption.go`
+
+This function mixes Japanese characters **INTO** English words at the character level:
+
+```go
+func CorruptTextJapanese(text string, intensity float64) string {
+    katakana := []rune("アイウエオカキクケコサシスセソタチツテトナニヌネノハヒフヘホマミムメモヤユヨラリルレロワヲン")
+    kanjiFragments := []rune("壊虚深淵闇処理分析監視接続統計使用読込実行")
+
+    // For each character:
+    // 50% chance: Replace with Katakana
+    // 25% chance: Replace with Kanji
+    // 25% chance: Keep + maybe insert Katakana after
+}
+```
+
+### Example Outputs
+
+**Input**: `"USAGE ANALYTICS"`
+**Intensity**: `0.35`
+
+**Possible outputs** (randomized each time):
+```
+"US使AGE ANア統LYTICS"
+"USアGE AN統AL読TICSカ"
+"USカGE 分NALYTI監S"
+"U接AGE処A壊ALYTICS"
+```
+
+The Japanese characters are mixed IN, making it readable but glitchy!
+
+---
+
+## Files Updated
+
+### 1. `cmd/celeste/commands/corruption.go`
+
+**Added** (line 124):
+```go
+func corruptTextCharacterLevel(text string, intensity float64) string {
+    // Character-level Japanese mixing
+    // Same implementation as CorruptTextJapanese
+}
+```
+
+### 2. `cmd/celeste/commands/stats.go`
+
+**Changed** (line 194):
+```go
+// OLD (word replacement):
+title := corruptTextSimple("USAGE ANALYTICS", 0.40)
+
+// NEW (character mixing):
+title := corruptTextCharacterLevel("USAGE ANALYTICS", 0.35)
+```
+
+### 3. `cmd/celeste/tui/streaming.go`
+
+**Added** (line 252):
+```go
+func CorruptTextJapanese(text string, intensity float64) string {
+    // Character-level Japanese mixing
+    // Available throughout TUI
+}
+```
+
+**Kept** (line 233):
+```go
+func CorruptText(text string, intensity float64) string {
+    // Block character corruption (█▓▒░)
+    // For skill execution, heavy glitching
+}
+```
+
+---
+
+## Two Corruption Types
+
+### Type 1: Character-Level Japanese Mixing ✨ **NEW**
+
+**Function**: `CorruptTextJapanese()` or `corruptTextCharacterLevel()`
+**Output**: `"US使AGE ANア統LYTICS"` (readable with Japanese)
+**Use for**: Dashboard titles, section headers, any text that should stay readable
+
+```go
+// Dashboard header
+title := tui.CorruptTextJapanese("USAGE ANALYTICS", 0.35)
+
+// Section header
+section := tui.CorruptTextJapanese("PROVIDER BREAKDOWN", 0.30)
+```
+
+**Intensity Guide**:
+- `0.25-0.30`: Light corruption (25-30% chars replaced)
+- `0.30-0.35`: Medium corruption (30-35% chars replaced) ← **Recommended for titles**
+- `0.35-0.40`: Heavy corruption (35-40% chars replaced)
+
+### Type 2: Block Character Corruption
+
+**Function**: `CorruptText()`
+**Output**: `"tar▓█_r▒ad░ng"` (hard to read, heavy glitching)
+**Use for**: Skill names during execution, loading animations
+
+```go
+// Skill execution (strikethrough + corruption)
+skillName := tui.CorruptText("tarot_reading", 0.40)
+
+// Loading state
+loading := tui.CorruptText("Loading...", 0.30)
+```
+
+**Intensity Guide**:
+- `0.30-0.35`: Light block corruption
+- `0.35-0.40`: Medium block corruption ← **Recommended for skills**
+- `0.40-0.50`: Heavy block corruption
+
+---
+
+## When to Use Each Function
+
+| Context | Function | Intensity | Example |
+|---------|----------|-----------|---------|
+| Dashboard title | `CorruptTextJapanese` | 0.35 | "US使AGE ANア統LYTICS" |
+| Section header | `CorruptTextJapanese` | 0.30 | "PROバIDERア BREア統KDOWN" |
+| Subsection | `CorruptTextJapanese` | 0.25 | "TO監AL SEセSSI使NS" |
+| Skill executing | `CorruptText` | 0.40 | "tar▓█_r▒ad░ng" |
+| Loading animation | `CorruptText` | 0.30 | "L▓ad█ng..." |
+| Status phrases | Neither (use phrase bank) | N/A | "処理 processing purosesu..." |
+
+---
+
+## Testing the Fix
+
+### Before (Word Replacement):
+```bash
+celeste chat
+/stats
+```
+Output was:
+```
+👁️  使用 tōkei  👁️  (whole words replaced)
+```
+
+### After (Character Mixing):
+```bash
+celeste chat
+/stats
+```
+Output is now (randomized):
+```
+👁️  US使AGE ANア統LYTICS  👁️  (Japanese mixed in)
+```
+
+Each time you run `/stats`, the corruption is randomized, so you'll see different variations like:
+- `"US使AGE ANア統LYTICS"`
+- `"USアGE AN統AL読TICSカ"`
+- `"USカGE 分NALYTI監S"`
+
+---
+
+## Visual Comparison
+
+### Old Implementation (Word-Level)
+```
+▓▒░ ═══════════════════════════════════════ ░▒▓
+           👁️  使用 統計  👁️
+     ⟨ tōkei dēta wo... fuhai sasete iru... ⟩
+▓▒░ ═══════════════════════════════════════ ░▒▓
+```
+**Problem**: Entire words replaced, not mixed
+
+### New Implementation (Character-Level)
+```
+▓▒░ ═══════════════════════════════════════ ░▒▓
+           👁️  US使AGE ANア統LYTICS  👁️
+     ⟨ tōkei dēta wo... fuhai sasete iru... ⟩
+▓▒░ ═══════════════════════════════════════ ░▒▓
+```
+**Solution**: Japanese characters mixed INTO English ✓
+
+---
+
+## Matches Style Guide Examples
+
+The new implementation now matches all the examples from `STYLE_GUIDE.md`:
+
+✅ `"loading"` → `"loaディング"`
+✅ `"processing"` → `"pro理cessing"`
+✅ `"analyzing"` → `"ana分lysing"`
+✅ `"corrupting"` → `"cor壊rupting"`
+✅ `"statistics"` → `"sta計stics"`
+
+And the dashboard title:
+✅ `"USAGE ANALYTICS"` → `"US使AGE ANア統LYTICS"`
+
+---
+
+## Implementation Notes
+
+### Why Two Functions?
+
+1. **Readable corruption** (Japanese mixing) - For UI text users need to read
+2. **Heavy corruption** (block characters) - For dramatic effect when readability isn't critical
+
+### Why the Old Implementation Was Wrong
+
+The old `corruptTextSimple()` function did **semantic word replacement**:
+- "USAGE" → `"使用"` (whole word)
+- "ANALYTICS" → `"統計"` (whole word)
+
+This was more of a **translation** than **corruption**. The aesthetic requires **glitchy mixing** where Japanese interrupts English mid-word.
+
+### Performance
+
+Character-level mixing is slightly more expensive than word replacement, but the difference is negligible:
+- Dashboard renders once per `/stats` command
+- Randomization happens at display time
+- No caching needed (variations are a feature!)
+
+---
+
+## Related Files
+
+- **Implementation**: `tui/streaming.go:252` and `commands/corruption.go:124`
+- **Usage**: `commands/stats.go:194`
+- **Style Guide**: `docs/STYLE_GUIDE.md`
+- **Phrase Library**: `docs/CORRUPTION_PHRASES.md`
+- **Validation**: `docs/IMPLEMENTATION_VALIDATION.md`
+
+---
+
+**Status**: ✅ **FIXED** - Dashboard now uses character-level corruption
+**Tested**: Visual output matches style guide examples
+**Impact**: All dashboard headers now have proper translation-failure aesthetic

package/docs/COMPONENTS_REFERENCE.md

@@ -17,6 +17,12 @@ This document provides a comprehensive reference for all components available in
 6. [API Documentation](#api-documentation)
 7. [Nikke Components](#nikke-components)
 8. [Background & Images](#background--images)
+9. [Extension Components](#extension-components)
+   - [Gallery System](#gallery-system)
+   - [Lightbox](#lightbox)
+   - [NSFW Content Blur](#nsfw-content-blur)
+   - [Social Links List](#social-links-list)
+   - [Countdown Widget](#countdown-widget)
 
 ---
 
@@ -445,7 +451,7 @@ Complete API documentation components for building readable API docs.
 
 ## Nikke Components
 
-Game-specific components for Nikke applications. See [NIKKE_COMPONENTS.md](./NIKKE_COMPONENTS.md) for complete documentation.
+Game-specific components for Nikke applications.
 
 ### Element Badges
 
@@ -632,7 +638,7 @@ All components follow accessibility best practices:
 
 ## Customization
 
-All components use CSS variables for easy customization. See [VARIABLES_REFERENCE.md](./VARIABLES_REFERENCE.md) for complete variable list.
+All components use CSS variables for easy customization. See `src/css/variables.css` for the complete variable list.
 
 ```css
 :root {
@@ -644,16 +650,297 @@ All components use CSS variables for easy customization. See [VARIABLES_REFERENC
 
 ---
 
+## Extension Components
+
+Production-tested components from whykusanagi.xyz for galleries, social links, countdowns, and more. Import via `extensions.css` (included in `theme.css`) or individually.
+
+### Gallery System
+
+Responsive gallery grid with filtering and lightbox integration.
+
+**Filter Bar:**
+```html
+<div class="filter-bar">
+  <button class="filter-btn active" data-filter="all">All</button>
+  <button class="filter-btn" data-filter="photos">Photos</button>
+  <button class="filter-btn" data-filter="art">Art</button>
+</div>
+```
+
+**Gallery Container:**
+```html
+<div class="gallery-container" id="my-gallery">
+  <div class="gallery-item" data-tags="photos">
+    <img src="image.jpg" alt="Description">
+    <div class="gallery-caption">
+      <div class="title">Image Title</div>
+      <div class="meta">Category • Date</div>
+    </div>
+  </div>
+</div>
+```
+
+**Variants:**
+- `.gallery-container.compact` - Smaller grid items (200px min)
+- `.gallery-container.large` - Larger grid items (350px min)
+- `.gallery-item.square` - 1:1 aspect ratio
+- `.gallery-item.portrait` - 3:4 aspect ratio
+- `.gallery-item.landscape` - 16:9 aspect ratio
+- `.filter-bar.left` - Left-aligned filters
+- `.filter-bar.right` - Right-aligned filters
+
+**JavaScript Integration:**
+```javascript
+import { initGallery } from '@whykusanagi/corrupted-theme/gallery';
+
+const gallery = initGallery('#my-gallery', {
+  filterBarSelector: '.filter-bar .filter-btn',
+  enableLightbox: true,
+  enableNsfw: true,
+  filterAnimation: true,
+  onFilter: (filter) => console.log('Filtered:', filter)
+});
+
+// Manual filter
+gallery.filter('photos');
+```
+
+---
+
+### Lightbox
+
+Fullscreen image viewer with keyboard navigation and touch gestures.
+
+```html
+<!-- Lightbox is auto-created by gallery.js -->
+<!-- Manual creation (if needed): -->
+<div class="lightbox" id="my-lightbox">
+  <button class="lightbox-close">&times;</button>
+  <button class="lightbox-prev"><i class="fas fa-chevron-left"></i></button>
+  <img class="lightbox-image" src="" alt="">
+  <button class="lightbox-next"><i class="fas fa-chevron-right"></i></button>
+  <div class="lightbox-caption"></div>
+  <div class="lightbox-counter"></div>
+</div>
+```
+
+**Features:**
+- Keyboard navigation (Arrow keys, Escape)
+- Touch swipe gestures on mobile
+- Click outside to close
+- Image counter display
+- Automatic caption display
+
+**JavaScript API:**
+```javascript
+const gallery = initGallery('#gallery');
+
+// Open specific image
+gallery.openLightbox(0);
+
+// Close lightbox
+gallery.closeLightbox();
+```
+
+---
+
+### NSFW Content Blur
+
+Content warning overlay with click-to-reveal functionality.
+
+```html
+<!-- Default warning text -->
+<div class="gallery-item nsfw-content">
+  <img src="sensitive-image.jpg" alt="Description">
+</div>
+
+<!-- Custom warning text -->
+<div class="gallery-item nsfw-content" data-warning="Sensitive Content">
+  <img src="image.jpg" alt="Description">
+</div>
+```
+
+**States:**
+- Default: Blurred with "18+ Click to View" overlay
+- `.revealed`: Blur removed, overlay hidden
+
+**JavaScript API:**
+```javascript
+const gallery = initGallery('#gallery', {
+  enableNsfw: true,
+  nsfwWarning: 'Click to View',
+  onNsfwReveal: (element) => console.log('Revealed:', element)
+});
+
+// Manual reveal
+gallery.revealNsfw(element);
+```
+
+---
+
+### Social Links List
+
+Link-in-bio style layout for social profiles.
+
+```html
+<div class="social-links-container">
+  <img src="avatar.jpg" alt="Profile" class="profile-avatar">
+  <h1 class="profile-name">@username</h1>
+  <p class="profile-bio">Your bio text here.</p>
+  
+  <div class="link-list">
+    <!-- Platform-specific hover colors -->
+    <a href="#" class="link-item twitter">
+      <i class="fab fa-twitter"></i> Twitter
+    </a>
+    <a href="#" class="link-item instagram">
+      <i class="fab fa-instagram"></i> Instagram
+    </a>
+    <a href="#" class="link-item youtube">
+      <i class="fab fa-youtube"></i> YouTube
+    </a>
+    <a href="#" class="link-item github">
+      <i class="fab fa-github"></i> GitHub
+    </a>
+    <a href="#" class="link-item discord">
+      <i class="fab fa-discord"></i> Discord
+    </a>
+    <a href="#" class="link-item twitch">
+      <i class="fab fa-twitch"></i> Twitch
+    </a>
+    <!-- Default accent color -->
+    <a href="#" class="link-item">
+      <i class="fas fa-globe"></i> Website
+    </a>
+  </div>
+</div>
+```
+
+**Avatar Sizes:**
+- `.profile-avatar.sm` - 100px diameter
+- `.profile-avatar` - 140px diameter (default)
+- `.profile-avatar.lg` - 180px diameter
+
+**Platform Classes:**
+Each platform class applies branded hover colors:
+- `.twitter` - Twitter blue
+- `.instagram` - Instagram gradient
+- `.youtube` - YouTube red
+- `.github` - GitHub dark
+- `.discord` - Discord purple
+- `.twitch` - Twitch purple
+
+---
+
+### Countdown Widget
+
+Event countdown with configurable shapes and animations.
+
+**HTML Container:**
+```html
+<div id="countdown-widget"></div>
+```
+
+**JavaScript Initialization:**
+```javascript
+import { initCountdown } from '@whykusanagi/corrupted-theme/countdown';
+
+// Inline configuration
+initCountdown({
+  config: {
+    title: 'Product Launch',
+    eventDate: '2025-04-01T00:00:00-07:00',
+    completedMessage: 'Now Available!',
+    character: {
+      image: 'character.png',
+      rotation: 0,
+      background: {
+        type: 'diamond',
+        color: 'radial-gradient(circle, rgba(54, 83, 161, 0.6), rgba(217, 79, 144, 0.6))',
+        borderColor: '#4c2967'
+      },
+      overlay: {
+        image: 'overlay.png',
+        position: 'behind',
+        animation: 'float'
+      }
+    },
+    popup: {
+      message: '<strong>Pre-order now!</strong>',
+      frequency: 15000,
+      duration: 5000
+    }
+  }
+});
+
+// Or load from JSON via URL parameter
+// Access: page.html?event=kirara loads /data/countdown/kirara.json
+initCountdown();
+```
+
+**Shape Types:**
+- `diamond` - Rotated square (default)
+- `circle` - Round container
+- `heart` - Heart shape
+- `star` - 5-point star
+- `hexagon` - 6-sided polygon
+- `octagon` - 8-sided polygon
+
+**Configuration Schema:**
+```javascript
+{
+  title: string,              // Display title
+  eventDate: string,          // ISO 8601 date
+  completedMessage: string,   // Message when countdown ends
+  character: {
+    image: string,            // Image URL
+    rotation: number,         // Degrees (0-360)
+    objectPosition: string,   // CSS object-position
+    background: {
+      type: string,           // Shape type
+      color: string,          // CSS background
+      borderColor: string     // Hex color
+    },
+    overlay: {
+      image: string,          // Overlay image URL
+      position: 'behind'|'front',
+      animation: 'float'|null,
+      rotation: number
+    }
+  },
+  popup: {
+    message: string,          // HTML content
+    frequency: number,        // Ms between popups
+    duration: number,         // Ms popup visible
+    colors: {
+      bg: string,
+      border: string,
+      text: string
+    }
+  }
+}
+```
+
+**CSS Classes:**
+- `.countdown-container` - Main wrapper (600×600px)
+- `.shape-container` - Shape wrapper (375×375px)
+- `.shape-container.diamond|circle|heart|star|hexagon|octagon`
+- `.countdown-box` - Timer display
+- `.countdown-popup` - Popup message
+- `.countdown-character` - Character image
+- `.countdown-overlay-wrapper` - Overlay container
+
+---
+
 ## Related Documentation
 
-- [VARIABLES_REFERENCE.md](./VARIABLES_REFERENCE.md) - Complete CSS variables reference
-- [NIKKE_COMPONENTS.md](./NIKKE_COMPONENTS.md) - Nikke-specific components
-- [CUSTOMIZATION.md](./CUSTOMIZATION.md) - Customization guide
-- [ACCESSIBILITY.md](./ACCESSIBILITY.md) - Accessibility standards
+- [README.md](../README.md) - Main documentation and quick start guide
+- [Variables Reference](#customization) - CSS variables for customization (see Customization section above)
+- [Nikke Components](#nikke-components) - Game-specific components (see section above)
 
 ---
 
-**Last Updated:** 2025-11-24  
-**Version:** 1.0  
+**Last Updated:** 2025-11-26  
+**Version:** 1.1  
 **Status:** Complete and Production Ready