optimizations

docs/nova-cards-v3-audit-checklist.md

@@ -0,0 +1,219 @@
+# Nova Cards v3 Audit Checklist
+
+Audit date: 2026-03-28
+
+Source of truth reviewed:
+- `.vscode/agents/skinbase-nova-cards-system_v3.md`
+- Nova Cards controllers, services, models, routes, React Studio UI, migrations, and feature tests
+
+Validation status:
+- Verified with `php artisan test tests/Feature/NovaCards`
+- Result: 72 passing tests, 489 assertions
+
+Follow-up roadmap:
+- `docs/nova-cards-v3-priority-roadmap.md`
+
+Status legend:
+- `[x]` Implemented end to end or clearly present
+- `[-]` Partially implemented or scaffolded
+- `[ ]` No clear implementation found during audit
+
+Important note:
+- The v3 agent file is a roadmap/spec, not a strict shipping checklist. Several sections describe target-state product direction rather than features that are already expected to exist in full.
+
+## 1. v3 schema versioning and normalization
+
+- [x] `schema_version` is stored and normalized for v3 cards
+- [x] New projects normalize to v3 shape
+- [x] Legacy v1/v2 projects are detected and upgraded
+- [x] Save flow rewrites cards into the newer project structure
+- [x] Compatibility behavior is covered by feature tests
+- [-] Explicit admin rerender/backfill tooling for migrated cards was not found
+
+Notes:
+- Implemented via migration, `NovaCardProjectNormalizer`, and v3 tests.
+
+## 2. Advanced editor architecture improvements
+
+- [x] Structured project JSON exists with major v3 sections like `canvas`, `background`, `text_blocks`, `frame`, `effects`, `export_preferences`, and `source_context`
+- [x] Multiple text blocks are supported
+- [x] Additional body and caption blocks can be added and edited
+- [x] Layout presets, alignment, position, padding, max width, typography, frame, effects, background modes, overlays, focal position, and packs are exposed in the Studio UI
+- [x] Background upload works through the draft API
+- [x] Mobile step-based flow exists for Studio
+- [x] Version history and version restore exist
+- [x] Block reordering UI now exists for text blocks
+- [x] Compare versions UI now exists at a useful summary level
+- [x] Dedicated quick mode versus advanced mode switch now exists
+- [-] The editor is structured and block-based, but not a full layer tool
+- [-] Visibility toggles exist for text blocks through the `enabled` flag, but not as a broader layer system
+- [ ] Snap guides were not found
+- [ ] Safe-zone editing helpers beyond stored config were not found
+- [ ] Lock/unlock controls for editable elements were not found
+
+Notes:
+- This area is materially beyond MVP, and the recent Studio usability pass closed the highest-value gaps around quick/full mode, block reorder, and version compare. It still does not match the full “advanced studio” vision in the spec.
+
+## 3. Creator presets
+
+- [x] Creator presets table and model exist
+- [x] Preset CRUD API exists
+- [x] Presets can be captured from an existing card
+- [x] Presets can be applied back to a card as project patches
+- [x] Default preset behavior exists
+- [x] Studio UI exposes preset browsing, apply, capture, and delete actions
+- [x] Preset logic is covered by tests
+
+## 4. Discovery and ranking surfaces
+
+- [x] Public cards index includes featured, trending, latest, and rising content
+- [x] Rising service exists and is tested
+- [x] Related cards service exists and is tested
+- [x] Remixed cards page exists
+- [x] Lineage page exists
+- [x] Challenge listing and challenge detail pages exist
+- [x] Template packs page exists
+- [x] Creator page exists
+- [x] Dedicated style-family feed now exists
+- [x] Dedicated palette-family feed now exists
+- [x] Best-remixes discovery surface now exists
+- [x] Dedicated mood feed now exists through config-backed tag mappings
+- [x] Dedicated editorial landing page now exists
+- [x] Dedicated seasonal landing page now exists
+- [-] Discovery includes several meaningful surfaces, but not the full matrix described by the spec
+- [ ] Remix-tree browsing surface beyond lineage was not found
+
+Notes:
+- Discovery is solid for core launch surfaces, but it is not yet the full “discovery intelligence” product outlined in the spec.
+
+## 5. Creator identity and profile integration
+
+- [x] Creator-specific public page exists for cards by user
+- [x] Creator page now exposes public summary stats and creator highlight cards
+- [x] Creator page now exposes featured works and featured collections
+- [x] Top categories and top tags are surfaced on creator pages
+- [x] Studio analytics page exists for a creator’s own card with views, likes, saves, remixes, shares, downloads, and related counters
+- [x] Style family and palette family are stored on cards
+- [-] Creator identity exists at the card/creator listing level, but richer creator-card identity features are not complete
+- [x] Featured card rail now exists on creator pages as featured works
+- [x] Featured collection rail now exists on creator pages
+- [x] Dedicated Nova Cards creator portfolio page now exists
+- [x] Creator pages now surface signature themes, challenge history, most remixed works, most liked works, remix branch activity, a remix graph summary, creator preference signals, and a recent creator timeline
+- [-] Deeper creator identity modules are still incomplete beyond the current public portfolio summary; stronger interactive remix graphing and richer persistent preference identity are still missing
+- [x] Creator spotlight eligibility/featured creators now exist for Nova Cards editorial surfacing
+
+## 6. Social, remix, collection, challenge, and editorial support
+
+- [x] Like, favorite, save, remix, duplicate, and challenge submission flows exist
+- [x] Remix lineage is preserved and visible
+- [x] Public collection detail page exists
+- [x] Official collections and admin management for Nova Cards exist
+- [x] Challenge admin management exists
+- [x] Challenge entry visibility rules are covered by tests
+- [x] Best-remixes public surface exists
+- [x] Nova Cards editorial landing surfaces exist
+- [x] Seasonal or themed card hubs specific to Nova Cards exist
+- [x] Featured creators workflow specific to Nova Cards now exists
+- [-] Editorial and community support is present, but the richer “ecosystem” layer remains incomplete
+
+## 7. AI assistance hooks and optional UI
+
+- [x] AI assist endpoint exists
+- [x] AI assist service exists
+- [x] Studio UI exposes AI suggestion requests
+- [x] Suggestions include tags, mood, layout suggestions, and readability fixes
+- [x] Suggestions are optional and creator-controlled
+- [-] The AI assist layer appears primarily rule-based/fallback-driven rather than a deep external AI composition system
+- [ ] More advanced assist actions from the spec, such as “convert to story format” or “create wallpaper version” as explicit AI actions, were not found
+
+## 8. Export system improvements
+
+- [x] Export request API exists
+- [x] Export status polling exists
+- [x] Export queue job exists
+- [x] Multiple export formats exist: preview, hires, square, story, wallpaper, and OG
+- [x] Export permissions are enforced via `allow_export`
+- [x] Studio UI exposes export requests
+- [-] Core export foundation is implemented, but richer policy/output features remain open
+- [ ] Watermark policy controls were not found
+- [ ] Advanced export preset management beyond format choice was not found
+
+## 9. Trust, moderation, and rights
+
+- [x] Card moderation status exists on the model
+- [x] Reporting supports cards, comments, challenges, and challenge entries
+- [x] Moderation queue/report summary integration exists
+- [x] Ownership and remix-related rights flags exist, including `allow_remix`, `allow_background_reuse`, and `allow_export`
+- [x] Background upload validation is enforced
+- [x] API throttles and write-protection middleware are wired on key Nova Cards endpoints
+- [-] Trust/moderation foundations are real, but the full anti-abuse roadmap is not complete
+- [x] Publish-time duplicate-content heuristic flagging now exists for Nova Cards
+- [x] Publish-time self-remix-loop heuristic flagging now exists for Nova Cards
+- [x] Staff admin/reporting surfaces now expose persisted Nova Card publish heuristic reasons
+- [x] Staff moderation overrides now persist actor/source metadata on Nova Cards
+- [x] Staff overrides now persist moderation disposition codes like cleared/escalated/rejected
+- [x] Staff moderation UI now allows selecting custom review dispositions per action
+- [ ] Challenge branch freeze / remix-branch intervention tooling was not found
+
+## 10. Backward-compatible migration strategy and rerender tooling
+
+- [x] Migration for v3 schema additions exists
+- [x] Legacy project JSON is normalized at load/use time
+- [x] Older cards remain editable through normalization paths
+- [x] Tests verify upgrade behavior
+- [-] Compatibility is present, but operational migration tooling is incomplete
+- [ ] Admin rerender tool for migrated cards was not found
+- [ ] Backfill job for schema versions was not found
+
+## 11. Acceptance criteria summary
+
+### Studio/editor
+- [x] Structured multi-block project model exists
+- [x] Creator presets exist and can be reused
+- [x] Versioned schema and normalization work
+- [x] Exports are functional
+- [x] Mobile Studio flow is usable
+- [x] Studio usability pass now covers quick/full mode, text-block reorder, and version compare summaries
+- [-] Full advanced editor capability set from the spec is not complete
+
+### Social/community
+- [x] Remix chains are preserved and visible
+- [x] Collections are integrated into card flows
+- [x] Challenge flows exist
+- [-] Stronger creator identity exists only in a limited form
+
+### Discovery
+- [x] Rising and related content work
+- [x] Creator, collection, challenge, and template public surfaces exist
+- [-] Broader discovery matrix and editorial surfacing are incomplete
+
+### AI assistance
+- [x] Optional assistive suggestions exist
+- [x] Creator remains in control
+- [-] AI assistance is limited compared with the long-term vision
+
+### Moderation/trust
+- [x] Reporting and moderation hooks are in place
+- [x] Attribution and basic rights controls are preserved
+- [-] Anti-abuse depth from the spec is incomplete
+
+### Technical
+- [x] v1 and v2 content remain compatible through normalization
+- [x] Schema migration is safe and test-covered
+- [x] Render/export pipeline supports v3 features currently in use
+- [-] Future-ready operational tooling is only partially present
+
+## 12. Bottom line
+
+- [x] Nova Cards v3 foundation is implemented
+- [x] The core shipping slice is real: schema versioning, Studio improvements, presets, AI assist, exports, rising, related cards, remix lineage, challenge integration, moderation/reporting, and public browsing
+- [-] Several roadmap areas are only partially implemented
+- [ ] The full spec in `.vscode/agents/skinbase-nova-cards-system_v3.md` is not fully implemented end to end
+
+## 13. Highest-value missing areas
+
+- [ ] Advanced editor depth beyond the recent usability pass: lock/unlock, snap guides, safe-zone helpers, and broader layer controls
+- [-] Rich creator identity surfaces: featured works, featured collections, and featured creators now exist, but portfolio depth and creator-history surfaces are still missing
+- [x] Broader discovery surfaces now include style, palette, mood, best-remix, editorial, and seasonal pages
+- [-] Stronger editorial tooling exists for cards, collections, challenges, and creators, but broader packaging and workflow depth are still limited
+- [ ] Operational rerender/backfill tooling for long-term schema evolution