Prepare hashavatar 0.13.0

Add patterned backgrounds and integer frame mask hardening.

Author: eldryoth

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.13.0
+
+- Bumped the crate to `0.13.0`.
+- Added seven `AvatarBackground` variants: `polka-dot`, `striped`,
+  `checkerboard`, `grid`, `sunrise`, `ocean`, and `starry`.
+- Implemented the new backgrounds for raster and SVG output with bounded,
+  asset-free drawing paths.
+- Added parser/display/`ALL` coverage, raster distinctness tests, and
+  parser-backed SVG well-formedness coverage for the expanded background
+  catalog.
+- Replaced raster frame-shape hit-testing with integer arithmetic for circle,
+  squircle, hexagon, and octagon masks, reducing floating-point sensitivity in
+  shape clipping.
+- Updated automatic visual golden fingerprints because the expanded
+  `AvatarBackground::ALL` list changes automatic background distribution.
+- Fixed documentation that still referenced `cargo test --all-features`; the
+  `blake3` and `xxh3` feature modes are intentionally mutually exclusive.
+- Refreshed README wording for feature-gated encoder testing and the expanded
+  background catalog.
+
 ## 0.12.0
 
 - Bumped the crate to `0.12.0`.

Cargo.lock

@@ -1,9 +1,9 @@
 [package]
 name = "hashavatar"
-version = "0.12.0"
+version = "0.13.0"
 edition = "2024"
 rust-version = "1.95"
-description = "Deterministic procedural avatars in Rust with configurable identity hashing and WebP, optional PNG/JPEG/GIF, and SVG export"
+description = "Deterministic procedural avatars in Rust with configurable identity hashing, patterned backgrounds, WebP, optional PNG/JPEG/GIF, and SVG export"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/valkyoth/hashavatar"
 homepage = "https://github.com/valkyoth/hashavatar"

Cargo.toml

@@ -6,7 +6,7 @@ The crate starts conservative: validated avatar dimensions, bounded identity inp
 
 ## Current Status
 
-The current crate version is `0.12.0`.
+The current crate version is `0.13.0`.
 
 Implemented now:
 
@@ -25,8 +25,8 @@ Implemented now:
 - Avatar families through `AvatarKind`: animals, characters, fantasy/sci-fi
   faces, playful objects, and symbols. Current labels are listed in the public
   option catalog below.
-- Background modes through `AvatarBackground`: `themed`, `white`, `black`,
-  `dark`, `light`, and `transparent`.
+- Background modes through `AvatarBackground`: fixed, transparent, patterned,
+  gradient, and star-field canvas treatments.
 - Visual layers through `AvatarAccessory`, `AvatarColor`,
   `AvatarExpression`, and `AvatarShape`.
 - In-memory `WebP` encoding through `AvatarOutputFormat`; `PNG`, `JPEG`, and
@@ -37,7 +37,8 @@ Implemented now:
 - No public path-writing helpers; callers own their storage and filesystem boundary.
 - `#![forbid(unsafe_code)]` in library code.
 - Golden visual regression fingerprints.
-- Isolated fuzz harness for avatar identities, families, backgrounds, SVG rendering, and PNG encoding.
+- Isolated fuzz harness for avatar identities, families, backgrounds, SVG
+  rendering, default WebP encoding, and feature-gated encoder paths.
 - Local release gates for formatting, clippy, tests, docs, dependency policy, RustSec advisories, package contents, SBOM generation, reproducible build checks, and crates.io publish dry runs.
 
 Planned or intentionally external:
@@ -74,29 +75,29 @@ future release has a concrete image-generation reason to split it.
 
 ```toml
 [dependencies]
-hashavatar = "0.12.0"
+hashavatar = "0.13.0"
 ```
 
 Optional identity hash modes and extra raster encoders are disabled by default.
 Hash modes are mutually exclusive, so enable at most one of `blake3` or `xxh3`:
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.12.0", features = ["blake3"] }
+hashavatar = { version = "0.13.0", features = ["blake3"] }
 ```
 
 Enable additional raster formats explicitly:
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.12.0", features = ["png", "jpeg", "gif"] }
+hashavatar = { version = "0.13.0", features = ["png", "jpeg", "gif"] }
 ```
 
 Or enable every optional raster encoder at once:
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.12.0", features = ["all-formats"] }
+hashavatar = { version = "0.13.0", features = ["all-formats"] }
 ```
 
 Combine these as needed, for example `features = ["blake3", "png"]`.
@@ -143,7 +144,7 @@ in caller code.
 | Enum | Controls | Values |
 | --- | --- | --- |
 | `AvatarKind` | Base avatar family | `cat`, `dog`, `robot`, `fox`, `alien`, `monster`, `ghost`, `slime`, `bird`, `wizard`, `skull`, `paws`, `planet`, `rocket`, `mushroom`, `cactus`, `frog`, `panda`, `cupcake`, `pizza`, `icecream`, `octopus`, `knight`, `bear`, `penguin`, `dragon`, `ninja`, `astronaut`, `diamond`, `coffee-cup`, `shield` |
-| `AvatarBackground` | Canvas/background treatment | `themed`, `white`, `black`, `dark`, `light`, `transparent` |
+| `AvatarBackground` | Canvas/background treatment | `themed`, `white`, `black`, `dark`, `light`, `transparent`, `polka-dot`, `striped`, `checkerboard`, `grid`, `sunrise`, `ocean`, `starry` |
 | `AvatarAccessory` | Optional accessory layer | `none`, `glasses`, `hat`, `headphones`, `crown`, `bowtie`, `eyepatch`, `scarf`, `halo`, `horns` |
 | `AvatarColor` | Optional accent palette | `default`, `neon-mint`, `pastel-pink`, `crimson`, `gold`, `deep-sea-blue` |
 | `AvatarExpression` | Optional expression overlay | `default`, `happy`, `grumpy`, `surprised`, `sleepy`, `winking`, `cool`, `crying` |
@@ -380,7 +381,7 @@ your namespace style version when intentionally migrating output.
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.12.0", features = ["blake3"] }
+hashavatar = { version = "0.13.0", features = ["blake3"] }
 ```
 
 ```rust
@@ -408,7 +409,7 @@ assert!(svg.contains("alien avatar"));
 
 ```toml
 [dependencies]
-hashavatar = { version = "0.12.0", features = ["xxh3"] }
+hashavatar = { version = "0.13.0", features = ["xxh3"] }
 ```
 
 ```rust
@@ -625,23 +626,24 @@ For style-aware rendering, the deterministic tuple also includes
 `accessory`, `color`, `expression`, and `shape`. Existing `AvatarOptions`
 entry points keep those extra layer choices at `none`, `default`, `default`,
 and `square`, so explicitly selected `AvatarOptions` output remains stable
-unless the selected family renderer changes. `0.12.0` adds new `AvatarKind`
-values, so automatic style derivation can map some identities to different
-families than `0.11.0`; services that need the old automatic distribution
-should keep their existing namespace style version until they intentionally
-migrate. Some family/layer combinations are deterministic no-ops when the
-layer has no sensible anchor for that family.
+unless the selected family renderer changes. `0.13.0` adds new
+`AvatarBackground` values, so automatic style derivation can map some
+identities to different backgrounds than `0.12.0`; services that need the old
+automatic distribution should keep their existing namespace style version until
+they intentionally migrate. Some family/layer combinations are deterministic
+no-ops when the layer has no sensible anchor for that family.
 
 Frame shapes are applied as masks in raster output and as SVG clip paths in SVG
 output. Non-square shapes therefore trim the background, avatar body, color
 accent, accessory layer, and expression layer consistently before drawing the
 frame border.
 
-The renderer uses floating-point geometry internally. The project tests golden
-fingerprints on the release platform, but it does not yet claim formal
+The renderer still uses floating-point geometry in family-specific drawing
+paths. Frame-shape raster hit-testing uses integer arithmetic as of `0.13.0`,
+which reduces one source of platform rounding variance. The project tests
+golden fingerprints on the release platform, but it does not yet claim formal
 bit-identical raster output across every CPU architecture, compiler backend,
-and optimization mode. Future core-boundary work tracks fixed-point geometry
-as the path to a stricter cross-platform determinism contract.
+and optimization mode.
 
 The procedural cat renderer seeds its internal RNG from bytes `32..64` of the
 identity digest and uses the lower digest bytes for direct visual parameters.

README.md

@@ -64,8 +64,9 @@ Dependency changes should be reviewed for:
   identity hash, and do not recommend it for user-controlled identifiers unless
   the application first maps those identifiers through its own cryptographic
   boundary.
-- Optional dependency features must be tested with `cargo test --all-features`
-  before release.
+- Optional dependency features must be tested in valid feature combinations
+  before release. Do not use `cargo test --all-features` because the `blake3`
+  and `xxh3` identity-hash modes are intentionally mutually exclusive.
 
 `scripts/validate-dependencies.sh` enforces the current direct dependency allowlist.
 

docs/DEPENDENCIES.md

@@ -91,6 +91,9 @@
   async/runtime boundary.
 - Internal rectangle helpers use saturating or clamping arithmetic for edge and
   intersection calculations.
+- Raster frame-shape hit-testing uses integer arithmetic for circle, squircle,
+  hexagon, and octagon masks, reducing platform-specific floating-point
+  rounding in clipping decisions.
 - Polygon rasterization returns immediately for empty polygons and zero-sized
   images, widens scanline interpolation math before rounding, and is covered by
   a dedicated fuzz harness for arbitrary image dimensions, degenerate polygons,

docs/SECURITY_CONTROLS.md

@@ -446,6 +446,47 @@ public API.
 - `scripts/stable_release_gate.sh check` passes.
 - crates.io publish dry run passes.
 
+## 0.13.0: Background Expansion And Determinism Hardening
+
+Status: implemented in `0.13.0`.
+
+Goal: improve the background catalog without adding new avatar families, and
+reduce platform-sensitive geometry in frame-shape masking before `1.0`.
+
+### Scope
+
+- Add a small accepted background set:
+  - `PolkaDot`
+  - `Striped`
+  - `Checkerboard`
+  - `Grid`
+  - `Sunrise`
+  - `Ocean`
+  - `Starry`
+- Keep background rendering deterministic, bounded, asset-free, and represented
+  in both raster and SVG output.
+- Avoid admitting busier backgrounds such as `Wavy`, `Synthwave`, `Pixel`, and
+  `Cloudy` until they have a clearer contrast and readability story.
+- Replace selected float-based frame-shape raster hit-testing with integer
+  arithmetic.
+- Fix stale documentation around feature-combination testing and fuzz encoder
+  coverage.
+
+### Finish Line
+
+`0.13.0` is done when:
+
+- Every accepted background has `as_str`, `Display`, `FromStr`, and `ALL`
+  coverage.
+- Raster tests prove the new background canvases are distinct and bounded.
+- SVG tests parse every new background as well-formed XML.
+- Golden fingerprints document the automatic-output impact from expanding
+  `AvatarBackground::ALL`.
+- README, dependency docs, changelog, and release notes describe the new
+  background catalog and the feature-testing policy.
+- `scripts/stable_release_gate.sh check` passes.
+- crates.io publish dry run passes.
+
 ## 1.0.0: Stability Contract
 
 Goal: freeze a professional, security-oriented public API and rendering

docs/VERSION_PLAN.md

@@ -0,0 +1,42 @@
+# hashavatar 0.13.0
+
+`0.13.0` expands the background catalog and applies targeted determinism
+hardening without adding new avatar families.
+
+## Added
+
+- Added seven `AvatarBackground` values:
+  - `polka-dot`
+  - `striped`
+  - `checkerboard`
+  - `grid`
+  - `sunrise`
+  - `ocean`
+  - `starry`
+- Implemented each new background in raster and SVG output.
+- Added tests that prove the new raster backgrounds are distinct and that the
+  new SVG backgrounds remain well-formed XML.
+
+## Changed
+
+- Raster frame-shape hit-testing now uses integer arithmetic for circle,
+  squircle, hexagon, and octagon masks. This reduces one source of
+  platform-specific floating-point rounding in clipped output.
+- Automatic style derivation can now map some identities to different
+  backgrounds because `AvatarBackground::ALL` contains more variants. Services
+  that need old automatic output should keep their existing namespace
+  `style_version` until they intentionally migrate.
+- Documentation now avoids `cargo test --all-features` guidance because
+  `blake3` and `xxh3` are intentionally mutually exclusive crate-wide identity
+  hash modes.
+- README fuzz wording now reflects default WebP coverage and feature-gated
+  encoder paths instead of describing PNG as always available.
+
+## Compatibility Notes
+
+- Explicit `AvatarOptions` and `AvatarStyleOptions` selections remain
+  deterministic for the selected kind, background, dimensions, seed, namespace,
+  crate identity hash mode, and identity.
+- The new background variants are public API and therefore affect automatic
+  background distribution.
+- No new avatar families were added in this release.

docs/release-notes/RELEASE_NOTES_0.13.0.md

@@ -8,7 +8,7 @@ publish = false
 cargo-fuzz = true
 
 [dependencies]
-hashavatar = { path = "..", version = "0.12.0", features = ["fuzzing"] }
+hashavatar = { path = "..", version = "0.13.0", features = ["fuzzing"] }
 libfuzzer-sys = "0.4"
 roxmltree = "0.21.1"