feat: add official Flutter SDK (usenavii) with SVG parity to @usenavii/core - #5

Summary

Adds an official Flutter / Dart SDK for Navii as packages/flutter (pub package name: usenavii).

This is a faithful Dart port of @usenavii/core plus thin widgets mirroring @usenavii/react-native — not a hosted-API wrapper and not a JS/WASM bridge. Same seed + same options → byte-identical SVG as the TypeScript engine.

Architecture

• Engine: packages/flutter/lib/src/core/ (port of packages/core)
• Widgets: Navii / NaviiGroup via flutter_svg (SvgPicture.string)
• Versioning: independent SemVer on pub.dev (out of npm lockstep)
• Current version: 0.1.0-dev.1 (parity target: @usenavii/core 0.9.x)

Features

Engine API (re-exported from package:usenavii/usenavii.dart)

• createAvatar, selectAvatar, renderAvatar / renderAvatarInner
• renderGroup / renderGroupTiles
• build(BuildSpec) for non-seeded composition
• Packs: builtInPacks, packRegistry, resolvePacks
• Primitives: sha256Hex, cyrb53, createRng, seed / seedFromEmail / normalizeEmail
• random() helper

Flutter widgets

• Navii — required seed; props map to engine options (styleHint → engine style); Semantics via alt ?? title
• NaviiGroup — overlapping stack with +N counter; empty seeds → zero-size widget (RN returns null)
• animated accepted but painted statically in v1 (same as React Native — CSS keyframes do not run in flutter_svg)

Example + docs

• packages/flutter/example/ — seed field, size, mood, NaviiGroup (web + macOS)
• Root README Packages table + Flutter quick start
• Package README linked to https://navii.dev and GitHub

CI / publish

• .github/workflows/flutter.yml — flutter pub get / analyze / test / dart pub publish --dry-run on packages/flutter/**
• Flutter explicitly excluded from .github/workflows/release.yml npm matrix (five JS packages only)
• LICENSE, package CHANGELOG.md, .pubignore, root CHANGELOG version-mapping table
• CONTRIBUTING.md documents the Flutter lockstep exception

Parity / testing

Golden fixtures exported from @usenavii/core assert string-identical SVG for:

• Primitives (sha256, PRNG, seed helpers)
• selectAvatar specs
• createAvatar / renderAvatar
• renderGroup / renderGroupTiles + dimensions
• build(BuildSpec)
• Packs registry + pack-affected SVG output
• Widget tests: determinism, layout size, empty group, README snippet smoke tests

cd packages/flutter
flutter pub get
flutter analyze --no-fatal-infos
flutter test

cd example && flutter run -d chrome   # or -d macos
dart pub publish --dry-run             # from packages/flutter (clean tree)

Non-goals (intentional)

• No package.json in packages/flutter (keeps pnpm / npm release CI clean)
• Not added to the npm publish matrix
• Animation remains static in the Flutter widget for v1 (engine still emits CSS when animated: true for string parity)

Test plan

• flutter test green under packages/flutter
• flutter analyze --no-fatal-infos green
• dart pub publish --dry-run succeeds on a clean tree
• Example runs: cd packages/flutter/example && flutter run -d chrome
• Confirm .github/workflows/release.yml still publishes only core / react / react-native / vue / svelte
• Spot-check: same seed in Node @usenavii/core and Dart createAvatar → identical SVG
• Root README lists usenavii / Flutter package

Notes

• PRNG draw order matches core (new variants append only).
• Prefer stable ids as seeds (user.id → UUID → email), never Date.now() or display names.