Add Banishment quest experience and ScreenAuditKit validation workflow#3
Merged
Conversation
Chain and schedule VoiceOver announcements for banishment encounters: add pendingAnnouncementTask, schedule/cancel helpers, and new announceBanishedThenEncounterArrival()/announceEnterDarkThenEncounterArrival() so follow-up encounter lines play after feedback. Cancel pending announcements when the view disappears, on timeouts, and when VO is disabled mid-game. Revamp trap overlay: split into portrait/card/decoy subviews, add animated entrance, explicit in-trap back control (toolbar hidden during traps), and updated accessibility labels/hints to support Lights Off mode. Update Localizable.xcstrings with new/updated keys for the encounter announcements and hints, and record workspace UI state changes.
Refactor the Banishment quest to use per-encounter (Enchanter-style) segment timers instead of a single scored duration, adding scoredSessionStart and segmentDeadlineStart and new segment length constants. Replace delayed announcement scheduling and the decoy/wrong-decoy button flow with immediate, cancellable announcements and a skippable escape (performBanishEscape) that advances runs immediately. Add a commit flag to avoid race conditions when completing a scored run and skip abandoning a session during commit. Start GameSession with an explicit start date and restart segment timers on phase changes; implement a single scored countdown task that reads the current segment deadline. Add more diagnostic logging (startup timestamp tags) including an updated push log in iOSAppRouter. Update UI to remove the decoy button and related handlers. Refresh Localizable.xcstrings to match the voiceover text and new strings. Also add memlog notes and minor ancillary changes.
Introduce The Banishment illustrated quest: add asset catalog images and Contents.json entries, new iOSBanishmentArt keys, and integrate banishment scenes into the screenshot harness and quest view model. Update AGENTS.md and cursor rules with a mandatory illustrated-assets authorship policy (LLM/human only; no procedural script-generated shipping art) and clarify allowed mechanical pipeline scripts. Add design/memlog files, QA/import/validation utilities and fastlane screenshots (and adjust .gitignore). These changes prepare the app and pipeline to consume vetted banishment PNGs and enforce traceable authorship.
Revamps the Banishment quest UI: replaces the old prologue column with a centered layout, adds a large gesture illustration (raster + vector fallback), and improves accessibility identifiers and hints. Removes ward ring usage from runtime sprite heuristics and moves Z/ward compositing out of the live trap overlay; introduces BanishmentTrapPlayfieldLayout to compute cluster/panel sizes dynamically. Adds localized strings for prologue instructions, swipe explanation and trap kickers, and updates the prologue button label/hint. Styles and theming updates for iOSGameResultView (dark ambient background, background asset selection, visual refinements) and minor UIKit import. Also updates the gesture asset and many documentation screenshots/user state blobs.
Introduce QuestPaint UI primitives and apply them across several screens: new QuestPaintAmbientBackdrop, QuestPaintReadableScrim, text roles/modifier, and layout metrics (iOSQuestPaintChrome.swift). Update iOSBanishmentQuestView, iOSVORequiredView and iOSGameResultView to use the new backdrop, scrim, readable text styles, tweak colors/shadows, and prefer dark color scheme and toolbar material. Clarify iOSBanishmentArt comment to note the PNG uses true alpha and add a utility script (utility/transparent_edge_dark_matte.py) to convert edge-connected dark matte to transparency; update the banishment gesture image. Update localized strings (rename “The Ward” to “Goblin” and adjust related copy). Remove outdated fastlane screenshots and include an updated workspace user state. The changes improve visual composition, legibility over illustrated backdrops, and provide tooling to prepare image assets for correct alpha handling.
Introduce reusable quest UI pieces and migrate views to the new "quest paint" readable styling. Adds QuestStandardPrimaryButton/QuestStandardSecondaryButton (QuestStandardActions) and QuestVoiceOverGestureSpellPlate for VO gesture lessons; includes small accessibility modifiers for optional identifiers/hints. Update multiple views to use questPaintReadableText roles instead of direct font calls, switch hub/first-run/basics/dungeon/enchanter backgrounds to QuestPaintAmbientBackdrop + QuestPaintReadableScrim, and adjust layout/padding using QuestPaintContentMetrics (reading column max & horizontal padding). Also: ensure backdrop images are clipped to avoid layout expansion, refine lights-off backgrounds to retain art traces, wire spell plate presets into prologues/results, add localized string changes, and include documentation/memlog and screenshot updates.
Introduce a new local Swift package, ScreenAuditKit, with library and CLI targets, tests, README, and .gitignore to support deterministic screenshot validation (includes Package.swift, sources, tests, and a screenaudit executable). Add a ScreenAuditContracts.json for UITests and wire the package into the Xcode workspace; include a helper script (utility/validate_screen_audit.sh). Also apply broad localization/content updates: simplify and standardize VoiceOver copy (renaming "Moonstone alignment lane" to "Glyph stream" and tweaking timer and tutorial strings), adjust status labels and timer announcements, and clarify timer semantics in iOSDungeonDescentView.swift comments. Add Fastlane screenshot copies and memlog/design notes related to the new workstream.
Introduce deterministic PNG baseline comparison to ScreenAuditKit: adds ScreenAuditBaselineComparator, ScreenAuditBaselineDiff, region and baseline expectation models, CLI --baselines support, a new rule (baselineDifferenceExceeded), and tests (ScreenAuditBaselineTests). Integrates baseline comparison into the validator and report pipeline, decoding new contract fields with backward-compatible defaults. Fix visual/screenshot rendering in iOS views by forcing raster assets to .renderingMode(.original) and removing compositingGroup where it caused fringe/checkerboard artifacts. Also update many raster assets and documentation/fastlane screenshots to reflect the visual changes.
Introduce visual artifact detection and review tooling: add transparency/opaque-border, rendered-matte, and checkerboard inspectors; add a PNG overlay renderer and integrate overlay generation into the validator (overlay paths returned on validation). Extend contracts with asset expectations (fallbackArt) and add a rule evaluator to emit low-confidence fallback-art findings. Update ScreenAuditRegion to include critical regions, adjust decoding/initializers, and add related tests and fixtures to cover the new checks and overlay output.
Remove the Resonance mockup scene and its artifacts (scene enum/case, root view branch, UI tests, ScreenAuditContracts entry, route catalog row, and screenshot assets/fastlane entries). Adjust UI layouts and spacing across several views: reduce image/frame sizes, update paddings and column max widths in Banishment, Dungeon and Result screens, shorten VStacks and font/icon sizes, and trim the Dungeon prologue practice list and related visuals. Rename/update QuestPaintContentMetrics call sites to use horizontalPadding/contentMaxWidth. Update Localizable.xcstrings with condensed copy and refresh screenshots in docs/fastlane.
Introduce QuestPaintScreen: a reusable illustrated scaffold (ambient backdrop + readable scrim + centered scroll column) and add QuestLayoutRole.result with adjusted content metrics. Hide decorative backdrop views from the accessibility tree to avoid image filenames being spoken and make Enchanter/Basckdrop views accessibilityHidden. Refactor iOSGameResultView and iOSVORequiredView to use QuestPaintScreen. Add Lights Off (BanishmentPhase.darkTower) UI and accessibility: proof banner, localized strings (nav/title/hints), and prologue/instruction text reorganizations. Update Crystal Resonance scroll proxy to expose accessibilityValue and a lights-off hint so VoiceOver names the current glyph/alignment. Add ScreenAudit asset provenance JSON and wire provenance IDs into screenshot contracts. Misc: localization updates, small docs/tests and ScreenAuditKit tweaks related to these changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds the Banishment quest experience, introduces a reusable local Swift Package called ScreenAuditKit, and establishes a broader design consistency/audit workflow for screenshots, visual assets, and quest UI review.
The main goal is to move RA11y toward a repeatable design validation approach: quest screens should not only build and run, they should be auditable through deterministic screenshot contracts, provenance metadata, visual heuristics, and CI/Fastlane-friendly reports.
What Changed
Banishment Quest
Added the Banishment quest flow and supporting SwiftUI views.
Added Banishment visual assets to the iOS asset catalog.
Added Banishment screenshot routes and updated screenshot automation coverage.
Added refreshed generated screenshots for supported devices.
Added supporting design docs, prompt sheets, asset pipeline notes, and QA checklists under memlog/.
Shared Quest UI Design System
Added reusable quest chrome components:
iOSQuestPaintChrome
iOSQuestStandardActions
iOSQuestVoiceOverSpellPlate
Updated existing quest screens to better align around shared visual language, readable text treatment, action placement, and consistent “painted quest” presentation.
Refined hub, result, onboarding, VoiceOver-required, Dungeon, Resonance, and Enchanter surfaces to reduce one-off styling and improve consistency.
ScreenAuditKit
Added ScreenAuditKit as a separate local SPM package in the workspace.
It includes:
ScreenAuditKit library product
screenaudit CLI executable
JSON contract decoding and validation
screenshot evidence extraction
deterministic rule evaluation
Markdown and JSON reports
baseline image comparison
ignored/protected/critical region support
rendered matte risk detection
checkerboard-like artifact detection
suspicious opaque border detection
overlay PNG generation with sidecar Markdown/JSON explanations
asset provenance support for explainable design warnings
This package is intentionally generic and local-first. It is designed so we can keep iterating inside this repo, then later move it toward a standalone reusable SPM module.
RA11y Screen Audit Contracts
Added ScreenAuditContracts.json for screenshot validation.
Added ScreenAuditAssetProvenance.json so review warnings explain source, status, quality, known risks, and supporting evidence.
Added utility/validate_screen_audit.sh.
Added Fastlane integration for screen audit validation.
Updated ADR/workstream docs describing the long-term plan.
The current Banishment warnings are intentionally advisory. They document provenance risk rather than blocking CI:
source: mockupCrop
status: temporary
quality: bootstrap
known risks: cropped screenshot source, not confirmed final master asset, needs authored export verification
Why This Approach
This PR separates design validation from app implementation.
Instead of hard-coding RA11y-specific checks into the app or relying only on manual screenshot review, we now have a portable audit package that can be dropped into the app or pipeline. Contracts describe what matters, reports explain what was checked, and provenance makes visual warnings actionable.
The direction is:
App code owns the product experience.
Contracts own expected screenshot and design review behavior.
Provenance files explain asset quality and source risk.
ScreenAuditKit owns reusable validation mechanics.
Fastlane/CI can run the same checks without knowing RA11y internals.
This gives us a path toward stronger design consistency without turning subjective taste into brittle CI failures.
Validation
Ran:
swift test --package-path ScreenAuditKit
bash utility/validate_screen_audit.sh
Results:
ScreenAuditKit tests pass.
Screen audit validates all configured screenshot folders.
Banishment provenance warnings are reported as non-blocking warnings.
Overlay PNG/Markdown/JSON artifacts are generated under build_results/screen-audit/.
Follow-Up Work
Add a top-level screen audit index report.
Tighten semantic regions so overlays highlight specific UI/art zones instead of broad review regions.
Expand provenance coverage to all high-value quest assets.
Archive ScreenAuditKit reports as CI/Fastlane artifacts.
Continue extracting repeated quest presentation into shared components.
Eventually move ScreenAuditKit out as a standalone SPM package when the API stabilizes.