Theming: materials, artwork and verification
One documented material contract for y2kanimator and its embedded timelines. Inspect the actual artwork, distinguish implemented behavior from planned skin capabilities, and review every change here.
The two material owners
TimelineTrack is the strip or tape carrying timed content. Its appearance is WashiStyling. TrackHeader is the adjoining header and cap device; its appearance is HeaderStyling. Device and TrackHeaderMaterial are retired design names.
Each theme has seven ordered colour slots. Every slot owns an independent headerStyle and washiStyle recipe, even when the initial recipes have identical values. A component selects its recipe by slot and role. It does not borrow arbitrary finish or font settings from its host chatroom.
The theme owns immutable reusable artwork. Components own how that artwork is applied to their geometry, text, indicators and content. Referencing the same image does not merge the two recipes. The World shell remains dark-only in this iteration; historical light and frosted source samples below are asset references, not available shell themes.
One gloss profile per theme
The migrated native theme format is version 3. It supplies exactly one RGBA image, one pixel wide and 128 pixels high. The renderer stretches it horizontally and samples its height across the local face. Downsampled mip levels are filtered copies of this same image, not additional authored gloss profiles.
Each HeaderStyling and WashiStyling independently chooses glossEnabled, glossStrength and glossOnFlat. The shader mixes the base colour with the profile RGB using profile alpha multiplied by strength. Flat exposure cells stay flat unless their recipe explicitly allows gloss.
The work-header thumbnail is part of the header surface: it receives the same gloss, left-edge fade and curved mask. That finish is presentation only; it never changes the source thumbnail or authored artwork.
The profile may contain dark shading as part of its surface finish. Exterior cast shadows are separate geometry. Never bake a second exterior drop shadow into this profile or restore per-height highlight/shadow sprites.
Supported recipe fields
- typography: family (interface/system, rounded or serif), scale, tracking and baseline. Header and tape typography resolve independently.
- glossEnabled and glossStrength: enable and attenuate the single shared profile. glossOnFlat: opt a flat cell into that finish.
- radius: local face curvature; backingOpacity: the translucent backing, separate from cell/content opacity.
- pattern and period: optional atlas region and repeat period. The current seven-slot recipes have no tileable track patterns. Atlas compatibility pixels do not mean patterns are enabled.
- indicator: a native artwork reference in the recipe. The browser currently also uses separate exported indicator sprites and procedural timeline controls; arbitrary per-recipe indicator replacement is not complete.
- Masks, contact shadows, exterior shadows, attachment joins and fixed hit regions remain component geometry. Arbitrary Winamp-style geometry, embedded fonts, uploaded skin packages and marketplace distribution are future work.
Fonts and icons: current limits
The browser prepares three shared host-font glyph pages (system, rounded and serif) in a 1024 × 1344 RGBA atlas. The current retained glyph path contains printable ASCII. It is not an embedded custom-font delivery system and does not establish complete international text coverage.
Theme recipes own typography selection. The host owns font availability and glyph preparation. Native font rendering and browser fallback fonts can differ; exact typeface and glyph parity requires a packaged font/glyph contract.
Controls that are unavailable keep their presentation and use disabled content state. Their actions, permissions and native hit behavior are not changed by skins. A chat embed must use the same renderer and control vocabulary as the application.
What is actually downloaded
Playbar layers are already quality-90 WebP with lossless alpha. Masks, indicator artwork and peripheral strips use lossless WebP. References are content-addressed. The authored playbar reference width is 1376 logical points; image compression never changes control geometry.
The timeline material is the newer compact, seven-slot / single-gloss system. Its current transport is still a SHA-256 checked .bin.gz containing 1168 bytes of GPU uniforms, a 512 × 256 RGBA atlas with ten exact Metal-generated mip levels, and the 1 × 128 gloss with eight mip levels. Each decoded payload is 701,240 bytes. This is NOT yet the requested all-WebP transport.
The WebP migration must preserve straight-alpha colour, orientation, atlas regions, mip filtering and native source identities. It must not reintroduce the retired large atlas or generate gloss for each row height. Until browser pixel comparisons pass, the existing exact mip payload is explicitly a migration dependency.
The asset reference below is generated directly from the checked-in material payloads. PNG atlas/profile images are documentation-only views of those bytes; the application does not download these documentation images.
Geometry, clipping and shadows
Camera movement and playbar resizing update projection and retained placement. They must not warp faces, regenerate source pixels, or stretch the time axis independently of its labels and hit regions. Painting-column caps retain their shape while only the straight section repeats.
A header shoulder and its main face use one continuous contour. Joined header/cap backing is the shadow silhouette; translucent backing alpha must not weaken or double the exterior cast. Header and right-cap contact shadows fall onto the track underneath. Notifications are foreground exceptions.
The browser timeline uses timeline-shadow-style.js for WebGPU, DOM connector contacts and Canvas approximations. World HTML surfaces use the named tokens in styles/shadows.css. Gloss, recessed rails, edge fringing and cast shadows are distinct effects.
WebGPU and Metal use the same material data contract. Canvas2D uses the same scene and projection with simpler materials and approximate shadow blur. It is a compatibility backend, not a claim of pixel-identical native rendering. Physical iPad acceptance remains separate from browser screenshots or compilation.
Caching and performance ownership
Public skin resources may be shared across accounts; private project content may not. The timeline loader verifies encoded length and SHA-256, bounds decompression, and uploads each prepared theme once per shared GPU device while leased. Glyphs are also shared.
Current shared renderer limits are four admitted surfaces and 128 MiB of tracked texture/material allocations. This is an admission limit, not a measurement of total browser or GPU process memory. Render targets, DOM and decoder overhead need separate accounting.
Material textures are pinned by active leases and destroyed after the final lease releases them, or on device loss. Camera-only motion does not decode images, compile shaders, create fonts or rebuild material atlases. Source revisions, not camera positions, identify cached resources.
Required review for every theming change
- Update this guide for any changed field, ownership rule, transport, sizing, font, shadow or cache behavior. State what is implemented and what is still a target.
- Regenerate source artwork manifests through their exporters, never by editing generated JavaScript or modifying original native theme packages.
- Review theme-review.json against the changed source and update its reviewed hashes only after the prose and asset reference agree. Web/timeline and handbook builds reject stale review receipts.
- Run the theme documentation verifier, normal build/type checks and relevant renderer tests. Inspect the handbook asset reference and test actual widgets in the Codex browser.
- Record visual evidence for expanded/collapsed shots, boards, FX and audio; narrow/zoomed cells; header joins, caps, thumbnails, notifications and playbar resizing. Keep unverified cases explicit.
- Checkpoint the source and publish the documentation with the iteration. Documentation is a release requirement, not optional follow-up work.
Actual source artwork
These are the existing exported pixels, not new mockups. Click an image to open its source. The gloss strips are widened only by page styling so that their contents are visible.
np24-01-pearl-quilt
24,285 encoded bytes · 701,240 decoded bytes · seven style pairs
The full exported chrome reference set contains 24 unique WebP files (1,315,746 bytes total). This is the reference closure, not a claim that every file is fetched at first paint.
np24-03-frosted-stars
22,223 encoded bytes · 701,240 decoded bytes · seven style pairs
np24-15-midnight-tartan
14,064 encoded bytes · 701,240 decoded bytes · seven style pairs
The full exported chrome reference set contains 26 unique WebP files (1,489,570 bytes total). This is the reference closure, not a claim that every file is fetched at first paint.