From 527db4a65a0f50e87cba4abcbba7d1b5b92902c1 Mon Sep 17 00:00:00 2001 From: whyKusanagi Date: Mon, 18 May 2026 01:14:51 -0700 Subject: [PATCH 1/6] docs: overhaul README for 0.2.0 - Add CDN Distribution section (cdn.whykusanagi.xyz + cdn.nikkers.cc) - Add Canonical Data section (src/data/ JSON, 6-pool context API) - Add Container Layout BREAKING-change callout + migration link - Add NSFW option canonicalization note - Expand Component Quick Reference with 19 new component subsections (Toast, ClockWidget, EventBar, LogoBanner, Lightbox, NsfwReveal, PngExport, WebSocketManager, CorruptionManager, CRTEffects, 10 animation-blocks classes, CorruptionCharsets, CorruptedParticlesBackground, plus core utilities) - Update CSS & JS Imports to list new modules - Update Table of Contents - Preserve existing voice + structure; link out to COMPONENTS_REFERENCE, CDN_CONSUMPTION, MIGRATION_CONTAINER docs instead of inlining API tables Co-Authored-By: Claude Sonnet 4.6 --- README.md | 587 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 520 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 56109b6..c14fb20 100644 --- a/README.md +++ b/README.md @@ -7,22 +7,26 @@ A production-ready glassmorphic design system for cinematic, cyberpunk-inspired ## Table of Contents 1. [Overview](#overview) 2. [Installation](#installation) -3. [Project Architecture](#project-architecture) -4. [Base Layout & Background](#base-layout--background) -5. [CSS & JS Imports](#css--js-imports) -6. [Component Quick Reference](#component-quick-reference) -7. [Interactive Components](#interactive-components) -8. [Animations & Experience Layer](#animations--experience-layer) -9. [Lifecycle Management](#lifecycle-management) -10. [Nikke Utilities](#nikke-utilities) -11. [Extension Components](#extension-components) -12. [Customization & Tokens](#customization--tokens) -13. [Coding Standards](#coding-standards) -14. [Development Workflow](#development-workflow) -15. [Testing & QA Expectations](#testing--qa-expectations) -16. [Support](#support) -17. [Celeste Widget Integration](#celeste-widget-integration-optional) -18. [License](#license) +3. [CDN Distribution](#cdn-distribution) +4. [Project Architecture](#project-architecture) +5. [Container Layout (0.2.0 Breaking Change)](#container-layout-020-breaking-change) +6. [Canonical Data (JSON Source of Truth)](#canonical-data-json-source-of-truth) +7. [NSFW Option Canonicalization](#nsfw-option-canonicalization) +8. [Base Layout & Background](#base-layout--background) +9. [CSS & JS Imports](#css--js-imports) +10. [Component Quick Reference](#component-quick-reference) +11. [Interactive Components](#interactive-components) +12. [Animations & Experience Layer](#animations--experience-layer) +13. [Lifecycle Management](#lifecycle-management) +14. [Nikke Utilities](#nikke-utilities) +15. [Extension Components](#extension-components) +16. [Customization & Tokens](#customization--tokens) +17. [Coding Standards](#coding-standards) +18. [Development Workflow](#development-workflow) +19. [Testing & QA Expectations](#testing--qa-expectations) +20. [Support](#support) +21. [Celeste Widget Integration](#celeste-widget-integration-optional) +22. [License](#license)
@@ -73,54 +77,119 @@ npm install @whykusanagi/corrupted-theme ``` > Tip: make sure you are logged in with `npm login` if the package is private. No `.npmrc` token is needed for the public release. -### CDN (when mirrored) +### CDN ```html - + + + + + ``` +Use `cdn.nikkers.cc` for sites under `nikkers.cc`, and `cdn.whykusanagi.xyz` for sites under `whykusanagi.xyz` — same-origin loads skip CORS and need no extra CSP entries. See [CDN Distribution](#cdn-distribution) and [docs/CDN_CONSUMPTION.md](docs/CDN_CONSUMPTION.md) for full guidance. + ### Manual Copy Copy `src/css` into your project (or use `dist/theme.min.css`) and import it locally. +## CDN Distribution + +corrupted-theme is served from a Cloudflare R2 bucket bound to two domains: + +- **`cdn.whykusanagi.xyz`** — for sites under `whykusanagi.xyz` +- **`cdn.nikkers.cc`** — for sites under `nikkers.cc` + +Both domains serve the same content. Use the domain that matches your site's root to keep the load same-origin, which avoids CORS preflights and simplifies CSP policy. + +**Pinned version** (production-safe — breaking changes never auto-propagate): +```html + + +``` + +**Floating `@latest`** (first-party sites that publish together — updates within ~5 minutes): +```html + +``` + +For production hardening, add SRI hashes (published in `CHANGELOG.md` for each release; regenerate with `npm run generate-sri`). See [docs/CDN_CONSUMPTION.md](docs/CDN_CONSUMPTION.md) for the same-origin rule, CSP guidance, CORS allowlist, and JSON data fetching. + ## Project Architecture ``` . ├── src/ │ ├── css/ -│ │ ├── variables.css # design tokens -│ │ ├── typography.css # font stack + hierarchy -│ │ ├── glassmorphism.css # shared glass utilities -│ │ ├── animations.css # motion + corruption keyframes -│ │ ├── components.css # UI primitives + layouts (incl. carousel) -│ │ ├── utilities.css # spacing, flex, layout utilities -│ │ └── theme.css # entry point (imports all modules) +│ │ ├── variables.css # design tokens +│ │ ├── typography.css # font stack + hierarchy +│ │ ├── glassmorphism.css # glass utilities (dark/subtle/gradient + modifiers) +│ │ ├── animations.css # motion + corruption keyframes (.glitch-word etc.) +│ │ ├── components.css # UI primitives + layouts (incl. carousel) +│ │ ├── utilities.css # spacing, flex, layout utilities +│ │ ├── toast.css # Toast notification styles (0.2.0) +│ │ ├── seamless-background.css # multi-layer parallax tiled background (0.2.0) +│ │ └── theme.css # entry point (imports all modules) +│ ├── data/ # canonical JSON source of truth (0.2.0) +│ │ ├── phrases.json # SFW+NSFW phrases, 6 context pools × 3 languages +│ │ ├── charsets.json # katakana / hiragana / kanji / symbols / blocks +│ │ ├── colors.json # 6-hex palette + semantic-use map +│ │ └── schemas/ # AJV schemas for each JSON file │ ├── core/ -│ │ ├── timer-registry.js # lifecycle: tracked setTimeout/setInterval/rAF -│ │ └── event-tracker.js # lifecycle: tracked addEventListener +│ │ ├── timer-registry.js # lifecycle: tracked setTimeout/setInterval/rAF +│ │ ├── event-tracker.js # lifecycle: tracked addEventListener +│ │ ├── corruption-charsets.js # CorruptionCharsets registry (0.2.0) +│ │ ├── corruption-manager.js # CorruptionManager unified lifecycle (0.2.0) +│ │ ├── websocket-manager.js # WebSocketManager auto-reconnect (0.2.0) +│ │ ├── random-utils.js # randomPick / randomInt / shuffle … (0.2.0) +│ │ ├── time-utils.js # formatTime / timeAgo / formatDuration … (0.2.0) +│ │ ├── clipboard-helpers.js # copyWithFeedback (0.2.0) +│ │ └── url-state.js # serializeFormToParams / buildShareUrl (0.2.0) │ └── lib/ -│ ├── carousel.js # carousel/slideshow with autoplay + swipe -│ ├── celeste-proxy.js # Celeste CLI proxy integration -│ ├── celeste-widget.js # Celeste chat widget -│ ├── character-corruption.js# auto-corruption for individual characters -│ ├── components.js # modal, dropdown, tabs, collapse, accordion, toast -│ ├── corrupted-particles.js # Canvas 2D floating phrase particle background -│ ├── corrupted-text.js # multi-language glitch animation -│ ├── corrupted-vortex.js # WebGL raymarched spiral vortex shader -│ ├── corruption-loading.js # cinematic loading curtain -│ ├── countdown-widget.js # event countdown with shapes -│ └── gallery.js # gallery grid with filtering + lightbox -├── dist/theme.min.css # postcss + cssnano build output +│ ├── animation-blocks.js # 10 block classes: TitleDecoder, ProgressBar … (0.2.0) +│ ├── carousel.js # carousel/slideshow with autoplay + swipe +│ ├── celeste-proxy.js # Celeste CLI proxy integration +│ ├── celeste-widget.js # Celeste chat widget +│ ├── character-corruption.js # auto-corruption for individual characters +│ ├── clock-widget.js # multi-timezone cycling clock (0.2.0) +│ ├── components.js # modal, dropdown, tabs, collapse, accordion, toast +│ ├── corrupted-particles-background.js # auto-injector background particles (0.2.0) +│ ├── corrupted-particles.js # Canvas 2D floating phrase particle background +│ ├── corrupted-text.js # multi-language glitch animation +│ ├── corrupted-vortex.js # WebGL raymarched spiral vortex shader +│ ├── corruption-loading.js # cinematic loading curtain +│ ├── countdown-widget.js # event countdown with shapes +│ ├── crt-effects.js # CRT post-processing layer (0.2.0) +│ ├── event-bar.js # scrolling event-ticker banner (0.2.0) +│ ├── gallery.js # gallery grid with filtering + lightbox +│ ├── lightbox.js # standalone lightbox (extracted 0.2.0) +│ ├── logo-banner.js # animated logo/title banner (0.2.0) +│ ├── nsfw-reveal.js # age-gate click-to-reveal overlay (0.2.0) +│ ├── png-export.js # exportElementAsPng (html2canvas peer dep, 0.2.0) +│ └── toast.js # Toast singleton (0.2.0) +├── dist/ +│ ├── theme.min.css # postcss + cssnano build output +│ └── timer-registry.global.js # UMD build for IIFE contexts (0.2.0) +├── cdn-worker/ # Cloudflare Worker for @latest CDN routing (0.2.0) ├── examples/ -│ ├── showcase-complete.html # full design system demo -│ ├── interactive-components.html # modal, dropdown, tabs, carousel demo +│ ├── showcase-complete.html # full design system demo +│ ├── interactive-components.html # modal, dropdown, tabs, carousel demo │ ├── basic/ -│ │ ├── corrupted-text.html # CorruptedText demo -│ │ ├── multi-gallery.html # multi-instance gallery demo -│ │ └── typing-animation.html # TypingAnimation demo +│ │ ├── corrupted-text.html # CorruptedText demo +│ │ ├── multi-gallery.html # multi-instance gallery demo +│ │ └── typing-animation.html # TypingAnimation demo (with NSFW toggle) │ └── advanced/ -│ ├── glsl-vortex.html # CorruptedVortex WebGL demo -│ └── particles-bg.html # CorruptedParticles demo -├── scripts/static-server.js # ESM static server (Docker) -└── docs/COMPONENTS_REFERENCE.md # exhaustive snippets +│ ├── glsl-vortex.html # CorruptedVortex WebGL demo +│ └── particles-bg.html # CorruptedParticles demo +├── scripts/static-server.js # ESM static server (Docker) +└── docs/ + ├── COMPONENTS_REFERENCE.md # exhaustive component snippets (28+ entries) + ├── CDN_CONSUMPTION.md # CDN setup, same-origin rule, SRI, CSP + ├── CROSS_LANGUAGE_CONTRACT.md # phrases/charsets JSON schema + Go embed guide + ├── MIGRATION_CONTAINER_0.2.0.md # .container breaking change migration guide + └── governance/ # versioning, design governance, contribution guides ``` **npm scripts** @@ -128,6 +197,76 @@ Copy `src/css` into your project (or use `dist/theme.min.css`) and import it loc - `npm run watch` – rebuilds on change (dev use) - `npm run dev:static` – serves `/examples` (port 8000) - `npm run dev:proxy` – Celeste proxy (port 5000) +- `npm run validate-data` – AJV schema validation for `src/data/*.json` (0.2.0) +- `npm run generate-sri` – generate SRI hashes for CDN consumers (0.2.0) +- `npm run publish-cdn` – upload `dist/` + `src/data/` to R2, bump `@latest` pointer (0.2.0) + +## Container Layout (0.2.0 Breaking Change) + +> **Breaking change.** The `.container` class is now structural-only in 0.2.0 — it applies `max-width`, `margin-inline: auto`, and horizontal padding, but **no grid layout**. Sites that previously relied on the implicit grid behavior must add a modifier class. + +```css +/* 0.2.0 — base is structural only */ +.container { max-width: 1200px; margin-inline: auto; padding-inline: 1rem; } + +/* Opt-in modifiers */ +.container--grid-2col { display: grid; grid-template-columns: 1fr 1fr; gap: 2rem; } +.container--grid-3col { display: grid; grid-template-columns: repeat(3,1fr); gap: 2rem; } +.container--with-bg { background: var(--glass); border: 1px solid var(--border); border-radius: var(--radius-2xl); backdrop-filter: blur(15px); } +.container--fullscreen { max-width: none; min-height: 100vh; } +.container--centered { display: flex; flex-direction: column; align-items: center; justify-content: center; } +``` + +**Migration:** If you were forcing a 2-column grid, add `container--grid-2col`. If you had workaround rules that `unset`-ed `.container`, remove them — the base no longer fights downstream layouts. Pin to `^0.1.9` in the meantime if you cannot migrate yet. + +See [docs/MIGRATION_CONTAINER_0.2.0.md](docs/MIGRATION_CONTAINER_0.2.0.md) for the full guide. + +## Canonical Data (JSON Source of Truth) + +0.2.0 introduces a `src/data/` layer that all internal corruption modules (and downstream Go consumers via `go:embed`) read from instead of maintaining inline arrays: + +| File | Contents | +|------|----------| +| `src/data/phrases.json` | SFW + NSFW phrases across 6 context pools (`data`, `system`, `status`, `void`, `memory`, `glitch`) × 3 languages | +| `src/data/charsets.json` | katakana, hiragana, kanji, symbols, blocks | +| `src/data/colors.json` | 6-hex palette + semantic-use map | + +The context-aware phrase API: + +```js +import { getPhraseByContext } from '@whykusanagi/corrupted-theme/corruption-phrases'; + +// Pick a phrase from a specific context pool +const phrase = getPhraseByContext('system', false); // SFW system pool +const nsfw = getPhraseByContext('void', true); // NSFW void pool + +// Or consume the JSON directly +import phrases from '@whykusanagi/corrupted-theme/data/phrases.json' with { type: 'json' }; +const pool = phrases.sfw.japanese.status; +``` + +Each file has a `schemaVersion` field. Additive changes (new pool, new charset) bump the minor version; breaking changes bump the major version. Run `npm run validate-data` to verify the JSON against AJV schemas before publishing. + +See [docs/CROSS_LANGUAGE_CONTRACT.md](docs/CROSS_LANGUAGE_CONTRACT.md) for the Go `go:embed` integration guide and stability guarantees. + +## NSFW Option Canonicalization + +**0.2.0 canonicalizes the NSFW option name to `nsfw` across all components.** The previous per-component names are deprecated aliases that emit a one-time `console.warn` and will be removed in 0.3.x. + +| Component | Old (deprecated) | New (canonical) | +|-----------|-----------------|-----------------| +| `CorruptedParticles` | `includeLewd` | `nsfw` | +| `animation-blocks` | `lewdMode` | `nsfw` | +| `TypingAnimation` | `nsfw` | `nsfw` (unchanged) | +| `CorruptionManager` | — | `nsfw` | + +```js +// Correct — all components now use the same option name +new CorruptedParticles(canvas, { nsfw: false }); // was: { includeLewd: false } +new TitleDecoder(el, { nsfw: false }); // was: { lewdMode: false } +``` + +**All defaults are `nsfw: false`.** Opt-in to NSFW content only in 18+ or explicit-consent contexts. ## Base Layout & Background @@ -231,12 +370,15 @@ Import only the modules you need for smaller bundle sizes. #### CSS @import Syntax ```css /* Correct order (matches theme.css structure) */ -@import '@whykusanagi/corrupted-theme/variables'; /* 1. Foundation tokens */ -@import '@whykusanagi/corrupted-theme/typography'; /* 2. Font styles */ -@import '@whykusanagi/corrupted-theme/glassmorphism'; /* 3. Glass effects */ -@import '@whykusanagi/corrupted-theme/animations'; /* 4. Keyframes - MUST come before components */ -@import '@whykusanagi/corrupted-theme/components'; /* 5. UI components - MUST come after animations */ -@import '@whykusanagi/corrupted-theme/utilities'; /* 6. Utility classes */ +@import '@whykusanagi/corrupted-theme/variables'; /* 1. Foundation tokens */ +@import '@whykusanagi/corrupted-theme/typography'; /* 2. Font styles */ +@import '@whykusanagi/corrupted-theme/glassmorphism'; /* 3. Glass effects */ +@import '@whykusanagi/corrupted-theme/animations'; /* 4. Keyframes - MUST come before components */ +@import '@whykusanagi/corrupted-theme/components'; /* 5. UI components - MUST come after animations */ +@import '@whykusanagi/corrupted-theme/utilities'; /* 6. Utility classes */ +/* 0.2.0 additions (opt-in) */ +@import '@whykusanagi/corrupted-theme/toast-css'; /* Toast notification styles */ +@import '@whykusanagi/corrupted-theme/seamless-background';/* Parallax tiled background */ ``` #### HTML Link Tags @@ -269,6 +411,34 @@ import { initCarousel } from '@whykusanagi/corrupted-theme/carousel'; import { initCorruptedText } from '@whykusanagi/corrupted-theme/corrupted-text'; import { initGallery, destroyGallery } from '@whykusanagi/corrupted-theme/gallery'; import { initCountdown } from '@whykusanagi/corrupted-theme/countdown'; + +// 0.2.0 — Drift reconvergence (canonical corruption layer) +import { CorruptionCharsets } from '@whykusanagi/corrupted-theme/corruption-charsets'; +import { CorruptionManager, decodeText, phraseFlicker, hybridDecode } + from '@whykusanagi/corrupted-theme/corruption-manager'; +import { CRTEffects, applyCRTGlow } from '@whykusanagi/corrupted-theme/crt-effects'; +import { TitleDecoder, ProgressBar, ScanlineSweep, TerminalBoot, GlitchPulse, + ASCIIBorder, SystemDiagnostic, LoadingBarMulti, DataTransmission, TerminalPrompt, + playParallel, playSequence, playStaggered } + from '@whykusanagi/corrupted-theme/animation-blocks'; +import CorruptedParticlesBackground + from '@whykusanagi/corrupted-theme/corrupted-particles-background'; + +// 0.2.0 — Widgets +import { Toast } from '@whykusanagi/corrupted-theme/toast'; +import { ClockWidget } from '@whykusanagi/corrupted-theme/clock-widget'; +import { EventBar } from '@whykusanagi/corrupted-theme/event-bar'; +import { LogoBanner } from '@whykusanagi/corrupted-theme/logo-banner'; +import { Lightbox } from '@whykusanagi/corrupted-theme/lightbox'; +import { NsfwReveal } from '@whykusanagi/corrupted-theme/nsfw-reveal'; +import { exportElementAsPng } from '@whykusanagi/corrupted-theme/png-export'; +import { WebSocketManager } from '@whykusanagi/corrupted-theme/websocket-manager'; + +// 0.2.0 — Core utilities +import { randomPick, randomInt, shuffle } from '@whykusanagi/corrupted-theme/random-utils'; +import { formatTime12h, timeAgo } from '@whykusanagi/corrupted-theme/time-utils'; +import { copyWithFeedback } from '@whykusanagi/corrupted-theme/clipboard-helpers'; +import { buildShareUrl, applyParamsToForm } from '@whykusanagi/corrupted-theme/url-state'; ``` Components auto-initialize on `DOMContentLoaded` when imported. For manual control: @@ -454,6 +624,286 @@ typing.start('Neural corruption detected... System Online'); See `examples/basic/typing-animation.html` — it has a toggle switch at the top to opt into NSFW phrases (checkbox resets each page load per the explicit-opt-in spec). +### Drift Reconvergence — Canonical Corruption Layer (0.2.0) + +#### CorruptionCharsets + +Named charset registry backed by `src/data/charsets.json`. + +```js +import { CorruptionCharsets } from '@whykusanagi/corrupted-theme/corruption-charsets'; + +CorruptionCharsets.katakana; // primary corruption glyphs +CorruptionCharsets.standard; // katakana + symbols (matrix-style) +CorruptionCharsets.soft; // hiragana only (gentle degradation) +CorruptionCharsets.intense; // kanji + blocks (heavy data-loss) +CorruptionCharsets.all; // union of every set +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#corruptioncharsets) for all sets. + +#### CorruptionManager + +Unified lifecycle runner for all three canonical corruption patterns. + +```js +import { CorruptionManager } from '@whykusanagi/corrupted-theme/corruption-manager'; + +const mgr = new CorruptionManager({ nsfw: false }); + +mgr.decode(el, 'SYSTEM READY', { duration: 2000 }); // Pattern 1 +mgr.flicker(el, ['アイウエオ', '██████'], { duration: 3000 }); // Pattern 2 +mgr.hybrid(el, ['CORRUPTION'], 'SIGNAL RESTORED', {}); // Pattern 3 +mgr.stop(); // cancel all +mgr.destroy(); // full teardown +``` + +One-shot helpers (no instance needed): `decodeText`, `phraseFlicker`, `hybridDecode` — each returns a cancel function. + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#corruptionmanager) for full method table. + +#### CRTEffects + +CRT post-processing layer — scanlines, vignette, chromatic aberration, RGB split, screen shake. + +```js +import { CRTEffects } from '@whykusanagi/corrupted-theme/crt-effects'; + +const crt = new CRTEffects(containerEl, { scanlines: true, vignette: true, flicker: false }); +crt.start(); +crt.screenShake(containerEl, 300, 5); // duration ms, intensity px +crt.destroy(); +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#crteffects) for the full options table. + +#### animation-blocks (10 classes) + +Composable animation blocks that return Promises. Mix with `playParallel` / `playSequence` / `playStaggered`. + +```js +import { + TitleDecoder, ProgressBar, ScanlineSweep, TerminalBoot, GlitchPulse, + ASCIIBorder, SystemDiagnostic, LoadingBarMulti, DataTransmission, TerminalPrompt, + playSequence, +} from '@whykusanagi/corrupted-theme/animation-blocks'; + +await playSequence([ + new TitleDecoder(el, { text: 'CORRUPTED STREAM', nsfw: false }), + new ProgressBar(el, { label: 'Loading...', duration: 2000 }), + new TerminalBoot(el, { lines: ['Initializing...', 'Ready.'] }), +]); +``` + +> `lewdMode` is a deprecated alias for `nsfw` — use `nsfw: true` in new code. + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#animation-blocks) for all 10 class descriptions. + +#### CorruptedParticlesBackground + +Auto-injecting background particles (DPR=1 performance mode, sits behind blur layers). + +```js +import CorruptedParticlesBackground from '@whykusanagi/corrupted-theme/corrupted-particles-background'; + +const bg = new CorruptedParticlesBackground({ nsfw: false, count: 25 }); +// automatically inserts a fixed canvas before .glass-backdrop +bg.destroy(); +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#corruptedparticlesbackground). + +### Widgets (0.2.0) + +#### Toast + +Singleton notification helper. Auto-mounts its own DOM container on first use. + +```js +import { Toast } from '@whykusanagi/corrupted-theme/toast'; + +Toast.show('Saved'); +Toast.success('Submitted!', { duration: 3000 }); +Toast.error('Upload failed'); +Toast.info('Loading…'); +``` + +Import `@whykusanagi/corrupted-theme/toast-css` alongside (or include in your `theme.css` build). See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#toast). + +#### ClockWidget + +Cycling multi-timezone clock using `Intl.DateTimeFormat` for DST correctness. + +```js +import { ClockWidget } from '@whykusanagi/corrupted-theme/clock-widget'; + +const widget = new ClockWidget(document.getElementById('clock'), { + timezones: ['America/Los_Angeles', 'Europe/London'], + cycleMs: 10000, + format: '12h', +}); +widget.start(); +widget.destroy(); +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#clockwidget). + +#### EventBar + +Scrolling event-ticker banner with label + content + optional icon. Supports live `update()`. + +```js +import { EventBar } from '@whykusanagi/corrupted-theme/event-bar'; + +const eb = new EventBar(document.getElementById('events'), { + items: [{ label: 'Latest Follow', content: '@user1', icon: '★' }], +}); +eb.update([{ label: 'Latest Tip', content: '$10.00', icon: '✦' }]); +eb.destroy(); +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#eventbar). + +#### LogoBanner + +Animated logo/title banner with five position presets and reveal animation. + +```js +import { LogoBanner } from '@whykusanagi/corrupted-theme/logo-banner'; + +const banner = new LogoBanner(el, { + src: '/assets/logo.png', subtitle: 'LIVE', position: 'top-right', animation: 'fade', +}); +banner.show(); +banner.update({ position: 'center' }); +banner.destroy(); +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#logobanner). + +#### Lightbox (standalone) + +Extracted from `gallery.js` as its own module. Keyboard (Escape/arrows) + touch-swipe. `gallery.js` re-exports it for backward compat. + +```js +import { Lightbox } from '@whykusanagi/corrupted-theme/lightbox'; + +const lb = new Lightbox(null, { onOpen: (img, i) => {}, onClose: () => {} }); +lb.setImages([{ src: 'a.jpg', alt: 'A', caption: 'Caption' }]); +lb.open(0); +lb.destroy(); +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#lightbox-standalone). + +#### NsfwReveal + +Age-gate blur overlay with click-to-reveal. Session persistence handled by the caller. + +```js +import { NsfwReveal } from '@whykusanagi/corrupted-theme/nsfw-reveal'; + +const nr = new NsfwReveal(document.getElementById('img'), { + warning: 'NSFW — click to reveal', + blurPx: 20, +}); +nr.reveal(); // programmatic reveal +nr.destroy(); // restore original state +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#nsfwreveal). + +#### PngExport + +Capture a DOM element as PNG and trigger a download. Requires optional peer dep `html2canvas`. + +```js +import { exportElementAsPng } from '@whykusanagi/corrupted-theme/png-export'; + +await exportElementAsPng(document.getElementById('card'), { + filename: 'my-card.png', + scale: 2, +}); +``` + +Install the peer dep only when using: `npm install html2canvas`. See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#pngexport). + +#### WebSocketManager + +Auto-reconnect WebSocket wrapper with exponential backoff (capped 30s), event-ID dedup, ACK support, and visibility-aware pause/resume. + +```js +import { WebSocketManager } from '@whykusanagi/corrupted-theme/websocket-manager'; + +const ws = new WebSocketManager({ url: 'wss://your-server/ws', autoConnect: false }); +ws.on((msg) => console.log(msg)); +ws.connect(); +ws.destroy(); +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#websocketmanager) for all options. + +### Core Utilities (0.2.0) + +All utility modules are pure functions with no DOM dependency — safe in Node.js and SSR contexts. + +#### random-utils +```js +import { randomPick, randomInt, randomFloat, randomVariance, shuffle, randomSample } + from '@whykusanagi/corrupted-theme/random-utils'; + +randomPick(['a', 'b', 'c']); // random element +randomVariance(50, 0.2); // 50 ± 20% +shuffle([1, 2, 3]); // Fisher-Yates in-place +randomSample([1,2,3,4], 2); // 2 elements without replacement +``` + +#### time-utils +```js +import { formatTime12h, formatDate, timeAgo, formatDuration } + from '@whykusanagi/corrupted-theme/time-utils'; + +formatTime12h(); // "02:32 PM" +timeAgo(new Date(Date.now() - 3e5)); // "5m ago" +formatDuration(3661); // "1h 1m 1s" (input: seconds) +``` + +#### clipboard-helpers +```js +import { copyWithFeedback } from '@whykusanagi/corrupted-theme/clipboard-helpers'; + +await copyWithFeedback(btn, 'text to copy', { successLabel: 'COPIED!', durationMs: 1200 }); +// Button label briefly becomes "COPIED!" then reverts. Returns Promise. +``` + +#### url-state +```js +import { buildShareUrl, applyParamsToForm } from '@whykusanagi/corrupted-theme/url-state'; + +const url = buildShareUrl(form, 'https://example.com/embed'); +// → "https://example.com/embed?username=alice&dark=1" +applyParamsToForm(form, new URLSearchParams(window.location.search)); +``` + +### CSS Utilities (0.2.0) + +**`.scrollbar-corrupted`** — styled scrollbar (Firefox + WebKit) matching the theme accent colors. Apply to any scrollable container: + +```html +
…
+``` + +**`seamless-background.css`** — multi-layer parallax tiled background. Import the CSS module, add `.seamless-bg-host` to a parent, and set the `--seamless-background-image` variable: + +```html + +
+ + +``` + +See [COMPONENTS_REFERENCE.md](docs/COMPONENTS_REFERENCE.md#seamless-backgroundcss) for the full modifier class list. + ## Interactive Components v0.1.8 adds JS-driven interactive components that self-initialize via `data-ct-*` attributes. Import the components module and everything wires up automatically on `DOMContentLoaded`. @@ -620,22 +1070,22 @@ typing.settle(); // resolve to final text **CorruptedParticles** - Canvas 2D Floating Phrase Background - Floating Japanese phrase particles across three depth layers - Mouse hover repel, click burst (6 particles), connection lines between nearby particles -- SFW/NSFW phrase modes with `includeLewd` toggle +- SFW/NSFW phrase modes via `nsfw` toggle (`includeLewd` is a deprecated alias) - Demo: `examples/advanced/particles-bg.html` ```js import CorruptedParticles from '@whykusanagi/corrupted-theme/corrupted-particles'; const particles = new CorruptedParticles(canvas, { - count: 60, // number of particles - speed: 1.0, // global speed multiplier - lineDistance: 150, // max distance for connection lines (px) - includeLewd: false // enable 18+ phrases (default: off) + count: 60, // number of particles + speed: 1.0, // global speed multiplier + lineDistance: 150, // max distance for connection lines (px) + nsfw: false // enable 18+ phrases (default: off) }); // auto-starts on construction -particles.stop(); // pause animation -particles.start(); // resume -particles.destroy(); // full teardown +particles.stop(); // pause animation +particles.start(); // resume +particles.destroy(); // full teardown ``` **CorruptedVortex** - WebGL Raymarched Spiral Vortex @@ -890,11 +1340,14 @@ These guidelines keep contributions aligned with enterprise frameworks: ## Development Workflow ```bash -npm install # install dependencies -npm run build # compile CSS bundle -npm run watch # dev rebuild loop -npm run dev:static # serve /examples on :8000 -npm run dev:proxy # optional Celeste proxy on :5000 +npm install # install dependencies +npm run build # compile CSS bundle +npm run watch # dev rebuild loop +npm run dev:static # serve /examples on :8000 +npm run dev:proxy # optional Celeste proxy on :5000 +npm run validate-data # AJV schema validation for src/data/*.json +npm run generate-sri # generate SRI hashes for CDN consumers +npm run publish-cdn # upload dist/ + src/data/ to R2, bump @latest pointer # Docker showcase docker build -t corrupted-theme:latest . From ef7a4b73615b45108ef9029ee4d7c881b4b517a3 Mon Sep 17 00:00:00 2001 From: whyKusanagi Date: Mon, 18 May 2026 01:27:11 -0700 Subject: [PATCH 2/6] docs: update demo pages for 0.2.0 components - index.html (live site at corrupted.whykusanagi.xyz): add "0.2.0 New Components" card to Explore grid + "0.2.0 Examples" quick-links section covering all 8 new example pages. Add CDN install option to Quick Install block. - examples/index.html: same updates as root index (relative paths). - examples/showcase.html: add "0.2.0 New Components" banner section after hero with btn links to all 8 new examples. Extend nav Examples submenu with Animation Blocks, CRT Effects, Corruption Manager, and Widgets Showcase entries. - examples/showcase-complete.html: add "#v020-components" section with glass-card tiles for all 8 new components (Animation Blocks, CRT Effects, Corruption Manager, Particles Background, Widgets Showcase, Utilities, PNG Export, WebSocket Manager). Add nav anchor and Examples submenu entries. Co-Authored-By: Claude Sonnet 4.6 --- examples/index.html | 66 ++++++++++++++++++++++- examples/showcase-complete.html | 96 +++++++++++++++++++++++++++++++++ examples/showcase.html | 23 ++++++++ index.html | 66 ++++++++++++++++++++++- 4 files changed, 249 insertions(+), 2 deletions(-) diff --git a/examples/index.html b/examples/index.html index e2a1470..2eff16f 100644 --- a/examples/index.html +++ b/examples/index.html @@ -541,6 +541,9 @@

Quick Install

+
+ Or via CDN: <link rel="stylesheet" href="https://cdn.whykusanagi.xyz/corrupted-theme/@latest/dist/theme.min.css"> +
@@ -654,13 +657,74 @@

Nikke Components

Animations & Effects

- Corruption loading screens, glitch text effects, multi-language animations, + Corruption loading screens, glitch text effects, multi-language animations, syntax highlighting, and motion utilities.

See animations
+ + + +
+ +
+

+ 0.2.0 New Components + New +

+

+ Animation Blocks, CRT Effects, Corruption Manager, Particles Background, + Widgets Showcase, Utilities, PNG Export, and WebSocket demo. +

+
+ Explore 0.2.0 +
+ + + + + +
+
+

0.2.0 Examples

+

New components and demos added in this release

+
+ +
+ + + Animation Blocks + + + + CRT Effects + + + + Corruption Manager + + + + Particles Background + + + + Widgets Showcase + + + + Utilities + + + + PNG Export + + + + WebSocket Demo +
diff --git a/examples/showcase-complete.html b/examples/showcase-complete.html index 0a29ca3..64dbd3c 100644 --- a/examples/showcase-complete.html +++ b/examples/showcase-complete.html @@ -133,6 +133,7 @@ Nikke Corrupted Backgrounds + 0.2.0 New
  • Extensions
    • @@ -149,6 +150,10 @@ Layouts Character Corruption Buffer Corruption + Animation Blocks + CRT Effects + Corruption Manager + Widgets Showcase
  • Docs
    • @@ -1669,6 +1674,97 @@

    Screen Reader Onl + +
    +

    0.2.0 New Components

    +

    + Standalone demo pages for all new components added in the 0.2.0 release. Each page is + self-contained and fully documented. +

    + +
    + + +

    Animation Blocks

    +

    + 10 terminal-style animation classes: TitleDecoder, ProgressBar, ScanlineSweep, TerminalBoot, + GlitchPulse, ASCIIBorder, SystemDiagnostic, LoadingBarMulti, DataTransmission, TerminalPrompt. +

    + View demo +     + + + +

    CRT Effects

    +

    + Full CRT post-processing layer with scanlines, vignette, phosphor glow, and + .glitch-word / .glitch-kanji keyframe utilities. +

    + View demo +     + + + +

    Corruption Manager

    +

    + Lifecycle-managed multi-animation runner. Coordinates multiple concurrent corruption + effects with start/stop/destroy hooks and IntersectionObserver-based activation. +

    + View demo +     + + + +

    Particles Background

    +

    + Canvas 2D floating Japanese phrase background with 3 depth layers, hover repel, + click burst, phrase flickering, and connection lines. includeLewd: false by default. +

    + View demo +     + + + +

    Widgets Showcase

    +

    + Toast notifications (singleton), ClockWidget, NsfwReveal overlay, event-bar, + logo-banner, and other reusable widget components. +

    + View demo +     + + + +

    Utilities

    +

    + random-utils, time-utils, clipboard-helpers, url-state, and seamless-bg CSS utilities. + Modular helpers for common tasks with zero external dependencies. +

    + View demo +     + + + +

    PNG Export

    +

    + html2canvas-backed PNG snapshot utility. Export any DOM element as a high-quality PNG + with one function call. Peer dependency on html2canvas. +

    + View demo +     + + + +

    WebSocket Manager

    +

    + Reconnecting WebSocket wrapper with exponential backoff, event bus, and + typed message dispatching. Fully self-contained, no runtime dependencies. +

    + View demo +     +
    +
    +

    Background Images

    diff --git a/examples/showcase.html b/examples/showcase.html index 959f5ad..efa0353 100644 --- a/examples/showcase.html +++ b/examples/showcase.html @@ -151,6 +151,10 @@ Layouts Character Corruption Buffer Corruption + Animation Blocks + CRT Effects + Corruption Manager + Widgets Showcase
  • Docs
    • @@ -168,6 +172,25 @@

    Corrupted Theme

    + +
    +

    0.2.0 New Components

    +

    + New in this release: Animation Blocks, CRT Effects, Corruption Manager, Particles Background, + Widgets Showcase, Utilities, PNG Export, and WebSocket Manager. +

    +
    + Animation Blocks + CRT Effects + Corruption Manager + Particles Background + Widgets Showcase + Utilities + PNG Export + WebSocket Demo +
    +
    +

    Glass Components

    diff --git a/index.html b/index.html index c040087..373309b 100644 --- a/index.html +++ b/index.html @@ -522,6 +522,9 @@

    Quick Install

    +
    + Or via CDN: <link rel="stylesheet" href="https://cdn.whykusanagi.xyz/corrupted-theme/@latest/dist/theme.min.css"> +
    @@ -617,13 +620,74 @@

    Nikke Components

    Animations & Effects

    - Corruption loading screens, glitch text effects, multi-language animations, + Corruption loading screens, glitch text effects, multi-language animations, syntax highlighting, and motion utilities.

    See animations
    + + + +
    + +
    +

    + 0.2.0 New Components + New +

    +

    + Animation Blocks, CRT Effects, Corruption Manager, Particles Background, + Widgets Showcase, Utilities, PNG Export, and WebSocket demo. +

    +
    + Explore 0.2.0 +
    +     + +
    + + +
    +
    +

    0.2.0 Examples

    +

    New components and demos added in this release

    +
    + +
    + + + Animation Blocks + + + + CRT Effects + + + + Corruption Manager + + + + Particles Background + + + + Widgets Showcase + + + + Utilities + + + + PNG Export + + + + WebSocket Demo +
    From 739924fa176620214ba2530c8dec95203ebcb43e Mon Sep 17 00:00:00 2001 From: whyKusanagi Date: Mon, 18 May 2026 01:32:36 -0700 Subject: [PATCH 3/6] docs: update components/ for 0.2.0 (JS lib inventory, CRT effects, glassmorphism variants) - COMPONENT_LIBRARY: add 0.2.0 JS library section (19 new components across animation-blocks, crt-effects, widgets, utilities); bump web component total to 75; link COMPONENTS_REFERENCE for full APIs - ANIMATION_GUIDELINES: add CRT effects section (.glitch-word, .glitch-kanji, scanline-movement/crt-flicker keyframes, CRTEffects class); bump version to 0.2.0 - GLASSMORPHISM: add 0.2.0 container variant section (.glass-container-dark/subtle/gradient/animated, color modifiers -cyan/-purple/-magenta, @supports fallback); bump version to 0.2.0 Co-Authored-By: Claude Sonnet 4.6 --- docs/components/ANIMATION_GUIDELINES.md | 66 +++++++++++++++++++++++-- docs/components/COMPONENT_LIBRARY.md | 63 +++++++++++++++++++++-- docs/components/GLASSMORPHISM.md | 49 ++++++++++++++++-- 3 files changed, 166 insertions(+), 12 deletions(-) diff --git a/docs/components/ANIMATION_GUIDELINES.md b/docs/components/ANIMATION_GUIDELINES.md index de6fbd5..b7595ab 100644 --- a/docs/components/ANIMATION_GUIDELINES.md +++ b/docs/components/ANIMATION_GUIDELINES.md @@ -2,8 +2,8 @@ > **Celeste Brand System** | Component Documentation > **Document**: Animation Guidelines -> **Version**: 1.0.0 -> **Last Updated**: 2025-12-13 +> **Version**: 0.2.0 +> **Last Updated**: 2026-05-18 --- @@ -476,6 +476,62 @@ Multi-layer glitch effect for error states or brand moments: --- +## CRT Effects & Advanced Glitch Keyframes (0.2.0) + +### CSS Classes + +Two new CSS classes ship in `src/css/animations.css` as of 0.2.0: + +#### `.glitch-word` + +Inline RGB-split glitch effect driven by CSS pseudo-elements. Activates on hover. + +```html +CORRUPTED +``` + +```css +/* Defined in animations.css — activated on :hover */ +.glitch-word { position: relative; } +.glitch-word::before { color: #d94f90; /* pink channel */ } +.glitch-word::after { color: #8b5cf6; /* purple channel */ } +``` + +#### `.glitch-kanji` + +Full-line glitch wrapper with scanline overlay and scattered Japanese characters. Use for dramatic headings or hover effects on corrupted text elements. + +```html +

    SYSTEM CORRUPT

    +``` + +Both classes respect `prefers-reduced-motion` — animation is disabled when the user has reduced motion enabled. + +### CRT Effects JS Layer (`src/lib/crt-effects.js`) + +The `CRTEffects` class applies a post-processing CRT overlay to a container element. It uses CSS animation keyframes defined in `animations.css`: + +| Keyframe | Purpose | +|----------|---------| +| `scanline-movement` | Horizontal scanline drift | +| `crt-flicker` | Phosphor flicker at 0.12s cadence | + +```javascript +import { CRTEffects } from '@whykusanagi/corrupted-theme/crt-effects'; + +const crt = new CRTEffects(document.querySelector('.hero'), { + scanlines: true, + flicker: true, + phosphor: true, + intensity: 0.3, +}); +crt.start(); +``` + +See [`docs/COMPONENTS_REFERENCE.md`](../COMPONENTS_REFERENCE.md) for the full `CRTEffects` API. + +--- + ## CLI Terminal Animations ### Terminal Constraints @@ -895,7 +951,7 @@ Need animation? --- -**Last Updated**: 2025-12-13 -**Version**: 1.0.0 +**Last Updated**: 2026-05-18 +**Version**: 0.2.0 **Maintainer**: Celeste Brand System -**Status**: ✅ Phase 2 Complete +**Status**: ✅ Updated for 0.2.0 (CRT effects + glitch keyframes) diff --git a/docs/components/COMPONENT_LIBRARY.md b/docs/components/COMPONENT_LIBRARY.md index 66d93d2..73e62f6 100644 --- a/docs/components/COMPONENT_LIBRARY.md +++ b/docs/components/COMPONENT_LIBRARY.md @@ -1,7 +1,7 @@ # Celeste Brand System - Component Library -**Version**: 1.0.0 -**Last Updated**: 2025-12-13 +**Version**: 0.2.0 +**Last Updated**: 2026-05-18 **Status**: 🟠 **HIGH PRIORITY DOCUMENT** --- @@ -35,8 +35,11 @@ This document provides a complete inventory of all Celeste design system compone | **Navigation** | 6 | 0 | Navbar, breadcrumbs, tabs | | **Feedback** | 5 | 2 | Alerts, loaders, notifications | | **Extensions** | 10 | 0 | Gallery, countdown, social links | +| **JS Libraries (0.2.0)** | 19 | 0 | Animation blocks, CRT, widgets, utilities | -**Total**: 56 web components, 8 CLI patterns +**Total**: 75 web components + JS libs, 8 CLI patterns + +> **0.2.0 JS libraries** are documented in full in [`docs/COMPONENTS_REFERENCE.md`](../COMPONENTS_REFERENCE.md). See the section below for a summary. --- @@ -1048,6 +1051,56 @@ Component --- +## 0.2.0 JavaScript Library Components + +The 0.2.0 release adds a canonical JS layer on top of the CSS framework. Full API docs live in [`docs/COMPONENTS_REFERENCE.md`](../COMPONENTS_REFERENCE.md). Summary: + +### Core (`src/core/`) + +| Module | Class / Export | Purpose | +|--------|---------------|---------| +| `corruption-manager.js` | `CorruptionManager` | Lifecycle-managed multi-animation runner | +| `corruption-charsets.js` | charset helpers | Canonical charset access from `src/data/charsets.json` | +| `corruption-phrases.js` | phrase helpers | Canonical phrase access from `src/data/phrases.json` | +| `typing-animation.js` | `TypingAnimation` | Buffer-style corruption with SFW/NSFW modes | +| `timer-registry.js` | `TimerRegistry` | Global interval/timeout registry (UMD build) | +| `event-tracker.js` | `EventTracker` | DOM event lifecycle helpers | + +### Lib (`src/lib/`) + +**Animation Blocks** (`animation-blocks.js`) — 10 classes: +`TitleDecoder`, `ProgressBar`, `ScanlineSweep`, `TerminalBoot`, `GlitchPulse`, `ASCIIBorder`, `SystemDiagnostic`, `LoadingBarMulti`, `DataTransmission`, `TerminalPrompt` + +| Module | Class / Export | Purpose | +|--------|---------------|---------| +| `crt-effects.js` | `CRTEffects` | Full CRT post-processing layer (scanlines, flicker, phosphor glow) | +| `corrupted-text.js` | `CorruptedText` | Inline character-level corruption | +| `corrupted-particles.js` | `CorruptedParticles` | Canvas 2D floating particle field | +| `corrupted-vortex.js` | `CorruptedVortex` | WebGL raymarched spiral tunnel | +| `gallery.js` | `Gallery` | Responsive grid gallery with lightbox | +| `lightbox.js` | `Lightbox` | Standalone image lightbox | +| `countdown-widget.js` | `CountdownWidget` | Event countdown with shape variants | +| `clock-widget.js` | `ClockWidget` | Real-time corrupted clock | +| `toast.js` | `ToastManager` | Singleton toast notification queue | +| `nsfw-reveal.js` | `NsfwReveal` | Blur overlay with click-to-reveal | +| `event-bar.js` | `EventBar` | Stream event overlay bar | +| `logo-banner.js` | `LogoBanner` | Animated logo/brand banner | +| `png-export.js` | `PNGExport` | html2canvas-based DOM export | +| `websocket-manager.js` | `WebSocketManager` | Reconnecting WebSocket with corruption states | + +### Utilities (`src/core/`) + +| Module | Exports | Purpose | +|--------|---------|---------| +| `random-utils.js` | `randomFrom`, `weightedRandom`, etc. | Random helpers | +| `time-utils.js` | `formatDuration`, `countdown`, etc. | Time formatting | +| `clipboard-helpers.js` | `copyToClipboard`, etc. | Clipboard access | +| `url-state.js` | `getParam`, `setParam`, etc. | URL search param state | + +All JS libs share the same class-based API: `new FooClass(element, options)` with `start()`, `stop()`, `destroy()`. + +--- + ## Related Documents - **GLASSMORPHISM.md** - Detailed glass effect specifications @@ -1055,7 +1108,9 @@ Component - **ANIMATION_GUIDELINES.md** - Motion and timing - **COLOR_SYSTEM.md** - Semantic color usage - **COMPONENT_MAPPING.md** - Cross-platform equivalents (Platform tier) +- **COMPONENTS_REFERENCE.md** - Full JS API reference (0.2.0) +- **CDN_CONSUMPTION.md** - CDN import guide --- -**Status**: ✅ **COMPONENT LIBRARY COMPLETE** - Ready for implementation +**Status**: ✅ **COMPONENT LIBRARY COMPLETE** - Updated for 0.2.0 diff --git a/docs/components/GLASSMORPHISM.md b/docs/components/GLASSMORPHISM.md index 6746d6f..1f0e6b4 100644 --- a/docs/components/GLASSMORPHISM.md +++ b/docs/components/GLASSMORPHISM.md @@ -1,7 +1,7 @@ # Celeste Brand System - Glassmorphism -**Version**: 1.0.0 -**Last Updated**: 2025-12-13 +**Version**: 0.2.0 +**Last Updated**: 2026-05-18 **Status**: 🟠 **HIGH PRIORITY DOCUMENT** --- @@ -342,6 +342,49 @@ window.addEventListener('scroll', () => { --- +## 0.2.0 Container Variants + +The T12 glassmorphism CSS merge added standalone container classes and color modifier classes in `src/css/glassmorphism.css`. These compose with the existing depth layers. + +### Standalone Container Classes + +| Class | Opacity | Blur | Use Case | +|-------|---------|------|----------| +| `.glass-container` | 85% | 15px | Default container (replaces ad-hoc glass inline styles) | +| `.glass-container-dark` | 92% | 20px | Modals, dropdowns, elevated panels | +| `.glass-container-subtle` | 60% | 8px | Low-key background sections | +| `.glass-container-gradient` | 80% + gradient | 15px | Hero sections with branded gradient overlay | +| `.glass-container-animated` | 80% | 15px | Animated shimmer; adds border glow pulse | + +All variants include the `@supports not (backdrop-filter)` fallback automatically — no extra code needed. + +### Color Modifier Classes + +Compose with any container class to tint the border and shadow: + +```html + +
    ...
    + + +
    ...
    + + +
    ...
    +``` + +| Modifier | Border Color | Shadow Tint | +|----------|-------------|-------------| +| `.glass-container-cyan` | `#00ffff` | cyan glow | +| `.glass-container-purple` | `#8b5cf6` | purple glow | +| `.glass-container-magenta` | `#d94f90` | magenta glow (default accent) | + +### `@supports` Fallback + +All new classes include an automatic `@supports not (backdrop-filter: blur(1px))` block that upgrades the background opacity to 0.95 so content remains readable on browsers without blur support. + +--- + ## CLI Equivalent (Block Characters) Since terminals don't support `backdrop-filter`, the CLI achieves glassmorphism through **block characters and color gradients**. @@ -599,4 +642,4 @@ From `DESIGN_TOKENS.md`: --- -**Status**: ✅ **GLASSMORPHISM COMPLETE** - Ready for implementation +**Status**: ✅ **GLASSMORPHISM COMPLETE** - Updated for 0.2.0 (new container variants + color modifiers) From 06df27ec05a7ec5296efa9c5aeaf18358055891f Mon Sep 17 00:00:00 2001 From: whyKusanagi Date: Mon, 18 May 2026 01:32:43 -0700 Subject: [PATCH 4/6] docs: update platforms/ for 0.2.0 (CDN section, new component mapping, cross-language contract) - WEB_IMPLEMENTATION: add CDN Consumption section linking to CDN_CONSUMPTION.md with quick-reference snippet; bump version - COMPONENT_MAPPING: add 0.2.0 JS library component mapping table (19 entries) with CLI equivalent notes; bump version - CLI_IMPLEMENTATION: add Cross-Language Data Contract section referencing src/data/*.json and CROSS_LANGUAGE_CONTRACT.md; update related docs links; bump version - NPM_PACKAGE: fix CDN URL from @0.1.9 to @0.2.0; replace speculative future migration guide with actual 0.2.0 migration summary pointing to MIGRATION_CONTAINER_0.2.0.md Co-Authored-By: Claude Sonnet 4.6 --- docs/platforms/CLI_IMPLEMENTATION.md | 31 +++++++++++++++++++++-- docs/platforms/COMPONENT_MAPPING.md | 38 +++++++++++++++++++++++----- docs/platforms/NPM_PACKAGE.md | 35 +++++++------------------ docs/platforms/WEB_IMPLEMENTATION.md | 31 ++++++++++++++++++++--- 4 files changed, 97 insertions(+), 38 deletions(-) diff --git a/docs/platforms/CLI_IMPLEMENTATION.md b/docs/platforms/CLI_IMPLEMENTATION.md index 89d7f51..0d5310b 100644 --- a/docs/platforms/CLI_IMPLEMENTATION.md +++ b/docs/platforms/CLI_IMPLEMENTATION.md @@ -1009,17 +1009,44 @@ func stripAnsi(s string) string { --- +## Cross-Language Data Contract (0.2.0) + +As of 0.2.0, phrase lists, character sets, and the canonical color palette are no longer embedded as inline arrays in celeste-cli Go source. They are published as JSON in the npm package and available to any language consumer. + +**Canonical data files** (in `@whykusanagi/corrupted-theme`): + +| File | Content | +|------|---------| +| `src/data/phrases.json` | SFW + NSFW phrase pools (void, memory, japanese, english, romaji) | +| `src/data/charsets.json` | Katakana, Hiragana, Kanji, symbol, block character sets | +| `src/data/colors.json` | Canonical 6-color palette + semantic use mapping | + +For the full contract — including JSON schema, field semantics, and Go consumption examples — see [`docs/CROSS_LANGUAGE_CONTRACT.md`](../CROSS_LANGUAGE_CONTRACT.md). + +**Quick Go consumption example**: +```go +// Embed the JSON files from the npm package (or a local copy) +//go:embed phrases.json charsets.json +var phraseData []byte +var charsetData []byte +``` + +This replaces the previous pattern of hardcoded `katakana` and `hiragana` slices defined inline in `tui/streaming.go`. + +--- + ## Related Documentation - [WEB_IMPLEMENTATION.md](./WEB_IMPLEMENTATION.md) - Web platform comparison - [COMPONENT_MAPPING.md](./COMPONENT_MAPPING.md) - CLI ↔ Web equivalents +- [CROSS_LANGUAGE_CONTRACT.md](../CROSS_LANGUAGE_CONTRACT.md) - JSON data contract for Go/non-JS consumers - [ANIMATION_GUIDELINES.md](../components/ANIMATION_GUIDELINES.md) - Animation timing reference - [COLOR_SYSTEM.md](../brand/COLOR_SYSTEM.md) - Color specifications - [TRANSLATION_FAILURE_AESTHETIC.md](../brand/TRANSLATION_FAILURE_AESTHETIC.md) - Corruption rules --- -**Last Updated**: 2025-12-13 -**Version**: 1.0.0 +**Last Updated**: 2026-05-18 +**Version**: 0.2.0 (added cross-language contract reference) **Maintainer**: Celeste Brand System **Status**: ✅ Ready for Production diff --git a/docs/platforms/COMPONENT_MAPPING.md b/docs/platforms/COMPONENT_MAPPING.md index 8f55597..c512837 100644 --- a/docs/platforms/COMPONENT_MAPPING.md +++ b/docs/platforms/COMPONENT_MAPPING.md @@ -2,8 +2,8 @@ > **Celeste Brand System** | Platform Documentation > **Document**: Cross-Platform Component Mapping -> **Version**: 1.0.0 -> **Last Updated**: 2025-12-13 +> **Version**: 0.2.0 +> **Last Updated**: 2026-05-18 --- @@ -110,12 +110,38 @@ This document maps **web components** (from @whykusanagi/corrupted-theme) to the | `.video` | N/A | 🌐 | N/A | Web-only (video player) | | `.audio` | N/A | 🌐 | N/A | Web-only (audio player) | -**Summary**: +**Summary** (CSS components): - ✅ **30 components** with 1:1 equivalents (53%) - 🔄 **18 components** adapted for platform (32%) - 🌐 **8 components** web-only (14%) - 💻 **0 components** CLI-only (CLI uses web equivalents) +### 0.2.0 JS Library Components (Web-Only) + +The following JS modules have no CLI equivalent — they target browser/canvas/WebGL environments. See [`docs/COMPONENTS_REFERENCE.md`](../COMPONENTS_REFERENCE.md) for full APIs. + +| npm Export | Class | Category | CLI Equivalent | +|------------|-------|----------|---------------| +| `./corruption-manager` | `CorruptionManager` | Core | None (CLI uses Go structs) | +| `./animation-blocks` | 10 block classes | Animation | `CorruptText()` + `CorruptTextJapanese()` (approximate) | +| `./crt-effects` | `CRTEffects` | Animation | None | +| `./corrupted-text` | `CorruptedText` | Corruption | `CorruptTextJapanese()` | +| `./corrupted-particles` | `CorruptedParticles` | Visual | None | +| `./corrupted-vortex` | `CorruptedVortex` | Visual | None | +| `./toast` | `ToastManager` | Feedback | Banner alerts | +| `./nsfw-reveal` | `NsfwReveal` | Overlay | None | +| `./gallery` | `Gallery` | Extension | None | +| `./lightbox` | `Lightbox` | Extension | None | +| `./countdown-widget` | `CountdownWidget` | Extension | None | +| `./clock-widget` | `ClockWidget` | Extension | None | +| `./event-bar` | `EventBar` | Streaming | None | +| `./logo-banner` | `LogoBanner` | Branding | None | +| `./png-export` | `PNGExport` | Utility | None | +| `./websocket-manager` | `WebSocketManager` | Networking | Go WebSocket client | +| `./random-utils` | helpers | Utility | Go `math/rand` | +| `./time-utils` | helpers | Utility | Go `time` | +| `./clipboard-helpers` | helpers | Utility | pbcopy / xclip | + --- ## Container Components @@ -573,7 +599,7 @@ Need navigation? --- -**Last Updated**: 2025-12-13 -**Version**: 1.0.0 +**Last Updated**: 2026-05-18 +**Version**: 0.2.0 **Maintainer**: Celeste Brand System -**Status**: ✅ Complete Cross-Platform Reference +**Status**: ✅ Complete Cross-Platform Reference (updated for 0.2.0) diff --git a/docs/platforms/NPM_PACKAGE.md b/docs/platforms/NPM_PACKAGE.md index cd81aba..656300f 100644 --- a/docs/platforms/NPM_PACKAGE.md +++ b/docs/platforms/NPM_PACKAGE.md @@ -88,9 +88,11 @@ pnpm add @whykusanagi/corrupted-theme ```html - + ``` +> **Preferred CDN**: Use the live-site CDN for zero-latency delivery and SRI-verified assets. See [`docs/CDN_CONSUMPTION.md`](../CDN_CONSUMPTION.md) for details. + ### Local Development For local development or contributing: @@ -724,33 +726,14 @@ npm install @whykusanagi/corrupted-theme@latest ## Migration Guide -### From v0.1.x to v0.2.x (Future) - -**Planned breaking changes**: -1. Design tokens moved to external JSON file -2. CSS custom property names standardized (e.g., `--accent` → `--color-accent`) -3. Component naming conventions updated +### From v0.1.x to v0.2.0 -```css -/* Before (v0.1.x) */ -.card { - background: var(--glass-bg); -} +See [`docs/MIGRATION_CONTAINER_0.2.0.md`](../MIGRATION_CONTAINER_0.2.0.md) for the full guide. Key changes: -/* After (v0.2.x) */ -.glass-card { /* Renamed for clarity */ - background: var(--color-bg-glass); /* Standardized naming */ -} -``` - -**Automated migration**: -```bash -# Install migration tool (future) -npm install -g @whykusanagi/theme-migrate - -# Run migration -theme-migrate upgrade 0.1.x 0.2.x ./src -``` +- **`.container` class redesigned** — now controls max-width layout; replace old `.container` usage with new `.glass-container` variants where glass effect was intended +- **New canonical JSON data** — phrase lists and charsets live in `src/data/` instead of inline in JS +- **New JS exports** — 19 new modules available under `./corruption-manager`, `./animation-blocks`, `./crt-effects`, etc. in `package.json` exports map +- **No removed exports** — all 0.1.x CSS classes and JS classes remain; 0.2.0 is additive ### From Custom CSS to Corrupted Theme diff --git a/docs/platforms/WEB_IMPLEMENTATION.md b/docs/platforms/WEB_IMPLEMENTATION.md index 9a900b6..947525c 100644 --- a/docs/platforms/WEB_IMPLEMENTATION.md +++ b/docs/platforms/WEB_IMPLEMENTATION.md @@ -2,8 +2,8 @@ > **Celeste Brand System** | Platform Documentation > **Document**: Web Implementation Guide -> **Version**: 1.0.0 -> **Last Updated**: 2025-12-13 +> **Version**: 0.2.0 +> **Last Updated**: 2026-05-18 --- @@ -1205,9 +1205,32 @@ document.querySelector('.form').addEventListener('submit', (e) => { --- +## CDN Consumption (0.2.0) + +For projects that cannot use npm, all JS modules are available directly via CDN. See [`docs/CDN_CONSUMPTION.md`](../CDN_CONSUMPTION.md) for the full guide, SRI hashes, and recommended ` +``` + +SRI hashes for all CDN assets are published in `CHANGELOG.md` alongside each release. + +--- + ## Related Documentation - [NPM_PACKAGE.md](./NPM_PACKAGE.md) - Package installation and configuration +- [CDN_CONSUMPTION.md](../CDN_CONSUMPTION.md) - CDN import guide and SRI hashes - [COMPONENT_MAPPING.md](./COMPONENT_MAPPING.md) - Web ↔ CLI component equivalents - [COMPONENT_LIBRARY.md](../components/COMPONENT_LIBRARY.md) - All available components - [ANIMATION_GUIDELINES.md](../components/ANIMATION_GUIDELINES.md) - Animation specifications @@ -1215,7 +1238,7 @@ document.querySelector('.form').addEventListener('submit', (e) => { --- -**Last Updated**: 2025-12-13 -**Version**: 1.0.0 +**Last Updated**: 2026-05-18 +**Version**: 0.2.0 **Maintainer**: Celeste Brand System **Status**: ✅ Ready for Production From cf39f46a837624c5532c0ceb286bab5b4b0e7b68 Mon Sep 17 00:00:00 2001 From: whyKusanagi Date: Mon, 18 May 2026 01:32:49 -0700 Subject: [PATCH 5/6] docs: refresh 0.1.x-era docs for 0.2.0 (canonical JSON redirect, personality phrases) - CORRUPTION_PHRASES: add prominent 0.2.0 redirect header pointing at src/data/phrases.json + CROSS_LANGUAGE_CONTRACT; update related files section; doc preserved as narrative context - CHARACTER_LEVEL_CORRUPTION: add 0.2.0 note redirecting charset consumers to src/data/charsets.json + corruption-charsets.js; update related files section - PERSONALITY: add Personality Phrase Pools section documenting the sfw/nsfw void+memory pools in phrases.json that power TypingAnimation, CorruptedParticles, and custom overlays; add canonical JSON source link Co-Authored-By: Claude Sonnet 4.6 --- docs/CHARACTER_LEVEL_CORRUPTION.md | 7 ++++++- docs/CORRUPTION_PHRASES.md | 12 +++++++++++- docs/PERSONALITY.md | 19 +++++++++++++++++++ 3 files changed, 36 insertions(+), 2 deletions(-) diff --git a/docs/CHARACTER_LEVEL_CORRUPTION.md b/docs/CHARACTER_LEVEL_CORRUPTION.md index a043c25..4b1eb14 100644 --- a/docs/CHARACTER_LEVEL_CORRUPTION.md +++ b/docs/CHARACTER_LEVEL_CORRUPTION.md @@ -1,8 +1,10 @@ # Character-Level Corruption - Implementation Guide -**Date**: 2025-12-12 +**Date**: 2025-12-12 (updated 2026-05-18 for 0.2.0 canonical charsets) **Issue Fixed**: Dashboard titles now use character-level Japanese mixing instead of word replacement +> **0.2.0 note**: The Katakana, Hiragana, and Kanji arrays used by `CorruptTextJapanese()` are now defined canonically in **`src/data/charsets.json`** (part of the npm package). JS callers should consume them via `src/core/corruption-charsets.js` or `src/core/corruption-phrases.js`. Go callers can embed or fetch the JSON — see [`docs/CROSS_LANGUAGE_CONTRACT.md`](CROSS_LANGUAGE_CONTRACT.md). The inline array patterns shown in this document remain valid reference implementations but are superseded by the canonical JSON for production use. + --- ## The Problem @@ -251,6 +253,9 @@ Character-level mixing is slightly more expensive than word replacement, but the ## Related Files +- **Canonical charsets (0.2.0)**: `src/data/charsets.json` — Katakana, Hiragana, Kanji, symbols +- **JS access**: `src/core/corruption-charsets.js` +- **Cross-language contract**: `docs/CROSS_LANGUAGE_CONTRACT.md` - **Implementation**: `tui/streaming.go:252` and `commands/corruption.go:124` - **Usage**: `commands/stats.go:194` - **Style Guide**: `docs/STYLE_GUIDE.md` diff --git a/docs/CORRUPTION_PHRASES.md b/docs/CORRUPTION_PHRASES.md index 86b4658..32a5418 100644 --- a/docs/CORRUPTION_PHRASES.md +++ b/docs/CORRUPTION_PHRASES.md @@ -1,5 +1,13 @@ # Celeste CLI - Corruption Phrases Library +> **As of 0.2.0** — The canonical phrase data now lives in **`src/data/phrases.json`** (published with the npm package). The JSON file is the single source of truth for all phrase pools (SFW and NSFW, by language and theme). The `corruption-phrases.js` module in `src/core/` provides typed access to those pools from JavaScript. +> +> For multi-language consumers (Go, Python, etc.) see **[`docs/CROSS_LANGUAGE_CONTRACT.md`](CROSS_LANGUAGE_CONTRACT.md)** for the full JSON schema and consumption guide. +> +> This document remains as **narrative context and a human-readable reference** for the phrase library. All phrase additions should go into `src/data/phrases.json`, not here. + +--- + **Seeded phrases for consistent branding across the application** This file provides pre-made corrupted phrases following the translation-failure aesthetic. Use these directly in your code instead of inventing new corruptions ad-hoc. @@ -517,10 +525,12 @@ Final: "生成 generating repōto..." ## Related Files +- **Canonical JSON** (0.2.0): `src/data/phrases.json` — source of truth for all phrase pools +- **JS Access**: `src/core/corruption-phrases.js` — typed access helpers +- **Contract doc**: `docs/CROSS_LANGUAGE_CONTRACT.md` — JSON schema + Go/non-JS consumption - **Style Guide**: `/docs/STYLE_GUIDE.md` - Full aesthetic documentation - **Go Implementation**: `/cmd/celeste/tui/streaming.go` - Corruption functions - **Official Theme**: `@whykusanagi/corrupted-theme` - npm package -- **TypeScript Reference**: `../_archive/celeste-cli-typescript/src/ui/corruption.ts` (legacy) --- diff --git a/docs/PERSONALITY.md b/docs/PERSONALITY.md index 4111b85..5aab652 100644 --- a/docs/PERSONALITY.md +++ b/docs/PERSONALITY.md @@ -119,8 +119,27 @@ - **Personality Over Data:** Always prioritize personality over raw information - **Rotation:** Never repeat same response type consecutively to same user +## Personality Phrase Pools (0.2.0) + +As of 0.2.0, the in-universe personality phrases ("Corrupt me more…", void-theme lore, intimacy lines) are canonically stored in `src/data/phrases.json` alongside the technical corruption phrases. The relevant pools are: + +| Pool path | Content | +|-----------|---------| +| `sfw.japanese.void` | SFW Japanese void/abyss phrases | +| `sfw.japanese.memory` | SFW identity-loss Japanese phrases | +| `nsfw.english.void` | NSFW void descent English phrases | +| `nsfw.english.memory` | NSFW identity/intimacy English phrases | +| `nsfw.japanese.void` | NSFW Japanese void phrases | +| `nsfw.japanese.memory` | NSFW Japanese intimacy phrases | + +These pools power `TypingAnimation` (buffer corruption mode), `CorruptedParticles` floating text, and any custom corruption-loading overlay when `includeLewd: true`. + +--- + ## See Also +- `src/data/phrases.json` - Canonical personality phrase pools (0.2.0) +- `docs/CROSS_LANGUAGE_CONTRACT.md` - JSON schema for phrases.json - `../celeste_essence.json` - Full system prompt for LLM - `../Celeste_Capabilities.json` - What Celeste can do (7 projects) - `../content_archetypes.json` - Content generation patterns From 2f72b203031c8cef5db5e1641d3427488066dbdf Mon Sep 17 00:00:00 2001 From: whyKusanagi Date: Mon, 18 May 2026 01:32:54 -0700 Subject: [PATCH 6/6] docs: brand/ references src/data/colors.json as canonical color source - COLOR_SYSTEM: add 0.2.0 header note that src/data/colors.json is the machine-readable source of truth for the 6-color corruption palette; bump version to 0.2.0 - DESIGN_TOKENS: note canonical color subset at src/data/colors.json alongside the full design-tokens.json; link CROSS_LANGUAGE_CONTRACT for schema; bump version to 0.2.0 Co-Authored-By: Claude Sonnet 4.6 --- docs/brand/COLOR_SYSTEM.md | 8 +++++--- docs/brand/DESIGN_TOKENS.md | 9 +++++---- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/brand/COLOR_SYSTEM.md b/docs/brand/COLOR_SYSTEM.md index bb7adb6..c53fc60 100644 --- a/docs/brand/COLOR_SYSTEM.md +++ b/docs/brand/COLOR_SYSTEM.md @@ -1,10 +1,12 @@ # Celeste Brand System - Color System -**Version**: 1.0.0 -**Last Updated**: 2025-12-13 +**Version**: 0.2.0 +**Last Updated**: 2026-05-18 **WCAG Compliance**: AA (4.5:1 minimum) **Status**: 🔴 **CRITICAL FOUNDATION DOCUMENT** +> **0.2.0 canonical source**: The 6-color corruption palette and semantic use mapping are now defined in **`src/data/colors.json`** (published with the npm package). That JSON file is the machine-readable single source of truth. See [`docs/CROSS_LANGUAGE_CONTRACT.md`](../CROSS_LANGUAGE_CONTRACT.md) for the schema. The values in this document match colors.json exactly. + --- ## Overview @@ -580,4 +582,4 @@ See `DESIGN_TOKENS.md` for complete W3C DTCG format. --- -**Status**: ✅ **COLOR SYSTEM COMPLETE** - All colors specified with WCAG compliance +**Status**: ✅ **COLOR SYSTEM COMPLETE** - All colors specified with WCAG compliance (0.2.0: canonical JSON source at src/data/colors.json) diff --git a/docs/brand/DESIGN_TOKENS.md b/docs/brand/DESIGN_TOKENS.md index 3f3fb77..457e0e0 100644 --- a/docs/brand/DESIGN_TOKENS.md +++ b/docs/brand/DESIGN_TOKENS.md @@ -1,7 +1,7 @@ # Celeste Brand System - Design Tokens -**Version**: 1.0.0 -**Last Updated**: 2025-12-13 +**Version**: 0.2.0 +**Last Updated**: 2026-05-18 **Token Format**: W3C Design Tokens Community Group (DTCG) **Status**: 🔴 **CRITICAL FOUNDATION DOCUMENT** @@ -19,7 +19,8 @@ Design tokens are **platform-agnostic design decisions** stored in a structured - ✅ **Tooling support** (Figma, Style Dictionary, Theo) **Celeste's Implementation**: -- **Master file**: `design-tokens.json` (W3C DTCG format) +- **Master file**: `design-tokens.json` (W3C DTCG format — full token set) +- **Canonical color subset (0.2.0)**: `src/data/colors.json` — the 6-color corruption palette and semantic mapping, published with the npm package as a machine-readable source of truth. Values are identical to the color tokens below. See [`docs/CROSS_LANGUAGE_CONTRACT.md`](../CROSS_LANGUAGE_CONTRACT.md) for the schema. - **Generated files**: - `tokens.css` (CSS custom properties for web) - `tokens.go` (Go constants for CLI) @@ -1006,4 +1007,4 @@ module.exports = { --- -**Status**: ✅ **FOUNDATION COMPLETE** - Tokens defined, ready for generation +**Status**: ✅ **FOUNDATION COMPLETE** - Tokens defined, ready for generation (0.2.0: colors.json is canonical color subset)